Agent-System/.doc/audit/2026-09-21-agent-policy-review.md

title, status, created, owner, reviewed_dev_sha, implementation_status

title	status	created	owner	reviewed_dev_sha	implementation_status
Agent 工作规范增删改审查	done	2026-09-21	Codex	a241e83815	not_started

Agent 工作规范增删改审查

结论

现有方向合理：任务 worktree、主目录保护、串行集成、真实证据和安全清理应继续保留。当前最值得做的是消除冲突、减少重复维护、让关键门禁可执行，不是继续扩充一份越来越长的 AGENTS。

本轮建议集中为 10 组增删改与 2 项安全补充观察。它们不都是缺陷：下文区分已验证问题、流程简化建议与已有方案的实施事项。只形成审查结果，没有修改生效规则、脚本、锁、运行环境或业务代码。

已确定的用户选择不重新讨论：全部新增写入走 .worktrees；锁先交付统一入口与提交门禁防误改，OS 权限隔离后续实施；本轮是规范审查，不是实施授权。

1. 审查范围与现场

冻结基线为本地 dev@a241e838，审查在 .worktrees/agent-policy-review 进行。覆盖 AGENTS、PROJECT、worktree 工作规范、Cursor 四条规则、任务/收口/handoff 模板、Herdr roster，并检查相关脚本与测试入口。

主目录采样为干净 dev；未 fetch 或推送。本轮新分支只写审查记录和自己的 CURRENT 快照，不修改被审查规范。

实际测量：

• 基线 CURRENT 并行认领共有 161 条：158 条 done、2 条 in_progress、1 条 cancelled。新增本轮认领后为 162 条；不把本轮新增记录算成基线问题。
• 基础启动链六份文件合计 71,205 字符，这是文件字符数，不是模型 token 数或耗时指标。
• CURRENT 焦点有 5 项，而 AGENTS 要求 1–3 项；其中长期红线混在当前焦点中。
• 之前的规范收口 d5302a76 与 .locks 方案 5987bdcd 均不是本轮基线 dev 的祖先，不能把它们当作所有 Agent 已能读取的生效规则。
• 本轮没有运行 Go、前端、数据库或产品 PI 测试；命令问题来自源码筛选条件核查，不宣称本轮复现了产品运行故障。

2. 优先级总表

“先修”是工程流程优先级，不改变产品 FEATURE-MATRIX 或 production_ready。

ID	类别	建议动作	优先级	直接收益
R01	已验证冲突	修改测试范围与验收模型规则	先修	消除纯文档也被要求真实 PI 的矛盾
R02	已验证命令问题	修改真实 PI 示例为准确、可核验的入口	先修	避免漏测而误以为完成全链路
R03	流程简化建议	新增任务分级，允许一个主文档承载小任务	第二批	少建重复记录，减少共享文件写入
R04	已验证膨胀/不一致	精简 CURRENT 和启动读取范围	第二批	活跃冲突更易发现，降低每轮上下文成本
R05	已验证状态矛盾	修改会话结束与任务完成定义	先修	防止为了结束会话把未完成任务写成 done
R06	已验证过强要求	删除固定五层提交顺序，保留逻辑原子性	第二批	代码与测试一起可验证、可回退
R07	已验证引用问题 + 结构调整	确立规范唯一来源与生效版本	先修	避免客户端副本、草案和历史记录互相覆盖
R08	规范增强建议	新增任务授权记录与例外处理边界	第二批	授权内持续执行，超范围才停下确认
R09	已知方案实施事项	优先落实最小工具门禁	与先修并行规划	把已知运维误操作挡在执行前
R10	收口流程增强	明确清理执行者、保留原因和复查触发	第二批	已完成 worktree 不再长期无主积累

3. 具体增删改

R01 修改：测试要求必须按变更范围生效

依据：AGENTS.md:118、PROJECT.md:118 明确纯工程规范/文档不调用产品 PI；.cursor/rules/test-reports-standard.mdc:49,61 仍要求报告包含全量 Go 回归，并在报告生成前做真实 PI 全链路。后者是 alwaysApply。旧收口分支虽包含相关澄清，但尚未进入本轮基线 dev。

