@fitlab-ai/agent-infra 0.9.10 → 0.9.11

package/lib/update.ts

@@ -20,13 +20,11 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
-  requiresPullRequest?: boolean;       // legacy field; read-only, migrated to prFlow then removed
   prFlow?: 'required' | 'disabled';
   sandbox?: Record<string, unknown>;
   task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
-  tuis?: unknown;
   agentClients?: unknown;
   customTUIs?: unknown;
 };
@@ -46,28 +44,9 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
-// One-time migration of the legacy project-level PR switch to the three-state
-// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
-// strong constraint `required`; `false` maps to `disabled`. A missing or
-// already-migrated config is left untouched (idempotent). Returns the new
-// prFlow value when a migration happened, otherwise null.
-function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
-  if (config.requiresPullRequest === true) {
-    delete config.requiresPullRequest;
-    config.prFlow = 'required';
-    return 'required';
-  }
-  if (config.requiresPullRequest === false) {
-    delete config.requiresPullRequest;
-    config.prFlow = 'disabled';
-    return 'disabled';
-  }
-  return null;
-}
-
-async function cmdUpdate(): Promise<void> {
+async function cmdSync(): Promise<void> {
   console.log('');
-  console.log('  ai update');
+  console.log('  ai sync');
   console.log('  ==================================');
   console.log('');
 
@@ -104,7 +83,6 @@ async function cmdUpdate(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
   if (platformAdded) config.platform = structuredClone(defaults.platform);
   if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
   if (taskAdded) config.task = structuredClone(defaults.task);
@@ -119,7 +97,7 @@ async function cmdUpdate(): Promise<void> {
     language
   });
 
-  info(`Updating seed files for: ${project}`);
+  info(`Syncing seed files for: ${project}`);
   console.log('');
 
   // update skill
@@ -137,12 +115,6 @@ async function cmdUpdate(): Promise<void> {
     replacements
   );
   ok('Updated .agents/scripts/lib/agent-infra-package.js');
-  try {
-    fs.unlinkSync(path.join('.agents', 'skills', 'update-agent-infra', 'scripts', 'sync-templates.cjs'));
-  } catch {
-    // Ignore missing legacy script from pre-ESM installs.
-  }
-
   const added = {
     managed: workflowPlan.projectAssets.registry.managed.filter(
       (entry) => !currentRegistry.managed.includes(entry)
@@ -165,7 +137,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -178,9 +150,6 @@ async function cmdUpdate(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
-      if (prFlowMigrated) {
-        info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
-      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -196,15 +165,12 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && prFlowMigrated) {
-      info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
-    }
     ok(`Updated ${CONFIG_PATH}`);
   }
 
   // done
   console.log('');
-  ok('Seed files updated successfully!');
+  ok('Seed files synced successfully!');
   console.log('');
   if (workflowPlan.nextSteps.length === 0) {
     console.log('  No Agent Client project integration enabled.');
@@ -220,4 +186,4 @@ async function cmdUpdate(): Promise<void> {
   }
 }
 
-export { cmdUpdate };
+export { cmdSync };

package/lib/version.ts

@@ -11,5 +11,10 @@ if (!packageJsonUrl) {
 
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
+const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
-export { VERSION };
+function isValidAgentInfraVersion(value: unknown): value is string {
+  return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
+}
+
+export { VERSION, isValidAgentInfraVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/README.en.md

@@ -124,7 +124,7 @@ To adapt agent-infra to a private code-hosting platform:
 
 1. Set `.agents/.airc.json` `platform.type` to a stable identifier such as `my-platform`.
 2. Copy the generated rule files in `.agents/rules/` and adapt them to your platform's CLI or API while keeping the runtime filenames unchanged.
-3. Add the customized rule files to `.agents/.airc.json` `files.ejected` so future `agent-infra update` runs do not overwrite them.
+3. Add the customized rule files to `.agents/.airc.json` `files.ejected` so future `ai sync` runs do not overwrite them.
 4. If you maintain a fork of the template source, add matching `.{platform}.` template variants before adding that platform identifier to the sync logic.
 5. Validate the customized workflow on a test task before rolling it out broadly.
 
@@ -227,7 +227,7 @@ Ordinary `managed` files keep their overwrite semantics. A small set of platform
 
 ## Agent Client Configuration
 
-Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `antigravity-cli`, `opencode`). Each canonical entry has three required fields and one optional orchestration policy:
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all five built-in clients (`claude-code`, `codex`, `antigravity-cli`, `opencode`, `traecli`). Each canonical entry has three required fields and one optional orchestration policy:
 
 | Field | Meaning |
 |-------|---------|
@@ -250,7 +250,9 @@ ai agent-client configure
 
 `enable` and `disable` only change `enabled`; `configure` edits both dimensions. `ai init` asks which clients to enable and preserves the displayed defaults when you press Enter. All clients default to `installInSandbox: true`.
 
-Legacy `tuis` and built-in client ids in `sandbox.tools` are migration inputs only. The next config-writing command converts them into the canonical `agentClients` array and removes the legacy fields. If canonical and legacy values conflict, the command stops without modifying files so the conflict can be resolved explicitly.
+TraeCode CLI uses `.agents/skills/` as the canonical Skill source. agent-infra generates lightweight slash-command wrappers under `.traecli/commands/`; each wrapper reads the corresponding shared Skill and forwards `$ARGUMENTS` when that Skill declares arguments. It does not mirror Skill packages into `.trae/skills/`, which remains user-owned for intentional Trae-specific overrides.
+
+`agentClients` is the sole source of truth for built-in client state. The top-level array must contain all five built-in clients in the fixed canonical order; `sandbox.tools` lists only non-client tools such as `agent-infra` and custom tools. A legacy `tuis` field or a built-in client id in `sandbox.tools` is rejected, and configuration is never rewritten automatically.
 
 ### Side effects of disabling an Agent Client
 

package/templates/.agents/README.zh-CN.md

@@ -122,7 +122,7 @@
 
 1. 在 `.agents/.airc.json` 中把 `platform.type` 设为稳定标识，例如 `my-platform`。
 2. 以 `.agents/rules/` 下已生成的规则文件为起点，改写为你的平台 CLI 或 API 调用，同时保持运行时文件名不变。
-3. 将这些自定义规则文件加入 `.agents/.airc.json` 的 `files.ejected`，避免后续执行 `agent-infra update` 时被覆盖。
+3. 将这些自定义规则文件加入 `.agents/.airc.json` 的 `files.ejected`，避免后续执行 `ai sync` 时被覆盖。
 4. 如果你维护的是模板源码分支或私有 fork，需要先补齐对应的 `.{platform}.` 模板变体，再把该平台标识加入模板同步逻辑。
 5. 在正式推广前，先用一个测试任务完整验证工作流和 gate 校验。
 
@@ -225,7 +225,7 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 ## Agent Client 配置
 
-`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部四个内建客户端（`claude-code`、`codex`、`antigravity-cli`、`opencode`）。每个规范条目包含三个必填字段和一个可选编排策略：
+`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部五个内建客户端（`claude-code`、`codex`、`antigravity-cli`、`opencode`、`traecli`）。每个规范条目包含三个必填字段和一个可选编排策略：
 
 | 字段 | 含义 |
 |------|------|
@@ -248,7 +248,9 @@ ai agent-client configure
 
 `enable` 和 `disable` 只修改 `enabled`；`configure` 同时编辑两个维度。`ai init` 会询问启用哪些客户端，直接回车会保留界面展示的默认值。所有客户端的 `installInSandbox` 默认均为 `true`。
 
-旧 `tuis` 字段和 `sandbox.tools` 中的内建客户端 id 仅作为迁移输入。下一次写配置的命令会将其转换为规范 `agentClients` 数组并移除旧字段。若规范配置与旧配置冲突，命令会在修改文件前停止，要求显式解决冲突。
+TraeCode CLI 以 `.agents/skills/` 作为 Skill 的唯一权威源。agent-infra 仅在 `.traecli/commands/` 下生成轻量 slash-command 包装文件；每个包装文件读取对应的共享 Skill，并在该 Skill 声明参数时转发 `$ARGUMENTS`。它不会把 Skill 包镜像到 `.trae/skills/`；该目录继续由用户所有，仅用于有意添加的 Trae 专属覆盖。
+
+`agentClients` 是内建客户端状态的唯一配置来源。顶层数组必须按固定规范顺序包含全部五个内建客户端；`sandbox.tools` 只列出 `agent-infra` 和自定义工具等非客户端工具。旧 `tuis` 字段或 `sandbox.tools` 中的内建客户端 id 会被拒绝，配置不会被自动改写。
 
 ### 取消 Agent Client 的副作用
 

package/templates/.agents/rules/compatibility-policy.en.md

@@ -15,7 +15,7 @@ Add or extend compatibility only when the task or an existing public contract ex
 1. **Subject**: concrete consumers, released versions, or stored data still using the old contract.
 2. **Necessity**: why an atomic cutover, one-time conversion, or actionable failure is insufficient.
 3. **Window**: a version, date, or verifiable endpoint for the compatibility period.
-4. **Exit**: removal conditions, ownership, and the code, tests, and documentation to delete.
+4. **Exit**: removal conditions and the code, tests, and documentation to delete.
 
 If any item is missing, compatibility is unauthorized scope expansion. Implement the current contract, fail closed with an actionable repair message for old input, or perform an explicit one-time conversion outside the main path.
 
@@ -23,6 +23,7 @@ If any item is missing, compatibility is unauthorized scope expansion. Implement
 
 - Keep one canonical write format and one source of truth. Do not dual-write, maintain shadow state, or try the new path before silently falling back to the old path.
 - Concentrate an approved conversion at one boundary and immediately enter the current model; business logic must not understand several historical versions.
+- Mark temporarily retained compatibility at its single boundary with `TODO(compat): Remove ... once ...`, naming the removal target and a verifiable removal condition. The TODO stays co-located with the code; tasks and issues are optional scheduling aids, not compatibility facts or workflow gates.
 - Use warnings only when the primary action remains correct and the user can retry an ancillary operation. Never hide uncertainty about identity, authorization, data interpretation, or side-effect correctness.
 - When removing an old capability, remove its adapters, branches, fixtures, tests, and migration documentation together. Do not add negative tests that permanently remember deleted behavior.
 - Never guess the meaning of unknown state. Preserve it, stop writes, and provide rebuild or manual-repair guidance.
@@ -31,9 +32,9 @@ If any item is missing, compatibility is unauthorized scope expansion. Implement
 
 - **Analysis**: separate explicit compatibility requirements from model speculation and identify real consumers or stored data. State current-only when evidence is absent.
 - **Plan**: for approved compatibility, identify the boundary, single conversion point, window, and deletion plan. Do not present a compatibility layer as the default low-risk option.
-- **Implementation**: implement only the approved compatibility budget. Do not preserve an unapproved old branch “just in case.”
-- **Review**: verify the four admission items, single source of truth, and exit condition. Flag unauthorized compatibility, indefinite shims, dual writes, and runtime-path migrations as scope and maintainability problems.
+- **Implementation**: implement only the approved compatibility budget, and add or move its `TODO(compat)` at the single compatibility boundary. Do not preserve an unapproved old branch “just in case.”
+- **Review**: verify the four admission items, single source of truth, exit condition, and co-located `TODO(compat)`. Flag unauthorized compatibility, indefinite shims, dual writes, and runtime-path migrations as scope and maintainability problems.
 
 ## Existing Compatibility Logic
 
-During an ordinary task, record out-of-scope compatibility logic and its risk without deleting it. A dedicated simplification task should first inventory consumers and stored data, then process items in this order: remove now, warn then remove, retain temporarily.
+During an ordinary task, when out-of-scope compatibility is found, only ensure that its single boundary has one `TODO(compat)` and record the location and risk. Do not delete the logic or duplicate the marker. A dedicated simplification task should first search those TODOs and inventory consumers and stored data, then process items in this order: remove now, warn then remove, retain temporarily.

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

@@ -15,7 +15,7 @@
 1. **对象**：仍在使用旧契约的具体消费者、已发布版本或存量数据。
 2. **必要性**：为何不能原子切换、一次性转换或直接失败并提示修复。
 3. **期限**：兼容窗口的版本、日期或可验证终点。
-4. **退出**：删除条件、责任归属以及届时要删除的代码、测试和文档。
+4. **退出**：删除条件以及届时要删除的代码、测试和文档。
 
 缺少任一项时，兼容属于未经授权的范围扩张：按当前契约实现；遇到旧输入时失败关闭并提供可操作提示，或在主路径之外执行一次性显式转换。
 
@@ -23,6 +23,7 @@
 
 - 当前契约只有一个规范写入格式和一个事实源；禁止双写、影子状态和“先试新逻辑、失败再走旧逻辑”。
 - 兼容转换集中在单一边界，转换后立即进入当前模型；业务核心不得感知多个历史版本。
+- 暂时保留的兼容逻辑必须在唯一兼容边界使用 `TODO(compat): Remove ... once ...` 标记要删除的对象和可验证删除条件。该 TODO 与代码同源；任务或 Issue 只用于可选排期，不作为兼容事实源或工作流门禁。
 - warning 只用于主动作仍然正确且用户可重试的外围问题，不能掩盖身份、授权、数据解释或副作用正确性的不确定。
 - 删除旧能力时同步删除专属 adapter、分支、fixture、测试和迁移文档；不要新增“已删除能力不存在”的反向断言。
 - 不为兼容而猜测未知状态。无法唯一解释时保留原数据、停止写入并给出重建或人工修复提示。
@@ -31,9 +32,9 @@
 
 - **分析**：区分用户明确兼容要求与模型自行推测；列出现存消费者和数据证据。没有证据时明确采用 current-only。
 - **方案**：为获准兼容标出边界、唯一转换点、窗口和删除计划；不得把兼容层当作低风险默认方案。
-- **实现**：只实现已批准的兼容预算。方案未授权的旧分支不得“顺手保留”。
-- **审查**：逐项核对四项准入证据、单一事实源和退出条件。未经授权的兼容、无期限 shim、双写或主路径迁移应作为范围与维护性问题提出。
+- **实现**：只实现已批准的兼容预算，并在唯一兼容边界写入或随重构移动 `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/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.
 

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.
 

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 负责。
 

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 负责。
 

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