# Agent worktree 与 L1 操作规范

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

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

## 1. 首次启用与旧锁兼容

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

```bash
./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. 创建任务并登记范围

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

```bash
./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. 写操作与长驻客户端

```bash
# 每次命令包裹完整操作；不是先拿一次 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 拒绝。发布入口不是对旧文件的整份覆盖。

```bash
../../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 的实际结果）：

```json
{"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. 验证与候选集成

按[验证契约](./2026-09-21-validation-contract.md)选真实检查。工程工具自测入口：

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

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

```bash
# 在候选工作区：登记 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. 共享服务与镜像

```bash
# 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. 查询、恢复与冻结

```bash
./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 分别记录，见[收口清单](./templates/session-close-checklist.md)。命令结束不等于任务完成；task close 会拒绝仍有运行或待恢复 operation 的任务。

### 8.1 只读盘点（先盘点，再人工处置）

```bash
# 批量 worktree 清理就绪度；verdict=ready 才可考虑 remove。从不自动删除。
./scripts/agentctl cleanup report

# FEATURE-MATRIX 状态漂移：硬告警仅 done→非 done（ISSUE-20260923 工具化）；
# open_capabilities 为人工判断候选。从不自动升 done / 写 MATRIX。
./scripts/agentctl docs drift
```

daemon 前台循环可按 `--audit-every N`（默认 30）周期跑上述盘点；**不在 daemon 内调用 `docs apply`**（主目录 cwd 必 `WORKTREE_MISMATCH`）。常驻 systemd/launchd 装载需独立授权，本规范默认不装载。

### 8.2 关闭与删除

```bash
./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 和复查责任，不换成强制删除。盘点只读；删除仍人工；拒绝即保留 cleanup_pending。

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

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

### 8.3 CodeGraph（治理加速器）

- `agentctl init` 与 `agent-worktree.sh create` 会 best-effort 初始化/同步 `.codegraph/`（CLI 缺失则跳过，不阻断）。
- `hooks install` 安装 `post-merge` / `post-checkout` → `hooks codegraph-sync`（fail-open，永不阻断 integrate）。
- 会话启动执行 `codegraph sync -q`。索引是 tree-sitter **近似**：有假阴性；**grep 是完整性唯一权威**；重命名与穷举调用方必须 grep 确认。