@fitlab-ai/agent-infra 0.7.1 → 0.7.3

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

@@ -62,6 +62,14 @@ $ {command}
 
 {describe any deviation from the approved plan}
 
+## Per-Finding Verification
+
+> Fix mode only; for an initial implementation write "(initial implementation this round, no review findings)". Read/Grep-verify each finding of the previous `review-code` before acting on it.
+
+| Finding | Reproduced? | Disposition (fix / rebut) |
+|------|----------|----------------------|
+| {finding} | {yes/no, with file:line or command} | {fix note, or counter-argument + recorded under unresolved} |
+
 ## Items for Review
 
 **Focus areas for reviewers**:

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

@@ -62,6 +62,14 @@ $ {command}
 
 {describe any deviation from the approved plan}
 
+## 对审查发现的逐条核实
+
+> 仅修复模式填写；初次实现写「（本轮为初次实现，无审查发现）」。对上一轮 `review-code` 的每条发现先 Read/Grep 核实再处置。
+
+| 发现 | 是否复现 | 处置（修复 / 反驳） |
+|------|----------|----------------------|
+| {finding} | {是/否，附 file:line 或命令} | {修复说明，或反证 + 记入 unresolved} |
+
 ## 供审查关注的内容
 
 **建议审查者重点关注**:

package/templates/.agents/skills/commit/SKILL.en.md

@@ -19,7 +19,7 @@ When updating related `task.md` frontmatter, read `.agents/rules/version-stamp.m
 
 ## 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.
 
 ## 1. Check Local Modifications (CRITICAL)
 
@@ -58,13 +58,12 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 > The full four-case status matrix, prerequisite checks, and multi-TUI next-step commands live in `reference/task-status-update.md`. Read `reference/task-status-update.md` before updating task state.
 
-> **IMPORTANT**: When showing the next step, output every TUI command format in full and directly use the standard template from `reference/task-status-update.md`. 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).
+> **IMPORTANT**: When showing the next step, output every TUI command format in full and directly use the standard template from `reference/task-status-update.md`. 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).
 
 Append the Commit Activity Log entry and choose exactly one next-step case:
-- final commit -> `complete-task {task-id}`
+- final commit -> render the next step by `.agents/.airc.json`'s `prFlow` (`disabled` -> single option `complete-task`; `required` -> single option `create-pr`; absent -> two options `create-pr` / `complete-task`); see Case 1 in `reference/task-status-update.md`
 - more work remains -> update task.md and stop
 - ready for review -> `review-code {task-id}`
-- ready for PR (only when the project enables the PR flow, i.e. `requiresPullRequest !== false`) -> `create-pr`
 
 ## 6. Sync Issue Metadata When Applicable
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -19,7 +19,7 @@ description: "提交当前变更到 Git"
 
 ## 任务入参短号别名
 
-> 如果 `{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. 检查本地修改（关键）
 
@@ -58,13 +58,12 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 > 完整的 4 种状态分支、前置条件检查和多 TUI 下一步命令见 `reference/task-status-update.md`。更新任务状态前，先读取 `reference/task-status-update.md`。
 
-> **重要**：向用户展示下一步时，必须完整输出所有 TUI 命令格式，并直接使用 `reference/task-status-update.md` 中对应场景的标准模板。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> **重要**：向用户展示下一步时，必须完整输出所有 TUI 命令格式，并直接使用 `reference/task-status-update.md` 中对应场景的标准模板。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 追加 Commit 的 Activity Log，并且只能选择一个下一步分支：
-- 最终提交 -> `complete-task {task-id}`
+- 最终提交 -> 按 `.agents/.airc.json` 的 `prFlow` 渲染下一步（`disabled` → 单选 `complete-task`；`required` → 单选 `create-pr`；缺省 → 二选一 `create-pr` / `complete-task`），详见 `reference/task-status-update.md` 场景 1
 - 还有后续工作 -> 更新 task.md 后停止
 - 准备审查 -> `review-code {task-id}`
-- 准备创建 PR（仅项目启用 PR 流程，即 `requiresPullRequest !== false`）-> `create-pr`
 
 ## 6. 同步 Issue 元数据（按需）
 

package/templates/.agents/skills/commit/reference/task-status-update.en.md

@@ -23,20 +23,19 @@ Before selecting the next step, verify:
 - whether the latest `review-code.md` / `review-code-r{N}.md` passed without findings
 - whether there are still pending fixes, review work, or PR creation steps
 
-**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `requiresPullRequest` field. Treat missing or `true` as "PR flow enabled" (default); treat explicit `false` as "PR flow disabled". All branches that depend on this field follow the same rule.
+**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow). All branches that depend on this preference follow the same three states.
 
 Choose exactly one case:
 
 | Decision Basis | Required Case |
 |---|---|
