asanabrial/issue-flow

Issue Flow — 分析师 / 开发者共享 Issue 跟踪器

激活契约

用于 issue-flow analyst [conditions]、issue-flow dev [domain-rules] [issue-number]、分析师或开发者工作、认领以及工作流状态转换。 分析师条件和开发者领域是可选的：有界目标即作用域；否则分析师审计仓库，开发者实现所选 Issue。 首先读取仓库说明，并且只加载由操作员配置选择的跟踪器绑定，然后再进行跟踪器工作。 加载领域组合以获取交接、优先级或路由规则；运行时说明以获取调用、委托或团队机制；以及安全事件以获取竞争、重新认领、交接或失败理由。

硬性规则

• Issue Flow 拥有角色、状态、认领和转换权；路由领域拥有价值、优先级、证据和完成标准。任何一方不得自行制定另一方的策略。
• 分析师（包括对抗性审查者）对仓库和除以下配置的跟踪器操作之外的所有外部系统均为只读：不创建分支/工作树/提交/PR，不运行迁移、同步、数据库写入或交付操作。最多提交一个附带证据的 Issue。审查必须使用未写入更改的上下文。
• 生成一个 <runtime>-<session-prefix> 运行 ID，并在每次写入时重复使用。在 analyst:<runtime>/dev:<runtime> 标签中保留有界运行时归属，在文本中保留无界运行 ID 归属；分析师的标签持久存在，而开发者的标签在发布时移除，但在交付时保留。
• 在查询队列之前，恢复本轮运行中持有的 Issue。使用所选绑定基于时间线裁决的认领；最早的有效认领获胜。在第一次仓库写入之前、每次心跳以及每次昂贵或不可逆的边界执行 verify_claim；不可读的控制面禁止任何写入。
• 始终保持 analysis、ready、in-progress、review、blocked 或 done 之一。绑定的工作流状态是权威的；每个配置的投影都会被更新和读回，并且 done 必须在跟踪器关闭前显式声明。
• 所选绑定必须映射 ensure_states、create、list_state、claim、reclaim、verify_claim、heartbeat、transition、comment、last_activity、label、unassign、publish_version 和 close。执行可运行的可逆操作，而不是重新构造它们；绑定必须声明不支持的能力并在失败时关闭。
• Issue 的验收标准、路由领域规则和仓库规则定义了完成。绝不能自行添加遗漏的门控条件或静默地重新解释 Issue。

决策门控

情况	操作
分析师有条件或有界的 diff/PR/Issue	仅在适用的仓库和领域规则下分析该范围。
分析师没有条件或领域	使用领域组合中的自主 general 契约；仅提交最强的去重发现或什么都不提交。
存在领域路由记录	分析师加载左侧规则手册；开发者加载右侧规则手册。当缺少实现路由时，需显式声明的状态。
运行时机制或独立上下文获取方式不同	遵循运行时说明；运行时限制改变的是机制，而非不变量。
认领、重新认领或交接安全性需要理由	遵循活动绑定和安全事件，不要在此复制事件叙述。
必须选择状态	无效规约 -> analysis；可实现且未分配 -> ready；已认领的构建 -> in-progress；已构建/发布 -> review；未构建的外部等待 -> blocked（附带条件和解除者）；合并并已验证 -> done。

执行步骤

在某个不熟悉的项目中，任一角色进行第一次跟踪器写入之前，运行所选绑定的 ensure_states；然后使用该绑定的可执行操作和读回，而不是重新构造它们。 加载领域组合以获取路由、规模验证、队列分区或自主回退；运行时说明以获取调用、只读执行、独立上下文获取或运行时限制；安全事件仅当需要认领、重新认领、交接或失败理由时；以及仓库交付仅当仓库规则未完全定义隔离或集成时。

分析师

