@fitlab-ai/agent-infra 0.7.1 → 0.7.3

package/templates/.agents/skills/review-code/reference/output-templates.zh-CN.md

@@ -43,9 +43,9 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修复问题后提交（推荐）：
-  - Claude Code / OpenCode：/code-task {task-id}
-  - Gemini CLI：/agent-infra:code-task {task-id}
-  - Codex CLI：$code-task {task-id}
+  - Claude Code / OpenCode：/code-task {task-ref}
+  - Gemini CLI：/agent-infra:code-task {task-ref}
+  - Codex CLI：$code-task {task-ref}
 
 或直接提交（跳过修复）：
   - Claude Code / OpenCode：/commit
@@ -64,9 +64,9 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修复问题：
-  - Claude Code / OpenCode：/code-task {task-id}
-  - Gemini CLI：/agent-infra:code-task {task-id}
-  - Codex CLI：$code-task {task-id}
+  - Claude Code / OpenCode：/code-task {task-ref}
+  - Gemini CLI：/agent-infra:code-task {task-ref}
+  - Codex CLI：$code-task {task-ref}
 
 [当 env-blocked > 0 时，在最后附加一行：]
 提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /code-task。
@@ -80,9 +80,9 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 重新设计技术方案：
-  - Claude Code / OpenCode：/plan-task {task-id}
-  - Gemini CLI：/agent-infra:plan-task {task-id}
-  - Codex CLI：$plan-task {task-id}
+  - Claude Code / OpenCode：/plan-task {task-ref}
+  - Gemini CLI：/agent-infra:plan-task {task-ref}
+  - Codex CLI：$plan-task {task-ref}
 
 > 注意：Rejected 表示实现方向需要整体重做，不是局部修复。`code-task/scripts/detect-mode.js` 分支 #7 会拒绝直接 `/code-task`，要求先重新方案设计。
 

package/templates/.agents/skills/review-code/reference/report-template.en.md

@@ -61,7 +61,7 @@ Use this template when writing `review-code.md` or `review-code-r{N}.md`.
 
 ## Evidence
 
-> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present.
+> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present. Every Blocker must be backed by a reproducible command (rg/grep/sed/nl) and its raw output; a judgment that cannot be reproduced must be downgraded or moved to Self-Doubt.
 
 - Claim: {verified claim}
 ```text
@@ -69,6 +69,12 @@ $ {command}
 {raw output}
 ```
 
+## Self-Doubt
+
+> Explicitly declare conclusions, inferences, and assumptions in this review that were **not directly verified**; downstream can rebut them on this basis. Write "None" if there are none.
+
+- {an unverified conclusion or inference; note why it was not verified and the impact if it is overturned}
+
 ## Highlights
 
 - {what went well}

package/templates/.agents/skills/review-code/reference/report-template.zh-CN.md

@@ -62,7 +62,7 @@
 
 ## 证据原文
 
-> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。
+> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。每条 Blocker 必须配可复现命令（rg/grep/sed/nl）及其原文；无法复现的判断须降级或移入「自我质疑」。
 
 - 断言：{verified claim}
 ```text
@@ -70,6 +70,12 @@ $ {command}
 {raw output}
 ```
 
+## 自我质疑
+
+> 显式声明本轮审查中**未直接验证**的结论、推断项与所作假设；下游据此可反驳。无则写「（无）」。
+
+- {未直接验证的结论或推断；说明为何未验证、若被推翻的影响}
+
 ## 亮点
 
 - {what went well}

package/templates/.agents/skills/review-code/reference/review-criteria.en.md

@@ -14,11 +14,13 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 - [ ] Performance and security risks
 - [ ] Comments and documentation
 - [ ] Consistency with the approved technical plan
+- [ ] Every blocker is backed by reproducible grep/sed/nl evidence; conclusions not directly verified are declared under Self-Doubt
 
 **Common anti-examples**:
 - Checking only whether tests pass without reading the actual diff
 - Treating wording preferences as reproducible code problems
 - Misclassifying environment-limited verification gaps as blockers
+- Asserting a `file:line` or behavior from memory or impression without verifying via rg/nl
 
 ## Common Review Principles
 

package/templates/.agents/skills/review-code/reference/review-criteria.zh-CN.md

