@fitlab-ai/agent-infra 0.8.1 → 0.8.3

package/templates/.agents/scripts/workflow-warnings.js

@@ -0,0 +1,290 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const SECTION_ZH = "工作流告警";
+const SECTION_EN = "Workflow Warnings";
+const ACTIVITY_ZH = "活动日志";
+const ACTIVITY_EN = "Activity Log";
+const HEADER = "| id | time | step | severity | code | status | target | message | action | resolved_at | resolution |";
+const SEPARATOR = "|----|------|------|----------|------|--------|--------|---------|--------|-------------|------------|";
+const VALID_SEVERITIES = new Set(["IMPORTANT", "ACTION_REQUIRED"]);
+const VALID_STATUSES = new Set(["open", "resolved", "ignored"]);
+
+function usage() {
+  process.stderr.write([
+    "Usage:",
+    "  node .agents/scripts/workflow-warnings.js add <task-dir> --step <step> --severity <IMPORTANT|ACTION_REQUIRED> --code <code> --target <target> --message <message> --action <action>",
+    "  node .agents/scripts/workflow-warnings.js set-status <task-dir> --id <WW-N> --status <resolved|ignored> --resolution <reason>",
+    "  node .agents/scripts/workflow-warnings.js list <task-dir> [--status <status>] [--format json|text]",
+    ""
+  ].join("\n"));
+  process.exit(2);
+}
+
+function parseOptions(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const key = args[index];
+    if (!key?.startsWith("--")) usage();
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) usage();
+    options[key.slice(2)] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function timestamp() {
+  const date = new Date();
+  const pad = (value) => String(value).padStart(2, "0");
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absolute = Math.abs(offsetMinutes);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`;
+}
+
+function escapeCell(value) {
+  return String(value ?? "").replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function unescapeCell(value) {
+  const text = String(value ?? "");
+  let output = "";
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    const next = text[index + 1];
+    if (char === "\\" && (next === "\\" || next === "|")) {
+      output += next;
+      index += 1;
+      continue;
+    }
+    output += char;
+  }
+  return output;
+}
+
+function isEscapedAt(value, index) {
+  let backslashes = 0;
+  for (let cursor = index - 1; cursor >= 0 && value[cursor] === "\\"; cursor -= 1) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+}
+
+function splitRow(line) {
+  let value = String(line || "").trim();
+  if (!value.startsWith("|")) return [];
+  value = value.replace(/^\|/, "").replace(/\|$/, "");
+  const cells = [];
+  let cell = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "|" && !isEscapedAt(value, index)) {
+      cells.push(unescapeCell(cell.trim()));
+      cell = "";
+      continue;
+    }
+    cell += char;
+  }
+  cells.push(unescapeCell(cell.trim()));
+  return cells;
+}
+
+function rowToWarning(cells, lineIndex) {
+  return {
+    lineIndex,
+    id: cells[0] || "",
+    time: cells[1] || "",
+    step: cells[2] || "",
+    severity: cells[3] || "",
+    code: cells[4] || "",
+    status: cells[5] || "",
+    target: cells[6] || "",
+    message: cells[7] || "",
+    action: cells[8] || "",
+    resolved_at: cells[9] || "",
+    resolution: cells[10] || ""
+  };
+}
+
+function warningToLine(warning) {
+  return [
+    warning.id,
+    warning.time,
+    warning.step,
+    warning.severity,
+    warning.code,
+    warning.status,
+    warning.target,
+    warning.message,
+    warning.action,
+    warning.resolved_at,
+    warning.resolution
+  ].map(escapeCell).join(" | ").replace(/^/, "| ").replace(/$/, " |");
+}
+
+function findSection(lines) {
+  let start = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (new RegExp(`^##\\s+(${SECTION_ZH}|${SECTION_EN})\\s*$`).test(lines[index].trim())) {
+      start = index;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function insertSection(content) {
+  const lines = content.split(/\r?\n/);
+  const existing = findSection(lines);
+  if (existing) return { content, section: existing };
+
+  const activityIndex = lines.findIndex((line) => {
+    const trimmed = line.trim();
+    return trimmed === `## ${ACTIVITY_ZH}` || trimmed === `## ${ACTIVITY_EN}`;
+  });
+  const heading = content.includes(`## ${ACTIVITY_EN}`) ? SECTION_EN : SECTION_ZH;
+  const block = [`## ${heading}`, "", "<!-- Workflow degradation, platform sync failures, permission gaps, and related events. Keep the header when empty. -->", "", HEADER, SEPARATOR, ""];
+  const insertAt = activityIndex >= 0 ? activityIndex : lines.length;
+  lines.splice(insertAt, 0, ...block);
+  const updated = lines.join("\n");
+  return { content: updated, section: findSection(updated.split(/\r?\n/)) };
+}
+
+function readTask(taskDir) {
+  const taskPath = path.join(taskDir, "task.md");
+  if (!fs.existsSync(taskPath)) {
+    throw new Error(`Task file not found: ${taskPath}`);
+  }
+  return { taskPath, content: fs.readFileSync(taskPath, "utf8") };
+}
+
+function parseWarnings(content) {
+  const lines = content.split(/\r?\n/);
+  const section = findSection(lines);
+  if (!section) return [];
+  const warnings = [];
+  for (let index = section.start + 1; index < section.end; index += 1) {
+    const cells = splitRow(lines[index]);
+    if (cells.length === 0) continue;
+    if ((cells[0] || "").toLowerCase() === "id") continue;
+    if (cells.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
+    if (cells.length < 11) continue;
+    warnings.push(rowToWarning(cells, index));
+  }
+  return warnings;
+}
+
+function nextId(warnings) {
+  const max = warnings.reduce((current, warning) => {
+    const match = /^WW-(\d+)$/.exec(warning.id);
+    return match ? Math.max(current, Number.parseInt(match[1], 10)) : current;
+  }, 0);
+  return `WW-${max + 1}`;
+}
+
+function requireOption(options, key) {
+  const value = options[key];
+  if (!value) usage();
+  return value;
+}
+
+function add(taskDir, options) {
+  const severity = requireOption(options, "severity");
+  if (!VALID_SEVERITIES.has(severity)) throw new Error(`Invalid severity: ${severity}`);
+  const step = requireOption(options, "step");
+  const code = requireOption(options, "code");
+  const target = requireOption(options, "target");
+  const message = requireOption(options, "message");
+  const action = requireOption(options, "action");
+
+  const task = readTask(taskDir);
+  const inserted = insertSection(task.content);
+  const lines = inserted.content.split(/\r?\n/);
+  const warnings = parseWarnings(inserted.content);
+  const duplicate = warnings.find((warning) =>
+    warning.status === "open" &&
+    warning.step === step &&
+    warning.code === code &&
+    warning.target === target
+  );
+  if (duplicate) {
+    process.stdout.write(`${JSON.stringify({ created: false, warning: duplicate }, null, 2)}\n`);
+    if (inserted.content !== task.content) fs.writeFileSync(task.taskPath, inserted.content, "utf8");
+    return;
+  }
+
+  const warning = {
+    id: nextId(warnings),
+    time: timestamp(),
+    step,
+    severity,
+    code,
+    status: "open",
+    target,
+    message,
+    action,
+    resolved_at: "",
+    resolution: ""
+  };
+  lines.splice(inserted.section.end - 1, 0, warningToLine(warning));
+  fs.writeFileSync(task.taskPath, lines.join("\n"), "utf8");
+  process.stdout.write(`${JSON.stringify({ created: true, warning }, null, 2)}\n`);
+}
+
+function setStatus(taskDir, options) {
+  const id = requireOption(options, "id");
+  const status = requireOption(options, "status");
+  if (!["resolved", "ignored"].includes(status)) throw new Error(`Invalid status for set-status: ${status}`);
+  const resolution = requireOption(options, "resolution");
+  const task = readTask(taskDir);
+  const lines = task.content.split(/\r?\n/);
+  const warnings = parseWarnings(task.content);
+  const warning = warnings.find((candidate) => candidate.id === id);
+  if (!warning) throw new Error(`Warning not found: ${id}`);
+  warning.status = status;
+  warning.resolved_at = timestamp();
+  warning.resolution = resolution;
+  lines[warning.lineIndex] = warningToLine(warning);
+  fs.writeFileSync(task.taskPath, lines.join("\n"), "utf8");
+  process.stdout.write(`${JSON.stringify({ updated: true, warning }, null, 2)}\n`);
+}
+
+function list(taskDir, options) {
+  const format = options.format || "text";
+  const status = options.status || "";
+  if (format !== "json" && format !== "text") usage();
+  const warnings = parseWarnings(readTask(taskDir).content)
+    .filter((warning) => !status || warning.status === status)
+    .map(({ lineIndex: _lineIndex, ...warning }) => warning);
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify({ warnings }, null, 2)}\n`);
+    return;
+  }
+  for (const warning of warnings) {
+    process.stdout.write(`${warning.id} [${warning.severity}] ${warning.code} ${warning.target} - ${warning.action}\n`);
+  }
+}
+
+try {
+  const [command, taskDirArg, ...rest] = process.argv.slice(2);
+  if (!command || !taskDirArg) usage();
+  const taskDir = path.resolve(taskDirArg);
+  const options = parseOptions(rest);
+  if (command === "add") add(taskDir, options);
+  else if (command === "set-status") setStatus(taskDir, options);
+  else if (command === "list") list(taskDir, options);
+  else usage();
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

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

@@ -0,0 +1,118 @@
+---
+name: complete-manual-validation
+description: >
+  Mark PR manual validation as completed and update the manual-validation section
+  in the existing PR summary comment in place.
+---
+
+# Complete Manual Validation
+
+## Boundary / Critical Rules
+
+- 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.
+- After this skill runs, update `task.md` immediately.
+
+Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
+
+## Step 0: State Check (pre-execution hard gate)
+
+After loading workflow / skill / rules instructions, and before any task-state judgment or user-visible conclusion, run the state check first. Reading instruction files does not count as an external-state action or conclusion.
+
+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
+```
+
+## Task id short ref
+
+> 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.
+
+## Step Start: Write the started Marker
+
+After confirming prerequisites and the artifact round, and before this round's first artifact action, append a started marker to task.md `## Activity Log`:
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation [started]** by {agent} — started
+```
+
+See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
+## Steps
+
+### 1. Parse Arguments
+
+Input:
+
+```text
+complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
+```
+
+- `{task-ref}` is required.
+- `{pr-ref}` is optional and accepts `#NN`, `NN`, or a full PR URL.
+- `{verification-summary}` is required. If it is missing, stop and ask for a validation summary; do not write an artifact or update the PR.
+
+### 2. Verify Prerequisites
+
+Check:
+- `.agents/workspace/active/{task-id}/task.md`
+- a valid PR: prefer explicit `{pr-ref}`, otherwise read `pr_number` from task.md frontmatter
+
+Stop if the task is missing, the validation summary is missing, or no valid PR can be resolved.
+
+### 3. Determine Artifact Round
+
+Scan the task directory:
+- no `manual-validation.md` and no `manual-validation-r*.md` -> write `manual-validation.md`
+- `manual-validation.md` exists and no `manual-validation-r*.md` -> write `manual-validation-r2.md`
+- `manual-validation-r{N}.md` exists -> write `manual-validation-r{N+1}.md`
+
+### 4. 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 resolve the PR number, find the `sync-pr` summary comment, extract the manual-validation scope, and update the section to `### ✅ Manual Validation Passed`.
+
+### 5. Create the Manual Validation Artifact
+
+Before this step, read `reference/report-template.md`. Create `{manual-validation-artifact}` with state check, validation verdict, validation scope, validation details, and PR summary sync result.
+
+### 6. Update task.md
+
+Get the current time:
+
+```bash
+date "+%Y-%m-%d %H:%M:%S%:z"
+```
+
+Update `.agents/workspace/active/{task-id}/task.md`:
+- `updated_at`: current time
+- `assigned_to`: current agent
+- `agent_infra_version`: value from `.agents/rules/version-stamp.md`
+- keep `current_step` unchanged
+- append the `{manual-validation-artifact}` link and PR summary sync result to `## Implementation Notes`
+- append Activity Log:
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation** by {agent} — Manual validation passed → {manual-validation-artifact}; {summary-result}
+  ```
+
+If the task has a valid `issue_number`, follow `.agents/rules/issue-sync.md` to update the task comment and publish the `{manual-validation-artifact}` comment.
+
+### 7. Verification Gate
+
+Run:
+
+```bash
+node .agents/scripts/validate-artifact.js gate complete-manual-validation .agents/workspace/active/{task-id} {manual-validation-artifact} --format text
+```
+
+### 8. Tell the User
+
+Report the artifact path, PR summary sync result, and verification output. Before rendering the final output, read `.agents/rules/next-step-output.md` and append `Completed at: YYYY-MM-DD HH:mm:ss` as the absolute last line.

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

@@ -0,0 +1,118 @@
+---
+name: complete-manual-validation
+description: >
+  标记 PR 人工验证已完成，并原地更新 PR 摘要评论中的人工校验段落。
+  当维护者已完成真实环境或权限相关人工验证、需要统一收尾 PR 摘要时使用。
+---
+
+# 完成人工验证
+
+## 行为边界 / 关键规则
+
+- 本技能用于收尾已有 PR 摘要评论中的人工校验状态，不创建并行的普通验证留言。
+- 必须写入 `manual-validation.md` 或 `manual-validation-r{N}.md`，让后续 PR 摘要刷新可复用人工验证结果。
+- 找不到 `sync-pr` 摘要评论时失败，不创建部分摘要兜底。
+- 执行本技能后必须立即更新 `task.md`。
+
+版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
+
+## 第 0 步：状态核对（执行前硬约束）
+
+在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
+
+运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+
+```bash
+git status -s
+ls -la .agents/workspace/active/{task-id}/
+tail .agents/workspace/active/{task-id}/task.md
+```
+
+## 任务入参短号别名
+
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+
+## 步骤开始：写入 started 标记
+
+确认前置条件和产物轮次后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 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 双标记约定」。
+
+## 执行步骤
+
+### 1. 解析入参
+
+输入格式：
+
+```text
+complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
+```
+
+- `{task-ref}` 必填。
+- `{pr-ref}` 可选，支持 `#NN`、`NN` 或完整 PR URL。
+- `{verification-summary}` 必填。若缺失，立即停止并提示补充验证说明；不写产物、不更新 PR。
+
+### 2. 验证前置条件
+
+检查：
+- `.agents/workspace/active/{task-id}/task.md`
+- 有效 PR：优先使用显式 `{pr-ref}`，否则读取 task.md frontmatter 的 `pr_number`
+
+如果任务不存在、验证说明缺失，或无法解析有效 PR，立即停止。
+
+### 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`
+
+### 4. 更新 PR 摘要
+
+执行此步骤前，先读取：
+- `.agents/rules/issue-sync.md`
+- `.agents/rules/pr-sync.md`
+- `reference/summary-update.md`
+
+按 `reference/summary-update.md` 解析 PR 号、查找 `sync-pr` 摘要评论、提取待人工校验范围，并把人工校验段落更新为 `### ✅ 人工验证已通过`。
+
+### 5. 创建人工验证产物
+
+执行此步骤前，先读取 `reference/report-template.md`。创建 `{manual-validation-artifact}`，记录状态核对、验证结论、验证范围、验证详情和 PR 摘要同步结果。
+
+### 6. 更新 task.md
+
+获取当前时间：
+
+```bash
+date "+%Y-%m-%d %H:%M:%S%:z"
+```
+
+更新 `.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}
+  ```
+
+如任务存在有效 `issue_number`，按 `.agents/rules/issue-sync.md` 更新 task 评论并发布 `{manual-validation-artifact}` 评论。
+
+### 7. 完成校验
+
+运行完成校验：
+
+```bash
+node .agents/scripts/validate-artifact.js gate complete-manual-validation .agents/workspace/active/{task-id} {manual-validation-artifact} --format text
+```
+
+### 8. 告知用户
+
+输出产物路径、PR 摘要同步结果和当次完成校验输出。渲染最终输出前，先读取 `.agents/rules/next-step-output.md`，并在绝对最后一行追加 `Completed at: YYYY-MM-DD HH:mm:ss`。

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

@@ -0,0 +1,49 @@
+{
+  "skill": "complete-manual-validation",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "agent_infra_version",
+        "current_step",
+        "assigned_to"
+      ]
+    },
+    "artifact": {
+      "file_pattern": "manual-validation.md|manual-validation-r{N}.md",
+      "required_sections": [
+        "State Check",
+        "Validation Verdict",
+        "Validation Scope",
+        "Validation Details",
+        "PR Summary Sync"
+      ],
+      "freshness_minutes": 30,
+      "required_patterns": [
+        "^\\$ "
+      ]
+    },
+    "activity-log": {
+      "expected_action_pattern": "Complete Manual Validation",
+      "freshness_minutes": 30
+    },
+    "review-ledger": {
+      "stage_scope": ["analysis", "plan", "code"]
+    },
+    "platform-sync": {
+      "when": "pr_number_exists",
+      "expected_pr_comment_marker_key": "prSummary",
+      "expected_pr_comment_required_patterns": [
+        "^### ✅ Manual Validation Passed$"
+      ],
+      "verify_task_comment_content": true,
+      "verify_issue_type": true,
+      "verify_issue_fields": false
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+{
+  "skill": "complete-manual-validation",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "agent_infra_version",
+        "current_step",
+        "assigned_to"
+      ]
+    },
+    "artifact": {
+      "file_pattern": "manual-validation.md|manual-validation-r{N}.md",
+      "required_sections": [
+        "状态核对",
+        "验证结论",
+        "验证范围",
+        "验证详情",
+        "PR 摘要同步"
+      ],
+      "freshness_minutes": 30,
+      "required_patterns": [
+        "^\\$ "
+      ]
+    },
+    "activity-log": {
+      "expected_action_pattern": "Complete Manual Validation",
+      "freshness_minutes": 30
+    },
+    "review-ledger": {
+      "stage_scope": ["analysis", "plan", "code"]
+    },
+    "platform-sync": {
+      "when": "pr_number_exists",
+      "expected_pr_comment_marker_key": "prSummary",
+      "expected_pr_comment_required_patterns": [
+        "^### ✅ 人工验证已通过$"
+      ],
+      "verify_task_comment_content": true,
+      "verify_issue_type": true,
+      "verify_issue_fields": false
+    }
+  }
+}

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

