@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/templates/.agents/rules/compatibility-policy.zh-CN.md

@@ -0,0 +1,40 @@
+# 兼容性策略
+
+本规则约束需求分析、方案、实现和审查中的兼容性决策。默认只支持当前契约；兼容是需要证据和退出条件的例外预算，不是稳健性的默认同义词。
+
+## 什么属于兼容逻辑
+
+以下任一行为都属于兼容逻辑：同时接受或写入新旧 schema、字段、状态或命令；保留旧别名、adapter、wrapper、shim；在运行主路径执行迁移；根据旧格式回退到另一套语义；为旧调用方维持并行事实源或测试矩阵。
+
+以下行为本身不属于历史兼容：当前版本操作的幂等重试与崩溃恢复；平台、操作系统或权限能力的显式分支；对未知状态失败关闭并给出恢复提示；用户明确要求的多版本公共契约。不得用这些名义扩大成旧协议支持。
+
+## 新增兼容的准入门槛
+
+只有任务或既有公共契约明确要求兼容，并且产物同时记录以下四项证据时，才能新增或延长兼容逻辑：
+
+1. **对象**：仍在使用旧契约的具体消费者、已发布版本或存量数据。
+2. **必要性**：为何不能原子切换、一次性转换或直接失败并提示修复。
+3. **期限**：兼容窗口的版本、日期或可验证终点。
+4. **退出**：删除条件以及届时要删除的代码、测试和文档。
+
+缺少任一项时，兼容属于未经授权的范围扩张：按当前契约实现；遇到旧输入时失败关闭并提供可操作提示，或在主路径之外执行一次性显式转换。
+
+## 实现边界
+
+- 当前契约只有一个规范写入格式和一个事实源；禁止双写、影子状态和“先试新逻辑、失败再走旧逻辑”。
+- 兼容转换集中在单一边界，转换后立即进入当前模型；业务核心不得感知多个历史版本。
+- 暂时保留的兼容逻辑必须在唯一兼容边界使用 `TODO(compat): Remove ... once ...` 标记要删除的对象和可验证删除条件。该 TODO 与代码同源；任务或 Issue 只用于可选排期，不作为兼容事实源或工作流门禁。
+- warning 只用于主动作仍然正确且用户可重试的外围问题，不能掩盖身份、授权、数据解释或副作用正确性的不确定。
+- 删除旧能力时同步删除专属 adapter、分支、fixture、测试和迁移文档；不要新增“已删除能力不存在”的反向断言。
+- 不为兼容而猜测未知状态。无法唯一解释时保留原数据、停止写入并给出重建或人工修复提示。
+
+## 生命周期阶段要求
+
+- **分析**：区分用户明确兼容要求与模型自行推测；列出现存消费者和数据证据。没有证据时明确采用 current-only。
+- **方案**：为获准兼容标出边界、唯一转换点、窗口和删除计划；不得把兼容层当作低风险默认方案。
+- **实现**：只实现已批准的兼容预算，并在唯一兼容边界写入或随重构移动 `TODO(compat)`。方案未授权的旧分支不得“顺手保留”。
+- **审查**：逐项核对四项准入证据、单一事实源、退出条件及就地 `TODO(compat)`。未经授权的兼容、无期限 shim、双写或主路径迁移应作为范围与维护性问题提出。
+
+## 既有兼容逻辑
+
+普通任务发现范围外的既有兼容逻辑时，只确保唯一边界存在 `TODO(compat)` 并记录位置和风险，不擅自删除，也不重复添加标记。专门的简化任务应先检索这些 TODO、建立消费者与存量数据视图，再按“可立即删除 → 先告警后删除 → 暂时保留”的顺序逐项处理。

package/templates/.agents/rules/create-issue.github.en.md

@@ -1,6 +1,6 @@
 # Issue Creation
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 After `create-task` writes task.md, create and initialize the Issue through declarative internal intents:
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Issue 创建
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 当 `create-task` 完成本地 `task.md` 落盘后，通过声明式内部命令创建 Issue：
 

package/templates/.agents/rules/human-decision-context.en.md

