@fitlab-ai/agent-infra 0.8.2 → 0.8.4

package/templates/.agents/README.en.md

@@ -165,11 +165,14 @@ Recommended frontmatter:
 name: enforce-style
 description: "Apply the team style guide before code review. Use when you need to align the team's code style before review"
 args: "<task-id>"   # optional
+disable-model-invocation: true   # optional; consumed by supporting TUI adapters
 ---
 ```
 
 Write `description` as "one-line responsibility + scenario clause": after the short responsibility, append "Use when …" (the Chinese `SKILL.zh-CN.md` variant uses "当……时使用") as the cross-TUI trigger semantics, so Agent Skills-capable tools can self-discover the skill in natural conversation. Do **not** add a separate `triggers` (or similar) frontmatter field for this.
 
+Set the generic optional `disable-model-invocation` field to `true` when generated TUI commands should disable model invocation; each TUI adapter consumes it according to its capabilities. To preserve line breaks in a multiline `description`, use a YAML literal block (`|`); sync emits the corresponding multiline metadata format for each TUI.
+
 After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
 
 ### Shared skill sources

package/templates/.agents/README.zh-CN.md

@@ -165,11 +165,14 @@
 name: enforce-style
 description: "在代码审查前应用团队风格规范。当需要在评审前统一团队代码风格时使用"
 args: "<task-id>"   # 可选
+disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器消费
 ---
 ```
 
 `description` 采用「一句话职责 + 场景触发子句」写法：在简短职责描述后补充「当……时使用」（英文 `SKILL.en.md` 用「Use when …」），作为跨 TUI 的触发语义，供支持 Agent Skills 的工具在自然对话中自发现该 skill。**不要**为此新增 `triggers` 等额外 frontmatter 字段。
 
+当生成的 TUI 命令需要禁用模型调用时，将通用可选字段 `disable-model-invocation` 设为 `true`；各 TUI 适配器按自身能力决定是否消费。多行 `description` 如需保留换行，使用 YAML literal block（`|`）；同步器会为各 TUI 输出对应的多行元数据格式。
+
 新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
 
 ### 共享 skill 源

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 \
@@ -169,7 +169,7 @@ Field write failures are non-blocking.
 Update task.md:
 
 - Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
-- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
+- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`)
 
 > Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Create Task`), written by the caller SKILL step 3.
 
@@ -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 \
@@ -169,7 +169,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 更新 task.md：
 
 - 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
-- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
+- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`）
 
 > 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Create Task`），由调用方 SKILL 步骤 3 写入。
 
@@ -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:

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/review-handshake.en.md

@@ -85,8 +85,8 @@ When an executor judges an item to be a key design decision that needs human rul
 
 ## post-review commit gate (code stage only)
 
-- The highest-round `review-code` report records `Review Baseline Commit` (R, `git rev-parse HEAD`) and `Reviewed Diff Fingerprint` (F, full worktree diff fingerprint).
-- `commit` reads only the highest-round `review-code` artifact. When that artifact is Approved, the pre-commit HEAD equals R, and the staged diff fingerprint equals F, task.md receives `last_reviewed_commit` (B, the new commit SHA).
+- `review-code` captures `Review Baseline Commit` (R, `git rev-parse HEAD`) once, computes `Reviewed Diff Fingerprint` (F, the full worktree diff fingerprint) from that same R, and records both in the highest-round report. When the round is Approved it also writes `last_reviewed_commit: R` (B) to task.md; a non-Approved round preserves the existing B.
+- `commit` reads only the highest-round `review-code` artifact. When that artifact is Approved, the pre-commit HEAD equals R, and the staged diff fingerprint equals F, it advances task.md B to the new commit SHA.
 - The `complete-task` `post-review-commit` gate prefers B; when B is absent or invalid, it falls back to R from the highest-round `review-code` artifact.
 - If new commits touch code / rule paths after B / R, the gate blocks and requires a fresh `review-code`.
 - **Exemption**: append a ledger row `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |` recording that a human explicitly allowed those commits without re-review.

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -85,8 +85,8 @@
 
 ## post-review commit 门禁（仅 code 阶段）
 