-| all workflow steps completed + latest review approved with no findings + all tests passed | Case 1: final commit |
+| all workflow steps completed + latest review approved with no findings + all tests passed | Case 1: final commit (render next step by `prFlow`) |
 | unfinished steps, pending fixes, or waiting on others still exist | Case 2: more work remains |
 | this commit prepares the task for code review | Case 3: ready for review |
-| code is committed, review is done, **and the project enables the PR flow**, with PR creation as the next step | Case 4: ready for PR |
 
 Never apply more than one case. Match the single next-step branch first, then update the task.
 
-**Gate downgrade**: When `requiresPullRequest === false`, Case 4 must never be entered; commits that would otherwise fall into Case 4 collapse into Case 1 (final commit -> `/complete-task`).
+**Case 1 next-step rendering (evaluate the `prFlow` strong constraint first)**: the terminal "final commit" next step is rendered by `prFlow` -- `"disabled"` -> single option "complete directly" (`/complete-task`), never guide PR creation; `"required"` -> single option "go through the PR flow" (`/create-pr`); field absent -> two options (`/create-pr` or `/complete-task`). PR creation is carried by Case 1's "go through the PR flow" option; it is no longer a separate case.
 
 ### Case 1: Final Commit
 
@@ -44,15 +43,40 @@ Prerequisites:
 - [ ] all code committed
 - [ ] all tests passed
 - [ ] code review approved
-- [ ] all workflow steps completed (for the `pr_tasks` list under each yaml `commit` step, count those items toward completion only when `requiresPullRequest !== false`)
+- [ ] all workflow steps completed (for the `pr_tasks` list under each yaml `commit` step, decide whether to count them by the "PR path" rule: `prFlow=required` always counts; `prFlow=disabled` never counts; when absent, exclude only if `pr_status=skipped`, otherwise count)
 
-Required next-step commands:
+Required next-step commands (rendered by `prFlow`):
+
+`prFlow="disabled"` -> single option "complete directly":
 
 ```text
 Next step - complete and archive the task:
-  - Claude Code / OpenCode: /complete-task {task-id}
-  - Gemini CLI: /agent-infra:complete-task {task-id}
-  - Codex CLI: $complete-task {task-id}
+  - Claude Code / OpenCode: /complete-task {task-ref}
+  - Gemini CLI: /agent-infra:complete-task {task-ref}
+  - Codex CLI: $complete-task {task-ref}
+```
+
+`prFlow="required"` -> single option "go through the PR flow":
+
+```text
+Next step - create Pull Request:
+  - Claude Code / OpenCode: /create-pr {task-ref}
+  - Gemini CLI: /agent-infra:create-pr {task-ref}
+  - Codex CLI: $create-pr {task-ref}
+```
+
+field absent -> two options:
+
+```text
+Next step - choose one:
+  - Go through the PR flow:
+    - Claude Code / OpenCode: /create-pr {task-ref}
+    - Gemini CLI: /agent-infra:create-pr {task-ref}
+    - Codex CLI: $create-pr {task-ref}
+  - Complete directly (no PR):
+    - Claude Code / OpenCode: /complete-task {task-ref}
+    - Gemini CLI: /agent-infra:complete-task {task-ref}
+    - Codex CLI: $complete-task {task-ref}
 ```
 
 ### Case 2: More Work Remains
