Agent Notes 是 Cherry Studio 仓库内的一套决策记录规则与协作流程，用于在代码之外保存可再次审视、可追溯的决策依据。它明确定位：Agent Notes 不替代当前代码、参考文档、issue 或 PR 讨论，只补充决策层信息。
用途与触发条件
- 每个由人编写的 PR 必须声明一条 Agent Note，或写明 N/A 理由；自动化生成的 PR（仓库工作流、Dependabot）不受该元数据要求约束，但仍须通过常规校验。
- 改动类别（class）只标明决策主题，不强制所有笔记都从 proposed 起步；初始生命周期取决于目标是否需要在实现前获得人工同意，以及决策是否已经落地。
- 局部或机械性修改，若只是恢复既有约定且不存在持久取舍，使用 N/A。
- 当修复改变失败行为、兼容性、安全性、并发、原子性、生命周期等根因不写明就可能被反转的选择时，应在同一 PR 中编写 implemented 状态的缺陷修复笔记。
- 小型且已完成的测试或其他持久决策，若未达到 Spec 先行门槛，可以 implemented 状态进入其所属类别。
- 实质性功能、架构、流程与简化工作，应从 proposed 的 Spec 开始。
- 当行为、归属、验收标准（AC）、备选方案或风险需要在实现前获得人工同意时，任何类别都从 proposed 开始。
先检查现有树
- 按领域术语、机制名、路径和被否决的备选方案搜索，将结果分类为：新增、同一归属、部分取代、完全取代。
- 尽可能更新已有归属笔记；部分取代的笔记保持活跃并互相交叉链接。
- 完全取代必须保留每一条独有理由、备选方案、后果与验证事实；删除旧笔记需要明确的人工批准。
- 目前还没有 archived 生命周期；不得因时间久远、合并状态、代码迁移或措辞过时而归档。完全被取代的笔记保持活跃并交叉链接，直到另行批准的归档设计提供活跃优先检索、后继发现与对应门禁。
Spec 先行栈流程
- 创建底部的 Spec 分支和 proposed 双语笔记。
- 为可观测的验收标准分配连续的 AC 编号，并指定验证负责人。
- 通过 gh-create-pr 创建 Spec PR，该 PR 即为 This PR。
- 检查 GitHub 评审，要求存在 commit id 等于当前 Spec head 的显式 APPROVED 评审；批准不要求合并。
- 批准后，用 gh-stack 创建实现层，每个 PR 链接 Spec 并列出其 AC 覆盖。
- 行为、归属、AC、备选方案或风险的实质变化应落在 Spec 分支上，重新 rebase 上游并再次要求批准。
- 最终层将三项配对产物移到 implemented/，用现在时重写已发布现实，并将每条 AC 映射到实际证据。
最终层判定与验证
- 决定第 7 步前运行 gh stack view --json。若退出码为 2，按 gh-stack 技能的远端发现流程处理；本地元数据缺失不能证明 PR 是独立的。
- 对栈而言，检查当前层和每个下层实现 PR，只汇总有实际运行验证支撑的 AC。中间层保持 proposed；只有累计证据覆盖全部已批准 AC 的最终层才执行状态转换。不得仅凭分支顺序推断最终性。
- gh stack sync 之后，对每个活跃 PR 基础重新运行 pnpm change:scope，并只重跑因作用域改写而失效的检查；同步成功不等于验证通过。
拒绝
- 只有明确的人工决定才能把 proposed 笔记转为 rejected；讨论、沉默和 CHANGES_REQUESTED 都不算。
- 仅当证据能防止可合理预见的重复错误时，才保留 rejected 笔记；否则关闭未合并的探索，避免仓库噪音。拒绝后应停止并关闭任何实现层。
验证
- 生命周期移动时，除 pnpm docs:check-notes、作用域配对的写入/检查、pnpm docs:check 与 git diff --check 之外，还要运行 pnpm agent-notes:check-transition --base <verified-spec-ref>。
- 转换检查器校验声明的方向与 AC 映射，从不决定拒绝或栈是否完成。只报告实际运行过的证据。
限制与暂未提供
- 资料未说明该规则的适用范围之外的工具实现细节、界面形态、收费或价格信息。
- 资料未提供 archived 生命周期，也未提供独立归档设计。
- 资料未提供具体的失败示例数量、性能数据或效果指标。