@@ -4,7 +4,7 @@ This rule governs every new `[needs-human-decision]` detail block produced by an
 
 ## Self-contained Context
 
-A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. Start in plain language: explain why a decision is needed now, what must be chosen, which choice is recommended, and why. Then explain what the choice affects and what could go wrong if the wrong choice is made or no action is taken.
+A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. In a fixed order, explain in plain language what must be chosen, why a decision is needed now, what it affects, and what could go wrong if it is wrong or postponed. Then explain each option, followed by the recommendation and its reason.
 
 Provide at least two options with short names. For each option, explain what would actually be done, what would happen after choosing it, its benefits, and its trade-offs. Each decision must also include at least one everyday example or analogy that stays true to the real effects and helps the maintainer compare the options. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
 
@@ -13,13 +13,10 @@ Provide at least two options with short names. For each option, explain what wou
 ```markdown
 ### {AN-N|PL-N|CD-N|HD-N}: {Title} [needs-human-decision]
 
-- **Why a decision is needed now**: {plain-language facts, constraints, and why work cannot simply continue}
 - **What needs a decision**: {the one choice that must be made}
-- **Recommended choice**: {Option A/B/...}
-- **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
+- **Why a decision is needed now**: {plain-language facts, constraints, and why work cannot simply continue}
 - **What this affects**: {affected behavior, files, users, or future practice}
 - **What could go wrong**: {problems caused by the wrong choice or no action}
-- **Everyday example or analogy**: {a familiar comparison that accurately reflects the real effects and helps compare the options}
 
 #### Option A: {Name}
 
@@ -27,6 +24,7 @@ Provide at least two options with short names. For each option, explain what wou
 - **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
+- **Example or analogy**: {a plain-language example that shows this option's real effect}
 
 #### Option B: {Name}
 
@@ -34,9 +32,13 @@ Provide at least two options with short names. For each option, explain what wou
 - **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
+- **Example or analogy**: {a plain-language example that shows this option's real effect}
+
+- **Recommended choice**: {Option A/B/...}
+- **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
 ```
 
-Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. An example or analogy helps understanding; it does not replace facts, concrete effects, or risks. One example that clearly compares the overall choice is enough, so do not mechanically repeat the same analogy under every option. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
+Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. Every option needs its own example or analogy, and it does not replace facts, concrete effects, or risks. Put the recommendation and its reason after all options. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
 
 ## Implementation Intent Declaration
 
@@ -44,4 +46,4 @@ For the code stage, the author must add `**Implementation required**: yes/no` af
 
 ## Decision Closure
 
-Use `ai task decisions <task-ref> <ordinal|ledger-id>` to inspect full context and `ai decide <task-ref> <ordinal|ledger-id> <decision>` to record the ruling. `ai decide` updates the row to `human-decided`, creates an independent `HDR-N` record, and updates evidence and the activity log; do not manually imitate only part of that transaction.
+Use `ai task decisions [--task <ref> | -t <ref>] [--item <ordinal|ledger-id> | -i <ordinal|ledger-id>]` to inspect full context and `ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) <decision>` to record the ruling. `ai decide` updates the row to `human-decided`, creates an independent `HDR-N` record, and updates evidence and the activity log; do not manually imitate only part of that transaction.

package/templates/.agents/rules/human-decision-context.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## 自足性要求
 
-详情必须让维护者不需要了解内部流程，也不需要再问模型，就能看懂并做选择。先用大白话说明为什么现在需要决定、具体要选什么、建议选哪个以及原因；再说明会影响什么、选错或暂不处理会怎样。
+详情必须让维护者不需要了解内部流程，也不需要再问模型，就能看懂并做选择。按固定顺序先用大白话说明要决定什么、为什么现在需要决定、会影响什么以及选错或暂不处理会怎样；再分别说明方案 A/B/...，最后给出建议选哪个及原因。
 
 每项至少提供两个有简短名称的方案，并分别写清实际会怎么做、选了以后会怎样、好处和代价。每项还必须提供至少一个贴近日常、且不歪曲事实的例子或类比，帮助维护者比较方案。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
 
