@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/task/verification-types.ts

@@ -1,3 +1,20 @@
+import type fs from 'node:fs';
+
+export type VerificationShared = {
+  repoRoot: string;
+  loadTask: (taskDir: string) => { ok: true; content: string; metadata: Record<string, string> } | { ok: false; message: string };
+  getCheckedRequirements: (content: string) => string[];
+  normalizeContent: (text: unknown) => string;
+  isBlank: (value: unknown) => boolean;
+  escapeRegExp: (value: string) => string;
+  passResult: (type: string, message: string, warnings?: string[]) => VerificationCheckResult;
+  failResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
+  blockedResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
+  safeStat: (filePath: string) => fs.Stats | null;
+  parseIssueNumber: (value: unknown) => number | null;
+  parsePrNumber: (value: unknown) => number | null;
+};
+
 type VerificationStatus = 'pass' | 'fail' | 'blocked';
 type VerificationCheckResult = {
   type: string;

package/lib/task/verification.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 // checks are provided by typed domain modules without a stdout protocol.
 import { verifyInProcess } from './verification-engine.ts';
 
-import { parseArtifactName } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import type { ArtifactFamily } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { TaskWorkspaceState } from './resolve-ref.ts';

package/lib/task/workflow-command.ts

@@ -0,0 +1,18 @@
+export const TASK_WORKFLOW_COMMANDS = Object.freeze({
+  'artifact-inspect': ['task-artifact', 'inspect'],
+  'artifact-init': ['task-artifact', 'init'],
+  'artifact-repair': ['task-artifact', 'repair'],
+  'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+  'review-finalize-summary': ['task-review', 'finalize-summary'],
+  event: ['task-event', null],
+  'ledger-finding-response': ['task-ledger', 'finding-respond'],
+  'ledger-finding-review': ['task-ledger', 'finding-review'],
+  'ledger-finding-upsert': ['task-ledger', 'finding-upsert'],
+  'decision-next-id': ['task-ledger', 'decision-next-id'],
+  'decision-upsert': ['task-ledger', 'decision-upsert'],
+  'invalidation-reconcile': ['task-invalidation', 'reconcile'],
+  'warning-add': ['task-warning', 'add']
+} as const);
+export type TaskWorkflowOperation = keyof typeof TASK_WORKFLOW_COMMANDS;
+export const TASK_WORKFLOW_OPERATIONS = Object.freeze(Object.keys(TASK_WORKFLOW_COMMANDS) as TaskWorkflowOperation[]);
+export type WorkflowCommand = typeof TASK_WORKFLOW_COMMANDS[TaskWorkflowOperation][0];

package/lib/task/workflow-warning-intents.ts

@@ -52,17 +52,6 @@ function nextWarningId(rows: readonly WorkflowWarning[]): string {
   return `WW-${max + 1}`;
 }
 
-function validateRows(rows: readonly WorkflowWarning[]): { code: string; message: string } | null {
-  const ids = new Set<string>();
-  for (const row of rows) {
-    if (!/^WW-[1-9]\d*$/.test(row.id)) return { code: 'WARNING_ID_INVALID', message: `warning id '${row.id}' is invalid` };
-    if (ids.has(row.id)) return { code: 'WARNING_DUPLICATE_ID', message: `duplicate warning id '${row.id}'` };
-    ids.add(row.id);
-    if (!WORKFLOW_WARNING_SEVERITIES.has(row.severity) || !WORKFLOW_WARNING_STATUSES.has(row.status)) return { code: 'WARNING_DOCUMENT_INVALID', message: `warning '${row.id}' has invalid severity or status` };
-  }
-  return null;
-}
-
 function sectionMutation(content: string): TaskMutation[] {
   if (/^##\s+(工作流告警|Workflow Warnings)\s*$/m.test(content)) return [];
   const english = /^##\s+Activity Log\s*$/m.test(content);
@@ -98,8 +87,6 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
     const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : 'WARNING_DOCUMENT_INVALID';
     return failed(intent, code, error instanceof Error ? error.message : String(error), resolved.taskId);
   }
-  const invalid = validateRows(rows);
-  if (invalid) return failed(intent, invalid.code, invalid.message, resolved.taskId);
   if (intent.kind === 'list') {
     if (intent.status && !WORKFLOW_WARNING_STATUSES.has(intent.status)) return failed(intent, 'WARNING_PAYLOAD_INVALID', 'warning status is invalid', resolved.taskId);
     const warnings = rows.filter((row) => !intent.status || row.status === intent.status);

package/lib/task/workflow-warnings.ts

@@ -4,6 +4,7 @@ const WORKFLOW_WARNING_HEADINGS = ['工作流告警', 'Workflow Warnings'];
 const WORKFLOW_WARNING_STATUSES = new Set(['open', 'resolved', 'ignored']);
 const WORKFLOW_WARNING_SEVERITIES = new Set(['IMPORTANT', 'ACTION_REQUIRED']);
 const WORKFLOW_WARNING_COLUMNS = ['id', 'time', 'step', 'severity', 'code', 'status', 'target', 'message', 'action', 'resolved_at', 'resolution'] as const;
+const WARNING_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
 
 type WorkflowWarning = {
   id: string;
@@ -19,14 +20,32 @@ type WorkflowWarning = {
   resolution: string;
 };
 
-/** Parses workflow warning rows and fails closed on malformed table structure. */
+/** Parses warning structure and lifecycle fields using one contract for all readers. */
 function parseWorkflowWarnings(content: string): WorkflowWarning[] {
   const table = parseTable(content, { sectionAliases: WORKFLOW_WARNING_HEADINGS, columns: WORKFLOW_WARNING_COLUMNS });
-  return table?.rows.map(({ values }) => ({
+  const warnings = table?.rows.map(({ values }) => ({
     id: values.id!, time: values.time!, step: values.step!, severity: values.severity!,
     code: values.code!, status: values.status!, target: values.target!, message: values.message!,
     action: values.action!, resolvedAt: values.resolved_at!, resolution: values.resolution!
   })) ?? [];
+  const errors: { code: string; message: string }[] = [];
+  const invalid = (message: string, code = 'WARNING_DOCUMENT_INVALID') => errors.push({ code, message });
+  for (const warning of warnings) {
+    const { id, time, severity, status, action, resolvedAt, resolution } = warning;
+    if (!/^WW-[1-9]\d*$/.test(id)) invalid(`${id || '(empty id)'}: invalid id`, 'WARNING_ID_INVALID');
+    if (!WARNING_TIME_PATTERN.test(time)) invalid(`${id}: invalid time '${time}'`);
+    for (const field of ['step', 'code', 'target', 'message'] as const) {
+      if (!warning[field].trim()) invalid(`${id}: ${field} is required`);
+    }
+    if (!WORKFLOW_WARNING_SEVERITIES.has(severity)) invalid(`${id}: illegal severity '${severity}'`);
+    if (!WORKFLOW_WARNING_STATUSES.has(status)) invalid(`${id}: illegal status '${status}'`);
+    if (status === 'open' && !action.trim()) invalid(`${id}: open warning requires action`);
+    if ((status === 'resolved' || status === 'ignored') && (!resolvedAt.trim() || !resolution.trim())) {
+      invalid(`${id}: ${status} warning requires resolved_at and resolution`);
+    }
+  }
+  if (errors.length) throw Object.assign(new Error(errors.map((error) => error.message).join('; ')), { code: errors[0]!.code });
+  return warnings;
 }
 
 function getOpenWorkflowWarnings(content: string): WorkflowWarning[] {

package/lib/update.ts

@@ -119,6 +119,12 @@ async function cmdSync(): Promise<void> {
     replacements
   );
   ok('Updated .agents/scripts/lib/agent-infra-package.js');
+  renderFile(
+    path.join(templateDir, '.agents', 'scripts', 'package.json'),
+    path.join('.agents', 'scripts', 'package.json'),
+    replacements
+  );
+  ok('Updated .agents/scripts/package.json');
   const added = {
     managed: workflowPlan.projectAssets.registry.managed.filter(
       (entry) => !currentRegistry.managed.includes(entry)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -26,12 +26,13 @@
   "bin": {
     "agent-infra": "./dist/bin/cli.js",
     "ai": "./dist/bin/cli.js",
-    "agent-infra-internal": "./dist/bin/internal-cli.js"
+    "agent-infra-internal": "./bin/internal-cli.sh"
   },
   "files": [
     "dist/",
     "!dist/**/*.map",
     "bin/cli.ts",
+    "bin/internal-cli.sh",
     "lib/",
     "runtime/",
     "templates/"
@@ -54,7 +55,7 @@
     "@clack/prompts": "1.7.0",
     "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
-    "fs-ext-extra-prebuilt": "2.2.13",
+    "fs-native-extensions": "1.5.1",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
     "smol-toml": "^1.6.1",
@@ -67,6 +68,8 @@
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
     "test:smoke": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\"",
     "test:smoke:fast": "node scripts/run-tests.js --skip-build \"tests/unit/**/*.test.ts\"",
+    "test:platform-smoke": "node scripts/run-tests.js \"tests/integration/platform-smoke/**/*.test.ts\"",
+    "test:platform-smoke:fast": "node scripts/run-tests.js --skip-build \"tests/integration/platform-smoke/**/*.test.ts\"",
     "test:core": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
     "test:integration": "node scripts/run-tests.js \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
@@ -85,8 +88,5 @@
   },
   "overrides": {
     "axios": "1.18.1"
-  },
-  "allowScripts": {
-    "fs-ext-extra-prebuilt@2.2.13": true
   }
 }

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -16,7 +16,7 @@ function internalCliInvocation(args) {
   return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
 }
 
-function findCapabilityToken(value, depth = 0) {
+function findCapabilityRef(value, depth = 0) {
   if (depth > 5 || value == null) return '';
   if (typeof value === 'string') {
     const match = /agent-infra-codex-capability:([A-Za-z0-9_-]{20,})/.exec(value);
@@ -24,14 +24,14 @@ function findCapabilityToken(value, depth = 0) {
   }
   if (Array.isArray(value)) {
     for (const entry of value) {
-      const found = findCapabilityToken(entry, depth + 1);
+      const found = findCapabilityRef(entry, depth + 1);
       if (found) return found;
     }
     return '';
   }
   if (typeof value === 'object') {
     for (const entry of Object.values(value)) {
-      const found = findCapabilityToken(entry, depth + 1);
+      const found = findCapabilityRef(entry, depth + 1);
       if (found) return found;
     }
   }
@@ -77,11 +77,11 @@ process.stdin.on('end', () => {
       process.exit(1);
     }
     const managedAgent = /^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''));
-    const capabilityToken = hook === 'post-tool' ? findCapabilityToken(toolResponse) : '';
+    const capabilityRef = hook === 'post-tool' ? findCapabilityRef(toolResponse) : '';
     const parentReconcile = hook === 'post-tool'
       && toolName === 'collaborationwait_agent'
       && toolResponse.timed_out !== true;
-    if (!managedAgent && !parentReconcile && !capabilityToken) process.exit(0);
+    if (!managedAgent && !parentReconcile && !capabilityRef) process.exit(0);
     const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
     const normalized = {
       sessionId: String(event.session_id || ''),
@@ -96,7 +96,7 @@ process.stdin.on('end', () => {
       taskName: String(toolInput.task_name || ''),
       transcriptPath: String(event.transcript_path || '')
     };
-    if (capabilityToken) normalized.capabilityToken = capabilityToken;
+    if (capabilityRef) normalized.capabilityRef = capabilityRef;
     const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
     try {
       const { command, commandArgs, shell } = internalCliInvocation(args);

package/templates/.agents/rules/testing-discipline.en.md

@@ -43,6 +43,8 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 
 Complete each item below for this repository. Record the chosen behavior and its boundaries so contributors can select and validate tests consistently.
 
+When a project uses a cross-platform smoke boundary, keep real CLI, git, shell, environment-forwarding, and process-lifecycle tests outside the unit tier. Document which operating systems execute that boundary and keep structural tier checks separate from line coverage.
+
 ### 1. Test commands
 
 > TODO: Document the complete test command and any faster commands used during development.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -43,6 +43,8 @@ assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 
 请为本仓库填写以下各项，记录选定行为及其边界，以便贡献者一致地选择并验证测试。
 
+如果项目使用跨平台 smoke 边界，应将真实 CLI、git、shell、环境透传和进程生命周期测试放在 unit 层之外；记录该边界运行的操作系统，并将测试层级结构检查与代码行覆盖率分开。
+
 ### 1. 测试命令
 
 > TODO: 记录完整测试命令，以及开发期间使用的可选快速命令。

package/templates/.agents/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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

@@ -9,7 +9,7 @@ description: >
 # Complete Manual Validation
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-Lifecycle events require explicit trigger data: use `{trigger-initiator}=orchestrator` for orchestration and `model` otherwise; `{request-id}` is a stable single-line identifier for this task and artifact round, and `{reason-code}` is `user-request` or `validation-rerun`. Reuse the same values for started and completed.
+The transaction coordinator appends lifecycle events and the final PR summary state. The maintainer's validation summary and PR manual-validation comment are the human-validation authority; the transaction receipt provides state-transition and recovery consistency.
 
 
 ## Boundary / Critical Rules
@@ -20,7 +20,7 @@ Before generating the validation completion report, read `.agents/rules/evidence
 
 - This skill closes the manual-validation status in an existing PR summary comment; it does not create a parallel ordinary validation comment.
 - It must write `manual-validation.md` or `manual-validation-r{N}.md` so later PR summary refreshes can reuse the validation result.
-- If the `sync-pr` summary comment is missing, fail instead of creating a partial fallback summary.
+- If the `sync-pr` summary comment is missing, fail instead of creating a partial fallback summary; before the receipt, completion log, and final summary are all committed, the remote summary may only be pending/non-pass.
 - Before generating manual-validation artifact Markdown that will be synced to an Issue, read `.agents/rules/sync-content-generation.md` and follow its generator-side constraints; Issue sync remains transparent and does not parse or rewrite the body.
 - After this skill runs, update `task.md` immediately.
 
@@ -42,10 +42,6 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 > 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.
 
-## Step Start: Write the started Marker
-
-After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} manual-validation.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}` and record the returned `artifactContext`.
-
 ## Steps
 
 ### 1. Parse Arguments
@@ -70,33 +66,49 @@ Stop if the task is missing, the validation summary is missing, or no valid PR c
 
 ### 3. Resolve the Artifact Context
 
-Run `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`. Continue only for `ready`; take the round and `{manual-validation-artifact}` from `next.round` / `next.name`. Do not scan rounds or construct names in the skill. Then run the started event and verify the returned identity.
+Run `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`. Continue only for `ready`; take the round and `{manual-validation-artifact}` from `next.round` / `next.name`. Do not scan rounds or construct names in the skill. The transaction coordinator owns the started event.
+
+### 4. Register Manual Validation Start
+
+Before creating any manual-validation artifact, obtain the canonical summary body from `platform-pr summary-context`, then call the transaction coordinator in prepare mode:
 
-### 4. Update the PR Summary
+```bash
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
+```
+
+Prepare must idempotently record `manual-validation.started` before writing the prepared transaction; on failure, stop without creating the artifact.
+
+### 5. Create the Manual Validation Artifact
+
+Before this step, read `reference/report-template.md`. After `started` is recorded, create `{manual-validation-artifact}` and record the state check, validation verdict, validation scope, validation details, and expected PR summary synchronization result; the transaction coordinator validates and commits this artifact in the next step.
+
+### 6. Update the PR Summary
 
 Before this step, read:
 - `.agents/rules/issue-sync.md`
 - `.agents/rules/pr-sync.md`
 - `reference/summary-update.md`
 
-Follow `reference/summary-update.md` to validate the PR binding, obtain canonical inputs from `platform-pr summary-context`, and update the manual-validation section through `platform-pr summary-sync` to `### ✅ Manual Validation Passed`.
+Follow `reference/summary-update.md` to validate the PR binding, obtain canonical inputs from `platform-pr summary-context`, and call the transaction coordinator once:
 
-### 5. Create the Manual Validation Artifact
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
 
-Before this step, read `reference/report-template.md`. Create `{manual-validation-artifact}` and record:
-- State check
-- Validation verdict
-- Validation scope
-- Validation details
-- PR summary sync result
+The coordinator owns pending summary, receipt, completion log, final promotion, and post-write verification; it internally uses the controlled `agent-infra-internal task-event {task-id}` route. Do not call final `summary-sync` or `manual-validation.completed` separately. Raw evidence files from other hosts are not required.
 
-### 6. Update task.md
+### 7. Update task.md
 
-Run `agent-infra-internal task-event {task-id} manual-validation.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {manual-validation-artifact} --summary-result "{summary-result}"`. The core keeps `current_step` unchanged while atomically recording the implementation-notes link, metadata, and done log.
+After the transaction coordinator succeeds, the core has atomically recorded `manual-validation.completed` with the same transaction/receipt/head identity. Do not append the Activity Log manually.
 
 If the task has a valid `issue_number`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {manual-validation-artifact} --agent {standard-agent-token}`.
 
-### 7. Verification Gate
+### 8. Verification Gate
 
 Run:
 
@@ -109,7 +121,7 @@ Handle the result:
 - Exit code 1 -> fix the reported problem and rerun
 - Exit code 2 -> stop and report that manual intervention is required
 
-### 8. Tell the User
+### 9. Tell the User
 
 Report:
 - Artifact path

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

@@ -9,7 +9,7 @@ description: >
 # 完成人工验证
 > `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-生命周期事件必须携带显式触发信息：编排调用使用 `{trigger-initiator}=orchestrator`，否则使用 `model`；`{request-id}` 是本任务与本轮产物的稳定单行标识，`{reason-code}` 使用 `user-request` 或 `validation-rerun`；started 与 completed 使用同一组值。
+事务协调器统一追加 lifecycle 事件和 PR 摘要最终状态。维护者提供的验证说明和 PR 摘要留言就是人工验证依据；事务回执负责保证状态转换和恢复一致性。
 
 
 ## 行为边界 / 关键规则
@@ -20,7 +20,7 @@ description: >
 
 - 本技能用于收尾已有 PR 摘要评论中的人工校验状态，不创建并行的普通验证留言。
 - 必须写入 `manual-validation.md` 或 `manual-validation-r{N}.md`，让后续 PR 摘要刷新可复用人工验证结果。
-- 找不到 `sync-pr` 摘要评论时失败，不创建部分摘要兜底。
+- 找不到 `sync-pr` 摘要评论时失败，不创建部分摘要兜底；receipt、通过日志和 final summary 未全部提交前，远端只允许 pending/non-pass 状态。
 - 生成会同步到 Issue 的人工验证 artifact Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；Issue 同步保持透明，不解析或改写正文。
 - 执行本技能后必须立即更新 `task.md`。
 
@@ -42,10 +42,6 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 > 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
-## 步骤开始：声明 started 事件
-
-确认前置条件和产物上下文后、本轮第一个产出动作之前执行 `agent-infra-internal task-event {task-id} manual-validation.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}`，并以返回的 `artifactContext` 记录本轮身份。
-
 ## 执行步骤
 
 ### 1. 解析入参
@@ -70,33 +66,49 @@ complete-manual-validation [--task <ref> | -t <ref>] [{pr-ref}] {verification-su
 
 ### 3. 解析产物上下文
 
-运行 `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`。仅当结果为 `ready` 时继续；从 `next.round` / `next.name` 取得本轮 round 与 `{manual-validation-artifact}`。不得自行扫描轮次或拼装文件名。随后执行 started 事件并复核返回身份。
+运行 `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`。仅当结果为 `ready` 时继续；从 `next.round` / `next.name` 取得本轮 round 与 `{manual-validation-artifact}`。不得自行扫描轮次或拼装文件名。事务协调器负责 started 事件。
+
+### 4. 登记人工验证开始
+
+在创建任何人工验证 artifact 前，先从 `platform-pr summary-context` 取得 canonical 摘要正文，然后调用事务协调器的 prepare 模式：
 
-### 4. 更新 PR 摘要
+```bash
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
+```
+
+prepare 必须先幂等登记 `manual-validation.started`，再写入 prepared transaction；失败时停止，不创建 artifact。
+
+### 5. 创建人工验证产物
+
+执行此步骤前，先读取 `reference/report-template.md`。在 started 已登记后创建 `{manual-validation-artifact}`，记录状态核对、验证结论、验证范围、验证详情和预期 PR 摘要同步结果；事务协调器将在后续步骤校验并提交这份 artifact。
+
+### 6. 更新 PR 摘要
 
 执行此步骤前，先读取：
 - `.agents/rules/issue-sync.md`
 - `.agents/rules/pr-sync.md`
 - `reference/summary-update.md`
 
-按 `reference/summary-update.md` 校验 PR 绑定，从 `platform-pr summary-context` 取得 canonical 输入，并通过 `platform-pr summary-sync` 把人工校验段更新为 `### ✅ 人工验证已通过`。
+按 `reference/summary-update.md` 校验 PR 绑定，从 `platform-pr summary-context` 取得 canonical 输入，并调用一次 transaction coordinator：
 
-### 5. 创建人工验证产物
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
 
-执行此步骤前，先读取 `reference/report-template.md`。创建 `{manual-validation-artifact}`，记录：
-- 状态核对
-- 验证结论
-- 验证范围
-- 验证详情
-- PR 摘要同步结果
+coordinator 负责 pending summary、receipt、通过日志、final promotion 和 post-write verification；内部受控调用 `agent-infra-internal task-event {task-id}`，不要分别调用 final `summary-sync` 或 `manual-validation.completed`。不要求调用方提供其他主机上的原始 evidence 文件。
 
-### 6. 更新 task.md
+### 7. 更新 task.md
 
-执行 `agent-infra-internal task-event {task-id} manual-validation.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {manual-validation-artifact} --summary-result "{summary-result}"`，由核心在保持 `current_step` 不变的同时原子登记实现备注链接、时间/版本和完成日志。
+transaction coordinator 成功后，核心已使用同一 transaction/receipt/head identity 原子登记 `manual-validation.completed`；不要手工补写 Activity Log。
 
 如任务存在有效 `issue_number`，调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`，再调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {manual-validation-artifact} --agent {standard-agent-token}`。
 
-### 7. 完成校验
+### 8. 完成校验
 
 运行完成校验：
 
@@ -109,7 +121,7 @@ agent-infra-internal task-verify {task-id} manual-validation.completed --artifac
 - 退出码 1 -> 修复问题后重新运行
 - 退出码 2 -> 停止并告知需要人工介入
 
-### 8. 告知用户
+### 9. 告知用户
 
 输出：
 - 产物路径

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

@@ -37,7 +37,7 @@
       "when": "pr_fact_bound",
       "expected_pr_comment_marker_key": "prSummary",
       "expected_pr_comment_required_patterns": [
-        "^### ✅ Manual Validation Passed$"
+        "^### ✅ (?:人工验证已通过|Manual Validation Passed)$"
       ],
       "verify_task_comment_content": true,
       "verify_issue_type": true,

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

@@ -37,7 +37,7 @@
       "when": "pr_fact_bound",
       "expected_pr_comment_marker_key": "prSummary",
       "expected_pr_comment_required_patterns": [
-        "^### ✅ 人工验证已通过$"
+        "^### ✅ (?:人工验证已通过|Manual Validation Passed)$"
       ],
       "verify_task_comment_content": true,
       "verify_issue_type": true,

package/templates/.agents/skills/complete-manual-validation/reference/report-template.en.md

@@ -7,6 +7,7 @@ Read this file before creating `manual-validation.md` / `manual-validation-r{N}.
 
 - **Validation Round**: Round {N}
 - **Artifact File**: `manual-validation.md`
+- **Human Validation Basis**: Maintainer's PR validation comment and validation summary
 
 ## State Check
 
@@ -39,6 +40,7 @@ $ tail .agents/workspace/active/{task-id}/task.md
 - Result: {summary-result}
 - Summary comment: {comment-id or URL}
 - Updated status: `### ✅ Manual Validation Passed`
+- Transaction: `{transaction-id}`; receipt=`{receipt-digest}`; head=`{pr-head-sha}`
 ````
 
 ## Filling Rules

package/templates/.agents/skills/complete-manual-validation/reference/report-template.zh-CN.md

@@ -7,6 +7,7 @@
 
 - **验证轮次**：Round {N}
 - **产物文件**：`manual-validation.md`
+- **人工验证依据**：维护者提供的 PR 验证留言和验证说明
 
 ## 状态核对
 
@@ -39,6 +40,7 @@ $ tail .agents/workspace/active/{task-id}/task.md
 - 结果：{summary-result}
 - 摘要评论：{comment-id 或 URL}
 - 更新状态：`### ✅ 人工验证已通过`
+- Transaction：`{transaction-id}`；receipt=`{receipt-digest}`；head=`{pr-head-sha}`
 ````
 
 ## 填写规则

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

@@ -4,14 +4,23 @@ Run only for a valid `{task-id}` whose task.md binds a verified `pr_delivery_fac
 
 Follow `.agents/rules/pr-sync.md` for the shared summary structure and failure semantics.
 
-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 with exactly one `<!-- canonical-pr-change-report -->` placeholder to a temporary file and run:
+1. Run `agent-infra-internal platform-pr summary-context {task-id}` to obtain the canonical summary body; the maintainer's PR validation comment and validation summary are the human-validation authority.
+2. Before creating the canonical `manual-validation*` artifact, call the transaction coordinator in prepare mode to record `started` before writing the prepared transaction:
 
 ```bash
-agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json --result no_op
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-The core owns the rendered report, marker/authoritative PR-head wrapping, pagination, and in-place reconciliation. If context says no manual validation is required, stop without marking it passed.
+3. After prepare succeeds, write the canonical `manual-validation*` artifact, write the pending plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder to a temporary file, and run the transaction coordinator:
+
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
+
+The core owns the rendered report, marker/authoritative PR-head wrapping, pagination, pending-first ordering, receipt, completion log, final promotion, and in-place reconciliation. Before the receipt and completion log exist, the summary must not contain `### ✅ Manual Validation Passed`. 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

@@ -4,16 +4,25 @@
 
 摘要结构与失败语义统一遵循 `.agents/rules/pr-sync.md`。
 
-1. 在 canonical `manual-validation*` artifact 落盘后，调用 `agent-infra-internal platform-pr summary-context {task-id}`。
-2. 从返回的最新产物重新聚合摘要，将人工校验段渲染为 `### ✅ 人工验证已通过`，写明验证时间和说明。
-3. 把只含一次 `<!-- canonical-pr-change-report -->` 的纯正文写入临时文件，调用：
+1. 调用 `agent-infra-internal platform-pr summary-context {task-id}`，取得 canonical 摘要正文；维护者提供的 PR 人工验证留言和验证说明作为完成人工校验依据。
+2. 在创建 canonical `manual-validation*` artifact 前，调用 transaction coordinator 的 prepare 模式，先登记 started，再写 prepared transaction：
 
 ```bash
-agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json --result no_op
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-marker、报告段、权威 PR head、分页查找和原地更新由 core 负责。若当前 context 表明无需人工校验，则停止并返回 `summary failed: no manual validation required`，不误标通过。
+3. prepare 成功后写入 canonical `manual-validation*` artifact，并把只含一次 `<!-- canonical-pr-change-report -->` 的 pending 正文写入临时文件，调用 transaction coordinator：
+
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
+
+marker、报告段、权威 PR head、分页查找、pending-first 顺序、receipt、通过日志和 final promotion 由 core 负责。若当前 context 表明无需人工校验，则停止并返回 `summary failed: no manual validation required`，不误标通过。receipt/log 前不得出现 `### ✅ 人工验证已通过`。
 
 结果回传：`summary updated`、`summary skipped (no diff)` 或 `summary failed: <reason>`。

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

@@ -104,7 +104,7 @@ Run /create-pr --task {task-ref} first, then complete; --skip-pr is not accepted
 Before lifecycle, verify only the hard gates:
 - [ ] Task identity, active state, concurrency locks, and local atomic lifecycle operations are available
 - [ ] Required-PR delivery is satisfied when `prFlow=required`
-- [ ] Other business evidence (workflow, review, commit, tests, disagreement ledger, manual validation, and platform sync) is recorded or can be checked after lifecycle
+- [ ] Other business evidence (workflow, review, commit, tests, disagreement ledger, manual validation, and platform sync) is recorded or can be checked after lifecycle; manual validation requires a committed transaction, receipt, current artifact digest, and an identity-bearing completion log
 
 > **⚠️ Prerequisite Branch Check — you must decide whether to continue or stop before proceeding:**
 >

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

@@ -103,7 +103,7 @@ agent-infra-internal platform-pr resolve-external {task-id} --agent {standard-ag
 生命周期前只验证硬门禁：
 - [ ] task 身份、active 状态、并发锁和本地原子生命周期操作可用
 - [ ] `prFlow=required` 时已满足 required-PR delivery
-- [ ] 其余业务证据（工作流、审查、提交、测试、分歧账本、人工校验和平台同步）已记录或可在生命周期后校验
+- [ ] 其余业务证据（工作流、审查、提交、测试、分歧账本、人工校验和平台同步）已记录或可在生命周期后校验；人工验证只能由 committed transaction、receipt、当前 artifact 摘要和带 identity 的通过日志满足
 
 > **⚠️ 前置条件分支判断 — 你必须先判断“继续”还是“停止”：**
 >