@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/version.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import semver from 'semver';
 
 const packageJsonUrl = [
   new URL('../package.json', import.meta.url),
@@ -12,9 +13,22 @@ 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.-]+)?$/;
+const LEGACY_COMPATIBILITY_CUTOFF_VERSION = '1.0.0';
 
 function isValidAgentInfraVersion(value: unknown): value is string {
   return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
 
-export { VERSION, isValidAgentInfraVersion };
+function isLegacyCompatibilityEnabled(runtimeVersion = VERSION): boolean {
+  const normalized = runtimeVersion.startsWith('v') ? runtimeVersion.slice(1) : runtimeVersion;
+  const parsed = semver.valid(normalized);
+  return parsed !== null && semver.lt(parsed, LEGACY_COMPATIBILITY_CUTOFF_VERSION);
+}
+
+function legacyCompatibilityError(resource: string, runtimeVersion = VERSION): Error & { code: string } {
+  return Object.assign(new Error(
+    `PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: ${resource} requires migration to the current schema before v${LEGACY_COMPATIBILITY_CUTOFF_VERSION} runtime ${runtimeVersion}`
+  ), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
+}
+
+export { LEGACY_COMPATIBILITY_CUTOFF_VERSION, VERSION, isLegacyCompatibilityEnabled, isValidAgentInfraVersion, legacyCompatibilityError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,12 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "exports": {
+    "./platform-provider": {
+      "types": "./dist/lib/platform/provider-contract.d.ts",
+      "import": "./dist/lib/platform/provider-contract.js"
+    }
+  },
   "bin": {
     "agent-infra": "./dist/bin/cli.js",
     "ai": "./dist/bin/cli.js",
@@ -48,6 +54,7 @@
     "@clack/prompts": "1.7.0",
     "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
+    "fs-ext-extra-prebuilt": "2.2.13",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
     "smol-toml": "^1.6.1",
@@ -59,6 +66,7 @@
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
     "test:smoke": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\"",
+    "test:smoke:fast": "node scripts/run-tests.js --skip-build \"tests/unit/**/*.test.ts\"",
     "test:core": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
     "test:integration": "node scripts/run-tests.js \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
@@ -77,5 +85,8 @@
   },
   "overrides": {
     "axios": "1.18.1"
+  },
+  "allowScripts": {
+    "fs-ext-extra-prebuilt@2.2.13": true
   }
 }

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

@@ -13,7 +13,9 @@ 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.
+- [`evidence-reporting.md`](evidence-reporting.md) — Minimum evidence semantics for state checks, successful summaries, exceptional results, identity fields, and sensitive data boundaries.
 - [`sync-content-generation.md`](sync-content-generation.md) — Producer-side Markdown constraints for task and lifecycle content synchronized to Issues.
+- [`decision-qualification.md`](decision-qualification.md) — Constraint, candidate, human-confirmation, and six-artifact qualification-audit contract.
 
 ## Issue / PR
 
@@ -30,7 +32,7 @@ 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.
+- [`local-artifact-repair.md`](local-artifact-repair.md) — Pre-completion local artifact validation for analysis/plan/code and model-per-case repair, safety gates, and convergence 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.

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

@@ -12,7 +12,9 @@
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
 - [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。
+- [`evidence-reporting.md`](evidence-reporting.md) — 生命周期报告的状态核对、成功摘要、异常证据、身份字段和敏感信息边界。
 - [`sync-content-generation.md`](sync-content-generation.md) — 同步到 Issue 的任务和生命周期 Markdown 生成约束。
+- [`decision-qualification.md`](decision-qualification.md) — 约束、候选、人工确认和六类 artifact 资格审计契约。
 
 ## Issue / PR
 
@@ -29,7 +31,7 @@
 - [`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 失败后的模型逐例修复、机械安全门、动态收敛与结果输出契约。
+- [`local-artifact-repair.md`](local-artifact-repair.md) — analysis/plan/code completed 前的本地产物校验、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 推断。

package/templates/.agents/rules/decision-qualification.en.md

@@ -0,0 +1,22 @@
+# Decision Qualification and Constraint Audit
+
+Any analysis, plan, implementation, or review that decides whether a human decision is needed must audit qualification from the normalized constraints and candidates in `task.md` before creating `HD-N`.
+
+## Single source of truth
+
+- The `### Constraints` and `### Candidate and Rejected Options` tables in `task.md` are the only constraint and candidate fact source.
+- The constraint table uses `constraint_id`, `statement`, `status`, `authority`, `source`, `evidence`, `derived_from`, and `approval_evidence`; the candidate table uses `candidate_id`, `statement`, `status`, `constraint_ids`, `impact`, and `evidence`.
+- All six artifact families must include `## Qualification Audit` with actual constraint dependencies, candidate qualification, classification results, upstream relations, and a dependency snapshot. Each upstream relation records family, file name, round, and SHA-256.
+
+## Status and confirmation
+
+- A `confirmed` constraint requires source evidence, the current semantic digest, and a qualification confirmation record; a confirmation for an old digest cannot be reused.
+- `derived`, `assumption`, `open`, `conflicted`, and `superseded` are pending facts and cannot automatically exclude a candidate.
+- The internal proposal entry point may write only non-confirmed constraints and `pending` candidates. It cannot write actor, QCR, confirmed, or approval fields.
+- `agent-infra-internal task-qualification` is the internal confirmation, supersession, and revocation entry point for agents and skills; ordinary users are not exposed to the constraint-digest protocol. `human-declared` is an audit label, not identity authentication. On confirmation, the core generates the QCR and binds it to the current post-write per-constraint digest, request id, time, and a single-line rationale. Supersession and revocation move the constraint to `superseded` and `open`, respectively, clear current approval evidence, and retain historical QCRs.
+
+## Invalidation and review
+
+When a constraint changes, only artifacts declaring the affected `C-N` can be direct invalidation seeds; the change then follows the real downstream closure. All six families, including reviews, are symmetric. If snapshots, relations, or change classification cannot prove a pure constraint change, use the existing full invalidation path. The newly completed source artifact, its receipt, and its derived snapshot are excluded from the old target graph.
+
+Missing or unknown references, digest mismatches, dangling relations, and cycles fail closed. Formatting-only changes must not change semantic digests; changes to meaning, provenance, status, candidates, or upstream identity require a new audit.

package/templates/.agents/rules/decision-qualification.zh-CN.md

@@ -0,0 +1,22 @@
+# 决策资格与约束审计
+
+涉及“是否需要人工裁决”的分析、方案、实现或审查，必须先基于 `task.md` 的规范化约束和候选表完成资格审计，再决定是否创建 `HD-N`。
+
+## 唯一事实源
+
+- `task.md` 的 `### 约束` 和 `### 候选与否决方案` 是唯一约束/候选事实源。
+- 约束表必须使用 `constraint_id`、`statement`、`status`、`authority`、`source`、`evidence`、`derived_from`、`approval_evidence`；候选表必须使用 `candidate_id`、`statement`、`status`、`constraint_ids`、`impact`、`evidence`。
+- 六类阶段产物都要在 `## 资格审计` 中声明实际约束依赖、候选资格、分类结果、上游关系和依赖快照。上游关系必须保存 artifact 的 family、文件名、round 和 SHA-256。
+
+## 状态与确认
+
+- `confirmed` 约束必须有来源证据、当前语义 digest 和 `资格确认记录`；旧 digest 的确认不能复用。
+- `derived`、`assumption`、`open`、`conflicted`、`superseded` 只能作为待审事实，不能自动排除候选。
+- 内部 proposal 入口只能写入非 confirmed 约束和 `pending` 候选，不能写 actor、QCR、confirmed 或 approval 字段。
+- `agent-infra-internal task-qualification` 是供 Agent/skill 使用的内部确认、替代和撤销入口，不向普通用户暴露 constraint digest 协议；`human-declared` 是审计标签，不是身份认证。确认时 QCR 由核心生成并绑定确认写入后的当前单约束 digest、request id、时间和单行理由；替代与撤销分别把约束转为 `superseded` 与 `open`，清空当前 approval evidence，并保留历史 QCR。
+
+## 失效与审查
+
+约束变化时，只有声明受影响 `C-N` 的 artifact 才能成为直接失效种子，并沿真实上游关系的下游闭包传播；六类 artifact（含 review）对等处理。快照、关系图或变化分类无法证明为纯约束变化时，回退既有全量失效路径。新完成的 source artifact、自身 receipt 和派生快照不作为旧图目标。
+
+缺失、未知引用、digest 不匹配、悬空关系或环都必须 fail closed。排版变化不应改变语义 digest；语义、来源、状态、候选或上游 identity 变化必须触发重新审计。

package/templates/.agents/rules/evidence-reporting.en.md

@@ -0,0 +1,28 @@
+# Lifecycle Evidence Reporting
+
+This rule governs lifecycle reports persisted in the task workspace or synchronized to an Issue. It defines the minimum evidence semantics without changing artifact identity, receipts, synchronization, or restore protocols.
+
+## State Check
+
+- Record the `task-snapshot` command and its task, artifact, and scope.
+- For normal results, record the key conclusion and exceptions; do not repeat the full directory listing or `task.md` tail.
+- For identity mismatches, failures, blocking conditions, or disputes, retain the decisive raw lines that support the judgment.
+
+## Successful Checks
+
+Every successful check records the command or an allowed public command name, target and scope, exit status or structured result, actual result, and uncovered parts. Do not write only “passed” or “tests passed”, and do not paste complete successful stdout by default.
+
+## Failures, Blocking Conditions, and Disputes
+
+Record a reproducible command or entry point, the exact file/line/object/version location, exit status, and the smallest decisive excerpt supporting the conclusion. If reproduction is unavailable, state the limitation explicitly rather than presenting incomplete evidence as success.
+
+## Preserved Identity and Security Boundaries
+
+- Preserve artifact SHA-256, semantic digest, review head, receipt, request-id, snapshot tree, and platform marker exactly.
+- The Issue continues to mirror the complete report; the report must not depend on logs accessible only on the local machine.
+- Manual validation keeps its stricter basename-only and sanitized-result rules; this shared rule does not expand public fields.
+- A `$ ` command line satisfies the structural gate but does not require complete successful output.
+
+## Evidence Pairing
+
+Pair every verification claim with a `$ ` command and a proportionate result summary. Include a decisive raw excerpt only for failure, blocking, or dispute conclusions. When a command contains sensitive arguments, use its allowed public name or a redacted command.

package/templates/.agents/rules/evidence-reporting.zh-CN.md

@@ -0,0 +1,28 @@
+# 生命周期报告证据记录规则
+
+本规则约束会持久化到任务目录或同步到 Issue 的生命周期报告。它统一报告的最低证据语义，不改变 artifact 身份、receipt、同步或恢复协议。
+
+## 状态核对
+
+- 记录 `task-snapshot` 命令及任务、产物和检查范围。
+- 正常结果记录关键结论和异常；不要重复粘贴完整目录清单或 `task.md` 尾部。
+- 身份不一致、失败、阻塞或争议时，保留能支持判断的决定性原文行。
+
+## 成功检查
+
+成功路径至少记录：命令或允许公开的命令名称、目标与检查范围、退出状态或结构化结果、实际结果、未覆盖部分。不能只写“通过”或“测试通过”，也不默认粘贴完整成功 stdout。
+
+## 失败、阻塞和争议
+
+记录可复现的命令或调用入口、准确的文件/行号/对象/版本位置、退出状态，以及决定结论的最小决定性摘录。无法复现时明确写出限制，不把不完整证据写成成功。
+
+## 不变的身份与安全边界
+
+- artifact SHA-256、semantic digest、review head、receipt、request-id、快照树和平台 marker 必须精确保留。
+- Issue 继续镜像报告全文；报告不得依赖只有本机可访问的日志。
+- 人工验证继续使用 basename-only、sanitized result 等更严格规则；共享规则不扩大可公开字段。
+- `$ ` 命令行标记满足结构门禁，但不要求附带完整成功输出。
+
+## 证据配对
+
+报告中的每个验证断言都应配一个 `$ ` 命令和相称结果摘要；只有失败、阻塞或争议结论才附决定性原文摘录。命令含敏感参数时使用允许公开的命令名或脱敏命令。

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

@@ -29,6 +29,6 @@ agent-infra-internal platform-pr sync {task-id} \
   --agent {standard-agent-token} --metadata --closing-issue
 ```
 
-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.
+Conflicting bindings do not change `task.md`. The shared core computes one `in:` target from task-bound diff/PR files and the repository mapping. A unique closing Issue is converged before the PR; other metadata comes from the linked Issue. Zero or multiple closing Issues update only the PR and return `degraded`; `in:` labels are never copied back from the Issue or removed from unrelated resources. Permission-bound items degrade independently, partial side effects return `blocked` with `IN_LABEL_SYNC_PARTIAL`, and an already-created PR is never rolled back.
 
 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

@@ -39,7 +39,7 @@ agent-infra-internal platform-pr sync {task-id} \
   --agent {standard-agent-token} --metadata --closing-issue
 ```
 
-core 从关联 Issue 复制 type / `in:` labels、assignee、具体 milestone，并确保 closing association。权限不足返回逐项 `skipped` 和顶层 `degraded`；不得反向修改 Issue。
+core 根据 task-bound diff/PR files 与仓库映射计算唯一 `in:` target；唯一 closing Issue 按 Issue→PR 顺序收敛，其他 metadata 从关联 Issue 复制。零或多个 closing Issue 只更新 PR 并返回 `degraded`；不得从 Issue 反向复制 `in:`，也不清除非 `in:` labels。权限不足逐项返回 `skipped`，部分副作用返回 `blocked` 与 `IN_LABEL_SYNC_PARTIAL`。
 
 ## 状态语义
 

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

@@ -25,6 +25,8 @@ agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token
 
 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.
 
+PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.
+
 `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:

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

@@ -71,6 +71,8 @@ agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token
 
 status labels 始终至多一个；关闭后不保留 status label。`in:` labels 只从项目允许映射与仓库实际 labels 交集产生。需求复选框以 task.md 原文为身份，歧义时 fail closed。
 
+PR event 的 `in:` 同步使用 `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`。PR files 是事件证据；唯一 closing Issue 按 Issue→PR 顺序写入并复读，零或多个 closing Issue 只写 PR 并返回 `degraded`。写入后副作用不明或复读未收敛必须返回 `blocked` 与 `IN_LABEL_SYNC_PARTIAL`。
+
 ## 补发
 
 complete-task 按 artifact catalog 时间线遍历本地已有产物：task 使用 `--kind task`，其余使用 `--kind artifact --artifact <file> --backfill`；最后用 `--kind summary --body-file <path>` 原地同步交付摘要。artifact backfill 在远端缺少 marker 时创建带“历史产物补发”提示的评论；已存在合法 marker 集合时保持原评论和分片不变并返回 `no-op`；marker 冲突仍失败。该判定由 core 完成，不由 Skill 扫描评论或拼标题。

package/templates/.agents/rules/label-milestone-setup.en.md

@@ -2,17 +2,17 @@
 
 Read this rule before initializing labels or milestones, or before changing milestone metadata during release work.
 
-## Entry points
+## Runtime intent entry points
 
-Use the shared scripts rather than composing provider commands in a skill:
+Use the internal runtime intents rather than composing platform commands in a skill:
 
 ```text
-bash .agents/skills/init-labels/scripts/init-labels.sh [--cleanup-stale-in]
-bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
+agent-infra-internal platform-metadata init-labels [--cleanup-stale-in]
+agent-infra-internal platform-metadata init-milestones [--history]
 ```
 
-`init-labels.sh` reads the repository's `labels.in` configuration, creates or updates the declared `in:` labels, and preserves unrelated labels. `--cleanup-stale-in` is destructive and may only be passed after explicit confirmation; it removes stale `in:` labels that are no longer declared.
+The `init-labels` runtime intent reads the repository's `labels.in` configuration, creates or updates the declared `in:` labels, and preserves unrelated labels. `--cleanup-stale-in` is destructive and may only be passed after explicit confirmation; it removes stale `in:` labels that are no longer declared.
 
-`init-milestones.sh` owns milestone inference and the provider-specific write path. Callers must pass the requested arguments through unchanged and must not rebuild milestone discovery, ordering, branch ancestry, or write logic.
+The `init-milestones` runtime intent owns milestone planning and result reporting. Callers must pass the requested arguments through unchanged and must not rebuild milestone discovery, ordering, or write logic.
 
-Both scripts return a stable status. A successful no-op is still success; a degraded result must be reported without claiming that remote metadata was changed. Failed or cancelled operations must not be reported as completed.
+Both intents return a stable status. A successful no-op is still success; a degraded result must be reported without claiming that remote metadata was changed. Failed or cancelled operations must not be reported as completed.

package/templates/.agents/rules/label-milestone-setup.zh-CN.md

@@ -2,17 +2,17 @@
 
 在初始化 label、milestone，或在发布工作中修改 milestone 元数据前，先阅读本规则。
 
-## 入口
+## Runtime intent 入口
 
-SKILL 应调用共享脚本，不得自行拼装 provider 命令：
+SKILL 应调用内部 runtime intent，不得自行拼装平台命令：
 
 ```text
-bash .agents/skills/init-labels/scripts/init-labels.sh [--cleanup-stale-in]
-bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
+agent-infra-internal platform-metadata init-labels [--cleanup-stale-in]
+agent-infra-internal platform-metadata init-milestones [--history]
 ```
 
-`init-labels.sh` 读取仓库的 `labels.in` 配置，创建或更新声明的 `in:` label，并保留无关 label。`--cleanup-stale-in` 具有破坏性，只有在得到明确确认后才能传入；它会删除不再声明的过期 `in:` label。
+`init-labels` runtime intent 读取仓库的 `labels.in` 配置，创建或更新声明的 `in:` label，并保留无关 label。`--cleanup-stale-in` 具有破坏性，只有在得到明确确认后才能传入；它会删除不再声明的过期 `in:` label。
 
-`init-milestones.sh` 负责 milestone 推断和 provider 写入路径。调用方应原样传递请求参数，不得重新实现 milestone 发现、排序、分支祖先判断或写入逻辑。
+`init-milestones` runtime intent 负责 milestone 规划和结果报告。调用方应原样传递请求参数，不得重新实现 milestone 发现、排序或写入逻辑。
 
-两个脚本都返回稳定状态。成功的 no-op 仍算成功；degraded 结果必须如实报告，不能声称远端元数据已变更。失败或取消的操作不得报告为已完成。
+两个 intent 都返回稳定状态。成功的 no-op 仍算成功；degraded 结果必须如实报告，不能声称远端元数据已变更。失败或取消的操作不得报告为已完成。

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -1,12 +1,19 @@
 # General Rule - Model-Driven Local Artifact Repair
 
-This rule applies only when `review-analysis`, `review-plan`, or `review-code` handles a finalizer failure for **the same controlled review artifact**. It does not apply to `task.md`, the ledger, receipts, source code, Git, platform resources, or lifecycle state.
+This rule applies when `analyze-task`, `plan-task`, or `code-task` handles **the same controlled local artifact** before its completed event, and when `review-analysis`, `review-plan`, or `review-code` handles a finalizer failure for **the same controlled review artifact**. It does not apply to `task.md`, the ledger, receipts, source code, Git, platform resources, or lifecycle state.
+
+## Pre-completion gate for analysis, plan, and code artifacts
+
+- `analyze-task`, `plan-task`, and `code-task` must call `task-artifact ... finalize-local` before publishing a completed event; pass only that call's `artifactSha256` and `semanticDigest` to the completed event.
+- `finalize-local` does not modify the artifact or task state, but it writes a one-shot local provenance intent in the repository workspace. After `failed`, the model may make one minimal edit in the same artifact only when `repairable=true` and the diagnostic explicitly describes one provably safe structural operation (the current shared engine operations are `replace-line` and `insert-section`), then rerun the same call completely; count each byte-changing edit, up to 8.
+- The first repairable failure's semantic digest is retained in that intent; a later `passed` result must match the baseline, and the completed event must verify and atomically transition the same intent to `consumed` before writing `task.md` under the task lock. A consumption failure must not write the task; the consumed intent is durable and retryable, so no failure-prone post-write deletion is attempted. Do not replace a failed baseline with a newly computed digest or publish a completed event without the finalizer.
+- After `failed`, no progress, or a repeated diagnostic or fingerprint, do not publish a completed event. After `passed`, do not rescan or manually write summary data.
 
 ## Authorization Boundary
 
 - The finalizer only reads facts, validates state, normalizes successful results, and performs atomic writes. It does not maintain a recoverable-error allowlist, infer repairability, or choose report content to delete.
 - The initial finalizer call is not counted as a repair attempt. Editing is allowed only after the mechanical safety gates pass and the model explicitly determines that the current problem can be solved by a minimal, explainable artifact change.
-- The model may edit only the one ordinary review artifact declared by the current review skill, and the file must be inside the current task directory. It must not edit `task.md`, the review disagreement ledger, receipts, source code, other reports, or remote resources.
+- The model may edit only the one ordinary local artifact declared by the current skill, and the file must be inside the current task directory. It must not edit `task.md`, the review disagreement ledger, receipts, source code, other reports, or remote resources.
 - `changed=false`, an error code, or a format shape is diagnostic evidence, not automatic authorization. The model must judge each case using the complete diagnostic, artifact content, and context.
 
 ## Non-bypassable Mechanical Safety Gates
@@ -33,6 +40,10 @@ If any condition fails, stop immediately without invoking a model edit. The mode
 
 The repair count exists only in the in-memory context of the current skill invocation. Do not write it to `task.md`, the ledger, or a public receipt. Do not create different normal budgets by error code, skill, or problem type.
 
+## Shared Structural Engine
+
+The report skeleton is created by `agent-infra-internal task-artifact {task-id} init --family {family} --artifact {artifact}`. The skeleton writes only identity, headings, and `artifact-section:{family}:{section-id}` markers; it does not represent semantic completion. The current skill must fill each slot with real content. When the finalizer returns one provably safe structural operation, use that result's SHA and semantic digest with `task-artifact {task-id} repair --family {family} --artifact {artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`. Repair executes only the one operation from the shared engine, does not write `task.md`, the ledger, receipts, Git, or platform resources, and must be followed by a complete rerun of the original finalizer.
+
 ## Completion Events and User Output
 
 - After the final complete finalizer result succeeds, publish the review completed event using that same result's provenance, ledger state, verdict, and counts. Generate cross-stage next-step commands only when `stageStatus.canAdvance=true` and the verdict is Approved; when `canAdvance=false`, still record the result and route to same-stage revision/review.

package/templates/.agents/rules/local-artifact-repair.zh-CN.md

@@ -1,12 +1,19 @@
 # 通用规则 - 模型驱动的本地产物修复
 
-本规则只适用于 `review-analysis`、`review-plan`、`review-code` 在 finalizer 失败后处理**同一个受控 review artifact** 的场景。它不适用于 task.md、账本、receipt、源码、Git、平台资源或生命周期状态。
+本规则适用于 `analyze-task`、`plan-task`、`code-task` 在 completed 事件前处理**同一个受控本地产物**，以及 `review-analysis`、`review-plan`、`review-code` 在 finalizer 失败后处理**同一个受控 review artifact** 的场景。它不适用于 task.md、账本、receipt、源码、Git、平台资源或生命周期状态。
+
+## 分析、方案和代码产物完成前门禁
+
+- `analyze-task`、`plan-task` 和 `code-task` 必须在发布 completed 事件前调用 `task-artifact ... finalize-local`；只有同一次返回的 `artifactSha256` 和 `semanticDigest` 才能传给 completed 事件。
+- `finalize-local` 不修改产物或任务状态，但会在仓库工作区写入一次性的本地 provenance intent。返回 `failed` 时，只有 `repairable=true` 且诊断明确为一个可证明安全的结构操作（当前共享引擎操作为 `replace-line` 或 `insert-section`），模型才可在同一产物中执行一次最小编辑，然后完整重跑同一调用；每次实际字节修改计一次，最多 8 次。
+- 首次可修复失败的 semantic digest 会保存在该 intent 中；后续 `passed` 必须匹配该基线，completed event 还必须在任务锁内验证并在写 task.md 前原子转换为 `consumed` 状态。消费失败时不得写任务；转换后的 intent 是可重试的 durable 记录，成功写入后不再执行可能失败的后置删除。不得用重新计算的新摘要替换失败基线，也不得绕过 finalizer 直接发布 completed event。
+- 返回 `failed`、无进展、诊断或指纹重复时不得发布 completed 事件；返回 `passed` 后也不得重新扫描或手工补写摘要。
 
 ## 授权边界
 
 - finalizer 只负责读取事实、校验状态、规范化成功结果和原子写入；它不维护可修复错误码白名单，不推断 repairability，也不自动选择要删除的报告内容。
 - 首次 finalizer 调用不计入修复次数。只有在机械安全门通过后，模型明确判断当前问题能通过最小、可解释的 artifact 修改解决时，才允许编辑。
-- 模型只能修改当前 review skill 声明的一个普通 review artifact，且该文件必须位于当前 task 目录。不得修改 task.md、审查分歧账本、receipt、源码、其他报告或远端资源。
+- 模型只能修改当前 skill 声明的一个普通本地产物，且该文件必须位于当前 task 目录。不得修改 task.md、审查分歧账本、receipt、源码、其他报告或远端资源。
 - `changed=false`、错误码或某个格式形状只是诊断事实，不是自动批准。模型必须结合完整诊断、artifact 内容和上下文逐例判断。
 
 ## 不可绕过的机械安全门
@@ -33,6 +40,10 @@
 
 修复次数只存在于当前 skill invocation 的内存上下文，不写入 task.md、ledger 或公共 receipt。不得按错误码、技能或问题类型设置不同的正常预算。
 
+## 共享结构引擎
+
+报告骨架由 `agent-infra-internal task-artifact {task-id} init --family {family} --artifact {artifact}` 创建。骨架只写身份、标题和 `artifact-section:{family}:{section-id}` marker，不代表语义完成；槽位必须由当前 skill 填入真实内容。finalizer 返回单一可证明结构操作时，使用同一返回值的 SHA 和 semantic digest 调用 `task-artifact {task-id} repair --family {family} --artifact {artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`。repair 只执行共享引擎给出的一个结构操作，不写 task.md、ledger、receipt、Git 或平台资源，之后必须完整重跑原 finalizer。
+
 ## 完成事件与用户输出
 
 - 最终一次完整 finalizer 成功后，必须使用同一次返回的 provenance、账本状态、verdict 和计数发布 review completed 事件；`stageStatus.canAdvance=true` 且结论为 Approved 时才可生成跨阶段 next-step 命令，`canAdvance=false` 时仍须登记结果并路由到同阶段修订/复审。

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

@@ -2,7 +2,7 @@
 
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
+The model writes the semantic reviewer summary. Typed core owns the task-intent digest, complete three-dot diff, canonical `pr-change-report.json` sidecar, report rendering, authoritative PR-head wrapping, paginated comment lookup, and reconciliation.
 
 ## Three-Layer Isolation
 
@@ -15,11 +15,17 @@ The three never cross: a regular PR comment does not carry the full process copy
 ```bash
 agent-infra-internal platform-pr summary-context {task-id}
 
+agent-infra-internal platform-pr change-report {task-id} \
+  --agent {standard-agent-token} --mechanical-file {mechanical-report-file} \
+  --precheck-file {precheck-candidate-file}
+
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --result {primary-result}
 ```
 
-Use only canonical inputs returned by the context command. Write the plain body without marker or SHA. The core owns `<!-- sync-pr:{task-id}:summary -->`, current `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Summary failure never rolls back a PR or commit.
+Use only canonical inputs returned by the context command. The precheck must contain file evidence for six fixed checks; `formalReview` is always false and `needs-review` routes to `review-code`. Write the plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder, without a report heading/JSON, marker, or SHA. The core validates the task-intent digest, bound PR identity, complete patch SHA, and mechanical totals before rendering the report, then owns `<!-- sync-pr:{task-id}:summary -->`, authoritative `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Missing, stale, invalid, or bypassed report input never publishes; summary failure never rolls back a PR or commit.
 
 The canonical comment envelope produced by the core is:
 
@@ -34,7 +40,7 @@ The canonical comment envelope produced by the core is:
 ### 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. 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.
+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. The caller supplies the placeholder; the core renderer supplies the canonical `### PR Code Changes` section.
 
 ```bash
 agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \

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

@@ -2,7 +2,7 @@
 
 > `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
+PR 摘要的语义聚合由模型完成；任务意图 digest、完整三点 diff、canonical `pr-change-report.json` sidecar、报告渲染、marker、权威 PR head、分页评论查找和 create/update/no-op 由 typed core 负责。
 
 ## 三层隔离
 
@@ -24,7 +24,8 @@ agent-infra-internal platform-pr summary-context {task-id}
 - 测试结果
 - 审查历程与当前结论
 - 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
-- `### PR 代码增减`：基于 `platform-pr inspect` 的权威 base/head 和完整 `git diff --find-renames --numstat base...head`，按运行时代码、测试、Skill/规则、模板、文档及其他分类核算，并说明 rename、机械镜像与疑似不必要变化
+- 变更摘要、实现范围、测试结果、审查历程和人工校验三态
+- 一个 `<!-- canonical-pr-change-report -->` 占位符；`### PR 代码增减` 由 core renderer 基于权威 diff 生成，调用方不自行写标题或统计
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
@@ -41,16 +42,28 @@ core 最终包装出的 canonical 评论结构为：
 ### PR 代码增减
 ```
 
+先用机械脚本和模型预检生成输入，再写入任务目录固定 sidecar：
+
+```bash
+agent-infra-internal platform-pr change-report {task-id} \
+  --agent {standard-agent-token} --mechanical-file {mechanical-report-file} \
+  --precheck-file {precheck-candidate-file}
+```
+
+precheck 必须覆盖六项固定检查并提供文件证据；`formalReview` 固定为 `false`，`needs-review` 路由到 `review-code`。sidecar 是当前 head 的可丢弃派生缓存，不是 lifecycle artifact 或 Issue artifact。
+
 ## 发布
 
 把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：
 
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --result {primary-result}
 ```
 
-core 会包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和当前 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。
+正文必须恰好包含一次 `<!-- canonical-pr-change-report -->`，不得自行拼接报告标题/JSON、marker 或 last-commit。core 会重新校验任务意图 digest、绑定 PR identity、完整 patch SHA 和机械统计，由 renderer 生成报告段，再包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和权威 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 或报告失配则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。
 
 ## 结果回传
 

package/templates/.agents/rules/security-alerts.en.md

@@ -2,19 +2,19 @@
 
 Read this rule before importing or dismissing dependency or code-scanning alerts.
 
-## Shared entry point
+## Shared runtime intent
 
-All callers use the shared security script and parse its single JSON result:
+All callers use the runtime security intent and parse its single JSON result:
 
 ```text
-bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
-bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
-bash .agents/scripts/security-alerts.sh read-codescan --number {number}
-bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+agent-infra-internal platform-security read --kind dependabot --number {number}
+agent-infra-internal platform-security dismiss --kind dependabot --number {number} --reason {reason} --comment-file {file}
+agent-infra-internal platform-security read --kind code-scanning --number {number}
+agent-infra-internal platform-security dismiss --kind code-scanning --number {number} --reason {reason} --comment-file {file}
 ```
 
 The result contains `status`, `operation`, and either `data` or `error.code` plus `error.message`. The status is one of `applied`, `no-op`, `degraded`, or `failed`. Diagnostics belong on stderr; stdout must contain exactly one JSON object.
 
-Read the current alert before any dismiss operation. A dismiss reason must use the provider API reason value, and the generated task or Issue comment must be passed through `--comment-file`.
+Read the current alert before any dismiss operation. The runtime intent validates the structured reason, and the generated task or Issue comment must be passed through `--comment-file`.
 
-Do not invoke a provider CLI directly from a SKILL. A degraded or failed result must be reported accurately, and cancelled or failed operations must not be recorded as successful.
+Do not execute platform commands or implement the platform state machine directly from a SKILL. A degraded or failed result must be reported accurately, and cancelled or failed operations must not be recorded as successful.

package/templates/.agents/rules/security-alerts.zh-CN.md

@@ -2,19 +2,19 @@
 
 在导入或关闭依赖告警、代码扫描告警前，先阅读本规则。
 
-## 共享入口
+## 共享 runtime intent 入口
 
-所有调用方都使用共享安全脚本，并解析其单个 JSON 结果：
+所有调用方都使用 runtime security intent，并解析其单个 JSON 结果：
 
 ```text
-bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
-bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
-bash .agents/scripts/security-alerts.sh read-codescan --number {number}
-bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+agent-infra-internal platform-security read --kind dependabot --number {number}
+agent-infra-internal platform-security dismiss --kind dependabot --number {number} --reason {reason} --comment-file {file}
+agent-infra-internal platform-security read --kind code-scanning --number {number}
+agent-infra-internal platform-security dismiss --kind code-scanning --number {number} --reason {reason} --comment-file {file}
 ```
 
 结果包含 `status`、`operation`，以及 `data` 或 `error.code` 与 `error.message`。`status` 只能是 `applied`、`no-op`、`degraded` 或 `failed`。诊断信息写入 stderr；stdout 必须只包含一个 JSON 对象。
 
-任何关闭操作前都必须先读取当前告警。关闭原因必须使用 provider API 的 reason 值，生成的任务或 Issue 评论必须通过 `--comment-file` 传入。
+任何关闭操作前都必须先读取当前告警。关闭原因由 runtime intent 作为结构化输入校验，生成的任务或 Issue 评论必须通过 `--comment-file` 传入。
 
-SKILL 不得直接调用 provider CLI。degraded 或 failed 结果必须如实报告，取消或失败的操作不得记录为成功。
+SKILL 不得直接执行平台命令或实现平台状态机。degraded 或 failed 结果必须如实报告，取消或失败的操作不得记录为成功。

package/templates/.agents/rules/task-short-id.en.md

@@ -123,7 +123,4 @@ repair hint.
 ## Cross-TUI use
 
 Bare numeric `N` is safe in every shell and TUI without quoting:
-`ai sandbox exec 11 'npm test'`, `/review-analysis 11`.
-
-Starting with the next major version, migrate the old `#NN` form to `NN`;
-even a quoted value delivered intact to the CLI is rejected.
+`ai sandbox exec 11 'npm test'`, `/review-analysis --task 11`.

package/templates/.agents/rules/task-short-id.zh-CN.md

@@ -97,6 +97,4 @@ fi
 ## 跨 TUI 使用
 
 裸数字 `N` 在所有 shell 与 TUI 中都安全无需引号：
-`ai sandbox exec 11 'npm test'`、`/review-analysis 11`。
-
-从下一个大版本起，原 `#NN` 写法必须迁移为 `NN`；即使引用后完整传入 CLI 也会被拒绝。
+`ai sandbox exec 11 'npm test'`、`/review-analysis --task 11`。