programing-pipeline

编程工作流

与具体产品和工具无关的多代理编程工作流：定义主代理、执行子代理、审查子代理之间的协作契约，以及任务单、验收测试、证据、恢复与合并规则。不规定具体子代理调用方式、命令或通知方式。

适用场景

AI agent 修改、重构、修复、扩展或验证 Git 项目时使用，尤其需要隔离 worktree、独立审查和真实测试的任务。

执行 agent 须能读写项目文件、运行构建/测试命令、创建 Git worktree 并创建子代理；能力不足时在结果中标注证据边界，单代理自检 ≠ 独立审查。主代理成功返回、测试数量增加、退出码为 0 或报告文件存在，都不能单独代表产品完成。

角色契约

• 用户：提供目标、优先级；裁决真实设计决策、外部授权、不可逆风险。
• 主代理：读状态 → 拆任务 → 写任务单+逐条验收测试 → 提交冻结后派发 → 调度执行/审查子代理 → 核全部证据并重跑关键验收 → 更新任务单/路线图 → 全闸门通过后合并并在主工作树复验。不默认替执行子代理写业务代码；遇真实决策点保留现场停下，不猜测。
• 执行子代理：在指定 worktree 按红→绿→蓝实现冻结任务单；跑验收命令与必要回归；只在自己任务证据目录写执行报告。不改冻结目标/范围/验收测试，不自行扩大产品设计。
• 审查子代理：独立上下文读任务单、代码、执行报告；亲自重跑验收测试；查正确性、边界、范围、覆盖率与证据新鲜度；发现问题报 BLOCKED/FAIL。默认只读，不改产品代码。

主代理阶段推进不变量

主代理把执行/审查子代理视为阶段性工具调用。子代理返回只证明该阶段返回，不证明任务完成；主代理不得因为收到子代理结果、看到测试摘要或已经写出阶段总结，就结束当前任务。

• 每个子代理返回后，主代理必须重新读取当前任务单、Git/worktree 身份和本轮 .workflow/<task-id>/ 证据，核对 task-id、branch、HEAD、角色和报告新鲜度。
• 任务单规定还有后续阶段时，主代理必须继续推进下一个阶段，而不是先向用户发送总结；阶段性报告不是终止条件。
• 标准闭环是：执行子代理 → 独立审查子代理 → 主代理最终检查 → 合并后主工作树复验。审查通过不等于主代理最终检查通过。
• 子代理返回 FAIL、BLOCKED、超时或证据缺失时，主代理必须分类并按恢复规则保留现场、建立延续任务或上报阻塞；不得把阶段结果改写为 PASS，也不得跳过后续核验。
• 只有当前任务的最终证据全部齐全，或遇到必须由用户裁决、外部授权或无法自愈的阻塞，主代理才能结束本轮。完成当前任务后按用户约定停下，不自动开始下一个任务。

事实与上下文规则

• 事实只能来自本轮直接读取的文件、命令输出或测试产物；推断必须标为推断，未执行或未读取必须标为未验证，不能补造结果。
• PASS 必须能回溯到当前 task-id、HEAD、worktree、branch、完整命令、退出码、关键断言和产物；通知、代理自述和旧报告不能代替当前证据。
• 主代理按需读取本文件和相关 reference，不默认加载全部资料；委派简报只传任务身份、冻结契约路径、允许范围、验收 ID/命令、决策点和报告格式，证据不足再扩展阅读。

机械工具与项目级反馈

机械检查和统计由独立的 programing-pipeline-tools 命令程序执行；技能只规定调用时机和判断边界。新任务单必须包含 pipeline-contract 机器区块，由 pipeline-tools task validate 校验；任务执行前运行 task preflight，执行中用 command run 统一超时和日志，范围用 scope check，合并前后用 evidence verify 与 gate。

