Agent-System-Dev/policy/delivery.md

# 需求、试验与迭代交付

适用：本项目的需求、修复、规范修改和其他交付任务。依据固定版本的
[通用交付流程](../deps/development-guidelines/workflows/delivery.md)，本项目收紧为
**目标、范围和交付终点一次确认；范围内连续推进；问题按是否阻塞目标分流；
先可用、再迭代完善**。代码 Review 和 PR 合入由智能体完成。
本文件是阶段、决策点与连续执行的权威表述；启动、同步、命令证据和回收操作见
[开发门禁](governance.md)。规则的执行能力见 [能力矩阵](tool-adaptation-matrix.md)。

## 最高优先级：目标兑现与最小充分交付

本节自写入起立即生效，并在不削弱既有授权、证据、Review、CI、合入、清理与高后果双钥匙
边界的前提下，优先于本文件其他关于阶段、编排和完善程度的解释。

### 先做用户要求，不把任务升级成工程项目

- 用户明确要求的产物、范围、验收条件和交付终点是当前工作的唯一主线。基础设施、工具修复、
  通用化、加固、重构、迁移和新架构只有在用户明确要求，或有可复核证据证明其直接阻塞当前
  目标时才能进入当前范围。
- Markdown、配置、提示词、链接和说明等简单修改默认走最小闭环：定位 → 修改 → 最小直接验证
  → 报告。不得为此新建平台、框架、自动化系统、嵌套控制器、额外 worktree、复杂收据体系、
  新 PR 模板或新的阶段审批。
- Agent 路由、任务卡和证据工具都是交付手段，不是交付目标。推理时间、工具次数、规划方式和尚未写文件
  都不结束一次尝试。尝试只在显式终态失败、进程退出、总超时，或 stdin/stdout/stderr 都没有活动的
  空闲超时时结束。不得转而长期建设或加固路由系统，导致用户要求的简单产物一直未交付。

### 最小可用即停，问题按是否阻塞分流

- 首次达到“用户要求的产物可用、受影响系统可用、最小直接验证通过”后，立即停止新增工作并
  进入交付。后续体验、结构、性能、命名、治理与文档完善是新的增量，须由用户明确要求或另行授权。
- 只修复直接导致目标无法实现、系统不可用、明确验收失败或强制安全门禁失败的问题。高价值但
  不阻塞的问题只记录事实、影响与建议归属；低影响噪音直接忽略，不创建任务、不阻塞交付。
- Review 和 CLI 迭代只处理阻塞项。阻塞项闭合、请求产物可用且最小验证通过后循环立即结束；
  不得以“更完整”“更安全但并非门禁”“更通用”或“顺手清理”为由继续循环。

### 验证与编排必须成比例

- 实施阶段运行能直接证明本次修改的最小检查。完整或长耗时测试只在最终候选上运行一次，且仅限
  本仓规范明确要求、真实影响面覆盖广，或最小测试不足以判断回归的情况。
- 禁止在每个小文档、配置、提示词或 adapter 修改后重复完整套件；已经针对同一候选取得且对象
  未变化的有效结果不得因记录、格式或非阻塞意见重复执行。
- 编排成本不得超过任务本身。实施、修复与测试按 AGENT-EXECUTION.md 的候选和每候选最多 3 次全新尝试
  调度；主模型负责计划、范围与审查，角色分工不得推迟简单产物。检测到实现粒度与任务不匹配时，
  立即降级到最小充分做法。不限制单次 CLI 的推理时长、工具次数、规划方式或首次写文件时间。
- 移除机械人工停顿不等于增加机械 Agent 停顿。真实业务取舍、授权变化、高后果操作和必须由用户
  判定的验收仍请求人工；除此之外，不为计划、工具、自审或非阻塞完善反复等待。

## 授权、决策点与连续执行

任务卡默认记为 `goal-first`。用户的直接请求在目标、允许动作、写入对象和交付终点足够明确时，
即是对该范围的执行授权；方案、审计或只读请求仍不包含业务实施，本地实施不自动包含部署、迁移或共享环境写入。
授权一旦成立，范围内的调查、需求拆解、方案选择、计划、编辑、必要缺陷修复、测试、Review、PR 合入和安全收口连续推进，
不逐阶段、逐文件、逐命令重复请求批准。阶段用于追溯和质量控制，不是默认的人工停顿点。

只有以下情况请求人工决策：

- 目标、范围、优先级、验收条件或交付终点将发生变化；
- 多个可行选项会造成不同的用户结果、公开契约、权限/数据语义或持续运维成本，且现有决策无法确定取舍；
- 触及未授权共享环境、外部资源/成本、不可逆或本仓定义的高后果双钥匙操作；
- 用户感受、业务判断、用户持有的凭据/设备或平台 owner 操作使验收无法由可复核证据自动完成。

存在决策点时，只暂停受影响部分，提交具体选项、影响和推荐；其他已授权且不受影响的工作继续。
用户沉默不补齐真实决策点，但 Agent 自审、测试进展和工具记录也不得被包装成新的人工门禁。
独立 Review、证据、平台准入和高后果双钥匙仍有效；它们保证交付质量和安全，不扩大业务授权。

需求拆解、评估、方案和计划可以共用一份任务卡。小任务只记录目标、范围、验收、关键决定和验证；
不适用的阶段标记原因后直接跳过。任务启动检查、独立工作区和收据用于准备现场，不表示业务结果已验证。

