@fitlab-ai/agent-infra 0.8.5 → 0.9.1

package/templates/.agents/skills/complete-manual-validation/config/verify.zh-CN.json

@@ -23,14 +23,12 @@
         "验证详情",
         "PR 摘要同步"
       ],
-      "freshness_minutes": 30,
       "required_patterns": [
         "^\\$ "
       ]
     },
     "activity-log": {
-      "expected_action_pattern": "Complete Manual Validation",
-      "freshness_minutes": 30
+      "expected_action_pattern": "Complete Manual Validation"
     },
     "review-ledger": {
       "stage_scope": ["analysis", "plan", "code"]

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.en.md

@@ -1,60 +1,16 @@
-# PR Summary Manual Validation Update
+# Manual-validation PR Summary Update
 
-Read this file before `complete-manual-validation` updates the PR summary comment.
+Run only for a valid `{task-id}` whose task.md binds a `pr_number`; any user-supplied PR identity must match it.
 
-## Responsibility Boundary
+Follow `.agents/rules/pr-sync.md` for the shared summary structure and failure semantics.
 
-This file only describes PR summary comment updates. The manual-validation artifact schema lives in `reference/report-template.md`.
+1. After the canonical `manual-validation*` artifact is written, run `agent-infra-internal platform-pr summary-context {task-id}`.
+2. Rebuild the summary from canonical inputs and render `### ✅ Manual Validation Passed` with the validation time and explanation.
+3. Write the plain body to a temporary file and run:
 
-## PR Number Resolution
-
-1. Resolve `{task-ref}` to the task directory and read `task.md`.
-2. Prefer `task.md` frontmatter `pr_number`.
-3. If `pr_number` is empty, parse `{pr-ref}` from user input: `#123`, `123`, or a full PR URL.
-4. If `task.md` already has `pr_number` and the user also passed `{pr-ref}`, they must match.
-5. If they differ, fail with `summary failed: pr_number mismatch`. Do not write an artifact or PATCH a comment.
-6. If both are missing, fail with `summary failed: missing pr_number`. Do not write an artifact or PATCH a comment.
-
-## Required Reads
-
-Before remote operations, read:
-- `.agents/rules/issue-sync.md` to resolve upstream repository and permissions.
-- `.agents/rules/pr-sync.md` to reuse the PR summary hidden marker, Issues comments API, and shell safety rules.
-
-## Comment Lookup
-
-Fetch ordinary PR comments with the current platform's Issues comments API. Follow the concrete command pattern in `.agents/rules/pr-sync.md`.
-
-Find the `<!-- sync-pr:{task-id}:summary -->` summary comment. If it is missing, fail with `summary failed: missing sync-pr summary`.
-
-On failure, do not create an ordinary validation comment, do not create a partial summary comment, and do not write a `manual-validation*` artifact.
-
-## Manual Validation Scope Extraction
-
-- If a `### ⚠️ Manual Verification Required` section exists, take that section until the next `### ` heading.
-- If the current summary already says `### ✅ Manual Validation Passed`, allow a new validation artifact round and update the details.
-- If the current summary says `### ✅ No Manual Verification Needed`, stop and report that this PR does not need manual validation; do not mark it as passed.
-
-## Three-Branch Rendering
-
-The updated `{manual-validation-section}` is:
-
-```markdown
-### ✅ Manual Validation Passed
-
-- Validation time: {time}
-- Validation notes: {verification-summary}
+```bash
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --body-file {summary-body-file}
 ```
 
-Later `pr-sync` aggregation renders in this priority order:
-1. latest `manual-validation.md` / `manual-validation-r{N}.md` has a passed verdict -> `### ✅ Manual Validation Passed`
-2. no passed artifact and retained manual-validation items exist -> `### ⚠️ Manual Verification Required`
-3. no passed artifact and no retained manual-validation items -> `### ✅ No Manual Verification Needed`
-
-## PATCH Rules
-
-Update existing comments with Issues comments PATCH and follow the heredoc safety rules in `.agents/rules/pr-sync.md`.
-
-## Result Reporting
-
-Return `summary updated`, `summary skipped (no diff)`, or `summary failed: <reason>`.
+The core owns marker/HEAD wrapping, pagination, and in-place reconciliation. If context says no manual validation is required, stop without marking it passed.

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.zh-CN.md

@@ -1,87 +1,18 @@
 # PR 摘要人工验证更新
 
-在 `complete-manual-validation` 更新 PR 摘要评论前先读取本文件。
+人工验证产物结构见 `reference/report-template.md`。本步骤只在有效 `{task-id}` 且 task.md 已绑定 `pr_number` 时执行；用户另传 PR 身份时必须与绑定值一致。
 
-## 职责边界
+摘要结构与失败语义统一遵循 `.agents/rules/pr-sync.md`。
 
-本文件只描述 PR 摘要评论更新流程。人工验证产物结构见 `reference/report-template.md`。
+1. 在 canonical `manual-validation*` artifact 落盘后，调用 `agent-infra-internal platform-pr summary-context {task-id}`。
+2. 从返回的最新产物重新聚合摘要，将人工校验段渲染为 `### ✅ 人工验证已通过`，写明验证时间和说明。
+3. 把纯正文写入临时文件，调用：
 
-## PR 号解析
-
-1. 从 `{task-ref}` 定位任务目录并读取 `task.md`。
-2. 优先读取 `task.md` frontmatter 的 `pr_number`。
-3. 如果 `pr_number` 为空，再从用户输入的 `{pr-ref}` 解析：
-   - `#123`
-   - `123`
-   - `{platform-host}/{owner}/{repo}/pull/123`
-4. 如果 `task.md` 已有 `pr_number`，且用户也传入 `{pr-ref}`，两者必须一致。
-5. 两者不一致时失败：`summary failed: pr_number mismatch`。不写 artifact，不 PATCH 评论。
-6. 两者都缺失时失败：`summary failed: missing pr_number`。不写 artifact，不 PATCH 评论。
-
-## 前置读取
-
-执行远端操作前先读取：
-- `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测。
-- `.agents/rules/pr-sync.md`，复用 PR 摘要隐藏标记、Issues comments API 和 Shell 安全规则。
-
-## 评论查找
-
-使用当前平台的 Issues comments API 查询 PR 上的普通评论，具体命令遵循 `.agents/rules/pr-sync.md`。
-
-查找以以下标记开头或包含该标记的评论：
-
-```html
-<!-- sync-pr:{task-id}:summary -->
-```
-
-找不到时失败：
-
-```text
-summary failed: missing sync-pr summary
-```
-
-失败时不创建普通验证留言，不创建部分摘要评论，不写 `manual-validation*` artifact。
-
-## 待人工校验范围提取
-
-从当前摘要评论中提取人工校验范围：
-- 如果存在 `### ⚠️ 需人工校验` 段，取该段到下一个 `### ` heading 之前的内容。
-- 如果当前摘要已是 `### ✅ 人工验证已通过`，允许再次写入新一轮验证产物并更新详情。
-- 如果当前摘要是 `### ✅ 无需人工校验`，停止并提示当前 PR 无需人工校验；不误标为人工验证已通过。
-
-## 三分支渲染
-
-更新后的 `{manual-validation-section}` 为：
-
-```markdown
-### ✅ 人工验证已通过
-
-- 验证时间：{time}
-- 验证说明：{verification-summary}
+```bash
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --body-file {summary-body-file}
 ```
 
-后续 `pr-sync` 聚合时按以下优先级渲染：
-1. 最新 `manual-validation.md` / `manual-validation-r{N}.md` 结论为通过 -> `### ✅ 人工验证已通过`
-2. 没有通过产物且仍有保留人工校验项 -> `### ⚠️ 需人工校验`
-3. 没有通过产物且无保留人工校验项 -> `### ✅ 无需人工校验`
-
-## PATCH 规则
-
-更新已有评论时必须使用 Issues comments PATCH，具体命令遵循 `.agents/rules/pr-sync.md`。
-
-Shell 安全规则：
-- 先读取本地和远端正文，再构造完整正文。
-- heredoc 使用单引号 `<<'EOF'`。
-- 不在 heredoc 内执行变量展开或命令替换。
-- 构造含 `<!-- -->` 的正文时不用 `echo`。
-
-## 结果回传
+marker、当前 HEAD、分页查找和原地更新由 core 负责。若当前 context 表明无需人工校验，则停止并返回 `summary failed: no manual validation required`，不误标通过。
 
-返回以下结果之一：
-- `summary updated`
-- `summary skipped (no diff)`
-- `summary failed: missing pr_number`
-- `summary failed: pr_number mismatch`
-- `summary failed: missing sync-pr summary`
-- `summary failed: no manual validation required`
-- `summary failed: <reason>`
+结果回传：`summary updated`、`summary skipped (no diff)` 或 `summary failed: <reason>`。

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

@@ -3,6 +3,7 @@ name: complete-task
 description: >
   Mark a task as completed and archive it.
   Use when a task's work is done and verified and you want to close and archive it.
+  Only invoke this skill automatically when the conversation includes a resolvable task reference.
 ---
 
 # Complete Task
@@ -21,26 +22,20 @@ After loading workflow / skill / rules instructions, and before any task-state j
 Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
 
 ```bash
-git status -s
-ls -la .agents/workspace/active/{task-id}/
-tail .agents/workspace/active/{task-id}/task.md
+agent-infra-internal task-snapshot {task-id} --format text
 ```
 
 Before the state check is complete, do not make external-state assertions such as "the code is unchanged", "tests passed", or "there are no other references", including in reasoning. This gate is only a structural floor; evidence pairing and authenticity still require the report template and review discipline.
 
-## Task id short ref
+## Task Context Resolution
 
-> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
 
-## Step Start: Write the started Marker
+> Resolve the task reference, then confirm that the task is in a state or directory supported by this skill and that `task.md` exists; if it cannot be located, handle it as a missing task and stop.
 
-After confirming the task exists and before this round's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this round's done entry plus a ` [started]` suffix, note `started`):
+## Step Start: Local Lifecycle Boundary
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task [started]** by {agent} — started
-```
-
-`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+On the normal path, complete business updates, platform sync, and the pre-completion gate while the task is active. Only then may the lifecycle intent in Step 6 atomically commit base terminal fields, the started/done pair, the directory move, and short-id release. Do not write those mechanical fields first. An archived task may only enter `finalization-retry`; do not move it back or rerun lifecycle.
 
 ## Steps
 