@@ -13,13 +13,10 @@
 ```markdown
 ### {AN-N|PL-N|CD-N|HD-N}：{标题} [needs-human-decision]
 
-- **为什么现在要决定**：{用大白话说明已知情况、限制，以及为什么不能直接继续}
 - **要决定什么**：{本次只需要选定的一件事}
-- **建议选哪个**：{方案 A/B/...}
-- **为什么这样建议**：{结合好处、代价和现有限制说明原因}
+- **为什么现在要决定**：{用大白话说明已知情况、限制，以及为什么不能直接继续}
 - **会影响什么**：{会受影响的功能、文件、用户或后续做法}
 - **如果选错或暂不处理**：{可能出现的问题}
-- **打个比方**：{用一个贴近日常且符合真实影响的例子或类比，帮助比较方案}
 
 #### 方案 A：{名称}
 
@@ -27,6 +24,7 @@
 - **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
+- **例子/类比**：{用大白话举一个能说明该方案实际效果的例子}
 
 #### 方案 B：{名称}
 
@@ -34,9 +32,13 @@
 - **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
+- **例子/类比**：{用大白话举一个能说明该方案实际效果的例子}
+
+- **建议选哪个**：{方案 A/B/...}
+- **为什么这样建议**：{结合好处、代价和现有限制说明原因}
 ```
 
-可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。例子或类比用于帮助理解，不能替代事实、实际影响和风险说明；一个能清楚比较整体选择的例子即可，不必为每个方案机械重复同一类比。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
+可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。每个方案都要有自己的例子或类比，且不能替代事实、实际影响和风险说明。建议和建议原因放在所有方案之后。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
 
 ## 实现意图声明
 
@@ -44,4 +46,4 @@ code 阶段的提出者必须在详情块的方案说明后另写 `**是否需
 
 ## 裁决闭环
 
-使用 `ai task decisions <task-ref> <序号|账本ID>` 查看完整详情，使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 写入裁决。`ai decide` 负责把目标行更新为 `human-decided`、创建独立 `HDR-N` 记录、更新 evidence 与活动日志；不得手工模拟其中一部分写入。
+使用 `ai task decisions [--task <ref> | -t <ref>] [--item <序号|账本ID> | -i <序号|账本ID>]` 查看完整详情，使用 `ai decide [--task <ref> | -t <ref>] (--item <序号|账本ID> | -i <序号|账本ID>) <裁决内容>` 写入裁决。`ai decide` 负责把目标行更新为 `human-decided`、创建独立 `HDR-N` 记录、更新 evidence 与活动日志；不得手工模拟其中一部分写入。

package/templates/.agents/rules/issue-fields.github.en.md

@@ -1,6 +1,6 @@
 # Issue Fields
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 Synchronize Issue Type and pinned fields through one intent:
 

package/templates/.agents/rules/issue-fields.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Issue 字段
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 Issue Type 与 pinned fields 统一由 `platform-issue` intent 动态读取组织 schema 并同步：
 

package/templates/.agents/rules/issue-pr-commands.en.md

@@ -1,6 +1,6 @@
 # PR Platform Intents
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 PR lookup, creation, binding, and metadata synchronization go through typed internal intents. Skills decide branches and write titles/bodies; they do not assemble platform commands.
 

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -1,6 +1,6 @@
 # PR Platform Intents
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 PR lookup, creation, binding, and metadata synchronization go through typed internal intents. Skills decide branches and write titles/bodies; they do not assemble platform commands.
 

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -1,6 +1,6 @@
 # PR 平台意图命令
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 PR 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 

package/templates/.agents/rules/issue-pr-commands.zh-CN.md

@@ -1,6 +1,6 @@
 # PR 平台意图命令
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 PR 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 

package/templates/.agents/rules/issue-sync.github.en.md

@@ -1,6 +1,6 @@
 # Issue Sync
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 ## Marker Registry
 

package/templates/.agents/rules/issue-sync.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Issue 同步规则
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 ## Marker 注册表
 
@@ -27,7 +27,7 @@ agent-infra-internal platform-context resolve [--cwd <path>]
 agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
-  --kind task|artifact|summary|cancel --agent <standard-agent-token> \
+  --kind task|artifact|summary|cancel --agent {standard-agent-token} \
   [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
 ```
 

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -5,17 +5,17 @@
 - The orchestrator only routes and delegates. Stage skills remain the single source of truth for behavior and artifacts.
 - Every stage and rework round uses a fresh executor. Every review uses a fresh reviewer; follow-up reuse is forbidden.
 - A reviewer may only write its review artifact and core-generated task metadata. Business-code, HEAD, or index changes invalidate the receipt.