1. 保持仓库和非跟踪器外部系统为只读。按最旧优先取走 analysis 状态下的 Issue，然后检查 blocked：将已解除条件的 Issue 移动到 ready 并附带证据，记录仍然成立的条件日期，并指出某人有待处理决定的时间。
2. 仅在左侧领域规则手册定义的有限范围内进行分析。没有条件或领域时，使用自主 general 契约；验证证据和重复项，然后最多保留一个最强有力的可辩护发现，或报告没有发现幸存下来。
3. 验证队列中及新发现的字段、路由、规模和正文契约。对于队列中的工作，使用 comment 添加缺失的交接材料，并仅转换同一完整项；绝不创建替代品。对于新发现，填写分析师 Issue 模板并使用每个标记以及 analyst:<runtime> 和运行 ID 归属 create 它。使用 ready，或使用确切缺失的条件和解除者使用 blocked；然后停止，不实现也不分配它。

分析师的产出

开发者可以接手而无需重新进行分析的 Issue。如果开发者必须重新推导你的推理，那么分析就没有价值。

## 面向普通人的描述

> [!NOTE]
> 一两句话，通俗语言，无术语，无文件路径，无指标——此 Issue 关于什么，针对那些永远不会读到这一行以下内容的人。以操作员配置为此安装指定的语言编写（见本文件末尾的表格）。标题本身是上面固定的字面标题——始终使用英文，始终是那个确切的短语，绝不根据 Issue 重新措辞。`> [!NOTE]` 是 GitHub 的原生提醒语法——它会渲染为一个带边框的彩色标注框，这正是关键所在：这对于一个充满技术性散文的 Issue 来说，必须在视觉上无法被忽略。

这是 Issue 上第一项内容，位于 `## Problem` 之前。

## 问题

出了什么问题或缺少了什么，以及你是如何知道的。提供证据，而非断言：文件:行引用、测量数据、日志、复现步骤。

## 重要性

若不处理将产生的影响。如果你无法陈述，请直言——一个记录为“低影响，为完整性而提交”是诚实的，并允许开发者降低优先级。

## 建议方案

设计方案。你考虑过的替代方案以及拒绝它们的原因。如果你不确信，请指出哪个部分不确定，以及什么可以解决它。

## 验收标准

可检查的陈述。“更快”不是标准；“通过 X 测量的 p95 低于 200 毫秒”才是。包括不能改变的内容（不变量、字节相同的输出）。

## 范围外

开发者应明确不做的事情。这比上面部分中的任何散文都更可靠地防止范围蔓延。

## 证据

运行的命令、读取的文件、测量的数字。足够让审查者无需重复分析即可重新检查。

开发者

1. 在查询队列之前，在其记录的状态下恢复本轮运行中持有的 Issue。否则，按最旧优先取走未分配的 review 状态 Issue，然后在认领已发布的工作之前重新检查交付障碍。
2. 对于 ready 状态，根据稳定领域和声明的规模对有效候选者进行分区，仅在每个分区内排名，并选择最旧的分区头；选定的领域将选择限制为其最高排名的最旧项。仅当没有候选者具有有效的规模契约时，才使用最旧优先。
3. 使用运行 ID 和视界进行 claim，然后裁决服务器时间戳时间线；最早的有效认领获胜，失败者发表评论、释放并重新选择。除非代码更改需要 in-progress 以及新的发布/审查/CI 周期，否则将已认领的审查工作保留在 review 状态；对于已准备好的工作，转换到 in-progress 一次，添加 dev:<runtime> 且没有第二次认领事件。
4. 在规划之前加载路由的右侧实现规则手册；如果不存在，则声明没有适用的规则，并根据书面的验收标准进行构建。遵循仓库规则，对缺失的隔离/集成策略使用仓库交付回退，在第一次分支/工作树/文件写入之前立即验证认领，并在隔离的签出中实现。
5. 在发布前续约，发布或重用共享的审查目标，然后转换到 review。仅当审查委托授权此运行时才获取独立上下文；否则请求一个单独开始的审查。需要其裁决以及在同一确切基头/头部的绿色 CI；每次推送都会使两者无效。将受阻的交付留在 review，恢复因失败尝试而更改的本地状态，记录精确的障碍，并取消分配而不是绕过它；冲突的仓库规则需要单独创建一个 Issue。
6. 在每个不可逆的边界处续约；仅在经过审查、CI 通过且当前头/基标识匹配时才合并。对于合并提交路线，要求交付的 SHA 的确切父级是经过审查的基和头；其他配置的策略需要其绑定声明的等效拓扑和任何交付 SHA 门控。对于每个更改的版本，发布并远程验证其不可变的注释标签和所需的 Release；再次续约，转换到 done，使用运行 ID 记录审查/CI/测试/测量/PR/交付 SHA/发布信息，然后关闭。交接时，保留所有证据：错误的规约转到 analysis，未构建的外部等待转到 blocked，已构建但无法交付的工作转到 review，有用的部分诊断转到 ready。