## Agent 实施单元与主模型职责

产生仓库变更的实施工作拆成可独立实施的单元。通用规则遵循上游 [Development-Guidelines 核心硬边界 8 与 agent-execution 标准](../deps/development-guidelines/standards/agent-execution.md)（agent-per-unit、会话隔离、JSON 终态收据、无 host 隐式代写、受控 transport/admission 准入）。任务卡默认记
`实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）`。执行路由以根目录
[AGENT-EXECUTION.md](../AGENT-EXECUTION.md) 为唯一权威；按角色声明的候选顺序在新进程与
隔离工作区中尝试外部 Agent。不得跨单元复用同一外部进程，也不得 resume 同一次尝试。

实施、修复与测试的正常候选只有 Cursor、Antigravity（`agy`）和 PI。每个候选对安全可恢复失败
最多 3 次全新尝试：`unavailable`，或外部无副作用已被机制证明的 `failed-clean`。三次仍属这类失败后才进入
下一候选。单元包的 `network=false` 与 `external_cost=false` 只是声明，不证明外部干净；当前没有强制的
网络/外部费用隔离或可信对账，所以已启动的失败尝试即使私有克隆可精确恢复，也记为 `failed-unknown`
并保留现场。三个正常候选都安全耗尽后，才允许一次全新的 Codex CLI 紧急尝试；这次不按每候选 3 次计算。
紧急尝试若仍是安全可恢复失败，运行停在 `blocked`。host 不接过该单元继续撰写。

Codex 平时只用于规划、方案设计、实施计划，或独立 Review。执行配置没有单独的 plan 角色；
上述规划与设计工作可以直接使用 Codex CLI。`review` 角色的候选可以包含 Codex，并按该角色自己的
顺序和尝试上限执行。Codex 不出现在实施、修复、测试的正常候选里；这三个角色上的一次紧急尝试是唯一例外。

显式 fail-stop 立即停止整次运行，不重试、不换候选、不启动紧急尝试：`failed-unknown`、
`scope-expansion`、`blocked`、`cancelled`、无效配置、未对账的 Git 状态与安全失败。总超时，
以及 stdin/stdout/stderr 都没有活动的空闲超时，归入 `failed-unknown`。

一次尝试只在显式终态失败、进程退出、总超时或该空闲超时时结束。推理时长、工具次数、规划方式和
首次写文件时间都不是结束条件。CLI 可在该单元的目标、范围与安全边界内自主检查、计划、测试并迭代。

worker 提示词写明终态记录的 JSON Schema（`terminal_status`、`summary`、`changed_files`、`evidence`、
`scope_expansion`）。控制器只从该 CLI 实际事件信封解码：Cursor `stream-json` 的 `result` 事件、
agy `stream-json` 的 `result` 事件或 `json` 输出对象、PI `json` 模式最后一条 assistant `message_end`。
退出码 0 且有改动时，只有有效的 `completed` 记录才可能成功；记录缺失、无效或仅有散文均记
`failed-unknown`。`blocked`、`cancelled`、`failed-unknown` 记录直接按该终态停止，不得成功。

主模型（host）负责计划、拆解、有界单元包、强制范围、检查与审阅实际 diff、运行权威验证、
规范提交、管理 PR/CI/合入、写入证据与任务管理元数据，以及安全清理。权威验证、集成、合入与
任务卡证据所有权属于 host；worker 的局部自检不能替代任务卡证据、独立 Review、当前 HEAD 的 CI
与平台准入。

每个外部 worker 只接收一个有界单元。Worker 不得扩围、提交、推送、打开或合并 PR、派遣同伴、
改变路由或模型、部署，或清理规范 worktree。

单元包不得要求 worker 暂存或修改 Git 索引、配置或引用（`git add`、`git update-index`、
`git commit`、`git stash`、`git submodule init/update`、`git config`）；需要改 gitlink 时，
只在子模块目录内检出目标提交并保持未暂存。host 在 `scripts/agent-exec run` 前提交自己的改动，
运行期间不修改规范检出（包括 `.task/**`）。

`run-everything` 仅在隔离单元内取消逐步命令批准提示；不扩大用户授权范围，也不授予 worker
规范 Git、推送、PR、合入、部署或清理权威。

实施结果进入当前分支，必须来自一次成功 transport，由 host 执行
`scripts/agent-exec apply` 在干净分支上快进；或者本次暂存内容通过 pre-commit 调用的
`admit`：非豁免路径与该成功 transport 的路径和精确内容一致，且 transport 的父提交是当前 HEAD。
apply/admit 依赖的本地 HMAC 执行历史与 checkout 钩子只是本地完整性/篡改证据（SELF）：同一主机
OS 用户可读取密钥或绕过钩子，因此它不是 GATE、可信身份或防恶意主体的保护。本地记录缺失或无效
仍拒绝；交付信任只来自精确 HEAD 的必需 CI（GATE）或独立 REPLAY。
host 可以直接编写并提交的豁免只有 `.task/**`、`docs/superpowers/specs/**` 和
`docs/superpowers/plans/**`。除此之外，host 不直接撰写实施单元。