@@ -75,25 +99,9 @@ Required next-step commands:
 
 ```text
 Next step - code review:
-  - Claude Code / OpenCode: /review-code {task-id}
-  - Gemini CLI: /agent-infra:review-code {task-id}
-  - Codex CLI: $review-code {task-id}
-```
-
-### Case 4: Ready for PR
-
-If the next step is Pull Request creation:
-- update `updated_at`
-- update `agent_infra_version` from `.agents/rules/version-stamp.md`
-- record the PR plan in `task.md`
-
-Required next-step commands:
-
-```text
-Next step - create Pull Request:
-  - Claude Code / OpenCode: /create-pr {task-id}
-  - Gemini CLI: /agent-infra:create-pr {task-id}
-  - Codex CLI: $create-pr {task-id}
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /agent-infra:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
 ```
 
-> Note: beyond the four cases, if `task.md` contains a valid `pr_number`, the commit skill must sync the PR summary via `reference/pr-summary-sync.md` before entering the verification gate.
+> Note: beyond the cases above, if `task.md` contains a valid `pr_number`, the commit skill must sync the PR summary via `reference/pr-summary-sync.md` before entering the verification gate.

package/templates/.agents/skills/commit/reference/task-status-update.zh-CN.md

@@ -23,20 +23,19 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 最新的 `review-code.md` / `review-code-r{N}.md` 是否无问题通过
 - 是否仍然存在待修复项、待审查工作或待创建 PR 的步骤
 
-**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `requiresPullRequest` 字段；当字段缺失或为 `true` 时视为「启用 PR 流程」（默认），仅当显式为 `false` 时视为「关闭 PR 流程」。所有依赖该字段的分支按此规则判定。
+**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR）。所有依赖该偏好的分支按此三态判定。
 
 必须且只能选择一个分支：
 
 | 判断依据 | 必选分支 |
 |---|---|
-| 所有工作流步骤都已完成 + 最新审查无问题通过 + 所有测试通过 | 场景 1：最终提交 |
+| 所有工作流步骤都已完成 + 最新审查无问题通过 + 所有测试通过 | 场景 1：最终提交（按 `prFlow` 渲染下一步） |
 | 仍有未完成步骤、待修复项或等待他人的动作 | 场景 2：还有后续工作 |
 | 这次提交是为了把任务交给代码审查 | 场景 3：准备进入审查 |
-| 代码已提交、审查已完成，且**项目启用 PR 流程**，下一步是创建 PR | 场景 4：准备创建 PR |
 
 绝对不要同时套用多个分支。先匹配唯一的下一步分支，再更新任务。
 
-**门控降级**：当 `requiresPullRequest === false` 时，场景 4 永远不被进入；原本会落入场景 4 的提交统一收敛到场景 1（最终提交 → `/complete-task`）。
+**场景 1 下一步渲染（先判 `prFlow` 强约束）**：终态「最终提交」的下一步命令按 `prFlow` 渲染——`"disabled"` → 单选「直接完成」（`/complete-task`），永不引导创建 PR；`"required"` → 单选「走 PR 流程」（`/create-pr`）；字段缺省 → 二选一（`/create-pr` 或 `/complete-task`）。创建 PR 的动作统一由场景 1 的「走 PR 流程」选项承载，不再单列独立场景。
 
 ### 场景 1：最终提交
 
@@ -44,15 +43,40 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - [ ] 所有代码都已提交
 - [ ] 所有测试通过
 - [ ] 代码审查已通过
-- [ ] 所有工作流步骤已完成（对 yaml `commit` 步骤的 `pr_tasks` 列表，仅在 `requiresPullRequest !== false` 时计入）
+- [ ] 所有工作流步骤已完成（对 yaml `commit` 步骤的 `pr_tasks` 列表，按「走 PR 路径」判定是否计入：`prFlow=required` 始终计入；`prFlow=disabled` 不计入；缺省下仅当 `pr_status=skipped` 时不计入，否则计入）
 
