@fitlab-ai/agent-infra 0.11.8 → 0.11.10

package/templates/.agents/rules/commit-and-pr.zh-CN.md

@@ -7,12 +7,12 @@
 - `scope`：模块名（可省略）
 - `subject` 使用英文祈使语气，保持简洁
 
-## 禁止自动提交
+## 提交执行边界
 
-- 绝对不要自动执行 `git commit` 或 `git add`
-- 仅在用户明确发起提交命令时才进入提交流程
-- 唯一例外：用户显式启动的 active `run-task` 可签发一次性 commit authorization；它等价于本轮提交授权，但不得放宽暂存、敏感文件、版权、测试、审查快照、HEAD/tree 或 push 门禁。
-- 完成代码修改后，提醒用户使用对应 TUI 的提交命令
+- 不直接执行 `git add` 或 `git commit`；所有自动提交都必须通过 `agent-infra-internal git-workflow commit` 共享 core，并遵守对应技能提供的 paths、HEAD/tree 和交付模式约束。
+- 提交由当前工作流定义。`code-task` 完成实现必须在测试和实现报告 preflight 通过后，通过共享 core 创建一个本地 checkpoint；该要求适用于直接调用和 `run-task` 编排，不需要额外的提交授权或用户确认。
+- `code-task` 的本地 checkpoint 不推送远端。其他技能只有在其流程明确要求时才可调用共享 core；独立 `commit` 技能仍须由用户显式调用，并遵循其 push delivery 流程。
+- 工作流没有要求提交时，不要自行创建提交；需要用户执行独立提交时，再提示对应 TUI 命令。
 
 ## PR 提交规则
 

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

@@ -18,6 +18,6 @@ Any analysis, plan, implementation, or review that decides whether a human decis
 
 ## Invalidation and review
 
-When a lifecycle artifact is replaced, start from the old artifact and follow verified input edges in the task receipts to find and invalidate every downstream consumer. Exclude the new artifact from the old graph. If any relation is missing, identity or SHA-256 does not match, or the graph cannot be verified, use the existing static downstream invalidation scope.
+The current artifact is the latest successfully completed report with a matching completion fact, current file digest, and paired completion log. A filename round or modification time alone does not prove completion. Downstream reports must continue to verify lifecycle receipts, and review-code must verify the reviewed snapshot identity. Resume an open started round in place; pending rework intent determines the return stage. Existing “Artifact Invalidation” sections are historical text only and do not affect current reports, authorization, routing, or recovery. Editing them does not change the task-input digest.
 
 When a qualification audit is present, missing or unknown references and digest mismatches block finalization. Audits in the old format with an upstream-relations table must be regenerated in the current format. Formatting-only changes must not change semantic digests; changes to meaning, provenance, status, or candidates require a new audit.

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

@@ -18,6 +18,6 @@
 
 ## 失效与审查
 
-替换某个阶段产物时，系统从被替换的旧 artifact 出发，沿任务收据中验证过的输入边计算所有下游消费者，并使旧消费者失效；新产物不进入旧图。若任一关系缺失、身份不匹配、SHA-256 不匹配或图无法验证，则使用既有静态下游失效范围。
+当前报告由最近一次具备匹配 completion fact、当前文件摘要和配对完成日志的成功完成记录确定。文件轮次和修改时间不能单独证明完成。下游报告必须继续验证生命周期收据，review-code 必须验证被审快照身份。未闭合的 started 轮次从原轮次恢复；pending 返工意图决定返回阶段。存量“产物失效记录”仅为历史文本，不参与当前报告、授权、路由或恢复；修改它不改变任务输入摘要。
 
 资格审计存在时，缺失、未知引用或 digest 不匹配都必须拒绝收尾。旧版包含“上游关系”表的资格审计不再读取，应按当前格式重新生成。排版变化不应改变语义 digest；语义、来源、状态或候选变化必须触发重新审计。

package/templates/.agents/rules/next-step-output.en.md

@@ -33,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 
 - Pass the next skill name for the already-selected scenario. Include `--task-ref` only when that command needs a task reference.
 - Include `--version` only for a versioned release command. It must start with a digit and satisfy `semver.valid(raw) === raw`; never pass an action, complete command, shell fragment, whitespace, or a `v` / `V` / `=` prefix.
-- The helper lists only built-in clients enabled in `.agents/.airc.json` `agentClients`, followed by valid `customTUIs` in configuration order.
+- The helper lists enabled built-in clients, followed by selected sandbox custom tools with a valid `invoke` field in `sandbox.tools.ids` order.
 - Insert non-empty stdout verbatim at `{next-step-commands}` below the current "Next steps" heading. When stdout is empty, omit the client command block while still rendering reminders, warnings, and `Completed at`.
 - If the helper writes stderr or exits non-zero, use the current skill's error path and stop; never fall back to a hard-coded client table.
 - A complex skill selects one scenario first and invokes the helper once for that scenario; it must not pre-render every branch.

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -33,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 
 - 静态传入当前已选场景的下一 skill 名；只有命令需要任务引用时才传 `--task-ref`。
 - 只有版本化发布命令需要版本时才传 `--version`；值必须是以数字开头且 `semver.valid(raw) === raw` 的规范 SemVer。不得传 action、完整命令、shell 片段、空白或 `v` / `V` / `=` 前缀。