-- An active run has one pending delegation. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run (on the claude-code path, missing or mismatched model/effort evidence, and fork/spawn-mode evidence this host structurally does not provide, follow the recording rules in `.agents/skills/run-task/reference/host-validation.md` instead and are exempt from this; missing or mismatched `parentId`/`childId` still pauses).
+- An active run has one pending delegation. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run (on the claude-code path, missing or mismatched model/effort evidence, and fork/spawn-mode evidence this host structurally does not provide, follow the recording rules in `.agents/skills/run-task/reference/host-validation.md` instead and are exempt from this; missing or mismatched `parentId`/`childId` still pauses). Cross-root package/build/contract or hook/profile content drift is a deliverable warning; the current receipt's hook/evidence binding remains hard.
 - The first release ends after one existing safely gated `commit`; it does not create a PR, monitor checks, or complete the task.
 
 ## Recovery
 
-`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
+`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. If the state cannot be recognized, preserve the file, advise rebuilding the sandbox or manually repairing it, do not migrate it, and do not create a follow-up task. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
 
 ## Codex Host and Capability
 
-- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence.
-- The controller starts a nested loop only after control generation, task binding, Codex version, closed bundle, build/contract manifest, profiles, and hook discovery pass. Both bypass flags are restricted to this task-bound launch path.
+- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence. The actual hook/profile used by the run is the source of record; content drift is reported as a warning with rebuild guidance.
+- The controller starts a nested loop only after control generation, task binding, protocol version, profiles, and hook discovery pass. Build/contract and content drift is reported as a structured warning with rebuild guidance instead of blocking natural evolution. Both bypass flags are restricted to this task-bound launch path.
 - Every prepare arms a one-use capability attested by the current loop's real PostToolUse. Atomic consumption binds task/session/build/controller and retains only a redacted tombstone.
 
 ## Model Policy

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -5,17 +5,17 @@
 - 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
 - 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
 - reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停（claude-code 路径下 model/effort 证据的缺失或错配、以及该宿主结构上不提供的 fork/spawn-mode 证据，按 `.agents/skills/run-task/reference/host-validation.md` 的记录规则处理，不在此列；`parentId`/`childId` 的缺失或错配仍然暂停）。
+- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停（claude-code 路径下 model/effort 证据的缺失或错配、以及该宿主结构上不提供的 fork/spawn-mode 证据，按 `.agents/skills/run-task/reference/host-validation.md` 的记录规则处理，不在此列；`parentId`/`childId` 的缺失或错配仍然暂停）。跨根 package/build/contract 或 hook/profile 内容漂移只输出可交付 warning；本轮 receipt 的 hook/evidence 绑定仍硬校验。
 - 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
 
 ## 恢复语义
 
-`orchestration.json` 是详细状态源。current run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。读取时只接受当前 writer 的完整结构；未知字段、缺失字段、非法 provenance 或旧 run 一律失败关闭且不改写。升级 agent-infra 前必须完成或清空所有 active run。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。
+`orchestration.json` 是详细状态源。current run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。读取时只接受当前 writer 的完整结构；未知字段、缺失字段、非法 provenance 或旧 run 一律失败关闭且不改写。遇到无法识别的 `orchestration.json`，保留原文件并提示重建 sandbox 或人工修复后重试，不做 schema 迁移，也不创建 follow-up task。升级 agent-infra 前必须完成或清空所有 active run。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。
 
 ## Codex 宿主与 capability
 
