factory-runbook

factory-runbook

此技能的作用

factory-runbook 是软件工厂共用的运行机制，分为两部分：

1. 发布流程（如下）——每次工厂运行结束时都会执行的确定性「分支 → 提交 → 推送 → 草稿 MR/PR」流程。工厂编排器会在发布步骤调用此技能；也可直接用它发布一次运行产生的更改。
2. 运行契约（references/）——执行器循环、跟踪器集成、泳道、简报/提供方模板，以及运行上下文规则。工厂技能会按路径引用这些内容，而不是复制它们。

此技能绝不批准或合并。此步骤之后引擎的关卡就是审批。

**直接调用防护：**发布需要运行上下文——来自工厂运行的 ADLC_RUN_ID（通常还包括 ADLC_ISSUE_REF 和 ADLC_STEP_OUTPUT），或编排器显式提供的参数（编排器名称、步骤 ID、输出类型、路径）。绝不可臆造分支名称、步骤或要提交的路径。若既没有运行上下文，也没有这些参数，请说明缺少什么并停止。

---

发布流程——请先阅读

**要求：**无——此技能独立自足。（调用方声明依赖的方式相反：adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook。）

1. 开始：bash {REPO_ROOT}/.agents/skills/factory-runbook/scripts/bash/run-branch.sh [--kind <intent|code>] ——在 Windows 上使用 PowerShell 对应脚本（每个辅助脚本在 scripts/powershell/ 下都有对应版本）。在项目根目录检出运行分支（意图运行时根据 ADLC_ISSUE_REF 使用 factory/intent/<repo>-<iid> ——这是默认值；任务代码运行时加上 --kind code，使用 factory/mission/<repo>-<iid>），复用现有分支或从 origin 继续。意图泳道和重新调度共用此流程。没有 ADLC_RUN_ID 时，此命令不执行任何操作。
2. 执行生命周期步骤。每个有文件更改的步骤之后： bash {REPO_ROOT}/.agents/skills/factory-runbook/scripts/bash/commit-step.sh --orchestrator <name> --step <id> --output-type <draft|decision|artifact-ref|findings> --summary "<one line, no issue text>" --records <IDs> -- <paths the step wrote, moved or deleted>。只暂存允许列表中的路径；为该步骤的总线标记打印 sha: <sha> 或 sha: none。
3. 返回前，务必执行：bash {REPO_ROOT}/.agents/skills/factory-runbook/scripts/bash/open-mr.sh [--kind <intent|code>] ——仅推送运行分支，查找或新建一个草稿 MR（合并提交，不 squash；在创建时应用 Issue 里程碑；若 Issue 指定了受派人则使用该受派人，否则使用运行者自己的账户，详见 tracker-integration.md 操作 11；确定性解析器 {REPO_ROOT}/.agents/skills/factory-runbook/scripts/bash/resolve-mr-ownership.sh 本身由调用方/完成阶段运行，不在 open-mr.sh 内运行），agent-authored 标记也同样在完成阶段处理（任务阶段 6、编排器 §7 规范整理——不在此辅助脚本中处理）。此脚本会将 mr_url 写入 ADLC_STEP_OUTPUT。代码任务（factory/mission/* 分支）请传入 --kind code。无论结果如何都要调用它——空运行不会创建任何内容，关卡会显示没有链接。还要在同一个 JSON 对象中写入一行 conclusion，并保留现有键。
4. 切勿在此处请求审批或等待回复。辅助脚本返回非零退出码（路径被拒绝、缺少提交者身份、跟踪器范围不符）时，运行必须停止——报告问题，不要设法绕过。

在工厂运行之外，除非用户主动启用（在 .adlc/init-options.json 中设置 adlc.commit_steps: true，或将 --commit 传给 commit-step.sh），否则辅助脚本不执行任何操作；没有 ADLC_RUN_ID 时，run-branch.sh 和 open-mr.sh 绝不执行任何操作。

只有由编排器调用的运行手册才会提交、推送并创建 MR，而且只能通过这些辅助脚本执行；生命周期技能绝不会执行这些操作。

运行契约（references/）

文件	使用方
executor.md	每个 Kind-A 编排器（步骤架构、运行状态、泳道、门控、收敛）
tracker-integration.md	与跟踪器集成的技能（评论总线、标签、租约、提供方操作、MR 归属）
lanes.md	基于泳道的分派使用方
mission-brief-template.md	简报/里程碑编写者（队列、编排器）
issues-provider.yml	提供方解析模板（设置时会写入仓库副本）
run-context.md	运行模式与本地会话规则
mission-template.yml	运行策略默认值（执行、监督、预算）