-- helper 只展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并在其后按配置顺序追加合法的 `customTUIs`。
+- helper 展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并按 `sandbox.tools.ids` 顺序追加具有有效 `invoke` 的已选自定义沙箱工具。
 - 将非空 stdout 原样放入当前“下一步”标题后的 `{next-step-commands}`；stdout 为空时省略整个客户端命令块，但继续输出提醒、告警和 `Completed at`。
 - helper 写 stderr 或返回非零时，按当前 skill 的错误路径报告并停止；禁止回退到硬编码客户端表。
 - 复杂 skill 先选定唯一场景，再只为该场景调用一次 helper，不得提前渲染所有分支。

package/templates/.agents/scripts/lib/agent-infra-package.js

@@ -1,7 +1,6 @@
 import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
 const PACKAGE_NAME = "@fitlab-ai/agent-infra";
 const COMMAND_NAMES = ["ai", "agent-infra"];
@@ -82,7 +81,6 @@ function rootsForCommand(commandPath, platform) {
 function resolveAgentInfraPackage(options = {}) {
   const env = options.env || process.env;
   const platform = options.platform || process.platform;
-  const startPath = options.startPath || fileURLToPath(import.meta.url);
   const attempts = [];
   const tryRoot = (candidate, source) => {
     const inspected = inspectPackageRoot(candidate, source);
@@ -95,11 +93,6 @@ function resolveAgentInfraPackage(options = {}) {
     if (explicit) return { ...explicit, attempts };
   }
 
-  for (const candidate of packageRootsAbove(startPath)) {
-    const self = tryRoot(candidate, "current installation");
-    if (self) return { ...self, attempts };
-  }
-
   for (const command of COMMAND_NAMES) {
     const commandPaths = lookupCommand(command, platform);
     if (commandPaths.length === 0) {

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

@@ -28,9 +28,9 @@ Before generating the implementation report, read `.agents/rules/evidence-report
 - Before generating task or lifecycle Markdown that will be synchronized to an Issue, read `.agents/rules/sync-content-generation.md` and apply its producer-side constraints; the sync path does not parse or rewrite the body
 - 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
-- Before a checkpoint, ledger write, or `code.completed`, the implementation report must pass `task-artifact ... preflight --family code`. Preflight only validates and seals a generation; `finalize-local` publishes the matching final digest later.
-- 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
-- Do not invoke the `commit` skill or push to a remote; after tests pass, call the shared commit core with `delivery: { mode: 'local' }` to create the local checkpoint. The durable intent must close only after the checkpoint and task state sync succeed; only then emit `code.completed`
+- After writing the implementation report, pass `task-artifact ... preflight --family code` before pending ledger writes, the checkpoint, later Issue syncs, or `code.completed`. Preflight validates and seals the generation without publishing formal/task/ledger/platform state; after the checkpoint, `finalize-local` revalidates the report and returns its digests for the `code.completed` event to record.
+- 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. Record `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}` as a pending ledger update and run it only after report preflight passes. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope.
+- Completing this skill requires a local checkpoint: after report preflight passes, call the shared commit core with `delivery: { mode: 'local' }`. Do not invoke the standalone `commit` skill, run raw `git add` / `git commit`, or push to a remote. The durable intent must close only after the checkpoint and task state sync succeed; only then emit `code.completed`.
 - Create a new code artifact for each round and never overwrite an older one
 - After executing this skill, you **must** immediately update task.md
 
@@ -116,10 +116,6 @@ Use the project test commands from the `test` skill and iterate until all requir
 
 When triaging a test failure or unexpected behavior, first read `.agents/rules/debugging-guide.md` and locate the root cause via its four-phase flow; do not blindly patch and retry.
 
-After tests pass, call the shared commit core with `agent-infra-internal git-workflow commit --input {checkpoint-input}`. Pass `delivery: { "mode": "local" }`, explicit paths, expected HEAD/tree, task ref, agent, and the code round. This creates only a local checkpoint and does not contact a remote. The core writes a durable intent before committing and removes it after task-writer synchronization; do not emit `code.completed` if either checkpoint or task synchronization fails.
-
-After the checkpoint succeeds, when task.md has a `platform_issue_identity`, run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --in-labels from-diff --base {delivery-base-ref}`. The task-bound `delivery_base_ref` is the only source for Issue `in:` evidence; record a warning and continue the local code stage if this sync fails. `complete-task` restores and verifies this evidence before archiving.
-
 ### 9. Write the Code Report
 
 Before writing this round's `{code-artifact}`, create the controlled report skeleton:
@@ -136,7 +132,27 @@ Create `.agents/workspace/active/{task-id}/{code-artifact}`.
 
 ### 10. Pre-completion Report Gate
 
-After writing the report and before publishing `code.completed`, read and follow `.agents/rules/local-artifact-repair.md` and run:
+After writing the report, read and follow `.agents/rules/local-artifact-repair.md`. Complete the preflight, pending ledger updates, local checkpoint, and finalizer in that order. If preflight fails, repair the same controlled candidate and rerun it; do not perform the later ledger updates, checkpoint, `code.completed`, or Issue sync in this gate. The milestone narrowing in step 3 remains an earlier prerequisite.
+
+Run preflight:
+
+```bash
+agent-infra-internal task-artifact {task-id} preflight --family code --artifact {code-artifact}
+```
+
+After preflight passes, apply pending ledger updates recorded during implementation, including `decision-upsert` and, in fix mode, `finding-respond`. Do not write these ledger updates before preflight passes.
+
+Then create the local checkpoint through the shared core. Pass `delivery: { "mode": "local" }`, explicit paths, expected HEAD/tree, task ref, agent, and code round:
+
+```bash
+agent-infra-internal git-workflow commit --input {checkpoint-input}
+```
+
+This creates only a local checkpoint and does not contact a remote. The core writes a durable intent before committing and removes it after task-writer synchronization; do not emit `code.completed` if either checkpoint or task synchronization fails.
+
+After the checkpoint succeeds, when task.md has a `platform_issue_identity`, run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --in-labels from-diff --base {delivery-base-ref}`. The task-bound `delivery_base_ref` is the only source for Issue `in:` evidence; record a warning and continue the local code stage if this sync fails. The PR stage computes and syncs the final `in:` labels.
+
+Then run the finalizer:
 
 ```bash
 finalizer=$(agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact})
@@ -169,6 +185,6 @@ Present the verification summary per `.agents/rules/validation-output.md`, retai
 
 ### 13. Tell the User
 
-Use `reference/output-template.md` (or `reference/fix-mode.md` in fix mode) and render the selected next-step commands through the shared helper. Do not push, create a PR, or invoke the `commit` skill here.
+Use `reference/output-template.md` (or `reference/fix-mode.md` in fix mode) and render the selected next-step commands through the shared helper. The local checkpoint is required for this skill; do not invoke the standalone `commit` skill, push, or create a PR here.
 
 > Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).

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

@@ -28,9 +28,9 @@ description: >
 - 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 实现前读取 `.agents/rules/compatibility-policy.md`；只实现方案明确批准的兼容预算，不以“稳妥”为由保留旧分支、旧结果契约或迁移 shim
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
-- 实现报告在 checkpoint、账本和 `code.completed` 前必须先通过 `task-artifact ... preflight --family code`；preflight 只验证并封存 generation，不发布 formal/task/ledger/platform 状态。随后 `finalize-local` 才发布同一次通过的 digest。
-- 实现中遇到方案未覆盖的关键设计决策时，先调用 `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}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
-- 不调用 `commit` 技能，也不推送远端；测试通过后直接调用共享 commit core 的 `delivery: { mode: 'local' }` 创建本地 checkpoint。checkpoint 使用 durable intent，只有 checkpoint 与 task 状态同步成功后才发送 `code.completed`
+- 实现报告写完后，必须先通过 `task-artifact ... preflight --family code`，再写入待处理账本、创建 checkpoint、执行后续 Issue 同步或发布 `code.completed`。preflight 只验证并封存 generation，不发布 formal/task/ledger/platform 状态；checkpoint 后运行 `finalize-local` 重新验证并取得摘要，`code.completed` 事件登记该摘要。
+- 实现中遇到方案未覆盖的关键设计决策时，调用 `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}` 留作待处理账本更新，在报告 preflight 通过后再执行。不得扫描编号、手写账本行、中途提问或擅自扩范围。
+- 完成本技能必须创建一个本地 checkpoint：实现报告 preflight 通过后直接调用共享 commit core，使用 `delivery: { mode: 'local' }`。不调用独立 `commit` 技能、不运行原始 `git add` / `git commit`，也不推送远端。checkpoint 使用 durable intent；只有 checkpoint 与 task 状态同步成功后才发送 `code.completed`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md
 
@@ -153,10 +153,6 @@ echo "$result"
 
 如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。
 
-测试通过后，先创建报告并运行 `task-artifact {task-id} preflight --family code --artifact {code-artifact}`；preflight 失败只允许在同一受控 candidate 中修复并完整重跑，且不得产生 checkpoint、ledger、completed 或平台副作用。preflight 通过后，才通过 `agent-infra-internal git-workflow commit --input {checkpoint-input}` 调用共享 commit core，输入 `delivery: { "mode": "local" }`、明确 paths、expected HEAD/tree、task ref、agent 和 code round。该调用只创建本地 checkpoint，不访问远端；core 会在 commit 前写入 durable intent，并在 task writer 成功后清理 intent。checkpoint 失败或 task 状态未闭合时，不得发送 `code.completed`。
-
-checkpoint 成功后，若任务存在 `platform_issue_identity`，调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --in-labels from-diff --base {delivery-base-ref}`，由 task-bound `delivery_base_ref` 产生 Issue 的 `in:` target；同步失败时记录 warning，继续完成本地代码阶段。`complete-task` 在归档前补齐并核验该证据。
-
 排查测试失败或行为不符合预期时，先读取 `.agents/rules/debugging-guide.md`，按其四阶段流程定位根因，禁止盲目改代码重试。
 
 ### 9. 编写实现报告
@@ -175,7 +171,27 @@ agent-infra-internal task-artifact {task-id} init --family code --artifact {code
 
 ### 10. 报告完成前门禁
 
-报告写入后、发布 `code.completed` 前，读取并遵循 `.agents/rules/local-artifact-repair.md`，执行：
+报告写入后，先读取并遵循 `.agents/rules/local-artifact-repair.md`，依次完成 preflight、待处理账本更新、本地 checkpoint 和 finalizer。preflight 失败只允许在同一受控 candidate 中修复并完整重跑；preflight 未通过时不得执行本门禁后续的账本更新、checkpoint、`code.completed` 或 Issue 同步。步骤 3 的里程碑收窄仍按其前置要求执行。
+
+执行 preflight：
+
+```bash
+agent-infra-internal task-artifact {task-id} preflight --family code --artifact {code-artifact}
+```
+
+preflight 通过后，先完成实现过程中记录的待处理账本更新，包括人工裁决 `decision-upsert` 和修复模式 `finding-respond`；不得在 preflight 通过前写入这些账本更新。
+
+然后通过以下调用共享 commit core 创建本地 checkpoint，输入 `delivery: { "mode": "local" }`、明确 paths、expected HEAD/tree、task ref、agent 和 code round：
+
+```bash
+agent-infra-internal git-workflow commit --input {checkpoint-input}
+```
+
+该调用只创建本地 checkpoint，不访问远端。core 会在 commit 前写入 durable intent，并在 task writer 成功后清理 intent。checkpoint 失败或 task 状态未闭合时，不得发送 `code.completed`。
+
+checkpoint 成功后，若任务存在 `platform_issue_identity`，调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --in-labels from-diff --base {delivery-base-ref}`，由 task-bound `delivery_base_ref` 产生 Issue 的 `in:` target；同步失败时记录 warning，继续完成本地代码阶段。PR 阶段计算并同步最终 `in:` 标签。
+
+随后执行 finalizer：
 
 ```bash
 finalizer=$(agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact})
@@ -232,12 +248,13 @@ agent-infra-internal task-verify {task-id} code.completed --artifact {code-artif
 - [ ] 已完成批准范围内的代码实现
 - [ ] 已创建 `{code-artifact}`
 - [ ] 所有必需测试通过
+- [ ] 已通过共享 commit core 创建本地 checkpoint
 - [ ] 已更新 task.md 并追加 Activity Log
 - [ ] 已通过统一 helper 渲染已选场景的下一步命令
 
 ## 停止
 
-完成检查清单后立即停止。不要在本技能中推送远端、创建 PR 或调用 `commit` 技能。
+完成检查清单后立即停止。本技能必须创建本地 checkpoint；不要在本技能中调用独立 `commit` 技能、推送远端或创建 PR。
 
 ## 注意事项
 

package/templates/.agents/skills/code-task/reference/code-rules.en.md

@@ -47,7 +47,7 @@ Two-way failure handling:
 ## Notes
 
 1. **Prerequisite**: the analysis or plan lifecycle input selected by core must exist
-2. **No auto-commit**: do not run `git commit` or `git add`
+2. **Local checkpoint**: after report preflight passes, `code-task` must create a local checkpoint through the shared commit core; do not run `git commit` or `git add` directly
 3. **Test quality**: new tests must validate meaningful business logic
 4. **Code quality**: follow project coding conventions
 5. **Plan deviation**: record any deviation in the code report

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

@@ -47,7 +47,7 @@
 ## 注意事项
 
 1. **前置条件**：必须存在核心按所选路径返回的 analysis 或 plan 生命周期输入
-2. **禁止自动提交**：不要执行 `git commit` 或 `git add`
+2. **本地 checkpoint**：实现报告 preflight 通过后，必须由 `code-task` 通过共享 commit core 创建本地 checkpoint；不要直接执行 `git commit` 或 `git add`
 3. **测试质量**：新增测试必须验证有意义的业务逻辑
 4. **代码质量**：遵循项目编码规范
 5. **方案偏离**：任何偏离都要记录到实现报告中

package/templates/.agents/skills/code-task/reference/fix-mode.en.md

@@ -4,7 +4,7 @@ Read this file before changing code during fix mode.
 
 ## Plan the Fixes
 
-**Verify each finding first (mandatory before editing)**: for every finding in `{review-artifact}`, Read/Grep the cited `file:line` and corresponding `git diff`, then choose one of the four states in `.agents/rules/review-handshake.md`. Submit it through `agent-infra-internal task-ledger {task-id} finding-respond --id {ledger-id} --round {code-round} --status {state} --evidence {evidence}` (every state needs commensurate evidence; "accept" is not a zero-cost default):
+**Verify each finding first (mandatory before editing)**: for every finding in `{review-artifact}`, Read/Grep the cited `file:line` and corresponding `git diff`, then choose one of the four states in `.agents/rules/review-handshake.md`. Record the response and evidence, then submit it through `agent-infra-internal task-ledger {task-id} finding-respond --id {ledger-id} --round {code-round} --status {state} --evidence {evidence}` after the code report preflight passes (every state needs commensurate evidence; "accept" is not a zero-cost default):
 - `accepted` → include it in the classification and fixes below; evidence cites the fix `file:line`
 - `adjusted` → use an alternative fix, with rationale; awaits review-code confirmation
 - `refuted` → verification judged it unfounded / a wrong `file:line` / hallucinated → do not change code; give a counter-argument in the report's `## Per-Finding Verification` section; awaits review-code confirmation
@@ -49,15 +49,11 @@ After completing the repair round, run the **smoke subset** to verify the comple
 
 Before writing the code report, run the project's **core subset** as final verification and confirm that all required tests still pass. If the project does not have layered scripts, fall back to the full project test command.
 
-## Choose the Next-Step Branch
+## Choose the Next Step
 
-Decision rules:
-1. always recommend re-review as the default next step, regardless of the severity of fixed issues
-2. direct commit may be selected only when all issues are resolved and the changes are clearly low risk
-3. do not select direct commit while any `Blocker` or `Major` remains unresolved
-4. render only the selected branch and invoke the helper exactly once
+After `code-task` creates the local checkpoint, the next step is always re-review. Do not route to the standalone `commit` skill because the checkpoint already exists.
 
-For the default branch, populate `{next-step-commands}` by running `agent-infra-internal agent-client next-steps --skill review-code --task-ref {task-ref}`:
+Populate `{next-step-commands}` by running `agent-infra-internal agent-client next-steps --skill review-code --task-ref {task-ref}`:
 
 ```text
 Task {task-id} fix completed.
@@ -75,17 +71,10 @@ Next step - review again:
 {next-step-commands}
 ```
 
-Only when the direct-commit branch satisfies the rules above and is selected, populate `{next-step-commands}` by running `agent-infra-internal agent-client next-steps --skill commit`, then replace the ending with:
-
-```text
-Next step - commit directly:
-{next-step-commands}
-```
-
 ## Notes
 
 1. **Prerequisite**: a code review artifact must exist (`review-code.md` or `review-code-r{N}.md`)
-2. **No auto-commit**: do not run `git commit`
+2. **Checkpoint**: fix mode must create the local checkpoint through the shared commit core after report preflight and pending ledger updates; do not run `git add` / `git commit` directly
 3. **Scope discipline**: verify each reviewed issue one by one — fix it if it holds, rebut it if it does not; do not expand to issues the review did not list
 4. **Disagreement handling**: record any disagreement in the report
 5. **Re-review**: recommend `review-code` as the default next step after fix mode

package/templates/.agents/skills/code-task/reference/fix-mode.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## 规划修复
 
-**先逐条核实（动手前必做）**：对 `{review-artifact}` 的每一条发现，先 Read/Grep 其引用的 `file:line` 与对应 `git diff`，确认问题真实存在，再按 `.agents/rules/review-handshake.md` 的四态处置；完成相称证据后逐条调用 `agent-infra-internal task-ledger {task-id} finding-respond --id {ledger-id} --round {code-round} --status {四态} --evidence {相称证据}`（"接受"不是零成本默认）：
+**先逐条核实（动手前必做）**：对 `{review-artifact}` 的每一条发现，先 Read/Grep 其引用的 `file:line` 与对应 `git diff`，确认问题真实存在，再按 `.agents/rules/review-handshake.md` 的四态处置；记录每条待写入的响应及相称证据，等 code 报告 preflight 通过后，再逐条调用 `agent-infra-internal task-ledger {task-id} finding-respond --id {ledger-id} --round {code-round} --status {四态} --evidence {相称证据}`（“接受”不是零成本默认）：
 - `accepted` → 纳入下方分类与修复，证据指向修复点 `file:line`
 - `adjusted` → 采用替代修法，附理由，待 review-code 复核确认
 - `refuted` → 核实判定不成立 / 基于错误 `file:line` / 幻觉 → 不改代码，在报告 `## 对审查发现的逐条核实` 给出反证，待 review-code 复核确认
@@ -49,15 +49,11 @@ manual-validation 项不在修复范围。处理规则：
 
 写 code 报告前，运行项目测试的 **core 子集**做最终验证，确保所有必需测试仍然通过。如果项目没有分层 script，回退到完整项目测试命令。
 
-## 选择下一步分支
+## 选择下一步
 
-判断规则：
-1. 始终将重新审查作为默认推荐的下一步，无论本轮修复了哪个级别的问题
-2. 直接提交仅可作为已选分支，且仅在所有问题均已解决且改动明显低风险时
-3. 如果仍有任何 `Blocker` 或 `Major` 未解决，不要选择直接提交
-4. 只渲染已选分支，且只调用一次 helper
+修复完成并由 `code-task` 创建本地 checkpoint 后，下一步统一为重新审查；不得把独立 `commit` 技能作为下一步，因为 checkpoint 已由 `code-task` 创建。
 
-默认分支使用 `agent-infra-internal agent-client next-steps --skill review-code --task-ref {task-ref}` 生成 `{next-step-commands}`：
+使用 `agent-infra-internal agent-client next-steps --skill review-code --task-ref {task-ref}` 生成 `{next-step-commands}`：
 
 ```text
 任务 {task-id} 修复完成。
@@ -75,17 +71,10 @@ manual-validation 项不在修复范围。处理规则：
 {next-step-commands}
 ```
 
-仅当直接提交分支满足上述条件并被选中时，改用 `agent-infra-internal agent-client next-steps --skill commit` 生成 `{next-step-commands}`，并将末尾替换为：
-
-```text
-下一步 - 直接提交：
-{next-step-commands}
-```
-
 ## 注意事项
 
 1. **前置条件**：必须存在代码审查产物（`review-code.md` 或 `review-code-r{N}.md`）
-2. **禁止自动提交**：不要执行 `git commit`
+2. **checkpoint**：修复阶段仍须由 `code-task` 在报告 preflight 和待处理账本更新后，通过共享 commit core 创建本地 checkpoint；不要直接执行 `git add` / `git commit`
 3. **范围约束**：逐条核实审查列出的问题，成立则修复、不成立则反驳；不扩大到审查未列出的问题
 4. **分歧处理**：如果不同意审查意见，要在报告里明确记录
 5. **重新审查**：修复后默认推荐执行 `review-code`

package/templates/.agents/skills/code-task/reference/report-template.en.md

@@ -84,7 +84,7 @@ Use this structure when creating `code.md` or `code-r{N}.md`.
 
 ## Per-Finding Verification
 
-> Fix mode only; for an initial implementation write "(initial implementation this round, no review findings)". Read/Grep-verify every prior finding and submit its four-state response through `task-ledger finding-respond`; do not edit the task.md table manually. accepted/adjusted cite the fix `file:line`; refuted/cannot-judge cite counter-evidence or raw command output.
+> Fix mode only; for an initial implementation write "(initial implementation this round, no review findings)". Read/Grep-verify every prior finding, record its four-state response and evidence, then submit it through `task-ledger finding-respond` after the code report preflight passes; do not edit the task.md table manually. accepted/adjusted cite the fix `file:line`; refuted/cannot-judge cite counter-evidence or raw command output.
 
 | Finding | Disposition | Commensurate evidence |
 |------|----------|----------|

package/templates/.agents/skills/code-task/reference/report-template.zh-CN.md

@@ -84,7 +84,7 @@
 
 ## 对审查发现的逐条核实
 
-> 仅修复模式填写；初次实现写「（本轮为初次实现，无审查发现）」。对上一轮 `review-code` 的每条发现先 Read/Grep 核实，再按四态处置；相称证据完成后通过 `task-ledger finding-respond` 提交结构化意图，不手写 task.md 表格。accepted/adjusted 附修复点 file:line，refuted/cannot-judge 附反证 file:line 或命令原文。
+> 仅修复模式填写；初次实现写「（本轮为初次实现，无审查发现）」。对上一轮 `review-code` 的每条发现先 Read/Grep 核实，再按四态处置；记录相称证据，并在 code 报告 preflight 通过后通过 `task-ledger finding-respond` 提交结构化意图，不手写 task.md 表格。accepted/adjusted 附修复点 file:line，refuted/cannot-judge 附反证 file:line 或命令原文。
 
 | 发现 | 处置状态 | 相称证据 |
 |------|----------|----------|

package/templates/.agents/skills/commit/SKILL.en.md

@@ -96,7 +96,7 @@ Present the verification summary per `.agents/rules/validation-output.md`; do no
 
 ## 6. Render the next step
 
-Before rendering the next step, read `.agents/rules/next-step-output.md` and call the unified helper exactly once based on the latest task and PR state. A failed push keeps the task active and reports only diagnostics; a final commit routes to `create-pr` or `complete-task` according to `prFlow`.
+Before rendering the next step, read `.agents/rules/next-step-output.md` and call the unified helper exactly once based on the latest task and PR state. A failed push keeps the task active and reports only diagnostics. When a verified PR is already bound, route to `watch-pr`; without a bound PR, route to `create-pr` or `complete-task` according to `prFlow`.
 
 ## Notes
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -96,7 +96,7 @@ agent-infra-internal task-verify {task-id} commit.completed --format text
 
 ## 6. 输出下一步
 
-渲染下一步前先读取 `.agents/rules/next-step-output.md`，并根据最新 task/PR 状态只调用一次统一 helper。push 失败时保持任务 active，只输出诊断；最终提交则按 `prFlow` 选择 `create-pr` 或 `complete-task`。
+渲染下一步前先读取 `.agents/rules/next-step-output.md`，并根据最新 task/PR 状态只调用一次统一 helper。push 失败时保持任务 active，只输出诊断；已有 verified 绑定 PR 时路由到 `watch-pr`；没有绑定 PR 时，按 `prFlow` 选择 `create-pr` 或 `complete-task`。
 
 ## 注意事项
 

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

@@ -186,25 +186,28 @@ Finalization runs allowed artifact backfill -> lifecycle -> terminal task commen
 
 Both Scenario A and Scenario B `finalization-retry` run the same `task-finalization` entry point from the host. The receipt is only a re-entry hint, not canonical truth: every re-entry revalidates allowed artifact backfill, the terminal task comment, and completion verification, then repeats summary seal from the retained durable staging record; only an already `completed` task with its short-id registry entry released may skip the irreversible lifecycle. Do not split the operation into the former lifecycle, comment-sync, or completion-gate commands. If backfill, the task comment, summary seal, or verification is blocked by the network, preserve the receipt, durable staging record, and completed steps, fix the network, and rerun complete-task. If lifecycle has not completed, keep the task active and resume the pending steps from the receipt.
 
-Consume the structured finalization result, receipt, and warning projection directly. Continue only for `completed` or `completed_with_warnings`; preserve the receipt and stop for `failed`, `blocked`, or `unknown`, then retry through the same finalization entry point. Do not run `ls completed` or `task-verify complete-task.completed` from a stale sandbox mount, and do not let that local result overrule the host result.
+Consume the structured finalization result, receipt, and warning projection directly. Continue only for `completed` or `completed_with_warnings`. Treat `failed` and `blocked` as explicit host failure or blocked outcomes: preserve the receipt, stop the current flow, and follow the returned status and error; call finalization again only when the host state permits it and the cause has been fixed. If an `accepted=true` request is `unknown`, preserve the receipt and original request ID. Never resubmit task-finalization; query only the original request with `sandbox-control recover <same-request-id>`. Create a new request only when the request was rejected before acceptance and its error permits a retry. Do not run `ls completed` or `task-verify complete-task.completed` from a stale sandbox mount, and do not let that local result overrule the host result.
 
-### Accepted sandbox-control result recovery
+### Recovering an accepted sandbox-control result
 
-When this skill is invoked from a sandbox and the control client reports an
-accepted request without a terminal result, preserve the request identity. The
-client prints `SANDBOX_CONTROL_REQUEST_ID: <request-id>` on stderr for this
-case. After the broker is healthy again, recover the same terminal response:
+When this skill runs in a sandbox and an accepted task-finalization request has
+no terminal result yet, the client automatically recovers under the same
+request ID. The five-minute total budget starts with the first unknown result;
+each recover call is limited to 30 seconds. While a published unknown response
+is present, the client rereads it every 25 ms during that call. When a recover
+call times out with unknown, the client continues immediately without an extra
+wait. The client prints `SANDBOX_CONTROL_REQUEST_ID: <request-id>` on stderr.
+
+If no terminal result arrives within five minutes, preserve the receipt and
+request ID and treat the result as pending/unknown. Do not resubmit
+task-finalization. Once the broker is healthy, continue querying only the
+original request ID:
 
 ```bash
 agent-infra-internal sandbox-control recover <request-id>
 ```
 
-Do not submit a new request for an accepted task finalization. The broker's
-`processing/<request-id>/result.json` is private transport evidence; it is not
-a task receipt and cannot by itself prove completion. The finalization receipt
-and the host completion gate remain authoritative. If the request was rejected
-before acceptance, a new request ID may be used according to the error's
-retryability.
+Do not submit a new request for an accepted task finalization. If the request ID is missing or the receipt cannot be read, keep the result pending and recover the original ID only from stderr, a handoff, or the receipt; do not look it up by task key. The broker's `processing/<request-id>/result.json` is private transport evidence, not a task receipt, and cannot by itself prove completion. The finalization receipt and host completion gate remain authoritative. If recovery with the same ID still has no terminal result, inspect broker and host executor activity. Stop and preserve the original request ID while a request is active, the broker is busy, or status is unknown. Retry with a new request ID only after confirming that the original request never started or its executor has ended; the new request performs the full prepare and commit after broker admission. Only a request rejected before acceptance may be retried directly with a new request ID according to the error's retryability.
 
 ### 8. Inform User
 

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

@@ -185,24 +185,25 @@ finalization 按允许的 artifact backfill → lifecycle → task 评论 → co
 
 场景 A 与场景 B `finalization-retry` 都从宿主执行同一个 `task-finalization` 入口。receipt 只是重入提示，不是 canonical truth：每次重入都要重新核对允许的 artifact 回填、终态 task 评论、完成校验，并使用保留的 durable staging record 重做 summary seal；只有任务已处于 `completed` 且短号 registry 已释放时，才可跳过不可逆的 lifecycle。不得拆开调用旧的 lifecycle、评论同步或完成校验命令。若回填、task 评论、summary seal 或校验因网络问题返回 `blocked`，保留 receipt、durable staging record 和已完成状态，修复网络后重跑 complete-task；若生命周期仍未完成，任务保持 active 并从 receipt 的待处理步骤继续。
 
-完成结果必须直接消费本次宿主 finalization 的结构化输出、receipt 和 warning projection。`completed` 或 `completed_with_warnings` 才允许继续；`failed` / `blocked` / `unknown` 必须保留 receipt 并停止，之后通过同一 finalization 入口重试。不要在沙箱旧挂载中另行运行 `ls completed` 或 `task-verify complete-task.completed`，也不要用其结果推翻宿主结果。
+完成结果必须直接消费本次宿主 finalization 的结构化输出、receipt 和 warning projection。只有 `completed` 或 `completed_with_warnings` 允许继续。`failed` / `blocked` 是宿主明确返回的失败或阻塞结果：保留 receipt，停止当前流程，并按宿主返回的状态和错误处理；只有宿主状态允许且原因已修复时，才重新调用 finalization。若 `accepted=true` 的请求结果为 `unknown`，保留 receipt 和原 request ID；不得重发 task-finalization，只能通过 `sandbox-control recover <同一 request-id>` 查询原请求。只有请求在 accepted 之前被拒绝，且错误允许重试时，才可创建新请求。不要在沙箱旧挂载中另行运行 `ls completed` 或 `task-verify complete-task.completed`，也不要用其结果推翻宿主结果。
 
 ### accepted 后的 sandbox-control 结果恢复
 
-如果本技能在沙箱内执行，且 control client 报告请求已经 accepted 但没有
-terminal result，必须保留原 request identity。此时 client 会在 stderr 输出
-`SANDBOX_CONTROL_REQUEST_ID: <request-id>`。broker 恢复健康后，使用同一个
-request ID 读取 terminal response：
+如果本技能在沙箱内执行，且 task-finalization 请求已经 accepted 但暂时没有
+terminal result，client 会从首次 unknown 开始自动按同一个 request ID 恢复，
+总预算为 5 分钟，每次 recover 最多 30 秒；published unknown 会在当前调用中
+按 25ms 间隔重读，预算用尽后立即继续 recover，不额外等待。client 会在 stderr
+输出 `SANDBOX_CONTROL_REQUEST_ID: <request-id>`。
+
+5 分钟后仍没有 terminal result 时，必须保留 receipt 和 request ID，并将结果视为
+pending/unknown；不得重发 task-finalization。broker 恢复健康后，只能继续查询原
+request ID：
 
 ```bash
 agent-infra-internal sandbox-control recover <request-id>
 ```
 
-accepted 的 task finalization 不得提交新请求。broker 的
-`processing/<request-id>/result.json` 只是私有 transport evidence，不是 task
-receipt，单凭它不能证明任务完成；finalization receipt 和宿主完成校验仍是
-权威。如果请求在 accepted 之前已被拒绝，则可依据错误的 retryability 使用
-新的 request ID。
+accepted 的 task finalization 不得提交新请求。若 request ID 缺失或 receipt 无法读取，保持 pending；只从 stderr、handoff 或 receipt 中恢复原 ID，不按 task key 查询。broker 的 `processing/<request-id>/result.json` 只是私有 transport evidence，不是 task receipt，单凭它不能证明任务完成；finalization receipt 和宿主完成校验仍是权威。若同 ID 恢复仍没有 terminal result，必须检查 broker 和宿主 executor 的活动状态：活动请求、`busy` 或状态未知时停止并保留原 request ID。只有确认原请求从未启动或 executor 已结束后，才可用新的 request ID 重试；新请求会在 broker 接纳后执行完整 prepare 和 commit。仅当请求在 accepted 之前已被拒绝时，才可直接依据错误的 retryability 决定是否提交新的 request ID.
 
 ### 8. 告知用户
 

package/templates/.agents/skills/create-pr/reference/pr-body-template.en.md

@@ -57,7 +57,7 @@ Milestone rule:
 
 - Extract `platform_issue_identity` from task.md when this work belongs to an active task
 - If `platform_issue_identity` exists, complete the prerequisite code-hosting platform detection steps first, then query the Issue via `.agents/rules/issue-pr-commands.md`
-- Before calling the PR creation command, check whether the current branch already has a PR. If it does, report the PR URL and state, then stop without repeating metadata sync or summary publication
+- Before calling `platform-pr create`, check whether the current branch already has a PR. If the task is bound to the unique PR, the core reuses that bound identity and continues metadata sync, change reporting, and summary publication. If an existing PR is unbound, verify and bind its identity before continuing; an ordinary create request without a bound PR identity may create a new PR
 - Use HEREDOC to pass the PR body
 - Replace `{$IssueNumber}` in the template when present
 - End the PR body with `Generated with AI assistance`

package/templates/.agents/skills/create-pr/reference/pr-body-template.zh-CN.md

@@ -57,7 +57,7 @@ Milestone 规则：
 
 - 当前工作属于 active task 时，从 task.md 提取 `platform_issue_identity`
 - 如果存在 `platform_issue_identity`，先完成代码托管平台检测，再通过 `.agents/rules/issue-pr-commands.md` 查询 Issue
-- 调用 PR 创建命令前，先检查当前分支是否已有 PR；若已有，报告 PR URL 和状态后停止，不重复执行元数据同步或 summary 发布
+- 调用 `platform-pr create` 前检查当前分支是否已有 PR；任务已绑定到唯一 PR 时，core 复用该绑定身份并继续完成元数据同步、变更报告和摘要发布；发现已有 PR 但任务尚未绑定时，先核验并绑定其身份再继续；未绑定 PR 身份的普通创建请求可能会创建新的 PR
 - 使用 HEREDOC 传入 PR 正文
 - 模板中存在 `{$IssueNumber}` 时进行替换
 - PR 正文以 `Generated with AI assistance` 结尾

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

@@ -175,7 +175,7 @@ manual-validation counts do not influence branch selection; they are displayed o
 
 > Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
 
-render the selected next-step commands through the shared helper. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+Render only the selected scenario's commands returned by the shared helper. The helper builds custom tool commands from `sandbox.tools.ids` and `sandbox.tools.definitions`; do not reread configuration or manually append commands.
 
 ## Completion Checklist
 

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

@@ -171,7 +171,7 @@ manual-validation 的数量不参与分支选择，只作为人工校验计数
 
 > 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
-向用户通过统一 helper 渲染已选场景的下一步命令。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+向用户只展示统一 helper 返回的已选场景命令。自定义工具命令由 helper 按 `sandbox.tools.ids` 和 `sandbox.tools.definitions` 生成；不得再次读取配置或手工追加命令。
 
 ## 完成检查清单
 

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

@@ -41,10 +41,10 @@ If the summary cannot be parsed safely, set `{last-readable-review-result}` to "
 
 Do not route by review round. Read `prFlow` / verified `pr_delivery_fact`; when a PR exists, call `agent-infra-internal platform-checks inspect {task-id}`. Select exactly one mutually exclusive exit:
 
-- No PR: use Branch A3 (complete) when `prFlow=disabled`; otherwise use Branch A1 (create PR).
-- Existing PR with PR head != `R`: Branch A1 (create or update the PR).
-- PR head = `R` with `pending|failed|cancelled` checks or temporarily unavailable platform state: Branch A2 (watch); never show completion.
-- PR head = `R` with `passed|no-required` checks: Branch A3 (complete).
+- No PR: use Branch A4 (complete) when `prFlow=disabled`; otherwise use Branch A1 (create PR).
+- Existing PR with PR head != `R`: Branch A2 (update the existing PR).
+- PR head = `R` with `pending|failed|cancelled` checks or temporarily unavailable platform state: Branch A3 (watch); never show completion.
+- PR head = `R` with `passed|no-required` checks: Branch A4 (complete).
 
 Common Branch A summary:
 
@@ -63,7 +63,16 @@ Next step - create a Pull Request:
 {next-step-commands}
 ```
 
-#### Branch A2: Watch All Checks
+#### Branch A2: Update an Existing Pull Request
+
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit --task-ref {task-ref}`. `commit` delivers the current commit; when there is no new commit, it uses push-only delivery to update the bound PR. The commit skill routes a bound PR to `watch-pr` afterward.
+
+```text
+Next step - update the existing Pull Request:
+{next-step-commands}
+```
+
+#### Branch A3: Watch All Checks
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}`.
 
@@ -72,7 +81,7 @@ Next step - watch PR checks:
 {next-step-commands}
 ```
 
-#### Branch A3: Complete and Archive
+#### Branch A4: Complete and Archive
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.