factory-mission

factory-mission

在工厂运行期间——请先阅读

当设置了 ADLC_RUN_ID 时，工作流引擎会在无人值守的情况下将此技能作为其 execute 步骤运行，随后进入完成门禁。请严格执行以下步骤：

1. 任务就是本次运行对应的问题。 从参数中的 --issue <ref> 获取；如果缺失或为空，则使用 ADLC_ISSUE_REF。两者都没有时，不要提问：将 {"conclusion":"blocked: factory run without an issue"} 写入 ADLC_STEP_OUTPUT 并返回。
2. 针对该问题端到端完成任务（下方的阶段 0–6）：撰写简述、测试（RED）、编码（GREEN）、收敛，然后在变更所属的代码库中创建或复用草稿代码 MR/PR。
3. 返回前，务必： 将 mr_url（你创建或复用的代码 MR/PR）和一行 conclusion 写入 ADLC_STEP_OUTPUT——写成一个所有值均为字符串的扁平 JSON 对象；保留文件中已有的任何键。引擎会在完成门禁中关联 mr_url。无论结果如何，都要执行此操作；如果没有 MR，只写入 conclusion。
4. 绝不提问或等待回答。 此步骤之后的完成门禁就是审批；在此处提问会导致步骤结束且没有任何实现成果。

---

此技能的作用

factory-mission 是软件工厂的执行框架编排器。它接收功能描述，将其整理为一份 任务简报（目标、约束、非目标、成功标准），生成按顺序排列的 步骤列表，并通过依次运行子 Agent 来执行这些步骤。

它实现了以下关键工厂平台功能：

1. 通用技能路由：解耦步骤分派。它会扫描已安装的技能，并将清单交给子 Agent（由模型选择适合该步骤的工具）。
2. 与跟踪器无关的集成（references/tracker-integration.md）：使用 --issue <ref> 调用时，会获取工单上下文，遵循自动化／分派标签（autonomous/supervised），并回写状态评论和迭代日志。
3. Agent 间评论总线（references/tracker-integration.md §Agent 间评论总线）：集成跟踪器后，每个步骤的终端输出（决策、发现、工件引用——绝不包含草稿）都会以结构化评论的形式发布到 PR/MR/工单中。下一步开始前会读取之前的标记。这种持久的 Agent 间记忆可以跨越会话边界、运行时切换和 Pod 崩溃而保留。草稿保留在本地磁盘上。
4. 自包含的工作者简报：任务简报会作为草稿保存在 .adlc/workflows/runs/<run_id>/brief.md 中。恢复运行和跨运行时工作者会从磁盘读取简报，不依赖会话上下文。
5. 工作树隔离：每次运行都会获得自己的 Git 工作树，绝不会触碰用户的主检出目录。退出时会清理工作树（若有未保存的工作，则保留）。
6. 基于租约的运行状态检测：状态文件包含带心跳和 TTL 的可续期租约。恢复时可以区分正在运行、已过期和已完成的任务。
7. 停滞检测：分派子 Agent 后，会在可配置的时间窗口（默认 20 分钟）检查可观察到的进度。若 Agent 卡住且通过了熔断器检查，系统会检测到并终止它。
8. 基于通道的分派（references/lanes.md）：步骤可以通过不同通道运行——inline（当前会话）、agent（相同 CLI 的新会话，用于分离编写者与检查者），或 cli:<runtime>（可选的跨厂商运行时）。对于无人值守阶段，默认使用 agent 通道。
9. 暂存板工具：子 Agent 共用具名且仅限当前运行使用的暂存板（.adlc/workflows/runs/<run_id>/scratchpads/<name>.txt），以便在发布前逐步整理笔记、草稿和审查意见。
10. 工作流记忆与自我改进：持久化的 JSONL 数据库（.adlc/workflows/memory.jsonl，在整个工作区内共享）会存储不同运行中的经验。factory-learn 会定期运行回顾，以精简和调整记忆权重。
11. 分层上下文参数：工作流和 Agent 通过 {{params.<key>}} 引用参数，解析顺序从最具体到最宽泛：agent < workflow < repository < project < default。
12. 测试与代码分离：在 autonomous 或 supervised 模式下，系统会将 implement 拆分为依次运行的 test（测试 Agent 在只读的 src/ 下编写失败测试）和 code（实现 Agent 在只读的 tests/ 下编写代码）——每个阶段结束时都必须通过机械式门禁（见阶段 5）：RED 门禁证明新测试套件在开始编写代码前会失败；GREEN 门禁证明测试套件在进入收敛阶段前会通过。

---

适用场景

• 在启用了工厂功能的团队中，从头到尾构建某项功能。
• 需要一个带熔断器、评分回归检查和可靠恢复机制（factory-mission --resume）的执行循环。
• 希望针对工单队列自主运行。

不适用场景：

• 非工厂类的独立项目（运行 adlc-cli workflow run <workflow.yml>——CLI 引擎，共享运行状态）。
• 简单的单行更改（直接处理）。