后果：Agent 依据不同入口可能运行无关长测试、误动共享服务，或把必要测试当作可选。冲突本身应先消除，不能依靠“Agent 应该理解”。

建议修改：测试范围统一在一处定义，PROJECT 和客户端规则引用它：

变更	必要验证
纯规范/普通文档	差异、链接、状态与指令一致性
治理脚本	沙盒临时仓库中的真实分支、锁、退出与拒绝路径；不以 shell 语法检查替代行为验证
Go/接口	对应单测、项目 Go/架构门禁，受影响 PG/鉴权负例
前端	对应测试和构建；受影响交互用真实浏览器
迁移/运行配置	独立环境升级、兼容性、回退/前滚条件及就绪验证
产品 Agent/工作流	受影响真实产品 PI 链路；不得以 stub/SKIP 替代

固定七段报告模板改为“完整报告模板”，小型文档/脚本验证可用精简报告或任务内验证节；必须保留实际命令、结果、提交与适用范围。不要删除真实性要求，也不允许把未运行记作 PASS。

模型要求按目标环境的已批准配置核验并记录实际值。PROJECT.md:118 的固定 M2.7-highspeed 不能不分环境套用：当前 dev Compose 默认 M2.7-highspeed，而 test/main Compose 默认 M3。这里是配置源码差异，未检查运行中的秘密配置；建议保留环境策略，禁止为“满足文档”自行切换模型。

R02 修改：真实 PI 命令要准确选择测试并证明没有跳过

依据：PROJECT.md:91–92 使用 RUN_PI_E2E=1 ... go test ./... -run 'PI'。测试名 TestPiAgent_FullLifecycle_MultiRole_RealWorld_E2E（internal/server/piagent_e2e_test.go:66）及 TestWorkflowGovernance_PiAgent_PG_*（同模块的 workflow_governance_piagent_pg_test.go:264,278,293）不匹配大小写敏感的 PI。

后果：命令执行范围与“全链路”的名称不一致；配置缺失还可能让数据库用例跳过。退出码 0 不能单独证明验收完成。

建议修改：优先引用已有 scripts/run-nightly-real-pi.sh 作为明确基线入口，写清独立 TEST_DATABASE_URL、Runner 认证、KB/运行环境要求。该脚本当前仅选 U8 和 FullNoneMixedChain 两类测试，不能把它表述为覆盖全部工作流；任务按变更范围追加精确测试名与浏览器验收。增加 expected-tests 与实际执行/SKIP 对照，保存最终提交、配置与证据。

不得在文档中填写真实凭证，也不运行测试来试探生产数据。

R03 新增：任务分级；删除小任务必须重复建多份记录的要求

依据：AGENTS.md:12,37,41–44 要求任何任务落盘、任务文、研究/审计产物、验收及交接；没有最小产物集或合并记录的规则。

建议：保留“需要审计的工作必须有持久证据”，明确三档：

• 信息答复：解释已有结果、查询简单状态，且不产生新决策、持久成果、仓库写入或运行副作用，可直接答复；不为一次答复单独开 worktree。若要写入任何成果，仍进入任务 worktree。
• 单一小任务/有价值的只读审查：一个任务文或专用 audit/research 主文档可同时承载范围、结论、验证、状态和交接；不强制再复制同一内容到另外三份文档。
• 跨模块、多阶段、数据/部署任务：完整 task、必要 plan、验证报告、handoff；仅在信息确实独立时拆文件，互相链接而不复制全文。

本次这样的实质规范审查仍须落盘，不能以“只读”免除证据。将相关追问、修正与收口归入原 task_id；只读子审查使用父任务的范围和记录，不为每个 reviewer 再开业务任务链。无关新增任务才从 dev 建新分支。

这项改变需要审核采纳；本轮仍遵守现有落盘规则，没有提前使用豁免。

R04 修改：CURRENT 只承载活跃协调，历史留索引

依据：CURRENT 161 条认领中 158 条已完成；AGENTS.md:132 要求 1–3 焦点，当前正文有 5 项。

建议删除/迁移：从 CURRENT 活跃表移出已完成/取消且没有后续阻塞的行，历史 owner、branch、worktree、证据在归档任务/历史索引保留。将长期红线独立为受控约束区或链接；它不是每天反复排序的焦点。

