@fitlab-ai/agent-infra 0.9.11 → 0.9.12

package/lib/task/verification-engine.ts

@@ -7,6 +7,8 @@ import { fileURLToPath } from "node:url";
 
 import {
   extractReviewBaseline,
+  extractReviewTargetHead,
+  extractReviewedHead,
   extractReviewDiffBase,
   extractReviewDiffFingerprint,
   extractReviewedSnapshotTree,
@@ -30,6 +32,8 @@ import { inspectDecisionDetailDuplicates } from "./decision-details.ts";
 import { loadVerificationConfig } from "./verification-config.ts";
 import { snapshotReview } from "../git/review-snapshot.ts";
 import { OrchestrationStateError, readRun } from "./orchestration.ts";
+import { resolveDeliveryTarget } from "./delivery-target.ts";
+import { readPrDeliveryFact } from "./pr-delivery-fact.ts";
 
 const TASK_ENUMS = {
   type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -195,15 +199,14 @@ function validateCleanCompletionEvidence(run: any): string | null {
     || !shaPattern.test(evidence.headTree)
     || !shaPattern.test(evidence.worktreeTree)
     || !shaPattern.test(evidence.lastReviewedCommit)
-    || !Number.isInteger(evidence.prNumber)
-    || evidence.prNumber <= 0
-    || !shaPattern.test(evidence.prHead)
+    || !(evidence.prNumber === null || (Number.isInteger(evidence.prNumber) && evidence.prNumber > 0))
+    || !(evidence.prHead === null || shaPattern.test(evidence.prHead))
   ) {
     return 'Clean completion evidence has an invalid structure';
   }
   if (
     evidence.head !== evidence.lastReviewedCommit
-    || evidence.head !== evidence.prHead
+    || (evidence.prHead !== null && evidence.head !== evidence.prHead)
     || evidence.headTree !== evidence.worktreeTree
   ) {
     return 'Clean completion evidence does not bind matching commit and tree identities';
@@ -276,12 +279,8 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
   if (run.completionEvidence != null) {
     const evidenceError = validateCleanCompletionEvidence(run);
     if (evidenceError) return failResult('orchestration-evidence', evidenceError);
-  } else if (run.status === 'completed' && (
-      run.receipts.length === 0
-      || run.receipts.at(-1)?.stage !== 'commit'
-      || run.receipts.at(-1)?.status !== 'consumed'
-    )) {
-      return failResult('orchestration-evidence', 'Completed run requires a final consumed commit receipt');
+  } else if (run.status === 'completed') {
+    return failResult('orchestration-evidence', 'Completed run requires reviewed-head-clean completion evidence');
   }
   if (run.pendingDelegation && !['prepared', 'activated', 'stage-completed'].includes(run.pendingDelegation.status)) {
     return failResult('orchestration-evidence', `Pending receipt has unsafe status '${run.pendingDelegation.status}'`);
@@ -500,18 +499,18 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }: any): any {
     return failResult('required-pr-delivery', 'Project configuration is invalid');
   }
   const flow = projectConfig.prFlow;
-  const status = String(task.metadata.pr_status || 'pending');
-  const prNumber = parsePrNumber(task.metadata.pr_number);
+  const factRead = readPrDeliveryFact(task.metadata);
+  if (factRead.status === 'invalid') return failResult('required-pr-delivery', factRead.error.message);
+  const fact = factRead.status === 'valid' ? factRead.fact : null;
+  const status = fact?.state || 'unbound';
+  const prNumber = fact?.state === 'bound' ? fact.identity.number : null;
   if (flow === 'disabled') return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
-  if (flow === 'required' && (status !== 'created' || prNumber === null)) {
+  if (flow === 'required' && (status !== 'bound' || prNumber === null)) {
     return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
   }
-  if (flow !== 'required' && status === 'pending') {
+  if (flow !== 'required' && status === 'unbound') {
     return failResult('required-pr-delivery', 'Pull request delivery is pending; create a PR or explicitly skip it');
   }
-  if (status === 'created' && prNumber === null) {
-    return failResult('required-pr-delivery', 'Task claims a created pull request without a valid pr_number');
-  }
   if (flow === 'required') {
     if (mode === 'gate') {
       return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
@@ -527,6 +526,7 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }: any): any {
     const pullRequest = inspected.pullRequest;
     const repository = inspected.platform.repository?.toLowerCase() || '';
     const taskBranch = String(task.metadata.branch || '').trim();
+    const deliveryBaseRef = String(task.metadata.delivery_base_ref || projectConfig.delivery?.baseRef || '').trim();
     if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
       return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
     }
@@ -535,6 +535,7 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }: any): any {
       || pullRequest.repository.toLowerCase() !== repository
       || pullRequest.base.repository.toLowerCase() !== repository
       || (taskBranch && pullRequest.head.ref !== taskBranch)
+      || (deliveryBaseRef && pullRequest.base.ref !== deliveryBaseRef)
     ) {
       return failResult('required-pr-delivery', 'Bound pull request identity does not match the task');
     }
@@ -1110,9 +1111,12 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
 
   const task = loadTask(taskDir);
   if (!task.ok) return failResult("post-review-commit", task.message);
+  const factRead = readPrDeliveryFact(task.metadata);
+  if (factRead.status === 'invalid') return failResult("post-review-commit", factRead.error.message);
+  const fact = factRead.status === 'valid' ? factRead.fact : null;
   const lastReviewedCommit = task.ok ? (task.metadata.last_reviewed_commit || "").trim() : "";
   const globs = resolvePostReviewGlobs(config, loadPostReviewConfig(repoRoot));
-  const hasPullRequest = Number(task.metadata.pr_number) > 0;
+  const hasPullRequest = fact?.state === 'bound';
   let inspected: ReturnType<typeof inspectPlatformPullRequest> | null = null;
   if (hasPullRequest) {
     inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
@@ -1302,7 +1306,8 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
 
   const content = fs.readFileSync(resolvedArtifact.path, "utf8");
   const verdict = parseReviewVerdict(content);
-  const reviewBaseline = extractReviewBaseline(content);
+  const reviewTargetHead = extractReviewTargetHead(content);
+  const reviewReviewedHead = extractReviewedHead(content);
   const reviewDiffBase = extractReviewDiffBase(content);
   const reviewedFingerprint = extractReviewDiffFingerprint(content);
   const reviewedTree = extractReviewedSnapshotTree(content);
@@ -1311,30 +1316,42 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
     return failResult("review-fact", `Unsupported review verdict '${verdict}'`);
   }
 
+  const deliveryRemote = String(task.metadata.delivery_remote || "").trim();
+  const deliveryBaseRef = String(task.metadata.delivery_base_ref || "").trim();
+  if (!deliveryRemote || !deliveryBaseRef) {
+    return failResult("review-fact", "Task delivery target is not bound; re-run task branch preparation before review-code");
+  }
+  if (!reviewTargetHead || !reviewReviewedHead || !reviewDiffBase) {
+    return failResult("review-fact", "Review fact must record target head, reviewed head, and diff base");
+  }
+
   let gitRoot;
   let head;
   let baseline;
+  let targetHead;
   let diffBase;
   try {
     gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
     head = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-    baseline = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewBaseline}^{commit}`], { encoding: "utf8" }).trim();
-    diffBase = execFileSync(
-      "git",
-      ["-C", gitRoot, "rev-parse", `${reviewDiffBase || reviewBaseline}^{commit}`],
-      { encoding: "utf8" }
-    ).trim();
+    const target = resolveDeliveryTarget(gitRoot, { remote: deliveryRemote, baseRef: deliveryBaseRef });
+    if (!target.ok) throw new Error(target.message);
+    const reviewedRef = reviewReviewedHead;
+    baseline = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewedRef}^{commit}`], { encoding: "utf8" }).trim();
+    targetHead = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewTargetHead}^{commit}`], { encoding: "utf8" }).trim();
+    const computed = execFileSync("git", ["-C", gitRoot, "merge-base", baseline, targetHead], { encoding: "utf8" }).trim();
+    diffBase = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewDiffBase}^{commit}`], { encoding: "utf8" }).trim();
+    if (diffBase !== computed) throw new Error('saved review diff base does not match merge-base(reviewed head, target head)');
   } catch {
     return blockedResult(
       "review-fact",
-      `Unable to resolve review baseline '${reviewBaseline}' in the task repository; re-run review-code`
+      `Unable to resolve saved review commits in the task repository; re-run review-code`
     );
   }
 
   if (baseline !== head) {
     return failResult(
       "review-fact",
-      `Review baseline ${baseline.slice(0, 8)} does not match current HEAD ${head.slice(0, 8)}; re-run review-code`
+      `Reviewed head ${baseline.slice(0, 8)} does not match current HEAD ${head.slice(0, 8)}; re-run review-code`
     );
   }
 
