@fitlab-ai/agent-infra 0.9.8 → 0.9.10

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

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

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 v3 run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Historical v2 state is read-compatible, but new Codex delegations require v3. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no commit intent or consumed authorization, and no matching unconsumed active lifecycle evidence. Unknown schemas and incomplete active v3 state fail closed.
+`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` 是详细状态源。v3 run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后升级；历史 v2 状态仅兼容读取，新的 Codex delegation 必须写 v3。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 commit intent/authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。迁移是 forward-only，未知 schema 或缺 provenance 的 active v3 一律失败关闭。
+`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/pr-sync.en.md

@@ -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

@@ -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

@@ -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

@@ -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/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

@@ -28,7 +28,7 @@ Map user intent to the corresponding workflow command:
 - 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 six internal commands (`task-event` / `task-lifecycle` / `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.
+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.
 
 ## State Snapshot and Completion Verification Entrypoints
 
@@ -68,7 +68,7 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
   `- {time} — **{base} [started]** by {agent} — started`
 - **done line** (written when the step completes, unchanged from today): the action is the base itself:
   `- {time} — **{base}** by {agent} — {completion summary}`
-- **Commit-specific attempt**: the commit skill must not hand-write started. `commit-start` writes a structured `Commit [started]` with `attempt`, `baseline`, and `agent` under the task lock; `commit-terminate` writes the matching `Commit [aborted]` when an attempt is abandoned before side effects. Aborted closes activity only and is never successful commit evidence.
+- **Commit execution boundary**: the commit skill must not hand-write task Activity Log, review anchors, receipts, or checkpoints. Task-bound direct and orchestrated modes both call the single `commit-operation.execute`; taskless direct is allowed only for `TASK_CONTEXT_NOT_FOUND` and creates no task-state side effects.
 - `{base}` is that skill's existing done action text, including `(Round {N})` (e.g. `Plan Task (Round 1)`). started and done must share the same `{base}` to pair.
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.

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

@@ -28,7 +28,7 @@
 - 历史 `gemini` / `gemini-cli` 仅保留 `ai task log` 渲染兼容，不接受写入
 - 人工步骤例外：无论使用哪个 Agent，只要是人做的决定，统一声明 `human`
 
-六个内部命令（`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
+七个内部命令（`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
 
 ## 状态快照与完成验证入口
 
@@ -70,7 +70,7 @@
   `- {time} — **{基名} [started]** by {agent} — started`
 - **done 行**（步骤完成时写，与现状一致）：action 即基名本身：
   `- {time} — **{基名}** by {agent} — {完成说明}`
