diff --git a/AGENTS.md b/AGENTS.md index 2ea3bcbb..b1858643 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,12 +88,12 @@ policy/delivery.md。 ## 任务启动门禁（强制） -- **新需求分流检查**：每次接到新需求，在创建分支前先运行 `make task-triage` 检查目标仓库中是否有接纳中的大任务集成分支（`branch_kind=initiative` 且 `accepting_requirements=true`）。三态分流：`JOIN`（建立对应大任务的子任务 `make task-start KIND=child INITIATIVE=feature/ NAME=feature/-`）、`NEW`（建立普通任务或新的大任务 `make task-start [KIND=initiative] NAME=feature/`）、`DECISION_REQUIRED`（存在多个候选或改变范围/优先级，由人工决策）。 +- **新需求分流检查**：每次接到新需求，在创建分支前以远端为准运行 `make task-triage REQ='<需求>' TRIAGE_RECEIPT=<路径>` 检查接纳中的大任务集成分支（`branch_kind=initiative` 且 `accepting_requirements=true`）；有候选时再运行 `make task-triage-decide TRIAGE_RECEIPT=<路径> VERDICT=JOIN|NEW … REASON='<理由>'`；随后 `make task-start … TRIAGE_RECEIPT=<路径>` 核验收据，通过后才建分支。三态分流：`JOIN`（建立对应大任务的子任务 `make task-start KIND=child INITIATIVE=feature/ NAME=feature/- TRIAGE_RECEIPT=<路径>`）、`NEW`（建立普通任务或新的大任务 `make task-start [KIND=initiative] NAME=feature/ TRIAGE_RECEIPT=<路径>`）、`DECISION_REQUIRED`（存在候选时的待决策状态；改变范围/优先级的加入由人工决策）。 - 任务启动或恢复后，**第一次项目写操作前**通过 `RECEIPT=/tmp/<本次唯一名称>.json CMD="make precheck" make evidence` 运行一次启动检查并保存 完整脱敏收据（不要求已有任务卡）；按输出完成必读。`SHARED_WORKSPACE_BUSY / SYNC_REQUIRED / REMOTE_UNVERIFIED` 均不得进入写入流程；失败后排除原因再启动，不把缓存远端当最新事实。 -- 新任务运行 `make task-start NAME=feature/ PRECHECK_RECEIPT=/tmp/<本次唯一名称>.json`， +- 新任务运行 `make task-start NAME=feature/ TRIAGE_RECEIPT=<分流收据路径> PRECHECK_RECEIPT=/tmp/<本次唯一名称>.json`， 建立独立 worktree 与任务卡并导入首次收据。恢复已有登记任务在原 worktree 用 `make task-resume PRECHECK_RECEIPT=/tmp/<本次唯一名称>.json` 验证并原样导入收据。 默认 delivery 要求严格 READY；局部恢复接口、启用条件与旧收据处理见 [开发门禁](policy/governance.md#启动与恢复)。任务中途不重复启动检查。 @@ -103,7 +103,7 @@ policy/delivery.md。 任务卡记录主干 R0、父分支及其 SHA、父 PR；子分支命名 `/<父slug>-<子题>`， 不嵌 SHA；合入顺序固定父→子；父合入后子分支须 `make task-sync` 并入最新 main 并把 PR base 改回 main，方可声明可合入（分支保护要求 head 含 origin/main，未同步必被拦）。 -- **验收、请求审核、合入前**各运行一次 `make task-sync`；完成声明的 precheck、task-sync、 +- **验收、请求审核、合入前**各运行一次 `make task-sync`，并运行 `make task-pr-check`（大任务收口用 `FINAL=1`）核验 PR base/head 门禁；完成声明的 precheck、task-sync、 测试三段输出由 `make evidence` 写入任务卡（见「证据与验证门禁」），不手抄。 - **多个分支交付 / CI 调度**：先读 [合入调度](policy/merge-queue.md)，核对采纳状态、协调者、 记录及当前窗口。新模式尚未启用时保留既有同步节点；启用后最终同步至合入核验共用窗口， diff --git a/deps/development-guidelines b/deps/development-guidelines index 2f5b1987..2688fd2b 160000 --- a/deps/development-guidelines +++ b/deps/development-guidelines @@ -1 +1 @@ -Subproject commit 2f5b19872be2a4597838a4131ad75d1be089ee5e +Subproject commit 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb diff --git a/policy/adoption.md b/policy/adoption.md index ba4e1388..0161f932 100644 --- a/policy/adoption.md +++ b/policy/adoption.md @@ -6,7 +6,8 @@ - 过程文档位置：modules/documents（docs/records/） - 版本权威：父仓 gitlink - 批准/生效依据：Dev PR#1（19/19 正负例 + make test）；guidelines PR#1 -- 合入调度通用版本：`0.1.0-draft.11`，实际合入提交 `2f5b19872be2a4597838a4131ad75d1be089ee5e`（Guidelines PR #5）；本仓 gitlink 固定该源码版本。Dev 采用 [manual 串行合入规则](merge-queue.md)：并行开发，轮到后才同步、跑最终 CI 并由智能体合入。该规则不要求先完成全写者审计或第二轮试行，也不宣称自动互斥已经实现。 +- 规范源码版本：`0.1.0-draft.12`，实际合入提交 `2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb`（Guidelines PR #7）；本仓 gitlink（`deps/development-guidelines`）固定该源码版本，版本权威为父仓 gitlink。 +- 合入调度通用版本：`0.1.0-draft.11`，实际合入提交 `2f5b19872be2a4597838a4131ad75d1be089ee5e`（Guidelines PR #5）；draft.12 未修改其合入调度文件（standards/merge-queue.md、templates/merge-queue.md）。Dev 采用 [manual 串行合入规则](merge-queue.md)：并行开发，轮到后才同步、跑最终 CI 并由智能体合入。该规则不要求先完成全写者审计或第二轮试行，也不宣称自动互斥已经实现。 - 过程计划固定：Documents PR #96 实际合入 `129cc3579d9c9e3edfb46c99270d65f3e1dad0a0`，包含既有主干文档及获批 U1–U6 计划；当前进展以任务/PR 记录为准。 | 规范/工作流 | 适用条件与范围 | 执行方式/证据 | @@ -24,6 +25,7 @@ | 同上（zcode 实例） | zcode 客户端写路径 | policy/tool-adaptation-zcode.md：PreToolUse 写守卫；脚本负例与客户端接线分开，客户端 pending-live | | core/baseline.md「规范层级」+ documentation.md「记忆分层/机制化」（draft.9） | 层级效力、记忆权威、经验机制化 | manual：本仓 policy/ 仅收紧不放宽；记忆四层按条文执行（任务卡=任务记忆，documents/records=项目记忆，Dev 仓 AGENTS.md 指针已就位） | | draft.11 合入调度 | active/manual；Dev main 使用 #518 排序和单一最终窗口 | 等待分支不追 main；窗口任务同步一次、固定 HEAD、跑当前必需 CI、由智能体合入并回读结果。Issue 不是原子锁，平台保护仍承担最终准入 | +| draft.12 工程 Agent 执行标准、终态收据 Schema、两级交付与分流（硬边界 8、agent-execution、A8） | 实施、交付、分流与 PR 目标；任务启动前 | active/manual：`make task-triage` 收据为 `make task-start … TRIAGE_RECEIPT=…` 的前置，远端不可核验时 REMOTE_UNVERIFIED（exit 6）并拒绝建分支；child PR 由 `make task-pr-check` 本地核验与 CI `PR base gate` 门禁；AGENT-EXECUTION.md 已声明 `integration` 块。draft.12 Schema 正负例与平台侧负例在项目中的真实运行本次未执行（NOT_RUN），不由本行推断 | ## 项目差异 diff --git a/policy/delivery.md b/policy/delivery.md index d60589e1..6300861e 100644 --- a/policy/delivery.md +++ b/policy/delivery.md @@ -154,17 +154,22 @@ host 可以直接编写并提交的豁免只有 `.task/**`、`docs/superpowers/s 本仓采用两级业务交付模型： - **`main`**：稳定基线，仅接纳已完成并通过最终组合准入的结果。 - **大任务集成分支（initiative）**：从最新 `origin/main` 建立，根目标与即时目标均为 `main`。负责跨单元目标的阶段集成、组合验证与最终交付。合入主干后关闭、归档与回收，不作为长期存在的 develop 分支。 -- **子任务分支（child）**：从所属大任务分支固定 HEAD 建立，即时目标为大任务分支。负责一个有界单元的实施、独立 Review 与局部验证，通过 PR 合入大任务分支。 +- **子任务分支（child）**：从远端所属大任务分支的当前头建立（须等于分流收据核验的 head，`make task-start` 校验），即时目标为大任务分支。负责一个有界单元的实施、独立 Review 与局部验证，通过 PR 合入大任务分支。 - **普通任务分支（standalone）**：无需阶段集成的小需求或独立修复，直接从最新 `origin/main` 建立并向 `main` 交付。 -每次接到新需求，创建分支前必须执行分流检查（`make task-triage`），扫描仓库中进行中且允许接纳需求（`accepting_requirements=true`）的大任务分支： -- `JOIN`：加入唯一匹配的大任务，从大任务分支创建子任务分支交付； -- `NEW`：无接纳中的大任务，建立普通任务或新的大任务； -- `DECISION_REQUIRED`：存在多个候选大任务或加入将改变交付边界/优先级，交由人工决策。 +每个任务卡记录 `root_target` 与 `immediate_target`（子任务为所属大任务分支，其余为 `main`）。`make task-resume`、`make task-sync` 与 `make task-finish` 以 `immediate_target` 为准；`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` 合并大任务分支最新状态，解决文本与语义冲突，完成直接相关测试与独立 Review 后通过 PR 合入大任务分支； -2. **大任务合入主干**：所有必需子任务合入后，关闭需求接纳（`accepting_requirements=false`），同步最新 `origin/main`，执行完整组合验证、独立 Review 与必需 CI，然后合入 `main`。 +1. **子任务合入大任务**：子任务完成时，通过 `make task-sync` 合并大任务分支的远端最新状态（delivery 只认远端头），解决文本与语义冲突，完成直接相关测试与独立 Review 后，以大任务分支为 base 提 PR，并通过 `make task-pr-check` 与 CI `PR base gate`； +2. **大任务合入主干**：所有必需子任务已合入或已延期后，将大任务卡的 `accepting_requirements` 置为 `false`，通过 `make task-sync` 同步最新 `origin/main`，再运行 `make task-pr-check FINAL=1` 核验 `## 子任务登记` 中必需子任务均为「已合入」或「已延期」；随后执行完整组合验证、独立 Review 与必需 CI，以 `main` 为 base 合入。 ## 目标优先、范围控制与问题分流 diff --git a/policy/governance.md b/policy/governance.md index a1f266ec..a1186973 100644 --- a/policy/governance.md +++ b/policy/governance.md @@ -37,10 +37,16 @@ CI 或独立 REPLAY。host 可以直接管理的豁免只有 `.task/**`、`docs/ 从当前检出运行一次启动检查，使用每次唯一、仓外的绝对收据路径： ```bash +make task-triage REQ='<需求>' TRIAGE_RECEIPT=/tmp/my-task-triage.json RECEIPT=/tmp/my-task-precheck.json CMD="make precheck" make evidence -make task-start NAME=feature/my-task PRECHECK_RECEIPT=/tmp/my-task-precheck.json +make task-start NAME=feature/my-task TRIAGE_RECEIPT=/tmp/my-task-triage.json PRECHECK_RECEIPT=/tmp/my-task-precheck.json ``` +分流以远端为准（见 [迭代交付](delivery.md) 的两级分支模型）。有候选时先运行 +`make task-triage-decide TRIAGE_RECEIPT=… VERDICT=JOIN|NEW …` 写入显式决策与理由。子任务使用 +`KIND=child INITIATIVE=feature/<大任务> NAME=feature/<大任务>-<子题>`，收据须为选中该大任务的 JOIN。 +`task-start` 对 DECISION_REQUIRED、过期、远端不可核验（REMOTE_UNVERIFIED，退出码 6）或与所选 initiative 不一致的收据直接拒绝，且不建分支。 + 第一步先捕获原始执行，再创建任务卡；收据保存完整脱敏输出、退出码、执行位置和对象。 第二步核验收据与当前仓库/基线，再创建工作区并导入；不靠事后重跑冒充首次检查。 同一收据不可覆盖。首次检查失败时处理原因，使用新路径重新启动。主干在两步间前进时， @@ -63,12 +69,16 @@ LOCAL_READY 只用于局部恢复；新任务入口始终校验严格 READY， 恢复核验实际 worktree/卡片/分支、R0 祖先关系及源码外原始收据；脏现场、Git 操作、组件漂移和未知远端仍拒绝。 旧收据允许作为历史证据原样导入，不自动成为当前恢复或交付准入；格式继续为 schema 1。 -堆叠任务使用 `PARENT=feature/parent PARENT_PR=<父PR链接>`。父分支须包含本批主干 R0； +堆叠（standalone）任务使用 `PARENT=feature/parent PARENT_PR=<父PR链接>`；子任务改用 `KIND=child`。父分支须包含本批主干 R0； 卡片同时记录父分支、父 SHA 和父 PR。父先合入，子同步最新 main 并改回 main 为 PR base。 +当前 `make task-pr-check` 与 CI `PR base gate` 对 standalone PR 只接受 base 为 `main`，因此堆叠 PR 在 base 改回 `main` 前不能通过这两道门禁。 + +PR 门禁：`make task-pr-check [PR=N] [FINAL=1]` 核验当前分支 PR 的状态、base 与 head（远端为准）。子任务期望 base 为卡片 `immediate_target`（所属大任务分支，且其父仍有开放 PR 指向 `main`）；普通任务与大任务为 `main`。`FINAL=1` 仅用于大任务收口，要求 `accepting_requirements=false` 且必需子任务已合入或已延期。 ## 被测对象 `make task-sync` 在父仓合并后按固定 gitlink 物化未修改组件，并核对实际组件工作树。 +同步目标取卡片 `immediate_target`：子任务为远端所属大任务分支头，其余为 `origin/main`。 组件 feature 分支若与新指针不同，先保留其分支，交给 owner 显式同步并更新组合； 不能用自动 checkout 丢弃组件分支现场。任何失败都保留现场并阻止同步成功声明。 @@ -121,14 +131,14 @@ RECEIPT=/tmp/my-attempt-worktree-check.json CMD="make test-worktree" make eviden 子模块另有登记 worktree 时拒绝回收，避免删除其他检出依赖的 Git 管理目录。 可再生缓存由 owner 按已识别路径单独处置；无法确认用途的文件保留。 -任务合入需以本次成功获取的权威目标验证。合入提交不能证明未提交文件已经落盘。 +任务合入需以本次成功获取的权威目标验证：子任务为其所属大任务分支的远端头，其余为 `origin/main`（即 `immediate_target`）。合入提交不能证明未提交文件已经落盘。 Git 对含子模块的工作区需要显式删除选项时，只有全部现场检查通过才允许该路径； 它不豁免任何脏状态、忽略文件、独有提交/引用或锁检查。普通删除失败不转入强删兜底。 保留无法确认安全的目录和分支，输出下一步处理依据。 子仓 pin 之外的 refs/stash/reflog 历史采取保守拒绝，即使其中部分可能已在远端： owner 须先独立确认其保存与归属，工具不把缓存的远端引用当作唯一数据已经备份的证据。 远端分支删除与本地回收分别报告，失败不能声明两者全部完成。 -回收后由所有者执行 `make task-close` 闭合卡片；回收命令不顺带改写共享主检出。 +回收后由所有者执行 `make task-close` 闭合卡片；回收命令不顺带改写共享主检出。闭合 PR 默认 base 为 `main`；仅 `FOLD=--fold`（随任务分支合入）时 base 为卡片 `immediate_target`。 post-merge 仅提示，不自动调用闭合。`make task-close` 会提交、推送并可能创建 PR， 执行者先按迭代交付规则核对该动作的授权及所选任务，保留未授权的其他任务现场。 回收命令使用待删目录之外的 `RECEIPT` 保存输出，清理结果由后续闭合记录引用。