@@ -14,11 +14,13 @@
 - [ ] 性能与安全风险
 - [ ] 代码注释和文档
 - [ ] 与已批准技术方案的一致性
+- [ ] 每条 blocker 都配可复现的 grep/sed/nl 证据，未直接验证的结论已在「自我质疑」声明
 
 **常见反例**：
 - 只检查测试是否通过，没有阅读实际 diff
 - 用自然语言措辞偏好替代可复现的代码问题
 - 把环境缺失导致无法验证的事项误归类为 blocker
+- 凭印象或记忆断言 `file:line`/行为，没有用 rg/nl 复核就下结论
 
 ## 通用审查原则
 

package/templates/.agents/skills/review-plan/SKILL.en.md

@@ -28,7 +28,7 @@ tail .agents/workspace/active/{task-id}/task.md
 
 ## Task id short ref
 
-> If `{task-id}` begins with `#`, follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
 ## Steps
 
@@ -65,7 +65,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 ```
 
 Set `current_step` to `technical-design-review`, refresh task metadata, and append:
-`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {review-artifact}`
+`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {review-artifact}`
 
 If task.md has a valid `issue_number`, read `.agents/rules/issue-sync.md`, sync the task comment, and publish the `{review-artifact}` comment.
 
@@ -78,3 +78,5 @@ node .agents/scripts/validate-artifact.js gate review-plan .agents/workspace/act
 ### 8. Tell the User
 
 Use the conclusion branch in `reference/output-templates.md` and show all TUI command formats.
+
+> Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `#NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).

package/templates/.agents/skills/review-plan/SKILL.zh-CN.md

@@ -30,7 +30,7 @@ tail .agents/workspace/active/{task-id}/task.md
 
 ## 任务入参短号别名
 
-> 如果 `{task-id}` 入参以 `#` 开头，先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
 ## 执行步骤
 ### 1. 验证前置条件
@@ -76,7 +76,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `updated_at`：{当前时间}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
 - 追加：
-  `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {review-artifact}`
+  `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {review-artifact}`
 
 如果 task.md 中存在有效的 `issue_number`，执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测，然后同步 task 评论并发布 `{review-artifact}` 评论。
 
@@ -92,6 +92,8 @@ node .agents/scripts/validate-artifact.js gate review-plan .agents/workspace/act
 
 按 `reference/output-templates.md` 的结论分支输出，并展示所有 TUI 的下一步命令。
 
+> 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `#NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
 ## 完成检查清单
 
 - [ ] 已审查最新方案上下文

package/templates/.agents/skills/review-plan/config/verify.en.json

@@ -23,7 +23,8 @@
         "Environment-Blocked Findings",
         "Conclusion and Recommendations",
         "State Check",
-        "Evidence"
+        "Evidence",
+        "Self-Doubt"
       ],
       "required_patterns": [
         "^### Approval Decision$",
@@ -32,7 +33,7 @@
       "freshness_minutes": 30
     },
     "activity-log": {
-      "expected_action_pattern": "Plan Review \\(Round \\d+\\)",
+      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)",
       "freshness_minutes": 30
     },
     "platform-sync": {

package/templates/.agents/skills/review-plan/config/verify.zh-CN.json

@@ -23,7 +23,8 @@
         "环境性遗留",
         "结论与建议",
         "状态核对",
-        "证据原文"
+        "证据原文",
+        "自我质疑"
       ],
       "required_patterns": [
         "^### 审查决定$",
@@ -32,7 +33,7 @@
       "freshness_minutes": 30
     },
     "activity-log": {
-      "expected_action_pattern": "Plan Review \\(Round \\d+\\)",
+      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)",
       "freshness_minutes": 30
     },
     "platform-sync": {

package/templates/.agents/skills/review-plan/reference/output-templates.en.md

@@ -25,9 +25,9 @@ Task {task-id} technical plan review completed. Verdict: approved.
 [- Review report: .agents/workspace/active/{task-id}/{review-artifact}]
 
 Next step - write code:
-  - Claude Code / OpenCode: /code-task {task-id}
-  - Gemini CLI: /agent-infra:code-task {task-id}
-  - Codex CLI: $code-task {task-id}
+  - Claude Code / OpenCode: /code-task {task-ref}
+  - Gemini CLI: /agent-infra:code-task {task-ref}
+  - Codex CLI: $code-task {task-ref}
 
 [When env-blocked > 0, append:]
 Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -41,14 +41,14 @@ Task {task-id} technical plan review completed. Verdict: approved.
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - revise plan before coding (recommended):
-  - Claude Code / OpenCode: /plan-task {task-id}
-  - Gemini CLI: /agent-infra:plan-task {task-id}
-  - Codex CLI: $plan-task {task-id}
+  - Claude Code / OpenCode: /plan-task {task-ref}
+  - Gemini CLI: /agent-infra:plan-task {task-ref}
+  - Codex CLI: $plan-task {task-ref}
 
 Or proceed directly to coding:
-  - Claude Code / OpenCode: /code-task {task-id}
-  - Gemini CLI: /agent-infra:code-task {task-id}
-  - Codex CLI: $code-task {task-id}
+  - Claude Code / OpenCode: /code-task {task-ref}
+  - Gemini CLI: /agent-infra:code-task {task-ref}
+  - Codex CLI: $code-task {task-ref}
 
 [When env-blocked > 0, append:]
 Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -62,9 +62,9 @@ Task {task-id} technical plan review completed. Verdict: changes requested.
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - revise technical plan:
-  - Claude Code / OpenCode: /plan-task {task-id}
-  - Gemini CLI: /agent-infra:plan-task {task-id}
-  - Codex CLI: $plan-task {task-id}
+  - Claude Code / OpenCode: /plan-task {task-ref}
+  - Gemini CLI: /agent-infra:plan-task {task-ref}
+  - Codex CLI: $plan-task {task-ref}
 
 [When env-blocked > 0, append:]
 Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -78,9 +78,9 @@ Task {task-id} technical plan review completed. Verdict: rejected, redesign requ
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - redesign:
-  - Claude Code / OpenCode: /plan-task {task-id}
-  - Gemini CLI: /agent-infra:plan-task {task-id}
-  - Codex CLI: $plan-task {task-id}
+  - Claude Code / OpenCode: /plan-task {task-ref}
+  - Gemini CLI: /agent-infra:plan-task {task-ref}
+  - Codex CLI: $plan-task {task-ref}
 
 [When env-blocked > 0, append:]
 Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.

package/templates/.agents/skills/review-plan/reference/output-templates.zh-CN.md

@@ -25,9 +25,9 @@
 [- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}]
 
 下一步 - 编写代码：
-  - Claude Code / OpenCode：/code-task {task-id}
-  - Gemini CLI：/agent-infra:code-task {task-id}
-  - Codex CLI：$code-task {task-id}
+  - Claude Code / OpenCode：/code-task {task-ref}
+  - Gemini CLI：/agent-infra:code-task {task-ref}
+  - Codex CLI：$code-task {task-ref}
 
 [当 env-blocked > 0 时，在最后附加一行：]
 提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -41,14 +41,14 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修订方案后编码（推荐）：
-  - Claude Code / OpenCode：/plan-task {task-id}
-  - Gemini CLI：/agent-infra:plan-task {task-id}
-  - Codex CLI：$plan-task {task-id}
+  - Claude Code / OpenCode：/plan-task {task-ref}
+  - Gemini CLI：/agent-infra:plan-task {task-ref}
+  - Codex CLI：$plan-task {task-ref}
 
 或直接进入编码：
-  - Claude Code / OpenCode：/code-task {task-id}
-  - Gemini CLI：/agent-infra:code-task {task-id}
-  - Codex CLI：$code-task {task-id}
+  - Claude Code / OpenCode：/code-task {task-ref}
+  - Gemini CLI：/agent-infra:code-task {task-ref}
+  - Codex CLI：$code-task {task-ref}
 
 [当 env-blocked > 0 时，在最后附加一行：]
 提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -62,9 +62,9 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修订技术方案：
-  - Claude Code / OpenCode：/plan-task {task-id}
-  - Gemini CLI：/agent-infra:plan-task {task-id}
-  - Codex CLI：$plan-task {task-id}
+  - Claude Code / OpenCode：/plan-task {task-ref}
+  - Gemini CLI：/agent-infra:plan-task {task-ref}
+  - Codex CLI：$plan-task {task-ref}
 
 [当 env-blocked > 0 时，在最后附加一行：]
 提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -78,9 +78,9 @@
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 重新设计：
-  - Claude Code / OpenCode：/plan-task {task-id}
-  - Gemini CLI：/agent-infra:plan-task {task-id}
-  - Codex CLI：$plan-task {task-id}
+  - Claude Code / OpenCode：/plan-task {task-ref}
+  - Gemini CLI：/agent-infra:plan-task {task-ref}
+  - Codex CLI：$plan-task {task-ref}
 
 [当 env-blocked > 0 时，在最后附加一行：]
 提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。

package/templates/.agents/skills/review-plan/reference/report-template.en.md

@@ -61,7 +61,7 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 
 ## Evidence
 
-> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present.
+> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present. Every Blocker must be backed by a reproducible command (rg/grep/sed/nl) and its raw output; a judgment that cannot be reproduced must be downgraded or moved to Self-Doubt.
 
 - Claim: {verified claim}
 ```text