@@ -51,9 +46,12 @@ Check that the task exists in `.agents/workspace/active/{task-id}/`.
 Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, e.g. `TASK-20260306-143022`
 
 If not found in `active/`, check `blocked/` and `completed/`:
-- If in `completed/`: Inform user the task is already completed
+- If in `completed/` and task.md has a matching Complete Task Activity Log entry: enter Scenario B `finalization-retry`, skip Steps 2-6, and proceed to Step 7
+- If in `completed/` without a matching entry: report the incomplete terminal identity and stop without hand-repairing it
 - If in `blocked/`: Inform user the task is blocked; suggest unblocking first
 
+Scenario A is the normal active-task path. Scenario B `finalization-retry` retries only the archived task comment and terminal gate.
+
 ### 2. Verify Completion Prerequisites (Failure Must Stop)
 
 **Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow), and `pr_status` from `task.md` frontmatter (`pending` / `created` / `skipped`).
@@ -89,16 +87,7 @@ Before marking complete, verify ALL of these:
 - [ ] Code has been reviewed (`review-code.md` or `review-code-r{N}.md` exists, and the latest review verdict is Approved; or review was done externally)
 - [ ] Code has been committed (no uncommitted changes related to this task)
 - [ ] Tests are passing
-- [ ] The disagreement ledger has no unclosed disagreements and there are no un-re-reviewed post-review commits (mechanically checked by the "Pre-completion hard gate" below)
-
-**Pre-completion hard gate (run BEFORE moving the directory or releasing the short id)**: the Step 7 `gate complete-task` runs only after the directory has been `mv`-ed to `completed/` and the short id released; to avoid a gate failure occurring after those irreversible operations, run the two new completion gates on the **active directory** first:
-
-```bash
-node .agents/scripts/validate-artifact.js check review-ledger .agents/workspace/active/{task-id} --skill complete-task --format text
-node .agents/scripts/validate-artifact.js check post-review-commit .agents/workspace/active/{task-id} --skill complete-task --format text
-```
-
-A non-zero exit from either (fail/blocked) -> treat as an unmet prerequisite and **stop**, do not run Steps 3-7. If the output contains `reviewed snapshot was not anchored`, rerun `commit` or `review-code`; never fall back to the review baseline. `--force` does **NOT** lift this hard gate: unclosed disagreements must first be closed in the ledger (`confirmed`/`closed`/`human-decided`), and un-re-reviewed commits after an anchor must be re-reviewed via `review-code` or covered by a `post-review-commit` / `human-decided` exemption row in the ledger.
+- [ ] The disagreement ledger has no unclosed disagreements or un-re-reviewed post-review commits; local HEAD, `last_reviewed_commit`, and PR head either match strictly or a merged squash has complete platform identity, Git topology, and content-equivalence evidence
 
 > **⚠️ Prerequisite Branch Check — you must decide whether to continue or stop before proceeding:**
 >
