From 2002ac470f50f6821fffd4db4aa9d30928435ea3 Mon Sep 17 00:00:00 2001
From: Yuimi_Chaya <124485273+Yuimi-chaya@users.noreply.github.com>
Date: Mon, 10 Aug 2026 21:12:20 +0800
Subject: [PATCH] Sync repository with current AGENTS policy

---
 CHANGELOG.md                                  |  8 ++
 README.md                                     |  6 +-
 reference/AGENTS.md                           | 54 +++++------
 references/interview-schema.md                | 69 ++++++++++++--
 references/rule-catalog.md                    | 38 +++++---
 scripts/validate-repository.ps1               | 90 ++++++++++++++++++-
 skills/maintain-development-notes/SKILL.md    |  6 +-
 .../agents/openai.yaml                        |  4 +-
 workflows/ADOPT.md                            | 35 +++++---
 workflows/UPDATE.md                           | 21 +++--
 10 files changed, 247 insertions(+), 84 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 65102d7..1fad5dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0 - 2026-08-10
+
+- Synchronize the reference policy with the current 15-rule `AGENTS.md`.
+- Add per-turn preflight and note-reading decisions, Git recovery checkpoints and rollback safety, capability-aware subagent escalation/routing/retry policies, and visual review transfer budgets.
+- Extend adoption and update workflows with Git state inspection, recovery-point planning, capability fallbacks, and media constraints.
+- Strengthen cross-file validation so outdated catalogs, interviews, workflows, or reference blocks cannot silently pass.
+- Require the development-note Skill to re-read current instructions and recovery notes at the start of every project-work turn.
+
 ## 0.1.1 - 2026-08-01
 
 - Split development-note behavior into independent read and write gates.
diff --git a/README.md b/README.md
index f7603a6..c825d2c 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 一套供本地 Agent 与用户共同审阅、按需采用的开发规范参考，以及用于复杂项目上下文恢复的 `maintain-development-notes` Skill。
 
-本仓库不会把参考 `AGENTS.md` 直接覆盖到用户目录。终端偏好、资源并发、子代理策略等属于用户决策，即使 Agent 能检测当前环境，也必须逐项解释并询问。只有在全部必答项完成、语义冲突逐项处理、最终 diff 获得明确确认后，本地 Agent 才能修改文件。
+本仓库不会把参考 `AGENTS.md` 直接覆盖到用户目录。终端偏好、逐回合预检、Git 检查点、资源并发、子代理能力路由和媒体审查预算等属于用户决策，即使 Agent 能检测当前环境，也必须逐项解释并询问。只有在全部必答项完成、语义冲突逐项处理、恢复点确认、最终 diff 获得明确确认后，本地 Agent 才能修改文件。
 
 ## 仓库内容
 
@@ -37,6 +37,10 @@ workflows/ADOPT.md 和 references/interview-schema.md 与我逐项讨论。
 - **最小修改**：保留用户现有内容、编码、BOM、换行和文件结构。
 - **能力诚实**：平台不支持指定子代理模型或推理档位时，必须说明，不能声称已经配置。
 - **先读后做**：遇到问题、选方案或恢复工作时，先检索既有笔记中的相同场景、用户偏好、已否决方案、总体方向和权威状态，再调查和修改。
+- **每轮预检**：项目回合开始时确认 Shell、工作目录、任务范围和 Git 状态，并重新读取最新适用指令与恢复笔记。
+- **可恢复检查点**：多文件、已验收功能、状态/配置、媒体或返工前，使用任务级本地提交或仓库外二进制补丁保护现场；发布权限另行确认。
+- **能力路由而非模型幻觉**：`luna`、`terra`、`sol` 只是参考角色映射，安装时必须检测真实能力并由用户确认等效路由。
+- **媒体轻量审查**：保留原图，发送受尺寸、质量和批量体积约束的审查副本；透明或像素细节使用无损裁切，禁止把图片 base64 塞进线程。
 
 ## Skill 安装
 
diff --git a/reference/AGENTS.md b/reference/AGENTS.md
index 787351c..d64d2b2 100644
--- a/reference/AGENTS.md
+++ b/reference/AGENTS.md
@@ -1,43 +1,31 @@
-你是我的编程助手，必须遵守以下规则。
+你是我的编程助手。以下为硬规则；与更高优先级指令冲突时，以更高优先级指令为准。
 
-## 环境与终端
+## 开工与记录
 
-1. 默认环境：中国大陆网络 + Windows + PowerShell 或 Git Bash。
-2. 执行命令前必须判断当前 Shell；PowerShell 不准当 bash 用，Git Bash 不准当 PowerShell 用。
-3. 命令失败后禁止原样重复执行；必须分析原因，并换用当前 Shell 支持的等价命令。
-4. PowerShell 中禁止使用 bash 专属写法：`sed`、`awk`、`grep`、`rm -rf`、`touch`、`export`、`cat <<EOF` 等。
-5. 安装依赖或下载失败时，优先考虑大陆网络问题；只允许使用本次命令的临时镜像源/代理，禁止擅自修改全局 npm/pip/git/proxy 配置。
-6. 当当前环境多次阻碍任务推进时，不应持续使用低效或反复失败的绕过方案。对于 Shell 版本或能力不足、缺少必要依赖、工具不兼容，或存在明显更合适的可下载工具等情况，可以暂停操作，向用户简要说明阻碍、已尝试方案、推荐工具及收益、来源、版本、安装范围和潜在影响，并询问是否允许下载或安装。未经明确同意不得执行；获准后也只安装完成当前任务所需的最小范围，优先免安装、临时或项目级方案，禁止擅自修改全局配置、默认 Shell，或替换、卸载现有工具。
-7. 所有路径必须加引号，尤其是中文路径、空格路径、括号路径。
+1. 每个涉及项目工作的回合，在诊断、计划、写入或测试前，先确认 Shell、工作目录和任务范围；若为 Git 仓库，同时检查 `git status --short`、当前分支和 HEAD，不得影响用户的无关修改。
+2. 每轮开始前必须阅读最近的 `AGENTS.md` 和已有的 `DEVELOPMENT_NOTES.md`、`HANDOFF.md` 或等价笔记，长笔记可用 `rg` 定位相关段落，但禁止只写不读。确认根因、改变方案、完成测试、真人验收、备份、回滚、提交或推送后及时更新；复杂长期项目自动使用 `$maintain-development-notes`。纯聊天和与项目无关的短查询可跳过。
 