建议保留：正在进行、阻塞、等待集成及仍需清理的事项。cleanup_pending 是清理/操作阶段，不新增为 task.status 的第六种状态；一行可写任务 done、cleanup pending，并给 owner、原因和下次检查条件。

启动读取修改：每会话先读短核心规则、项目入口、活跃状态摘要；编码前按范围补读相关模块标准、相关 FEATURE-MATRIX 行、任务/方案及操作规程。发布才读完整发布门禁。不要通过摘要跳过硬红线，也不要要求每次解释一个已知结果都重读全部历史。

模块开发任务应有明确条件指针指向已有 .doc/system-design/2026-09-20-module-development-standards.md，复用现有接口/事件/表写者规则，不新造一套编码规范。

R05 修改：会话结束、任务完成、合入与清理分别判定

依据：收口模板第 3 行适用于“任务完成或切换 Agent”，第 22 行却无条件要求 status=done；AGENTS 同时允许 blocked/cancelled。任务模板已有 deployment/cleanup 字段，但缺少明确的结果判定与集成/同步状态。

建议替换收口条件：

会话结束不等于任务完成。根据实际情况保留 in_progress、blocked、cancelled 或 done；只有任务范围内的验收条件满足才能 done。换 Agent 必须记录剩余工作及接管条件。只有终态任务才归档；不得为了归档改成 done。

为任务记录补充按需字段：review_state、integration_state、deployment、cleanup、remote_sync。例如“方案研究 done、review pending、未合入、deployment not_required”是合法状态；“代码已合入、部署 failed”不能报交付完成。字段由工具生成优先，避免人工重复维护多张表。

研究/审查的验收是有据可审的产物，不要求把未获实施授权的方案部署到 dev。实现任务的 done 则按其获授权交付范围判定。收口报告始终区分本地提交、dev 合入、实际运行版本和远端状态。

R06 删除：固定按数据库、服务、API、测试、文档分层提交的硬性顺序

依据：.cursor/rules/git-workflow-and-environments.mdc:33–38 规定“一个任务必须”按五类依次提交；AGENTS 的原子提交目标是一个逻辑变更一批。

后果：小修复也被机械拆分，代码与对应测试分离；一些提交无法独立构建/验证，回退时还可能留下半套契约。

建议替换：

每个提交围绕一个可解释、可验证、可回退的逻辑变更；实现与其回归测试可同批。迁移、兼容阶段、配置或文档只有在独立审查/回退有价值时拆分，不要求每项任务凑齐固定提交层次。

保留 Conventional Commits、明确文件范围、渐进式交付和独立 worktree；不以“原子”为名把无关改动揉成一批。

R07 修改：规范来源、生效状态与客户端薄入口

已验证的小错误：.cursor/rules/git-secrets-autonomy.mdc:2,8 把 Secrets 指向 AGENTS §8，实际在 §9。AGENTS 开头称可整文件复制到任意项目，但正文包含本仓库日期路径、脚本和 Herdr 约定；应改为“可复用基线，项目路径/流程需调整”。

建议新增规范生命周期：每项规则记录 proposed/approved/active/deprecated 的规则状态、适用范围、生效提交与 owner；工具能力另记 manual/enforced。这里是规则生命周期，不复用任务 status。

外层系统约束和当前用户授权仍有效；项目内部规则冲突时有明确处理：AGENTS 保存通用硬边界，PROJECT 定义其授权范围内的项目细则，专门 runbook 负责操作流程；客户端入口只引用同一来源，不复制一套近似规则。草案、旧审计和历史报告属于证据，不能自行覆盖生效规则；较新的日期不等于已生效。

此前收口和锁方案未进入当前 dev，说明“已经写好/提交”与“已被所有新任务读取”必须分开。旧任务启动时记录 policy revision，集成前重读当前 dev 的相关生效规则；期间发生变化时做差异检查，不默默套旧规则，也不突然按未来未实施机制阻塞旧任务。

删除 PROJECT 中重复的“当前已无 blocker”等长期硬编码断言，改为引用有日期/制品身份的权威门禁结果。模型、schema、角色可用性等动态值记录在环境/执行收据中；不要在多个入口重复写一份可能过期的“当前值”。

