Agent-System/.doc/ops/2026-09-21-agent-worktree-workflow.md

Agent worktree 与 L1 操作规范

修订：agent-governance-2026-09-21-r1。来源：AGENTS、规范登记。工具为 scripts/agentctl（Python 标准库，macOS/Linux 双平台），协议 v1；实际安装与验证见实施任务。

本规范约束合作 Agent 的统一操作入口和 Git 提交/引用门禁。任意同 UID shell、修改管理器或跳过 hooks 仍可绕过；不把 L1 宣称为 OS 沙箱。共享服务配置与产品数据库不属于任务素材。

1. 首次启用与旧锁兼容

由获授权协调者在干净主目录 dev 执行一次：

./scripts/agentctl init
./scripts/agentctl hooks install
./scripts/agentctl doctor

init 只在主目录运行；明确初始化主仓唯一 .locks/state.sqlite 和身份文件，不能从 linked worktree 自动建立第二套状态。现有 .git/agent-control/dev-integration.lock 保留，用硬链接使 .locks/os/dev-integration.lock 指向同一 inode；旧操作未结束、旧锁忙或新旧身份不符均拒绝迁移。状态目录整体被 Git/Docker 忽略，禁止自行删锁/删库/复制 WAL/重建空目录。

status、doctor 只读，未初始化返回结构化错误而不创建文件；每次打开管理库都会核对旧新 dev 锁身份。hooks install 拒绝覆盖外来 hook 或既有自定义 hooksPath；不能把别人的保护脚本直接替换掉。启用前必须完成主目录集成，并让旧任务在下一次写/集成前读取本修订。

2. 创建任务并登记范围

从任一同仓工作区使用已验证工具：

./scripts/agent-worktree.sh create feature/task-id
# 输出 worktree 路径和本次实际 base_dev_sha；所有新任务显式来自当前 dev。
cd .worktrees/task-id
../../scripts/agentctl task register --id task-id --owner Codex --scope internal/example --scope .doc

示例名称、范围应替换为实际 task_id 与最小写范围；要维护 CURRENT 自己的行，task_id 与该行 task 字段一致。工具定位唯一主仓，不在任务区嵌套 .worktrees。分支只接受 feature/<task-id> 或 fix/<task-id>，重名/路径占用/符号链接均拒绝。旧目录清理由 Git 真实映射定位，不按名字猜测。

任务登记保存 owner、分支、worktree、源提交、允许写路径和能力；不隐式扩展已有登记。任务 scope 是允许范围，实际写许可由每次 with 获取。文件路径为仓库相对路径或目录前缀，. 表示全仓源文件范围，仅供明确需要的治理/集成任务；不能登记 .git、.locks 或运行数据作为源码写范围。

特殊能力按任务授权登记，例如 --capability docs:publish、git:dev、env:dev；test/main/shared 能力不能由普通 dev 任务顺带申请。能力字段记录的是已授予的任务边界，不自行产生用户授权。

3. 写操作与长驻客户端

# 每次命令包裹完整操作；不是先拿一次 fd 锁，再换一个 shell 假定仍持有。
../../scripts/agentctl with --task task-id --resource path:internal/example -- <command> <args>

# Git 暂存/提交用同一 supervisor 包住，另持任务自身的 index 锁。
../../scripts/agentctl with --task task-id --resource path:internal/example --resource git:index -- <git-write-script>

with 可包裹任务客户端或包含多条命令的受控脚本；不必由模型手工续租。它是非重入操作锁：不在持有某资源的 child 中再次申请同一资源。长期 worker 只持实施路径，不长期占共享文档/集成资源；提交、共享文档更新和 task close 由协调者在 worker 退出后以新的短操作完成。需要自主逐步提交的客户端使用逐命令 with，不套全任务的大锁。默认 child cwd 为登记的任务 worktree，只有明确环境/集成操作可选择主目录。代码审查、查询或读取不可变 Git 快照不必持写锁。--shared 仅供稳定读取，不能通过写操作 guard。