-必带下一步命令：
+必带下一步命令（按 `prFlow` 渲染）：
+
+`prFlow="disabled"` → 单选「直接完成」：
 
 ```text
 下一步 - 完成并归档任务：
-  - Claude Code / OpenCode: /complete-task {task-id}
-  - Gemini CLI: /agent-infra:complete-task {task-id}
-  - Codex CLI: $complete-task {task-id}
+  - Claude Code / OpenCode: /complete-task {task-ref}
+  - Gemini CLI: /agent-infra:complete-task {task-ref}
+  - Codex CLI: $complete-task {task-ref}
+```
+
+`prFlow="required"` → 单选「走 PR 流程」：
+
+```text
+下一步 - 创建 Pull Request：
+  - Claude Code / OpenCode: /create-pr {task-ref}
+  - Gemini CLI: /agent-infra:create-pr {task-ref}
+  - Codex CLI: $create-pr {task-ref}
+```
+
+字段缺省 → 二选一：
+
+```text
+下一步 - 二选一：
+  - 走 PR 流程：
+    - Claude Code / OpenCode: /create-pr {task-ref}
+    - Gemini CLI: /agent-infra:create-pr {task-ref}
+    - Codex CLI: $create-pr {task-ref}
+  - 直接完成（无 PR）：
+    - Claude Code / OpenCode: /complete-task {task-ref}
+    - Gemini CLI: /agent-infra:complete-task {task-ref}
+    - Codex CLI: $complete-task {task-ref}
 ```
 
 ### 场景 2：还有后续工作
@@ -75,25 +99,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 ```text
 下一步 - 代码审查：
-  - Claude Code / OpenCode: /review-code {task-id}
-  - Gemini CLI: /agent-infra:review-code {task-id}
-  - Codex CLI: $review-code {task-id}
-```
-
-### 场景 4：准备创建 PR
-
-如果下一步是创建 Pull Request：
-- 更新 `updated_at`
-- 按 `.agents/rules/version-stamp.md` 更新 `agent_infra_version`
-- 在 `task.md` 中记录 PR 计划
-
-必带下一步命令：
-
-```text
-下一步 - 创建 Pull Request：
-  - Claude Code / OpenCode: /create-pr {task-id}
-  - Gemini CLI: /agent-infra:create-pr {task-id}
-  - Codex CLI: $create-pr {task-id}
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /agent-infra:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
 ```
 
-> 注意：四个场景之外，只要 `task.md` 中存在有效 `pr_number`，commit 技能必须先按 `reference/pr-summary-sync.md` 同步 PR 摘要，再进入完成校验。
+> 注意：上述场景之外，只要 `task.md` 中存在有效 `pr_number`，commit 技能必须先按 `reference/pr-summary-sync.md` 同步 PR 摘要，再进入完成校验。

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -28,7 +28,7 @@ Before the state check is complete, do not make external-state assertions such a
 
 ## 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
 
@@ -44,10 +44,36 @@ If not found in `active/`, check `blocked/` and `completed/`:
 
 ### 2. Verify Completion Prerequisites (Failure Must Stop)
 
