From 048bbe4a5e2fd6ae0093664a2041a7533ea39fdf Mon Sep 17 00:00:00 2001 From: weichen Date: Mon, 21 Sep 2026 08:08:14 +0000 Subject: [PATCH] docs(workflow): require isolated worktrees for all new agent changes Adopt the approved workflow with explicit dev baselines, serialized candidate integration, scoped validation and safe cleanup. Keep automation work tracked separately from the active policy. --- .../rules/git-workflow-and-environments.mdc | 3 +- .doc/README.md | 1 + .doc/ops/2026-09-13-herdr-agent-roster.md | 4 +- .../ops/2026-09-21-agent-worktree-workflow.md | 85 +++++++++++++++ .doc/ops/CURRENT.md | 6 +- ...26-09-21-agent-workflow-governance-plan.md | 14 +-- ...21-agent-workflow-governance-automation.md | 28 +++++ ...9-21-agent-workflow-governance-adoption.md | 36 +++++++ .doc/ops/templates/session-close-checklist.md | 6 +- .doc/ops/templates/short-term-task.md | 7 +- ...26-09-21-agent-workflow-governance-plan.md | 12 ++- .doc/status/FEATURE-MATRIX.md | 2 +- AGENTS.md | 101 ++++++------------ PROJECT.md | 6 +- 14 files changed, 220 insertions(+), 91 deletions(-) create mode 100644 .doc/ops/2026-09-21-agent-worktree-workflow.md create mode 100644 .doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md create mode 100644 .doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md diff --git a/.cursor/rules/git-workflow-and-environments.mdc b/.cursor/rules/git-workflow-and-environments.mdc index 59d6d4d0..580874ed 100644 --- a/.cursor/rules/git-workflow-and-environments.mdc +++ b/.cursor/rules/git-workflow-and-environments.mdc @@ -12,7 +12,8 @@ alwaysApply: true 1. **开发分支 (`dev`)**: - **合入基线**，不是日常 commit 目标。 - **禁止**在 `dev` 上直接开发提交（含 docs/chore）。 - - 一律从最新 `dev` 检出 `feature/` 或 `fix/`，在 feature 分支上渐进式提交；自测后占集成槽位，`--no-ff` 合回 `dev`，并删除临时子分支（见 [AGENTS.md](../../AGENTS.md) §6.2）。 + - 全部新增改动（含单 Agent、文档）从明确的 `dev` SHA 创建 `.worktrees/` 内的 `feature/*` / `fix/*` 任务；主目录只作集成与运行入口。 + - 创建、候选验证、串行合入、部署和安全清理统一遵守 [AGENTS.md](../../AGENTS.md) §6 与 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md)；不以旧脚本的强制删除替代清理门禁。 2. **测试分支 (`test`)**: - 当 `dev` 积累了一定的功能阶段后，合并至 `test` 分支，创建阶段候选节点 Tag（如 `rc-vX.Y.Z-beta.1`）。 diff --git a/.doc/README.md b/.doc/README.md index 99ed93ef..88f29a22 100644 --- a/.doc/README.md +++ b/.doc/README.md @@ -33,6 +33,7 @@ | 我要… | 读这里 | |--------|--------| +| 创建任务、集成、部署、清理 | [worktree 工作规范](ops/2026-09-21-agent-worktree-workflow.md) | | 当前在做什么 | [ops/CURRENT.md](ops/CURRENT.md) | | 模块完成度 | [status/FEATURE-MATRIX.md](status/FEATURE-MATRIX.md) | | 发布 blocker | [remediation/gap-matrix.md](remediation/gap-matrix.md) | diff --git a/.doc/ops/2026-09-13-herdr-agent-roster.md b/.doc/ops/2026-09-13-herdr-agent-roster.md index da311783..14a523f0 100644 --- a/.doc/ops/2026-09-13-herdr-agent-roster.md +++ b/.doc/ops/2026-09-13-herdr-agent-roster.md @@ -4,7 +4,7 @@ **owner**: `orchestrator_codex` **status**: active -本文只管理工程协作终端，不管理产品运行时智能体。通用分支、worktree、mutex、集成槽、密钥和破坏性操作规则仍以仓库根 [AGENTS.md](../../AGENTS.md) 为准。 +本文只管理工程协作终端，不管理产品运行时智能体。通用分支、worktree、mutex、集成槽、密钥和破坏性操作规则仍以仓库根 [AGENTS.md](../../AGENTS.md) 为准。任务启动、合入和清理同时遵守 [worktree 工作规范](./2026-09-21-agent-worktree-workflow.md)；客户端脚本尚未强制校验的条件由调用者先检查。 ## 1. 身份边界 @@ -69,7 +69,7 @@ Claude 只在 `critical-review` 中作为前排备援；其他 lane 放在最后 | Kimi | `--auto` | Never Ask 模式 | | Cline | `--tui --auto-approve true` | 所有工具自动批准 | -即使客户端不弹确认框，Agent 也不得自行执行：删库/清空数据、强推、删除主干或 worktree、停止 Herdr server、覆盖其他 Agent 未合并改动、泄露密钥、未获用户授权的外部写入。需要新权限时写 handoff/blocker，不把确认框转交给用户逐条点击。 +即使客户端不弹确认框，Agent 也不得自行执行：删库/清空数据、强推、删除主干或未通过清理门禁的 worktree、停止 Herdr server、覆盖其他 Agent 未合并改动、泄露密钥、未获用户授权的外部写入。需要新权限时写 handoff/blocker，不把确认框转交给用户逐条点击。 ## 6. 操作入口 diff --git a/.doc/ops/2026-09-21-agent-worktree-workflow.md b/.doc/ops/2026-09-21-agent-worktree-workflow.md new file mode 100644 index 00000000..d324e745 --- /dev/null +++ b/.doc/ops/2026-09-21-agent-worktree-workflow.md @@ -0,0 +1,85 @@ +# Agent worktree 工作规范 + +**生效日期**：2026-09-21。用户已确认“提交吧，之后按这套执行”。 +**规范来源**：[AGENTS](../../AGENTS.md) §6；[完整方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)。 + +本文件用于创建任务、集成、部署、清理时执行。工作方式立即采纳；自动注册表、队列、服务守卫、OS 权限隔离尚未实现，当前使用下面的显式校验与人工协调。代码文件隔离不等于数据库或运行环境隔离。 + +## 1. 创建任务 + +1. 读取启动链，检查主目录和各任务的 `git status`、分支、`git worktree list --porcelain` 与 CURRENT/任务文。识别其他 Agent 的活跃任务，冲突范围不进入写阶段。 +2. 确认主工作区真实路径：通过 Git worktree 列表和 common-dir 核对，不根据当前脚本父目录推算。已有 `.kilo` 或目录/分支不匹配 worktree 仅盘点，不自动搬动或清理。 +3. 确定任务 ID、允许写路径、mutex 和验证计划；同一写范围只有一个 owner。CURRENT 在各分支内仅作快照，协调者还需交叉核对活跃任务；未实现原子注册表前不宣称已有自动原子认领。 +4. 使用显式本地 dev SHA。远端状态注明已 fetch 或仅本地跟踪快照；不因创建任务在主目录 checkout/pull，也不从 feature 派生无关任务。 + +在已核实的主仓路径执行以下语义；示例 task-id 须替换为本任务唯一标识： + +```bash +repo_main=/home/weichen/projects/Agent-System +base_dev_sha=$(git -C "$repo_main" rev-parse --verify 'dev^{commit}') +git -C "$repo_main" worktree add -b feature/task-id "$repo_main/.worktrees/task-id" "$base_dev_sha" +``` + +先检查目标路径不存在、无 symlink 越界、分支未被使用；保留 `base_dev_sha` 到任务文。主目录需移动 Git 引用时取得下述锁。不要使用尚未修复的 `agent-worktree.sh create/remove`：前者未明确 dev 起点，后者包含强制删除。 + +## 2. 开发、测试与准入 + +- 所有新增代码、配置、规范和文档修改都在任务 worktree 完成；同一任务允许多个提交。 +- `.env`、业务数据、真实用户会话、其他任务的构建产物不复制到新工作区。测试使用专属数据库、目录、端口和测试身份。 +- 每次准入冻结完整 head SHA；记录命令、结果和证据。提交变化或 dev 组合变化后检查受影响的准入是否需重跑。 +- Go、web、迁移、产品 PI 的门禁见完整方案 §6.2。治理规则/纯工程文档检查链接、规则冲突、差异和状态；不启动真实 PI 或重建业务服务。 +- 普通文档与运行模板、提示词分开：`templates/**/*.md`、`configs/**/*.md` 可能改变运行行为。 + +## 3. 串行锁和集成槽位 + +共享 dev 的 Git 更新、部署、写入验收都使用共同 Git 目录下同一个 `agent-control/dev-integration.lock`。锁是本机合作约束；旧客户端可绕过，因此仍核查主目录现场、活跃任务、CURRENT 槽位并保留前后基线。完整注册表、自动队列另行实施。 + +锁应由覆盖整个操作的父进程持有，不是一个命令拿锁后退出再执行下一条： + +```bash +common_dir=$(git rev-parse --path-format=absolute --git-common-dir) +mkdir -p "$common_dir/agent-control" +exec 9>"$common_dir/agent-control/dev-integration.lock" +flock -n 9 || exit 1 +# 在本进程及受控子进程中执行基线核对、候选准入、dev 更新与所需部署/验收。 +# 同时记录 owner、task、phase、原 dev、候选 SHA 和恢复状态。 +# 操作完毕或形成失败交接后退出本进程，关闭 fd 9。 +``` + +CURRENT holder/phase 由集成任务分支记录并在合入时成为快照，不能为占槽去改动另一个活跃任务的脏工作区。实时 owner/phase 可写在 common-dir 的 `agent-control/active-operation.json`，但该文件不是锁。结束保留结果再释放；发现前次非终态记录，先核查恢复，不能只因锁空闲就重复执行。 + +共享 dev 的长 E2E 持锁至结束；独立固定环境才允许释放 dev。资源不足则排队，不默认起多套共享 Compose 或终止产品任务。 + +## 4. 集成候选与部署 + +1. 锁定 dev 基线 D 和任务 head T；任务工作树干净且准入证据有效。 +2. 从 D 建 `.worktrees/` 下的 `feature/integrate-*`，把 T 以 `--no-ff` 合成候选 M。业务冲突退回 owner 修复；集成者不在主目录改代码解冲突。 +3. 在 M 验证相应门禁。dev 仍为 D、任务仍为 T 才可在干净 dev 工作区 `merge --ff-only M`；变化则重建候选。dev 历史保留该 no-ff 节点，不再重做另一份未测试合并。 +4. 纯工程规范/文档标 `deployment=not_required`。运行内容变化则从已合入版本构建/应用确定制品，核验实际镜像、schema、`/health`、`/ready` 和相关业务链路。 +5. 当前 `candidate-images-build.sh --commit` 未保证构建树等于参数，修复前调用者必须确保干净树、HEAD 与参数完全一致，记录证据；不能仅凭标签声明准确版本。 +6. `restart` 仅重启现有容器。worktree 不调用共享 `env-service.sh` 写命令；共享服务只由主目录下获授权的持锁集成者操作。失败记录 merged/deployed/accepted 的实际状态，兼容性不明时不自动恢复数据库。 + +### 主目录旧任务尚未结束时 + +保护旧任务现场，不能为了落实新规范先强切 dev。仅**纯工程规范/文档**允许过渡例外：dev 未在其他 worktree 检出时，持锁将 dev 检出到 `.worktrees/agent-governance-dev-integration`，只接收已验证文档候选，不运行服务、不合入未验收业务代码。登记临时目录、原因和接管人，当前根目录继续保持原任务分支。 + +旧任务 owner 保存/提交成果、确认主目录干净后：先确认临时 dev 工作区干净且没有 Agent/进程使用，普通 remove 该临时 worktree，释放 dev 检出占用，再由主目录切回 dev。不能用 `--ignore-other-worktrees` 或强删抢占。此前新任务直接从 dev ref 创建自己的 worktree，读取 dev 中已采纳的规范；旧任务收口时也按新流程集成。 + +## 5. 安全清理 + +清理在待删除目录外执行，依次核查： + +1. worktree 实际路径、分支与任务登记一致；无越界/保护项；无 merge/rebase 中间状态。 +2. `git merge-base --is-ancestor dev` 成功；冻结后未新增未合入提交。 +3. 所需部署与验收通过或 not_required；报告、截图和唯一日志已归档。 +4. 检查 tracked、untracked **及 ignored 文件**；只允许丢弃确认可再生的缓存，不因 `git status --short` 为空就认定没有证据文件。 +5. Agent/测试进程已退出、无进程 cwd/其他任务依赖该目录。 +6. 普通 `git worktree remove `；分支用 `git branch -d `。若非 dev 当前检出导致 -d 拒绝，即使祖先检查通过也保留到 dev 可用时清理，不换成 -D。 + +失败只标 cleanup_pending，保留数据。禁止强制删除、按年龄批量删除或把 worktree 清理扩展为 data/数据库/容器卷清理。Push 仅在用户明确要求时执行，并与本地提交/合入分开报告。 + +## 6. 执行状态 + +- 已采纳：强制任务 worktree、明确 dev 基线、主目录保护、串行集成/部署、按范围验证、条件清理。 +- 可立即执行：本规范的原生 Git、人工范围认领、本机 flock、精确候选检查。 +- 尚待工程实现：自动登记与排队、脚本强制 guard、安全 helper、部署身份闭环、PI 镜像交付、故障自动恢复和 OS 沙箱。见 [自动化实施任务](./long-term/2026-09-21-agent-workflow-governance-automation.md)。 diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 6882b230..9f7e73ea 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -13,6 +13,8 @@ | owner | task | branch | worktree | mutex | status | |-------|------|--------|----------|-------|--------| +| Cursor | 2026-09-21-intent-workflow-scoping | fix/intent-workflow-scoping-2026-09-21 | -（迁移前旧任务，保留现场） | intent+web+docgov | in_progress | +| Codex | 2026-09-21-agent-workflow-governance-adoption | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance | in_progress | | Codex | 2026-09-21-agent-workflow-governance-plan | feature/agent-workflow-governance-plan | .worktrees/feature-agent-workflow-governance-plan | agent-workflow-governance-plan | done | | Cursor | 2026-09-21-workflow-doc-key-unification | fix/workflow-doc-key-unification-2026-09-21 | .worktrees/fix-workflow-doc-key-unification-2026-09-21 | docgov+web | done | | Cursor | 2026-09-21-dev-deep-test-four-issues | fix/dev-deep-test-four-issues-2026-09-21 | - | web+intent+taskrun | done | @@ -178,7 +180,7 @@ | holder | phase | since | scope | queue | |--------|-------|-------|-------|-------| -| - | idle | 2026-09-21 | 文档键统一已合入并重建 dev；`/health` schema_version=60；项目 6579 为 7 条 bd_* | - | +| Codex | merging | 2026-09-21 | Agent worktree 规范采纳；仅文档候选集成，主目录旧任务现场保留；deployment=not_required | - | **phase**: `idle` | `merging` | `smoke` | `e2e` @@ -196,7 +198,7 @@ | 类型 | 路径 | |------|------| -| 2026-09-21 Agent worktree 治理（仅方案） | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md) · [调研](./research/2026-09-21-agent-workflow-governance-research.md) · [交接](./handoffs/2026-09-21-agent-workflow-governance-plan.md)；未实施、未合入 dev | +| 2026-09-21 Agent worktree 工作规范 | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md) · [调研](./research/2026-09-21-agent-workflow-governance-research.md) · [交接](./handoffs/2026-09-21-agent-workflow-governance-plan.md)；规范已采纳，自动化另列 planned | | 2026-09-20 rdev 种子 | [short-term](./short-term/2026-09-20-rdev-seed-hotfix.md) · [报告](../test-reports/2026-09-20-rdev-seed-hotfix-test-report.md) | | 2026-09-20 模块解耦 | [审计](../audit/2026-09-20-module-coupling-audit.md) · [规范](../system-design/2026-09-20-module-development-standards.md) · [批次 A–G](../remediation/2026-09-20-module-decoupling-batch-plan.md) · [short-term](./short-term/2026-09-20-module-decoupling-spec-audit.md) | | 文档总地图 | [../README.md](../README.md) | diff --git a/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md index 19622af9..7d645b57 100644 --- a/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md +++ b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md @@ -1,12 +1,12 @@ --- -title: "Agent worktree 并行治理方案待审核" +title: "Agent worktree 并行治理规范采纳与迁移交接" created: 2026-09-21 from: Codex to: user-and-next-agent status: open --- -# 交接：Agent worktree 并行治理方案待审核 +# 交接：Agent worktree 并行治理规范采纳与迁移交接 ## 已完成 @@ -16,26 +16,26 @@ status: open ## 下一步 -用户审核方案后，从最新 dev 按 W0–W4 逐步实施；尚未授权执行治理改造、旧 worktree 清理或服务更新。本次 worktree 留作审核，不能自动清理。 +用户已确认采纳并提交。生效规则见 [worktree 工作规范](../2026-09-21-agent-worktree-workflow.md)；自动化仍按 [W0–W4 实施任务](../long-term/2026-09-21-agent-workflow-governance-automation.md) 追踪，不能当作已经实现。此次仅集成规范文档，不迁移旧任务或重建服务。 ## 认领 / 槽位 | 项 | 值 | |---|---| | 研究 mutex | 已在本 worktree CURRENT 标记 done | -| 共享集成槽位 | 未占用，未修改主目录 CURRENT | +| 共享集成槽位 | 本任务分支 CURRENT 登记文档集成；实际操作持 common-dir 下 dev-integration.lock，主目录 CURRENT 保留 | | branch | feature/agent-workflow-governance-plan | | worktree | .worktrees/feature-agent-workflow-governance-plan | | 起点 | 本地 dev@15b8a4a8 | -| 合入 / push | 均未执行；方案只在本地任务分支 | +| 合入 / push | 本次按已验证候选合入本地 dev；未 push，最终结果见规范采纳验收报告 | ## 验证及边界 - 仅文档差异、链接和状态检查；未运行 Go/前端测试、迁移或真实 PI 操作，不作产品验收声明。 - 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。 -- 当前没有机器协调入口，分支 CURRENT 不等于全局实时认领。本任务只读代码，写入独立文档文件。 +- 当前没有自动任务协调器，分支 CURRENT 不等于全局实时认领。此次只有人工明确范围和本机 flock，不宣称自动队列或全局硬隔离已实现。 - 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。 -- 后续合入 CURRENT 要保留当时其他任务和槽位状态；本次不合入是因为仅请求研究方案且主目录正有进行中任务，不是已经完成的代码交付。 +- 主目录仍是旧任务分支；dev 暂由 `.worktrees/agent-governance-dev-integration` 检出以安全集成文档。旧任务 owner 保存成果、确认主目录干净后，先安全移除临时 dev worktree，再在主目录切回 dev；不得强抢 dev 检出。 ## 相关链接 diff --git a/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md b/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md new file mode 100644 index 00000000..35412922 --- /dev/null +++ b/.doc/ops/long-term/2026-09-21-agent-workflow-governance-automation.md @@ -0,0 +1,28 @@ +--- +title: "Agent worktree 治理自动化 W0–W4" +status: planned +created: 2026-09-21 +updated: 2026-09-21 +owner: next-implementation-owner +mutex: agent-workflow-governance +--- + +# Agent worktree 治理自动化 W0–W4 + +工作方式已由用户采纳，本任务跟踪尚未实现的工程能力。规则生效不等于脚本或权限隔离已完成。 + +## 按依赖实施 + +1. W0：接续主目录旧任务，核查运行挂载与热补丁，安全回到 dev。 +2. W1：修 worktree 创建起点、主仓定位、安全 remove、路径/分支校验和构建忽略。 +3. W2：原子认领、资源 mutex、集成队列、env-service guard、operation 恢复。 +4. W3：候选测试对应实际 dev/运行制品，PI 源码镜像交付、就绪/业务验收和恢复。 +5. W4：证据归档、条件自动清理、客户端薄入口与状态投影。 + +每个实施任务从当时 dev 在 `.worktrees/` 开工；按 [完整方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) §11 验收。W5 OS/跨机能力按实际需要另立任务。 + +## 关闭条件 + +- 两个独立任务完成并行开发、串行交付、运行验收和安全清理。 +- 错误起点、并发抢占、危险清理、部署失败/超时/崩溃均有拒绝或恢复证据。 +- 自动化机制确实落地后再将对应 FEATURE-MATRIX 能力升 done。 diff --git a/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md b/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md new file mode 100644 index 00000000..2428761f --- /dev/null +++ b/.doc/ops/short-term/2026-09-21-agent-workflow-governance-adoption.md @@ -0,0 +1,36 @@ +--- +title: "采纳 Agent worktree 工作规范" +status: in_progress +created: 2026-09-21 +updated: 2026-09-21 +owner: Codex +branch: feature/agent-workflow-governance-plan +worktree: .worktrees/feature-agent-workflow-governance-plan +mutex: agent-workflow-governance +--- + +# 采纳 Agent worktree 工作规范 + +## 授权与范围 + +用户于 2026-09-21 确认“提交吧，之后按这套执行”。延续原治理任务，在原 dev 派生的独立 worktree 内将方案采纳为生效规则，提交并合入本地 dev。仅修改规范、模板和治理记录。 + +本次不将 W1–W4 的自动化开发宣称已完成；它们保留在实施任务中。主目录仍有其他任务未提交改动，使用临时集成 worktree 合入纯文档，不迁移原任务、不改变业务运行态、不 push。 + +## 步骤 + +1. [x] 核对主目录现场、原方案提交与集成槽位。 +2. [ ] 同步 AGENTS、PROJECT、Cursor 规则、操作规范与模板。 +3. [ ] 文档检查、提交、独立 worktree 合入 dev。 +4. [ ] 更新验收/交接及清理状态。 + +## 验收 + +- [ ] 单 Agent 主目录开发例外已移除，生效规则可从启动链发现。 +- [ ] 创建明确来自 dev；测试提交、共享服务串行、部署及安全清理条件可执行。 +- [ ] 自动化能力保持 planned；主目录其他任务未提交改动不被纳入提交。 +- [ ] 本地 dev 含本次规范提交；未 push，未重建服务。 + +## 相关链接 + +- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md) diff --git a/.doc/ops/templates/session-close-checklist.md b/.doc/ops/templates/session-close-checklist.md index ae2cb032..4ecfd608 100644 --- a/.doc/ops/templates/session-close-checklist.md +++ b/.doc/ops/templates/session-close-checklist.md @@ -5,14 +5,14 @@ ## 认领与集成 - [ ] CURRENT「并行认领」行 status 已更新（done 或移除） -- [ ] 若曾占集成槽位：smoke 已完成，holder=idle，queue 已通知 +- [ ] 若曾占集成槽位：所需 smoke/E2E 已完成（或失败恢复交接），锁已释放、holder=idle；文档可记 deployment=not_required - [ ] mutex 无遗留 in_progress（除明确 handoff 交接项） ## 代码与分支 - [ ] 确认未在 `dev` / `test` / `main` 上直接 commit（工作均在 `feature/*` 或 `fix/*`） -- [ ] 已占集成槽位并 `merge --no-ff` 合回 `dev`（或 handoff 说明未 merge 原因） -- [ ] feature/fix 分支已删除或 worktree 已 remove（若已合入） +- [ ] 已持锁/占槽验证合并候选并合回 `dev`（或 handoff 说明未 merge 原因） +- [ ] 已按 [清理门禁](../2026-09-21-agent-worktree-workflow.md) 核对祖先、部署/验收、文件与进程；普通 remove/-d 已完成，或记录保留原因（不强删） - [ ] 无未 push 的关键提交（若用户要求同步远端） ## 文档 diff --git a/.doc/ops/templates/short-term-task.md b/.doc/ops/templates/short-term-task.md index a1d7dbff..930e8cfe 100644 --- a/.doc/ops/templates/short-term-task.md +++ b/.doc/ops/templates/short-term-task.md @@ -5,7 +5,12 @@ created: YYYY-MM-DD updated: YYYY-MM-DD owner: agent branch: feature/ # 必填：feature/* 或 fix/*；禁止 dev / test / main -worktree: "-" +worktree: .worktrees/ +base_dev_sha: <创建时的完整 dev SHA> +write_scope: [<允许修改的路径>] +head_sha: <准入时冻结的提交> +deployment: pending # pending | passed | failed | not_required +cleanup: pending # pending | done | retained-with-reason mutex: --- diff --git a/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md index 4b93c7e1..3b81c15f 100644 --- a/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md +++ b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md @@ -8,6 +8,8 @@ owner: Codex # Agent 工作规范与 worktree 并行开发治理方案 +> **2026-09-21 已采纳**：用户确认“提交吧，之后按这套执行”。生效工作规范见 [执行入口](../ops/2026-09-21-agent-worktree-workflow.md)。本文 status=planned 追踪尚未实现的自动化 W0–W4，不代表仍待审核；采纳与自动化验收分开记录。 + ## 1. 建议与目标 采用“主目录作为 dev 集成与运行入口，所有任务在 `.worktrees/` 内开发，自动检查后进入串行集成队列”的方案。单 Agent 也遵守。一个任务对应一个分支和一个 worktree，可包含多个原子提交；不是每改一个文件就新建分支。 @@ -20,7 +22,7 @@ owner: Codex 4. “合入”“部署成功”“业务验收通过”“已清理”“已推送”是不同事实，分别记录。 5. 普通文档不改变运行内容，无需每次重建 dev；部署范围应按实际差异判定。 -本次是待审核方案，未修改生效规则或脚本，未授权迁移既有任务、服务重建、批量清理及 test/main 晋升。 +原研究阶段只形成方案；现已采纳工作规范。此次规范提交不包含自动化脚本开发、既有任务迁移、服务重建、批量清理或 test/main 晋升。 现状依据：[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md)。目标是降低误改和并行竞争，不重建个人工程中控台，不为每项任务默认起全套环境。 @@ -208,7 +210,7 @@ flowchart LR push 与本地完成分开：用户未要求时不自动 push；已要求时必须成功并验证对应远端引用后才关闭同步项。没有 push 的合入仍需明确报告本地状态。清理只移除已安全保存的任务目录，不清理 `data`、共享卷或其他 Agent 目录。 -旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。本次研究 worktree 也因方案尚待审核而保留。 +旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。原研究 worktree 现可在规范合入且清理门禁满足后移除；临时 dev 集成 worktree 如需保留，必须交接主目录恢复条件。 ## 9. 规则与工具落点（拟实现） @@ -263,11 +265,11 @@ W1/W2 是最小可用安全闭环，W3/W4 达到用户完整目标。不要在 W 成功指标：新任务在主目录直接开发次数为 0；共享服务并发变更为 0；每次交付有可追溯收据；不产生强制删除；结束任务无无主 worktree。再收集候选重跑率、集成等待时间、构建时间和残留目录数，决定是否值得增加独立预览环境。 -## 12. 审核建议与待实施边界 +## 12. 已采纳方向与待实施边界 -建议批准 W0–W4 作为整体方向，先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。 +已采纳 W0–W4 方向；实施次序为先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。 -最值得审核的是两个策略：是否接受主目录只接收已测试合并节点的快进更新，以及是否将 dev PI 源码热挂载改为镜像交付。两者均推荐；实施前需接续现有主目录任务并核查热补丁，不能直接迁移现场。 +已采纳主目录接收已测试合并节点的流程，以及 dev PI 源码改为镜像交付的方向。后者尚未实施，切换前需接续现有主目录任务并核查热补丁，不能直接迁移现场。 尚未验证：远端分支保护、实际远端最新 dev、主机可承载的最佳并行数、每个客户端的沙箱边界。它们不阻碍本地方案成立，但不得据此承诺绝对禁止所有绕过或无限并行。 diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index 5f9cb682..e2c7a8e4 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -49,7 +49,7 @@ | 模块 | 声明范围 | 状态 | 发布关系 | 证据 | 剩余工作 / 关闭条件 | mutex | |------|----------|------|----------|------|---------------------|-------| -| Agent worktree 并行治理 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | planned | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md) | 仅完成研究与方案；规则、脚本、机器锁和试点均未实施，不能宣称已强制隔离 | `agent-workflow-governance` | +| Agent worktree 治理自动化 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | planned | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md) | [工作规范](../ops/2026-09-21-agent-worktree-workflow.md) 已采纳；人工显式校验立即执行。自动注册表、队列、脚本守卫、部署闭环和权限隔离仍待[实施](../ops/long-term/2026-09-21-agent-workflow-governance-automation.md)，不能宣称自动强制已完成 | `agent-workflow-governance` | | 意图识别 L1 | 18 类 Intent、三分支消解、写/只读分流、双标签 `DOC_BUSY`、intent 纯依赖边界 | done | non_blocker | [intent-recognition](../system-design/intent-recognition/)；[审计](../audit/2026-09-13-conversation-intent-runtime-state.md)；[报告](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/live.json)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U3](../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) | **边界 before**：含 U9–U12 叙事混入 → **after**：U9–U12 迁至「多意图扩面」行。关闭：纯依赖边界回归即重开 | `intent` | | 多意图持久计划（U1–U8 基线） | app/intentflow 生命周期、HITL、默认 `legacy`、U1–U8 代码与安全基线 | partial | non_blocker（默认 legacy） | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U8](../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md)；[Wave2 真 PI](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | legacy 有限只读多意图仍默认启用；新持久计划生产组合根仍使用 Fake query owner，confirm 后缺可靠调度，typed 参数/目标版本不足。原 U1–U8 测试证据保留，但不足以证明升 `auto_read/confirm` 可用。关闭条件见[整改方案](../remediation/2026-09-20-capability-enablement-impact-plan.md) Foundation 1 与 Track I | `intent-plan` | | 多意图扩面（U9–U12） | U9 LLM 分段实验；U10 mutate；U11 docgov；U12 workflow/run-control | partial | deferred_enhancement | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[脚手架](../test-reports/2026-09-16-pu8-u9-u12-flags-test-report.md)；[U9](../test-reports/2026-09-17-w4-u9-segment-test-report.md)；[U10](../test-reports/2026-09-17-w4-u10-mutate-test-report.md)；[U11](../test-reports/2026-09-17-w4-u11-docgov-test-report.md)；[U12](../test-reports/2026-09-17-w4-u12-run-control-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | U9 proposer 已实现和注入但未进入生产聊天分段调用；提议请求已带 reasoning profile。U10–U12 当前为 dry-run/validated-only adapter。历史直接调用/PI 测试继续有效，不代表 live 接线。逐域实现和验收，禁止以 `full` 一次放量 | `intent-plan` | diff --git a/AGENTS.md b/AGENTS.md index 0fdaafa6..e75af5c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,9 @@ 3. **[`.doc/README.md`](./.doc/README.md)**（文档 taxonomy） 4. **[`.doc/ops/CURRENT.md`](./.doc/ops/CURRENT.md)**（焦点、并行认领、集成槽位） 5. **[`.doc/status/FEATURE-MATRIX.md`](./.doc/status/FEATURE-MATRIX.md)**（模块完成度） -6. 相关 **short-term** / **handoff** / **audit** / **remediation** -7. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md) +6. 创建任务、合入、部署、清理前：读 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)（含自动化未落地时的操作方法） +7. 相关 **short-term** / **handoff** / **audit** / **remediation** +8. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md) **未读完不得开始改代码**（紧急热修除外，事后必须在 24h 内补文档）。 @@ -90,79 +91,47 @@ ## 6. 多 Agent 协作 -### 6.1 并行认领（编码阶段） +### 6.1 任务与主目录边界 -任务开始前在 CURRENT「并行认领」表登记： +- 主目录作为 `dev` 集成与运行入口；**所有新增开发、配置、规范和文档改动，包括单 Agent 任务，均在 `.worktrees/` 的任务 worktree 内完成**。 +- 主目录跟踪文件只通过受控 Git 集成更新，不作日常编辑；`.git`、任务 worktree、服务运行数据和获授权的运维配置属于明确例外。禁止递归 chmod 整个主目录。 +- 一个任务一个 `feature/` / `fix/` 分支、一个 worktree，可包含多个原子提交。既有任务延续原任务分支；无关新任务重新从 dev 创建。 +- 已经在主目录运行的旧任务保留现场，由所有者完成或交接后迁移；其他 Agent 不得擅自 checkout、stash、reset、移动其未提交文件。 +- 任务必须登记 owner、branch、worktree、base_dev_sha、允许写路径、mutex、验证计划。CURRENT 保留认领快照；各 worktree 的 CURRENT 不构成原子锁。 +- 同一 mutex 或重叠写路径同时只允许一个写者；公共 lockfile、路由、迁移号单独认领。冲突时排队或写 handoff，不覆盖他人工作。 -| 字段 | 说明 | -|------|------| -| owner | 工具 + 标识 | -| task | short-term 文件名 | -| branch | `feature/*` 或 `fix/*` | -| worktree | 路径或 `-` | -| mutex | 模块名（见 FEATURE-MATRIX） | -| status | `in_progress` / `blocked` / `done` | +### 6.2 创建与开发 -**同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。 +1. 先核对仓库、主工作区、当前分支、工作树状态、已有 worktree 与任务认领。 +2. 由协调者管理 dev 同步；开发 Agent 不在共享主目录切分支或直接 pull。记录本地 dev 的确切 SHA 与远端同步状态，分叉时保留现场。 +3. 显式从该 `base_dev_sha` 创建 `.worktrees/`，不能省略起点，也不从另一 feature 分支开新任务。 +4. 在任务 worktree 完成开发、原子提交、相应测试和文档；不复制主目录 `.env`、业务 data 或其他任务的可变产物。 +5. 提交集成前冻结 head SHA；变更超出允许范围时先重新认领，提交变化后原测试/审查准入失效。 -### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支） +当前脚本尚有错误起点和强制删除缺口，**修复验收前不用 `agent-worktree.sh create/remove`**；按 [操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md) 使用带显式起点的 Git 命令和非强制清理。 -> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。 -> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。 +### 6.3 串行集成与环境验收 -**任务开始（先于改码）：** +- 编码和隔离测试可并行；dev 合入、共享服务变更和共享环境验收必须串行，记录 CURRENT 槽位和共同 Git 目录中的执行锁。完整机器队列未实现时按操作规范手工持锁，不以 Markdown 的 idle 作为唯一准入。 +- 推荐在 `.worktrees/` 内的临时 `feature/integrate-*` 上从 dev 基线生成 `--no-ff` 合并候选，验证该提交；锁内确认 dev 基线未变后，将干净 dev 工作区 `--ff-only` 推进至同一候选。dev 变化则重新组合并验证。 +- 业务冲突返回任务 worktree 解决；dev/test/main 禁止直接开发提交。迁移期间主目录被旧任务占用时，纯规范/文档可使用登记的临时 dev 集成 worktree，禁止由此操作共享服务；详见操作规范的收口条件。 +- Go 变更执行 PROJECT 的 Go/架构及相关 PG 检查；web 变更执行前端检查与受影响浏览器验证；涉及产品 PI 的业务交付执行真实链路验收。纯工程规范/文档只做对应一致性检查，不为形式重建服务。 +- 影响运行内容的改动合入后，持有环境槽位更新 dev，核查实际制品、`/health`、`/ready` 和相关业务行为。`restart` 不证明新代码部署；模板/提示词 Markdown 不能按普通文档跳过部署。 +- 使用共享 dev 的长 E2E 持有环境槽位直到结束；仅在切换到独立固定环境后才可提前释放。失败或未知结果先核对运行态、记录恢复，不能冒充 PASS 或盲目重复执行。 +- CURRENT 槽位字段仍为 `holder | phase | since | scope | queue`；生产/test 晋升独立授权，dev 任务不得顺手操作 `all`。 -1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端） -2. 从 `dev` 创建分支：`feature/`（新能力）或 `fix/`（缺陷）；slug 与 short-term 任务名对齐 -3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/`（worktree 内编码） -4. 单 Agent：可在主仓 `git checkout -b feature/`，**不得**留在 `dev` 上改码提交 +### 6.4 收口与清理 -**合回 dev（占集成槽位，见 §6.3）：** +- 分别报告已提交、已合入 dev、已部署、已验收、已清理、已推送；文档合入可注明 `deployment=not_required`。 +- 清理前核对：任务提交是 dev 的祖先、所需验收通过、证据持久化、无 tracked/untracked/唯一 ignored 遗留文件、无 Agent/进程或其他任务使用、路径与分支一致且不属保护项。 +- 使用普通 `git worktree remove` 和 `git branch -d`；拒绝时保留并记录 cleanup_pending，不升级到 `--force` / `-D`，不批量清空 `.worktrees`。 +- 未合入或待恢复任务保留 worktree 与 handoff；部署失败按兼容性恢复/前滚，不自动回滚数据库或硬重置 dev。 -```bash -git checkout dev -git merge --no-ff feature/ -m "merge: feature/" -# 冒烟通过后 -git branch -d feature/ # 或 agent-worktree.sh remove -``` +### 6.5 共享文档 -| 允许 | 禁止 | -|------|------| -| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit | -| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` | -| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 | -| 连主仓已起服务 `:8080` | 各 worktree 各起 docker | - -脚本：`./scripts/agent-worktree.sh create|list|remove` - -### 6.3 集成槽位（合入 dev + 容器验证） - -> **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。** - -Agent A 占槽 merge + 冒烟期间，Agent B **不得** merge dev 或动共享 docker；B 可继续 worktree 编码，并写入 queue 等待。 - -CURRENT「集成槽位」：`holder` | `phase`（idle/merging/smoke/e2e）| `since` | `scope` | `queue` - -**释放**：冒烟 PASS（或 FAIL+handoff）+ 文档同步 + holder=idle。长 E2E 优先 smoke 释放，E2E 结果后补报告。 - -**默认冒烟（holder 在主仓执行）**： - -```bash -go vet ./... -go test -short ./... -./scripts/env-service.sh dev rebuild -curl -sf http://127.0.0.1:8080/health -``` - -### 6.4 共享文档 - -`CURRENT.md` / `FEATURE-MATRIX.md` 由认领方或合并者更新；冲突时保留双方认领行再收敛。 - -### 6.5 协作纪律 - -- **单一焦点**：CURRENT 只列 1–3 个焦点 -- **不覆盖**：发现冲突先 handoff/blocker -- **交接优先**：口头转述不可代替 handoff 文件 +- CURRENT 只列 1–3 个焦点；机器状态与 Git 现场优先，CURRENT 是带日期的协作快照。 +- 实现者在任务文记录状态和 FEATURE-MATRIX 变更意图，由集成者串行汇总；保留其他任务、槽位与历史证据。 +- 规范生效与自动化实现分别记录；机器锁服务、队列、脚本守卫和权限沙箱未验收前不得宣称已自动强制。 ### 6.6 Herdr 角色、自动审批与备援 @@ -190,7 +159,7 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务） - 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci` - **原子提交**：一个逻辑变更一批；提交发生在 `feature/*` 或 `fix/*` 上，不在三大主干 -- **合回 dev**：占集成槽位后 `merge --no-ff`（见 §6.2、§6.3） +- **合回 dev**：占槽验证 `--no-ff` 合并候选，dev 接收已验证节点（见 §6.3）；只在任务分支直接开发提交 - **晋升**：`dev` → `test`（rc tag）→ `main`（release tag）；仅在规划的环境合并时动 `test`/`main` - **用户未要求**：不擅自 push - **用户已要求 push/同步远端**：必须自主完成 diff --git a/PROJECT.md b/PROJECT.md index 33594798..ebaab179 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -53,7 +53,7 @@ **红线**：知识库共享；对话与业务 DB **严格隔离**，禁止跨环境读写。 -**分支红线**：三大主干（`dev`/`test`/`main`）禁止直接开发 commit；一律从 `dev` 开 `feature/*` 或 `fix/*`，合回 `dev` 须占集成槽位（见 [AGENTS.md](./AGENTS.md) §6）。 +**开发入口**：所有新增改动均从明确的 `dev` 提交创建 `feature/*` / `fix/*`，在 `.worktrees/` 内完成；主目录保留给集成与运行。任务创建、串行集成、部署和清理遵守 [AGENTS.md](./AGENTS.md) §6 及 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)。 --- @@ -115,7 +115,7 @@ cd web && npm test && npm run build ## 8. 测试与验收铁律 -- 开发可用 stub；**交付前验收**必须真实 PI Agent + MiniMax-M2.7-highspeed 全链路 +- 涉及产品 Agent/工作流的业务交付：开发可用 stub，**交付前验收**必须真实产品 PI Agent Runner + MiniMax-M2.7-highspeed 全链路。纯工程规范/文档变更执行对应一致性检查，不调用产品 PI - 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard - 禁止 stub 输出冒充最终验收数据 @@ -141,4 +141,4 @@ cd web && npm test && npm run build ## 11. 语言与提交 - 对用户：**简体中文** -- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，合回 `dev` 用 `--no-ff`（禁止在三大主干直接 commit） +- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，集成遵守 AGENTS §6.3 的已验证合并候选流程（禁止在三大主干直接开发 commit）