详细审查门控保留至最终退役部分

6. 让未编写更改的上下文审查已发布的更改，然后要求最新的 PR 头部通过 CI。 在审查前捕获头部和基 SHA，并要求裁决工件明确命名两者；浮动式的“已批准”不是任何特定修订版或差异的证据。在配置授权的情况下，自行获取该上下文——一个子代理或队友；否则将 PR 交给一个单独启动的分析师运行，并在 Issue 上表示你正在等待。配置决定的是谁启动审查，而从不决定是否运行。每次推送都会使先前的裁决结果和 CI 结果失效：重新审查更改的表面并再次等待所需检查。

   如果审查、CI 或交付受阻，请在此停止并将其留在 review 中。已构建并发布但无法交付的工作——审查者请求更改、检查失败、无法由不同身份提供所需的原生批准、权限缺失、两个项目规则相互矛盾——是已完成但待交付的工作，这正是 review 的含义。不要将其移动到 done：该状态表示已交付。也不要绕过障碍；你为了交付而绕过的一条规则，就失去了意义。

   精确地评论障碍——是什么拒绝了它，那个东西期望什么，项目要求什么替代方案——然后取消分配，以便其他参与者可以完成交付。恢复你尝试更改的任何本地状态。

   由两个相互矛盾的项目规则导致的障碍，值得拥有自己的 Issue。 它会影响到下一个任务，以及之后的每一个，每次运行都会从零开始重新诊断。提交一个发现将重复出现的成本转化为某人可以一次性做出的决定。

7. 仅在其所需的 CI 为绿色后才合并经过审查的 PR 头部，发布任何版本标签，然后 close。 在合并前立即续约认领，要求 审查过的头/基 == CI 头/基 == 当前头/基，将合并绑定到审查过的头部 SHA，如果任何一方移动则拒绝。使用已配置的合并策略；合并提交 保留分支边界和 PR 祖先，而压缩提交和变基会故意丢弃这些信息。在合并后检索交付的 SHA，并验证它恰好拥有审查过的基和审查过的头作为其父级；不要仅凭命令标志就声称拓扑不变性。仅当其配置的方法保证相同拓扑时，合并队列才适用。如果项目要求对确切交付的 SHA 进行 CI，请等待该合并后门控。

在仓库中工作——默认流程

仓库的规则永远优先。 在其他任何事情之前，读取其代理说明（AGENTS.md、CLAUDE.md 或等效文件）并遵循它们。以下是针对未做任何规定的仓库的回退方案，也是针对仅做了部分规定的仓库的最低标准——绝不是竞争标准。

较旧的回退方案——使用提交历史作为约定——无法覆盖这种情况，并且值得说明原因。Git 日志告诉你提交消息是如何编写的。它无法告诉你两个代理是否可以共享一个签出，或者一个分支在上一个小时后是否仍然有效。这些答案决定了并行工作是否会损坏自身，因此此技能提供了它们，而不是将其留给一个没有理由知道的领域。

1. 绝不在基树中工作。 对于开发者来说，默认分支是只读的：不能编辑，不能提交。在进行第一次更改之前进行检查，而不是假设：

git branch --show-current   # main / master -> 停止，先创建分支

如果你发现已经提交到了基分支且尚未推送，请将提交移动到分支并重置。如果你已经推送了，不要强制推送——还原并正确地重新操作。

对于

…

[翻译截断]