@@ -106,7 +95,7 @@ A non-zero exit from either (fail/blocked) -> treat as an unmet prerequisite and
 > - If any condition is missing -> **stop by default** and output the prerequisite warning
 > - Only continue with unmet prerequisites when the user explicitly requested `--force`
 >
-> **Do not continue to Steps 3-7 when prerequisites are not met, and do not output "Task {task-id} completed; task directory moved to completed/."**
+> **Do not continue to Steps 3-8 when prerequisites are not met, and do not output "Task {task-id} completed; task directory moved to completed/."**
 
 If any prerequisite is not met, warn the user:
 ```
@@ -116,78 +105,85 @@ Cannot complete task {task-id} - prerequisites not met:
 Please complete the missing steps first, or use --force to override.
 ```
 
-If prerequisites are not met and the user did not explicitly provide `--force`, stop immediately and do not execute Steps 3-7.
-
-### 3. Update Task Metadata
+If prerequisites are not met and the user did not explicitly provide `--force`, stop immediately and do not execute Steps 3-8.
 
-Get the current time:
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
+### 3. Complete Business-Only Content
 
-Update `.agents/workspace/active/{task-id}/task.md`:
-- `status`: completed
-- `current_step`: completed
-- `completed_at`: {current timestamp}
-- `target_date`: write the date portion (`YYYY-MM-DD`) of `completed_at` only when empty; keep any existing (human-entered) value
-- `updated_at`: {current timestamp}
-- `agent_infra_version`: value from `.agents/rules/version-stamp.md`
+Update only content that the lifecycle core does not own:
 - Add or update the `## State Check` section with the raw Step 0 audit command output, including `$ ` prompt lines, before `## Activity Log`
 - Mark all workflow steps as complete
 - Verify and check off all items in `## Completion Checklist` (change `- [ ]` to `- [x]`)
