Agent-Squad/policy/guidelines-adoption.md

通用规范采纳记录

• 项目/负责人：Agent-Squad / weichen
• 状态：active
• 规范位置：deps/development-guidelines
• 规范性文档目录：policy/
• 过程文档位置：任务卡在 .task/（.task/feature-governance-adoption.md）；任务主记录在 Gitea PR 中维护。既有过程记录仍按项目内固定目录豁免留在 docs/records/。过程记录不进规范库，也不写成与 Issue/PR 平行的第二状态。
• 版本权威：本仓 gitlink deps/development-guidelines @ 2688fd2be6a5（完整 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb，内容版本 0.1.0-draft.12，无已发布标签）
• 批准/生效依据：feature/governance-adoption PR（Agent-Squad）
• 替代范围和迁移说明：本次替代 2026-09-29 采纳的固定版本 26b562d2e34f（内容版本 0.1.0-draft.6），规则条目按 0.1.0-draft.12 重新核对。新增 AGENT-EXECUTION.md 执行路由、deps/development-manager gitlink（bd3a7de57a3a）、scripts/dm、scripts/agent-exec、scripts/task、scripts/hooks/pre-commit、.gitea/workflows/governance.yml 与任务卡模板。不改业务代码，不改既有 .gitea/workflows/ci.yml。此前迁移说明见 docs/records/2026-09-29-guidelines-and-observability.md。

规范/工作流	适用条件与范围	采纳或不适用理由	执行方式/证据
core/baseline.md	日常工作	编排库对外有失败关闭语义	manual
workflows/delivery.md、debugging.md、handoff.md	交付、排障与交接	跨仓组合需要可交接记录	manual
standards/collaboration.md	并行共同起点与组合升级	父仓 gitlink 锁定 Agent-Native 与基础库	manual
standards/merge-queue.md	多个就绪任务的最终同步、CI、Review 与合入调度	多个 agent 单元并行开发，合入须串行同步；协调者为仓库所有者	manual
standards/verification.md	验证与结论	GOWORK=off go test	manual；命令见 PROJECT.md（含 scripts/agent-exec validate --repo .、scripts/dm governance check --repo .）
workflows/design-verification.md、standards/testability.md、standards/failure-containment.md	规划、执行、HITL	conformance 覆盖公开 API	manual
standards/module-contracts.md	squad 与 agent-native 边界	依赖方向只允许 squad → agent-native	manual
standards/observability.md	HTTP 信封、trace、事件	接入错误码库与日志库	manual
standards/agent-execution.md	工程 Agent CLI 执行路由、会话隔离与受控集成	凡允许 AI 协助工程变更必须采纳；路由配置见 AGENT-EXECUTION.md；本库不实现 Agent	执行方式：AGENT-EXECUTION.md + scripts/agent-exec（validate / admit）；证据：governance check + 正负例（.task/feature-governance-adoption.md）
standards/tool-adaptation.md	为具体工具创建规则与钩子	本次引入 scripts/hooks/pre-commit（启用由 host/人执行，core.hooksPath）	manual；启用后以本仓 pre-commit 检查为证据
standards/multi-repo.md	多级 submodule	本仓 replace 是编译时的唯一依赖解析	manual
standards/data-reliability.md	运行目录、HITL 恢复、幂等回应	磁盘为权威	manual
standards/security.md	bash 权限挂起、脱敏	事件落盘沿用现有脱敏；凭证走环境变量	manual
standards/configuration.md	HITL 模式、规划器、日志配置	环境变量与 CLI 标志	manual
standards/documentation.md	三层文档	policy/ 与 docs/records/	manual
standards/release-operations.md	独立发布流水线	当前无制品仓库	不适用
workflows/automation.md	serve 内 15s wakeup sweep	有界、可手动触发；不另建定时系统	manual

项目差异

原规则/章节	项目采用方式	原因与风险	负责人/复查条件
documentation.md 过程仓默认独立仓库	其他过程记录放 docs/records/（既有过程记录的项目内固定目录豁免）	同 Agent-Native：避免个人项目再维护一个过程仓。风险是过程记录与代码同库	多人协作或对外发布时复查
documentation.md 过程仓默认独立仓库	任务卡与交付证据放 .task/（模板 .task/templates/task-card.md）	任务状态仍只认 Gitea Issue/PR，.task/ 不写成平行状态；风险是任务卡与代码同库	多人协作或对外发布时复查
multi-repo.md 组件说明不手写第二套 SHA	PROJECT.md 只写路径与角色，SHA 以 git submodule status 为准	手抄 SHA 会与 gitlink 漂移	每次依赖升级核对脚本

本次升级或首次接入验证

• deps/development-guidelines 固定 2688fd2be6a52c0bf110e7e6366b6f291ab5e4eb（内容版本 0.1.0-draft.12）；deps/development-manager 固定 bd3a7de57a3a9e1a4495b94c5fa5c08d71e7be8c。
• 工程 Agent 执行：AGENT-EXECUTION.md 为唯一路由权威；AI 实施单元只经 scripts/agent-exec run 执行，并经 scripts/agent-exec apply 集成。scripts/agent-exec 与 scripts/task 只是转调 scripts/dm 的薄入口。
• 登记为 active 的前置证据：一次成功执行正例（有效 completed 收据经 transport/admission 集成）；缺配置、无效终态收据、越权路径、未知副作用四类负例均被拒绝或 fail-stop。证据按 .task/feature-governance-adoption.md 记录。
• 入口核验：scripts/dm governance check --repo . 与 scripts/agent-exec validate --repo .（PROJECT.md「验证」节）。CI 由 .gitea/workflows/governance.yml 执行；既有 ci.yml 未改。
• 回退该规范挂载时，恢复上一已批准 gitlink 26b562d2e34f，并同时还原本次新增的治理脚本与 governance.yml；如已启用 core.hooksPath，需一并关闭。只还原规范 gitlink 不会把 deps/agent-native 移回根目录。

2026-09-29 追加：agent-intent 可选意图闸门

• 新增 deps/agent-intent（固定 55780ae2cce4ae98d8b0557b8234af8833a7c522）；deps/error-code-system 前进到 dbeed2f1b67eb417ce089e7033a228578fbbeb03（squad.intent_refused，追加式）；deps/agent-native 前进到 c659dc17d5086a8128999011994fc2dbe73419d3（其仓内新增 intentgate 装饰器）。
• 依赖边界新增：唯 squadintent 与 cli 组合根可 import agent-intent；squad/server/store 不感知意图；未配置意图时引擎行为与原实现一致。
• 接入与验证记录见 docs/records/2026-09-29-intent-gate-adoption.md；跨仓测试报告见 Agent-Intent 仓 docs/records。
• 回退：删 squadintent/ 与 cli 接线、go.mod 两行、submodule 与 .gitmodules 条目、一致性脚本对应段；可将 agent-native 回退到 cc8a6a7（其 intentgate 为可选包，不回退亦可编译）。

2026-09-29 追加（二）：目录驱动的编排

• deps/agent-intent 前进到 3674dc4bfd0b49191d21f0afab4002381e41a429（槽位约束与能力目录，E2/E4）；deps/agent-native 前进到 292142ac1a8b125488794e9374faee2cb1c8c579（pin 同步）。
• 新增能力目录（squad.IntentCatalog 数据视图）与系统功能步（StepSpec.IntentID + IntentRunner）；核心包仍零 import agent-intent。
• 接入与验证记录见 docs/records/2026-09-29-catalog-driven-orchestration.md。