锁资源支持目录层级冲突；多个资源一次申请、全部获准才启动 child。同任务不同路径可并发；index 单独排他。每个执行器持工作区生命周期 SH 锁，删除必须取得 EX，防止检查完清理后又进入新任务。--wait 为有限秒数，默认立即拒绝冲突；失败给 request_id/holder，可做不冲突工作或用原 request_id 重试。没有后台无限排队服务，也不需要常驻产品容器。

会话身份包含 PID/start-time/boot、操作代次与 epoch；继承凭据只对真实 supervisor 的子孙进程有效。锁不会因超时自动转给别人；异常进程和未完成 operation 保留恢复状态。SIGINT/SIGTERM、孤儿子进程和未完成文档写回按实现的恢复门禁处理。

4. 共享文档：短锁、行版本和写回收据

当前提供 CURRENT 与 FEATURE-MATRIX 的受控更新；普通任务只改 CURRENT 中自己的 task 行，不能覆盖别人的状态或自行释放槽位。模块行使用现有唯一模块名称定位；重复/歧义 ID 拒绝。发布入口不是对旧文件的整份覆盖。

../../scripts/agentctl docs snapshot --file .doc/ops/CURRENT.md --record task-id
../../scripts/agentctl docs apply --task task-id --request /tmp/task-state-delta.json

请求格式（示意，hash 使用 snapshot 的实际结果）：

{"request_id":"task-id-state-1","changes":[{"file":".doc/ops/CURRENT.md","record_id":"task-id","expected_sha256":"<old-row-hash>","replacement":"| Codex | task-id | feature/task-id | .worktrees/task-id | module | in_progress |"}]}

新增行使用 expected_sha256: null。必须登记目标文件 scope 和 docs:publish 能力。工具在同一个短租约中重新读取、行级 CAS、保留其他内容、记录 operation、原子替换并保存文件 hash 收据。同一 request_id 同一请求重放不会重复写；更换载荷不能复用 ID。存在未经管理的本地共享文档改动时拒绝将它们混入收据，先保留现场并对齐正确基线。

多个文档先全部预检再写；中断留下可恢复的前后内容，不能把两个 rename 声称为任意文件读取者的一次原子发布。以同一 Git 提交作为持久发布边界。文件正常更新后，在自己的 task worktree 持对应 path + git:index 租约暂存/提交；hook 检查暂存文件 hash 与已生成收据一致。

FEATURE-MATRIX 从未完成升为 done 需要 docs:approve 和已在该任务 HEAD 提交的 evidence 路径，不能因任务退出自动关闭能力。仅有工具日志不等于产品验收。文档布局/焦点维护使用显式 docs:admin 与 record_id: "@document" 的整文档 hash CAS；它不能修改 CURRENT 集成槽位，也不能绕过模块完成证据规则。普通任务没有此入口权限。

5. 验证与候选集成

按验证契约选真实检查。工程工具自测入口：

python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v

冻结待交付提交 T。从最新 dev D 创建独立 feature/integrate-<id> 候选工作区并登记，合并 T 形成 --no-ff 节点 M；候选的两名父提交中第一名必须是 D。发生业务冲突回原任务修复。

# 在候选工作区：登记 candidate-id、实际写范围和 git:dev 能力。
../../scripts/agentctl validate --task candidate-id -- <verification-command> <args>
../../scripts/agentctl integrate --task candidate-id --expected-dev <D>

validate 要求干净树、记录精确 HEAD 与命令摘要；必要的实际命令/测试输出仍保存在任务验收证据。不能拿 true 替代验证契约。integrate 要求对应验证收据、干净主目录 dev、基线仍为 D，再接收同一 M；dev 前进则重建候选并重验，不能重用陈旧 PASS。