-**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `requiresPullRequest` field. Treat missing or `true` as "PR flow enabled" (default); treat explicit `false` as "PR flow disabled". The completion check below is pruned accordingly.
+**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow), and `pr_status` from `task.md` frontmatter (`pending` / `created` / `skipped`).
+
+**PR dimension decision (evaluate the `prFlow` strong constraint FIRST, then `pr_status`)**:
+
+| `prFlow` | `pr_status` | Decision |
+|---|---|---|
+| `disabled` | any | No PR path -> PR dimension satisfied, continue with the other prerequisites |
+| `required` | `created` | PR dimension satisfied, continue |
+| `required` | `pending` / `skipped` | **Stop**: under a mandatory PR flow you must run `/create-pr` first; `--skip-pr` is NOT accepted (including a pre-existing / manually-set `skipped`) |
+| absent | `created` / `skipped` | PR dimension satisfied, continue |
+| absent | `pending` | **Stop by default** and print the two-option guidance below; unless the user passes `--skip-pr` (writes `pr_status: skipped`, then continues) or `--force` |
+
+- `--skip-pr` handling: effective only when `prFlow` is not `required` -> set `pr_status` to `skipped` in `task.md`, then continue; when `prFlow=required`, ignore `--skip-pr` and stop per the table.
+- Note: `--force` may override the other prerequisites below, but does **NOT** lift the `prFlow=required` PR constraint (the only exit from the strong constraint is creating a PR).
+
+Two-option guidance for absent + `pending`:
+```
+Task {task-id} has no PR yet (pr_status: pending). Choose one:
+  - Go through the PR flow: /create-pr {task-ref}
+  - Explicitly skip and complete: /complete-task {task-ref} --skip-pr
+```
+
+Stop message for `required` + `pending`/`skipped`:
+```
+This project enforces the PR flow (prFlow: "required") and the task has no PR yet.
+Run /create-pr {task-ref} first, then complete; --skip-pr is not accepted under a mandatory PR flow.
+```
 
 Before marking complete, verify ALL of these:
-- [ ] All workflow steps are complete (check workflow progress in task.md; **for the `pr_tasks` list under each yaml `commit` step, count those items toward the missing-work decision only when `.agents/.airc.json:requiresPullRequest !== false`**)
+- [ ] All workflow steps are complete (check workflow progress in task.md; **for the `pr_tasks` list under each yaml `commit` step, decide whether to count them by the "PR path" rule: `prFlow=required` always counts; `prFlow=disabled` never counts; when absent, exclude only if `pr_status=skipped`, otherwise count**)
 - [ ] Code has been reviewed (`review-code.md` or `review-code-r{N}.md` exists, and the latest review verdict is Approved; or review was done externally)
 - [ ] Code has been committed (no uncommitted changes related to this task)
 - [ ] Tests are passing
@@ -89,7 +115,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - Verify and check off all items in `## Completion Checklist` (change `- [ ]` to `- [x]`)
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Completed** by {agent} — Task moved to completed/
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task** by {agent} — Task moved to completed/
   ```
 
 ### 4. Move Task
@@ -146,6 +172,10 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
+> The completion timestamp line (the last line of the whole output) uses `date "+%Y-%m-%d %H:%M:%S"` (local timezone, no offset) and always sits at the very end of the output for at-a-glance scanning across windows. This skill renders no "Next steps" commands, but it does render an **optional sandbox-cleanup hint** before the timestamp line (see the gate below), and still prints the line.
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block in the output below only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to completed/, so read it from `.agents/workspace/completed/{task-id}/task.md`). This block is independent of "Next steps" semantics — it is not a workflow successor command.
+
 Output format:
 ```
 Task {task-id} completed; task directory moved to completed/.
@@ -157,6 +187,13 @@ Task info:
 
 Deliverables:
 - {List of key outputs: files modified, tests added, etc.}