-- direct-host 只接受 trusted project 或 managed lifecycle hooks。task-bound sandbox 必须由受控 nested controller 建立隔离 `CODEX_HOME`，仅接受绑定 controller context 的 user hooks；普通 user/plugin hook 不得成为证据源。
-- controller 只有在 control generation、task binding、Codex 版本、closed bundle、build/contract manifest、profile 与 hook discovery 全部通过后才能启动 nested loop。两个 bypass 参数只允许出现在该 task-bound 启动路径。
+- direct-host 只接受 trusted project 或 managed lifecycle hooks。task-bound sandbox 必须由受控 nested controller 建立隔离 `CODEX_HOME`，仅接受绑定 controller context 的 user hooks；普通 user/plugin hook 不得成为证据源。使用本轮实际加载的 hook/profile，内容漂移只记录 warning 并提示重建 sandbox。
+- controller 只有在 control generation、task binding、协议版本、profile 与 hook discovery 全部通过后才能启动 nested loop；build/contract 及内容漂移通过结构化 warning 告知并建议重建 sandbox，不阻塞自然演进。两个 bypass 参数只允许出现在该 task-bound 启动路径。
 - 每次 prepare 前必须 arm 一次性 capability，并由同一当前 loop 的真实 PostToolUse attestation；token 原子消费后保留去敏 tombstone，不能重放或跨 task/session/build/controller 使用。
 
 ## 模型策略

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -1,6 +1,6 @@
 # Milestone Inference
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 Milestones narrow through declarative Issue intents:
 

package/templates/.agents/rules/milestone-inference.github.zh-CN.md

@@ -1,6 +1,6 @@
 # Milestone 推断规则
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 Milestone 继续按生命周期逐步收窄，但候选读取、分支判断、权限降级和写入统一由 `platform-issue` 处理。
 

package/templates/.agents/rules/next-step-output.en.md

@@ -110,11 +110,11 @@ This section is a **third standalone rule, co-equal with the two above**, used o
   …(one entry per status=needs-human-decision row of this stage in task.md `## 审查分歧账本`)
 
 View details:
-  - All pending decisions: ai task decisions {task-ref}
-  - A single item's full background/options/impact/recommendation: ai task decisions {task-ref} <ordinal|ledger-id>
+  - All pending decisions: ai task decisions --task {task-ref}
+  - A single item's full background/options/impact/recommendation: ai task decisions --task {task-ref} --item <ordinal|ledger-id>
 
 To resolve:
-  - ai decide {task-ref} <ordinal|ledger-id> <decision and rationale>
+  - ai decide --task {task-ref} --item <ordinal|ledger-id> <decision and rationale>
 
 This command atomically creates the `HDR-N` ruling record, flips the target ledger row to `human-decided`, and updates evidence and the activity log; do not manually edit only part of the transaction.
 

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -110,11 +110,11 @@ Completed at: YYYY-MM-DD HH:mm:ss
   …（task.md `## 审查分歧账本` 中本阶段每个 status=needs-human-decision 行一条）
 
 查看详情：
-  - 全部待裁决项：ai task decisions {task-ref}
-  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|账本ID>
+  - 全部待裁决项：ai task decisions --task {task-ref}
+  - 单项完整背景/选项/影响/建议：ai task decisions --task {task-ref} --item <序号|账本ID>
 
 完成裁决：
-  - ai decide {task-ref} <序号|账本ID> <裁决内容与理由>
+  - ai decide --task {task-ref} --item <序号|账本ID> <裁决内容与理由>
 
 该命令原子写入 `HDR-N` 裁定记录、把目标账本行翻为 `human-decided`、更新 evidence 与活动日志；不要手工只修改其中一部分。
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -85,7 +85,7 @@ Use these checks together:
 - **Small-impact exemption**: if it is only a local, reversible, low-cost execution detail, record it under `## Assumptions` instead of upgrading it to a human ruling.
 - **Fallback**: when unsure whether it is key, treat it as key; `review-*` must check whether the executor missed any `[needs-human-decision]` markings that should have been upgraded.
 