-- **Append** to `## Activity Log` (do NOT overwrite previous entries):
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task** by {agent} — Task moved to completed/
-  ```
 
-### 4. Move Task
+Do not write `status/current_step/completed_at/updated_at/agent_infra_version`, the base Activity Log pair, the directory move, or short-id state here. Step 6 owns them.
+
+### 4. Sync the Platform While Active
+
+Check whether task.md has a valid `issue_number`. If it does not, skip this step without output.
+
+> Issue metadata boundaries live in `.agents/rules/issue-sync.md`; comments use internal platform intents.
 
-Move the task directory from active to completed:
+When an `issue_number` exists, execute in this exact order:
+
+1. In artifact-catalog order, run `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {artifact-agent} --backfill` for every local artifact.
+2. Run `agent-infra-internal platform-issue sync {task-id} --agent {agent} --requirements --fields`.
+3. Write the business summary to a temporary file and run `agent-infra-internal platform-comment sync {task-id} --kind summary --body-file {path} --agent {agent}`.
+
+Do not sync the task comment here; it requires the terminal task.md written by lifecycle. Do not set a `status:` label; platform automation clears status labels after the Issue closes.
+
+If any operation fails, the task must remain active and its short id must remain valid. Record the failure with the matching structured warning intent, then stop without entering Step 5:
 
 ```bash
-mv .agents/workspace/active/{task-id} .agents/workspace/completed/{task-id}
+agent-infra-internal task-warning {task-id} add --step complete-task --severity ACTION_REQUIRED --code {COMMENT_SYNC_FAILED|REQUIREMENTS_SYNC_FAILED|SUMMARY_SYNC_FAILED|NETWORK_RETRY_EXHAUSTED} --target {artifact|issue|summary|platform} --message "{error_code}: {error_message}" --action "Fix the platform sync problem and rerun complete-task"
 ```
 
-### 5. Verify Move
+The core deduplicates the stable `step/code/target` tuple. Callers must not allocate warning ids or edit ledger rows.
+
+### 5. Run the Active Pre-completion Hard Gate
+
+After platform writes succeed and before moving the directory or releasing the short id, run:
 
 ```bash