+
+Optional: clean up this task's sandbox
+(The task is archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
+Completed at: {completion-time}
 ```
 
 

package/templates/.agents/skills/complete-task/SKILL.zh-CN.md

@@ -28,7 +28,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. 验证任务存在
@@ -43,10 +43,36 @@ tail .agents/workspace/active/{task-id}/task.md
 
 ### 2. 验证完成前置条件（未满足则必须停止）
 
-**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `requiresPullRequest` 字段；当字段缺失或为 `true` 时视为「启用 PR 流程」（默认），仅当显式为 `false` 时视为「关闭 PR 流程」。下面的工作流步骤完成判定按此规则裁剪。
+**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR），以及 `task.md` frontmatter 的 `pr_status`（`pending` / `created` / `skipped`）。
+
+**PR 维度判定（先判 `prFlow` 强约束，后看 `pr_status`）**：
+
+| `prFlow` | `pr_status` | 判定 |
+|---|---|---|
+| `disabled` | 任意 | 无 PR 路径 → PR 维度满足，继续其余前置条件 |
+| `required` | `created` | PR 维度满足，继续 |
+| `required` | `pending` / `skipped` | **停止**：强制 PR 下必须先 `/create-pr`；`--skip-pr` 不被接受（含既有/手动写入的 `skipped`） |
+| 缺省 | `created` / `skipped` | PR 维度满足，继续 |
+| 缺省 | `pending` | **默认停止**并输出下方二选一引导；除非用户提供 `--skip-pr`（写 `pr_status: skipped` 后继续）或 `--force` |
+
+- `--skip-pr` 处理：仅在 `prFlow` 非 `required` 时生效——把 `task.md` 的 `pr_status` 写为 `skipped` 后继续；`prFlow=required` 时忽略 `--skip-pr` 并按上表停止。
+- 注：`--force` 可越过下方其余前置条件，但**不解除 `prFlow=required` 的 PR 强约束**（强约束的唯一出口是创建 PR）。
+
+缺省 + `pending` 的二选一引导消息：
+```
+任务 {task-id} 尚未创建 PR（pr_status: pending）。请二选一：
+  - 走 PR 流程：/create-pr {task-ref}
+  - 显式跳过并完成：/complete-task {task-ref} --skip-pr
+```
+
+`required` + `pending`/`skipped` 的停止消息：
+```
+当前项目强制 PR 流程（prFlow: "required"），任务尚未创建 PR。
+请先运行 /create-pr {task-ref} 创建 PR 后再完成；--skip-pr 在强制 PR 下不被接受。
+```
 
 标记完成之前，验证以下所有条件：
-- [ ] 所有工作流步骤已完成（检查 task.md 中的工作流进度；**对 yaml 中 commit 步骤的 `pr_tasks` 列表，仅在 `.agents/.airc.json:requiresPullRequest !== false` 时计入未完成判定**）
+- [ ] 所有工作流步骤已完成（检查 task.md 中的工作流进度；**对 yaml 中 commit 步骤的 `pr_tasks` 列表，按「走 PR 路径」判定是否计入未完成判定：`prFlow=required` 始终计入；`prFlow=disabled` 不计入；缺省下仅当 `pr_status=skipped` 时不计入，否则计入**）
 - [ ] 代码已审查（`review-code.md` 或 `review-code-r{N}.md` 存在，且最新审查结论为 Approved；或已在外部完成审查）
 - [ ] 代码已提交（没有与此任务相关的未提交变更）
 - [ ] 测试通过
@@ -88,7 +114,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 逐项验证并勾选 `## 完成检查清单` 中的所有条目（将 `- [ ]` 改为 `- [x]`）
 - **追加**到 `## Activity Log`（不要覆盖之前的记录）：
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Completed** by {agent} — Task moved to completed/
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task** by {agent} — Task moved to completed/
   ```
 
 ### 4. 转移任务
@@ -145,6 +171,10 @@ node .agents/scripts/validate-artifact.js gate complete-task .agents/workspace/c
 
 > 仅在校验通过后执行本步骤。
 
+> 完成时间收尾行（整段输出的最后一行）取值 `date "+%Y-%m-%d %H:%M:%S"`（本地时区、不带偏移），固定放在输出的绝对末尾，便于多窗口扫视。本 skill 不渲染「下一步」命令，但会在收尾行之前渲染一段**可选的沙箱清理提示**（见下方门控），且仍统一打印该收尾行。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义，不是工作流后继命令。
+
 输出格式：
 ```
 任务 {task-id} 已完成，任务目录已转移到 completed/。
@@ -156,6 +186,13 @@ node .agents/scripts/validate-artifact.js gate complete-task .agents/workspace/c
 
 交付物：
 - {关键产出列表：修改的文件、添加的测试等}
+
+可选：清理本任务的沙箱
+（任务已归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
+Completed at: {completion-time}
 ```
 
 

package/templates/.agents/skills/complete-task/config/verify.en.json

@@ -18,7 +18,7 @@
       "require_completed_at": true
     },
     "activity-log": {
-      "expected_action_pattern": "Completed",
+      "expected_action_pattern": "(Complete Task|Completed)",
       "freshness_minutes": 30
     },
     "completion-checklist": {

package/templates/.agents/skills/complete-task/config/verify.zh-CN.json

@@ -18,7 +18,7 @@
       "require_completed_at": true
     },
     "activity-log": {
-      "expected_action_pattern": "Completed",
+      "expected_action_pattern": "(Complete Task|Completed)",
       "freshness_minutes": 30
     },
     "completion-checklist": {

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

@@ -13,24 +13,24 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 ## 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.
 
 ## Execution Flow
 
 ### Pre-gate: Project-level PR Flow Check
 
-**Gate read (project-level PR flow policy)**: Before running any numbered step, read `.agents/.airc.json`'s `requiresPullRequest` field. Treat missing or `true` as "PR flow enabled" (default); treat explicit `false` as "PR flow disabled".
+**Gate read (project-level PR flow policy)**: Before running any numbered step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow).
 
 Branch on the result:
-- missing / `true` -> continue to Step 1 below
-- explicit `false` -> output the message below and **stop immediately**. Do not run any subsequent numbered step, do not trigger any PR-creation command, do not modify `pr_number` in `task.md`, and do not publish a PR summary comment:
+- absent / `"required"` -> continue to Step 1 below
+- `"disabled"` -> output the message below and **stop immediately**. Do not run any subsequent numbered step, do not trigger any PR-creation command, do not modify `pr_number` / `pr_status` in `task.md`, and do not publish a PR summary comment:
 
 ```
-This project does not enable the PR flow (`.agents/.airc.json` sets `requiresPullRequest: false`).
+This project does not enable the PR flow (`.agents/.airc.json` sets `prFlow: "disabled"`).
 No Pull Request is required; run instead:
-  - Claude Code / OpenCode: /complete-task {task-id}
-  - Gemini CLI: /agent-infra:complete-task {task-id}
-  - Codex CLI: $complete-task {task-id}
+  - Claude Code / OpenCode: /complete-task {task-ref}
+  - Gemini CLI: /agent-infra:complete-task {task-ref}
+  - Codex CLI: $complete-task {task-ref}
 ```
 
 ### 1. Parse Command Arguments
@@ -96,7 +96,7 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S%:z"
 ```
 
-If `{task-id}` is available, update task.md with `pr_number`, `updated_at`, `agent_infra_version`, and append the PR Created Activity Log entry including metadata-sync and summary results.
+If `{task-id}` is available, update task.md with `pr_number`, `pr_status` (set to `created`), `updated_at`, `agent_infra_version`, and append the Create PR Activity Log entry including metadata-sync and summary results.
 
 ### 9. Verification Gate
 
@@ -117,9 +117,18 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification 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).
+> **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).
 