• 工具输出的退出码和原始日志是机械事实；终端摘要不替代日志。
• 在派发 executor/reviewer 前先运行 runtime preflight，确认 Node/pnpm/Git、native ABI 和项目所需测试能力；环境不匹配不得伪装成产品失败或继续正式验收。
• 子代理启动后先执行 runtime handshake：确认可读任务与 worktree、可执行验收命令、可写 .workflow/**，reviewer 不可写产品代码；握手 JSON 必须落在当前任务证据目录。
• 主代理未经用户明确授权不得修改产品代码；executor/reviewer 失败后应重派、建立 continuation 或保留决策点，不得接管实现。
• OpenCode Desktop 会话可用 metrics import-opencode-session 导入结构化流程信号；导入器不得从自然语言推断产品 PASS。
• 程序化命令应优先使用 --format json --output <path>；JSON 结果是后续阶段的权威输入，终端短摘要不作为流程状态来源。
• 使用 lifecycle status 获取当前阶段和允许/禁止动作；语义代理只能提交 recommendation/findings，不能直接把自然语言结论当作 gate 状态。
• 结构化执行闭环使用 dispatch write、result verify 和 freshness；只有当前 task-id、角色、HEAD、验收结果和证据引用均通过机械校验，才能把语义代理的 recommendation 交给下一阶段。
• 工具不可用、命令超时、证据缺失或身份/范围漂移时标为 BLOCKED/漂移，不绕过工具改写成 PASS。
• 报告必须包含机器可读的 pipeline-evidence 区块；自然语言报告不能单独产生验收结论。
• 每个非 metrics 的 pipeline-tools 阶段命令默认自动写入一个 observed 结果事件到项目 .workflow/metrics/；超时、环境阻塞、证据缺口、范围漂移等只根据机械退出码和结构化结果追加 derived 反馈事件。该目录应纳入 Git 追踪，作为可审查的流程改进历史。reported 只能保留追溯，统计不参与验收，不自动改写技能或契约。
• 自动采集不得从自然语言报告推断产品 PASS；不得记录 prompt、完整命令输出、凭据、token 或业务数据。仅在测试/明确诊断时使用 PIPELINE_TOOLS_DISABLE_AUTO_METRICS=1 关闭。
• 正常只把短摘要放入上下文；完整输出、报告和统计事件留在项目文件中，需要诊断时再读取。

不可违反的规则

1. 任务单先于实现：契约必须提交后才能建 worktree 或派发。
2. 契约冻结：不得为迁就实现改验收测试；设计变更记裁决并开延续任务（机器 task-id/path 保留 continuation），保留原历史。
3. 验收测试即用例：每条必须指向当前测试文件、用例、断言、命令、结果边界。
4. 独立审查：独立上下文直接复验；转述他人结果不算。
5. 证据属当前任务：task-id、worktree、branch、测试输出、报告路径必须一致且本轮生成。
6. 真实链路不可替代：单元/组件/协议/持久化/真实浏览器/设备各自证明各自边界。
7. 合并后复验：worktree 通过 ≠ 主工作树通过（依赖、构建产物、原生模块可能不同）。
8. 超时有界：单条测试默认 3 分钟硬上限，超时必须停止诊断；整套用更大的明确累计上限。
9. 决策点停下：缺产品决策、协议兼容、权限、外部服务或验收环境时保留现场上报，不替用户定案。
10. 数量≠覆盖率：绿色数、退出码、完成通知、报告存在、代码行数增加都不能单独 PASS。

标准生命周期

1. 恢复核对：读入口文档、路线图、任务指针、Git 状态、已有证据；发现多个活动任务或状态不一致，先 reconcile；禁止盲目重派或重建现场。
2. 规划拆分：以用户行为或可验证能力为单位；定依赖、范围、契约、风险、决策点、验收矩阵；未写成具体用例即设计未完成。有产物依赖顺序执行；仅文件范围与 fixture 完全不重叠且无隐含依赖才并行。
3. 冻结任务单：默认 docs/tasks/<task-id>.md，证据 .workflow/<task-id>/；提交任务单后记录契约提交，创建 worktree 前确认主分支 HEAD、新 worktree、branch 与契约提交的关系；之后契约冻结。
4. 执行：子代理只在任务 worktree 实现；用户功能贯通 UI→前端/协议→核心→领域事实→持久化/投影→回显→重启恢复；纯基建任务标 prerequisite，不得冒充产品闭环。
5. 独立审查：新上下文核身份和报告新鲜度，逐条复验；通过 ≠ 已合并。
6. 最终检查：读任务单/执行/审查/最终检查报告，抽查高风险测试，重跑关键验收、全量测试、构建、lint、范围、冲突检查；全部有证据才 ready-to-merge。
7. 合并复验：提交实现+证据，用 branch ref 合并；主工作树重装依赖，重跑聚焦验收、全量测试、构建、lint、差异检查；通过才标已合并。
8. 持久化：更新验收台账、执行记录、延续任务索引、最终结果、路线图、任务指针；完成通知含项目、task-id、阶段、分支、合并提交、验收状态、遗留项。

证据目录最小要求

.workflow/<task-id>/ 至少含 executor-report.md、review-report.md、final-check.md；每份写明 task-id、worktree、branch、轮次、命令、退出码、关键断言和证据文件。旧任务目录仅作历史。

任务规模与延续任务

• 含多个独立领域聚合、十个以上互不共享 fixture 的验收族或多平台任务，先拆成可独立审查的切片。
• 实现失败/证据缺失/环境阻塞/设计改变分开记录；设计或契约改变时创建延续任务，使用新 ID、新任务单、新证据目录（机器 ID/path 保留 continuation），父任务失败、裁决、已验收部分不得覆盖。
• 保留实现和证据现场，不无理由删 worktree、分支或报告。

参考文件（按需读取）