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/archive/ops/2026-09-21-agent-workflow-governance-plan.md b/.doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md new file mode 100644 index 00000000..9905cdd2 --- /dev/null +++ b/.doc/archive/ops/2026-09-21-agent-workflow-governance-plan.md @@ -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。 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 ef0dc44c..9f7e73ea 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -13,6 +13,9 @@ | 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 | | Cursor | 2026-09-21-trace-panel-to-chat | feature/trace-panel-to-chat-2026-09-21 | - | trace-impact+web | done | @@ -177,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` @@ -195,6 +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)；规范已采纳，自动化另列 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 new file mode 100644 index 00000000..7d645b57 --- /dev/null +++ b/.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.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；研究任务归档。 + +## 下一步 + +用户已确认采纳并提交。生效规则见 [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 登记文档集成；实际操作持 common-dir 下 dev-integration.lock，主目录 CURRENT 保留 | +| branch | feature/agent-workflow-governance-plan | +| worktree | .worktrees/feature-agent-workflow-governance-plan | +| 起点 | 本地 dev@15b8a4a8 | +| 合入 / push | 本次按已验证候选合入本地 dev；未 push，最终结果见规范采纳验收报告 | + +## 验证及边界 + +- 仅文档差异、链接和状态检查；未运行 Go/前端测试、迁移或真实 PI 操作，不作产品验收声明。 +- 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。 +- 当前没有自动任务协调器，分支 CURRENT 不等于全局实时认领。此次只有人工明确范围和本机 flock，不宣称自动队列或全局硬隔离已实现。 +- 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。 +- 主目录仍是旧任务分支；dev 暂由 `.worktrees/agent-governance-dev-integration` 检出以安全集成文档。旧任务 owner 保存成果、确认主目录干净后，先安全移除临时 dev worktree，再在主目录切回 dev；不得强抢 dev 检出。 + +## 相关链接 + +- [研究任务](../../archive/ops/2026-09-21-agent-workflow-governance-plan.md) +- [CURRENT](../CURRENT.md) 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/research/2026-09-21-agent-workflow-governance-research.md b/.doc/ops/research/2026-09-21-agent-workflow-governance-research.md new file mode 100644 index 00000000..fefa14ee --- /dev/null +++ b/.doc/ops/research/2026-09-21-agent-workflow-governance-research.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 按所有者和证据逐个处理，禁止一键清空。 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 new file mode 100644 index 00000000..3b81c15f --- /dev/null +++ b/.doc/remediation/2026-09-21-agent-workflow-governance-plan.md @@ -0,0 +1,276 @@ +--- +title: "Agent 工作规范与 worktree 并行开发治理方案" +status: planned +created: 2026-09-21 +updated: 2026-09-21 +owner: Codex +--- + +# Agent 工作规范与 worktree 并行开发治理方案 + +> **2026-09-21 已采纳**：用户确认“提交吧，之后按这套执行”。生效工作规范见 [执行入口](../ops/2026-09-21-agent-worktree-workflow.md)。本文 status=planned 追踪尚未实现的自动化 W0–W4，不代表仍待审核；采纳与自动化验收分开记录。 + +## 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/ + / 任务分支工作区 + / 临时集成候选；也属于受控 worktree +``` + +统一目录名 `.worktrees`，不同时引入 `.worktree`。目录用任务 ID，分支用 `feature/` / `fix/`，通过登记映射关联，不用有歧义的字符串替换推算路径。 + +| 对象 | 开发 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/.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 的初始提交就是该 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-`，在 `.worktrees/` 从锁定 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 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 现可在规范合入且清理门禁满足后移除；临时 dev 集成 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 的实际证据验收。 diff --git a/.doc/status/FEATURE-MATRIX.md b/.doc/status/FEATURE-MATRIX.md index 4ccb981f..e2c7a8e4 100644 --- a/.doc/status/FEATURE-MATRIX.md +++ b/.doc/status/FEATURE-MATRIX.md @@ -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) | [工作规范](../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）