@@ -1378,7 +1395,7 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
     if (cleanSnapshot && lastReviewedCommit !== baseline) {
       return failResult(
         "review-fact",
-        `Approved clean review must set task last_reviewed_commit to baseline ${baseline.slice(0, 8)}`
+        `Approved clean review must set task last_reviewed_commit to reviewed head ${baseline.slice(0, 8)}`
       );
     }
     if (!cleanSnapshot && lastReviewedCommit) {

package/lib/task/verification-review.ts

@@ -1,5 +1,7 @@
 export {
   extractReviewBaseline,
+  extractReviewTargetHead,
+  extractReviewedHead,
   extractReviewDiffBase,
   extractReviewDiffFingerprint,
   extractReviewedSnapshotTree,

package/lib/update.ts

@@ -23,6 +23,7 @@ type UpdateConfig = {
   prFlow?: 'required' | 'disabled';
   sandbox?: Record<string, unknown>;
   task?: { shortIdLength: number };
+  delivery?: { remote?: string; baseRef?: string };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
   agentClients?: unknown;
@@ -33,6 +34,7 @@ type Defaults = {
   platform: { type: string };
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
+  delivery: { remote: string; baseRef: string };
   labels: Record<string, unknown>;
   files: FileRegistry;
 };
@@ -83,10 +85,12 @@ async function cmdSync(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
+  const deliveryAdded = !config.delivery;
   if (platformAdded) config.platform = structuredClone(defaults.platform);
   if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
   if (taskAdded) config.task = structuredClone(defaults.task);
   if (labelsAdded) config.labels = structuredClone(defaults.labels);
+  if (deliveryAdded) config.delivery = structuredClone(defaults.delivery);
 
   const workflowPlan = planAgentClientReconciliation({
     config: config as unknown as Record<string, unknown>,
@@ -150,6 +154,9 @@ async function cmdSync(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
+      if (deliveryAdded) {
+        info(`Default delivery target added to ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -165,6 +172,9 @@ async function cmdSync(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && deliveryAdded) {
+      info(`Default delivery target added to ${CONFIG_PATH}.`);
+    }
     ok(`Updated ${CONFIG_PATH}`);
   }
 

package/package.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,8 +1,10 @@
-# Issue 同步
+# Issue 同步规则
+
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 ## Marker 注册表
 
-以下隐藏标记是 Issue 同步的唯一权威注册表：
+以下 key 及格式是 Issue 评论身份的兼容契约；调用方只传 key/资源，不自行拼 marker。
 
 | Key | Marker |
 |---|---|
@@ -12,8 +14,63 @@
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
-Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+`prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
+
+`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 编号并只读注册的 Issue marker，不新增 PR 来源。
+
+## 平台 intent
+
+平台 upstream、认证、capability、分页、marker 查找、幂等 create/update、分片、重试与错误分类由 typed platform core 统一处理：
+
+```bash
+agent-infra-internal platform-context resolve [--cwd <path>]
+agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+agent-infra-internal platform-comment owner <task-ref>
+agent-infra-internal platform-comment sync <task-ref> \
+  --kind task|artifact|summary|cancel --agent {standard-agent-token} \
+  [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
+```
+
+- `applied|no-op|degraded` → exit 0；`failed` → exit 1；`blocked` → exit 2。
+- task 评论保持 `<details>` frontmatter 可逆格式；artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- 相同 intent 重放必须收敛为 `no-op`；重复 marker 返回 `COMMENT_MARKER_CONFLICT` 且不写入。
+- 外部贡献者锁定统一使用 `platform-comment owner`；不同作者且无 triage 时返回 `COMMENT_OWNER_CONFLICT`。
+
+## 降级与告警
+
+平台结果不直接写 task.md。调用方在有关联任务时把关键失败映射为 workflow warning：
+
+- capability 不足：`IMPORTANT / PERMISSION_DEGRADED`
+- 评论同步永久失败：`ACTION_REQUIRED / COMMENT_SYNC_FAILED`
+- 网络重试耗尽：`ACTION_REQUIRED / NETWORK_RETRY_EXHAUSTED`
+
+使用 `agent-infra-internal task-warning {task-id} add ...` 登记；不得手写 warning 表。
+
+```bash
+agent-infra-internal task-warning {task-id} add \
+  --step issue-sync --severity {severity} --code {code} \
+  --target {target} --message {message} --action {action}
+```
+
+## Issue 元数据 intent
+
+所有 Issue 元数据写入统一使用：
+
+```bash
+agent-infra-internal platform-issue inspect {task-id}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
+```
+
+`sync` 支持 status/in labels、assignee、milestone、Issue Type、pinned fields、需求复选框与 Issue state。省略 flag 表示 preserve，`none` 表示显式清空。适配层统一处理集合差集、动态 schema、权限降级、dry-run、重试、错误分类与幂等重放；SKILL 不得拼装平台 CLI、GraphQL 或权限分支。
+
+- `planned|applied|no-op|degraded` → exit 0
+- `failed` → exit 1
+- `blocked` → exit 2
+
+status labels 始终至多一个；关闭后不保留 status label。`in:` labels 只从项目允许映射与仓库实际 labels 交集产生。需求复选框以 task.md 原文为身份，歧义时 fail closed。
 
-当前代码平台未提供 Issue 适配器；`platform-issue` 返回结构化 no-op/degraded operations。
+## 补发
 
-自定义平台会跳过 Issue 元数据、标签、里程碑、负责人和评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和平台适配器。请继续正常写入本地任务产物。
+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

@@ -1,5 +1,18 @@
 # Label and Milestone Setup
 
-This code platform does not provide built-in label or milestone setup.
+Read this rule before initializing labels or milestones, or before changing milestone metadata during release work.
 
-Initialization of remote labels and milestones is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Local task workflow files remain usable without remote metadata setup.
+## Entry points
+
+Use the shared scripts rather than composing provider 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"
+```
+
+`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.
+
+`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.
+
+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.

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

@@ -1,5 +1,18 @@
 # Label 和 Milestone 初始化
 
-当前代码平台未内置标签或里程碑初始化支持。
+在初始化 label、milestone，或在发布工作中修改 milestone 元数据前，先阅读本规则。
 
-自定义平台会跳过远端标签和里程碑初始化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。即使没有远端元数据初始化，本地任务工作流文件仍可使用。
+## 入口
+
+SKILL 应调用共享脚本，不得自行拼装 provider 命令：
+
+```text
+bash .agents/skills/init-labels/scripts/init-labels.sh [--cleanup-stale-in]
+bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
+```
+
+`init-labels.sh` 读取仓库的 `labels.in` 配置，创建或更新声明的 `in:` label，并保留无关 label。`--cleanup-stale-in` 具有破坏性，只有在得到明确确认后才能传入；它会删除不再声明的过期 `in:` label。
+
+`init-milestones.sh` 负责 milestone 推断和 provider 写入路径。调用方应原样传递请求参数，不得重新实现 milestone 发现、排序、分支祖先判断或写入逻辑。
+
+两个脚本都返回稳定状态。成功的 no-op 仍算成功；degraded 结果必须如实报告，不能声称远端元数据已变更。失败或取消的操作不得报告为已完成。

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

@@ -0,0 +1,46 @@
+# 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.
+
+## 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.
+- `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
+
+Before every model edit, confirm that:
+
+1. the finalizer returned a failure and no artifact operation was committed;
+2. the task, stage, artifact, review round, identity, and provenance still match;
+3. the target is an ordinary file inside the current task directory, with no concurrency conflict, permission error, I/O uncertainty, or target replacement;
+4. the change does not alter human-decision semantics, decision-detail or ledger identity, and does not involve task state, receipts, Git, platform, or any other external side effect. A known and verifiable pending human decision may remain when the model proves the edit is unrelated to that decision.
+
+If any condition fails, stop immediately without invoking a model edit. The model cannot bypass these gates.
+
+## Dynamic Convergence Loop
+
+1. Run the initial finalizer with the fixed task, stage, artifact, and orchestrated intent.
+2. On success, use that complete result for the existing completion gates; do not rescan the ledger or write summary fields manually.
+3. On failure with the safety gates passed, let the model read the structured diagnostic, current artifact, and required context, then decide whether to repair or stop. It must explain the scope and reason for the proposed change.
+4. If the model continues, perform one minimal edit to the artifact. Increment `repairAttempts` only when the file bytes actually change, then rerun the same finalizer intent completely.
+5. Re-run every safety check after each retry. A new, independent problem still limited to the same artifact may be offered to the model for another decision; the previous repairability decision must not be reused automatically.
+6. Stop immediately when the model cannot establish safety or identifies an environment, permission, concurrency, identity, provenance, unknown-state, uncertain human-decision semantics/details, or other non-local problem. A known human decision is not itself a stop condition.
+7. Stop when the diagnostic or artifact fingerprint repeats, no byte-level progress occurs, or the model cannot propose a verifiable minimal change.
+8. Allow at most 8 actual artifact edits per skill invocation as an emergency circuit breaker. This cap only prevents infinite loops and resource exhaustion; it is not a normal business stop condition and does not mean that at most eight problems may be repaired. Preserve the final structured diagnostic when the cap is reached.
+
+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.
+
+## 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.
+- On failure, model stop, lack of progress, repeated diagnostics, or the emergency cap, do not publish a completed event, advance the lifecycle, generate cross-stage commands, or fabricate an approval.
+- Stopping advancement does not discard review results. User output must show the artifact path, the last safely readable summary/findings, actual `repairAttempts`, the last structured diagnostic, and the stop reason.
+- If the summary cannot be safely parsed, show only the artifact path and the raw structured diagnostic; do not infer counts or add a conclusion, and state that lifecycle advancement stopped while the artifact remains available.
+- A stop path may only suggest rerunning the current review skill or handling the issue manually. It must not invoke cross-stage helpers such as `code-task` or `complete-task`.
+
+## Lifecycle Isolation
+
+`complete-task`, alert closing, task restoration, and other task-lifecycle/task-finalization entry points involve task state, receipts, remote results, or archival side effects and do not consume this rule. They retain their own hard-stop, same-intent retry, and unknown-state semantics.