@fitlab-ai/agent-infra 0.9.9 → 0.9.10

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

@@ -27,11 +27,10 @@ npm install
 npm run build
 ```
 
-生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如需运行当前检出的 CLI，请直接执行构建产物并比较当前版本与包版本。不要在宿主机上执行 `npm link`：它会写入 npm 全局前缀，并可能遮蔽由 Homebrew 或 npm 安装的稳定版。
 
 ```bash
-npm link
-ai version --raw
+node ./dist/bin/cli.js version --raw
 node -p "'v' + require('./package.json').version"
 ```
 

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

@@ -12,6 +12,7 @@ so you can quickly find "which ones to read" without opening each file.
 - [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
 - [`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.
 
 ## Issue / PR
 

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

@@ -11,6 +11,7 @@
 - [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
+- [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。
 
 ## Issue / PR
 

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

@@ -0,0 +1,39 @@
+# Compatibility Policy
+
+This rule governs compatibility decisions during analysis, planning, implementation, and review. Support the current contract by default. Compatibility is an exception budget that requires evidence and an exit condition; it is not a synonym for safety.
+
+## What Counts as Compatibility
+
+Compatibility logic includes accepting or writing multiple generations of schemas, fields, states, or commands; retaining legacy aliases, adapters, wrappers, or shims; migrating data in the normal runtime path; falling back to different semantics based on an old format; or maintaining parallel facts and tests for old callers.
+
+Current-operation idempotency and crash recovery, explicit platform or permission capability branches, fail-closed handling of unknown state, and user-required public multi-version contracts are not inherently legacy compatibility. Do not use those labels to expand support for an old protocol.
+
+## Admission Gate
+
+Add or extend compatibility only when the task or an existing public contract explicitly requires it and the artifact records all four items:
+
+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.
+
+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.
+
+## Implementation Boundaries
+
+- 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.
+- 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.
+
+## Lifecycle Requirements
+
+- **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.
+
+## 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.

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 current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
+`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. If the state cannot be recognized, preserve the file, advise rebuilding the sandbox or manually repairing it, do not migrate it, and do not create a follow-up task. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
 
 ## Codex Host and Capability
 
-- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence.
-- The controller starts a nested loop only after control generation, task binding, Codex version, closed bundle, build/contract manifest, profiles, and hook discovery pass. Both bypass flags are restricted to this task-bound launch path.
+- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence. The actual hook/profile used by the run is the source of record; content drift is reported as a warning with rebuild guidance.
+- The controller starts a nested loop only after control generation, task binding, protocol version, profiles, and hook discovery pass. Build/contract and content drift is reported as a structured warning with rebuild guidance instead of blocking natural evolution. Both bypass flags are restricted to this task-bound launch path.
 - Every prepare arms a one-use capability attested by the current loop's real PostToolUse. Atomic consumption binds task/session/build/controller and retains only a redacted tombstone.
 
 ## Model Policy

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

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

package/templates/.agents/rules/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/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/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 步：状态核对（执行前硬约束）
 

package/templates/.agents/skills/create-pr/SKILL.en.md

@@ -78,19 +78,25 @@ If `{task-id}` is available and the related task provides `issue_number`, keep `
 
 Capture the `result` field from `platform-pr create` (`pr_created`, `pr_reused`, or `no_op`), then run `agent-infra-internal platform-pr sync {task-id} --agent {standard-agent-token} --metadata --closing-issue --result {primary-result}`. The core copies type / `in:` labels, assignee, and a specific milestone from the Issue and maintains the closing association. Permission-bound items degrade independently, and the Issue is never updated in reverse. After the PR identity is bound, metadata or summary sync failures produce `pr_created_with_warnings`, `pr_reused_with_warnings`, or `no_op_with_warnings` from that primary result, preserve the primary-action fact, and retry only unfinished sync steps.
 
-### 7. Publish the Review Summary
+### 7. Generate the PR Code Change Report
+
+After creating or uniquely reusing the PR, run `agent-infra-internal platform-pr inspect {task-id}` to obtain the authoritative base/head SHAs, then follow `reference/change-report.md` to classify the complete PR additions/deletions, renames, and potentially unnecessary changes. Read that reference before this step.
+
+The report is part of the reviewer summary below and must also appear in the final user response. Do not provide only a grand total or inspect only the last commit.
+
+### 8. Publish the Review Summary
 
 Read the latest context artifacts when they exist: `plan.md` / `plan-r{N}.md`, `review-plan.md` / `review-plan-r{N}.md`, `code.md` / `code-r{N}.md`, and `review-code.md` / `review-code-r{N}.md`.
 
-Aggregate a reviewer-facing summary from those artifacts and maintain a single idempotent summary comment via the hidden marker. Pass the same `--result {primary-result}` to `summary-sync`; a sync substep must not infer whether the PR was created or reused.
+Aggregate a reviewer-facing summary from those artifacts, append the `### PR Code Changes` section generated in step 7, and maintain a single idempotent summary comment via the hidden marker. Pass the same `--result {primary-result}` to `summary-sync`; a sync substep must not infer whether the PR was created or reused.
 
 > Canonical context, aggregation, and the `summary-sync` call live in `reference/comment-publish.md`, which points to `.agents/rules/pr-sync.md`. Read that reference before publishing.
 
-### 8. Confirm Task Status
+### 9. Confirm Task Status
 
 After a PR is created or uniquely recovered, `platform-pr create` atomically updates `pr_number`, `pr_status`, canonical time/version metadata, and the Create PR completion log through the task write core. The caller verifies the structured result and does not edit those fields again.
 
-### 9. Verification Gate
+### 10. Verification Gate
 
 If this operation is associated with `{task-id}`, run the verification gate to confirm task metadata and sync state. If there is no task context, skip this step.
 
@@ -105,13 +111,13 @@ Handle the result as follows:
 
 Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
 
-### 10. Inform User
+### 11. Inform User
 
 > Execute this step only after the verification gate passes.
 
 > 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}`.
 
-Explain the created PR URL, summarize metadata sync and summary-comment results, and recommend watching the PR's checks next (render `{task-ref}` as the short id `NN` per `.agents/rules/next-step-output.md`):
+Explain the created PR URL, summarize metadata sync and summary-comment results, show the complete step 7 category table and necessity conclusion, and recommend watching the PR's checks next (render `{task-ref}` as the short id `NN` per `.agents/rules/next-step-output.md`):
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}`.
 

package/templates/.agents/skills/create-pr/SKILL.zh-CN.md

@@ -78,19 +78,25 @@ description: >
 
 记录 `platform-pr create` 结构化结果中的 `result`（`pr_created`、`pr_reused` 或 `no_op`），并调用 `agent-infra-internal platform-pr sync {task-id} --agent {standard-agent-token} --metadata --closing-issue --result {primary-result}`。core 从 Issue 复制 type / `in:` labels、assignee 和具体 milestone，并维护 Development 关联；逐项权限不足返回 degraded，不反向更新 Issue。PR 已成功绑定后，metadata/summary 同步失败只产生与 primary result 对应的 `pr_created_with_warnings`、`pr_reused_with_warnings` 或 `no_op_with_warnings`，保留主动作事实，重试只执行未完成的同步步骤。
 
-### 7. 发布审查摘要
+### 7. 生成 PR 代码增减报告
+
+创建或唯一复用 PR 后，调用 `agent-infra-internal platform-pr inspect {task-id}` 取得权威 base/head SHA，并按 `reference/change-report.md` 统计完整 PR 的分类增减、rename 与疑似不必要变化。执行本步骤前先读取该 reference。
+
+报告既是下方 reviewer 摘要的一部分，也必须出现在最终用户回复中；不得只给总行数或只统计最后一个 commit。
+
+### 8. 发布审查摘要
 
 读取最新的上下文产物：`plan.md` / `plan-r{N}.md`、`review-plan.md` / `review-plan-r{N}.md`、`code.md` / `code-r{N}.md`、`review-code.md` / `review-code-r{N}.md`（存在时）。
 
-基于这些产物聚合 reviewer 摘要，并使用隐藏标记维护唯一且幂等的摘要评论。调用 `summary-sync` 时继续传递同一个 `--result {primary-result}`，不得根据同步子步骤猜测 PR 是创建还是复用。
+基于这些产物聚合 reviewer 摘要，并追加第 7 步生成的 `### PR 代码增减` 段落，再使用隐藏标记维护唯一且幂等的摘要评论。调用 `summary-sync` 时继续传递同一个 `--result {primary-result}`，不得根据同步子步骤猜测 PR 是创建还是复用。
 
 > canonical context、摘要聚合和 `summary-sync` 调用见 `reference/comment-publish.md`（其引用 `.agents/rules/pr-sync.md`）。发布摘要前先读取该 reference。
 
-### 8. 确认任务状态
+### 9. 确认任务状态
 
 `platform-pr create` 在成功创建或恢复唯一远端身份后，通过任务写入内核原子更新 `pr_number`、`pr_status`、规范时间/版本和 Create PR 完成日志。调用方只核对结构化结果，不再次编辑这些字段。
 
-### 9. 完成校验
+### 10. 完成校验
 
 如果本次操作关联了 `{task-id}`，运行完成校验，确认任务元数据和同步状态符合规范；如果没有任务上下文，跳过本步骤。
 
@@ -105,13 +111,13 @@ agent-infra-internal task-verify {task-id} create-pr.completed --format text
 
 将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
 
-### 10. 告知用户
+### 11. 告知用户
 
 > 仅在校验通过后执行本步骤。
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-说明 PR URL、元数据同步结果、摘要评论结果，并推荐下一步进入 PR 监控（按 `.agents/rules/next-step-output.md` 把 `{task-ref}` 渲染为短号 `NN`）：
+说明 PR URL、元数据同步结果、摘要评论结果，完整展示第 7 步的分类统计表与必要性结论，并推荐下一步进入 PR 监控（按 `.agents/rules/next-step-output.md` 把 `{task-ref}` 渲染为短号 `NN`）：
 
 使用 `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 

package/templates/.agents/skills/create-pr/reference/change-report.en.md

@@ -0,0 +1,41 @@
+# PR Code Change Report
+
+<!-- pr-change-report-contract
+{"version":1,"source":"platform-pr-inspect","diff":"three-dot-find-renames-numstat","publish":["pr-summary","user-response"]}
+-->
+
+After a PR is created or uniquely reused, use the authoritative `base.sha` and `head.sha` returned by `platform-pr inspect` to measure the complete PR diff. Do not substitute the last commit or current worktree state.
+
+## Evidence Commands
+
+```bash
+git diff --find-renames --numstat {base-sha}...{head-sha}
+git diff --find-renames --name-status {base-sha}...{head-sha}
+git diff --find-renames --summary {base-sha}...{head-sha}
+```
+
+Count binary files in the file total but do not invent line counts for `-` numstat values. Explain renames and copies from `name-status` and `summary` separately so moves are not reported as full rewrites.
+
+## Classification and Reconciliation
+
+Using the repository's actual structure, assign every file to exactly one closest category and omit categories that do not apply:
+
+- Runtime code
+- Tests and test support
+- Skills, workflows, and collaboration rules
+- Templates or generated mirrors
+- Documentation
+- Configuration, dependencies, and other files
+
+The table must contain component, file count, additions, deletions, and net change, followed by a total row. Category totals must reconcile exactly with the complete numstat total. Then list the largest changed files and distinguish source, tests, template mirrors, and pure renames.
+
+## Required Analysis
+
+Briefly explain:
+
+- where growth is concentrated and how runtime code compares with tests, docs, and templates;
+- which line changes are path moves, bilingual mirrors, or mechanical synchronization;
+- whether any change cannot be traced directly to the PR goal and may be unnecessary; if none, state the evidence;
+- when a test fixture is much larger than production changes, what risk it covers instead of judging it only by size.
+
+Add the complete report as a `### PR Code Changes` section in the reviewer summary body. Preserve the same table and conclusion in the user-visible create-pr completion response. Do not create a second PR comment for this report.

package/templates/.agents/skills/create-pr/reference/change-report.zh-CN.md

@@ -0,0 +1,41 @@
+# PR 代码增减报告
+
+<!-- pr-change-report-contract
+{"version":1,"source":"platform-pr-inspect","diff":"three-dot-find-renames-numstat","publish":["pr-summary","user-response"]}
+-->
+
+PR 创建或复用成功后，使用 `platform-pr inspect` 返回的权威 `base.sha` 与 `head.sha` 统计完整 PR 差异，不以最后一个 commit 或工作树状态代替。
+
+## 证据命令
+
+```bash
+git diff --find-renames --numstat {base-sha}...{head-sha}
+git diff --find-renames --name-status {base-sha}...{head-sha}
+git diff --find-renames --summary {base-sha}...{head-sha}
+```
+
+`numstat` 中的二进制文件计入文件数，但不虚构行数。rename/copy 依据 `name-status` 与 `summary` 单独说明，避免把移动误报为整文件重写。
+
+## 分类与核算
+
+结合仓库实际结构，把每个文件唯一归入以下最贴近的类别；不适用的类别省略：
+
+- 运行时代码
+- 测试与测试辅助设施
+- Skill / workflow / 协作规则
+- 模板或生成镜像
+- 文档
+- 配置、依赖与其他
+
+输出表格必须包含“部分、文件数、新增、删除、净增”，并有合计行。各类别之和必须与完整 `numstat` 总计一致。随后列出增减最大的文件，并区分源码、测试、模板镜像和纯 rename。
+
+## 分析要求
+
+用简短结论回答：
+
+- 增长主要集中在哪里，运行时代码与测试/文档/模板各占多少；
+- 哪些行数只是路径迁移、双语镜像或机械同步；
+- 是否存在与 PR 目标无法直接对应、疑似不必要的变化；若没有，明确说明判断依据；
+- 若某个测试 fixture 明显大于生产改动，解释它覆盖的风险，而不是仅以行数评价。
+
+将完整报告以 `### PR 代码增减` 段落写入 reviewer 摘要正文，并在 create-pr 的用户可见完成回复中原样保留同一张统计表与结论。不要把报告另建成第二条 PR 评论。

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

@@ -15,6 +15,7 @@ If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--or
 
 - This skill only outputs a technical plan document (`plan.md` or `plan-r{N}.md`) and does not modify any business code
 - This is a **mandatory human review checkpoint**; do not automatically proceed to implementation
+- When the plan touches compatibility, migration, old formats, or old entry points, read `.agents/rules/compatibility-policy.md` first. Do not design adapters, shims, dual writes, or parallel state machines without passing its admission gate
 - 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`.
@@ -75,7 +76,7 @@ Use it to understand:
 
 - Read the relevant source files identified in the analysis
 - Understand the current architecture and patterns
-- Identify constraints (backward compatibility, performance, etc.)
+- Identify explicit constraints, including evidenced and approved compatibility or performance requirements; do not infer a compatibility promise
 - Consider edge cases and failure scenarios
 
 ### 5. Design the Technical Plan

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

@@ -15,6 +15,7 @@ description: >
 
 - 本技能仅产出技术方案文档（`plan.md` 或 `plan-r{N}.md`）—— 不修改任何业务代码
 - 这是一个**强制性的人工审查检查点** —— 不要自动进入实现阶段
+- 方案涉及兼容、迁移、旧格式或旧入口时，先读取 `.agents/rules/compatibility-policy.md`；未通过准入门槛时不得设计 adapter、shim、双写或并行状态机
 - 执行本技能后，你**必须**立即更新 task.md 中的任务状态
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
@@ -76,7 +77,7 @@ agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-t
 
 - 阅读分析中识别的相关源码文件
 - 理解当前架构和模式
-- 识别约束条件（向后兼容性、性能等）
+- 识别明确约束（包括有证据且已获准的兼容性、性能等），不自行推导兼容承诺
 - 考虑边界情况和错误场景
 
 ### 5. 设计技术方案

package/templates/.agents/skills/review-code/reference/migration-risks.en.md

@@ -6,20 +6,22 @@ Use when changes touch persistent formats, schemas, configuration/frontmatter, c
 
 ## Review Questions
 
-- Can old data or configuration be read safely, and is the post-write version boundary explicit?
-- Is migration repeatable, and can execution recover or continue after partial failure?
-- Does the rollback path match the compatibility window between old and new formats?
+- Does compatibility pass the subject, necessity, window, and exit gate in `.agents/rules/compatibility-policy.md`? If not, should the change be current-only?
+- Is an approved conversion concentrated at one boundary and followed by current-format-only writes, rather than teaching business logic multiple versions?
+- If migration is required, is it repeatable, and can partial failure recover or stop safely?
+- When an old format is removed, are its branches, fixtures, tests, and documentation removed in the same change?
 
 ## Evidence Requirements
 
-Record the transition from old input to new state, version decisions, and failure states. Prefer migration tests, fixtures, state transitions, or specification conflicts.
+Record compatibility admission evidence first. For approved compatibility, record the single conversion from old input to current state, version decisions, exit condition, and failure states. Prefer consumer or stored-data evidence, migration tests, fixtures, state transitions, or specification conflicts.
 
 ## Common Counterexamples
 
-- Testing only fresh installation and ignoring existing state.
+- Retaining an old read path “just in case” without real consumers or stored data.
+- Dual-writing formats or maintaining several state machines in the normal path.
 - Assuming migration succeeds once while ignoring retries and partial writes.
 - Replacing data-semantic validation with format-existence checks.
 
 ## When Closure Is Not Possible
 
-Record reproducible corruption or compatibility failures as findings, checks requiring real historical data as manual-validation, and missing samples or rollback evidence as a gap.
+Record unauthorized compatibility, dual writes, and shims without an exit condition as findings. For approved migrations, record reproducible corruption as a finding and checks requiring real historical data as manual-validation. Missing compatibility admission evidence cannot be treated as a harmless gap while approving the change.

package/templates/.agents/skills/review-code/reference/migration-risks.zh-CN.md

@@ -6,20 +6,22 @@
 
 ## 检视问题
 
-- 旧数据或旧配置能否被安全读取，写入后的版本边界是否明确。
-- 迁移是否可重复执行，部分失败后能否恢复或继续。
-- 回滚路径是否与新旧格式的兼容窗口一致。
+- 兼容是否通过 `.agents/rules/compatibility-policy.md` 的对象、必要性、期限和退出条件准入；未准入时是否应直接 current-only。
+- 获准转换是否集中在一个边界，转换后只写当前格式，而不是让业务核心理解多个版本。
+- 若确需迁移，是否可重复执行，部分失败后能否恢复或安全停止。
+- 删除旧格式时，专属分支、fixture、测试和文档是否同轮删除。
 
 ## 证据要求
 
-记录旧输入到新状态的转换、版本判定和失败状态；优先使用迁移测试、fixture、状态转换或规范冲突。
+先记录兼容准入证据；获准兼容时再记录旧输入到当前状态的唯一转换、版本判定、退出条件和失败状态。优先使用消费者/存量数据证据、迁移测试、fixture、状态转换或规范冲突。
 
 ## 常见反例
 
-- 只验证全新安装，不验证已有状态。
+- 没有真实消费者或存量数据，只因“可能需要”就保留旧读取。
+- 同时写新旧格式，或在主路径里维护多套状态机。
 - 假设迁移一次成功，忽略重试和部分写入。
 - 用格式存在性测试替代数据语义验证。
 
 ## 无法闭环时
 
-可复现的数据损坏或兼容失败形成 finding；需要真实历史数据的验证进入 manual-validation；缺少样本或回滚证据时记录 gap。
+未经授权的兼容层、双写或无退出条件 shim 形成 finding。已获准迁移中的可复现数据损坏形成 finding；需要真实历史数据的验证进入 manual-validation；缺少兼容准入证据时不能仅记录 gap 后放行。

package/templates/.agents/skills/run-manual-validation/SKILL.en.md

@@ -12,7 +12,7 @@ description: >
 
 - Select the validation mode, call the sole mechanical entry point, and record evidence; do not mark PR manual validation complete.
 - `complete-manual-validation` remains the maintainer's final registration after coverage is judged sufficient.
-- Never manipulate temporary worktrees, leases, or containers directly; only call `ai task validate`.
+- Never manipulate temporary worktrees, leases, or containers directly; only call `agent-infra-internal task-validate`.
 - Never record tokens, environment variables, full argv, absolute user paths, or raw transcripts in the artifact.
 
 ## Step 0: State Check (pre-execution hard gate)
@@ -28,7 +28,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 1. Read `reference/discovery-and-execution.md` and parse the input mode. Stop before started without an artifact for invalid or partial input.
 2. Run `agent-infra-internal task-artifact {task-id} inspect --family validation-run` and read the latest review-code manual-validation items. Then run `agent-infra-internal platform-pr inspect {task-id}` and use the reference status matrix to discover, merge, and number items. Only automatic mode stops before started when reliable sources are empty or the sole possible source is unreadable; valid explicit mode always continues with the user command as effective work.
 3. Take the round and artifact name from the core result. After confirming valid explicit work or a non-empty discovered list, run `agent-infra-internal task-event {task-id} validation-run.started --agent {standard-agent-token}` and classify each item as `executable|unavailable|unknown|unsafe|unresolved`.
-4. Invoke every executable item separately with `ai task validate {task-ref} --scope snapshot --format json -- {command...}`. Only make a second explicit inplace invocation for that item when evidence proves it is required. If no item is executable, run no fabricated command but still produce coverage-gap evidence.
+4. Invoke every executable item separately with `agent-infra-internal task-validate {task-ref} --scope snapshot --format json -- {command...}`. Only make a second explicit inplace invocation for that item when evidence proves it is required. If no item is executable, run no fabricated command but still produce coverage-gap evidence.
 5. Read `reference/report-template.md`, create `validation-run.md|validation-run-r{N}.md`, and record the input mode, discovered list, per-item results, CLI JSON allowlist, and sanitized summaries.
 6. Run `agent-infra-internal task-event {task-id} validation-run.completed --agent {standard-agent-token} --artifact {artifact}`. When an Issue exists, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` and then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {standard-agent-token}`.
 7. Run `agent-infra-internal task-verify {task-id} validation-run.completed --artifact {artifact} --format text`; fix failures and rerun it.
@@ -36,7 +36,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## Completion Checklist
 
-- [ ] Used `ai task validate` for every executable item, or recorded that none were executable
+- [ ] Used `agent-infra-internal task-validate` for every executable item, or recorded that none were executable
 - [ ] Recorded sanitized validation-run evidence
 - [ ] Did not change PR manual validation completion state
 - [ ] Updated task.md and passed completion verification