@fitlab-ai/agent-infra 0.9.3 → 0.9.4

package/lib/task/resolve-ref.ts

@@ -132,6 +132,43 @@ function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string
   return out;
 }
 
+/**
+ * Enumerate every task directory, including the cold YYYY/MM/DD archive.
+ * Invalid directory names, symlinks and entries without task.md are ignored;
+ * duplicate task ids fail closed because their identity would be ambiguous.
+ */
+function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: string; state: TaskWorkspaceState }[] {
+  const out: { taskId: string; taskDir: string; state: TaskWorkspaceState }[] = [];
+  const seen = new Set<string>();
+  const add = (taskId: string, taskDir: string, state: TaskWorkspaceState) => {
+    if (!TASK_ID_RE.test(taskId)) return;
+    const stat = fs.lstatSync(taskDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !fs.existsSync(path.join(taskDir, 'task.md'))) return;
+    if (seen.has(taskId)) throw new Error(`duplicate task identity: ${taskId}`);
+    seen.add(taskId);
+    out.push({ taskId, taskDir, state });
+  };
+
+  for (const state of FLAT_WORKSPACE_DIRS) {
+    const base = path.join(repoRoot, '.agents', 'workspace', state);
+    if (!fs.existsSync(base)) continue;
+    for (const taskId of fs.readdirSync(base).sort()) add(taskId, path.join(base, taskId), state);
+  }
+
+  const archive = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  for (const year of listSortedNumeric(archive, 4).reverse()) {
+    const yearDir = path.join(archive, year);
+    for (const month of listSortedNumeric(yearDir, 2).reverse()) {
+      const monthDir = path.join(yearDir, month);
+      for (const day of listSortedNumeric(monthDir, 2).reverse()) {
+        const dayDir = path.join(monthDir, day);
+        for (const taskId of fs.readdirSync(dayDir).sort()) add(taskId, path.join(dayDir, taskId), 'archive');
+      }
+    }
+  }
+  return out;
+}
+
 function locateHotTaskDirs(
   repoRoot: string,
   taskId: string
@@ -312,7 +349,15 @@ function resolveTaskContext(
   return { ok: true, repoRoot, ...match, state: 'active' };
 }
 
-export { resolveTaskRef, resolveTaskContext, detectRepoRoot, enumerateTaskDirs, locateHotTaskDirs, TASK_ID_RE };
+export {
+  resolveTaskRef,
+  resolveTaskContext,
+  detectRepoRoot,
+  enumerateTaskDirs,
+  enumerateAllTaskDirs,
+  locateHotTaskDirs,
+  TASK_ID_RE
+};
 export type {
   ResolveRefResult,
   ResolveTaskRefErrorCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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

@@ -16,7 +16,7 @@ so you can quickly find "which ones to read" without opening each file.
 ## Issue / PR
 
 - [`issue-pr-commands.md`](issue-pr-commands.md) — PR commands and Issue intent entry points.
-- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch PR required checks and pull failure logs (`watch-pr`).
+- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch all PR checks and pull failure logs (`watch-pr`).
 - [`create-issue.md`](create-issue.md) — Declarative Issue creation after `create-task` writes `task.md`.
 - [`issue-sync.md`](issue-sync.md) — Issue comment markers and declarative metadata intent contract.
 - [`issue-fields.md`](issue-fields.md) — Dynamic Issue Type pinned-field mapping boundary.

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

@@ -15,7 +15,7 @@
 ## Issue / PR
 
 - [`issue-pr-commands.md`](issue-pr-commands.md) — PR 命令集与 Issue intent 入口说明。
-- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR required checks、拉取失败日志的命令集（`watch-pr`）。
+- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR 全部 checks、拉取失败日志的命令集（`watch-pr`）。
 - [`create-issue.md`](create-issue.md) — `create-task` 落盘后的声明式 Issue 创建 intent。
 - [`issue-sync.md`](issue-sync.md) — Issue 评论 marker 与声明式元数据 intent 契约。
 - [`issue-fields.md`](issue-fields.md) — 动态 Issue Type pinned 字段映射边界。

package/templates/.agents/rules/human-decision-context.en.md

@@ -6,7 +6,7 @@ This rule governs every new `[needs-human-decision]` detail block produced by an
 
 A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. Start in plain language: explain why a decision is needed now, what must be chosen, which choice is recommended, and why. Then explain what the choice affects and what could go wrong if the wrong choice is made or no action is taken.
 
-Provide at least two options with short names, and state the benefits and trade-offs of each one. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
+Provide at least two options with short names. For each option, explain what would actually be done, what would happen after choosing it, its benefits, and its trade-offs. Each decision must also include at least one everyday example or analogy that stays true to the real effects and helps the maintainer compare the options. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
 
 ## Canonical Structure
 
@@ -19,19 +19,28 @@ Provide at least two options with short names, and state the benefits and trade-
 - **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
 - **What this affects**: {affected behavior, files, users, or future practice}
 - **What could go wrong**: {problems caused by the wrong choice or no action}
+- **Everyday example or analogy**: {a familiar comparison that accurately reflects the real effects and helps compare the options}
 
 #### Option A: {Name}
 
+- **What would actually be done**: {how the system or follow-up work would handle this option}
+- **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
 
 #### Option B: {Name}
 
+- **What would actually be done**: {how the system or follow-up work would handle this option}
+- **What happens after choosing it**: {specific changes for users, behavior, or follow-up work}
 - **Benefits**: {what this option provides}
 - **Trade-offs**: {what this option costs and where it falls short}
 ```
 
-Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
+Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. An example or analogy helps understanding; it does not replace facts, concrete effects, or risks. One example that clearly compares the overall choice is enough, so do not mechanically repeat the same analogy under every option. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
+
+## Implementation Intent Declaration
+
+For the code stage, the author must add `**Implementation required**: yes/no` after the options, then pass `--needs-implementation true|false` when `finding-review` escalates to `needs-human-decision` or when calling `decision-upsert`. The value is stored as a predeclared implementation input, so maintainers normally omit this option from `ai decide`. Historical tasks without a declaration may still pass it explicitly to `ai decide`; a value that conflicts with an existing declaration is rejected.
 
 ## Decision Closure
 

package/templates/.agents/rules/human-decision-context.zh-CN.md

@@ -6,7 +6,7 @@
 
 详情必须让维护者不需要了解内部流程，也不需要再问模型，就能看懂并做选择。先用大白话说明为什么现在需要决定、具体要选什么、建议选哪个以及原因；再说明会影响什么、选错或暂不处理会怎样。
 
-每项至少提供两个有简短名称的方案，并分别写清好处和代价。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
+每项至少提供两个有简短名称的方案，并分别写清实际会怎么做、选了以后会怎样、好处和代价。每项还必须提供至少一个贴近日常、且不歪曲事实的例子或类比，帮助维护者比较方案。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
 
 ## 规范结构
 
@@ -19,19 +19,28 @@
 - **为什么这样建议**：{结合好处、代价和现有限制说明原因}
 - **会影响什么**：{会受影响的功能、文件、用户或后续做法}
 - **如果选错或暂不处理**：{可能出现的问题}
+- **打个比方**：{用一个贴近日常且符合真实影响的例子或类比，帮助比较方案}
 
 #### 方案 A：{名称}
 
+- **实际会怎么做**：{选择该方案后，系统或后续工作具体怎么处理}
+- **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
 
 #### 方案 B：{名称}
 
+- **实际会怎么做**：{选择该方案后，系统或后续工作具体怎么处理}
+- **选了以后会怎样**：{用户、功能或后续工作会发生什么具体变化}
 - **好处**：{选择该方案能得到什么}
 - **代价**：{选择该方案要付出什么、有哪些局限}
 ```
 
-可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
+可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。例子或类比用于帮助理解，不能替代事实、实际影响和风险说明；一个能清楚比较整体选择的例子即可，不必为每个方案机械重复同一类比。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
+
+## 实现意图声明
+
+code 阶段的提出者必须在详情块的方案说明后另写 `**是否需要实现**：是/否`，并在 `finding-review` 升级为 `needs-human-decision` 或 `decision-upsert` 时传入 `--needs-implementation true|false`。该值会作为待裁决实现输入保存；维护者执行 `ai decide` 时通常无需再传此参数。历史任务没有预先声明时，仍可在 `ai decide` 中显式传参；显式值与已有声明冲突时命令失败。
 
 ## 裁决闭环
 

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

@@ -1,6 +1,6 @@
 # PR Readiness Platform Intents
 
-Typed intents own required-check selection, PR mergeability, polling deadlines, run/job resolution, and logs. Every inspect/poll aggregates facts from one PR head snapshot; facts are never mixed across heads.
+Typed intents own full check-set retrieval, PR mergeability, polling deadlines, run/job resolution, and logs. Every inspect/poll aggregates facts from one PR head snapshot; facts are never mixed across heads.
 
 ```bash
 agent-infra-internal platform-checks inspect {task-id}

package/templates/.agents/rules/pr-checks-commands.github.en.md

@@ -15,4 +15,4 @@ agent-infra-internal platform-checks logs {task-id} \
   --run {run-id} [--job {job-id}]
 ```
 
-The adapter normalizes REST `mergeable=false` to `conflicting`, null/missing to `unknown`, and true to `mergeable`; `mergeable=true` plus diagnostic `dirty` is contradictory and becomes `unknown`. Other diagnostics such as `blocked` do not override REST true. Core combines that fact with required checks for one `headSha`: only `ready` exits 0, `conflicting|checks-failed` exit 1, and pending/timeout/cancel/network blocking exit 2. Dependency and deterministic platform errors are preserved without degradation.
+The adapter normalizes REST `mergeable=false` to `conflicting`, null/missing to `unknown`, and true to `mergeable`; `mergeable=true` plus diagnostic `dirty` is contradictory and becomes `unknown`. Other diagnostics such as `blocked` do not override REST true. Core combines that fact with all checks for one `headSha`: only `ready` exits 0, `conflicting|checks-failed` exit 1, and pending/timeout/cancel/network blocking exit 2. Dependency and deterministic platform errors are preserved without degradation.

package/templates/.agents/rules/pr-checks-commands.github.zh-CN.md

@@ -1,6 +1,6 @@
 # GitHub PR readiness 平台意图
 
-required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
+PR 全部 checks 的获取、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
 GitHub adapter 要求 `gh >= 2.16.0`。平台上下文会在任何 GitHub API、PR 或 checks 操作前检查该依赖；未选择 GitHub 平台时不探测也不依赖 `gh`。
 
@@ -13,7 +13,7 @@ agent-infra-internal platform-checks watch {task-id} \
   --interval-seconds 30 --deadline-seconds 1800
 ```
 
-adapter 把 REST `mergeable=false` 规范化为 `conflicting`，null/缺失为 `unknown`，true 为 `mergeable`；true 与诊断 `dirty` 矛盾时降为 `unknown`。`blocked` 等其他诊断不覆盖 REST true。core 在同一 `headSha` 上与 required checks 聚合：仅 `ready` 退出 0，`conflicting|checks-failed` 退出 1，pending/timeout/cancel/网络阻塞退出 2。依赖与确定性平台错误不降级。
+adapter 把 REST `mergeable=false` 规范化为 `conflicting`，null/缺失为 `unknown`，true 为 `mergeable`；true 与诊断 `dirty` 矛盾时降为 `unknown`。`blocked` 等其他诊断不覆盖 REST true。core 在同一 `headSha` 上与全部 checks 聚合：仅 `ready` 退出 0，`conflicting|checks-failed` 退出 1，pending/timeout/cancel/网络阻塞退出 2。依赖与确定性平台错误不降级。
 
 ## 定位失败 run/job
 

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -1,6 +1,6 @@
 # PR readiness 平台意图
 
-required checks、PR mergeability、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。每次 inspect/poll 都在同一 PR head 快照上聚合，不跨 head 拼接事实。
+PR 全部 checks、PR mergeability、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。每次 inspect/poll 都在同一 PR head 快照上聚合，不跨 head 拼接事实。
 
 ## 快照与监控
 

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -93,7 +93,7 @@
 - 成功提交后令 `B=last_reviewed_commit=<new_head>`；`B` 只表示已经落到 Git commit 的审查锚点。
 - `complete-task` 的 `post-review-commit` gate 只使用 B；B 缺失、畸形或对象不存在时报告 `reviewed snapshot was not anchored`，不得回退 R。
 - 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。自动例外仅限两类：(1) 绑定的平台变更请求（PR/MR）已合并，且平台适配器提供权威快照与远端 Git 证据引用；gate 在隔离的临时仓库中抓取受审查 head 与目标分支，证明 B 是原变更请求 head、merge commit 位于权威目标分支历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；(2) 无有效变更请求，B 后恰有一个受保护路径提交，该提交是本地 HEAD 历史中的单父重写，且它与 B 的完整 tree 相同或受保护内容相同，重写后也没有受保护路径提交。适配器不支持该能力，缺少所需平台 / Git 证据，或当前 Git 凭据不能读取这些远端 refs 时 fail closed。
-- required checks 由合并前的分支保护 / ruleset 与 `review-code` / `watch-pr` 路由负责。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
+- 全部 PR checks 由合并前的 `review-code` / `watch-pr` 路由负责，其中 required checks 仍受分支保护 / ruleset 强制。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
 
 ## gate 行为速查

package/templates/.agents/rules/task-management.en.md

@@ -83,4 +83,6 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
 - **Deferred form (the skill creates task.md, so there is no file to write to at the start)** — capture `started_at` in memory before running, then when writing the Activity Log at the end, **append both lines at once** (started line uses `started_at`, done line uses the completion time):
   `create-task`, `import-issue`, `import-codescan`, `import-dependabot`.
 
+- **After host resolution** — `review-pr` writes started through `task-activity pr-review-start` only after resolving the unique task host, canonical round, and reviewed head. Success closes through `pr-review-complete`; a controlled pre-publication failure or head drift closes through `pr-review-terminate` with an `aborted` / `superseded` terminal. Replaying the same task/round/head/terminal payload is a no-op; one-shot review never writes a task Activity Log.
+
 **Exceptions**: read-only inspection skills that do not represent real progress (e.g. `check-task`) do not write started. A bare operation with no task.md context (e.g. a `commit` not tied to a task) likewise skips it.

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

@@ -86,4 +86,6 @@
 - **延迟补写（本技能创建 task.md，开始时无文件可写）**——开始执行前先在内存记录 `started_at`，最后写活动日志时**一次性补两条**（started 行用 `started_at`、done 行用完成时间）：
   `create-task`、`import-issue`、`import-codescan`、`import-dependabot`。
 
+- **宿主解析后写入**——`review-pr` 只有在唯一任务宿主、canonical round 与被审 head 确定后才通过 `task-activity pr-review-start` 写 started；成功以 `pr-review-complete` 闭合，已知未发布的受控失败或 head 漂移以 `pr-review-terminate` 写 `aborted` / `superseded` 终态。同一 task/round/head/terminal payload 重放为 no-op；一次性检视不写任务日志。
+
 **例外**：`check-task` 等只读巡检类、不代表实质工作推进的技能不写 started。无 task.md 上下文的纯操作（如无关联任务的 `commit`）同样跳过。

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

@@ -17,7 +17,7 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 
 - Follow the latest plan artifact: `plan.md` or `plan-r{N}.md`
 - Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; manual-validation items are out of scope
-- If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md`, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
+- If implementation encounters a key design decision not covered by the plan, run `agent-infra-internal task-ledger {task-id} decision-next-id`, write the returned `HD-N` detail block per `.agents/rules/human-decision-context.md` and determine whether implementation is required, then run `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`. Do not scan ids, assemble ledger rows, ask mid-flow, or silently expand scope
 - Never auto-run `git add` or `git commit`
 - Create a new code artifact for each round and never overwrite an older one
 - After executing this skill, you **must** immediately update task.md

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

@@ -17,7 +17,7 @@ description: >
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
-- 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
+- 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块并判断是否需要实现，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md

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

@@ -13,7 +13,9 @@ Create a Git commit without overwriting user work and update the related task st
 
 When updating related `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
 
-Direct invocation still requires explicit user authorization. For an active orchestration run, only its unconsumed one-use `commitAuthorization` is equivalent authorization for this round; orchestration core must consume it after success, and every other commit gate remains unchanged.
+When the entry business operands literally contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated`; otherwise bind it to empty. Never infer the source from a run file or environment.
+
+Direct invocation still requires explicit user authorization. An orchestrated invocation may continue only after the commit intent validates its activated receipt and one-use `commitAuthorization` before side effects; every other commit gate remains unchanged.
 
 ## Common Rationalizations and Rebuttals
 
@@ -29,7 +31,9 @@ Direct invocation still requires explicit user authorization. For an active orch
 
 Without explicit task scope, only `TASK_CONTEXT_NOT_FOUND` may continue through the existing bare-commit path. Detached HEAD, damaged candidates, or multiple matches are ambiguity errors. Any explicit task-scope failure is fatal.
 
-## Step Start: Write the started Marker
+## Step Start: Recover First, Then Write the started Marker
+
+When `{task-id}` is resolved, call `commit-status` first. For `recoverable` / `prepared`, call `commit-recover --agent {standard-agent-token}` without adding a second started entry or repeating Git side effects. Fail closed for `invalid` / `conflict` / `orphaned-start`; only `idle` enters the normal flow.
 
 Before checking local modifications, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
 
@@ -64,14 +68,18 @@ Review status, diff, and recent history, then prepare a Conventional Commit with
 
 ## 4. Create the Commit
 
+When `{task-id}` was resolved, read `reference/commit-orchestration.md` before this step and complete `commit-begin` before any successful Git/platform side effect. A taskless Git-only commit skips the intent protocol entirely.
+
 Detect the restricted push-only scenario first. Otherwise write message, explicit paths, and expected HEAD/tree to JSON and call `agent-infra-internal git-workflow commit --input {file}`.
 
+Immediately after a normal commit succeeds, run the committed checkpoint from that reference. If the checkpoint fails, retain the intent and stop before push or success-state writes.
+
 If this commit is associated with a task and a `review-code` artifact exists, read the highest-round `review-code` artifact before committing:
 - If that artifact's `Overall Verdict` / `总体结论` is Approved, parse `R`, `F`, and `Reviewed Snapshot Tree` / `审查快照树` (`T`)
 - After staging the explicit files, record `pre_head=$(git rev-parse HEAD)` and use the helper's JSON mode to generate the complete worktree tree `W` and normalized staged tree `S`
 - Before `git commit`, require `pre_head == R && W == T && S == T`; use the helper's `compare` mode to produce added, missing, and different diagnostics for both worktree and staged snapshots
 - If any condition fails, enter Scenario 4 in `reference/task-status-update.md`; do not run `git commit`, push, successful state updates, PR summary sync, or the completion gate
-- After all comparisons match and the commit succeeds, write `last_reviewed_commit: <new_head>` to task.md frontmatter
+- After all comparisons match and the commit succeeds, the Step 6 `commit-complete` core finalizer atomically writes `last_reviewed_commit` and Commit done; the caller must not write them
 - Do not scan backward to earlier Approved artifacts; the highest-round `review-code` artifact is the only authoritative source
 
 ## 5. Push to the Existing PR When Applicable
@@ -86,6 +94,8 @@ b. On an open PR -> push the current branch:
 
 Use `agent-infra-internal git-workflow push --input {file}` for per-ref normal push and verification. Never force push.
 
+After push succeeds and remote verification completes, immediately run the pushed checkpoint from `reference/commit-orchestration.md`.
+
 c. Safe degradation (never block an already completed `git commit`; only warn the user):
    - Platform unavailable / unauthenticated / detection failed / no open PR -> do not push; continue.
    - `git push` fails (needs `git pull --rebase`, no upstream, network error) -> keep the local commit and tell the user to push manually.
@@ -94,6 +104,12 @@ Fold the push outcome (pushed / skipped(no PR) / failed) into the next step's "U
 
 ## 6. Update Task Status When Applicable
 
+After checkpoints and before synchronization or the completion gate, call `commit-complete`. Under the task lock, core writes the review anchor, Commit done, and planned orchestration bytes, then deletes the intent last. On failure retain the intent and let the next skill run use status/recover.
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
+```
+
 Get the current time:
 
 ```bash
@@ -104,7 +120,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md` and invoke the shared helper for the scenario selected from `reference/task-status-update.md`.
 
-Append the Commit Activity Log entry and choose exactly one next-step case:
+After core finalization succeeds, choose exactly one next-step case:
 - open PR and successful push -> `watch-pr {task-ref}`; this takes precedence over the final-commit `prFlow` route
 - failed push -> keep the task active and show only push/synchronization diagnostics; do not show `watch-pr` or `complete-task`
 - final commit -> render the next step by `.agents/.airc.json`'s `prFlow` (`disabled` -> single option `complete-task`; `required` -> single option `create-pr`; absent -> two options `create-pr` / `complete-task`); see Case 1 in `reference/task-status-update.md`
@@ -146,13 +162,7 @@ Handle the result as follows:
 
 Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
 
-After the gate passes, declare the orchestrated commit stage complete. This command is a no-op when no active orchestration run exists, so the direct commit path remains unchanged:
-
-```bash
-agent-infra-internal task-orchestration {task-id} stage-completed --agent {standard-agent-token}
-```
-
-Stop if the command fails; a run without the full receipt lifecycle must not be marked completed.
+Run this gate only after core finalization succeeds; never place it before `commit-complete`.
 
 ## Notes
 

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

@@ -13,7 +13,9 @@ description: >
 
 更新关联 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
 
-直接调用仍要求用户显式授权。若存在 active orchestration run，只有未消费的一次性 `commitAuthorization` 可作为本轮等价授权；提交成功后必须由 orchestration core 消费，其他提交门禁保持不变。
+若入口业务操作数包含字面 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated`；否则绑定为空。不得从 run 文件或环境推断来源。
+
+直接调用仍要求用户显式授权。编排调用只有在副作用前通过 commit intent 对 activated receipt 与一次性 `commitAuthorization` 的联合校验后才可继续，其他提交门禁保持不变。
 
 ## 常见违规借口与反驳
 
@@ -29,7 +31,13 @@ description: >
 
 未显式指定 task scope 时，只有 `TASK_CONTEXT_NOT_FOUND` 可继续既有纯提交路径；detached HEAD、损坏候选或多匹配属于歧义，必须失败。显式 task scope 解析失败时一律失败。
 
-## 步骤开始：写入 started 标记
+## 步骤开始：先恢复，再写 started 标记
+
+已解析出 `{task-id}` 时，先调用 `agent-infra-internal task-orchestration {task-id} commit-status`：
+
+- `recoverable` / `prepared`：调用 `commit-recover --agent {standard-agent-token}`；不得追加第二条 started、重复 commit 或重复 push。recoverable 完成后直接进入同步与完成校验；prepared 清理后复用既有 open started 并继续正常提交。
+- `invalid` / `conflict` / `orphaned-start`：输出结构化 code 与状态证据并停止。
+- `idle`：继续下方正常流程。
 
 开始检查本地修改之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
 
@@ -64,14 +72,18 @@ git diff
 
 ## 4. 创建提交
 
+已解析出 `{task-id}` 时，执行本步骤前先读取 `reference/commit-orchestration.md`，并在任何 Git/平台成功副作用前完成 `commit-begin`；无任务上下文的纯 Git 提交完全跳过 intent 协议。
+
 先判断受限 push-only 场景；否则把 message、显式路径、expected HEAD/tree 写入临时 JSON，并调用 `agent-infra-internal git-workflow commit --input {file}`。core 负责范围、敏感文件、暂存树和幂等校验。
 
+普通 commit 成功后必须立即按该 reference 执行 committed checkpoint；checkpoint 失败时保留 intent 并停止，不得继续 push 或写成功状态。
+
 如果本次提交关联任务且存在 `review-code` 产物，在提交前读取最高轮 `review-code` 产物：
 - 若该产物 `总体结论` / `Overall Verdict` 为 Approved，解析 `R`、`F` 与 `审查快照树` / `Reviewed Snapshot Tree`（`T`）
 - 暂存明确文件后记录 `pre_head=$(git rev-parse HEAD)`，并以 helper 的 JSON 模式生成当前完整工作区树 `W` 与规范化暂存树 `S`
 - 在 `git commit` 前要求 `pre_head == R && W == T && S == T`；分别运行 helper 的 `compare` 模式生成 worktree/staged 的 added、missing、different 路径诊断
 - 任一条件不满足时进入 `reference/task-status-update.md` 的“场景 4：提交前快照阻断”，不得执行 `git commit`、push、成功状态更新、PR 摘要同步或完成 gate
-- 全部相等并成功提交后，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`
+- 全部相等并成功提交后，由步骤 6 的 `commit-complete` 核心收尾原子写入 `last_reviewed_commit` 与 Commit done；调用方不得手写
 - 不向后扫描更早的 Approved 产物；最高轮 `review-code` 产物是唯一权威来源
 
 ## 5. 推送到已有 PR（按需）
@@ -86,6 +98,8 @@ b. 命中开放 PR -> 推送当前分支：
 
 通过 `agent-infra-internal git-workflow push --input {file}` 逐 ref 普通推送并复核，禁止 force push。
 
+推送成功并完成远端复核后，必须立即按 `reference/commit-orchestration.md` 执行 pushed checkpoint。
+
 c. 安全降级（不阻塞已完成的 `git commit`，仅提示用户）：
    - 平台不可用 / 未认证 / 检测失败 / 未命中开放 PR -> 不推送，继续后续步骤。
    - `git push` 失败（如需 `git pull --rebase`、无 upstream、网络异常）-> 保留本地提交，提示用户手动推送。
@@ -94,6 +108,14 @@ c. 安全降级（不阻塞已完成的 `git commit`，仅提示用户）：
 
 ## 6. 按需更新任务状态
 
+普通 commit/push checkpoint 完成后，先调用核心收尾；它在同一任务锁内写入审查锚点、Commit done 与 orchestration planned bytes，最后删除 intent：
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
+```
+
+失败时保留 intent，输出 `commit-status` 后停止；重跑本技能由开头的 status/recover 路由恢复。调用方不得重复追加 Commit done 或修改 `last_reviewed_commit`。
+
 获取当前时间：
 
 ```bash
@@ -104,7 +126,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，并按 `reference/task-status-update.md` 的已选场景调用统一 helper。
 
-追加 Commit 的 Activity Log，并且只能选择一个下一步分支：
+核心收尾成功后只能选择一个下一步分支：
 - 已有开放 PR 且 push 成功 -> `watch-pr {task-ref}`；该分支优先于最终提交的 `prFlow` 路由
 - push 失败 -> 保持任务 active，只输出推送/同步诊断，不输出 `watch-pr` 或 `complete-task`
 - 最终提交 -> 按 `.agents/.airc.json` 的 `prFlow` 渲染下一步（`disabled` → 单选 `complete-task`；`required` → 单选 `create-pr`；缺省 → 二选一 `create-pr` / `complete-task`），详见 `reference/task-status-update.md` 场景 1
@@ -146,13 +168,7 @@ agent-infra-internal task-verify {task-id} commit.completed --format text
 
 将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
 
-校验通过后，声明编排中的 commit 阶段已完成；无 active orchestration run 时该命令为 no-op，不改变直接提交路径：
-
-```bash
-agent-infra-internal task-orchestration {task-id} stage-completed --agent {standard-agent-token}
-```
-
-命令失败时停止，不得把缺少完整 receipt 生命周期的 run 标记为完成。
+本 gate 只在步骤 6 核心收尾成功后运行；不得把完成校验放在 `commit-complete` 之前。
 
 ## 注意事项
 

package/templates/.agents/skills/commit/reference/commit-orchestration.en.md

@@ -0,0 +1,49 @@
+# Commit Orchestration Coordination
+
+This protocol applies only when `{task-id}` was resolved. A taskless Git-only commit must not read, create, or complete a commit intent.
+
+## Execution source
+
+- Bind `{execution-flag}` to `--orchestrated` only when that literal flag appears in the entry business operands.
+- Every other invocation is standalone. Never infer the source from `orchestration.json`, environment variables, or activity history.
+
+## Begin before side effects
+
+Call `commit-status` whenever the commit skill starts. For `recoverable` / `prepared`, call `commit-recover --agent {standard-agent-token}`; fail closed for every other non-`idle` state. The recovery intent accepts no token, head, or `--orchestrated` flag.
+
+After read-only preparation of status, copyright, message, review snapshot, and push routing, record `baseline_head=$(git rev-parse HEAD)` and run this before any commit, push, success log, or platform success sync:
+
+```bash
+commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head")
+commit_intent_token=$(printf '%s' "$commit_intent_result" | node -e 'let input = ""; process.stdin.on("data", chunk => input += chunk).on("end", () => process.stdout.write(JSON.parse(input).token))')
+```
+
+Set `commit_intent_token` from the one-use `token` in structured output and keep it only in the current process. A failed begin forbids all later side effects.
+
+## Side-effect checkpoints
+
+Immediately after a normal commit succeeds, record its new HEAD:
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-checkpoint --token "$commit_intent_token" --kind committed --head "$new_head"
+```
+
+Immediately after a push succeeds and remote verification completes, record the verified remote/ref/HEAD:
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-checkpoint --token "$commit_intent_token" --kind pushed --head "$pushed_head" --remote "$remote" --ref "$ref"
+```
+
+A push-only path skips the committed checkpoint; its pushed HEAD must equal the begin baseline.
+
+## Completion and recovery
+
+After the committed/pushed checkpoint and before task synchronization or `task-verify commit.completed`, run:
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
+```
+
+- Before the first side effect, abort only while HEAD still equals the baseline by using `commit-abort --token ... --expected-head ...`.
+- After a commit or push, never abort. Retain the intent and use `commit-status` / `commit-recover` for cross-session recovery.
+- Stop when `commit-complete` fails. Do not repeat commit/push or mark a run complete without its full receipt lifecycle.

package/templates/.agents/skills/commit/reference/commit-orchestration.zh-CN.md

@@ -0,0 +1,55 @@
+# Commit 编排协调
+
+本规则仅适用于已解析出 `{task-id}` 的提交。无任务上下文的纯 Git 提交不得读取、创建或完成 commit intent。
+
+## 执行来源
+
+- 只有入口业务操作数中字面出现 `--orchestrated` 时，`{execution-flag}` 才绑定为 `--orchestrated`。
+- 其他调用一律为 standalone；不得从 `orchestration.json`、环境变量或历史活动日志推断来源。
+
+## 副作用前 begin
+
+每次进入 commit 技能先调用 `commit-status`。`recoverable` / `prepared` 调用以下无 token 恢复入口，其他非 `idle` 状态 fail closed：
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-recover --agent {standard-agent-token}
+```
+
+恢复入口只接受 `--agent`；不得传 token、head 或 `--orchestrated`。recoverable 会幂等补齐 task/run 并最后删除 intent；prepared 仅在 HEAD=baseline 且恰有一个 open Commit started 时安全清理，随后复用该 started 继续正常流程。
+
+完成状态、版权、提交信息、review snapshot 和 push 场景的只读准备后，记录 `baseline_head=$(git rev-parse HEAD)`，并在任何 commit、push、任务成功日志或平台成功同步之前调用：
+
+```bash
+commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head")
+commit_intent_token=$(printf '%s' "$commit_intent_result" | node -e 'let input = ""; process.stdin.on("data", chunk => input += chunk).on("end", () => process.stdout.write(JSON.parse(input).token))')
+```
+
+`commit_intent_token` 只从结构化输出读取一次性 `token`，并仅保存在当前进程内。begin 失败时不得执行后续副作用。
+
+## 副作用 checkpoint
+
+普通 commit 成功后立即记录新 HEAD：
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-checkpoint --token "$commit_intent_token" --kind committed --head "$new_head"
+```
+
+push 成功并完成远端复核后立即记录已验证的 remote/ref/HEAD：
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-checkpoint --token "$commit_intent_token" --kind pushed --head "$pushed_head" --remote "$remote" --ref "$ref"
+```
+
+push-only 路径跳过 committed checkpoint，pushed HEAD 必须等于 begin 时的 baseline HEAD。
+
+## 完成与恢复
+
+committed/pushed checkpoint 完成后、任务同步与 `task-verify commit.completed` 之前调用：
+
+```bash
+agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
+```
+
+- 第一个副作用前失败时，仅可在 HEAD 仍等于 baseline 时调用 `commit-abort --token ... --expected-head ...`。
+- commit 或 push 发生后失败时不得 abort；保留 intent，并调用 `commit-status` 输出不含 token/digest 的恢复证据。跨会话重跑通过 `commit-recover` 收尾。
+- `commit-complete` 失败时停止。不得重复执行 commit/push，也不得把缺少完整 receipt 生命周期的 run 标记为完成。

package/templates/.agents/skills/commit/reference/task-status-update.en.md

@@ -12,23 +12,23 @@ Get the current time first:
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-For every task-related commit, append this Activity Log entry in `task.md`:
+The `commit-complete` / `commit-recover` core has already atomically written this Activity Log entry:
 
 ```text
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-If the commit stage confirmed that the highest-round `review-code` artifact is Approved, `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`, also write or refresh after a successful commit:
+When the evidence is satisfied, core also writes or refreshes:
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-This field is the only baseline for the `complete-task` `post-review-commit` gate. When any condition is not met, do not write or advance it.
+This field is the only baseline for the `complete-task` `post-review-commit` gate. The caller must not append Commit done again or write this field directly.
 
 ### Scenario 5: Existing-PR push wrap-up
 
-After a new commit or the restricted push-only path is successfully pushed to an existing open PR, the only next step is to watch required checks for the new head:
+After a new commit or the restricted push-only path is successfully pushed to an existing open PR, the only next step is to watch all checks for the new head:
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}`.
 

package/templates/.agents/skills/commit/reference/task-status-update.zh-CN.md

@@ -12,23 +12,23 @@
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-对于每一次与任务相关的提交，都要在 `task.md` 中追加以下 Activity Log：
+`commit-complete` / `commit-recover` 核心已原子写入以下 Activity Log：
 
 ```text
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-如果提交阶段已确认最高轮 `review-code` 产物 Approved、`pre_head == R`、完整工作区树 `W == T` 且规范化暂存树 `S == T`，成功提交后同时写入或刷新：
+证据满足时核心同时写入或刷新：
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-该字段是 `complete-task` 的 `post-review-commit` gate 唯一 baseline。条件不满足时不要写入或推进该字段。
+该字段是 `complete-task` 的 `post-review-commit` gate 唯一 baseline。调用方只读取核心结果选择后续路由，不得再次追加 Commit done 或手写/推进该字段。
 
 ### 场景 5：已有 PR 推送收尾
 
-新 commit 或受限 push-only 场景成功推送到已有开放 PR 后，唯一下一步是监控新 head 的 required checks：
+新 commit 或受限 push-only 场景成功推送到已有开放 PR 后，唯一下一步是监控新 head 的全部 checks：
 
 使用 `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。