-## 编码与文件安全
+## Git 检查点
 
-8. 中文文件可能是 UTF-8、GBK、CP936；看到乱码时禁止判断文件损坏，禁止擅自转码、重写、格式化。
-9. 新建文本文件默认 UTF-8 without BOM；修改已有文件时必须尽量保持原编码、原换行和原结构。
-10. 允许在命令、代码标识符、配置键、脚本中优先使用 ASCII；禁止因此删除、替换、转义已有中文内容。
-11. 修改文件必须最小化，只改任务相关内容；禁止无关重构，禁止删除用户内容。
-12. 遇到删除、覆盖、批量修改、批量转码、全局配置、编码不确定、图片版本不清楚、视觉判断主观时，必须先问用户。
-13. UI/图片判断要保守；不确定就问，不要把旧图、错图、临时图当最终结果。
+3. Git 项目必须保持可恢复检查点。修改已验收功能、视觉/媒体、状态机、全局配置、多文件逻辑，或开始第二轮返工前，先确认有效恢复点。
+4. 优先创建只包含本任务文件的本地提交；工作区含无关修改或暂不适合提交时，先在仓库外生成 `git diff --binary` 补丁或等价原样备份并报告路径。稳定里程碑或真人验收后及时建立本地检查点，除非用户明确要求，否则不得推送。
+5. 禁止把无关文件、未跟踪素材或他人修改混入检查点；避免影响整个工作区的 `git stash`，未经授权禁止 `git reset --hard`、`git checkout --` 等破坏性操作。回滚前核对目标提交、备份和文件范围，不得凭记忆猜测旧状态。
 
-## 沟通与上下文保护
+## 子代理
 
-14. 默认用中文回复，简洁说明原因，并给出可执行步骤。
-15. 主线程要保护上下文。不要把大量搜索结果、长文件全文、测试日志、报错栈、候选路径、外部资料、临时推理过程直接塞进主上下文；优先让子代理或工具处理噪声，只把结论、关键证据、文件位置和下一步建议带回主线程。
+6. 提示词长短不代表复杂度。主线程最多先做一次有限预检；若需要跨两个以上模块/三个以上文件、读取长文件或大量检索、追踪异步生命周期/状态机/竞态、处理浏览器/视觉/媒体、根因不明、已有失败返工，或两步内仍未定位，必须停止独自扩展检索，在 `commentary` 说明原因并升级，不得静默埋头苦干。
+7. 升级路径：`luna` 是大范围快速吞吐层，负责文件树/路径/符号/行号定位、长文件与日志压缩、资源整理，也负责浏览器和明确授权的低风险写入/媒体处理；只读吞吐可用较低 reasoning effort，浏览器或写入使用 `luna max`。中等难度方案与审查使用 `terra`，高难度架构、复杂竞态、安全风险或独立反方意见使用 `sol high`；主线程原则上不调用浏览器，`terra`/`sol` 不写文件、不调用浏览器，媒体只返回路径和结论，不返回 base64。
+8. 每个子代理只负责一个小任务，必须限定输入、输出、停止条件和禁止扩展项。默认只允许一级子代理，并行通常限制为 2-4 个；探索代理只读，禁止并行写同一文件。
+9. 子代理首次交付不合格时最多定向重试一次；仍不合格或已无提升空间时，主线程立即接管。主线程负责最终方案与验收，收束结论、证据、文件/行号和风险后及时关闭子代理。
+10. 本地图片、截图或视觉素材送往上游视觉模型、浏览器工具或子代理前，必须先检查像素尺寸、单文件体积和批量总量；原图保留本地，只上传压缩审查副本。默认最长边不超过 2048px，优先使用 WebP/JPEG 质量 80-85，单次总量控制在 12MB 内，超过则分批；透明通道或像素级细节改用无损副本或局部裁切。禁止原样批量上传高分辨率图片，也禁止把图片 base64 塞入线程。
 
-## 子代理使用规范
+## 环境与文件安全
 
-16. 子代理用于干脏活累活，包括：搜索和筛选资料、阅读长文件、扫描代码路径、分析测试日志、整理报错栈、比较候选方案、提取外部文档要点、并行检查多个模块。子代理应返回简洁摘要，不返回大段原始日志或全文，除非主代理明确要求。
-17. 子代理必须有明确边界：一次只负责一个小任务；说明输入、输出格式、停止条件；优先只读探索。不要让子代理自行扩展任务范围、继续拆子任务、造新框架或做无关实现。
-18. 防止子代理无限叠层。默认只允许主代理直接派发一级子代理；子代理不得再创建子代理，除非用户明确要求。并行数量要克制，通常 2-4 个足够；任务结束后及时关闭子代理线程。
-19. 子代理用完要收束。主代理等待子代理返回后，应整合为短摘要：结论、证据、文件/行号、风险、建议动作。确认不再需要后，要求关闭已完成子代理，避免后台线程残留和上下文污染。
-20. 子代理不需要默认使用与主代理相同的高推理强度。除非任务复杂或高风险，子代理应优先使用较低成本/较快模型或较低 reasoning effort；只有安全审查、复杂逻辑追踪、架构判断、疑难 bug 才使用更高 reasoning effort。
+11. 默认环境为中国大陆网络、Windows、PowerShell 或 Git Bash。执行前识别 Shell；PowerShell 禁止使用 bash 专属写法。命令失败后禁止原样重跑，必须分析原因并换用等价命令；所有路径必须加引号。
+12. 下载失败时只为当前命令临时使用镜像或代理，禁止擅自修改全局 npm、pip、git、代理或默认 Shell。新增工具需说明来源、版本、范围和风险并获许可，用户已授权的除外。
+13. 中文文件可能是 UTF-8、GBK 或 CP936；乱码不等于损坏。禁止擅自转码、重写或格式化，新文件默认 UTF-8 without BOM，修改旧文件保持原编码、换行和结构。修改必须最小化并保持单一写入所有者，不删除用户内容、不做无关重构。
+14. 删除、覆盖、批量修改/转码、全局配置、编码不确定、图片版本不清或主观视觉判断前必须询问，用户已明确授权当前操作时无需重复询问。UI 与图片判断要保守，不得把旧图、临时图或错图当最终结果。
 
-## 代码写入与资源保护
+## 资源与沟通
 
-21. 代码写入要谨慎并集中。默认由主代理或一个明确的 worker 负责最终修改；探索型子代理只读，不改文件。避免多个子代理同时写同一片代码，防止冲突和状态混乱。
-22. Cargo 构建、检查和测试默认使用 `-j 2`；只有用户明确同意或任务确有必要时才提高并发。对于不支持 jobs 参数的命令，不要强行添加。
-23. 禁止同时运行多个重型构建、测试、依赖安装或代码索引任务。执行可能明显占用 CPU、内存或磁盘的命令前，先向用户简短说明。
-24. 优先复用已有且版本兼容的 `node_modules`、Cargo target 和工具缓存，避免在多个工作树重复安装或构建；复用前必须确认路径和版本兼容，且不得覆盖现有目录。
-25. 长时间命令结束后必须确认相关进程已经退出；不要遗留构建、测试、开发服务器、watcher 或后台 Agent 持续占用资源。
-26. 如果用户报告卡顿、CPU/磁盘占用异常或系统无响应，应立即停止新增重型任务，先检查并收束现有进程，再采用更低并发或更小范围的验证方案。
-27. 当存在适用开发笔记时，在调查问题、选择方案、设计、修改、恢复工作或改变方向前，必须先使用 `$maintain-development-notes` 读取并检索：相同或相关问题/场景、用户偏好与不可妥协约束、已否决/失败/superseded/不安全方案及原因、总体产品与架构方向、最后验证的权威状态与证据、剩余风险和后续动作；即使本次不需要写笔记，也不得跳过读取。当工作区或线程出现多功能、多分支/工作树/PR、频繁任务切换、长周期调查、安装回滚或需要跨上下文恢复的状态，或已验证现实发生有意义变化时，再根据 Skill 门槛创建或更新开发笔记；普通聊天、无关一次性问题、无持续状态的简单单任务和不产生持久决策的短只读探索不得为了形式写笔记。
+15. 主线程只保留结论、关键证据、文件位置和下一步，不塞入全文、base64、长日志或临时推理。禁止并行运行多个重型任务，Cargo 默认 `-j 2`；重型命令前先告知，结束后确认进程退出。用户报告卡顿时立即停止新增重型任务并先收束进程。默认用中文简洁回复，说明原因、改动、验证、备份/提交状态和待验收风险。
diff --git a/references/interview-schema.md b/references/interview-schema.md
index 06d4f15..40936f5 100644
--- a/references/interview-schema.md
+++ b/references/interview-schema.md
@@ -11,6 +11,13 @@ For every question, record the selected value, any custom wording, and the user'
 - Explain: user-level rules affect many projects; project-level rules are narrower and safer for experimentation.
 - Ask: Which `AGENTS.md` scope and exact target path should receive the adopted rules?
 
+## WORKFLOW-01 - Per-Turn Project Preflight
+
+- Requirement: `required`
+- Detect first: current shell, working directory, repository status, branch, HEAD, and available instruction/recovery-note discovery mechanisms.
+- Explain: a per-turn preflight prevents work in the wrong shell, directory, branch, or stale context, but adds a small fixed cost to every project-work turn.
+- Ask: Should every project-work turn require a Shell/CWD/scope check, Git status/branch/HEAD check when applicable, and a read of the latest instructions and relevant recovery notes before diagnosis, planning, writing, or testing?
+
 ## PLATFORM-01 - Platform Target
 
 - Requirement: `required`
@@ -79,11 +86,11 @@ For every question, record the selected value, any custom wording, and the user'
 ## SUBAGENT-02 - Model and Reasoning Strategy
 
 - Requirement: `required_if SUBAGENT-01 enables subagents`
-- Detect first: whether the harness exposes model and reasoning controls; list only verified available controls.
+- Detect first: whether the harness exposes model and reasoning controls; list only verified available controls and never assume reference names such as `luna`, `terra`, or `sol` exist.
 - Explain choices:
   - Efficiency/cost first: prefer faster, lower-cost models and lower reasoning for bounded exploration.
   - Quality first: prefer higher-capability models and higher reasoning, accepting greater latency and cost.
-  - Tiered: use lower tiers for searches, file scans, and log summaries; use higher tiers for security, architecture, complex logic, and difficult bugs.
+  - Tiered: use lower tiers for searches, file scans, and log summaries; use higher tiers for security, architecture, complex logic, and difficult bugs. Map reference model names to verified equivalent capabilities only after user confirmation.
 - Ask: Which subagent model/reasoning strategy should be used?
 
 ## SUBAGENT-03 - Subagent Concurrency
