docs(workflow): plan isolated agent development and serialized integration

2026-09-21 07:59:40 +00:00
parent 15b8a4a87d
commit 6e28c57245
6 changed files with 429 additions and 0 deletions
@@ -0,0 +1,48 @@
+---
+title: "Agent 工作规范与 worktree 并行治理方案"
+status: done
+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-plan
+---
+
+# Agent 工作规范与 worktree 并行治理方案
+
+## 目标
+
+基于当前仓库规范、脚本和现场，评估主目录保护、强制 worktree、串行集成与清理机制，交付可审核方案。
+
+## 范围
+
+- 只读检查 Git、脚本、Compose、测试入口和协作记录。
+- 形成调研、治理方案及交接文档；仅在本任务 worktree 写文档。
+
+## 非目标
+
+- 不修改业务代码、Agent 规则或运维脚本；不切换主目录分支、不干预其他任务、不重建服务、不清理既有 worktree、不 push。
+
+## 步骤
+
+1. [x] 阅读启动链并盘点现场。
+2. [x] 显式从本地 dev@15b8a4a8 创建独立 worktree。
+3. [x] 完成机制核验、方案和边界审查。
+4. [x] 写交接并核查文档差异。
+
+## 验收标准
+
+- [x] 有现状证据、方案比较、操作流程、并行边界、恢复与验收标准。
+- [x] 区分已存在机制与拟实现机制；不将方案宣称为已落地。
+
+## 证据 / 备注
+
+初始主目录为 fix/intent-workflow-scoping-2026-09-21，有其他任务未提交变更。为保护现场，未执行 checkout dev / pull；从显式本地 dev 创建 worktree。origin/dev...dev 为 0/309，仅为本地远端跟踪引用快照，本轮未 fetch。认领仅登记本 worktree 的 CURRENT，尚无跨 worktree 实时协调入口；本任务只读代码且使用独立文档路径。
+
+## 交付
+
+- [调研](../../ops/research/2026-09-21-agent-workflow-governance-research.md)
+- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)
+- [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)
+- 仅文档核验，未执行产品测试；治理能力在 FEATURE-MATRIX 保持 planned。
@@ -13,6 +13,7 @@

 | owner | task | branch | worktree | mutex | status |
 |-------|------|--------|----------|-------|--------|
+| 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 |
 | Cursor | 2026-09-21-trace-panel-to-chat | feature/trace-panel-to-chat-2026-09-21 | - | trace-impact+web | done |