@@ -0,0 +1,48 @@
+# Manual Validation Completion Report Template
+
+Read this file before creating `manual-validation.md` / `manual-validation-r{N}.md`.
+
+````markdown
+# Manual Validation Completion Report
+
+- **Validation Round**: Round {N}
+- **Artifact File**: `manual-validation.md`
+
+## State Check
+
+```text
+$ git status -s
+$ ls -la .agents/workspace/active/{task-id}/
+$ tail .agents/workspace/active/{task-id}/task.md
+```
+
+## Validation Verdict
+
+- Verdict: passed
+- Validation time: {YYYY-MM-DD HH:mm:ss±HH:MM}
+- Operator: {agent}
+
+## Validation Scope
+
+- PR: #{pr-number}
+- Summary comment: {comment-id or URL}
+- Manual-validation items:
+  - {item-1}
+
+## Validation Details
+
+{verification-summary}
+
+## PR Summary Sync
+
+- Result: {summary-result}
+- Summary comment: {comment-id or URL}
+- Updated status: `### ✅ Manual Validation Passed`
+````
+
+## Filling Rules
+
+- Keep `Validation Details` grounded in the user-provided validation notes.
+- Derive `Validation Scope` from the PR summary's manual-verification section.
+- `PR Summary Sync` must record success, skip, or failure.
+- Only write a passing artifact after the summary comment is updated or skipped because there is no diff.