本地 hooks 检查主干直接提交、task 身份、暂存 scope/实际租约、共享文档收据与敏感运行路径；引用事务门禁复用同一候选父节点和 task-bound 验证检查；dev 还要求由 integrate 创建、绑定 old/new 的操作身份，不能借 with 的租约直接快进或 update-ref 绕过。test/main 仍需要各自明确授权的候选与能力。所有管理工具始终以主仓已生效版本为准，旧 worktree 的旧脚本不能代表新协议已接入。

6. 共享服务与镜像

# task 已获 env:dev；从主目录执行，源码须干净。
./scripts/agentctl with --task task-id --resource env:dev --cwd <main-root> -- ./scripts/env-service.sh dev rebuild

服务写动作在任何配置创建、网络或 Docker 调用前检查：调用目录与脚本目录都属于主目录、主分支为 dev、当前执行身份与目标环境租约有效。all 必须显式持有四个环境资源；不为方便隐式扩大权限。status/ps/logs 不初始化 env/data，也不要求写租约。

candidate-images-build.sh --commit SHA 要求实际源码 HEAD==SHA 且源码干净；仅允许现有 nightly 的固定 promotion-receipts 目录内未跟踪证据。它从该提交 git archive 到私有临时目录，Dockerfile 和上下文均来自不可变导出，不读取随后被其他操作修改的工作树或未跟踪证据。清单记录 source_tree/source_context；临时目录在退出时删除。镜像清单通过临时文件/fsync/rename 发布，避免截断 receipt 被当作完整证据。制品与报告版本分别记录；restart 不是新代码部署证明。

影响产品运行的变更合入后按授权更新 dev，核对实际镜像、挂载、schema、health/ready 与受影响业务。普通工程规范与本地治理工具更新无需重建产品容器。使用共享 dev 的长 E2E 持有环境租约到结束，不能让另一部署改变验收对象。

7. 查询、恢复与冻结

./scripts/agentctl status
./scripts/agentctl operation <run-id>
./scripts/agentctl recover --run <run-id> --reason '<现场检查与恢复依据>'

已结束且结果明确的请求可按 ID 查询；busy 不证明旧操作死亡。recover 仅在原 supervisor 和子进程组均已消失、物理锁可获得时继续；文档现场必须匹配该 operation 的原/目标内容，第三方变化则停止。外部 Docker/Git 未知结果必须先核对现场，理由写入恢复记录；管理器不能自动撤销已经发生的外部副作用。

必要维护可用 freeze/unfreeze 对已授权资源显式冻结，带 task 与 reason；有效持有者也不能绕过冻结。不能删除锁文件“解锁”，也不能恢复一份旧库后把旧租约自动标 active。损坏、身份变化、文件系统异常时停止受保护写入并交接。

8. 收口与清理

任务状态、集成、部署、远端同步和 cleanup 分别记录，见收口清单。命令结束不等于任务完成；task close 会拒绝仍有运行或待恢复 operation 的任务。

./scripts/agentctl task close --id task-id --status done
./scripts/agent-worktree.sh remove feature/task-id --delete-branch

清理由目录外的维护者执行，核对实际 Git 映射、dev 祖先、所有证据、tracked/untracked/ignored 文件、未完成 Git 操作、registry、生命周期锁和使用目录的进程。只用普通 remove/-d，拒绝时保留 cleanup_pending 和复查责任，不换成强制删除。

本机限制：无法读取某些同 UID 进程 cwd 时，工具不能证明其未使用目录，故保留 cleanup_pending；明确识别的 OS 用户 launchd（macOS）/systemd（Linux）管理进程有诊断性例外。进程 cwd 可见性走双路径：Darwin 用 lsof，Linux 用 /proc；测试中的删除正例可替换对应枚举以模拟可见主机，其余 Git/锁/文件条件为真实执行；可见占用、未知不可读、未合入、脏文件与活跃登记的拒绝另有真实/针对性测试。不要把这项限制转成跳过检查的通用开关。

保护任务、旧 detached 工作区和非本次产物不自动清理。用户未要求 push 时仅本地提交/合入；用户已要求时再按授权同步并核对远端引用。