@@ -195,6 +196,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-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) |
@@ -0,0 +1,43 @@
+---
+title: "Agent worktree 并行治理方案待审核"
+created: 2026-09-21
+from: Codex
+to: user-and-next-agent
+status: open
+---
+
+# 交接：Agent worktree 并行治理方案待审核
+
+## 已完成
+
+- 当前规范、worktree/服务/制品脚本、Compose、CI 和实际运行挂载的只读核查。
+- [调研](../research/2026-09-21-agent-workflow-governance-research.md) 与 [完整方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)，含现状差距、五阶段实施、恢复与十四项验收。
+- 本分支 CURRENT 登记已结束；FEATURE-MATRIX 新能力保持 planned；研究任务归档。
+
+## 下一步
+
+用户审核方案后，从最新 dev 按 W0–W4 逐步实施；尚未授权执行治理改造、旧 worktree 清理或服务更新。本次 worktree 留作审核，不能自动清理。
+
+## 认领 / 槽位
+
+| 项 | 值 |
+|---|---|
+| 研究 mutex | 已在本 worktree CURRENT 标记 done |
+| 共享集成槽位 | 未占用，未修改主目录 CURRENT |
+| branch | feature/agent-workflow-governance-plan |
+| worktree | .worktrees/feature-agent-workflow-governance-plan |
+| 起点 | 本地 dev@15b8a4a8 |
+| 合入 / push | 均未执行；方案只在本地任务分支 |
+
+## 验证及边界
+
+- 仅文档差异、链接和状态检查；未运行 Go/前端测试、迁移或真实 PI 操作，不作产品验收声明。
+- 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。
+- 当前没有机器协调入口，分支 CURRENT 不等于全局实时认领。本任务只读代码，写入独立文档文件。
+- 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。
+- 后续合入 CURRENT 要保留当时其他任务和槽位状态；本次不合入是因为仅请求研究方案且主目录正有进行中任务，不是已经完成的代码交付。
+
+## 相关链接
+
+- [研究任务](../../archive/ops/2026-09-21-agent-workflow-governance-plan.md)
+- [CURRENT](../CURRENT.md)
@@ -0,0 +1,61 @@
+---
+title: "Agent worktree 与并行协作机制核查"
+created: 2026-09-21
+status: done
+confidence: high
+---
+
+# Agent worktree 与并行协作机制核查
+
+## 结论
+
+用户提出的主目录保护、全部开发使用 worktree、从 dev 开任务分支、验证后合入并更新服务、安全清理的方向成立。当前仓库具备规范雏形，但机器执行尚未形成闭环；仅修改 AGENTS 文案无法保证并行可靠性。建议采用任务 worktree + 机器协调状态 + 串行集成队列，分阶段增加执行隔离。
+
+本次核查为只读研究及文档编写，未执行产品测试、迁移或服务重建。下列发现是代码与现场证据，风险推断不等于已发生事故。
+
+## 采样边界
+
+- 2026-09-21 初始主目录：`fix/intent-workflow-scoping-2026-09-21@5c6b4f77`；`internal/server/stage_access_helpers.go` 已修改，`internal/projectinstance/workflow_scope.go` 未跟踪，均属其他任务。
+- 本地 dev：`15b8a4a8`；研究 worktree 显式以此创建。上述治理脚本与主目录版本 diff 为空。
+- `git rev-list --left-right --count origin/dev...dev` 为 `0 309`。未 fetch，仅说明当时本地跟踪引用状态，不能宣称实时远端落后 309。
+- `git worktree list --porcelain` 初始列出主目录及 4 个 linked worktree：其中 3 个在 `.worktrees/`，1 个在 `.kilo/worktrees/` 且 detached；新增本次研究 worktree 后为 5 个 linked worktree。
+- 本机 Git 2.53.0；`core.hooksPath` 未配置，`.git/hooks` 未检出非 sample 文件。
+- CURRENT 中仍保留较早的“extra worktree 仅余……”叙述，不能用作当前 worktree 清单。
+
+## 发现与依据
+
+| 编号 | 当前证据 | 影响 / 推断 |
+|---|---|---|
+| F01 | `AGENTS.md` §6.2 允许单 Agent 在主目录创建 feature 分支；CURRENT 多条 worktree=`-` | 用户提出的是对现行规范的实质收紧，必须统一修改入口与执行规则 |
+| F02 | `scripts/agent-worktree.sh:50` 未给 start-point；Git worktree add 默认以 HEAD 为起点 | 从主目录任务分支创建新任务可能夹带其他任务提交，不能保证“来自 dev” |
+| F03 | 同脚本 5–7 行从脚本目录推导 ROOT | 在 linked worktree 调用自身脚本会推导嵌套 `.worktrees`，不能定位唯一主仓 |
+| F04 | 同脚本 34–35 行仅把 `/` 替换为 `-` | `feature/a-b` 与 `feature/a/b` 映射冲突；缺少任务 ID、严格命名及路径校验 |
+| F05 | 同脚本 67–69 行默认 `remove --force`，可选 `branch -D` 且吞错 | 删除前未验证是否合入 dev、是否有未保存文件、是否仍有 Agent 使用；可能损失工作 |
+| F06 | `scripts/env-service.sh:18–20,76–151` 从自身位置定位 Compose；无 worktree、分支、租约校验 | 文档禁止 worktree 动共享服务，但脚本未强制；`logs` 也会经过配置/目录初始化，非纯只读 |
+| F07 | `docker-compose.dev.yml:8,13,38,74,147,174–184` 固定 project/container/network/volume 名 | 不同目录运行同份 Compose 不能获得独立环境；单改 project name 仍不足以隔离显式名称和宿主端口 |
+| F08 | `docker-compose.dev.yml:53–58` 挂载主目录 PI 源码和数据；docker inspect 确认挂载实际存在 | 主目录变更可影响以后加载/重启时的 Runner 行为；`:ro` 只约束容器写入，不冻结宿主文件内容 |
+| F09 | `.doc/ops/CURRENT.md` 是普通版本化 Markdown，无原子认领；各 worktree 内容不同 | 两个 Agent 可同时看到 idle；分支内认领不会实时传到另一 worktree；不能用作真正互斥锁 |
+| F10 | `AGENTS.md` §6.3 要求长 E2E 可先 smoke 释放槽位 | 如 E2E 仍使用可变共享 dev，后续部署会使证据混合；必须保留环境租约或转入隔离环境 |
+| F11 | `scripts/herdr-agent-start.sh:97–109`、dispatch 66–77 行校验仓库文件和 feature/fix 分支，未检验 linked worktree 身份 | 主目录 feature 分支同样可通过；同一逻辑实例名及同 cwd 路由需要适配并行任务身份 |
+| F12 | `.dockerignore:1–20` 未排除 `.worktrees` / `.kilo`；`deploy/app/Dockerfile:19` 为 `COPY . .` | 多 worktree 可能进入构建上下文和构建阶段，增加大小和无关缓存失效；未测传输量，不断言全部最终进入运行镜像 |
+| F13 | `scripts/candidate-images-build.sh:29,48,53` 用指定 COMMIT 标记，但 docker build 使用当前目录 | 任意 `--commit` 并不保证构建该提交；未来集成凭证必须绑定真实干净树，不能直接相信标签 |
+| F14 | `internal/server/handlers.go:28–40,89–155` 提供 ready/schema，Version 固定为 v1.0 | `/ready` 可以检查就绪，但不能单独证明当前运行精确提交；需镜像标识、挂载和配置摘要关联 |
+| F15 | `.github/workflows/ci.yml` 已有 Go/迁移/PG/前端/架构门禁；nightly 与 promotion receipt 也已存在 | 应复用已存在的检查与凭证，补本地准入和集成关联，不另起一套相互矛盾标准 |
+
+## 运行态核查
+
+- dev app/events/PI/PG 均显示 healthy；本轮只查询状态，没有变更容器。
+- `GET :8080/ready`：`status=ok`、`env=dev`、`agent_backend=pi-agent`、schema=60，database/schema/task_store ready。
+- app 挂载主目录 `data/dev`、`.regulations`；PI 挂载主目录 `data/dev/workspaces`、`agent_sessions` 和四组源码路径。
+- app/events 镜像 ID 不同；本轮未调查构建历史，不能仅据此认定异常。这说明未来需要逐组件记录运行身份。
+- 未读取 `.env` 内容、用户会话正文或生产数据；未验证远端分支保护与 CI 当前执行结果。
+
+## 官方机制核验
+
+1. [Git worktree](https://git-scm.com/docs/git-worktree)：linked worktree 有独立 HEAD/index，但共享仓库资源；创建必须显式选择起点。`worktree lock` 用于防移动、删除和修剪，不是开发互斥锁。
+2. [Git hooks](https://git-scm.com/docs/githooks)：hooks 作用于 Git 生命周期，不能拦截编辑器普通写文件。客户端 hook 是防误操作层，不能当作 OS 权限隔离。
+3. [Docker Compose project name](https://docs.docker.com/compose/how-tos/project-name/)：project name 有多级优先级；结合本仓显式容器/卷/网络/端口配置，判断不能只换目录或加 `-p` 就宣称完全隔离。
+
+## 建议
+
+详见 [治理方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)。最先修正创建起点与强制删除，再落机器协调/服务守卫，最后试点候选集成和可靠部署。旧 worktree 按所有者和证据逐个处理，禁止一键清空。
@@ -0,0 +1,274 @@
+---
+title: "Agent 工作规范与 worktree 并行开发治理方案"
+status: planned
+created: 2026-09-21
+updated: 2026-09-21
+owner: Codex
+---
+
+# Agent 工作规范与 worktree 并行开发治理方案
+
+## 1. 建议与目标
+
+采用“主目录作为 dev 集成与运行入口，所有任务在 `.worktrees/` 内开发，自动检查后进入串行集成队列”的方案。单 Agent 也遵守。一个任务对应一个分支和一个 worktree，可包含多个原子提交；不是每改一个文件就新建分支。
+
+你的目标应保留，但补上五项前提：
+
+1. 主目录的**受版本控制文件**禁止日常直接编辑；集成更新、运行数据、受控配置和 Git 元数据需明确例外。
+2. worktree 只提供代码工作区隔离；数据库、端口、容器、共享状态须单独治理。
+3. “测过”必须对应确切提交和环境；排队后 dev 前进，旧测试不能直接代替新组合的验证。
+4. “合入”“部署成功”“业务验收通过”“已清理”“已推送”是不同事实，分别记录。
+5. 普通文档不改变运行内容，无需每次重建 dev；部署范围应按实际差异判定。
+
+本次是待审核方案，未修改生效规则或脚本，未授权迁移既有任务、服务重建、批量清理及 test/main 晋升。
+
+现状依据：[调研](../ops/research/2026-09-21-agent-workflow-governance-research.md)。目标是降低误改和并行竞争，不重建个人工程中控台，不为每项任务默认起全套环境。
+
+## 2. 方案比较
+
+| 方案 | 优点 | 局限 | 选择 |
+|---|---|---|---|
+| 只改 AGENTS，要求自觉使用 worktree | 最少改动 | 当前脚本仍能从错误分支开工、强删、竞争服务 | 不足以满足可靠性 |
+| 主目录固定 dev + 强制任务 worktree + 本机协调器 + 单集成队列 | 延续现有目录、三环境、脚本体系；适合当前单机多 Agent | 需少量脚本及状态治理；同 UID 仍可绕过规则 | **首选，分阶段落地** |
+| bare 仓库 + 全部 linked worktree + 独立部署目录 | 仓库与运行目录边界更整齐 | 需迁移 IDE、挂载、配置和运维；仍不能解决共享环境竞争 | 当前不迁移；未来运行目录脱离时再评估 |
+| 每任务独立 clone + 全套容器/DB | 隔离更强，可并行运行 E2E | 磁盘、内存、端口、凭证和数据治理成本高 | 高风险任务按需使用，不作默认 |
+| 远端 PR/merge queue + CI 部署 | 适合跨机器协作和权限强约束 | 需要远端权限、runner、制品和部署能力建设 | 后续阶段；不把本地状态文件当分布式锁 |
+
+## 3. 目录与权限边界
+
+```text
+Agent-System/                         主工作区；迁移后固定检出 dev
+  AGENTS.md / PROJECT.md              集成更新，禁止日常手工改写
+  internal/ web/ scripts/ ...          同上
+  .env / configs/.env.*                受控运维配置；不复制给每个任务
+  data/ .regulations/                  服务运行数据，非开发素材
+  .git/agent-control/                 拟新增本机协调状态，不提交 Git
+  .worktrees/
+    <task-id>/                        任务分支工作区
+    <integration-id>/                 临时集成候选；也属于受控 worktree
+```
+
+统一目录名 `.worktrees`，不同时引入 `.worktree`。目录用任务 ID，分支用 `feature/<task-id>` / `fix/<task-id>`，通过登记映射关联，不用有歧义的字符串替换推算路径。
+
+| 对象 | 开发 Agent | 集成执行者 | 运维/服务进程 |
+|---|---|---|---|
+| 主目录跟踪文件 | 只读 | 只允许受控 Git 快进更新；冲突回任务区解决 | 只读 |
+| 自己的任务 worktree | 范围内读写 | 读、建候选；不得混入其他任务未提交文件 | 无默认权限 |
+| 其他任务 worktree | 授权范围内只读 | 审查与协调 | 无 |
+| 主目录 `.env`、环境覆盖文件 | 默认不读写、不复制；使用注入的任务所需配置 | 部署时受控读取 | 独立运维任务授权后可改 |
+| `data/dev` 等业务数据 | 通过受控 API 和测试身份验收，禁止直接编辑 | 维护窗口内受控操作 | 服务正常读写 |
+| 共享 `.git` 与协调状态 | 通过统一入口使用 | 通过统一入口使用 | 不对业务容器暴露 |
+
+“主目录只读”不是 `chmod -R a-w`：后者会连带 `.git`、`.worktrees` 和数据，破坏正常运行。第一阶段采用规则+守卫防误操作；强约束阶段使用独立用户/沙箱，只给任务目录写权限，由受限管理入口代办共享 Git 和部署操作。不可宣称同 UID、可任意执行 shell 且可写共同 Git 目录时绝对不能改主仓。
+
+受控例外必须登记 task、owner、目标路径、原因、时效、验证和恢复办法。运维配置修改不等于开发例外；业务修复包括紧急修复仍走任务 worktree，可加急队列。若需破坏性数据操作或扩大授权，另行确认。
+
+## 4. 角色与任务契约
+
+角色按职责划分，不绑定特定模型：
+
+- **协调者**：明确授权范围、拆任务、依赖和写范围、安排验收与资源预算。
+- **实现者**：在唯一任务 worktree 内编码、测试和记录，提交冻结版本。
+- **审查者**：审查冻结 SHA；只读评审，可并行；任何修复回实现者并使旧准入失效。
+- **集成执行者**：唯一持有 dev 集成及部署租约，验证候选、合入、部署、恢复和收据。
+
+同一 Agent 可分时兼任；涉及鉴权、迁移、秘密配置或发布关键点，安排独立审查。增加 Agent 数量不能取代职责边界。Herdr 是可选的执行终端，核心入口也供普通 CLI/IDE 使用；不依赖 Herdr 是否在线。
+
+任务最少记录：`task_id`、授权范围、owner/运行实例、branch、worktree、base_dev_sha、依赖、允许写路径、mutex 集合、验证计划、风险、提交 SHA、准入/部署/清理结果、证据路径。初始模型仅建议 2–3 个并行写任务；根据内存、CPU、排队耗时调整，集成始终 1 个。
+
+任务状态继续使用现有 `planned/in_progress/blocked/done/cancelled`；另用 operation phase 表达 `developing/validating/queued/candidate_testing/merging/deploying/accepting/cleanup_pending/closed/failed`。不要把 phase 塞进旧文档 status。
+
+## 5. 机器协调状态与并行边界
+
+### 5.1 CURRENT 不再承担实时互斥
+
+当前每个 worktree 的 CURRENT 都是不同 Git 快照，不能原子认领。拟在 `git rev-parse --path-format=absolute --git-common-dir` 对应目录下建立 `agent-control/`：
+
+- `tasks/<id>.json`：单任务当前状态；包含 generation、owner、base/head SHA、paths、mutex、更新时间、证据。
+- `queue/`：待集成请求；以 task+head SHA 去重，FIFO 为默认，可审计加急。
+- `locks/`：注册表短事务锁、dev 集成锁、共享环境验收锁。
+- `operations/`：每次集成的阶段记录和恢复信息；记录原 dev、候选、运行镜像身份。
+- `runtime/dev.json`：当前实际部署版本及验收状态；不能由文档 done 推导。
+
+单机本地文件系统使用 `flock` 与原子 rename；注册任务、路径占用与 mutex 检查在同一短事务内完成。资源集合一次性校验并原子取得，禁止先占一个 mutex 再等另一个造成死锁。集成父进程持有 fd 锁贯穿 Git 更新和部署；子进程生命周期纳入管理。
+
+心跳过期只标记 suspect，不能据此强抢：先检查 owner 进程、子进程、Git 操作、容器活动，再进入恢复。崩溃可释放 OS 锁，但未完成 operation 仍阻止新集成，直到恢复者核实。`git worktree lock` 不是此处的互斥实现。
+
+此注册表只做本机实时协调，不包含秘密、不作为历史证据唯一存储。稳定任务文与收据落在 `.doc`；CURRENT 由集成执行者在任务/文档分支生成或合并摘要，带 snapshot 时间。Agent 启动先查机器状态再读 CURRENT。主目录无需为每个任务直接修改 Markdown。跨主机时升级中央服务或远端队列，不共享本机 flock 文件伪装分布式协调。
+
+### 5.2 开发冲突与资源冲突分别处理
+
+- 不同模块、不同写路径可以并行；同文件原则上单写者，扩大范围需重新登记。
+- 模块 mutex 是默认边界；稳定接口下的大模块可拆细，如 `web:chat`、`web:admin`，仍对共享路由/DTO/全局状态文件单独排他。
+- 迁移号由协调器短事务预留，候选阶段再次扫描重复和顺序；已在共享环境应用的迁移禁止改名重写。两个任务各自取“最大号+1”不是安全分配。
+- `go.mod/go.sum`、前端 lockfile、数据库迁移、顶层路由等公共热点集中认领；不为“提高并行”默认允许多人改同一热点。
+- CURRENT、FEATURE-MATRIX 的各任务变更意图写到本任务文，集成时串行汇总；不要每个分支都重写整张表。
+- PG 测试使用独立测试数据库/角色，必要时独立实例，独立端口及工作目录；不把业务 dev/test/main 库当测试沙盒。
+- 编码和本地测试不占 dev 部署锁；共享 dev 的写入验收单独申请环境租约并使用专属测试项目，禁止污染真实用户会话。
+- 依赖任务先合入 dev，再从新 dev 开下游分支；等待时做只读研究。默认不从 feature 派生另一功能分支，也不整支拉入未完成旁支。
+- 编译/浏览器/真实 PI 按资源预算调度；Go/npm 下载缓存可复用，每个 worktree 的 node_modules、dist、测试输出独立，不能共享可变目录。
+
+## 6. 开发、集成、部署闭环
+
+```mermaid
+flowchart LR
+  A[任务授权与范围登记] --> B[从明确 dev SHA 创建 worktree]
+  B --> C[并行开发与本地测试]
+  C --> D[冻结提交与审查]
+  D --> E[进入集成队列]
+  E --> F[构造并验证合并候选]
+  F --> G{dev 基线仍匹配}
+  G -- 否 --> F
+  G -- 是 --> H[受控推进 dev]
+  H --> I{影响运行内容}
+  I -- 是 --> J[构建或应用确定制品]
+  J --> K[就绪与相关业务验收]
+  I -- 否 --> L[记录无需部署]
+  K --> M[证据归档与安全清理]
+  L --> M
+```
+
+### 6.1 开工：从明确 dev 创建，不切换共享主目录
+
+1. 校验任务 ID、分支名、路径、授权范围、mutex 和已有任务。仅接受预期仓库身份；拒绝 symlink 越界、嵌套 worktree、路径冲突和分支占用。
+2. 主目录定位以 Git common-dir + 已登记主工作区为依据，不从当前脚本的父目录猜。核查 `git worktree list --porcelain`，拒绝用户目录同名但不同仓库的假路径。
+3. dev 同步由协调者串行进行；开发 Agent 不执行共享目录 `checkout dev && pull`。远端可访问时 fetch 后判定领先/落后/分叉；可快进时按同步协议处理；分叉或有现场改动则停止自动同步并保留现场。离线可按明示策略使用本地 dev SHA，记录来源新鲜度。
+4. 创建使用已解析 `base_dev_sha`，核心语义为 `git worktree add -b <branch> <path> <base_dev_sha>`；确保 branch 的初始提交就是该 dev 快照。
+5. 登记 branch/path/base SHA 后再发写任务；创建中断可按 task_id 幂等恢复。主目录即使有旧任务残留也不能偷偷 stash/reset；迁移期间本地只读研究可显式使用 dev 创建隔离文档任务。
+6. 不复制主目录 `.env`、`data`、浏览器登录态；依赖安装和测试配置留在自己的 worktree。
+
+### 6.2 开发与准入
+
+实现者提交原子变更；每个任务可有多次 commit。准入前固定 `head_sha`，检查实际变更是否超出 paths/mutex，运行相应门禁并审查。测试结果必须记录 commit、命令、退出码、工具/配置版本、时间和真实/stub/skip 分类。head 改变立即使旧准入失效。
+
+| 变更范围 | 基本准入 | 额外检查 |
+|---|---|---|
+| 普通 `.doc` 文档 | diff/链接/状态一致性 | 不需要 Go/PI/容器重建 |
+| Go / API | `go vet ./...`、`go test -short ./...`、现有架构检查 | 涉及 PG/鉴权用真实独立 PG 对应测试 |
+| web | `npm ci`、`npm test`、`npm run build` | 受影响交互以真实浏览器验收 |
+| 迁移/数据契约 | migration gate + 空库/已有库升级验证 | 并发编号、兼容旧应用、备份恢复证据 |
+| Agent/工作流/文档生成 | 对应单测、PG/接口检查 | 产品 PI Runner 与浏览器真实链路；stub 不作为最终验收 |
+| 治理脚本/规则 | 临时测试仓库中的错误起点、并发锁、清理拒绝、故障恢复等 | 用受控两任务试点证明闭环；无业务改动不为形式强跑产品 PI |
+
+规则/CI/Dockerfile/模板/提示词不按文件扩展名草率归入“普通文档”。尤其 `templates/**/*.md`、`configs/**/*.md` 可能属于运行制品。
+
+### 6.3 合并候选：测试什么，最终就合入什么
+
+建议引入临时 `feature/integrate-<id>`，在 `.worktrees/<integration-id>` 从锁定 dev SHA `D` 创建，再 `merge --no-ff` 冻结任务提交 `T` 得到候选 `M`。冲突由任务所有者在任务 worktree 解决，并重新提交/测试/排队；集成执行者不临场改业务逻辑。
+
+在候选 `M` 上执行组合门禁。成功后获取/校验 dev 集成锁，确认主目录为干净 dev、dev 仍为 `D`，任务仍冻结为 `T`，然后将 dev **仅快进到已验证的 `M`**。这样 dev 的历史仍保留 no-ff 合并节点，同时避免验证一个合并结果、再生成另一个未验证结果。
+
+这需要明确修订现行“只能在主目录执行 merge --no-ff”的字面约定：no-ff 合并节点在候选区生成，主目录只接收验证后的节点。不要用直接 update-ref 绕过主目录工作树同步。
+
+候选测试可在集成锁外进行，减少排队，但推进 dev 前必须 compare-and-check 原基线；dev 已变化则重建候选并重跑受影响验证。第一版仅一个集成执行者，不引入复杂投机合并队列。
+
+### 6.4 dev 更新与验收
+
+1. 取得部署/环境租约；共享 dev 存在尚未结束的真实任务或验收时排队，不默认杀任务。必要维护窗口先按已授权方式暂停新任务并等待结束。
+2. 记录旧运行 app/events/PI 镜像身份、目标 M、配置安全摘要和 schema；构建必须读取干净 M，不接受任意 `--commit` 给另一份目录内容贴标签。
+3. 第一版复用 `env-service.sh dev rebuild`，补 preflight、超时、失败状态、精确源身份及结果检查；`restart` 不能代替新代码构建。候选镜像脚本必须先修“标签 SHA 与构建树不一致”的风险，才可用于无重建应用同一制品。
+4. 核验 app `/health` 和 `/ready`、events 就绪、PI 连通性、实际镜像/挂载与目标匹配、预期 schema；然后执行变化相关真实业务和浏览器检查。当前固定 v1.0 不能证明提交版本，拟加 build metadata/镜像 revision label 并写部署收据。
+5. 建议将 dev PI 源码 bind mount 退出默认部署配置，运行源码随镜像；调试挂载只作显式临时 profile，有 owner、租约、过期时间和恢复动作。切换前应确认现存热补丁已归入源码与镜像。
+6. 将 `dev_merged_sha` 与 `runtime_deployed_sha` 分开。普通文档合入可记录 `deployment=not_required`；后续分类比较必须覆盖“当前实际运行版本→新 dev”的累计差异，不能只看最后一次 commit 漏掉先前未部署代码。
+7. 共享 dev 的长 E2E **持有环境租约直到结束**；仅当验收已转到独立固定环境且证据绑定身份后，才能释放共享环境继续部署。
+8. 发布收据记录 candidate/head/merge/runtime SHA、组件 image IDs/digests、schema、测试结果和恢复信息。秘密配置仅记录字段状态或受保护版本号，不记录值。
+
+原始操作收据先写本机协调区，完成后导出 `.doc/test-reports/`。部署后的报告以普通文档分支从最新 dev 产生并串行合入，跳过重建；避免为了给报告写入新 SHA 而形成无止境的“提交→重建→再提交报告”。稳定的执行 operation_id 关联最初制品。
+
+## 7. 失败恢复
+
+| 故障 | 必须行为 | 禁止行为 |
+|---|---|---|
+| 创建中断/同 ID 重试 | 查 registry、branch、Git worktree 元数据，恢复同一任务或明确冲突 | 新建第二个写者覆盖原任务 |
+| 合并冲突/候选门禁失败 | 保留候选证据，退回原任务修复 | 在主目录直接改业务代码、伪造 PASS |
+| dev 已前进 | 旧候选过期，重新组合与验证 | 强推/重置 dev 到旧基线 |
+| dev 已合入、构建失败 | 记录 merged-but-not-deployed；阻断后续集成，保留旧运行环境，修复后继续 | 宣称 done 或删除任务 worktree |
+| 部署成功但 ready/业务失败 | 标 failed；按预先检查的兼容性恢复旧镜像或修复前滚；恢复后再开放队列 | 仅看容器 Up 就放行 |
+| 迁移已应用 | 优先兼容性前滚；回退应用需证明新 schema 兼容 | 自动 Down、删库、restore 覆盖真实新增数据 |
+| Agent/集成进程崩溃 | 查 operation 阶段、实际 dev/runtime 和子进程；恢复者记录接管 | 超时直接抢锁并再部署 |
+| Docker/网络超时 | 区分未知结果与明确未执行；先查容器状态再决定重试 | 因超时重复应用有副作用动作 |
+| 清理失败 | 标 cleanup_pending，可重试，不影响已通过的部署事实 | 用 --force 掩盖路径/权限/dirty 错误 |
+
+需要回退已合入代码时，从最新 dev 创建 `fix/*`，形成显式 revert/修复提交并走同一队列；不硬重置 dev。DB 不兼容时先恢复服务能力或保留故障窗口，不能自动假定“换旧镜像”安全。
+
+## 8. 完成与安全清理
+
+开发实现完成可进入 validating/queued；只有合入、所需部署/验收、文档证据满足后才算任务 done。清理结果作为独立状态，便于磁盘维护。
+
+自动清理需全部满足：
+
+- 注册路径与 `git worktree list --porcelain` 的实际分支一致，路径严格位于主目录 `.worktrees` 且无 symlink 越界。
+- 冻结 task head 已通过 `git merge-base --is-ancestor <task-head> dev`，未出现排队后的新提交。
+- 所需部署/验收通过或明确 not_required，报告和 handoff 已持久化，旧运行恢复信息可追溯。
+- tracked/untracked 文件均检查；ignored 文件也盘点，只有预先约定的可再生缓存可删除。唯一日志、截图、报告、未提交草稿先迁入证据区。
+- Agent 和相关写进程已退出；不再是有效 cwd，无依赖任务正在使用目录；清理器从管理目录运行。
+- 无未完成 merge/rebase、无未解决锁、无“不整支合并/不删除”的历史保护标记。
+
+使用普通 `git worktree remove`；分支删除在明确祖先检查后用非强制 `git branch -d`，拒绝时报告并保留，绝不回退到 `-D`。`prune` 仅清理已失效的 Git 元数据，不等于删除工作成果；禁止 `rm -rf .worktrees/*`。
+
+push 与本地完成分开：用户未要求时不自动 push；已要求时必须成功并验证对应远端引用后才关闭同步项。没有 push 的合入仍需明确报告本地状态。清理只移除已安全保存的任务目录，不清理 `data`、共享卷或其他 Agent 目录。
+
+旧 FAV、目录/分支不匹配、`.kilo` detached 和未合入研究目录不能按年龄自动删。本次研究 worktree 也因方案尚待审核而保留。
+
+## 9. 规则与工具落点（拟实现）
+
+以下是后续能力要求，不是现在已经可调用的新命令。
+
+| 落点 | 变更要求 |
+|---|---|
+| `AGENTS.md` §2/3/6/8，`PROJECT.md`，`.cursor/rules/git-workflow-and-environments.mdc` | 去掉单 Agent 主目录开发例外；明示候选合并、主目录受控更新、运维例外、执行权限边界 |
+| 各客户端薄入口与 roster | 保留一个规范来源；按 task_id 建实例名；校验任务与 linked worktree 身份；重投不扩授权 |
+| `scripts/agent-worktree.sh` | 显式 dev SHA；唯一主仓定位；路径和分支校验；安全 remove；可恢复创建；list/doctor |
+| 拟新增任务/集成管理入口及公共 guard | 原子认领、队列、短事务锁、operation 日志、候选测试、dev/部署串行、状态恢复；尽量共享一份校验逻辑 |
+| `scripts/env-service.sh` | dev 写操作必须主目录/dev/有效集成租约；test/main/shared 按各自运维或晋升授权与锁校验，不能借 dev 任务操作 all；只读操作无隐式初始化；独立隔离验证环境走专用入口 |
+| `scripts/candidate-images-build.sh` 等制品入口 | 构建树与 SHA 严格关联、干净树校验、标签/收据对应制品；不能只检查传入 SHA 存在 |
+| `.dockerignore` | 排除 `.worktrees/`、已知 IDE worktree/cache、协调状态和测试输出；验证模板/配置必须仍被打包 |
+| `docker-compose.dev.yml` / Dockerfile | 默认撤出运行源码 bind mount、显式稳定运行数据路径、增加构建身份；保留受控调试 profile |
+| Git hooks / CI | 阻止主目录/主干直接开发提交和错误任务路径；测试/迁移/架构门禁；hooks 可绕过，远端保护另行配置 |
+| `.doc/ops/templates/*` / CURRENT / FEATURE-MATRIX | task_id、base/head/runtime 身份、权限范围、阶段收据；CURRENT 成为快照，模块状态据实际验收更新 |
+
+脚本入口可提供 `create/doctor/claim/validate/submit/status/integrate/cleanup` 语义；具体组合成几个文件由实现决定。不要把核心约束散落于每种模型提示词。
+
+## 10. 分阶段落地
+
+| 阶段 | 负责人职责 | 交付 | 进入下一阶段的条件 |
+|---|---|---|---|
+| W0 现场迁移准备 | 协调者 + 现有任务所有者 | 清点主目录改动、所有 worktree、运行挂载、旧保护项；确定切换窗口 | 原任务保存并由 owner 交接；主目录可安全回 dev；无强 stash/reset |
+| W1 基础防护 | 实现者 + 审查者 | 创建/安全清理修正、主目录规则、身份 doctor、构建忽略 | 临时仓库负例通过；旧目录仅盘点；新增写任务全部走 worktree |
+| W2 实时协调 | 实现者 + 集成者 | 注册表、原子 mutex/路径认领、队列、服务 guard、生命周期与恢复 | 同时申请同资源仅一个成功；非持有者服务写操作被拒；崩溃可恢复 |
+| W3 合并部署闭环 | 集成者 + 验收者 | 固定候选验证、dev 推进、制品身份、ready/业务验收、PI 镜像交付 | 两个并行任务串行交付，运行身份一致，失败恢复证据齐全 |
+| W4 收口与持续维护 | 协调者 | 证据归档、安全自动清理、统一薄入口、文档投影 | 清理拒绝危险状态；遗留任务有明确 owner/保留原因 |
+| W5 按需增强 | 平台维护者 | OS 权限隔离、临时预览环境、跨机远端队列 | 由实际瓶颈与绕过风险触发，不预先铺开全套平台 |
+
+W1/W2 是最小可用安全闭环，W3/W4 达到用户完整目标。不要在 W1 仅改文案后宣称治理已完成。实施任务分别从当时 dev 创建，互斥范围以具体文件/资源登记；治理脚本共用处串行。
+
+## 11. 验收清单
+
+以下为未来实施验收，均未在本次研究中执行：
+
+1. 主目录处在另一任务分支时，create 仍严格从指定 dev 创建；从任意子目录调用不会生成嵌套 worktree。
+2. 两个不同写范围任务可同时运行；同 mutex/热点路径同时申请只有一个成功，另一个有清楚排队原因。
+3. 未登记、路径越界、分支不符、主目录直写/提交被相应入口拒绝；另验证并诚实记录 OS 隔离启用前的绕过边界。
+4. feature/fix worktree 运行共享服务 start/stop/restart/rebuild/down 全部被 guard 拒绝；status/logs 不生成 env/data。
+5. 源码/文档/制品中不出现任务复制的秘密，构建上下文不含其他 worktree；模板 Markdown 正常进入镜像。
+6. 任务 A/B 从同一个 dev 起步；A 合入后 B 旧候选必须失效或重新组合验证，不可复用旧 PASS 直接推进。
+7. 合并冲突在任务区解决；主目录保持干净 dev，未夹带其他未提交修改。
+8. 指定错误 `--commit` 构建被拒绝；候选 SHA、运行组件 image ID、schema、验收收据可互相核对。
+9. 模拟构建失败、部署失败、ready 失败、迁移不兼容、进程崩溃和超时；均可按 operation 恢复，不冒充 done。
+10. 共享 dev 长 E2E 期间第二个部署排队；验收使用独立测试数据且不污染真实用户项目。
+11. 未合并、dirty、存在唯一 ignored 证据、分支/目录不符、Agent 存活、保护任务全部拒绝清理；完成任务可普通 remove。
+12. 普通文档合入记录 not_required，不重建；模板/提示词/运行配置变化正确触发运行验证。
+13. push 未授权时不发生；授权同步时验证目标远端引用，不以本地 origin 缓存冒充实时结果。
+14. 用两个隔离任务完成“认领→实现→审查→排队→候选→合入→部署→真实验收→证据→清理”的现场演练。
+
+成功指标：新任务在主目录直接开发次数为 0；共享服务并发变更为 0；每次交付有可追溯收据；不产生强制删除；结束任务无无主 worktree。再收集候选重跑率、集成等待时间、构建时间和残留目录数，决定是否值得增加独立预览环境。
+
+## 12. 审核建议与待实施边界
+
+建议批准 W0–W4 作为整体方向，先 W0/W1/W2，再验证 W3/W4。默认选择主目录固定 dev、本机队列、普通文档免部署、共享环境 E2E 租约、按需隔离 PG，暂不迁 bare/全任务 Docker/跨机平台。
+
+最值得审核的是两个策略：是否接受主目录只接收已测试合并节点的快进更新，以及是否将 dev PI 源码热挂载改为镜像交付。两者均推荐；实施前需接续现有主目录任务并核查热补丁，不能直接迁移现场。
+
+尚未验证：远端分支保护、实际远端最新 dev、主机可承载的最佳并行数、每个客户端的沙箱边界。它们不阻碍本地方案成立，但不得据此承诺绝对禁止所有绕过或无限并行。
+
+本方案自检已覆盖：worktree 隔离边界、机器锁与文档快照、精确候选测试、运行绑定、长 E2E 租约、数据库恢复、证据提交循环、安全清理及现存任务迁移。实施后仍需用 §11 的实际证据验收。
@@ -49,6 +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` |
 | 意图识别 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` |