Adaptive-Harness AGENTS.md

AGENTS.md

本文件适用于整个仓库。若子目录以后出现更具体的 AGENTS.md，以离目标文件最近的说明为准。

项目定位

Adaptive Harness 是本地优先、客户端无关的渐进式 Agent Harness。首版为 Python 3.12+ 的 CLI 与可嵌入 Runtime，核心目标是提供可信的工作区身份、能力边界、执行证据和完成门禁，而不是替模型增加固定的分析或开发流程。

当前仓库包含 v0.2 Runtime 前身实现和 v0.3 目标设计。阅读或交付时必须区分 implemented、partial 与 planned，不得把目标设计描述为当前能力。

事实来源

不同类型事实由以下文件分别负责：

• 产品目标、范围、不可破坏约束和验收边界：docs/adaptive-harness-prd.md
• 组件边界、依赖方向、权威关系和失败语义：docs/architecture/
• 机器协议：src/adaptive_harness/schemas/
• 协议版本和兼容政策：docs/contracts/
• 重要设计决策及原因：docs/adr/
• requirement、实现、测试和发布证据映射：docs/acceptance/traceability.md
• 实现顺序：docs/v0.3-observability-evolution-sprint-plan.md

这些来源按领域分工，不互相覆盖。发现矛盾时停止实现，记录冲突并修正相应事实来源，不得自行选择最宽松解释。

架构边界

• Kernel 不得依赖 Observability、Experience 或 Evolution。
• Observability 和 Experience 是派生层，不得参与 capability、approval 或 completion 判断。
• Evolution 只能协调注册 Manager 执行 mutation，不得成为 canonical config、Capability 或 Completion authority。
• 新增跨领域依赖前必须更新 dependency rules、architecture overview 和相应测试。
• planned 能力不得在代码、文档或交付报告中描述为 implemented。

不可破坏的约束

• 最小内核包含 Task Envelope、Capability Gateway、Executor、Verifier 和 Task Store；这些组件及其安全 invariant 不可关闭或被可选模块削弱。
• 按 capability、真实副作用和环境治理操作，不按任务名称或命令字符串推断安全性。
• 模型声明、自评和模板输出不能作为完成证据；completed 必须由当前任务的合法 acceptance evidence 支持。
• 权限取交集、限制取最严格值、deny 优先。未知字段、未知副作用和越界路径必须拒绝或升级审批。
• required acceptance 不得由模型自动删除；base SHA 在同一任务内不可改变；失败和不利证据不可覆盖。
• observe 与 enforced 必须如实标注。无法确认客户端具备拦截能力时使用 observe。
• 默认本地、离线、零遥测；不得回显 secret，也不得把未经脱敏的数据写入模型上下文或导出物。
• 初始化和配置修改必须先展示 diff、经用户确认后原子应用；失败时恢复原状态。
• Authority 归属与 contract execution 是两项独立职责。每个 canonical owner 必须在 authoritative write/publish 前、canonical read 返回可信数据前执行完整版本化 contract；producer 校验与 integrity digest 都不能替代该边界。
• PRD 中每条验收 requirement 必须有唯一稳定的 F-xxx-Ryy；covered traceability 必须引用存在的 pytest node ID和已登记 contract ID。路径存在只证明追踪链完整，不能替代语义 coverage review。

预期结构

实现代码放在 src/adaptive_harness/，按架构控制面中的边界组织：core/、cli/、adapters/、scanners/、modules/、templates/、feedback/ 和 schemas/。测试放在 tests/，测试数据放在 fixtures/，设计与用户文档放在 docs/。