@fitlab-ai/agent-infra 0.8.1 → 0.8.3

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,10 +1,11 @@
 # 下一步输出规则
 
-本文件定义 skill「告知用户 / 下一步」输出的三类**相互独立**的规则（第 3 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
+本文件定义 skill「告知用户 / 下一步」输出的四类**相互独立**的规则（第 3 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
 
 1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
 2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
 3. **人工裁决待办前置块**：仅 `review-analysis` / `review-plan` / `review-code`，且本阶段存在待裁决项（`{h} > 0`）时适用——在「下一步」命令前展开待裁决项并提示先完成裁决。
+4. **Workflow Warnings 输出块**：当前 task.md 存在 `status=open` 的 `## 工作流告警` 行时适用——在所有常规信息和「下一步」命令之后、`Completed at` 之前输出告警摘要。
 
 ## 占位符语义
 
@@ -62,6 +63,19 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 manual-validation 提醒），收尾行排在该提醒行之后。
 - 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
 
+## Workflow Warnings 输出块
+
+若当前任务的 `## 工作流告警` / `## Workflow Warnings` 表中存在 `status=open` 行，skill 最终输出必须在所有常规信息和「下一步」命令之后、`Completed at` 之前追加摘要块；无 open 告警时不输出本块。
+
+格式：
+
+```text
+[ACTION REQUIRED] Workflow warnings are open:
+  - WW-N {code} ({target}): {action}
+```
+
+`severity=ACTION_REQUIRED` 的行使用 `[ACTION REQUIRED]`；只有 `IMPORTANT` 行时使用 `[IMPORTANT]`。`{code}`、`{target}`、`{action}` 直接来自告警表对应列。
+
 ## 人工裁决待办前置块（review-* 专用，{h} > 0 时）
 
 本节是与上面两类规则**并列的第三类独立规则**，仅 `review-analysis` / `review-plan` / `review-code` 的「向用户汇报结论」步骤使用。

package/templates/.agents/rules/pr-sync.github.en.md

@@ -7,6 +7,7 @@ Read this file before syncing the single reviewer-facing PR summary comment.
 Current callers:
 - `create-pr`: create or update the summary comment when the PR is opened
 - `commit`: refresh the summary comment on an existing PR when needed
+- `complete-manual-validation`: update the summary comment in place after manual validation passes, and write a validation artifact that later aggregation can reuse
 
 If another skill needs to refresh the PR summary later, point that skill's reference file at this rule first, then document only the skill-specific trigger and failure behavior there.
 
@@ -26,17 +27,22 @@ Aggregate the latest artifacts in the task directory:
 - `plan.md` or the latest `plan-r{N}.md`
 - `code.md` or the latest `code-r{N}.md`
 - `review-code.md` or the latest `review-code-r{N}.md`
+- `manual-validation.md` or the latest `manual-validation-r{N}.md`
 
 Aggregation rules:
 - extract 2-4 self-contained technical decisions from `plan*`
 - build the review-history table from `review-code*` and `code*`
 - extract the test summary from `code*`
+- if the latest `manual-validation*` artifact has a passed verdict, render the manual-validation section first as `### ✅ Manual Validation Passed`, with a concise validation time, scope, and notes summary
 - if one artifact class is missing, treat it as "no data for this stage" and continue
 - Manual verification section: include only post-code-stage checks that still require a human to execute or judge and that the AI cannot close on its own.
   - **Admission boundary**: the verification result depends on a real environment, permissions, account, external system, or human judgment, and cannot be closed by an agent rerunning tests, adding checks, or continuing the fix loop.
   - **Sources**: `review-code*` "Manual Validation Items", plus `code*` items that satisfy the boundary above.
   - **Wording**: each retained item must state at least "what to verify + location (file/change/scope) + why only a human can verify it".
-  - **Empty rendering**: when there are no retained items, do NOT use the ⚠️ alarm style (it falsely implies a problem). Render the whole block as: heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list. Only use the `### ⚠️ Manual Verification Required` heading + item list when retained items exist.
+  - **Rendering priority**:
+    1. the latest `manual-validation*` artifact has a passed verdict -> heading `### ✅ Manual Validation Passed` + validation summary.
+    2. no passed artifact and retained items exist -> heading `### ⚠️ Manual Verification Required` + item list.
+    3. no passed artifact and no retained items -> heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list.
 
 ## Comment Body Template
 
@@ -72,7 +78,7 @@ Use this canonical comment body template:
 *Generated by {agent} · Internal tracking: {task-id}*
 ```
 
-> Render `{manual-validation-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
+> Render `{manual-validation-section}` per the "manual verification section" aggregation rule above: passed artifact → `### ✅ Manual Validation Passed` heading + validation summary; retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
 
 ## Comment Lookup And Update
 
@@ -111,6 +117,15 @@ EOF
 | `gh api` GET/PATCH/POST fails | warn and continue; whether the current skill should block is decided by the caller |
 | `pr_number` points to a missing PR | warn with `PR #{pr-number} not found` and continue |
 
+When the caller has a `{task-id}` / task directory and GET/PATCH/POST fails, record a Workflow Warning:
+
+```bash
+node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
+  --step pr-sync --severity ACTION_REQUIRED --code COMMENT_SYNC_FAILED \
+  --target "pr-summary" --message "{reason}" \
+  --action "Fix GitHub API / network issues and rerun the workflow step that triggers PR summary sync"
+```
+
 ## Result Reporting
 
 Return one of these normalized results so callers can reuse it in Activity Log entries or user output:

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

@@ -7,6 +7,7 @@
 当前调用方：
 - `create-pr`：首次创建或更新 PR 摘要评论
 - `commit`：在已有 PR 上按需刷新摘要评论
+- `complete-manual-validation`：人工验证完成后原地更新摘要评论，并写入可被后续聚合复用的验证产物
 
 如果后续 skill 也需要刷新 PR 摘要，先在对应 skill 的 reference 中引用本 rule，再补充该 skill 自身的触发条件和失败语义。
 
@@ -26,17 +27,22 @@
 - `plan.md` 或最新 `plan-r{N}.md`
 - `code.md` 或最新 `code-r{N}.md`
 - `review-code.md` 或最新 `review-code-r{N}.md`
+- `manual-validation.md` 或最新 `manual-validation-r{N}.md`
 
 聚合规则：
 - 从 `plan*` 提取 2-4 条自包含的关键技术决策
 - 用 `review-code*` 与 `code*` 构建审查历程表
 - 从 `code*` 提取测试结果摘要
+- 如果最新 `manual-validation*` 产物结论为通过，需人工校验段落优先渲染为 `### ✅ 人工验证已通过`，并摘要验证时间、验证范围和验证说明
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
 - 需人工校验段落：只收进入 code 阶段后仍需人实际执行或判断、AI 无法自行关闭的校验点。
   - **准入边界**：校验结论依赖真实环境、权限、账号、外部系统或人工判断，且无法通过 agent 重跑测试、补充检查或继续修复自行关闭。
   - **来源**：`review-code*` 的「人工校验项」，以及 `code*` 中满足上述边界的校验点。
   - **写法**：每条保留项至少写明「校验什么 + 定位（文件/改动/范围）+ 为什么只能由人校验」。
-  - **空集渲染**：无保留项时，不要使用 ⚠️ 告警样式（会让人误以为有问题）。整段降级渲染为：标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。有保留项时才用 `### ⚠️ 需人工校验` 标题 + 条目列表。
+  - **渲染优先级**：
+    1. 最新 `manual-validation*` 产物结论为通过 -> 标题 `### ✅ 人工验证已通过` + 验证摘要。
+    2. 没有通过产物且有保留项 -> 标题 `### ⚠️ 需人工校验` + 条目列表。
+    3. 没有通过产物且无保留项 -> 标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。
 
 ## 评论体模板
 
@@ -72,7 +78,7 @@
 *由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
-> `{manual-validation-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
+> `{manual-validation-section}` 按上文「需人工校验段落」聚合规则渲染：已通过产物 → `### ✅ 人工验证已通过` 标题 + 验证摘要；有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
 
 ## 评论查找与更新
 
@@ -111,6 +117,15 @@ EOF
 | `gh api` GET/PATCH/POST 失败 | 输出警告并继续；是否阻塞当前 skill 由调用方决定 |
 | `pr_number` 指向的 PR 不存在 | 输出 `PR #{pr-number} not found` 警告并继续 |
 
+当调用方存在 `{task-id}` / task 目录且 GET/PATCH/POST 失败时，记录 Workflow Warning：
+
+```bash
+node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
+  --step pr-sync --severity ACTION_REQUIRED --code COMMENT_SYNC_FAILED \
+  --target "pr-summary" --message "{reason}" \
+  --action "修复 GitHub API / 网络问题后重跑触发 PR 摘要同步的 workflow 步骤"
+```
+
 ## 结果回传
 
 统一回传以下结果之一，供调用方在 Activity Log 或用户输出中复用：

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

@@ -52,7 +52,7 @@ Map user intent to the corresponding workflow command:
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.
 
-**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, with fixed English labels `Manual-validation: {e}, Human-decision: {h}`. `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status ∈ {needs-human-decision, human-decided}`. `Manual-validation` (`{e}`) parses the `Manual-validation: {n}` source field from the review done note (normalized to the same field when displayed), defaulting to `0`. Non-review rows carry no human counts.
+**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, with fixed English labels `Manual-validation: {e}, Human-decision: {h}`. `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current pending rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status = needs-human-decision`, excluding rows already marked `human-decided`. `Manual-validation` (`{e}`) parses the `Manual-validation: {n}` source field from the review done note (normalized to the same field when displayed), defaulting to `0`. Non-review rows carry no human counts.
 
 **Gate** (`checkActivityLog`): when computing the "latest action / freshness" it skips `[started]` lines (ascending-order and format checks still cover every line), so a started marker never satisfies a skill's `expected_action_pattern`.
 

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

@@ -56,7 +56,7 @@
 
 **配对与渲染**（`ai task log`）：按 `{基名}` 把 started 与其后最近的同名 done 配成一行（同基名多次执行按时间升序 FIFO 配对）。STARTED 列显示 started 时间、DONE 列显示 done 时间；只有 started 无 done = 进行中（DONE 显示 `(in progress)`）；只有 done 无 started（历史日志）= 单态完成行。三种形态都合法、不报错。
 
-**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，固定英文标签 `Manual-validation: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`Manual-validation`（`{e}`）解析 review done note 中的 `Manual-validation: {n}` 源字段（展示时归一化为同一字段），缺失为 `0`。非审查步骤不附加人工计数。
+**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，固定英文标签 `Manual-validation: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status = needs-human-decision` 的当前待裁决数量，不包含已 `human-decided` 的行；`Manual-validation`（`{e}`）解析 review done note 中的 `Manual-validation: {n}` 源字段（展示时归一化为同一字段），缺失为 `0`。非审查步骤不附加人工计数。
 
 **gate**（`checkActivityLog`）：计算「最新 action / freshness」时跳过 `[started]` 行（升序与格式校验仍覆盖全部行），故 started 标记不会污染各 SKILL 的 `expected_action_pattern`。
 

package/templates/.agents/scripts/platform-adapters/platform-sync.github.js

@@ -112,6 +112,7 @@ export function check({ taskDir, config, artifactFile }, shared) {
     checkCommentMarker,
     checkPrCommentMarker,
     checkPrCommentLastCommit,
+    checkPrCommentRequiredPatterns,
     checkCommentContent,
     checkTaskCommentContent,
     checkInLabelsComputed,
@@ -158,6 +159,7 @@ function buildSyncContext({ taskDir, config, artifactFile }) {
     return { earlyReturn: blockedResult(CHECK_TYPE, upstreamRepo.message, "network_error") };
   }
   const permissions = detectPermissions(upstreamRepo.value, taskDir);
+  const repoOwnerType = detectRepoOwnerType(upstreamRepo.value, taskDir);
   const expectedValues = resolveExpectedValues(config);
   if (!expectedValues.ok) {
     return { earlyReturn: failResult(CHECK_TYPE, expectedValues.message, "check_failed") };
@@ -180,6 +182,7 @@ function buildSyncContext({ taskDir, config, artifactFile }) {
     issueNumber,
     prNumber,
     upstreamRepo: upstreamRepo.value,
+    repoOwnerType,
     hasTriage: permissions.hasTriage,
     hasPush: permissions.hasPush,
     expectedStatusLabel: expectedValues.statusLabel,
@@ -553,6 +556,41 @@ function checkPrCommentLastCommit(context, remoteData) {
   );
 }
 
+function checkPrCommentRequiredPatterns(context, remoteData) {
+  const patterns = context.config.expected_pr_comment_required_patterns || [];
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    return null;
+  }
+
+  if (!context.prMarker) {
+    return failResult(CHECK_TYPE,
+      "expected_pr_comment_required_patterns requires expected_pr_comment_marker",
+      "check_failed"
+    );
+  }
+
+  const comment = findCommentByMarker(remoteData.prComments, context.prMarker);
+  if (!comment) {
+    return failResult(CHECK_TYPE,
+      `Expected PR comment marker '${context.prMarker}' not found on PR #${context.prNumber}`,
+      "check_failed"
+    );
+  }
+
+  const body = String(comment.body || "");
+  for (const pattern of patterns) {
+    const regex = new RegExp(pattern, "m");
+    if (!regex.test(body)) {
+      return failResult(CHECK_TYPE,
+        `PR #${context.prNumber} summary comment is missing required pattern: ${pattern}`,
+        "check_failed"
+      );
+    }
+  }
+
+  return null;
+}
+
 function checkCommentContent(context, remoteData) {
   if (!context.config.verify_comment_content) {
     return null;
@@ -722,6 +760,10 @@ function checkIssueType(context, remoteData) {
   }
 
   if (!remoteData.issueType) {
+    if (context.repoOwnerType === "User") {
+      return null;
+    }
+
     return failResult(CHECK_TYPE,
       `Issue #${context.issueNumber} has no Issue Type set`,
       "check_failed"
@@ -1228,6 +1270,21 @@ function detectPermissions(upstreamRepo, taskDir) {
   };
 }
 
+function detectRepoOwnerType(upstreamRepo, taskDir) {
+  const ownerTypeResult = withRetry(() => ghText([
+    "api",
+    `repos/${upstreamRepo}`,
+    "--jq",
+    ".owner.type // empty"
+  ], taskDir));
+
+  if (!ownerTypeResult.ok) {
+    return "unknown";
+  }
+
+  return ownerTypeResult.value || "unknown";
+}
+
 function ghJson(args, cwd) {
   const result = ghCommand(args, cwd);
   if (!result.ok) {

package/templates/.agents/scripts/validate-artifact.js

@@ -61,6 +61,10 @@ const LEDGER_TERMINAL_OK = new Set(["confirmed", "closed", "human-decided"]);
 const DEFAULT_MAX_HANDSHAKE_ROUNDS = 3;
 const POST_REVIEW_COMMIT_STAGE = "post-review-commit";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+const WORKFLOW_WARNING_SECTION_NAMES = ["工作流告警", "Workflow Warnings"];
+const WORKFLOW_WARNING_STATUSES = new Set(["open", "resolved", "ignored"]);
+const WORKFLOW_WARNING_SEVERITIES = new Set(["IMPORTANT", "ACTION_REQUIRED"]);
+const WORKFLOW_WARNING_ID_PATTERN = /^WW-\d+$/;
 
 const scriptPath = fileURLToPath(import.meta.url);
 const repoRoot = path.resolve(path.dirname(scriptPath), "..", "..");
@@ -284,6 +288,11 @@ function checkTaskMeta({ taskDir, config }) {
     return failResult("task-meta", branchValidationError);
   }
 
+  const warningValidationErrors = validateWorkflowWarnings(task.content);
+  if (warningValidationErrors.length > 0) {
+    return failResult("task-meta", `Invalid Workflow Warnings: ${warningValidationErrors.join("; ")}`);
+  }
+
   const expectedStep = config.expected_step;
   if (expectedStep && metadata.current_step !== expectedStep) {
     return failResult(
@@ -561,6 +570,117 @@ function parseLedgerRows(section) {
   return rows;
 }
 
+function splitMarkdownTableRow(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(unescapeMarkdownTableCell(cell.trim()));
+      cell = "";
+      continue;
+    }
+    cell += char;
+  }
+  cells.push(unescapeMarkdownTableCell(cell.trim()));
+  return cells;
+}
+
+function unescapeMarkdownTableCell(value) {
+  let output = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    const next = value[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 parseWorkflowWarningRows(section) {
+  const rows = [];
+  for (const rawLine of String(section || "").split(/\r?\n/)) {
+    const cells = splitMarkdownTableRow(rawLine);
+    if (cells.length === 0) {
+      continue;
+    }
+    if ((cells[0] || "").toLowerCase() === "id") {
+      continue;
+    }
+    if (cells.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+      continue;
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+function validateWorkflowWarnings(content) {
+  const section = getSectionContent(content, WORKFLOW_WARNING_SECTION_NAMES);
+  if (!section.trim()) {
+    return [];
+  }
+
+  const rows = parseWorkflowWarningRows(section);
+  const errors = [];
+  for (const cells of rows) {
+    if (cells.length < 11) {
+      errors.push(`malformed row (expected 11 columns): ${cells.join(" | ")}`);
+      continue;
+    }
+    const [id, time, step, severity, code, status, target, message, action, resolvedAt, resolution] = cells;
+    if (!WORKFLOW_WARNING_ID_PATTERN.test(id)) {
+      errors.push(`${id || "(empty id)"}: invalid id`);
+    }
+    if (!DATE_TIME_PATTERN.test(time)) {
+      errors.push(`${id}: invalid time '${time}'`);
+    }
+    if (isBlank(step)) {
+      errors.push(`${id}: step is required`);
+    }
+    if (!WORKFLOW_WARNING_SEVERITIES.has(severity)) {
+      errors.push(`${id}: illegal severity '${severity}'`);
+    }
+    if (isBlank(code)) {
+      errors.push(`${id}: code is required`);
+    }
+    if (!WORKFLOW_WARNING_STATUSES.has(status)) {
+      errors.push(`${id}: illegal status '${status}'`);
+    }
+    if (isBlank(target)) {
+      errors.push(`${id}: target is required`);
+    }
+    if (isBlank(message)) {
+      errors.push(`${id}: message is required`);
+    }
+    if (status === "open" && isBlank(action)) {
+      errors.push(`${id}: open warning requires action`);
+    }
+    if ((status === "resolved" || status === "ignored") && (isBlank(resolvedAt) || isBlank(resolution))) {
+      errors.push(`${id}: ${status} warning requires resolved_at and resolution`);
+    }
+  }
+  return errors;
+}
+
 function resolveReviewSetting(config, key, fallback) {
   if (config && config[key] !== undefined && config[key] !== null) {
     return config[key];