安全耗尽不发出 `host-fallback-authorized`，`host_fallback_authorizations` 保持为 0。
未配置紧急候选时终态为 unavailable 或 blocked，不授权 host 撰写实施单元。现行
[AGENT-EXECUTION.md](../AGENT-EXECUTION.md) 的 `fallback_to_host` 是 `never`。旧值
`all-unavailable` 仍可解析，但同样不产生 host 撰写授权。已归档任务卡里的旧表述保持原样，
不改写成现行规则。

规划、只读调查、证据捕获、任务卡与 superpowers 规格/计划，以及 apply 或 admit 通过之后的集成、
验证、提交和 PR/CI/合入，属于 host 管理工作，不递归创建另一实施单元。

本条不重新引入逐阶段人工门禁；goal-first 的决策点、严格范围、先可用再迭代、独立 Review、
证据、平台准入与高后果双钥匙规则继续有效。

### 阶段会话隔离与独立 Review

为避免实施上下文、既有结论和自我辩护污染后续判断，阶段执行遵循“一个阶段/单元，一个新会话”：

- 需求分析、方案比较、设计、计划、实施单元、测试、Review 和验收默认分别启动全新会话。主模型可持续
  保存调度与任务状态，但交给 CLI 的每个阶段必须是新进程、新 conversation/thread、新 session；
  不跨阶段复用实现会话。
- Review 只有两种有效执行者：当前 host 主模型，或单独启动的全新 CLI session。实施 CLI 可以做局部
  自检，但其原 session、自我总结和续聊结果不构成独立 Review。
- 禁止评审调用使用 `--continue`、`--resume`、既有 conversation ID、session ID/文件、共享交互窗格，
  或任何会恢复实施上下文的等价方式。即使使用相同 CLI 或相同模型，也必须有新的 session 身份。
- 评审包只包含：固定目标与验收条件、适用规范、base/head、实际 diff、直接相关测试及来源明确的证据。
  默认不包含实施对话、隐藏推理、中间自评、失败尝试叙述和原 session 历史；需要背景时提供最小可复核
  事实或产物链接，不复制整段上下文。
- 任务卡/收据为各阶段记录 `stage`、工具、模型、attempt、session ID 与 `fresh_session=true`。CLI 不提供
  session ID 时记录 `not-observable`，同时记录新进程命令及未使用恢复参数的事实。无法证明独立性时，
  结果只能标为作者自检 `SELF`，不得标为独立 Review/REPLAY。
- 会话隔离不要求为简单任务增加新平台或复杂编排。平凡文档/配置任务仍按最小闭环执行；需要独立 Review
  时只额外启动一个最小、一次性的评审 session，不复用实施 session，也不扩展任务范围。

### 有界单元包、上下文与阶段交接

