@fitlab-ai/agent-infra 0.8.4 → 0.9.0

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

@@ -3,6 +3,7 @@ name: complete-manual-validation
 description: >
   标记 PR 人工验证已完成，并原地更新 PR 摘要评论中的人工校验段落。
   当维护者已完成真实环境或权限相关人工验证、需要统一收尾 PR 摘要时使用。
+  仅当对话包含可解析的任务引用时才可自动调用本技能。
 ---
 
 # 完成人工验证
@@ -23,24 +24,18 @@ 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 标记：
+## 步骤开始：声明 started 事件
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation [started]** by {agent} — started
-```
-
-格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+确认前置条件和产物上下文后、本轮第一个产出动作之前执行 `agent-infra-internal task-event {task-id} manual-validation.started --agent {agent}`，并以返回的 `artifactContext` 记录本轮身份。
 
 ## 执行步骤
 
@@ -64,12 +59,9 @@ complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
 
 如果任务不存在、验证说明缺失，或无法解析有效 PR，立即停止。
 
-### 3. 确定产物轮次
+### 3. 解析产物上下文
 
-扫描任务目录：
-- 不存在 `manual-validation.md` 且不存在 `manual-validation-r*.md` -> 本轮产物为 `manual-validation.md`
-- 已存在 `manual-validation.md` 且不存在 `manual-validation-r*.md` -> 本轮产物为 `manual-validation-r2.md`
-- 已存在 `manual-validation-r{N}.md` -> 本轮产物为 `manual-validation-r{N+1}.md`
+运行 `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`。仅当结果为 `ready` 时继续；从 `next.round` / `next.name` 取得本轮 round 与 `{manual-validation-artifact}`。不得自行扫描轮次或拼装文件名。随后执行 started 事件并复核返回身份。
 
 ### 4. 更新 PR 摘要
 
@@ -78,7 +70,7 @@ complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
 - `.agents/rules/pr-sync.md`
 - `reference/summary-update.md`
 
-按 `reference/summary-update.md` 解析 PR 号、查找 `sync-pr` 摘要评论、提取待人工校验范围，并把人工校验段落更新为 `### ✅ 人工验证已通过`。
+按 `reference/summary-update.md` 校验 PR 绑定，从 `platform-pr summary-context` 取得 canonical 输入，并通过 `platform-pr summary-sync` 把人工校验段更新为 `### ✅ 人工验证已通过`。
 
 ### 5. 创建人工验证产物
 
@@ -91,31 +83,16 @@ complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
 
 ### 6. 更新 task.md
 
-获取当前时间：
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
-
-更新 `.agents/workspace/active/{task-id}/task.md`：
-- `updated_at`：{当前时间}
-- `assigned_to`：{当前代理}
-- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
-- 保持 `current_step` 不变
-- 在 `## 实现备注` 中追加 `{manual-validation-artifact}` 链接和 PR 摘要同步结果
-- 追加 Activity Log：
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation** by {agent} — Manual validation passed → {manual-validation-artifact}; {summary-result}
-  ```
+执行 `agent-infra-internal task-event {task-id} manual-validation.completed --agent {agent} --artifact {manual-validation-artifact} --summary-result "{summary-result}"`，由核心在保持 `current_step` 不变的同时原子登记实现备注链接、时间/版本和完成日志。
 
-如任务存在有效 `issue_number`，按 `.agents/rules/issue-sync.md` 更新 task 评论并发布 `{manual-validation-artifact}` 评论。
+如任务存在有效 `issue_number`，调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`，再调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {manual-validation-artifact} --agent {agent}`。
 
 ### 7. 完成校验
 
 运行完成校验：
 
 ```bash
-node .agents/scripts/validate-artifact.js gate complete-manual-validation .agents/workspace/active/{task-id} {manual-validation-artifact} --format text
+agent-infra-internal task-verify {task-id} manual-validation.completed --artifact {manual-validation-artifact} --format text
 ```
 
 处理结果：

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

@@ -23,14 +23,12 @@
         "Validation Details",
         "PR Summary Sync"
       ],
-      "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/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. `--force` does **NOT** lift this hard gate: unclosed disagreements must first be closed in the ledger (`confirmed`/`closed`/`human-decided`), and un-re-reviewed post-review commits 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, there are no un-re-reviewed post-review commits, and local HEAD, `last_reviewed_commit`, and PR head match under the latest required-checks snapshot (mechanically checked below)
 
 > **⚠️ 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`, `required-checks`, 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`; for pending/failed/cancelled checks, run `watch-pr`; never fall back to the review baseline.
+
+`--force` does not lift this hard gate: close ledger disagreements, re-review or exempt post-review commits, pass required-checks with three-way head alignment, and pass platform preflight first.
 
-### 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 — status labels are automatically cleared when the Issue is closed
-- 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.