-> Use `ai task decisions <task-ref>` to view all pending decisions of a task and their detail blocks.
+> Use `ai task decisions [--task <ref> | -t <ref>]` to view all pending decisions of a task and their detail blocks.
 
 ## Human Review Checkpoint Semantics
 

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -85,7 +85,7 @@
 - **小影响豁免**：若它只是局部、可逆、低成本的执行细节，写入 `## 假设` 即可，不升级为人工裁决。
 - **兜底**：无法判断是否关键时按关键处理；`review-*` 需要复核执行方是否漏标应升级的 `[needs-human-decision]`。
 
-> 用户可用 `ai task decisions <task-ref>` 查看某任务全部待裁决项及其详情块。
+> 用户可用 `ai task decisions [--task <ref> | -t <ref>]` 查看某任务全部待裁决项及其详情块。
 
 ## 人工审查检查点语义
 

package/templates/.agents/rules/pr-sync.en.md

@@ -1,6 +1,6 @@
 # PR Summary Synchronization
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, the marker, current HEAD, paginated comment lookup, and create/update/no-op reconciliation.
 
@@ -10,7 +10,7 @@ The model writes the semantic reviewer summary. Typed core owns canonical artifa
 agent-infra-internal platform-pr summary-context {task-id}
 ```
 
-Use only the returned latest canonical `plan*`, `review-plan*`, `code*`, `review-code*`, and `manual-validation*`. The summary covers scope, tests, review history, and exactly one manual-validation state.
+Use only the returned latest canonical `plan*`, `review-plan*`, `code*`, `review-code*`, and `manual-validation*` for lifecycle claims. The summary covers scope, tests, review history, and exactly one manual-validation state. It also includes a `### PR Code Changes` section based on authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, with reconciled runtime, test, skill/rule, template, documentation, and other categories plus rename, mechanical-mirror, and unnecessary-change analysis.
 
 ## Publish
 

package/templates/.agents/rules/pr-sync.github.en.md

@@ -1,6 +1,6 @@
 # PR Summary Synchronization
 
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
 
@@ -31,9 +31,10 @@ The canonical comment envelope produced by the core is:
 ### Key Technical Decisions
 ### Review History
 ### Test Results
+### PR Code Changes
 ```
 
-Canonical inputs include `manual-validation.md`. The manual-validation section is one of `### ✅ Manual Validation Passed`, `### ⚠️ Manual Verification Required`, or `### ✅ No Manual Verification Needed`; `complete-manual-validation` refreshes the same summary in place.
+Canonical inputs include `manual-validation.md`. The manual-validation section is one of `### ✅ Manual Validation Passed`, `### ⚠️ Manual Verification Required`, or `### ✅ No Manual Verification Needed`; `complete-manual-validation` refreshes the same summary in place. The PR code-change section uses authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, reconciles runtime, test, skill/rule, template, documentation, and other categories, and explains renames, mechanical mirrors, and potentially unnecessary changes.
 
 ```bash
 agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \

package/templates/.agents/rules/pr-sync.github.zh-CN.md

@@ -1,6 +1,6 @@
 # PR 摘要同步
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
@@ -24,6 +24,7 @@ agent-infra-internal platform-pr summary-context {task-id}
 - 测试结果
 - 审查历程与当前结论
 - 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
+- `### PR 代码增减`：基于 `platform-pr inspect` 的权威 base/head 和完整 `git diff --find-renames --numstat base...head`，按运行时代码、测试、Skill/规则、模板、文档及其他分类核算，并说明 rename、机械镜像与疑似不必要变化
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
@@ -37,6 +38,7 @@ core 最终包装出的 canonical 评论结构为：
 ### 关键技术决策
 ### 审查历程
 ### 测试结果
+### PR 代码增减
 ```
 
 ## 发布

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -1,6 +1,6 @@
 # PR 摘要同步
 
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
@@ -16,6 +16,7 @@ agent-infra-internal platform-pr summary-context {task-id}
 - 测试结果
 - 审查历程与当前结论
 - 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
+- `### PR 代码增减`：基于 `platform-pr inspect` 的权威 base/head 和完整 `git diff --find-renames --numstat base...head`，按运行时代码、测试、Skill/规则、模板、文档及其他分类核算，并说明 rename、机械镜像与疑似不必要变化
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 