---

流程

factory-mission 按照共享执行器契约（references/executor.md）和与跟踪器无关的集成层（references/tracker-integration.md）执行。

阶段 0 至 4：设置与编译

1. 阅读本次运行的 mission.yml（.adlc/workflows/runs/<run_id>/mission.yml）。确定执行和监督方式。
2. 如果指定了 --issue <ref>（在工厂运行中，如果未指定，则使用 ADLC_ISSUE_REF）：
   • 查找凭据和 MCP/CLI 工具（references/tracker-integration.md）。
   • 获取议题内容，作为主要简报描述。
   • 阅读标签。如果派发模式为 interactive 或门控模式为 human-required，则停止执行（交还给交互会话）。
   • 本次运行的评论总线处于活动状态——步骤输出将作为标记评论发布到 PR/MR/议题中。
3. 如果没有议题（且不在工厂运行中）：从参数中读取规范描述。评论总线处于非活动状态——步骤之间仅通过本地文件通信。
4. 组织任务简报（目标、约束、非目标、成功标准）。简报为 draft——不会发布到评论总线。
5. 按照 agent < workflow < repository < project < default 的顺序解析分层上下文参数，并将冻结的值映射嵌入简报。
6. 根据路由分类（spec、change、quick）生成步骤列表。按照执行器约定，每个步骤声明 output_type（draft/decision/findings/artifact-ref）和 reads_from（标记或本地路径）。

**团队索引回退：**如果会话启动时未注入团队记录类索引，则直接从 docs/adlc/memory/ 读取绑定记录（双读顺序：先读 docs/adlc/memory，再回退到旧版 .adlc/memory），并用一行说明已采用回退方式。切勿因缺少注入而阻塞。

阶段 5：执行收敛循环

按顺序执行步骤。到达 implement / converge 时：

解耦测试/代码执行（强制 TDD）

在 autonomous 和 supervised 模式下，implement 步骤拆分为两个依次进行的子 Agent 派发，每次派发结束后都进行机械验证：

1. 测试 Agent（test 步骤）：
   • 指令：根据 spec.md 在 tests/ 中编写一套会失败的测试。
   • 强制要求：将 src/ 挂载为硬性只读；只有 tests/ 可写。
   • RED 门控（强制）：执行器运行测试套件，并断言至少有一个测试失败。若测试套件立即通过，意味着功能已存在或测试未断言任何内容——使用运行输出转到 SPEC_CORRECTION_NEEDED；绝不进入 code 步骤。在运行日志中记录失败数量。
2. 实现 Agent（code 步骤）：
   • 指令：在 src/ 中编写最少量的实现代码以通过测试。
   • 强制要求：将 tests/、spec.md 和 plan.md 挂载为硬性只读；只有 src/ 可写。
   • GREEN 门控（强制）：执行器再次运行测试套件；测试套件未通过时绝不能进入 converge。任何失败都会直接返回 code 步骤，并附上失败列表（此返回不会消耗收敛熔断器；只有失败的迭代才会消耗熔断器——使用 mission.yml 中的 code 步骤重试上限）。

仅当运行声明没有测试范围时，才允许跳过拆分：mission.yml 中设置 tdd: false、仅涉及文档/配置的步骤，或 interactive 模式（有人参与的结对工作会自行遵循规范，例如 superpowers 的 test-driven-development）。autonomous/supervised 模式下包含代码的步骤绝不跳过拆分。

收敛循环（Implement ↔ Converge）

1. 执行 implement 步骤（或先执行 test + code 步骤，并强制通过 RED→GREEN 门控）。
2. 执行 converge 步骤（独立评审模式；根据简报和非目标进行检查）。
3. 如果 converge 返回：
   • DONE（且质量高于 quality_threshold）：退出循环。
   • CONTINUE：递增 consecutive_tasks_appended。检查熔断器（默认值为 3）和分数回退计数器。重复执行。
   • SPEC_CORRECTION_NEEDED：停止并转到阶段 6。

阶段 6：完成与回写

1. 如果集成了跟踪器：读取 PR/MR/工单中的所有标记评论，以汇总审计轨迹（收敛决策、测试发现、实现产物引用、收敛历史）。
2. 关闭共享运行：执行最终的 adlc-cli workflow state advance <run_id> --step <last> --status completed（运行目录是持久归档；无需单独移动）。
3. 将每个实现任务的日志写入 iterations.md。
4. 如果集成了跟踪器：
   • 将完成摘要作为工单评论发布（标记：factory-mission:status=completed:run=<run_id>）。
   • 将生命周期标签从 executing 转换为 validation（如果已合并，则转为 done）。
   • 为已打开的 PR 添加 agent-authored 标记。
   • 在工厂运行中，将代码 MR/PR URL 作为 mr_url 写入 ADLC_STEP_OUTPUT（参见上文“在工厂运行中”）。
   • 将 PR 合并推迟至代码所有者批准后（未经批准绝不自动合并）。
5. 输出完整的审计摘要。