-Explain the created PR URL, summarize metadata sync and summary-comment results, and recommend `complete-task {task-id}` once the workflow is truly done.
+Explain the created PR URL, summarize metadata sync and summary-comment results, and recommend watching the PR's checks next (render `{task-ref}` as the short id `#NN` per `.agents/rules/next-step-output.md`):
+
+```
+Next step - Watch PR checks (auto self-heal until required checks are green):
+  - Claude Code / OpenCode: /watch-pr {task-ref}
+  - Gemini CLI: /agent-infra:watch-pr {task-ref}
+  - Codex CLI: $watch-pr {task-ref}
+```
+
+Once green, `watch-pr` then guides toward `complete-task {task-ref}`.
 
 ## Notes
 

package/templates/.agents/skills/create-pr/SKILL.zh-CN.md

@@ -13,24 +13,24 @@ description: "创建 Pull Request 到目标分支"
 
 ## 任务入参短号别名
 
-> 如果 `{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` 形式。
 
 ## 执行流程
 
 ### 前置门控：项目级 PR 流程检查
 
-**门控读取（项目级 PR 流程策略）**：在执行编号步骤前，读取 `.agents/.airc.json` 的 `requiresPullRequest` 字段；当字段缺失或为 `true` 时视为「启用 PR 流程」（默认），仅当显式为 `false` 时视为「关闭 PR 流程」。
+**门控读取（项目级 PR 流程策略）**：在执行编号步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR）。
 
 按读取结果分支：