package/templates/.agents/rules/release-commands.github.en.md

@@ -14,6 +14,12 @@ agent-infra-internal platform-release-notes context \
 
 The result contains `history`, `pullRequests`, `closingIssues`, and commit `authors` with normalized `login` / `resolution` values. `status: no-op` with error code `PLATFORM_RELEASE_NOTES_UNSUPPORTED` means the current platform does not support remote release-note operations.
 
+### Identity Safety Boundary
+
+- Render an identity as `@login` only when `resolution` is `platform-user` or `platform-noreply` and `login` is non-empty.
+- Exclude `resolution: unresolved` identities from the release-note contributor list. Never infer a login from a name, email address, domain, brand, or same-named platform account, and never substitute a guessed personal or organization account.
+- Do not publish unresolved identity emails or identity-verification TODOs in Release notes. Record any required investigation outside the release workflow without creating a platform mention.
+
 ## Stage Release Notes
 
 ```bash

package/templates/.agents/rules/release-commands.github.zh-CN.md

@@ -14,6 +14,12 @@ agent-infra-internal platform-release-notes context \
 
 结果包含 `history`、`pullRequests`、`closingIssues` 和带规范化 `login` / `resolution` 的 commit `authors`。`status: no-op` 且错误码为 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` 表示当前平台不支持远端发布说明能力。
 
+### 身份安全边界
+
+- 只有 `resolution` 为 `platform-user` 或 `platform-noreply` 且 `login` 非空的身份可以渲染为 `@login`。
+- `resolution: unresolved` 的身份不得进入发布说明的贡献者列表；不得从 Name、邮箱、域名、品牌或同名平台账号推断 login，也不得替换成推测的个人或组织账号。
+- 不得把未解析身份的邮箱或身份确认 TODO 写入可发布的 Release notes。需要调查时仅在发布流程外记录，不得产生平台 mention。
+
 ## Stage Release notes
 
 ```bash

package/templates/.agents/rules/review-handshake.en.md

@@ -82,7 +82,7 @@ When an executor judges an item to be a key design decision that needs human rul
 - `severity` is always `decision`.
 - `status` starts as `needs-human-decision`, so the existing gate blocks it.
 - `evidence` points to the stable anchor `<artifact>#HD-N` (e.g. `plan-r2.md#HD-1`), not a drift-prone line number.
-- A human records the ruling with `ai decide <task-ref> <ordinal|ledger-id> <decision>`; the command flips the target row to `human-decided` and points `evidence` to an independent `HDR-N` ruling record.
+- A human records the ruling with `ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) <decision>`; the command flips the target row to `human-decided` and points `evidence` to an independent `HDR-N` ruling record.
 
 > Viewing, deciding, and typed verification share the `lib/task/ledger.ts` domain semantics; no second parser is maintained.
 

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -82,7 +82,7 @@
 - `severity` 固定填 `decision`。
 - `status` 初始填 `needs-human-decision`，因此会被现有 gate 阻塞。
 - `evidence` 指向稳定锚点 `<artifact>#HD-N`（如 `plan-r2.md#HD-1`），不依赖易漂移的行号。