R08 新增：任务授权记录与例外边界

这是一项规范增强建议，不是声称现有 Agent 已越权。现有手册限制自动审批扩权、push 和破坏性操作，但任务模板只有范围/非目标，没有统一记录“这次到底获准做到哪一步”。

建议任务创建时记录：任务类型（研究/实现/运维）、用户目标、允许写路径、可执行环境、交付终点及明确禁止项。已授权范围内自主持续执行，不在每个 Git/测试步骤重复确认；分析和方案请求默认不包含业务实施。

只有扩大业务范围、增加外部写入、操作未授权环境或破坏性恢复等才重新确认。push 仍遵守明确授权规则；凭证存在不代表允许推送。合理默认写进任务模板，不用每次都问用户一张权限问卷。

紧急/迁移例外需记录 owner、原因、范围、期限/退出条件和恢复动作；例外仅覆盖明确条款。AGENTS.md:29 的紧急热修免启动阅读不能被解释为允许主目录直接开发、删库或取消验收。

R09 落实：先做最小执行门禁，不再只增加禁止句

这是上一治理/锁方案已承认的工程任务，不作为“新发现的缺失要求”重复计数。

已有证据：AGENTS 已禁用旧 helper 的 create/remove；源码仍包含省略 dev 起点和强制删除。env-service 的根目录来自脚本所在树，缺少执行目录/锁守卫。CURRENT 第 11 行及关联 MinerU 报告已记录一次 worktree rebuild 引起数据挂载漂移，说明风险并非仅理论；本轮未重演该事故。

建议实施顺序：

1. 修 worktree create/remove 的明确基线、主仓定位和安全删除。
2. 给共享服务写操作加主目录/dev/操作身份/持锁前置检查，明确 status 等只读入口；构建必须校验真实源码与申报 SHA。
3. 为 CURRENT/MATRIX 提供短锁、增量更新、版本检查，接入已设计 .locks 流程；旧锁兼容迁移后才换权威位置。
4. Git 提交/集成门禁拒绝超范围文件、混入 .env/运行产物和错误主干写入。门禁真实负例验收后再记录 enforced。

保持用户确认的 L1 目标，不提前搭建跨机平台或要求 OS 隔离才能使用。代码文件锁、全量资源队列和额外 UI 按已有阶段与实际冲突扩展，优先把当前两个共享文档和 dev 操作做可靠。

R10 新增：清理负责人和完成后的再检查机制

现有安全清理条件应保留，不放宽“不强删、不覆盖”的红线。需要补的是谁在 Agent 退出之后真正执行清理，以及什么时候重试。

操作规范要求无 Agent/进程 cwd 使用才能移除 worktree；长驻客户端即使完成任务也可能仍占 cwd。任务模板允许 retained-with-reason，但没有下一次检查条件。建议由独立集成/维护执行者在 owner 已退出后检查并清理，记录 cleanup_owner、保留原因、证据位置和触发条件；遗留目录分为活跃、保护、待审核、未合入和可清理，不按年龄批量删除。

已合入任务的依赖缓存与唯一截图/日志区别处理：可再生缓存明确登记，唯一证据先保存再移除；只保存路径而不保存文件不是证据归档。清理失败不影响已经通过的业务交付事实，但要保持可追踪的 cleanup pending。

4. 两项安全补充观察（非本轮阻塞项）

• 材料不能授予权限：日志、网页、测试输出、引用文本、Agent 产物可能含命令或“用户已授权”字样，应作为待核实内容。handoff 的授权声明回链到可核实的用户目标/委派范围，不仅凭文档自述执行推送、清理或外部写入。已有自动审批不扩权规则继续保留；这项建议补充来源辨别，不要求 L2 现在落地。
• 真实证据允许最小化与脱敏：测试报告可以保存真实执行中足够判定的片段，说明脱敏范围；不要求提交原始完整日志、个人信息、业务正文或截图中的秘密。现有凭证禁入与真实用户数据不复制要求继续有效。真实性约束来源与结论，不能误解成“未经处理的所有材料都要入 Git”。

