@fitlab-ai/agent-infra 0.8.2 → 0.8.3

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];

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);
+}