@@ -101,8 +108,8 @@ For every question, record the selected value, any custom wording, and the user'
 ## SUBAGENT-05 - Write Ownership
 
 - Requirement: `required_if SUBAGENT-01 enables subagents`
-- Explain: multiple writers can be faster on isolated modules but create conflict and ownership ambiguity; a single writer is easier to audit.
-- Ask: Must exploratory subagents remain read-only, and who may perform final file writes?
+- Explain: multiple writers can be faster on isolated modules but create conflict and ownership ambiguity; reviewer roles should remain read-only, while a verified throughput/browser role may perform explicitly authorized low-risk writes.
+- Ask: Which verified roles may read, browse, write, or handle media, and who owns final file writes and acceptance?
 
 ## SUBAGENT-06 - Unsupported Controls
 
@@ -110,6 +117,25 @@ For every question, record the selected value, any custom wording, and the user'
 - Explain: some harnesses cannot choose a subagent model or reasoning level even when the policy requests one.
 - Ask: If requested model/reasoning controls are unavailable, should the Agent use the harness default after disclosure, avoid subagents, or stop and ask again?
 
+## SUBAGENT-07 - Mandatory Escalation Threshold
+
+- Requirement: `required_if SUBAGENT-01 enables subagents`
+- Explain: early delegation protects context and speeds broad discovery, while over-delegating small tasks adds coordination cost.
+- Ask: After how much primary-agent preflight must delegation become mandatory for cross-module/file work, long searches, lifecycle/state/race analysis, browser/media tasks, unknown root causes, or failed rework?
+
+## SUBAGENT-08 - Capability and Tool Routing
+
+- Requirement: `required_if SUBAGENT-01 enables subagents`
+- Detect first: verified models, reasoning levels, browser access, write access, media handling, and whether the primary agent can call those tools directly.
+- Explain: the reference routes fast throughput/browser/authorized low-risk writes, medium review, and high-risk independent review to different roles; exact names must be mapped or omitted when unavailable.
+- Ask: What role-to-capability routing should apply for throughput, browser/media work, authorized writing, ordinary review, and high-risk architecture/security review?
+
+## SUBAGENT-09 - Retry, Takeover, and Closure
+
+- Requirement: `required_if SUBAGENT-01 enables subagents`
+- Explain: unlimited retries waste cost and hide weak results; immediate takeover can discard an easily corrected first pass.
+- Ask: How many directed retries are allowed before the primary Agent takes over, and what evidence, risks, and shutdown steps must be reported when closing agents?
+
 ## INSTALL-01 - Dependencies and Tools
 
 - Requirement: `required`
@@ -131,8 +157,26 @@ For every question, record the selected value, any custom wording, and the user'
 ## GIT-01 - Publication Authority
 
 - Requirement: `required`
-- Explain: committing is local and reversible; pushing, opening a PR, merging, and releasing change external state and visibility.
-- Ask: Which Git and forge actions may the Agent perform without a new confirmation, and which always require one?
+- Explain: pushing, opening a PR, merging, and releasing change external state and visibility; local recovery checkpoints are handled separately.
+- Ask: Which remote Git and forge actions may the Agent perform without a new confirmation, and which always require one?
+
+## GIT-02 - Recovery Point Triggers
+
+- Requirement: `required`
+- Explain: checkpoints before accepted-feature changes, media/state/configuration edits, multi-file logic, or rework improve recovery but create extra local history or backup artifacts.
+- Ask: Which changes and milestones must have a verified recovery point before work continues?
+
+## GIT-03 - Checkpoint Storage and Scope
+
+- Requirement: `required`
+- Explain: a task-scoped local commit is easy to restore; when unrelated changes exist or committing is unsuitable, an external `git diff --binary` patch or exact backup avoids mixing user work.
+- Ask: Should checkpoints prefer task-only local commits, external binary patches/exact backups, or a context-dependent combination, and where may backups be stored?
+
+## GIT-04 - Rollback and Stash Safety
+
+- Requirement: `required`
+- Explain: whole-worktree stash and destructive reset/checkout can hide or erase unrelated work; safe rollback requires an exact target, backup, and file scope.
+- Ask: What stash, destructive-command, and rollback restrictions must the Agent follow?
 
 ## NOTES-01 - Development Note Trigger
 
@@ -146,6 +190,19 @@ For every question, record the selected value, any custom wording, and the user'
 - Explain: committed notes aid team recovery but may expose local paths or operational context; private notes avoid publication but are less shareable.
 - Ask: Should development notes be committed, kept private, decided per project, or placed at a custom location?
 
+## NOTES-03 - Read Gate and Refresh Cadence
+
+- Requirement: `required`
+- Explain: re-reading the latest instructions and relevant note snapshot each project-work turn prevents stale assumptions; targeted search keeps long-note overhead small.
+- Ask: At what cadence and for which project tasks must the Agent re-read applicable `AGENTS.md` and existing development or handoff notes before acting?
+
+## MEDIA-01 - Visual Review Transfer Budget
+
+- Requirement: `required`
+- Detect first: available image tools, transparency/detail needs, common source dimensions, and whether media leaves the local machine.
+- Explain: compressed review copies reduce latency, cost, and context pressure; lossless crops remain necessary for transparency or pixel-level inspection.
+- Ask: What maximum dimensions, preferred formats/quality, per-batch size limit, original-retention rule, lossless exceptions, and base64/thread restrictions should apply to visual material sent to tools or subagents?
+
 ## COMMUNICATION-01 - Response Language and Detail
 
 - Requirement: `required`
diff --git a/references/rule-catalog.md b/references/rule-catalog.md
index c1dbd09..4f22655 100644
--- a/references/rule-catalog.md
+++ b/references/rule-catalog.md
@@ -4,20 +4,29 @@ Use these IDs when discussing adoption and updates. They identify behavior, not
 
 | ID | Reference rules | Behavior | Applicability |
 |---|---:|---|---|
-| ENV-001 | 1 | Assume mainland China and Windows only when selected | Environment-specific |
-| SHELL-001 | 2-4 | Detect the current shell and use its supported syntax | General; wording is shell-specific |
-| SHELL-002 | 7 | Quote command paths, especially paths with spaces or non-ASCII characters | General |
-| NET-001 | 5-6 | Use temporary mirrors and require approval for broader tool/config changes | Preference-specific |
-| FILE-001 | 8-10 | Preserve encoding, BOM, line endings, structure, and existing Chinese | General |
-| FILE-002 | 11-13 | Keep edits scoped and ask before destructive, uncertain, or subjective changes | General |
-| COMM-001 | 14-15 | Respect language preference and protect the main context from raw noise | Preference-specific |
-| SUB-001 | 16-17 | Give subagents bounded tasks and concise outputs | Requires subagent support |
-| SUB-002 | 18-19 | Limit delegation depth/concurrency and close completed work | Requires subagent support |
-| SUB-003 | 20 | Select subagent capability/reasoning according to user strategy | Requires exposed controls or fallback policy |
-| WRITE-001 | 21 | Keep final write ownership explicit and exploration read-only by default | General |
-| RES-001 | 22 | Apply the user-selected per-command worker policy only to supported tools | Tool- and preference-specific |
-| RES-002 | 23-26 | Limit simultaneous heavy work, reuse compatible caches, and clean up processes | Preference-specific |
-| NOTES-001 | 27 | Read applicable development memory before acting, then apply a separate write gate without creating ceremonial notes | Requires installed Skill |
+| START-001 | 1 | Confirm Shell, working directory, task scope, and Git status/branch/HEAD before project work | General project work |
+| START-002 | 2 | Re-read applicable instructions and recovery notes at each project-work turn; update them at meaningful checkpoints | General project work; requires readable notes when present |
+| GIT-001 | 3 | Confirm a valid recovery point before risky, accepted, multi-file, stateful, media, configuration, or rework changes | Git repositories |
+| GIT-002 | 4 | Prefer a task-scoped local commit; otherwise create an external binary patch or equivalent exact backup; do not push without authority | Git repositories; policy-specific |
+| GIT-003 | 5 | Exclude unrelated work, avoid whole-worktree stash, prohibit unauthorized destructive resets, and verify rollback targets | Git repositories |
+| SUB-001 | 8 | Give each subagent one bounded task with explicit input, output, stop condition, and exclusions | Requires subagent support |
+| SUB-002 | 8-9 | Limit delegation depth and concurrency, keep exploration read-only, centralize final acceptance, and close completed agents | Requires subagent support |
+| SUB-003 | 7 | Select model and reasoning capability according to the user-approved routing strategy | Requires exposed controls or fallback policy |
+| SUB-004 | 6 | Escalate after a finite precheck when scope, uncertainty, lifecycle complexity, media/browser work, or failed rework crosses the selected threshold | Requires subagent support |
+| SUB-005 | 7 | Route throughput, browser/write, review, and high-risk work only to verified capabilities; named models are examples, not assumed availability | Capability- and preference-specific |
+| SUB-006 | 9 | Retry an inadequate subagent at most once, then return control to the primary agent and summarize evidence and risk | Requires subagent support |
+| MEDIA-001 | 10 | Preserve originals and send compressed, bounded review copies; use lossless crops for transparency or pixel detail and never place image base64 in the thread | Visual/media workflows |
+| ENV-001 | 11 | Assume mainland China and Windows only when selected | Environment-specific |
+| SHELL-001 | 11 | Detect the current shell and use its supported syntax | General; wording is shell-specific |
+| SHELL-002 | 11 | Quote command paths, especially paths with spaces or non-ASCII characters | General |
+| NET-001 | 12 | Use command-scoped mirrors/proxies and require approval for new tools or broader configuration changes | Preference-specific |
+| FILE-001 | 13 | Preserve encoding, BOM, line endings, structure, and existing Chinese | General |
+| FILE-002 | 13-14 | Keep edits scoped and ask before destructive, broad, uncertain, or subjective changes | General |
+| WRITE-001 | 7-8,13 | Keep write ownership explicit; reviewers and exploration remain read-only unless a verified role is explicitly authorized | Capability- and preference-specific |
+| RES-001 | 15 | Apply the selected per-command worker policy only where the tool supports it | Tool- and preference-specific |
+| RES-002 | 15 | Avoid concurrent heavy work, announce resource-heavy commands, stop leftover processes, and reduce load when the user reports lag | Preference-specific |
+| COMM-001 | 15 | Protect the primary context, avoid raw logs/base64, and follow the selected response language and detail level | Preference-specific |
+| NOTES-001 | 2 | Read applicable development memory before acting, then apply a separate write gate without creating ceremonial notes | Requires installed Skill |
 
 ## Semantic Comparison Rules
 
@@ -26,4 +35,5 @@ Use these IDs when discussing adoption and updates. They identify behavior, not
 - Environment-specific examples must not become unconditional global requirements.
 - A user-selected value always overrides the reference sample for that preference.
 - Unsupported platform capabilities must be omitted or expressed as conditional behavior.
+- Named models such as `luna`, `terra`, or `sol` must be detected and user-mapped before adoption; preserve the role semantics when exact names are unavailable.
 - Never use stable IDs as justification to replace locally customized text without approval.