@@ -69,6 +69,12 @@ $ {command}
 {raw output}
 ```
 
+## Self-Doubt
+
+> Explicitly declare conclusions, inferences, and assumptions in this review that were **not directly verified**; downstream can rebut them on this basis. Write "None" if there are none.
+
+- {an unverified conclusion or inference; note why it was not verified and the impact if it is overturned}
+
 ## Highlights
 
 - {what went well}

package/templates/.agents/skills/review-plan/reference/report-template.zh-CN.md

@@ -62,7 +62,7 @@
 
 ## 证据原文
 
-> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。
+> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。每条 Blocker 必须配可复现命令（rg/grep/sed/nl）及其原文；无法复现的判断须降级或移入「自我质疑」。
 
 - 断言：{verified claim}
 ```text
@@ -70,6 +70,12 @@ $ {command}
 {raw output}
 ```
 
+## 自我质疑
+
+> 显式声明本轮审查中**未直接验证**的结论、推断项与所作假设；下游据此可反驳。无则写「（无）」。
+
+- {未直接验证的结论或推断；说明为何未验证、若被推翻的影响}
+
 ## 亮点
 
 - {what went well}

package/templates/.agents/skills/review-plan/reference/review-criteria.en.md

@@ -13,11 +13,13 @@ Follow the `design-review` step in `.agents/workflows/feature-development.yaml`.
 - [ ] Test strategy covers critical paths, regression risks, and edge cases
 - [ ] Risks, migration, rollback, or compatibility handling are sufficient
 - [ ] The plan avoids over-design and unrelated scope expansion
+- [ ] Every blocker is backed by reproducible grep/sed/nl evidence; conclusions not directly verified are declared under Self-Doubt
 
 **Common anti-examples**:
 - Saying "modify related code" without executable steps and verification points
 - Ignoring risks or constraints listed in the analysis
 - Introducing unnecessary abstractions, configuration, or frameworks for a single-use requirement
+- Asserting a `file:line` or behavior from memory or impression without verifying via rg/nl
 
 ## Common Review Principles
 

package/templates/.agents/skills/review-plan/reference/review-criteria.zh-CN.md

@@ -13,11 +13,13 @@
 - [ ] 测试策略是否覆盖关键路径、回归风险和边界情况
 - [ ] 风险、迁移、回滚或兼容性处理是否充分
 - [ ] 方案是否避免过度设计和无关扩张
+- [ ] 每条 blocker 都配可复现的 grep/sed/nl 证据，未直接验证的结论已在「自我质疑」声明
 
 **常见反例**：
 - 方案只写“修改相关代码”，没有可执行步骤和验证点
 - 设计没有回应分析中列出的风险或约束
 - 为单次需求引入不必要的新抽象、配置或框架
+- 凭印象或记忆断言 `file:line`/行为，没有用 rg/nl 复核就下结论
 
 ## 通用审查原则
 

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -23,7 +23,6 @@ const DEFAULTS = {
   "platform": {
     "type": "github"
   },
-  "requiresPullRequest": true,
   "sandbox": {
     "engine": null,
     "runtimes": [

package/templates/.agents/skills/watch-pr/SKILL.en.md

@@ -0,0 +1,131 @@
+---
+name: watch-pr
+description: "Watch a PR's required checks and self-heal on failure"
+---
+
+# Watch Pull Request
+
+After `create-pr`, continuously watch the PR's required CI checks: when everything is green, guide toward merge; when a required check fails, pull the logs, fix and push locally, then re-poll; when the fix attempt limit is reached or the failure is non-code / unlocatable, stop and ask the user for help. Platform-specific commands live in `.agents/rules/pr-checks-commands.md`; this skill body stays platform-agnostic.
+
+## Behavior Boundaries / Key Rules
+
+- Only watch + self-heal the current PR's required checks; make no changes unrelated to the failing check.
+- Self-heal modifies code and `git push`es to the PR branch, but **local tests for the affected area must pass before pushing**; fix attempts have a hard cap (default 2); only self-heal locatable code-layer failures (lint / format / test / type / build), and always route non-code failures (network / permission / external service / flaky) to the help exit.
+- The help exit is "produce-then-stop": end this round, output the blocker explanation, and wait for the user to trigger the next step — **never** ask mid-flow.
+- Bare numbers / `#NN` / `TASK-id` arguments are always resolved as task short ids (see `.agents/rules/task-short-id.md`); a PR number is passed only via `--pr <number>` / a PR URL / omission (current branch), never reusing the bare-number syntax.
+- After running this skill (task-anchored path), you must update task.md.
+
+Version stamp rule: before creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` and write or refresh `agent_infra_version`.
+
+## Task Argument Short-ID Alias
+
+> If the `{task-id}` argument matches `^[#]?[0-9]+$` (a bare number or `#`-prefixed), first read the "SKILL argument parsing" section of `.agents/rules/task-short-id.md` to resolve it; subsequent commands treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form.
+
+## Steps
+
+### 1. Resolve Arguments
+
+Resolve the target PR number `{pr#}` and an optional `{task-id}` via these deterministic branches:
+
+- Scenario A (argument omitted): use the current branch's PR number per `.agents/rules/pr-checks-commands.md`; then determine `{task-id}` via "Reverse-lookup task" below.
+- Scenario B (`#NN` / bare number / `TASK-id`, **task-anchored primary path**): when matching `^[#]?[0-9]+$`, resolve to the full `{task-id}` via "Task Argument Short-ID Alias" (on failure pass through the exit code; do not rewrite error handling); a `TASK-id` is used directly. Read `.agents/workspace/active/{task-id}/task.md` for `pr_number` as `{pr#}`; if `pr_number` is empty, follow "Error Handling" to prompt running `create-pr` first, then stop.
+- Scenario C (`--pr <number>` or a PR URL): use that PR number directly as `{pr#}`; then determine `{task-id}` via "Reverse-lookup task".
+- Reverse-lookup task (scenarios A / C): search `.agents/workspace/active/*/task.md` for a task whose `pr_number == {pr#}`; on a hit, take that `{task-id}` (task-anchored); on a miss, enter the "watch-only" degraded path (no `{task-id}`, skip steps 5/6).
+
+### 2. Watch Required Checks
+
+Before running this step, read `reference/monitor-and-heal.md` and `.agents/rules/pr-checks-commands.md`.
+
+Using the watch command in `.agents/rules/pr-checks-commands.md`, poll `{pr#}`'s required checks (with an overall time cap, default 30 minutes), and classify the outcome per the "Outcome Classification" of `reference/monitor-and-heal.md` into the "all green" / "failure" / "pending" scenarios, routing to step 7 (green exit), step 3 (self-heal), or step 4 (help exit) respectively.
+
+### 3. Failure Self-Heal Loop
+
+Before running this step, read the "Self-Heal Decision Tree" of `reference/monitor-and-heal.md` and "Resolve a Failing Run id and Pull Logs" of `.agents/rules/pr-checks-commands.md`.
+
+For a failing check: first deterministically resolve its failing run and pull the failure logs per the rule, then classify the failure; only when it is a locatable code-layer failure, make a minimal local fix, run the relevant tests until they pass, then **stage, commit, and push the fix** (`git add` only the related files → `git commit` per `.agents/rules/commit-and-pr.md` → `git push` to the current PR branch, recording the commit SHA), and return to step 2 to re-watch. Count fix attempts; on reaching the hard cap (default 2) or when the run is unlocatable, go to step 4.
+
+### 4. Help Exit (Produce-Then-Stop)
+
+When self-heal hits the cap, the failure is non-code, the run id is unlocatable, or step 2 times out while pending, stop this round and summarize for the user: the blocker, the fixes attempted (including each fix commit), and the relevant failing job and run/log links (report shape in the "Help report template" of `reference/monitor-and-heal.md`). Do **not** render a next-step command; wait for the user. Then, on the task-anchored path, run steps 5/6 to record this round's outcome.
+
+### 5. Update Task State
+
+> Task-anchored path only; the "watch-only" degraded path skips this step and step 6.
+
+Get the current time:
+
+```bash
+date "+%Y-%m-%d %H:%M:%S%:z"
+```
+
+Update `.agents/workspace/active/{task-id}/task.md`:
+- `assigned_to`: {current agent}
+- `updated_at`: {current time}
+- `agent_infra_version`: per `.agents/rules/version-stamp.md`
+- **Do not change** `pr_status` (keep `created`) or `current_step`
+- **Append** to `## Activity Log` (do not overwrite prior entries; `{N}` = number of existing Watch PR entries for this task + 1):
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Watch PR (Round {N})** by {agent} — {green: all required checks green / blocked: blocked: {summary}}
+  ```
+
+### 6. Verification Gate
+
+> Task-anchored path only.
+
+Run the verification gate:
+
+```bash
+node .agents/scripts/validate-artifact.js gate watch-pr .agents/workspace/active/{task-id} --format text
+```
+
+Handle the result:
+- exit code 0 (all passed) -> continue to "Inform User"
+- exit code 1 (verification failed) -> fix per the output and re-run the gate
+- exit code 2 (network interruption) -> stop and tell the user manual intervention is needed
+
+Keep the gate output in your reply as the verification evidence. Without current gate output, do not declare completion.
+
+### 7. Inform User
+
+> On the task-anchored path, execute this step only after the gate passes.
+
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+
+Output per scenario:
+- "All green" + task-anchored: state that all required checks passed and the PR is ready to merge, then render the next step from the template below (`{task-ref}` becomes the short id):
+
+  ```
+  Next step - Complete and archive the task:
+    - Claude Code / OpenCode: /complete-task {task-ref}
+    - Gemini CLI: /agent-infra:complete-task {task-ref}
+    - Codex CLI: $complete-task {task-ref}
+  ```
+
+- "All green" + watch-only: state the PR is ready to merge; there is no linked task this run, so run `complete-task` against the relevant task (do not force a short-id command block when no `{task-ref}` is available).
+- "Blocked": output only the step 4 blocker explanation; do not recommend a next-step command.
+
+## Completion Checklist
+
+- [ ] Resolved the target PR (and any task context)
+- [ ] Completed required-checks watching with an all-green / blocked conclusion
+- [ ] Self-heal limited to locatable code-layer failures, with local tests passing before push and within the fix cap
+- [ ] Task-anchored path: updated task.md and appended the Watch PR Activity Log entry
+- [ ] Task-anchored path: verification gate passed
+- [ ] Showed the user all TUI next-step command formats (green exit; the blocked exit renders no next step)
+
+## Stop
+
+Stop immediately after the checklist. The green exit waits for the user to run `complete-task`; the blocked exit waits for the user's decision.
+
+## Notes
+
+1. **Precondition**: the PR exists (created by `create-pr`, or locatable via explicit `--pr` / the current branch).
+2. **Bare numbers are always task short ids**: do not treat a bare number as a PR number; use `--pr <number>` for a PR number.
+3. **Self-heal safety**: local tests must pass before pushing; always ask for help on non-code / unlocatable failures rather than blindly retrying.
+4. **Re-runnable**: watch-pr may run multiple times within a task lifecycle; the Round count increments by the number of existing Watch PR Activity Log entries.
+
+## Error Handling
+
+- Cannot locate a PR (task short id resolves but task.md has no `pr_number`, and no `--pr` was passed and the current branch has no PR): prompt "Run `create-pr` first, or specify the PR with `--pr <number>`", then stop.
+- Platform CLI not authenticated or API unavailable: prompt that manual intervention is needed, then stop.
+- Short-id resolution failure: pass through `task-short-id.js`'s exit code and error message; do not rewrite it.