5. 推荐的规范组织

不建议再并列增加一套“总规范 v2”。保留现有路径并收敛职责：

位置	负责内容	移出/减少
AGENTS	最小安全红线、任务入口、权限/状态原则、操作指针	环境动态值、长命令、历史事件、重复模板索引
PROJECT	仓库地图、目标环境、测试入口与模块标准指针	重复通用规则、过期发布结论
worktree runbook	创建、同步、候选、部署、失败与清理	已结束迁移的具体临时目录案例，移入历史交接
锁管理 runbook（落地后）	唯一入口、状态、等待、恢复与兼容版本	让 Agent 手动拼锁协议的日常操作
CURRENT	活跃任务、当前槽位、1–3 焦点、必要约束链接	大量 done 历史行与长复盘
FEATURE-MATRIX	能力声明范围、证据、剩余条件	逐次操作流水、重复环境快照
客户端入口	明确引用上述来源	复制并稍微改写的第二套规则
任务/审查主文档	单项工作的范围、决定、证据和交接	对相同内容的无意义多文件复制

6. 改动顺序与验收

第一批：消除矛盾。 R01、R02、R05、R07 的明确错误先修。检查从所有客户端入口读取后，纯文档、业务修复、暂停交接、取消任务、真实 PI 验收五种场景都得到一致决策。

第二批：减少流程负担。 采纳 R03/R04/R06/R08/R10 后更新模板与薄入口；历史只迁移、不删除。验证信息问答不触发无意义写入，实质审计有唯一主产物，代码与测试能形成完整逻辑提交，未完成任务不会被强制 done。

第三批：工具实现。 R09 与既有 .locks 分阶段方案合并为一个实施队列，不重复造项目。用两个并行任务、锁冲突、旧版本共享文档、错误工作区部署、异常退出和清理拒绝的真实证据验收。当前 user-approved 的 L1 防误改边界不变。

规范检查可以自动化为轻量 doctor/lint：本地链接、必需字段/状态、过期 waiver、活跃认领冲突、测试入口存在、脚本能力版本与规范声明对齐。没有明确规则契约的模糊 prose lint 不作硬失败，也不为文案偏好构造复杂测试。

7. 审查覆盖与可信度

使用 ce-doc-review 非交互只读流程，审查依据为上述实际文件及脚本，而非仅凭历史记忆。

审查视角	结果	本报告处理
一致性（独立上下文）	3 项	复用声明/引用合入 R07，焦点上限合入 R04
可执行性（独立上下文）	1 项	PI 测试筛选问题合入 R02，主审已核对源码
范围/减负（独立上下文）	3 项	合入 R03/R04；保留实质审计必须落盘，收窄纯只读豁免
安全（独立上下文）	2 项观察，置信锚 50	仅列为 §4 补充观察，不当作已证实漏洞
反例审查（独立上下文）	0 项新增缺陷	候选 SHA、失败恢复、累计部署差异等已有引用约束，未重复提出
主审当前源核查	测试范围冲突、状态模板、提交顺序、动态配置与工具事实	补充 R01/R05/R06 等；明确区分改进建议与已知实施项

外部第三方 CLI 跨模型复核未执行：本轮未获得向其他外部服务发送仓库文档的显式授权；未以此阻塞会话内独立视角审查。未更改技能或项目配置来伪造关闭该步骤。

未采纳的建议形态：不把纯只读豁免扩大到有持久价值的审计；不把 cleanup_pending 塞进既有任务 status；不要求当前实现 OS 级权限隔离；不因为当前 helper 明确标为未修复，就重复说规范已承诺了不存在的能力。

已应用规范修正：0。 上述均是待审核建议。本轮只写审查产物与任务记录，未升级 FEATURE-MATRIX、未改 production_ready、未运行产品测试、未合入 dev 或 push。

8. 相关资料

• 当前工作手册
• 项目入口
• 已采纳工作方式
• 既有治理方案
• .locks 补充方案：目前在 feature/agent-lock-coordination-plan@5987bdcd 的 .doc/remediation/2026-09-21-agent-lock-coordination-plan.md，不在本轮 dev 基线；后续合入时再建立普通相对链接。