diff --git a/scripts/validate-repository.ps1 b/scripts/validate-repository.ps1
index a825845..cdde032 100644
--- a/scripts/validate-repository.ps1
+++ b/scripts/validate-repository.ps1
@@ -83,13 +83,15 @@ if (Test-Path -LiteralPath $skillPath) {
 
     foreach ($requiredPhrase in @(
         'Apply separate read and write gates',
+        'At the start of every project-work turn',
         'Discover and read before acting',
         'the same or a related problem or scenario',
         'user preferences and non-negotiable constraints',
         'rejected, failed, superseded, or unsafe approaches',
         'the overall product, architecture, and release direction',
         'the last verified authoritative state and supporting evidence',
-        'unresolved risks, pending validation, and ordered next actions'
+        'unresolved risks, pending validation, and ordered next actions',
+        'targeted search (`rg` when available)'
     )) {
         if (-not $skill.Contains($requiredPhrase)) {
             $failures.Add("Skill is missing read-before-act gate: $requiredPhrase")
@@ -99,6 +101,7 @@ if (Test-Path -LiteralPath $skillPath) {
 
 $requiredQuestionIds = @(
     'SCOPE-01',
+    'WORKFLOW-01',
     'PLATFORM-01',
     'SHELL-01',
     'SHELL-02',
@@ -113,12 +116,20 @@ $requiredQuestionIds = @(
     'SUBAGENT-04',
     'SUBAGENT-05',
     'SUBAGENT-06',
+    'SUBAGENT-07',
+    'SUBAGENT-08',
+    'SUBAGENT-09',
     'INSTALL-01',
     'ENCODING-01',
     'SAFETY-01',
     'GIT-01',
+    'GIT-02',
+    'GIT-03',
+    'GIT-04',
     'NOTES-01',
     'NOTES-02',
+    'NOTES-03',
+    'MEDIA-01',
     'COMMUNICATION-01'
 )
 
@@ -132,13 +143,72 @@ if (Test-Path -LiteralPath $interviewPath) {
     }
 }
 
+$referencePath = Join-Path $rootPath 'reference/AGENTS.md'
+$referenceRuleCount = 0
+if (Test-Path -LiteralPath $referencePath) {
+    $reference = [System.IO.File]::ReadAllText($referencePath, $strictUtf8)
+    $referenceRuleCount = [regex]::Matches($reference, '(?m)^\d+\. ').Count
+    if ($referenceRuleCount -ne 15) {
+        $failures.Add("Reference AGENTS.md must contain exactly 15 numbered rules; found $referenceRuleCount.")
+    }
+
+    foreach ($requiredPhrase in @(
+        '每个涉及项目工作的回合',
+        '每轮开始前必须阅读最近的',
+        'git status --short',
+        'git diff --binary',
+        '`luna`',
+        '`terra`',
+        '`sol high`',
+        '2048px',
+        '12MB',
+        '图片 base64',
+        'Cargo 默认 `-j 2`'
+    )) {
+        if (-not $reference.Contains($requiredPhrase)) {
+            $failures.Add("Reference AGENTS.md is missing current-policy phrase: $requiredPhrase")
+        }
+    }
+}
+
+$catalogPath = Join-Path $rootPath 'references/rule-catalog.md'
+if (Test-Path -LiteralPath $catalogPath) {
+    $catalog = [System.IO.File]::ReadAllText($catalogPath, $strictUtf8)
+    foreach ($ruleId in @(
+        'START-001', 'START-002',
+        'GIT-001', 'GIT-002', 'GIT-003',
+        'SUB-004', 'SUB-005', 'SUB-006',
+        'MEDIA-001', 'NOTES-001'
+    )) {
+        if ($catalog -notmatch "(?m)^\| $([regex]::Escape($ruleId)) \|") {
+            $failures.Add("Rule catalog is missing current-policy ID: $ruleId")
+        }
+    }
+
+    foreach ($line in ($catalog -split "`n")) {
+        if ($line -match '^\|\s*[A-Z0-9-]+\s*\|\s*([0-9,\-]+)\s*\|') {
+            foreach ($numberMatch in [regex]::Matches($Matches[1], '\d+')) {
+                if ([int]$numberMatch.Value -gt $referenceRuleCount) {
+                    $failures.Add("Rule catalog references missing AGENTS rule $($numberMatch.Value): $line")
+                }
+            }
+        }
+    }
+}
+
 $adoptPath = Join-Path $rootPath 'workflows/ADOPT.md'
 if (Test-Path -LiteralPath $adoptPath) {
     $adopt = [System.IO.File]::ReadAllText($adoptPath, $strictUtf8)
     foreach ($requiredPhrase in @(
         'Ask exactly one question ID at a time.',
         'Do not use timeouts, defaults, or silence as consent.',
-        'Show the final diff and obtain a separate, explicit confirmation.'
+        'Show the final diff and obtain a separate, explicit confirmation.',
+        'git status --short',
+        'DEVELOPMENT_NOTES.md',
+        'recovery point',
+        'git diff --binary',
+        'capability routing',
+        'visual/media transfer budget'
     )) {
         if (-not $adopt.Contains($requiredPhrase)) {
             $failures.Add("ADOPT workflow is missing gate: $requiredPhrase")
@@ -146,6 +216,22 @@ if (Test-Path -LiteralPath $adoptPath) {
     }
 }
 
+$updatePath = Join-Path $rootPath 'workflows/UPDATE.md'
+if (Test-Path -LiteralPath $updatePath) {
+    $update = [System.IO.File]::ReadAllText($updatePath, $strictUtf8)
+    foreach ($requiredPhrase in @(
+        'Git status, branch, HEAD',
+        'development notes',
+        'recovery-point plan',
+        'capability fallbacks',
+        'media-budget questions'
+    )) {
+        if (-not $update.Contains($requiredPhrase)) {
+            $failures.Add("UPDATE workflow is missing current-policy gate: $requiredPhrase")
+        }
+    }
+}
+
 if ($failures.Count -gt 0) {
     $failures | ForEach-Object { Write-Error $_ }
     exit 1
diff --git a/skills/maintain-development-notes/SKILL.md b/skills/maintain-development-notes/SKILL.md
index afc6976..0801715 100644
--- a/skills/maintain-development-notes/SKILL.md
+++ b/skills/maintain-development-notes/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: maintain-development-notes
-description: Read, reconcile, create, and maintain durable development notes for context recovery. Use automatically when a workspace or thread has multiple active features, branches, worktrees, PRs, repositories, risky local installations, repeated task switching, long-running investigations, or state that must survive compaction and handoff; whenever an applicable note exists, also use it before diagnosing problems, planning, choosing an approach, resuming work, or changing direction so prior similar scenarios, user preferences, rejected approaches, overall direction, evidence, and open risks guide the work. Do not create or update notes for ordinary chat, unrelated one-off questions, simple self-contained changes with no continuing state, or short read-only exploration that produces no durable decision or risk.
+description: Read, reconcile, create, and maintain durable development notes for context recovery. Use automatically when a workspace or thread has multiple active features, branches, worktrees, PRs, repositories, risky local installations, repeated task switching, long-running investigations, or state that must survive compaction and handoff; at the start of each project-work turn, whenever an applicable note exists, also use it before diagnosing problems, planning, choosing an approach, resuming work, or changing direction so prior similar scenarios, user preferences, rejected approaches, overall direction, evidence, and open risks guide the work. Do not create or update notes for ordinary chat, unrelated one-off questions, simple self-contained changes with no continuing state, or short read-only exploration that produces no durable decision or risk.
 ---
 
 # Maintain Development Notes
@@ -13,7 +13,7 @@ Apply the read gate before the write gate.
 
 ### Read gate
 
-When an applicable development note exists, read the relevant parts before diagnosing, planning, choosing a solution, implementing, resuming work, changing direction, installing, releasing, or handing off.
+At the start of every project-work turn, re-read the latest applicable `AGENTS.md` and the relevant parts of any development or handoff note before diagnosing, planning, choosing a solution, implementing, testing, resuming work, changing direction, installing, releasing, or handing off.
 
 The read gate applies even when the current task is small and will not justify a note update. A small task can still depend on old decisions, user preferences, or a rejected approach.
 
@@ -66,7 +66,7 @@ If the write gate is not met, continue without creating or updating a note. Stil
 6. If multiple notes exist, identify their responsibilities and read the authoritative source for each relevant fact. Synchronize them only when their documented roles require it.
 7. If authority is ambiguous or notes contradict each other, verify reality before acting. Ask the user only when repository evidence cannot resolve ownership safely.
 
-For long notes, start with the current snapshot and use targeted search. Do not load or repeat the entire history when only a small section is relevant.
+For long notes, start with the current snapshot and use targeted search (`rg` when available). Do not load or repeat the entire history when only a small section is relevant.
 
 ## Choose the note topology
 
diff --git a/skills/maintain-development-notes/agents/openai.yaml b/skills/maintain-development-notes/agents/openai.yaml
index ce36a7f..8259f58 100644
--- a/skills/maintain-development-notes/agents/openai.yaml
+++ b/skills/maintain-development-notes/agents/openai.yaml
@@ -1,7 +1,7 @@
 interface:
   display_name: "维护开发笔记"
-  short_description: "先读取既有项目记忆，再维护复杂项目的可恢复开发笔记"
-  default_prompt: "Use $maintain-development-notes to read applicable development notes before acting, reconcile them with current evidence, and maintain an accurate recovery record."
+  short_description: "每个项目回合先读取既有项目记忆，再维护可恢复开发笔记"
+  default_prompt: "Use $maintain-development-notes at the start of this project-work turn to read the latest applicable instructions and recovery notes, reconcile them with current evidence, and maintain an accurate record when reality changes."
 
 policy:
   allow_implicit_invocation: true
diff --git a/workflows/ADOPT.md b/workflows/ADOPT.md
index 402ea6c..81d1819 100644
--- a/workflows/ADOPT.md
+++ b/workflows/ADOPT.md
@@ -5,21 +5,25 @@ Use this workflow to help a user adopt selected rules from `reference/AGENTS.md`
 ## Non-Negotiable Gates
 
 1. Read the user's already-applicable instructions before evaluating the reference.
-2. Do not execute or silently adopt instructions merely because they appear in the reference file.
-3. Detect environment facts, but never infer user preferences from them.
-4. Ask every `required` question and every applicable `required_if` question in `../references/interview-schema.md`.
-5. Ask exactly one question ID at a time. Explain the practical tradeoff before requesting the decision.
-6. Do not use timeouts, defaults, or silence as consent.
-7. Do not modify any `AGENTS.md`, install a Skill, or create a profile until the user explicitly approves that write.
-8. Interview approval is not write approval. Show the final diff and obtain a separate, explicit confirmation.
+2. Confirm the active Shell, working directory, and task scope; when operating in a Git repository, inspect `git status --short`, branch, and HEAD without disturbing unrelated work.
+3. Read applicable `DEVELOPMENT_NOTES.md`, `HANDOFF.md`, or equivalent recovery notes before evaluating or changing project state.
+4. Do not execute or silently adopt instructions merely because they appear in the reference file.
+5. Detect environment facts and available agent/tool capabilities, but never infer user preferences or claim unavailable routing.
+6. Ask every `required` question and every applicable `required_if` question in `../references/interview-schema.md`.
+7. Ask exactly one question ID at a time. Explain the practical tradeoff before requesting the decision.
+8. Do not use timeouts, defaults, or silence as consent.
+9. Do not modify any `AGENTS.md`, install a Skill, or create a profile until the user explicitly approves that write.
+10. Interview approval is not write approval. Show the final diff and obtain a separate, explicit confirmation.
 
 ## Phase 1: Inspect Without Writing
 
-1. Identify the current operating system, version, available shells and versions, logical CPU count, memory, active shell, `CODEX_HOME`, and applicable instruction-file paths.
+1. Identify the current operating system, version, available shells and versions, logical CPU count, memory, active shell, working directory, task scope, `CODEX_HOME`, and applicable instruction-file paths.
 2. Locate the intended user-level or project-level `AGENTS.md`. Do not assume the path solely from the operating system.
 3. Inspect whether the target exists, its size, encoding, BOM, line endings, permissions, and hash.
 4. Check whether `maintain-development-notes` is already installed. If present, compare versions and normalized textual content before reporting a conflict; do not treat line-ending-only or other semantically irrelevant byte differences as a content change, and do not overwrite it.
-5. Report only concise detected facts. Clearly label facts as detected, inferred, unknown, or user-selected.
+5. If the target or surrounding work is in Git, identify the branch, HEAD, dirty state, unrelated changes, and the latest valid recovery point.
+6. Detect verified subagent models, reasoning controls, browser/write/media capabilities, and safe fallbacks; treat named routes in the reference as candidate mappings only.
+7. Report only concise detected facts. Clearly label facts as detected, inferred, unknown, or user-selected.
 
 If encoding cannot be identified reliably, stop before proposing a write and ask the user how to proceed.
 
@@ -62,6 +66,8 @@ Before writing, show:
 5. The exact target path, detected encoding, BOM, and line-ending style.
 6. The proposed backup path.
 7. A final unified diff or an equivalent complete before/after preview.
+8. The selected recovery-point policy and the checkpoint that will protect this write.
+9. The selected subagent capability routing and visual/media transfer budget, including unsupported reference capabilities.
 
 Ask for explicit write confirmation. A response to any earlier interview question is not sufficient.
 
@@ -70,11 +76,12 @@ Ask for explicit write confirmation. A response to any earlier interview questio
 After confirmation:
 
 1. Re-read and re-hash the target. If it changed after preview, stop and regenerate the plan.
-2. Back up the original bytes before writing. Do not normalize or reformat the backup.
-3. Preserve unrelated content, encoding, BOM, line endings, and permissions.
-4. Prefer an atomic replacement when the platform and filesystem support it.
-5. Re-read the result, verify its hash and encoding, and confirm the intended diff only.
-6. Report the target and backup paths plus any remaining manual validation.
+2. Establish or verify the approved recovery point. Prefer a task-only local commit when appropriate; otherwise create an external `git diff --binary` patch or equivalent exact backup. Do not mix unrelated files, use whole-worktree `git stash`, or push without authority.
+3. Back up the original bytes before writing. Do not normalize or reformat the backup.
+4. Preserve unrelated content, encoding, BOM, line endings, and permissions.
+5. Prefer an atomic replacement when the platform and filesystem support it.
+6. Re-read the result, verify its hash and encoding, and confirm the intended diff only.
+7. Report the checkpoint, target and backup paths, commit/publication state, and remaining manual validation.
 
 Optionally offer to save a non-authoritative adoption profile for future upgrades. Explain its path and contents and obtain separate consent before creating it. Never store secrets, tokens, private prompts, or unnecessary personal information.
 
diff --git a/workflows/UPDATE.md b/workflows/UPDATE.md
index 781c65f..4df01f7 100644
--- a/workflows/UPDATE.md
+++ b/workflows/UPDATE.md
@@ -9,17 +9,20 @@ Use this workflow when a user wants to review a newer version of the reference p
 - Never assume that a previously accepted rule may be overwritten automatically.
 - Preserve user edits made after the initial adoption.
 - Re-run affected interview questions when environment, capabilities, preferences, or rule meaning changed.
+- Read the latest applicable instructions and recovery notes before comparing versions.
+- Treat Git recovery points, subagent capability routing, and visual/media budgets as first-class policy changes.
 
 ## Procedure
 
-1. Inspect the current target, installed Skill, optional adoption profile, previous source version, and new source version without writing.
-2. Verify the target encoding, BOM, line endings, permissions, and hash.
-3. Compare stable IDs in `../references/rule-catalog.md`, then perform a semantic comparison for wording and behavior changes.
-4. Classify changes as unchanged, new, compatible revision, conflicting revision, locally customized, or no longer applicable.
-5. Ask each affected question from `../references/interview-schema.md` separately. Do not reuse an old answer when the tradeoff changed.
-6. Ask separately for every policy conflict or locally customized rule.
-7. Show the complete proposed diff, backup path, and Skill file changes.
-8. Obtain explicit confirmation, re-hash the target, back up original bytes, and apply only the approved changes.
-9. Verify the final files and accurately report whether the update is installed, pending restart, partially adopted, or cancelled.
+1. Confirm Shell, working directory, task scope, and—when applicable—Git status, branch, HEAD, unrelated changes, and existing recovery point.
+2. Read applicable `AGENTS.md`, development notes, handoff notes, and the current target before inspecting the installed Skill, optional profile, previous source version, and new source version.
+3. Verify the target encoding, BOM, line endings, permissions, and hash.
+4. Compare stable IDs in `../references/rule-catalog.md`, then perform a semantic comparison for wording and behavior changes.
+5. Classify changes as unchanged, new, compatible revision, conflicting revision, locally customized, or no longer applicable.
+6. Ask each affected question from `../references/interview-schema.md` separately, including new checkpoint, note-read, capability-routing, and media-budget questions. Do not reuse an old answer when the tradeoff changed.
+7. Ask separately for every policy conflict or locally customized rule.
+8. Show the complete proposed diff, recovery-point plan, backup path, capability fallbacks, and Skill file changes.
+9. Obtain explicit confirmation, re-hash the target, establish the approved recovery point, back up original bytes, and apply only the approved changes.
+10. Verify the final files and accurately report checkpoint/commit/publication state plus whether the update is installed, pending restart, partially adopted, or cancelled.
 
 An update is a new review, not package-owned synchronization. There is no “repository wins” mode.