-- `review-code` 在最高轮报告中记录 `审查基线提交`（R，`git rev-parse HEAD`）和 `审查差异指纹`（F，完整工作区 diff fingerprint）。
-- `commit` 只读取最高轮 `review-code` 产物；当该产物 Approved、提交前 HEAD 等于 R、且 staged diff fingerprint 等于 F 时，在 task.md 写入 `last_reviewed_commit`（B，新提交 SHA）。
+- `review-code` 一次性捕获 `审查基线提交`（R，`git rev-parse HEAD`），以同一 R 计算 `审查差异指纹`（F，完整工作区 diff fingerprint）并写入最高轮报告；本轮 Approved 时同时在 task.md 写入 `last_reviewed_commit: R`（B），非 Approved 时保留既有 B。
+- `commit` 只读取最高轮 `review-code` 产物；当该产物 Approved、提交前 HEAD 等于 R、且 staged diff fingerprint 等于 F 时，把 task.md 的 B 推进为新提交 SHA。
 - `complete-task` 的 `post-review-commit` gate 优先使用 B；B 缺失或非法时回退最高轮 `review-code` 的 R。
 - 若 B / R 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。

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/rules/testing-discipline.en.md

@@ -39,46 +39,8 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 - **Testing implementation details**: Prefer assertions on public APIs, artifacts, state changes, or error results; avoid assertions on private functions, internal call order, or temporary data structures.
 - **Insufficient assertions**: Assertions must pin down concrete expected values; do not replace checks on key fields, counts, and boundaries with "does not throw" or "result exists".
 
-## Coverage positioning (informational layer)
+## Project-specific test policy
 
-> CI emits coverage via `node --test --experimental-test-coverage` as a hint about "which files are weakly tested". It is **not a merge gate**.
+Keep repository-specific commands, directory conventions, coverage thresholds, CI integration, and reporting services in the project's own test documentation. Before adding a test, inspect that local policy and place the test in the layer that matches its observable scope and runtime cost.
 
-### Local run
-
-```bash
-npm run test:coverage
-```
-
-The tail of stdout prints per-file line / branch / function coverage and the uncovered line numbers.
-
-### CI display
-
-`.github/workflows/unit-tests.yml` writes the coverage block into the GitHub Actions step summary on the ubuntu-latest shard (visible on the PR Checks page). Windows / macOS shards do not duplicate this output.
-
-The Codecov badge at the top of the README is generated by Codecov after `.github/workflows/unit-tests.yml` uploads `coverage.lcov` from the ubuntu-latest shard.
-
-### Boundaries
-
-- **No percentage thresholds**: Threshold flags such as `--test-coverage-lines/branches/functions` are forbidden. Goodhart's law reminds us that once coverage becomes a metric, developers write "coverage-friendly but behavior-weak" tests.
-- **Third-party services for the badge only**: Codecov hosts the README coverage badge, but the root `codecov.yml` explicitly disables its project/patch status checks and PR comments — Codecov only displays a number here and does not participate in merge decisions. Do not integrate other services such as coveralls.
-- **No tier split**: Coverage is currently emitted only for the full `test` tier; smoke / core tier coverage has no independent value.
-- **Does not block PRs**: The CI step uses `continue-on-error: true`, so a failed coverage collection does not affect merges.
-
-### Where New Tests Go
-
-The test directory determines which npm script runs a test file:
-
-- `tests/unit/<module>/`: fast structural or pure-function tests; does not spawn the real CLI process or depend on external tools, suitable for `test:smoke`.
-- `tests/integration/<module>/`: combines multiple modules, runs CLI subprocesses, touches temporary filesystems, or verifies template sync flows while staying stable and reasonably fast, suitable for `test:core`.
-- `tests/e2e/<module>/`: slower contract, platform-sync, packaged-output, cross-process, or end-to-end workflow tests, run only by full `npm test`.
-
-Modules remain as second-level directories such as `cli`, `core`, `scripts`, and `templates`. Shared helpers and fixtures stay in `tests/helpers/`, `tests/helpers.ts`, and `tests/fixtures/`; do not place them under a tier.
-
-### Relation to "test tier coverage"
-
-Distinguish two concepts:
-
-- **Test tier coverage** (`tests/unit/core/test-tier-coverage.test.ts` checks test directory placement and npm script tier mapping): governs "which test files belong to which tier" and is orthogonal to source-line coverage.
-- **Source-line coverage** (this section): governs "which lines of production source are exercised by tests".
-
-The two serve different purposes and should not substitute for each other.
+If the project does not define a layered test suite, use its complete test command for RED and GREEN verification. Do not invent a test hierarchy or coverage gate as part of an unrelated change.

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