-ls .agents/workspace/completed/{task-id}/task.md
+agent-infra-internal task-verify {task-id} complete-task.preflight --format text
 ```
 
-Confirm the task directory was successfully moved.
+This event runs `review-ledger`, `post-review-commit`, then `platform-sync-preflight`. On any non-zero exit (fail/blocked), keep the task active, derive the stable code/target from the gate result, record it through `task-warning ... add --step complete-task ...`, and stop. For a review/head mismatch, rerun `commit` or `review-code`; never fall back to the review baseline.
+
+`--force` does not lift this hard gate: close ledger disagreements; re-review or exempt post-review commits, or prove a content-equivalent single-parent squash merge from the bound PR snapshot and local Git objects; then pass platform preflight. Missing platform facts, Git objects, topology, or content evidence fails closed. Required checks remain enforced before merge by branch protection / rulesets and the `review-code` / `watch-pr` routes.
 
-### 6. Sync to Issue
+### 6. Apply the Local Lifecycle Intent and Verify the Move
 
-Check whether `task.md` includes a valid `issue_number`. If not, skip this step and output nothing.
+```bash
+agent-infra-internal task-lifecycle {task-id} complete --agent {agent}
+```
 
-> Issue sync rules live in `.agents/rules/issue-sync.md`. Read that file before syncing, and complete upstream repository detection plus permission detection.
+Only `status=applied|no-op` means local completion succeeded. On `status=failed`, show the structured error and recovery steps and retry the same intent; do not claim completion or hand-repair partial state.
+
+```bash
+ls .agents/workspace/completed/{task-id}/task.md
+```
 
-If a valid `issue_number` exists:
-- First scan and backfill unpublished `task.md`, `analysis*.md`, `review-analysis*.md`, `plan*.md`, `review-plan*.md`, `code*.md`, and `review-code*.md` comments using the backfill rules in `.agents/rules/issue-sync.md` (`task.md` uses the idempotent update path)
-- Backfill checked `## Requirements` items to the Issue body by following the requirements-checkbox sync steps in issue-sync.md
-- Do not set any `status:` label — platform automation should clear status labels after the Issue closes; the pre-completion platform-sync gate verifies that a CLOSED Issue has no `status:` labels and fails until the workflow finishes or is repaired
-- Finally create or update the summary comment marked with the summary marker defined in `.agents/rules/issue-sync.md`
-- Read `.agents/rules/issue-fields.md` and follow Flow A to sync every non-empty Issue field (`priority`/`effort`/`start_date`/`target_date`) from `task.md` to the Issue (idempotent; skip without blocking when `has_push=false` or the fetch/write fails)
+Confirm the task directory was successfully moved.
 
-### 7. Verification Gate
+### 7. Sync the Terminal Task Comment and Run the Gate
 
-**Release short id** (after the directory has already been moved; the script is idempotent and returns 0 even if the task isn't registered):
+Both Scenario A and Scenario B `finalization-retry` execute this step from the completed directory. If a valid `issue_number` exists, first run:
 
 ```bash
-node .agents/scripts/task-short-id.js release "$task_id" || true
+agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}
 ```
 
+If this call fails, the task is already archived and `task-warning` cannot accept it. Keep the task completed and stop. After fixing the network or platform issue, rerun complete-task; Step 1 will enter `finalization-retry` and repeat only this step.
+
 Run the verification gate to confirm the task artifact and sync state are valid:
 
 ```bash
-node .agents/scripts/validate-artifact.js gate complete-task .agents/workspace/completed/{task-id} --format text
+agent-infra-internal task-verify {task-id} complete-task.completed --format text
 ```
 
 Handle the result as follows:
 - exit code 0 (all checks passed) -> continue to the "Inform User" step
 - exit code 1 (validation failed) -> fix the reported issues and run the gate again
-- exit code 2 (network blocked) -> stop and tell the user that human intervention is required
+- exit code 2 (network blocked or status-label cleanup is still pending) -> keep the task completed and stop; rerun complete-task later to enter `finalization-retry`
 
 Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
 

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

@@ -3,6 +3,7 @@ name: complete-task
 description: >
   标记任务完成并归档。
   当任务工作已完成并验证、需要收尾归档时使用。
+  仅当对话包含可解析的任务引用时才可自动调用本技能。
 ---
 
 # 完成任务
@@ -21,26 +22,20 @@ description: >
 运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
 
 ```bash
-git status -s
-ls -la .agents/workspace/active/{task-id}/
-tail .agents/workspace/active/{task-id}/task.md
+agent-infra-internal task-snapshot {task-id} --format text
 ```
 
 状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。
 
-## 任务入参短号别名
+## 任务上下文解析
 
-> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
-## 步骤开始：写入 started 标记
+> 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
-确认任务存在后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本轮 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+## 步骤开始：本地生命周期边界
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task [started]** by {agent} — started
-```
-
-`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+正常完成路径在 active 阶段完成业务更新、平台同步和预完成门禁后，才由步骤 6 的单次 lifecycle intent 原子完成基础终态字段、started/done 日志、目录转移和短号释放；不得提前手工写入这些机械状态。已归档任务只允许进入 `finalization-retry` 场景，不回迁目录或重新执行 lifecycle。
 
 ## 执行步骤
 ### 1. 验证任务存在
@@ -50,9 +45,12 @@ tail .agents/workspace/active/{task-id}/task.md
 注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
 
 如果在 `active/` 中未找到，检查 `blocked/` 和 `completed/`：
-- 如果在 `completed/`：告知用户任务已完成
+- 如果在 `completed/` 且 task.md 存在匹配的 Complete Task Activity Log：进入场景 B `finalization-retry`，跳过步骤 2-6，直接执行步骤 7
+- 如果在 `completed/` 但缺少匹配日志：告知用户任务已完成但终态身份不完整并停止，不手工修补
 - 如果在 `blocked/`：告知用户任务被阻塞；建议先解除阻塞
 
+场景 A 为 active 任务的正常完成路径；场景 B `finalization-retry` 只重试归档后的 task 评论与终态门禁。
+
 ### 2. 验证完成前置条件（未满足则必须停止）
 
 **门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR），以及 `task.md` frontmatter 的 `pr_status`（`pending` / `created` / `skipped`）。
@@ -88,16 +86,7 @@ tail .agents/workspace/active/{task-id}/task.md
 - [ ] 代码已审查（`review-code.md` 或 `review-code-r{N}.md` 存在，且最新审查结论为 Approved；或已在外部完成审查）
 - [ ] 代码已提交（没有与此任务相关的未提交变更）
 - [ ] 测试通过
-- [ ] 审查分歧账本无未关闭分歧，且无未复审的 post-review 提交（由下方「预完成硬门禁」机械校验）
-
-**预完成硬门禁（在移动目录、释放短号之前运行）**：步骤 7 的 `gate complete-task` 在目录已 `mv` 到 `completed/`、短号已释放之后才运行；为避免门禁失败发生在不可逆操作之后，必须在 **active 目录**上预先运行新增的两项完成门禁：
-
-```bash
-node .agents/scripts/validate-artifact.js check review-ledger .agents/workspace/active/{task-id} --skill complete-task --format text
-node .agents/scripts/validate-artifact.js check post-review-commit .agents/workspace/active/{task-id} --skill complete-task --format text
-```
-
-任一退出码非 0（fail/blocked）→ 按前置条件未满足处理，**停止**，不执行步骤 3-7。若输出包含 `reviewed snapshot was not anchored`，必须先重新 `commit` 或 `review-code`；不得回退审查基线。`--force` **不解除**本硬门禁：未关闭分歧必须先在账本闭合（`confirmed`/`closed`/`human-decided`），已锚点后的未复审提交必须重新 `review-code` 或在账本追加 `post-review-commit` / `human-decided` 豁免行。
+- [ ] 审查分歧账本无未关闭分歧、无未复审的 post-review 提交；本地 HEAD、`last_reviewed_commit`、PR head 严格一致，或已合并 squash 的平台身份、Git 拓扑与内容等价证据完整
 
 > **⚠️ 前置条件分支判断 — 你必须先判断“继续”还是“停止”：**
 >
@@ -105,7 +94,7 @@ node .agents/scripts/validate-artifact.js check post-review-commit .agents/works
 > - 如果任意一个条件不满足 → **默认停止**，输出前置条件未满足的警告
 > - 只有用户明确要求 `--force` 时，才可以在前置条件未满足时继续
 >
-> **禁止在前置条件未满足时继续执行步骤 3-7，也不要输出「任务 {task-id} 已完成，任务目录已转移到 completed/。」**
+> **禁止在前置条件未满足时继续执行步骤 3-8，也不要输出「任务 {task-id} 已完成，任务目录已转移到 completed/。」**
 
 如果任何前置条件未满足，警告用户：
 ```
@@ -115,78 +104,85 @@ Cannot complete task {task-id} - prerequisites not met:
 Please complete the missing steps first, or use --force to override.
 ```
 
-如果前置条件未满足且用户未明确提供 `--force`，立即停止，不执行步骤 3-7。
-
-### 3. 更新任务元数据
+如果前置条件未满足且用户未明确提供 `--force`，立即停止，不执行步骤 3-8。
 
-获取当前时间：
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
+### 3. 完成业务内容更新
 
-更新 `.agents/workspace/active/{task-id}/task.md`：
-- `status`：completed
-- `current_step`：completed
-- `completed_at`：{当前时间戳}
-- `target_date`：仅当为空时写入 `completed_at` 的日期部分（`YYYY-MM-DD`）；已有值（人工填写）则保留
-- `updated_at`：{当前时间戳}
-- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
+在 `.agents/workspace/active/{task-id}/task.md` 中只更新生命周期核心不负责的业务内容：
 - 新增或更新 `## 状态核对` 段，粘贴第 0 步审计命令原文（含 `$ ` 前缀行），放在 `## 活动日志` 之前
 - 标记所有工作流步骤为已完成
 - 逐项验证并勾选 `## 完成检查清单` 中的所有条目（将 `- [ ]` 改为 `- [x]`）
-- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task** by {agent} — Task moved to completed/
-  ```
 
-### 4. 转移任务
+不得在本步骤写 `status/current_step/completed_at/updated_at/agent_infra_version`、基础 Activity Log、目录或短号；这些由步骤 6 统一提交。
+
+### 4. 在 active 阶段同步平台
+
+检查 `task.md` 中是否存在有效的 `issue_number`。如果没有，跳过本步骤且不输出任何内容。
+
+> Issue 元数据边界见 `.agents/rules/issue-sync.md`；评论同步统一调用 internal platform intent。
 
-将任务目录从 active 移动到 completed：
+如果存在有效的 `issue_number`，严格按以下顺序执行：
+
+1. 按 artifact catalog 顺序，对本地已有产物逐项调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {artifact-agent} --backfill`。
+2. 调用 `agent-infra-internal platform-issue sync {task-id} --agent {agent} --requirements --fields`。
+3. 把业务摘要写入临时文件，并调用 `agent-infra-internal platform-comment sync {task-id} --kind summary --body-file {path} --agent {agent}`。
+
+不要在本步骤同步 task 评论；它依赖 lifecycle 写入后的完整终态 task.md。不要设置 `status:` label，平台自动化应在 Issue 关闭后清理状态标签。
+
+任一操作失败时，任务仍必须位于 active 且短号仍有效；先按失败类型调用以下结构化 warning intent，再立即停止，不进入步骤 5：
 
 ```bash
-mv .agents/workspace/active/{task-id} .agents/workspace/completed/{task-id}
+agent-infra-internal task-warning {task-id} add --step complete-task --severity ACTION_REQUIRED --code {COMMENT_SYNC_FAILED|REQUIREMENTS_SYNC_FAILED|SUMMARY_SYNC_FAILED|NETWORK_RETRY_EXHAUSTED} --target {artifact|issue|summary|platform} --message "{error_code}: {error_message}" --action "修复平台同步问题后重跑 complete-task"
 ```
 
-### 5. 验证转移
+相同 `step/code/target` 组合由核心幂等去重；调用方不分配 warning id 或手写账本行。
+
+### 5. 运行 active 预完成硬门禁
+
+平台写入成功后、移动目录和释放短号之前运行：
 
 ```bash
-ls .agents/workspace/completed/{task-id}/task.md
+agent-infra-internal task-verify {task-id} complete-task.preflight --format text
 ```
 
-确认任务目录已成功移动。
+该事件依次执行 `review-ledger`、`post-review-commit`、`platform-sync-preflight`。任一退出码非 0（fail/blocked）时，任务必须继续留在 active；从 gate 结果取稳定 code/target，通过 `task-warning ... add --step complete-task ...` 落账后停止。若审查基线或 head 不一致，必须先重新 `commit` / `review-code`；不得回退审查基线。
+
+`--force` 不解除本硬门禁：未关闭分歧必须先在账本闭合，未复审提交必须重新审查、具备有效豁免，或由绑定 PR 的权威合并快照与本地 Git 对象证明为内容等价的单父 squash merge；平台 preflight 必须通过。平台事实、Git 对象、拓扑或内容证据缺失时 fail closed。required checks 由合并前的分支保护 / ruleset 以及 `review-code` / `watch-pr` 路由承担。
 
-### 6. 同步到 Issue
+### 6. 执行本地生命周期意图并验证转移
 
-检查 `task.md` 中是否存在有效的 `issue_number`。如果没有，跳过此步骤且不输出任何内容。
+```bash
+agent-infra-internal task-lifecycle {task-id} complete --agent {agent}
+```
 
-> Issue 同步规则见 `.agents/rules/issue-sync.md`。执行同步前先读取该文件，完成 upstream 仓库检测和权限检测。
+仅 `status=applied|no-op` 视为本地完成。`status=failed` 时展示 `error` 与 completed/pending steps，以同一 intent 重试；不得宣称完成或手工补写局部状态。
+
+```bash
+ls .agents/workspace/completed/{task-id}/task.md
+```
 
-如果存在有效的 `issue_number`：
-- 先按 `.agents/rules/issue-sync.md` 的补发规则扫描并补发未发布的 `task.md`、`analysis*.md`、`review-analysis*.md`、`plan*.md`、`review-plan*.md`、`code*.md`、`review-code*.md` 评论（`task.md` 走幂等更新路径）
-- 按 issue-sync.md 的需求复选框同步步骤，兜底同步 `## 需求` 中已勾选的条目到 Issue body
-- 不要设置 `status:` label — 平台自动化应在 Issue 关闭后清理状态标签；预完成 platform-sync gate 会验证 CLOSED Issue 不含任何 `status:` 标签，残留时失败并要求等待或修复 workflow 后重跑
-- 最后创建或更新 `.agents/rules/issue-sync.md` 中定义的 summary 评论标记对应的 summary 评论
-- 读取 `.agents/rules/issue-fields.md`，按流程 A 把 `task.md` 中所有非空的 Issue 字段（`priority`/`effort`/`start_date`/`target_date`）同步到 Issue（幂等；`has_push=false` 或取数/写入失败时跳过，不阻断）
+确认任务目录已成功移动。
 
-### 7. 完成校验
+### 7. 同步终态 task 评论并完成校验
 
-**释放短号**（先 `mv` 目录已成功，再 release；脚本幂等，未在注册表也返回 0）：
+场景 A 与场景 B `finalization-retry` 都从 completed 目录执行本步骤。若存在有效的 `issue_number`，先调用：
 
 ```bash
-node .agents/scripts/task-short-id.js release "$task_id" || true
+agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}
 ```
 
+该调用失败时任务已归档，不能调用只接受 active 任务的 `task-warning`；保留 completed 状态并停止。修复网络或平台问题后重跑 complete-task，会由步骤 1 进入 `finalization-retry`，只重复本步骤。
+
 运行完成校验，确认任务产物和同步状态符合规范：
 
 ```bash
-node .agents/scripts/validate-artifact.js gate complete-task .agents/workspace/completed/{task-id} --format text
+agent-infra-internal task-verify {task-id} complete-task.completed --format text
 ```
 
 处理结果：
 - 退出码 0（全部通过）-> 继续到「告知用户」步骤
 - 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
-- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+- 退出码 2（网络中断或状态标签清理尚未收敛）-> 保留 completed 状态并停止；稍后重跑 complete-task 进入 `finalization-retry`
 
 将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。