-- 人工使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
+- 人工使用 `ai decide [--task <ref> | -t <ref>] (--item <序号|账本ID> | -i <序号|账本ID>) <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
 
 > 查看、裁决与 typed verification 共用 `lib/task/ledger.ts` 的领域语义，不维护第二 parser。
 

package/templates/.agents/rules/review-method.en.md

@@ -43,6 +43,7 @@ mandatory when matched, and `report_evidence` defines the audit trail.
 
 | lens_id | stages | observable_trigger | required_reference | report_evidence |
 |---------|--------|--------------------|--------------------|-----------------|
+| compatibility-budget | analysis, plan, code | Requirements, plans, or implementation add, extend, migrate, or remove old behavior, schemas, entry points, aliases, adapters, wrappers, shims, dual writes, or compatibility reads | `.agents/rules/compatibility-policy.md` | Record the subject, necessity, window, and exit condition, or confirm current-only |
 | documentation-antipatterns | code | The complete change context touches Markdown, rules, skills, CLI help, or user documentation that describes current behavior | `.agents/skills/review-code/reference/documentation-antipatterns.md` | Record triggering files, `loaded=yes`, and the lens result |
 | testing-discipline | code | The complete change context touches tests, fixtures, snapshots, or test helpers | `.agents/rules/testing-discipline.md` | Record triggering files, `loaded=yes`, and the test-discipline result |
 | security-risks | code | Authentication, authorization, untrusted input, sensitive data, credentials, cryptography, dependencies, or system boundaries change | `.agents/skills/review-code/reference/security-risks.md` | Record the changed security boundary, `loaded=yes`, and the lens result |

package/templates/.agents/rules/review-method.zh-CN.md

@@ -35,6 +35,7 @@
 
 | lens_id | stages | observable_trigger | required_reference | report_evidence |
 |---------|--------|--------------------|--------------------|-----------------|
+| compatibility-budget | analysis, plan, code | 需求、方案或实现新增、延长、迁移或删除旧行为、旧 schema、旧入口、alias、adapter、wrapper、shim、双写或兼容读取 | `.agents/rules/compatibility-policy.md` | 记录兼容对象、必要性、期限、退出条件，或确认 current-only |
 | documentation-antipatterns | code | 完整变更上下文触及描述当前行为的 Markdown、规则、skill、CLI 帮助或用户文档 | `.agents/skills/review-code/reference/documentation-antipatterns.md` | 记录触发文件、`loaded=yes` 与检视结果 |
 | testing-discipline | code | 完整变更上下文触及测试、fixture、snapshot 或测试 helper | `.agents/rules/testing-discipline.md` | 记录触发文件、`loaded=yes` 与测试纪律结论 |
 | security-risks | code | 认证授权、非可信输入、敏感数据、凭据、加密、依赖或系统边界发生变化 | `.agents/skills/review-code/reference/security-risks.md` | 记录安全边界变化、`loaded=yes` 与检视结果 |

package/templates/.agents/rules/task-management.en.md

@@ -23,9 +23,8 @@ Map user intent to the corresponding workflow command:
 
 `--agent` values must converge on the standard AI collaborator tokens; OS usernames (e.g. `devuser`) and git usernames (e.g. a human name) are forbidden. The standard set (short tokens are the single source of truth for the activity log):
 
-- AI short tokens: `claude` / `codex` / `antigravity` / `opencode` / `cursor`
+- AI short tokens: `claude` / `codex` / `antigravity` / `opencode` / `cursor` / `traecli`
 - Long-name mapping (normalized to the short token before writing): `claude-code` -> `claude`, `antigravity-cli` -> `antigravity`
-- Historical `gemini` / `gemini-cli` remain read-only for `ai task log` rendering and are not writable
 - Manual-step exception: no matter which agent is used, a human-made decision is always declared as `human`
 
 The seven internal commands (`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.

package/templates/.agents/rules/task-management.zh-CN.md

@@ -23,9 +23,8 @@
 
 `--agent` 取值必须收敛到标准 AI 合作者 token，禁止填入 OS 系统用户名（如 `devuser`）或 git 用户名（如 `季聿阶`）。标准集合（短名为活动日志唯一事实来源）：
 
-- AI 短名：`claude` / `codex` / `antigravity` / `opencode` / `cursor`
+- AI 短名：`claude` / `codex` / `antigravity` / `opencode` / `cursor` / `traecli`
 - 长名映射（写入前归一化为短名）：`claude-code` → `claude`、`antigravity-cli` → `antigravity`
-- 历史 `gemini` / `gemini-cli` 仅保留 `ai task log` 渲染兼容，不接受写入
 - 人工步骤例外：无论使用哪个 Agent，只要是人做的决定，统一声明 `human`
 
 七个内部命令（`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。