@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/update.ts

@@ -20,13 +20,12 @@ 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 };
+  delivery?: { remote?: string; baseRef?: string };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
-  tuis?: unknown;
   agentClients?: unknown;
   customTUIs?: unknown;
 };
@@ -35,6 +34,7 @@ type Defaults = {
   platform: { type: string };
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
+  delivery: { remote: string; baseRef: string };
   labels: Record<string, unknown>;
   files: FileRegistry;
 };
@@ -46,28 +46,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,11 +85,12 @@ async function cmdUpdate(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
+  const deliveryAdded = !config.delivery;
   if (platformAdded) config.platform = structuredClone(defaults.platform);
   if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
   if (taskAdded) config.task = structuredClone(defaults.task);
   if (labelsAdded) config.labels = structuredClone(defaults.labels);
+  if (deliveryAdded) config.delivery = structuredClone(defaults.delivery);
 
   const workflowPlan = planAgentClientReconciliation({
     config: config as unknown as Record<string, unknown>,
@@ -119,7 +101,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 +119,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 +141,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,8 +154,8 @@ 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}.`);
+      if (deliveryAdded) {
+        info(`Default delivery target added to ${CONFIG_PATH}.`);
       }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
@@ -196,15 +172,15 @@ 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}.`);
+    if (hasNewEntries && deliveryAdded) {
+      info(`Default delivery target added to ${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 +196,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.12",
   "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/README.en.md

@@ -13,6 +13,7 @@ so you can quickly find "which ones to read" without opening each file.
 - [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
 - [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
 - [`compatibility-policy.md`](compatibility-policy.md) — Compatibility by exception: admission evidence, implementation boundaries, exit conditions, and lifecycle review requirements.
+- [`sync-content-generation.md`](sync-content-generation.md) — Producer-side Markdown constraints for task and lifecycle content synchronized to Issues.
 
 ## Issue / PR
 
@@ -29,11 +30,12 @@ so you can quickly find "which ones to read" without opening each file.
 - [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — Fresh executor/reviewer, one-use receipt, pause/recovery, and safe endpoint rules for `run-task`.
 - [`review-handshake.md`](review-handshake.md) — Three-stage bidirectional review handshake: four-state disposition, symmetric evidence, disagreement ledger, convergence and post-review commit gate.
 - [`review-method.md`](review-method.md) — Shared three-stage review method: multi-pass review, risk lenses, traceability, and finding evidence.
+- [`local-artifact-repair.md`](local-artifact-repair.md) — Model-per-case repair, mechanical safety gates, dynamic convergence, and result-output contract for failed review artifacts.
 - [`human-decision-context.md`](human-decision-context.md) — Self-contained context and canonical structure for new human-decision details.
 - [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of bare-number short ids.
 - [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.
-- [`label-milestone-setup.md`](label-milestone-setup.md) — Platform commands to initialize labels / milestones.
-- [`security-alerts.md`](security-alerts.md) — Commands to import / close Dependabot and Code Scanning alerts.
+- [`label-milestone-setup.md`](label-milestone-setup.md) — Shared entry points to initialize labels / milestones.
+- [`security-alerts.md`](security-alerts.md) — Shared entry point to import / close dependency and code-scanning alerts.
 
 ## Commit & Release
 

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

@@ -12,6 +12,7 @@
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
 - [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。
+- [`sync-content-generation.md`](sync-content-generation.md) — 同步到 Issue 的任务和生命周期 Markdown 生成约束。
 
 ## Issue / PR
 
@@ -28,11 +29,12 @@
 - [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — `run-task` 的 fresh executor/reviewer、一次性 receipt、暂停恢复与安全终点规则。
 - [`review-handshake.md`](review-handshake.md) — 三阶段双向审查握手协议：四态处置、对称证据、分歧账本、收敛与 post-review commit 门禁。
 - [`review-method.md`](review-method.md) — 三阶段共享检视方法：多遍检视、风险镜头、追踪与 finding 证据契约。
+- [`local-artifact-repair.md`](local-artifact-repair.md) — review artifact 失败后的模型逐例修复、机械安全门、动态收敛与结果输出契约。
 - [`human-decision-context.md`](human-decision-context.md) — 新建人工裁决详情的自足上下文与规范结构。
 - [`task-short-id.md`](task-short-id.md) — 裸数字任务短号的解析、分配与生命周期。
 - [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。
-- [`label-milestone-setup.md`](label-milestone-setup.md) — 初始化 label / milestone 的平台命令集。
-- [`security-alerts.md`](security-alerts.md) — 导入 / 关闭 Dependabot 与 Code Scanning 告警的命令集。
+- [`label-milestone-setup.md`](label-milestone-setup.md) — 初始化 label / milestone 的共享入口。
+- [`security-alerts.md`](security-alerts.md) — 导入 / 关闭依赖与代码扫描告警的共享入口。
 
 ## 提交与发布
 

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.en.md

@@ -1,5 +1,14 @@
 # Issue Creation
 
-This code platform does not provide an Issue adapter. `platform-issue create` returns a structured no-op/degraded result.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `code-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.
+After `create-task` writes task.md, create and initialize the Issue through declarative internal intents:
+
+```bash
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
+```
+
+The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `issue_number` binding.
+
+`planned|applied|no-op|degraded` exit 0, `failed` exits 1, and `blocked` exits 2. Callers must not fall back to direct platform CLI or GraphQL orchestration.

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

@@ -1,5 +1,27 @@
 # Issue 创建
 
-当前代码平台未提供 Issue 适配器；`platform-issue create` 返回结构化 no-op/degraded 结果。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `code-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。
+当 `create-task` 完成本地 `task.md` 落盘后，通过声明式内部命令创建 Issue：
+
+```bash
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+```
+
+命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `issue_number`。
+
+创建后的初始元数据使用同一适配层同步：
+
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} \
+  --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
+```
+
+## 结果处理
+
+- `planned|applied|no-op|degraded`：exit 0；调用方按 operations 继续评论同步。
+- `failed`：exit 1；调用方登记 `ISSUE_CREATE_FAILED` warning，不伪造绑定。
+- `blocked`：exit 2；认证、网络或创建 outcome 不确定，调用方保留远端 identity 证据并停止盲目重试。
+- 已绑定有效 Issue 时只验证绑定并返回 no-op，绝不重复创建。
+
+自定义或空平台返回 no-op/degraded；调用方不得回退到直接平台 CLI 或 GraphQL 编排。

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 → issue-fields.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 → issue-fields.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.
 
@@ -12,36 +12,23 @@ agent-infra-internal platform-pr inspect {task-id}
 
 ## Create or recover
 
-Write the title and body to files, then run:
-
 ```bash
 agent-infra-internal platform-pr create {task-id} \
   --agent {standard-agent-token} --base {target-branch} --head {current-branch} \
   --title-file {title-file} --body-file {body-file}
 ```
 
-The core performs exact upstream/head/base lookup first. One match is reused, zero creates, and multiple matches fail closed. Unknown create outcomes are reconciled by the same exact identity rather than retried blindly. `--dry-run` returns only the plan.
+The core performs exact upstream/head/base lookup. One match is reused, zero creates, and multiple matches fail closed. Unknown create outcomes are reconciled by exact identity. `--dry-run` returns only the plan.
 
-## Bind
+## Bind and synchronize
 
 ```bash
 agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {standard-agent-token}
-```
-
-Conflicting bindings fail without changing `task.md`.
 
-## Synchronize metadata
-
-```bash
 agent-infra-internal platform-pr sync {task-id} \
   --agent {standard-agent-token} --metadata --closing-issue
 ```
 
-The core copies type / `in:` labels, assignee, a specific milestone, and the closing association from the linked Issue. Permission-bound operations report `skipped` under top-level `degraded`; the Issue is never updated in reverse.
-
-## Status contract
+Conflicting bindings do not change `task.md`. Metadata comes from the linked Issue, permission-bound items degrade independently, and an already-created PR is never rolled back.
 
-- `planned|applied|no-op|degraded`: exit 0.
-- `failed`: exit 1.
-- `blocked`: exit 2 for authentication, network, or unknown outcome.
-- Metadata or summary failures never roll back an already-created PR.
+Statuses `planned|applied|no-op|degraded` exit 0, `failed` exits 1, and `blocked` exits 2.

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.en.md

@@ -1,8 +1,8 @@
 # Issue Sync
 
-## Marker Registry
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-These hidden markers are the canonical registry for Issue synchronization:
+## Marker Registry
 
 | Key | Marker |
 |---|---|
@@ -12,8 +12,29 @@ These hidden markers are the canonical registry for Issue synchronization:
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
-Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
+`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue number and reads only registered Issue markers, with no PR source.
+
+Comments use `platform-comment`; Issue resources use `platform-issue`:
+
+```bash
+agent-infra-internal platform-issue inspect {task-id}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
+```
+
+The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.
+
+`planned|applied|no-op|degraded` exit 0; `failed` exits 1; `blocked` exits 2.
+
+Map material degraded/failed/blocked results to workflow warnings through the structured intent; callers must not edit warning rows directly:
+
+```bash
+agent-infra-internal task-warning {task-id} add \
+  --step issue-sync --severity {severity} --code {code} \
+  --target {target} --message {message} --action {action}
+```
 
-This code platform does not provide an Issue adapter. `platform-issue` returns structured no-op/degraded operations.
+## Backfill
 
-Issue metadata, labels, milestones, assignees, and comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and platform adapters. Continue writing local task artifacts normally.
+During completion, artifact comments are replayed with `--kind artifact --artifact <file> --backfill`. If the remote Issue has no matching marker, the core creates a comment with a historical-backfill notice. If a valid base or chunk marker set already exists, the core returns `no-op` and preserves the existing bodies and chunks. Marker conflicts still fail without writes.