-- **Commit 专用 attempt**：commit 技能不得手写 started。`commit-start` 在任务锁内写入带 `attempt`、`baseline`、`agent` 的结构化 `Commit [started]`；无副作用放弃时由 `commit-terminate` 写匹配的 `Commit [aborted]`。aborted 只闭合活动日志，不构成提交成功证据。
+- **Commit 执行边界**：commit 技能不得手写 task Activity Log、review anchor、receipt 或 checkpoint。task-bound direct 与 orchestrated 都调用唯一 `commit-operation.execute`；taskless direct 只在 `TASK_CONTEXT_NOT_FOUND` 时允许，且不产生任务状态副作用。
 - `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
   started 与 done 共用同一 `{基名}` 才能配对。
 

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -15,6 +15,7 @@ If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--or
 
 - This skill only outputs a requirements analysis document (`analysis.md` or `analysis-r{N}.md`) and does not modify any business code
 - Base the analysis strictly on the existing task input, requirements, context, and source information in `task.md`
+- When old behavior, data, schemas, or callers are involved, read `.agents/rules/compatibility-policy.md` first. State current-only when admission evidence is absent; do not turn speculation into a requirement
 - After executing this skill, you **must** immediately update task status in task.md
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -15,6 +15,7 @@ description: >
 
 - 本技能仅产出需求分析文档（`analysis.md` 或 `analysis-r{N}.md`）—— 不修改任何业务代码
 - 严格基于 `task.md` 中已有的任务输入、需求、上下文和来源信息展开分析
+- 涉及旧行为、旧数据、旧 schema 或旧调用方时，先读取 `.agents/rules/compatibility-policy.md`；没有兼容准入证据时明确采用 current-only，不把推测写成需求
 - 执行本技能后，你**必须**立即更新 task.md 中的任务状态
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。

package/templates/.agents/skills/block-task/SKILL.en.md

@@ -99,7 +99,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to blocked/, so read it from `.agents/workspace/blocked/{task-id}/task.md`). This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. Blocked task-bound sandboxes are protected from automatic batch cleanup; if cleanup is necessary, manually verify their identity first. This block is independent of "Next step" semantics.
 
 Output format:
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
@@ -112,9 +112,7 @@ Required to unblock: {what's needed}
 Archived to: .agents/workspace/blocked/{task-id}/
 
 Optional: clean up this task's sandbox
-(The task is blocked and moved to blocked/; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
-
-ai sandbox rm {branch}
+(The task is blocked and moved to blocked/; task-bound sandboxes are protected from automatic `ai sandbox rm --unbound` cleanup. If cleanup is necessary, manually verify the container, control manifest, and worktree identity first.)
 
 To unblock when the issue is resolved:
   agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{activation note}"

package/templates/.agents/skills/block-task/SKILL.zh-CN.md

@@ -100,7 +100,7 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。blocked task-bound 沙箱受保护，不通过自动批量清理；如确需清理，请人工核对身份。该块独立于「下一步」语义。
 
 输出格式：
 使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
@@ -113,9 +113,7 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 归档路径：.agents/workspace/blocked/{task-id}/
 
 可选：清理本任务的沙箱
-（任务已阻塞并移到 blocked/，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
-
-ai sandbox rm {branch}
+（任务已阻塞并移到 blocked/，task-bound 沙箱受保护，不会被 `ai sandbox rm --unbound` 自动删除；如确需清理，请先人工核对容器、控制清单和工作树身份。）
 
 解除阻塞时执行：
   agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{恢复说明}"

package/templates/.agents/skills/cancel-task/SKILL.en.md

@@ -106,7 +106,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to completed/, so read it from `.agents/workspace/completed/{task-id}/task.md`). This block is independent of "Next steps" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. Use the full `{task-id}` for cleanup; do not substitute the branch name. This block is independent of "Next steps" semantics.
 
 Output format:
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
@@ -119,9 +119,9 @@ Status label: {status-label or skipped}
 Target path: .agents/workspace/completed/{task-id}/
 
 Optional: clean up this task's sandbox
-(The task is archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(The task is completed and archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
 
-ai sandbox rm {branch}
+ai sandbox rm {task-id}
 
 Next step - inspect the moved task:
 {next-step-commands}

package/templates/.agents/skills/cancel-task/SKILL.zh-CN.md

@@ -105,7 +105,7 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。清理时使用完整 `{task-id}`，不要改用 branch 名。该块独立于「下一步」语义。
 
 输出格式：
 使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
@@ -118,9 +118,9 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 目标路径：.agents/workspace/completed/{task-id}/
 
 可选：清理本任务的沙箱
-（任务已归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（任务已完成并归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
 
-ai sandbox rm {branch}
+ai sandbox rm {task-id}
 
 下一步 - 查看已转移任务：
 {next-step-commands}

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -93,7 +93,7 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the cleanup hint only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, (3) that task's task.md `branch` exists and is not `main` / `master`, and (4) task state and sandbox workspace identity were cross-validated without conflict. The state and identity select the command: use the full `{task-id}` only for `completed` + `task-bound`; use `{branch}` only when `branch-only` identity was explicitly verified; omit an automatic cleanup command for `active`; for `blocked` / `archive`, render a manual-verification note without a command. If state or identity is missing or conflicting, omit the whole block. Dismissing the alert never implies that the task is completed. This block is independent of "Next step" semantics.
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
 
@@ -110,7 +110,11 @@ View: {html_url}
 Note: it can be reopened on the platform if necessary.
 
 Optional: clean up this task's sandbox
-(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(Only for a `completed` related task with `task-bound` identity, use the full task ID:)
+
+ai sandbox rm {task-id}
+
+(Only when `branch-only` identity was explicitly verified, use the branch name:)
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -93,7 +93,7 @@ agent-infra-internal task-lifecycle {task-id} close-codescan --agent {standard-a
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该任务 task.md 的 `branch` 存在且不是 `main` / `master`、(4) 任务状态与沙箱 workspace identity 已交叉校验且无冲突时，才渲染清理提示。状态和 identity 决定命令：仅 `completed` + `task-bound` 使用完整 `{task-id}`；仅在明确核对为 `branch-only` 时使用 `{branch}`；`active` 不渲染自动清理命令；`blocked` / `archive` 只渲染人工核对提示，不渲染命令。状态或 identity 缺失、冲突时整段省略；关闭告警本身不能推断任务已完成。该块独立于「下一步」语义。
 
 使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 
@@ -110,7 +110,11 @@ Code Scanning 告警 #{alert-number} 已关闭。
 注意：如有需要，可在 平台上重新打开。
 
 可选：清理本任务的沙箱
-（关联任务的沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（仅在关联任务为 `completed` 且 identity 为 `task-bound` 时，使用完整任务 ID：）
+
+ai sandbox rm {task-id}
+
+（仅在明确核对 identity 为 `branch-only` 时，使用分支名：）
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-dependabot/SKILL.en.md

@@ -101,7 +101,7 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the cleanup hint only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, (3) that task's task.md `branch` exists and is not `main` / `master`, and (4) task state and sandbox workspace identity were cross-validated without conflict. The state and identity select the command: use the full `{task-id}` only for `completed` + `task-bound`; use `{branch}` only when `branch-only` identity was explicitly verified; omit an automatic cleanup command for `active`; for `blocked` / `archive`, render a manual-verification note without a command. If state or identity is missing or conflicting, omit the whole block. Dismissing the alert never implies that the task is completed. This block is independent of "Next step" semantics.
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
 
@@ -118,7 +118,11 @@ View: {alert-url}
 Note: it can be reopened on the platform if necessary.
 
 Optional: clean up this task's sandbox
-(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(Only for a `completed` related task with `task-bound` identity, use the full task ID:)
+
+ai sandbox rm {task-id}
+
+(Only when `branch-only` identity was explicitly verified, use the branch name:)
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-dependabot/SKILL.zh-CN.md

@@ -101,7 +101,7 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {standard
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该任务 task.md 的 `branch` 存在且不是 `main` / `master`、(4) 任务状态与沙箱 workspace identity 已交叉校验且无冲突时，才渲染清理提示。状态和 identity 决定命令：仅 `completed` + `task-bound` 使用完整 `{task-id}`；仅在明确核对为 `branch-only` 时使用 `{branch}`；`active` 不渲染自动清理命令；`blocked` / `archive` 只渲染人工核对提示，不渲染命令。状态或 identity 缺失、冲突时整段省略；关闭告警本身不能推断任务已完成。该块独立于「下一步」语义。
 
 使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 
@@ -118,7 +118,11 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {standard
 注意：如有需要，可在平台侧重新打开。
 
 可选：清理本任务的沙箱
-（关联任务的沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（仅在关联任务为 `completed` 且 identity 为 `task-bound` 时，使用完整任务 ID：）
+
+ai sandbox rm {task-id}
+
+（仅在明确核对 identity 为 `branch-only` 时，使用分支名：）
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/code-task/SKILL.en.md

@@ -16,6 +16,7 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 ## Boundary / Critical Rules
 
 - Follow the latest plan artifact: `plan.md` or `plan-r{N}.md`
+- Read `.agents/rules/compatibility-policy.md` before implementation. Implement only the compatibility budget explicitly approved by the plan; never retain old branches, result contracts, or migration shims merely to be “safe”
 - Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; manual-validation items are out of scope
 - If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md` and determine whether implementation is required, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
 - Never auto-run `git add` or `git commit`

package/templates/.agents/skills/code-task/SKILL.zh-CN.md

@@ -16,6 +16,7 @@ description: >
 ## 行为边界 / 关键规则
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
+- 实现前读取 `.agents/rules/compatibility-policy.md`；只实现方案明确批准的兼容预算，不以“稳妥”为由保留旧分支、旧结果契约或迁移 shim
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
 - 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块并判断是否需要实现，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
@@ -35,6 +36,7 @@ description: >
 | 「方案这里不合理，顺手改更好」 | 偏离 `{plan-artifact}` 必须在报告中记录原因；有异议先停下确认，不擅自改方向。 |
 | 「测试过了，顺便提交一下」 | 本技能绝不执行 `git add`/`git commit`，提交是用户显式发起的独立步骤。 |
 | 「审查既然写了，照着改就行」 | 审查可能基于错误 `file:line` 或幻觉；动手前先 Read/Grep 核实，成立才修，不成立就反驳并记入 unresolved，不盲从。 |
+| 「保留旧入口更稳妥，反正只多一个分支」 | 未获批准的兼容是范围扩张和长期债务；没有对象、必要性、期限和退出条件就只实现当前契约。 |
 
 ## 第 0 步：状态核对（执行前硬约束）