通用规则见共享 [standards/agent-execution.md](../deps/development-guidelines/standards/agent-execution.md)
与 [workflows/handoff.md](../deps/development-guidelines/workflows/handoff.md)；本节只写本仓做法，模型偏好见
[AGENT-EXECUTION.md](../AGENT-EXECUTION.md#model-preferences-project-choice)。

- **单元包**：用现有单元包 JSON 的 `goal`/`constraints`/`verification` 写清：一个结果及验收条件、允许路径与
  须遵守的契约、非目标、前置提交 SHA、最小必读清单、直接验证命令、上下文容量及其来源（未知时按保守的
  100K 假设）和为执行预留的余量。不新增 schema、运行时字段或控制器。
- **容量**：100K/200K/300K/500K 只是规划参考，不是对任何 provider 能力的声明；容量更大不授权更宽的任务，
  单元仍按一个结果拆分。容量未知不构成失败条件，也不做自动容量强制。
- **阶段交接**：长任务每完成一个里程碑，host 自动在现有任务记录中写一份简短的持久交接：目标、状态、关键决定、
  文件与 SHA、命令与结果、阻塞项、下一步和来源链接；下一个 CLI 阶段或单元以全新会话启动，只读取交接与最小
  必读材料，不为交接等待人工。
- **上下文压力**：provider 支持时，只在阶段完成后使用其上下文压缩；没有自动压缩不阻塞工作。普通上下文压力用
  交接加 host 在既有授权内重新打包单元处理；只有真实扩围才按既有 `scope-expansion` fail-stop。
- **如实区分**：请求模型与实际事件报告的有效模型；可观察的 session 身份与 `not-observable`；worker 局部自检
  （SELF）与 host 集成验证、独立 Review、精确 HEAD CI（GATE）。
- **验证分工**：worker 只跑直接检查；host 在最终候选上运行一次所需的集成套件。涉及安全、契约或部署的改动，
  须写明正向、负向与回归用例。
- **单写者与强制边界**：同一单元同一时刻只有一个写者，host 在运行期间不改规范检出。记录时区分三类约束：
  提示词指导（单元包内容、容量、交接、模型偏好）、观察到的行为（事件报告的模型与 session），以及工具强制
  （配置校验、尝试上限、超时、transport/admit）。本节不新增门禁，不放宽凭据、范围、未知副作用与 CI 边界。

### 两级分支交付模型与分流检查

本仓采用两级业务交付模型：
- **`main`**：稳定基线，仅接纳已完成并通过最终组合准入的结果。
- **大任务集成分支（initiative）**：从最新 `origin/main` 建立，根目标与即时目标均为 `main`。负责跨单元目标的阶段集成、组合验证与最终交付。合入主干后关闭、归档与回收，不作为长期存在的 develop 分支。
- **子任务分支（child）**：从远端所属大任务分支的当前头建立（须等于分流收据核验的 head，`make task-start` 校验），即时目标为大任务分支。负责一个有界单元的实施、独立 Review 与局部验证，通过 PR 合入大任务分支。
- **普通任务分支（standalone）**：可独立验收、无需阶段集成与组合验证的工作（含修复、完善与新能力），直接从最新 `origin/main` 建立并向 `main` 交付。

每个任务卡记录 `root_target` 与 `immediate_target`（子任务为所属大任务分支，其余为 `main`）。`make task-resume`、`make task-sync` 与 `make task-finish` 以 `immediate_target` 为准；任务卡默认在合入前以 `make task-close SELF=1` 闭合并随本 PR 合入（归档后上述命令仍从 `.task/archive/` 读取合入前闭合的卡）；遗留卡的 `make task-close` 仅在 `FOLD=--fold` 时以其为闭合 PR base。

每次接到新需求，创建分支前必须分流，事实来源为 origin（本地 `.task/` 不参与发现）：
1. **发现**：`make task-triage REQ='<需求>' TRIAGE_RECEIPT=<路径>` 查询远端。候选须已推送、存在以 `main` 为 base 的开放 PR，且该远端分支的任务卡声明 `branch_kind=initiative`、`accepting_requirements=true` 且未标记已完成。无候选时收据直接为 `NEW`；有候选时为 `DECISION_REQUIRED`（退出码 5）。远端或 Gitea 不可核验时记为 `REMOTE_UNVERIFIED`（退出码 6），不得得出 `NEW`。
2. **决策**（仅有候选时）：`make task-triage-decide TRIAGE_RECEIPT=<路径> VERDICT=JOIN INITIATIVE=<分支> REASON='<加入理由>'`，或 `VERDICT=NEW REASON='<不适配理由>'`，显式记录结论与理由。禁止按候选数量自动 `JOIN`；加入会改变范围、关键路径或交付边界时交用户决策。
3. **启动**：`make task-start … TRIAGE_RECEIPT=<路径>` 在创建任何 worktree 或分支前核验收据（默认 4 小时内有效）、候选对象未变化，且结论与分支类型及所选 initiative 一致；不一致或远端不可核验时拒绝，不建分支。
- `JOIN` 建立子任务（child）；`NEW` 建立普通任务（standalone）或新的大任务（initiative）。

PR 目标：子任务 PR 的 base 为所属大任务分支；普通任务与大任务 PR 的 base 为 `main`。`make task-pr-check` 在本地核验 base 与 head（远端为准），CI 的 `PR base gate` 以同一规则复核。

两级合入与验证：
1. **子任务合入大任务**：子任务完成时，通过 `make task-sync` 合并大任务分支的远端最新状态（delivery 只认远端头），解决文本与语义冲突，完成直接相关测试与独立 Review 后，以大任务分支为 base 提 PR，并通过 `make task-pr-check` 与 CI `PR base gate`；L2→L1 按下文「层级、任务通道与分级门禁」的轻量门禁执行，不排 #518 窗口、不要求三段证据；
2. **大任务合入主干**：所有必需子任务已合入或已延期后，将大任务卡的 `accepting_requirements` 置为 `false`，通过 `make task-sync` 同步最新 `origin/main`，再运行 `make task-pr-check FINAL=1` 核验 `## 子任务登记` 中必需子任务均为「已合入」或「已延期」；随后执行完整组合验证、独立 Review 与必需 CI，以 `main` 为 base 合入。

### 层级、任务通道与分级门禁

层级固定两级，不再加深：
- **L1 initiative**：从 `main` 切出，最终一次合入 `main`。
- **L2 child**：从 L1 切出，合入 L1。L2 内部用 agent-exec 单元控制上下文，单元不开 PR。
- L1 超过约 2 周或 6–8 个子任务时，横向拆成多个并列 L1，用规划主记录串联；L2 过大时拆成兄弟 L2 或更多单元。

L1 章程与运行：
- 章程写在 L1 任务卡 `## 目标与非目标`：用途与目标、接纳范围与非目标、方案/计划链接、分级测试策略、验收条件、追加领域规则、生命周期；并维护 `## 子任务登记`。
- 建立 L1 时即开一个 base 为 `main` 的 [WIP] PR，供分流发现；其评论区作为该 L1 的仓外调度记录。
- 已登记在 `## 子任务登记` 的子任务可免分流收据，直接 `make task-start KIND=child …`。
- 子任务可继承 L1 章程中的全部或部分领域规则，并在子任务卡注明继承范围。
- L1 不追 `main`，只在最终窗口、需要 `main` 上某修复、或长周期 L1 的里程碑/每周一次时运行 `make task-sync`。

任务通道分两步判定，类别与拓扑互不替代：
- **类别只决定优先级**：修复用 `fix/`（P0 生产事故用 `hotfix/`），在合入队列中优先；hotfix 可在 #518 写明原因后插队。完善、扩展、新增不设额外优先级。
- **拓扑只按集成与验收需要决定**，不因工作被称为新增、完善或规模大而建 L1：
  - **standalone**：工作有自己的验收、没有依赖单元、不共享集成契约、也不需要协同发布验证时，从 `main` 切出并直达 `main`；小完善与新能力同样适用。可独立验收的修复默认为 standalone。
  - **L1**：多个相互依赖的单元、跨单元集成或一个共同最终验收需要阶段集成与组合验证时，建立 L1 并写章程。
  - **child**：工作（含修复）属于某在途 L1 的共同范围、依赖链或验收时，作为其子任务。只有该 L1 已记录的目标与验收确实覆盖此工作、且加入不会悄然改变其已约定范围时才 `JOIN`；否则按上两条判定 `NEW`。远端发现不可核验时不得得出 `NEW`、不建分支。
- 治理与规范调整同样按上述拓扑判定；需要 L1 时集中到一个治理 L1。
- 只改记录（任务卡、报告）的变更不单独推进 `main`，随所属任务 PR 合入。
- 组件 pin 跟随用到它的 L1/任务一起推进，不单独开 pin PR（紧急修复除外）。

分级门禁：

| 层级 | 检查 | Review | CI | 合入窗口与证据 | 人工 |
|---|---|---|---|---|---|
| 单元→L2 | worker 自检 + host 最小直接检查（`make test-affected`） | host 审阅实际 diff | 无 | 无 | 无 |
| L2→L1 | `make task-sync` 同步 L1 头 + `make test-affected` | 一次全新会话独立 Review | 轻量 CI（PR base 非 `main` 时只跑 `test` 作业，`test-pg`/`svc-realcombo` 跳过）作为 GATE | 不排 #518 窗口、不需分流收据（已登记子任务）、不要求三段证据；任务卡合入前 `make task-close SELF=1` | 无 |
| L1 的 WIP PR | — | — | 完整 CI，作为非阻塞预警 | — | — |
| L1 或 standalone→main | 最终窗口内 `make task-sync` + 完整组合验证 | 整体独立 Review | 完整 CI（`test`、`test-pg`、`svc-realcombo`） | #518 窗口、三段证据、合入前折叠闭合 | L1 最终一次用户专属验收（如有） |

人工审批只保留 L1 章程确认、L1 最终用户专属验收与高后果双钥匙操作；等待 CI 一律 `make ci-wait SHA=<完整 SHA>`。

## 目标优先、范围控制与问题分流

执行顺序为：

` 授权与安全边界 → 任务目标和系统可用 → 直接阻塞项 → 后续改进 `。

当前任务的完成标准是已批准的验收条件成立、目标用户链路可用，且受影响的既有关键能力没有明确回归。
完成不要求把所有邻近代码、历史欠账、工具噪音和低影响建议同时清零。先形成端到端可用、可验证的最小闭环，
再把体验、结构、性能和治理优化作为独立增量。

新发现按以下标准处理：

| 类别 | 判定 | 当前任务动作 |
|---|---|---|
| 阻塞项 | 直接导致目标无法实现、验收条件失败、系统/关键回归不可用、安全边界违反或必需门禁失败 | 在已授权范围内作最小充分修复；若超出范围，提交最小扩围决策 |
| 有价值非阻塞项 | 当前目标仍可交付，但有具体影响、复发风险或明确后续价值 | 只记录事实、影响和建议归属，不在当前任务修复，不阻塞交付 |
| 低影响噪音 | 不影响目标、可用性、安全、回归或后续决策 | 忽略或在当前记录中一句带过；不新建任务、不阻塞、不扩围 |

“影响目标”只决定问题的优先级，不自动扩大授权。“相关”、“顺手”、“重构更干净”、“以后可能用到”都不是当前实施依据。
Review 只将阻塞项列为必修；非阻塞意见标明后续建议，不得以“更完善”为由拒绝已达标且可用的当前增量。

## 阶段与出口

| 阶段 | 必需产物 | 进入下一阶段的条件 |
|---|---|---|
| 1 需求拆解 | 目标、用户场景、子需求、边界、非目标及待澄清问题 | 目标、授权范围和交付终点可执行；只有会改变结果的歧义才触发决策点 |
| 2 需求评估 | 价值、可行性、成本、风险、依赖、现有能力及在途任务重叠；与项目定位、模块职责和公开契约的符合度 | 无需用户取舍的评估由智能体结论；重大未知转入受控试验或具体决策点 |
| 3 需求表确认 | 稳定 ID、描述、适配依据、优先级、可判定验收条件、依赖和处理结论 | 当前增量与授权一致；影响实施的关键事实已核实或显式标注限制 |
| 4 方案设计 | 推荐方案与必要备选、职责和接口、数据与权限影响、失败恢复、待验证假设及试验结论 | 在已批准目标内选定最小充分方案；只有重大取舍触发人工决策 |
| 5 实施计划 | 关联需求的工作项、依赖顺序、责任人、文件或模块范围、测试方法与环境、完成条件及停止条件 | 计划足以执行且不扩大授权；远期工作保留粗粒度但不纳入当前任务 |
| 6 实施与自检 | 可审查变更、局部测试、计划偏差与迭代记录 | 当前增量达到验收条件，范围内阻塞项已闭合，非阻塞项已按价值分流 |
| 7 正式测试与验收 | 需求到证据映射；正常、异常、边界、回归结果及缺项 | 同步并固定被测对象，必需自动验证有有效证据；仅用户可判定的验收单独请求人工结论 |
| 8 代码 Review | 智能体审阅者、对象版本、需求符合性、正确性、维护性、测试充分性及问题闭合记录 | 智能体完成必要重放、整改、补测和复审；当前版本 Review 通过，平台要求的独立批准已满足 |
| 9 合入 | 最新 base/head、当前 HEAD 的 CI、Review、冲突处置和合入结果 | 智能体再次同步，确认冲突已解决、Review 有效且 CI 全部通过，经 PR 执行合入并核验真实结果；无需另请人工合入 |
| 10 合入核验与收口 | 实际合入内容及组件版本、验证依据、成果保存位置、写者状态、清理清单、任务归档安排及适用规划的进展与下一步建议 | 证明成果已保存、所有写者已退出并且回收条件满足后，智能体安全回收并闭合任务卡；无法证明时保留现场并请求决策 |

各阶段默认按已授权范围连续执行；只有命中本文定义的决策点才暂停受影响部分。
阶段产物、独立 Review、验证条件和平台准入保留；移除的是机械性人工签字，不是质量证据。
正式测试和最终 Review 的顺序不限制设计阶段试验、实施期测试或提前审阅。
文本合并无冲突不证明组合兼容；合入后仍核验真实内容与被测候选是否一致。

多个就绪任务的最终验证与合入按 [合入调度](#合入调度) 的采纳状态执行。
新模式生效后，阶段 7–9 在同一目标交付窗口内完成；对象未变时各节点重复核验，
不因记录检查再创建提交或重跑有效 CI。窗口领取不代替已触发的必要决策、独立 Review 或平台准入；
未生效时继续既有同步规则。固定后的证据按 [源码外收据流程](governance.md#候选固定前后) 保存。

## 长期方向与任务衔接

用户提出大方向、长期目标或跨任务规划时，必须在项目中留存可接续的主记录，不能仅保留
在聊天、IDE 私有计划或执行者记忆中。优先更新已有相关规划；确需新文档时，沿用
过程仓的 `modules/documents/docs/proposals/`，并在 [项目入口](../PROJECT.md) 提供链接。
正文只维护一处，任务卡和其他入口引用文档及版本，不复制另一份规划状态。

主记录至少包括：目标及背景、范围及成功标准、阶段或里程碑、关联方案和任务、来源、
负责人、确认状态、推进状态及更新时间。只有方向时可以先写简短目标记录，未知项标待定。
未确认的想法标“待确认”；确认依据与版本另记，不能由“已记录”推断“已批准”。
方向、范围或优先级调整时保留原决定、变更原因及批准依据，更新受影响的方案和任务引用。

启动或恢复相关任务时，先读取适用方向及规划的当前有效版本，核对本任务所属里程碑、
已有实现和在途任务。多个规划相互冲突或优先级不明时，记录冲突并提交人工决定，
不凭文档标题、日期或本地旧副本擅自选择权威。

任务完成时，如果存在适用方案或规划，必须依据实际结果更新其进展，并在任务主记录和
最终交付说明中给出下一步任务建议：

- 说明本任务推进了哪个目标或里程碑，以及剩余差距；区分已实现、已验证、已合入和已部署。
- 优先推荐一个下一任务，说明要解决的问题、关联规划及版本、推荐理由和优先顺序依据。
- 写明前置条件、依赖、待确认事项、预期产物和可判定验收条件；必要时补充备选及取舍。
- 建议前核对已有或在途任务；已有任务覆盖时引用该任务及待续办内容，避免重复安排。
- 无适用规划或规划已经完成时如实说明；存在阻塞时列出阻塞条件，优先建议澄清、验证假设
  或解除阻塞的任务，不为凑出下一步虚构工作。

进展更新和建议属于当前任务的收尾产物。跨仓更新遵循对应工作区、版本和评审要求；
更新尚未获批或合入时，任务卡保留待更新内容、负责人和下一动作，不能声称原规划已更新。
**下一步建议不等于启动授权**：没有覆盖该任务的明确授权，建议停留在待确认状态；
当前任务的完成或执行授权不自动扩展到新任务。

## 需求表与追溯

需求表以任务卡为主记录。项目符合度使用“符合 / 需调整后符合 / 不符合 / 待核实”，
附当前源码、项目约束或实测依据。处理结论使用“纳入本增量 / 后续处理 / 拒绝 / 待定”，
与符合度分开；关键依据缺失时保留待核实，不凭推测判定通过。

每个纳入实施的需求必须能追溯到：

`需求 ID 与验收条件 → 方案及工作项 → 测试或审阅方法 → 当前版本结果与证据`。

没有可判定验收方法的需求先澄清；待定或不符合的需求未经重新评审不得进入正式实施。
跨模块、权限、持久化、异步和恢复需求按实际风险补充真实链路及故障场景。
规范和文档任务采用差异、链接、规则一致性及相关工具行为检查，不制造无关业务测试。

## 设计探索循环

需求分析和设计阶段允许先试验再完善方案，无须先批准尚未能确定的完整设计。
执行试验前记录最小试验计划：待回答的问题或假设、对象和隔离环境、方法、预期判据、
允许副作用、时间或成本边界、停止条件及产物保存或处置方式。试验在已授权目标内、可逆、已隔离且不新增外部成本时直接执行；
命中决策点时再请求对应授权。

在已批准范围内可以反复尝试：

`初步方案 → 核对授权与试验边界 → 原型或测试 → 分析证据 → 修订方案与计划 → 核对结果`。

记录成功、失败及不确定结果，以及下一步继续探索、采用、换方案或暂停的理由。
超出范围、触及未授权共享环境、达到预算或持续无有效进展时，暂停受影响试验并提交决策。
无需强求全部未知一次消除；影响下一步的关键假设必须有结论，其余风险有责任人与处理安排。

原型标明用途和限制，不自动成为正式实现。决定复用时纳入方案、计划、代码 Review 与正式验证。
试验成功仅证明相应假设，不能替代验收；失败结果用于调整方案，不能静默降低验收标准。

## 实施、测试与 Review 的反馈循环

按可独立验证的增量推进；近期工作细化到可执行，后续工作根据证据逐步细化。
每轮形成“发现与证据 → 原假设或困难 → 调整及影响 → 重审和补测范围 → 决策 → 结果”。
记录放在同一任务卡，较长材料只引用文件或 PR，避免多份状态。

### 智能体行为面的真实验证（2026-10-09 裁定）

改动智能体行为面的 PR——提示词库、技能配方（SKILL 与 housestyle）、工具描述与
注册面、上下文组装与回放、终轮门禁与评分——须附**真实模型的任务级前后对照**
（`modules/backend/eval/live/` 基线，或等价的最小重放集），写入任务卡并标注来源
（GATE/REPLAY/SELF）。单测与 mock 回放不覆盖模型实际行为，只能证明机制，不能
替代该对照。确无条件跑真实模型时，在任务卡显式标注 `NOT_RUN` 并说明原因与
补救计划；不得以“预期改善”措辞代替证据。评测材料不进仓（沿用 eval/README 口径）。

| 变化 | 执行动作与评审边界 |
|---|---|
| 已批准范围内的内部组织、等价实现、局部缺陷修正 | 当前阶段继续调整、自测并记录；满足阶段表的客观出口条件后继续 |
| 技术路线、模块职责、公开契约、数据或权限设计、外部影响，或计划的关键依赖、交付顺序和资源约束变化 | 先判断是否改变已批准用户结果或持续成本；否则在范围内调整并补测，是则暂停受影响部分并提交决策 |
| 目标、范围、优先级或验收条件变化 | 返回需求评估和需求表，取得对应批准后更新下游方案、计划和验证 |
| 影响不明 | 先调查；仍无法判定时提交人工决定，不自行归入细节调整 |

未受影响且已有授权的工作可以继续。测试或 Review 发现实现缺陷，返回实施修复；
发现设计缺陷返回方案；发现需求理解错误返回需求阶段。只重走受影响环节，并说明
未重走部分为何仍有效。新版本不能沿用已受影响的批准、测试或 Review 结论。

批准对象使用文档修订或提交标识；正式验证固定源码、组件组合与相关配置。
对 head/base、依赖、需求或契约变化重新判断证据及评审的有效性，按影响补测和复审。
阶段状态、测试状态、代码审核状态及合入状态分别记录，不以一个“完成”互相替代。

## 合入调度

状态：active；执行方式：manual。目标是多个分支并行开发，同时避免各分支随 `main` 移动反复同步、
解决冲突和重跑最终 CI。本节只安排 Dev `refs/heads/main` 的最终交付顺序；需求、授权、阶段状态和
证据仍在原任务卡，受保护分支的最终准入仍由 Gitea 执行。

- **队列**：Dev main 只用一份[合入队列 #518](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/issues/518)，
  只记录顺序和当前窗口：任务/PR、owner、依赖、就绪状态、当前 base/head、CI、合入结果。
- **职责**：协调智能体维护顺序和窗口；任务 owner 负责分支内容和必要整改；窗口内的同步、冲突处置、
  Review、当前 HEAD CI 核验和所有 PR 合入由智能体执行。
- **范围**：只有推进 Dev main 的 PR 使用窗口，即 standalone/修复 PR、L1→main 与遗留卡闭合 PR；L2→L1 合入不排窗口
  （见 [层级、任务通道与分级门禁](#层级任务通道与分级门禁)）。组件仓按各自目标分支单独安排。
- **入队与顺序**：入队表示内容基本就绪且已取得所需授权，不要求已含最新 main。依赖未完成或待必要
  人工决策的任务标 `blocked`，不占窗口。默认按就绪顺序；`fix/`、`hotfix/` 优先，插队须在 #518 写明原因。
- **等待**：等待分支继续独立开发、提交和局部检查，但不因 main 前进而合并最新 main、解决无关冲突、
  推送新最终候选或重跑完整最终 CI，只记“待轮到后同步”；开发期检查不作为之后新 HEAD 的准入证据。

同一时间只给一个 Dev main 任务最终窗口。领取前确认前一窗口已释放、依赖已完成，并在 #518 记录
任务、PR、owner、当前 source HEAD 和领取时间。窗口内按序执行：

1. 运行一次 `make task-sync` 纳入最新 `origin/main`，解决冲突并核对组件组合；
2. 完成并提交候选内容（含任务卡），固定 `base_sha` 与最终 `head_sha`；
3. 运行任务要求的本地检查，固定后的收据保存在源码外（见[候选固定前后](governance.md#候选固定前后)），不为记结果改变 HEAD；
4. 对固定 HEAD 运行完整 CI（`test`、`test-pg`、`svc-realcombo`），用 `make ci-wait SHA=<完整 SHA>` 等待；
5. 完成当前 HEAD 的必要人工决策（如有）和智能体 Review，合入前再核对 main、head、冲突和三项 CI；
6. 以固定 `head_commit_id`、`force_merge=false` 经 PR 合入，回读实际 main 与候选一致后释放窗口，结果写回 #518。

同一 base/head 下，验收、Review 和合入前的 `make task-sync` 只核验（`changed=0`），不创建额外提交，
也不重复仍有效的完整 CI。目标 base、候选 HEAD、组件 pin、检查定义或相关环境任一变化，旧最终结果即失效；
受影响任务回队等待新窗口，不复制旧绿色状态、不为省 CI 降低检查。窗口外仍有 main 推进时按对象变化处理并记录。

冲突、代码/Review/CI 失败或等待必要人工决策时，当前任务保存现场、标 `blocked` 并释放窗口，其它分支继续
局部开发。合入请求超时或结果不明时先查询 PR 与 main 的真实状态，查清前暂停该目标，不重复发送合入请求。
本流程不建设、也不得推断已存在自动队列、优先级、合并列车、批量预测合并、原子租约或旧执行者 fencing，
不修改分支保护、CI workflow 或 runner 配置。

## 合入、清理与恢复

### 智能体 Review 与 PR 合入

已获实施及交付授权的任务，代码 Review 和所有 PR 合入必须由智能体执行，包括任务卡闭合 PR、
机器人和紧急通道。用户只负责已触发的必要决策及按双钥匙要求亲手调整平台保护；合入统一经智能体的
同步、Review、当前 HEAD CI 和平台准入流程完成，不由人工直接点击合入。
本条即该范围内的合入执行授权，条件满足后由智能体直接合入，无需用户再次批准或亲手点击。
用户明确限定为只读、方案、本地修改、草稿 PR 或禁止合入时，以该任务边界为准。
前序阶段的必要产物和已触发决策结论仍须齐备；合入职责不扩大需求、业务实施、部署/迁移或高后果操作授权。

智能体按以下顺序执行：

1. 完成 Review，记录审阅者及其身份、base/head、结论、问题处置和必要重放依据。
   要求独立审阅时由未参与本次实现的审阅智能体完成；平台要求的非作者批准须由符合
   平台身份及权限条件的账号给出，切换智能体角色不等于非作者账号批准。
2. 合入前以 evidence 记录 `make task-sync`，将最新权威目标纳入任务分支，解决全部
   文本及组件冲突，检查组合兼容性。无法在已批准需求和方案内判断冲突取舍时，暂停合入
   并提交具体决策；无冲突或仅文本合并成功不能代替语义兼容核验。
3. 同步、冲突解决或整改导致 head/base 变化时，重新判断 Review 与测试的有效性，完成
   受影响的复审和补测，推送新 HEAD，并等待该 HEAD 的 CI；旧版本绿色结果不能放行新版本。
4. 核验当前待合入 HEAD 的全部必需 CI，包括本仓 CI 的测试、构建及适用的其他作业，
   记录完整 SHA、运行链接、执行身份和结果（GATE）。缺检查、排队、运行中、失败、取消、
   适用检查被跳过或来源无法核验时均不得合入；本地 SELF 测试不能替代 CI 通过。
5. 再查最新 base/head、冲突状态、有效 Review、CI 及平台准入，满足后通过平台 PR 接口
   执行合入。最终推进须受平台陈旧候选保护、合并队列或等价的目标分支串行与版本核验保护；
   目标再前进时重新同步和核验，不绕过平台拒绝、不降低检查或批准要求。
6. 查询真实合入结果，记录 PR、被核验 HEAD、合入 SHA、目标分支和内容/组件核对结果。
   超时或断连先查询 PR 及目标状态，再决定是否重试；合入与后续清理分别记录。

本流程由智能体执行，任务卡模板和本地提示不构成平台强制门禁。平台能力按
[能力矩阵](tool-adaptation-matrix.md) 核验；分支保护变更仍由用户按双钥匙边界执行。
交付窗口覆盖普通 PR、闭合 PR、机器人及紧急通道；coordination 仍为 manual 时如实登记，
当前目标在窗口内被外部推进则建立新尝试，不继续使用旧候选的绿色结果。

### 清理与恢复

已授权任务的标准安全收口无需另行人工批准。仅回收本任务登记工作区，按开发门禁核对当前权威目标、
父子仓成果、未跟踪和 ignored 文件、独有提交与引用、活动 Git 操作以及所有写者退出。
无法证明成果已保存或写者已退出时保留现场并只请求该具体决策；本地删除与远端分支删除分别报告。

清理前保存任务主记录与证据。执行回收时将命令输出用 evidence 的 `RECEIPT` 模式保存到
待删目录之外；回收后的结果写入后续闭合记录，不能向已删除的任务卡补写收据。
任务卡默认在最终同步/合入前于任务 worktree 运行 `make task-close SELF=1`：写入本 PR 链接与
"已完成（合入前闭合）"状态并归档，随同一 PR 合入，不另建闭合 PR。仅已合入未闭合的遗留卡在主检出
运行 `make task-close`（`feature/card-close-*` PR）或用 `FOLD=--fold` 回填归档；其闭合 PR 的创建核对
当前闭合授权，合入按上述智能体 Review 与 PR 合入流程执行。
post-merge 默认只提示，不因 pull 或 merge 自动提交、推送或创建闭合 PR。

中断或交接时记录当前有效版本、批准范围、未决假设、最新试验结论、剩余事项及下一动作。
恢复后核对现场和授权，从最早未满足的环节续办；不重做仍有效的工作，不省略失效环节。