-- 缺失 / `true` → 继续到下方第 1 步
-- 显式 `false` → 输出以下消息后**立即停止**，不要执行任何后续编号步骤、不要触发任何 PR 创建命令、不要修改 `task.md` 的 `pr_number`、不要发布 PR 摘要评论：
+- 缺省 / `"required"` → 继续到下方第 1 步
+- `"disabled"` → 输出以下消息后**立即停止**，不要执行任何后续编号步骤、不要触发任何 PR 创建命令、不要修改 `task.md` 的 `pr_number` / `pr_status`、不要发布 PR 摘要评论：
 
 ```
-当前项目未启用 PR 流程（`.agents/.airc.json` 中 `requiresPullRequest: false`）。
+当前项目未启用 PR 流程（`.agents/.airc.json` 中 `prFlow: "disabled"`）。
 无需创建 Pull Request，请直接运行：
-  - Claude Code / OpenCode：/complete-task {task-id}
-  - Gemini CLI：/agent-infra:complete-task {task-id}
-  - Codex CLI：$complete-task {task-id}
+  - Claude Code / OpenCode：/complete-task {task-ref}
+  - Gemini CLI：/agent-infra:complete-task {task-ref}
+  - Codex CLI：$complete-task {task-ref}
 ```
 
 ### 1. 解析命令参数
@@ -96,7 +96,7 @@ description: "创建 Pull Request 到目标分支"
 date "+%Y-%m-%d %H:%M:%S%:z"
 ```
 
-如果获取到了 `{task-id}`，更新 task.md 的 `pr_number`、`updated_at`、`agent_infra_version`，并追加 PR Created 的 Activity Log，记录元数据同步和摘要发布结果。
+如果获取到了 `{task-id}`，更新 task.md 的 `pr_number`、`pr_status`（设为 `created`）、`updated_at`、`agent_infra_version`，并追加 Create PR 的 Activity Log，记录元数据同步和摘要发布结果。
 
 ### 9. 完成校验
 
@@ -117,9 +117,18 @@ node .agents/scripts/validate-artifact.js gate create-pr .agents/workspace/activ
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
-说明 PR URL、元数据同步结果、摘要评论结果，并在工作流真正完成后推荐执行 `complete-task {task-id}`。
+说明 PR URL、元数据同步结果、摘要评论结果，并推荐下一步进入 PR 监控（按 `.agents/rules/next-step-output.md` 把 `{task-ref}` 渲染为短号 `#NN`）：
+
+```
+下一步 - 监控 PR 检查（required checks 全绿前自动自愈）：
+  - Claude Code / OpenCode：/watch-pr {task-ref}
+  - Gemini CLI：/agent-infra:watch-pr {task-ref}
+  - Codex CLI：$watch-pr {task-ref}
+```
+
+`watch-pr` 全绿后会再引导 `complete-task {task-ref}`。
 
 ## 注意事项
 

package/templates/.agents/skills/create-pr/config/verify.json

@@ -15,7 +15,7 @@
       ]
     },
     "activity-log": {
-      "expected_action_pattern": "PR Created",
+      "expected_action_pattern": "(Create PR|PR Created)",
       "freshness_minutes": 30
     },
     "platform-sync": {
@@ -26,6 +26,7 @@
       "verify_pr_assignee": true,
       "verify_issue_fields": true,
       "verify_milestone": true,
+      "verify_milestone_specific": true,
       "expected_pr_comment_marker_key": "prSummary"
     }
   }