Omnifocus-Agent-MCP: Instructions file for Codex

AGENTS.md

本文件用于指导 Codex / AI coding agent 在本仓库中工作。

本仓库是一个 safety-controlled OmniFocus MCP Server。任何修改都必须优先保持：

• 受控 mutation
• 显式用户授权
• Domain correctness
• 可验证行为
• fail-closed 安全边界

先读文件

开始修改前，先阅读：

• docs/PROJECT_STATUS.md
• docs/SOURCE_MAP.md

如果涉及具体功能，再阅读对应 ADR、设计文档和测试。

语言与沟通

默认使用中文进行对话、工作更新、审计结论和面向维护者的说明。代码标识符、命令、错误码、外部英文原文或已有英文规范可保持原文；用户明确要求英文时再切换。

真实状态判断

遵循 docs/SOURCE_MAP.md 中定义的真实状态判断顺序。

不要把旧 Phase 文档中的限制直接理解为当前能力。旧文档可能描述的是当时阶段边界，而不是当前生产状态。

当前生产边界

personal-production 是当前生产 Profile。当前生产 MCP surface 以 docs/PROJECT_STATUS.md 和注册测试为准。

稳定约束：

• personal-production 不暴露 Resources。
• create_task 与 create_project_skeleton 是当前允许进入 personal-production 的受控 mutation capabilities；两者均受各自 schema、feature gate、Ledger、lock 与 verification 约束。
• upstream-full 是更宽的兼容 surface，不代表生产默认能力。
• 不得从已有 primitive、legacy Tool 或 upstream-full 能力推断可以进入 personal-production。

涉及 Tool / Resource / Profile 变化时，必须检查：

• src/serverRegistration.ts
• src/serverRegistration.test.ts

架构边界

保持 Domain-first 架构：

Raw Query
-> Strict Adapter
-> Domain Semantics
-> Mapper / Composer
-> MCP Tool

规则：

• MCP handler 不承载核心业务语义。
• 不绕过 Adapter、Domain schema、Mapper、Composer 或 verifier。
• 不因为 Tool 输出缺字段而直接暴露 generic raw query。
• direct / effective / source 语义必须保持可测试。
• Domain 层表达事实，不写入 AI recommendation、priority、risk 或 health 判断。

Change Scope

默认保持小范围修改，优先解决当前目标问题，并沿用现有架构边界。

未经明确要求，不进行：

• 大规模重构
• 目录重组
• API 统一
• 抽象层合并
• 将相邻但未授权的能力顺手纳入本次改动

如果发现更大的结构问题，先记录和说明，不要把它混入当前任务。

Mutation 安全边界

不要把分析、建议、计划、推断或未来意图转换为 mutation。

任何新增或扩展 mutation 能力，必须先有明确设计评审，并满足：

• 显式用户授权
• 有限 mutation set
• preview / confirmation 或等价的目标绑定证据
• auditability
• fail-closed 行为
• 幂等 / replay / duplicate protection
• 写后 verification
• 清晰的 mayHaveWritten / retrySafe 语义

未经明确设计批准，禁止：

• generic CRUD framework
• generic mutation executor
• name/path mutation resolver
• fuzzy matching
• fallback 到 Inbox / Project
• 自动创建 Tag
• 静默省略用户要求的 Tag
• edit / move / reparent / complete / delete existing task
• batch CRUD
• repeat / notifications