@@ -39,46 +39,8 @@ assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 - **测试实现细节**：优先断言公开接口、产物、状态变化或错误结果；避免断言私有函数、内部调用顺序、临时数据结构。
 - **断言不充分**：断言必须锁定具体期望值；不要用"只要不抛异常""结果存在即可"替代对关键字段、数量和边界的验证。
 
-## 覆盖率定位（信息层）
+## 项目级测试策略
 
-> CI 中通过 `node --test --experimental-test-coverage` 输出覆盖率，仅作为"哪些文件被测试薄弱"的提示，**不作为 merge gate**。
+仓库特定的命令、目录约定、覆盖率阈值、CI 集成和报告服务应记录在项目自己的测试文档中。新增测试前先读取该策略，并按测试的可观察范围与运行成本选择对应层级。
 
-### 本地运行
-
-```bash
-npm run test:coverage
-```
-
-stdout 末尾会打印按文件粒度的行 / 分支 / 函数覆盖率以及未覆盖行号。
-
-### CI 展示
-
-`.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上把覆盖率块写入 GitHub Actions 的 step summary（PR Checks 页可见）。Windows / macOS 分片不重复输出。
-
-README 顶部的 Codecov 徽章由 `.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上传 `coverage.lcov` 后由 Codecov 生成。
-
-### 边界
-
-- **不设置百分比阈值**：`--test-coverage-lines/branches/functions` 等阈值参数禁止加入；Goodhart's law 提醒我们一旦把覆盖率作为指标，开发者会写"覆盖率友好但行为弱"的测试。
-- **第三方服务仅用于徽章**：已接入 Codecov 托管 README 覆盖率徽章，但通过根 `codecov.yml` 显式关闭其 project/patch status check 与 PR 评论——Codecov 在本项目只展示数字，不参与 merge 决策。不接入 coveralls 等其他服务。
-- **不区分 tier**：当前只对 full `test` tier 输出覆盖率；smoke / core tier 的覆盖率没有独立价值。
-- **不阻塞 PR**：CI 步骤 `continue-on-error: true`，即便覆盖率采集失败也不影响 merge。
-
-### 新测试该放哪一层
-
-测试文件放入哪一层决定它会被哪些 npm script 自动执行：
-
-- `tests/unit/<module>/`：快速、结构性或纯函数类测试；不启动真实 CLI 子进程，不依赖外部工具，适合 `test:smoke`。
-- `tests/integration/<module>/`：会组合多个模块、运行 CLI 子进程、触达临时文件系统或验证模板同步流程，但仍应保持稳定和相对快速，适合 `test:core`。
-- `tests/e2e/<module>/`：较慢的契约、平台同步、打包产物、跨进程或端到端流程测试，只在完整 `npm test` 中运行。
-
-模块继续作为第二级目录（如 `cli`、`core`、`scripts`、`templates`）。共享 helper 和 fixtures 保持在 `tests/helpers/`、`tests/helpers.ts`、`tests/fixtures/`，不要放入任一 tier。
-
-### 与"测试 tier 覆盖"的关系
-
-注意区分两个概念：
-
-- **测试 tier 覆盖**（`tests/unit/core/test-tier-coverage.test.ts` 校验测试文件目录归属与 npm script tier 映射）：管的是"哪些测试文件被纳入哪一 tier"，与代码行覆盖率正交。
-- **代码行覆盖率**（本节）：管的是"业务源码哪些行被测试触达"。
-
-两者目的不同，不要相互替代。
+如果项目没有定义分层测试套件，RED 与 GREEN 验证都使用项目的完整测试命令。不要在无关改动中自行引入测试层级或覆盖率门禁。