@fitlab-ai/agent-infra 0.8.2 → 0.8.3

package/lib/task/commands/log.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { formatTable } from '../../table.ts';
 import { resolveTaskRef } from '../resolve-ref.ts';
-import { parseLedger, HUMAN_DECISION_STATUSES, type LedgerRow } from '../ledger.ts';
+import { parseLedger, type LedgerRow } from '../ledger.ts';
 
 const USAGE = `Usage: ai task log <N | #N | TASK-id>
 
@@ -14,7 +14,7 @@ Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
   A human-executed step shows AGENT as 'human' and, when it has no start marker,
   a '-' STARTED placeholder. Review-step NOTE also carries two human counts in
   the verdict list, right after blockers/major/minor: manual-validation
-  and human-decision (current ledger stage total).
+  and human-decision (current pending ledger stage total).
 `;
 
 const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const;
@@ -108,7 +108,7 @@ function pairEntries(entries: LogEntry[]): StepRow[] {
 function countHumanDecisionsByStage(rows: LedgerRow[]): Map<ReviewStage, number> {
   const counts = new Map<ReviewStage, number>();
   for (const row of rows) {
-    if (!isReviewStage(row.stage) || !HUMAN_DECISION_STATUSES.has(row.status)) continue;
+    if (!isReviewStage(row.stage) || row.status !== 'needs-human-decision') continue;
     counts.set(row.stage, (counts.get(row.stage) ?? 0) + 1);
   }
   return counts;

package/lib/task/commands/status.ts

@@ -6,7 +6,9 @@ import { resolveTaskRef } from '../resolve-ref.ts';
 import { enumerateArtifacts, type Artifact } from '../artifacts.ts';
 import { parseTaskFrontmatter, extractTitle, type Frontmatter } from '../frontmatter.ts';
 import { loadShortIdByTaskId } from '../short-id.ts';
+import { getOpenWorkflowWarnings, formatWorkflowWarningSummary, type WorkflowWarning } from '../workflow-warnings.ts';
 import { parseActivityLog, pairEntries } from './log.ts';
+import { statusCard, type DisplayMessage } from '../../server/display.ts';
 
 const USAGE = `Usage: ai task status <N | #N | TASK-id>
 
@@ -322,12 +324,28 @@ type StatusModel = {
   shortId: string;
   title: string;
   metadata: [string, string][];
+  workflowWarnings: WorkflowWarning[];
   artifacts: { count: number; groups: { stage: string; files: string[] }[] };
   workflow: WorkflowInfo;
   runtime: RuntimeInfo;
   git: GitInfo;
 };
 
+type BuildStatusModelInput = {
+  taskId: string;
+  taskDir: string;
+  taskMdPath: string;
+  repoRoot: string;
+  shortId?: string;
+  run?: Runner;
+  now?: Date;
+};
+
+type BuildStatusModelOptions = {
+  run?: Runner;
+  now?: Date;
+};
+
 // Indent each label/value pair by two spaces and pad labels to a common width so
 // every section reads as an aligned "key   value" block.
 function renderPairs(rows: [string, string][]): string[] {
@@ -343,6 +361,14 @@ function renderStatus(model: StatusModel): string[] {
 
   lines.push('', 'Metadata', ...renderPairs(model.metadata));
 
+  if (model.workflowWarnings.length > 0) {
+    lines.push(
+      '',
+      `Workflow Warnings (${model.workflowWarnings.length} open)`,
+      ...formatWorkflowWarningSummary(model.workflowWarnings).map((line) => `  ${line}`)
+    );
+  }
+
   lines.push('', `Artifacts (${model.artifacts.count})`);
   if (model.artifacts.groups.length === 0) {
     lines.push('  (none)');
@@ -394,36 +420,89 @@ function renderStatus(model: StatusModel): string[] {
   return lines;
 }
 
-function status(args: string[] = []): void {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    process.stdout.write(USAGE);
-    if (args.length === 0) process.exitCode = 1;
-    return;
-  }
-
-  const resolved = resolveTaskRef(args[0]!);
-  if (!resolved.ok) {
-    process.stderr.write(`ai task status: ${resolved.message}\n`);
-    process.exitCode = 1;
-    return;
+function modelTone(model: StatusModel): 'info' | 'success' | 'warning' | 'danger' | 'running' {
+  if (model.workflow.state === 'in-progress') return model.workflow.stale === 'yes' ? 'warning' : 'running';
+  if (model.metadata.some(([key, value]) => key === 'status' && value === 'completed')) return 'success';
+  if (model.metadata.some(([key, value]) => key === 'status' && (value === 'blocked' || value === 'cancelled'))) {
+    return 'danger';
   }
+  return 'info';
+}
 
-  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+function buildFromResolved(input: BuildStatusModelInput): StatusModel {
+  const content = fs.readFileSync(input.taskMdPath, 'utf8');
   const fm = parseTaskFrontmatter(content);
-  const run = makeRunner(resolved.repoRoot);
-  const artifacts = enumerateArtifacts(resolved.taskDir);
-  const workflow = collectWorkflow(content);
+  const run = input.run ?? makeRunner(input.repoRoot);
+  const artifacts = enumerateArtifacts(input.taskDir);
+  const workflow = collectWorkflow(content, input.now);
 
-  const model: StatusModel = {
-    taskId: resolved.taskId,
-    shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
+  return {
+    taskId: input.taskId,
+    shortId: input.shortId ?? loadShortIdByTaskId(input.repoRoot).get(input.taskId) ?? DASH,
     title: extractTitle(content),
     metadata: collectMetadata(fm),
+    workflowWarnings: getOpenWorkflowWarnings(content),
     artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
     workflow,
-    runtime: collectRuntime(resolved.taskDir, workflow, run),
+    runtime: collectRuntime(input.taskDir, workflow, run),
     git: collectGit(fm.branch ?? '', run)
   };
+}
+
+function buildStatusModel(ref: string, options?: BuildStatusModelOptions): StatusModel;
+function buildStatusModel(input: BuildStatusModelInput): StatusModel;
+function buildStatusModel(
+  refOrInput: string | BuildStatusModelInput,
+  options: BuildStatusModelOptions = {}
+): StatusModel {
+  if (typeof refOrInput !== 'string') {
+    return buildFromResolved(refOrInput);
+  }
+
+  const resolved = resolveTaskRef(refOrInput);
+  if (!resolved.ok) {
+    throw new Error(resolved.message);
+  }
+
+  return buildFromResolved({
+    taskId: resolved.taskId,
+    taskDir: resolved.taskDir,
+    taskMdPath: resolved.taskMdPath,
+    repoRoot: resolved.repoRoot,
+    run: options.run,
+    now: options.now
+  });
+}
+
+function statusModelToDisplay(model: StatusModel): DisplayMessage {
+  return statusCard(
+    `Task ${model.taskId} (${model.shortId})`,
+    modelTone(model),
+    [
+      ['workflow', model.workflow.state],
+      ['step', model.workflow.step],
+      ['runtime', model.runtime.status],
+      ['git', model.git.uncommitted]
+    ],
+    renderStatus(model).join('\n')
+  );
+}
+
+function status(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    if (args.length === 0) process.exitCode = 1;
+    return;
+  }
+
+  let model: StatusModel;
+  try {
+    model = buildStatusModel(args[0]!);
+  } catch (error) {
+    process.stderr.write(`ai task status: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+    return;
+  }
 
   for (const line of renderStatus(model)) {
     process.stdout.write(`${line}\n`);
@@ -433,12 +512,14 @@ function status(args: string[] = []): void {
 export {
   status,
   makeRunner,
+  buildStatusModel,
   collectMetadata,
   groupArtifacts,
   collectGit,
   collectWorkflow,
   collectRuntime,
   renderStatus,
+  statusModelToDisplay,
   METADATA_KEYS
 };
-export type { Runner, GitInfo, WorkflowInfo, RuntimeInfo, StatusModel };
+export type { Runner, GitInfo, WorkflowInfo, RuntimeInfo, StatusModel, BuildStatusModelInput };

package/lib/task/workflow-warnings.ts

@@ -0,0 +1,121 @@
+import { extractSection } from './sections.ts';
+
+const WORKFLOW_WARNING_HEADINGS = ['工作流告警', 'Workflow Warnings'];
+const WORKFLOW_WARNING_STATUSES = new Set(['open', 'resolved', 'ignored']);
+const WORKFLOW_WARNING_SEVERITIES = new Set(['IMPORTANT', 'ACTION_REQUIRED']);
+
+type WorkflowWarning = {
+  id: string;
+  time: string;
+  step: string;
+  severity: string;
+  code: string;
+  status: string;
+  target: string;
+  message: string;
+  action: string;
+  resolvedAt: string;
+  resolution: string;
+};
+
+function splitTableRow(line: string): string[] {
+  let value = line.trim();
+  if (!value.startsWith('|')) return [];
+  value = value.replace(/^\|/, '').replace(/\|$/, '');
+
+  const cells: string[] = [];
+  let cell = '';
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]!;
+    if (char === '|' && !isEscapedAt(value, index)) {
+      cells.push(unescapeTableCell(cell.trim()));
+      cell = '';
+      continue;
+    }
+    cell += char;
+  }
+  cells.push(unescapeTableCell(cell.trim()));
+  return cells;
+}
+
+function unescapeTableCell(value: string): string {
+  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: string, index: number): boolean {
+  let backslashes = 0;
+  for (let cursor = index - 1; cursor >= 0 && value[cursor] === '\\'; cursor -= 1) {
+    backslashes += 1;
+  }
+  return backslashes % 2 === 1;
+}
+
+function isSeparatorRow(cells: string[]): boolean {
+  return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+
+/**
+ * Parses well-formed workflow warning rows. Malformed rows are intentionally
+ * ignored here; validate-artifact is responsible for reporting structure errors.
+ */
+function parseWorkflowWarnings(content: string): WorkflowWarning[] {
+  const section = extractSection(content, WORKFLOW_WARNING_HEADINGS);
+  if (!section) return [];
+
+  const rows: WorkflowWarning[] = [];
+  for (const rawLine of section.split(/\r?\n/)) {
+    const cells = splitTableRow(rawLine);
+    if (cells.length === 0) continue;
+    if ((cells[0] ?? '').toLowerCase() === 'id') continue;
+    if (isSeparatorRow(cells)) continue;
+    if (cells.length < 11) continue;
+
+    rows.push({
+      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] ?? '',
+      resolvedAt: cells[9] ?? '',
+      resolution: cells[10] ?? ''
+    });
+  }
+  return rows;
+}
+
+function getOpenWorkflowWarnings(content: string): WorkflowWarning[] {
+  return parseWorkflowWarnings(content).filter((warning) => warning.status === 'open');
+}
+
+function formatWorkflowWarningSummary(warnings: readonly WorkflowWarning[]): string[] {
+  return warnings.map((warning) => {
+    const target = warning.target ? ` ${warning.target}` : '';
+    const action = warning.action ? ` - ${warning.action}` : '';
+    return `${warning.id} [${warning.severity}] ${warning.code}${target}${action}`;
+  });
+}
+
+export {
+  WORKFLOW_WARNING_HEADINGS,
+  WORKFLOW_WARNING_STATUSES,
+  WORKFLOW_WARNING_SEVERITIES,
+  parseWorkflowWarnings,
+  getOpenWorkflowWarnings,
+  formatWorkflowWarningSummary
+};
+export type { WorkflowWarning };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -67,7 +67,7 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22.20.0",
     "@types/semver": "^7.7.1",
-    "typescript": "~6.0"
+    "typescript": "~7.0"
   },
   "optionalDependencies": {
     "@lydell/node-pty": "^1.2.0-beta.12"

package/templates/.agents/rules/create-issue.github.en.md

@@ -101,7 +101,7 @@ If the final label set is empty, omit the `--label` argument.
 | `feature`, `enhancement` | `Feature` |
 | `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, others | `Task` |
 
-When applying the Issue Type, follow the "Set Issue Type" command in `.agents/rules/issue-pr-commands.md`; first call `gh api orgs/{owner}/issue-types` to list the org's actually available Types, and only set the inferred value when it is present in that list. Failure to set is non-blocking.
+When applying the Issue Type, follow the "Set Issue Type" command in `.agents/rules/issue-pr-commands.md`; only when the owner type is `Organization`, first call `gh api orgs/{owner}/issue-types` to list the org's actually available Types, and only set the inferred value when it is present in that list. User repositories, failed owner type probes, and failed writes are non-blocking.
 
 #### milestone
 
@@ -149,7 +149,7 @@ After success, parse the Issue number from the output (match only the `https://.
 
 ### 6. Set Issue Type (Optional)
 
-Execute only when `has_push=true` and the Issue Type inferred in §4 is in the org's actually available list:
+Execute only when `has_push=true`, the owner type is `Organization`, and the Issue Type inferred in §4 is in the org's actually available list:
 
 ```bash
 gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
@@ -188,4 +188,4 @@ Hand the following back to the caller `create-task`:
 - Auth failure / command unavailable: return a structured `{code: "AUTH_FAILED", message}` to `create-task`; do not modify task.md
 - Network timeout / DNS failure: `{code: "NETWORK", message}`
 - Template parsing failure, Issue number parsing failure, other anomalies: `{code: "VALIDATION", message}`
-- All failures keep task.md untouched; `create-task` takes the "Scenario C: failure fallback" output branch and prompts the user to retry manually or fill `issue_number` later
+- All failures keep task.md untouched; `create-task` must record the structured error in `## Workflow Warnings` (`severity=ACTION_REQUIRED`, `code=ISSUE_CREATE_FAILED`, `target=issue`) before taking the "Scenario C: failure fallback" output branch and prompting the user to retry manually or fill `issue_number` later

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -101,7 +101,7 @@ ai task issue-body {task-id} > "{body-file}"
 | `feature`, `enhancement` | `Feature` |
 | `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 及其它 | `Task` |
 
-实际设置时按 `.agents/rules/issue-pr-commands.md` 的 "设置 Issue Type" 命令；先调 `gh api orgs/{owner}/issue-types` 列出 org 实际可用的 Type，仅当推断值在列表中时才设置；设置失败不阻断流程。
+实际设置时按 `.agents/rules/issue-pr-commands.md` 的 "设置 Issue Type" 命令；仅当 owner type 为 `Organization` 时，先调 `gh api orgs/{owner}/issue-types` 列出 org 实际可用的 Type，并且仅当推断值在列表中时才设置；个人仓库、owner type 探测失败或设置失败都不阻断流程。
 
 #### milestone
 
@@ -149,7 +149,7 @@ gh issue create -R "$upstream_repo" \
 
 ### 6. 设置 Issue Type（可选）
 
-仅当 `has_push=true` 且 §4 推断的 Issue Type 在 org 实际可用列表中时执行：
+仅当 `has_push=true`、owner type 为 `Organization`，且 §4 推断的 Issue Type 在 org 实际可用列表中时执行：
 
 ```bash
 gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
@@ -188,4 +188,4 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 - 认证失败 / 命令不可用：返回结构化错误 `{code: "AUTH_FAILED", message}` 给 `create-task`，不修改 task.md
 - 网络超时 / DNS 失败：`{code: "NETWORK", message}`
 - 模板解析失败、Issue 编号解析失败、其它异常：`{code: "VALIDATION", message}`
-- 任意失败均不回滚 task.md；`create-task` 走"场景 C 失败兜底"输出，提示用户手动重试或在事后写入 `issue_number`
+- 任意失败均不回滚 task.md；`create-task` 必须把结构化错误写入 `## 工作流告警`（`severity=ACTION_REQUIRED`，`code=ISSUE_CREATE_FAILED`，`target=issue`），再走"场景 C 失败兜底"输出，提示用户手动重试或在事后写入 `issue_number`

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -83,11 +83,16 @@ gh issue create -R "$upstream_repo" --title "{title}" --body "{body}" --assignee
 Set the Issue Type:
 
 ```bash
-gh api "orgs/{owner}/issue-types" --jq '.[].name'
-gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-type}" --silent
+owner_type=$(gh api "repos/$upstream_repo" --jq '.owner.type // empty' 2>/dev/null || true)
+if [ "$owner_type" = "Organization" ]; then
+  owner=${upstream_repo%%/*}
+  gh api "orgs/$owner/issue-types" --jq '.[].name'
+  gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-type}" --silent
+fi
 ```
 
 - set the Issue Type only when `has_push=true`; otherwise skip and continue
+- query and set Issue Type only when the owner type is `Organization`; skip and continue for user repositories or failed owner type probes
 - when changing an existing Issue Type, read `.agents/rules/issue-fields.md` and use Flow B so same-name pinned fields are migrated and fields absent from the new type are cleared
 
 ## Update Issues

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

@@ -83,11 +83,16 @@ gh issue create -R "$upstream_repo" --title "{title}" --body "{body}" --assignee
 设置 Issue Type：
 
 ```bash
-gh api "orgs/{owner}/issue-types" --jq '.[].name'
-gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-type}" --silent
+owner_type=$(gh api "repos/$upstream_repo" --jq '.owner.type // empty' 2>/dev/null || true)
+if [ "$owner_type" = "Organization" ]; then
+  owner=${upstream_repo%%/*}
+  gh api "orgs/$owner/issue-types" --jq '.[].name'
+  gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-type}" --silent
+fi
 ```
 
 - 仅当 `has_push=true` 时执行 Issue Type 设置；否则跳过并继续
+- 仅当 owner type 为 `Organization` 时查询和设置 Issue Type；个人仓库或 owner type 探测失败时跳过并继续
 - 变更现有 Issue Type 时，先读取 `.agents/rules/issue-fields.md` 并使用流程 B，确保同名 pinned fields 迁移，且新 type 不包含的字段被清空
 
 ## Issue 更新

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

@@ -66,6 +66,17 @@ Key rules:
 - insufficient permission only affects direct Issue metadata writes and must not stop the skill
 - keep the existing `2>/dev/null || true` error-tolerance pattern
 
+When the caller has a `{task-id}` / task directory, permission degradation or critical sync failure must be recorded in `## Workflow Warnings`:
+
+```bash
+node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
+  --step issue-sync --severity IMPORTANT --code PERMISSION_DEGRADED \
+  --target "{operation}" --message "{reason}" \
+  --action "Wait for the bot/maintainer to backfill, or rerun the workflow step after permissions are available"
+```
+
+Comment create/update failures and exhausted network retries that affect reviewer visibility use `severity=ACTION_REQUIRED` with `code=COMMENT_SYNC_FAILED` or `NETWORK_RETRY_EXHAUSTED`.
+
 ## External Contributor Locking
 
 Maintainers (`has_triage=true`) are never blocked. External contributors (`has_triage=false`) must check whether the current task already has a `task` comment author on the Issue before they start.
@@ -210,6 +221,8 @@ EOF
 
 Comment publishing is not gated by `has_triage` or `has_push`.
 
+If comment lookup, creation, or update fails and the caller has a task directory, record a Workflow Warning (`step=issue-sync`, `severity=ACTION_REQUIRED`, `code=COMMENT_SYNC_FAILED`, `target={file-stem}`) and surface it in the final Workflow Warnings output block.
+
 ## task.md Comment Sync
 
 Hidden marker:

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

@@ -66,6 +66,17 @@ has_push=$(printf '%s' "$repo_perms" | grep -q '"push":true' 2>/dev/null && echo
 - 权限不足只影响直接写 Issue 元数据的步骤，不中断整个技能
 - 现有 `2>/dev/null || true` 容错模式保持不变
 
+当调用方存在 `{task-id}` / task 目录时，权限降级或关键同步失败必须写入 `## 工作流告警`：
+
+```bash
+node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
+  --step issue-sync --severity IMPORTANT --code PERMISSION_DEGRADED \
+  --target "{operation}" --message "{reason}" \
+  --action "等待 bot/维护者补位，或在具备权限后重跑对应 workflow 步骤"
+```
+
+评论创建 / 更新失败、网络重试耗尽等影响后续 reviewer 可见性的失败使用 `severity=ACTION_REQUIRED` 和 `code=COMMENT_SYNC_FAILED` 或 `NETWORK_RETRY_EXHAUSTED`。
+
 ## 外部开发者锁定机制
 
 维护者（`has_triage=true`）不受限制。外部开发者（`has_triage=false`）在开始任务前，必须先检查 Issue 上是否已有当前任务的 `task` 留言作者。
@@ -210,6 +221,8 @@ EOF
 
 评论发布不受 `has_triage` / `has_push` 限制，认证用户可正常执行。
 
+若评论查询、创建或更新失败且调用方有关联任务目录，记录 Workflow Warning（`step=issue-sync`、`severity=ACTION_REQUIRED`、`code=COMMENT_SYNC_FAILED`、`target={file-stem}`），并在最终输出的 Workflow Warnings 块提示人工处理。
+
 ## task.md 评论同步
 
 隐藏标记：

package/templates/.agents/rules/next-step-output.en.md

@@ -1,10 +1,11 @@
 # Next-Step Output Rule
 
-This file defines three **independent** rules for a skill's "notify-user / Next steps" output (the 3rd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
+This file defines four **independent** rules for a skill's "notify-user / Next steps" output (the 3rd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
 
 1. **Next-step output structure**: how "Next steps" commands and the "Task info" block present the task ID (placeholders / short-id lookup / fallback).
 2. **Agent output trailing line (Completed at)**: the **very last line** of user-facing output, **independent of the "Next steps" block**, applying to normal / error / early-return paths alike.
 3. **Pending human-decision pre-block**: applies only to `review-analysis` / `review-plan` / `review-code` when this stage has pending rulings (`{h} > 0`) — expand the pending items before the "Next steps" commands and prompt to resolve them first.
+4. **Workflow Warnings output block**: applies when task.md has `status=open` rows in `## Workflow Warnings` — print the warning summary after all normal information and "Next steps" commands, and before `Completed at`.
 
 ## Placeholder semantics
 
@@ -62,6 +63,19 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the manual-validation reminder), the completion line goes after that reminder.
 - This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.
 
+## Workflow Warnings Output Block
+
+If the current task's `## Workflow Warnings` / `## 工作流告警` table has any `status=open` row, the skill's final user output must append a summary block after all normal information and "Next steps" commands, and before `Completed at`. When no open warning exists, do not render this block.
+
+Format:
+
+```text
+[ACTION REQUIRED] Workflow warnings are open:
+  - WW-N {code} ({target}): {action}
+```
+
+Use `[ACTION REQUIRED]` when any open row has `severity=ACTION_REQUIRED`; otherwise use `[IMPORTANT]`. `{code}`, `{target}`, and `{action}` come directly from the warning table columns.
+
 ## Pending human-decision pre-block (review-* only, when {h} > 0)
 
 This section is a **third standalone rule, co-equal with the two above**, used only by the "notify-user / report conclusion" step of `review-analysis` / `review-plan` / `review-code`.

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: