@fitlab-ai/agent-infra 0.7.2 → 0.7.4

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

@@ -0,0 +1,41 @@
+# Rules Index
+
+`.agents/rules/` holds every collaboration rule in this project. Each SKILL loads the
+relevant few on demand; this index groups all rules by domain with a one-line purpose,
+so you can quickly find "which ones to read" without opening each file.
+
+> Maintenance note: when adding or removing `.agents/rules/*.md`, update this index too.
+
+## General Principles
+
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Silence during SKILL runs: no user questions by default, plus two exceptions.
+- [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
+- [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
+- [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
+
+## Issue / PR
+
+- [`issue-pr-commands.md`](issue-pr-commands.md) — GitHub commands to verify auth and read/write Issues / PRs.
+- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch PR required checks and pull failure logs (`watch-pr`).
+- [`create-issue.md`](create-issue.md) — Cascading Issue creation after `create-task` writes `task.md`.
+- [`issue-sync.md`](issue-sync.md) — Sync markers and flow for task artifacts ↔ Issue comments / labels / fields.
+- [`issue-fields.md`](issue-fields.md) — Read/write flow for Issue Type pinned fields (Priority/Effort/dates).
+- [`pr-sync.md`](pr-sync.md) — Sync rule for the single reviewer-facing PR summary comment.
+
+## Task Workflow
+
+- [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
+- [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of `#NN` / bare-number short ids.
+- [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.
+- [`label-milestone-setup.md`](label-milestone-setup.md) — Platform commands to initialize labels / milestones.
+- [`security-alerts.md`](security-alerts.md) — Commands to import / close Dependabot and Code Scanning alerts.
+
+## Commit & Release
+
+- [`commit-and-pr.md`](commit-and-pr.md) — Conventional Commits message and PR conventions.
+- [`release-commands.md`](release-commands.md) — Read past releases, query merged PRs, publish release notes.
+
+## Testing & Cross-platform
+
+- [`testing-discipline.md`](testing-discipline.md) — Test-writing discipline: prefer structural asserts, no brittle wording matches.
+- [`cross-platform-tests.md`](cross-platform-tests.md) — Cross-platform test guards: express platform skips via `onPlatforms()`.

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

@@ -0,0 +1,40 @@
+# 规则索引
+
+`.agents/rules/` 收录本项目所有协作规则。各 SKILL 执行时按需加载其中若干篇；
+本索引按业务域列出全部规则及其用途，便于快速定位「该读哪几篇」，无需逐文件翻阅。
+
+> 维护提醒：新增或删除 `.agents/rules/*.md` 时，请同步更新本索引。
+
+## 通用准则
+
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — SKILL 执行期禁言：默认不向用户提问，及两类例外。
+- [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
+- [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
+- [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
+
+## Issue / PR
+
+- [`issue-pr-commands.md`](issue-pr-commands.md) — 验证平台认证、读写 Issue / PR 的 GitHub 命令集。
+- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR required checks、拉取失败日志的命令集（`watch-pr`）。
+- [`create-issue.md`](create-issue.md) — `create-task` 落盘后级联创建 Issue 的规则。
+- [`issue-sync.md`](issue-sync.md) — task 产物与 Issue 评论 / 标签 / 字段的同步标记与流程。
+- [`issue-fields.md`](issue-fields.md) — Issue Type pinned 字段（Priority/Effort/日期）的读写流程。
+- [`pr-sync.md`](pr-sync.md) — 面向 reviewer 的唯一 PR 摘要评论的同步规则。
+
+## 任务工作流
+
+- [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
+- [`task-short-id.md`](task-short-id.md) — 任务短号 `#NN` / 裸数字的解析、分配与生命周期。
+- [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。
+- [`label-milestone-setup.md`](label-milestone-setup.md) — 初始化 label / milestone 的平台命令集。
+- [`security-alerts.md`](security-alerts.md) — 导入 / 关闭 Dependabot 与 Code Scanning 告警的命令集。
+
+## 提交与发布
+
+- [`commit-and-pr.md`](commit-and-pr.md) — Conventional Commits 提交信息与 PR 规范。
+- [`release-commands.md`](release-commands.md) — 读取历史 release、查询已合并 PR、发布 Release notes。
+
+## 测试与跨平台
+
+- [`testing-discipline.md`](testing-discipline.md) — 测试编写纪律：结构性断言优先，禁止脆弱的措辞匹配。
+- [`cross-platform-tests.md`](cross-platform-tests.md) — 跨平台测试守卫：用 `onPlatforms()` 表达平台跳过。

package/templates/.agents/rules/debugging-guide.en.md

@@ -0,0 +1,25 @@
+# General Rule - Structured Debugging Guide
+
+> This file defines the structured triage flow for "test failure / behavior not as expected"; SKILLs that modify code in response to failures (e.g. `code-task`, `watch-pr`) load it on demand before attempting a fix.
+
+## Triggers
+
+When any of the following happens, run this flow before changing code:
+
+- A test fails, or a build / type-check / lint error appears
+- Runtime behavior differs from expectations (output, state, or side effects)
+
+## Core Anti-pattern: No Blind Patch-and-Retry
+
+The "tweak one spot → rerun → still broken → guess another spot" loop hides the real root cause, introduces new defects, and wastes time. A change with no supporting evidence is not a fix.
+
+## Four-phase Flow
+
+1. **Gather evidence**: Read the full error message and stack trace (not just the last line) and pinpoint where it fails; reproduce minimally when needed, and record "actual vs expected behavior".
+2. **Form a hypothesis**: From the evidence, propose a root-cause hypothesis that explains **all** the symptoms rather than a surface symptom; if there are several, rank them by likelihood and testability.
+3. **Verify the hypothesis**: Before changing anything, confirm the hypothesis cheaply—add logging, add a breakpoint, shrink the input, or write a failing test that reproduces it; if it is disproven, return to phase 2.
+4. **Fix the root cause**: Change only the verified root cause (not the symptom), then rerun the relevant tests to confirm they pass; if they still fail, return to phase 1 with the new evidence instead of trial-and-error without evidence.
+
+## Relation to Project Principles
+
+This flow is the debugging-specific form of AGENTS.md's "Think Before Coding" and "Goal-Driven Execution": pin the problem with a reproducible failing case first, then make the fix turn it green.

package/templates/.agents/rules/debugging-guide.zh-CN.md

@@ -0,0 +1,25 @@
+# 通用规则 - 结构化调试指导
+
+> 本文件定义「测试失败 / 行为不符合预期」时的结构化排查流程；`code-task`、`watch-pr` 等会因失败而修改代码的 SKILL 在动手修复前按需加载。
+
+## 触发条件
+
+出现以下任一情况时，先按本流程排查，再改代码：
+
+- 测试失败，或构建 / 类型检查 / lint 报错
+- 运行结果与预期不符（输出、状态或副作用异常）
+
+## 核心反模式：禁止盲目改代码重试
+
+「改一处 → 重跑 → 还错 → 再猜一处」的循环会掩盖真实根因、引入新缺陷、浪费时间。没有证据支撑的修改不算修复。
+
+## 四阶段流程
+
+1. **收集证据**：完整读取错误信息与堆栈（不要只看最后一行），定位失败的具体位置；必要时最小化复现，记录「实际行为 vs 预期行为」。
+2. **形成假设**：基于证据提出能解释**全部**现象的根因假设，而不是停留在表层症状；若有多个假设，按可能性与可验证性排序。
+3. **验证假设**：动手改之前，用最小代价确认假设成立——加日志、加断点、缩小输入，或写一个能复现的失败用例；假设被证伪就回到阶段 2。
+4. **修复根因**：只针对已验证的根因修改（而非症状），改完重跑相关测试确认通过；仍失败则带着新证据回到阶段 1，不在无证据时反复试错。
+
+## 与项目准则的关系
+
+本流程是 AGENTS.md「先思考再动手」「目标驱动执行」在调试场景的具体化：先用可复现的失败用例锁定问题，再让修复使其通过。

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

@@ -1,6 +1,9 @@
 # Next-Step Output Rule
 
-When a skill renders "Next steps" commands and the "Task info" block in its notify-user step, present the task ID consistently per this rule. Read this file before rendering next steps.
+This file defines two **independent** rules for a skill's "notify-user / Next steps" output; read this file before rendering the final output and apply both:
+
+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.
 
 ## Placeholder semantics
 
@@ -46,9 +49,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 Short ids are always rendered with a `#` prefix as `#NN`, matching how task.md frontmatter renders `short_id`. `#` starts a comment in bash, so pasting example commands depends on the TUI (both the bare numeric `NN` and `#NN` are accepted by `task-short-id.js resolve`).
 
-## Completion timestamp line (Completed at)
+## Agent output trailing line (Completed at)
 
-Every skill that reads this rule and renders "Next steps / Inform user" output appends a single completion-time line as the **very last line** of its user-facing output, so users scanning across tmux windows can tell at a glance which agent finished most recently:
+This section is a standalone rule, **co-equal with the next-step output structure** and **not part of the "Next steps" block**. Every skill that renders user-facing output must append the completion-time line as the **very last line** of that output — including **complete-task, which renders no next-step commands**, and **error / early-return paths** where a precondition is unmet. This lets users scanning across tmux windows tell at a glance which agent finished most recently:
 
 ```text
 Completed at: YYYY-MM-DD HH:mm:ss

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,6 +1,9 @@
 # 下一步输出规则
 
-各 skill 在「告知用户」步骤渲染「下一步」命令与「任务信息」段时，统一按本规则呈现任务 ID 形态。渲染下一步前先读取本文件。
+本文件定义 skill「告知用户 / 下一步」输出的两类**相互独立**的规则；渲染最终输出前先读取本文件并同时落实两者：
+
+1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
+2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
 
 ## 占位符语义
 
@@ -46,9 +49,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 短号统一渲染为带 `#` 前缀的 `#NN`，与 task.md frontmatter 的 `short_id` 渲染一致。`#` 在 bash 中是注释起始符，示例命令若直接粘贴需视 TUI 而定（裸数字 `NN` 与 `#NN` 都被 `task-short-id.js resolve` 接受）。
 
-## 完成时间收尾行（Completed at）
+## Agent 输出收尾行（Completed at）
 
-所有读取本规则、并向用户渲染「下一步 / 告知用户」输出的 skill，在面向用户输出的**绝对最后一行**统一追加一行完成时间，便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
+本节是与「下一步输出结构」**并列的独立规则**，不隶属于「下一步」块。任何向用户渲染输出的 skill 都必须在面向用户输出的**绝对最后一行**追加完成时间收尾行——包括**声明「不渲染下一步命令」的 complete-task**，以及前置条件未满足而提前 return 的**错误 / 早退路径**。便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
 
 ```text
 Completed at: YYYY-MM-DD HH:mm:ss

package/templates/.agents/rules/pr-checks-commands.en.md

@@ -0,0 +1,5 @@
+# PR Checks Platform Commands
+
+This code platform does not provide built-in pull request check commands.
+
+Platform-specific check monitoring is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Keep local task artifacts as the source of truth, or install a platform-specific template pack before running the `watch-pr` skill.

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

@@ -0,0 +1,62 @@
+# PR Checks Platform Commands (GitHub)
+
+Read this file before watching a PR's required checks, resolving a failing run, pulling failure logs, or reading the current branch's PR. The `watch-pr` skill's platform-specific commands live here; the skill body and `reference/` stay platform-agnostic.
+
+## Current Branch PR / Repository Info
+
+```bash
+gh pr view --json number -q .number                  # PR number for the current branch
+gh pr view {pr#} --json headRefOid -q .headRefOid    # PR head SHA
+gh repo view --json nameWithOwner -q .nameWithOwner  # {owner}/{repo}
+```
+
+If `gh` is not authenticated or a command fails, stop or degrade per the calling skill's error handling.
+
+## Watch Required Checks
+
+```bash
+gh pr checks {pr#} --required --watch --fail-fast -i 30 \
+  --json name,bucket,link,workflow
+```
+
+- `--required`: include only checks the repository's branch protection marks as required.
+- `--watch`: block until those checks finish; `--fail-fast`: exit watch on the first failure.
+- `-i 30`: poll every 30 seconds (backoff). **Overall time cap default 30 minutes (1800 seconds)**: use the timeout mechanism that matches the execution environment; on timeout, treat as "pending" (exit code 8).
+  - POSIX shell: `timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
+  - PowerShell (Windows): use a job timeout —
+    ```powershell
+    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
+    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <treat as "pending"> }
+    ```
+  - Platform-neutral fallback (no external timeout tool): record the start time, loop `gh pr checks {pr#} --required --json name,bucket,link,workflow` **without** `--watch`, sleeping `-i` seconds each round and checking whether any `bucket` is still `pending`; if the elapsed time reaches 1800 seconds without finishing, exit the loop and treat as "pending".
+- The `bucket` field of `--json` classifies each check as `pass` / `fail` / `pending` / `skipping` / `cancel`.
+
+Exit code semantics:
+
+| Exit code | Meaning | Outcome class |
+|-----------|---------|---------------|
+| 0 | all required checks passed | all green |
+| 1 | at least one failed / errored | failure |
+| 8 | still pending (watch timed out or was cut off by `timeout`) | pending |
+
+Old `gh` (< 2.93) without `--required`: fall back to `gh pr checks {pr#} --watch --fail-fast` (i.e. "all checks must succeed"), and note this degradation in the help/report and suggest upgrading `gh`.
+
+## Resolve a Failing Run id and Pull Logs
+
+`gh pr checks --json` does not return a run id directly, but it returns each failing check's `link` (a URL to the run/job). Resolve in this deterministic order:
+
+1. Extract from the failing check's `link` via regex: `https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → group 1 is the run id (optional group 2 is the job id).
+2. When `link` is not a run URL or cannot be parsed, query check-runs by head SHA:
+   ```bash
+   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
+   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
+     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
+   ```
+   then extract the run id from `details_url` the same way.
+3. If neither path yields a run id → treat as "unlocatable" and use the skill's help exit; do not self-heal blindly.
+
+Once the run id is known, pull the failure logs:
+
+```bash
+gh run view {run-id} --log-failed
+```

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

@@ -0,0 +1,62 @@
+# PR 检查平台命令（GitHub）
+
+在监控 PR 的 required checks、解析失败 run、拉取失败日志或读取当前分支 PR 前先读取本文件。`watch-pr` 技能的平台专属命令集中在此，技能正文与 `reference/` 保持平台无关。
+
+## 当前分支 PR / 仓库信息
+
+```bash
+gh pr view --json number -q .number          # 当前分支对应的 PR 号
+gh pr view {pr#} --json headRefOid -q .headRefOid   # PR head SHA
+gh repo view --json nameWithOwner -q .nameWithOwner # {owner}/{repo}
+```
+
+`gh` 未认证或命令失败时，按调用方技能的错误处理停止或降级。
+
+## 监控 required checks
+
+```bash
+gh pr checks {pr#} --required --watch --fail-fast -i 30 \
+  --json name,bucket,link,workflow
+```
+
+- `--required`：只纳入仓库分支保护标记为 required 的 checks。
+- `--watch`：阻塞直到这些 checks 全部跑完；`--fail-fast`：出现首个失败即退出 watch。
+- `-i 30`：轮询间隔 30 秒（退避）。**总时长上限默认 30 分钟（1800 秒）**：按执行环境选用对应的超时方式，超时即按「挂起」处理（退出码 8）。
+  - POSIX shell：`timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
+  - PowerShell（Windows）：用作业超时——
+    ```powershell
+    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
+    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <按「挂起」处理> }
+    ```
+  - 平台中立回退（无外部超时工具时）：记录开始时间，循环执行**不带** `--watch` 的 `gh pr checks {pr#} --required --json name,bucket,link,workflow`，每轮 sleep `-i` 秒并检查 `bucket` 是否仍有 `pending`；累计时长 ≥ 1800 秒仍未结束 → 退出循环按「挂起」处理。
+- `--json` 的 `bucket` 字段把每个 check 归类为 `pass` / `fail` / `pending` / `skipping` / `cancel`。
+
+退出码语义：
+
+| 退出码 | 含义 | 结果分类 |
+|--------|------|----------|
+| 0 | 全部 required checks 通过 | 全绿 |
+| 1 | 至少一个失败 / 出错 | 失败 |
+| 8 | 仍有 pending（watch 超时或被 `timeout` 截断） | 挂起 |
+
+旧版 `gh`（< 2.93）若不支持 `--required`：回退为 `gh pr checks {pr#} --watch --fail-fast`（即「所有 check 必须 success」），并在求助/报告中注明该降级、建议升级 `gh`。
+
+## 解析失败 run id 并拉日志
+
+`gh pr checks --json` 不直接返回 run id，但返回失败 check 的 `link`（指向 run/job 的 URL）。按确定性顺序解析：
+
+1. 从失败 check 的 `link` 用正则提取：`https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → 第 1 组为 run id（可选第 2 组为 job id）。
+2. `link` 非 run URL 或无法解析时，用 head SHA 查 check-runs：
+   ```bash
+   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
+   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
+     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
+   ```
+   再从 `details_url` 同法提取 run id。
+3. 两路都拿不到 run id → 视为「不可定位」，按技能的求助出口处理，不盲目自愈。
+
+拿到 run id 后拉失败日志：
+
+```bash
+gh run view {run-id} --log-failed
+```

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

@@ -0,0 +1,5 @@
+# PR 检查平台命令
+
+当前代码平台未内置 Pull Request 检查命令支持。
+
+自定义平台会跳过平台专属的检查监控，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行 `watch-pr` 技能。

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

@@ -32,6 +32,7 @@ Aggregation rules:
 - build the review-history table from `review-code*` and `code*`
 - extract the test summary from `code*`
 - if one artifact class is missing, treat it as "no data for this stage" and continue
+- Manual verification section: extract items requiring human confirmation/fallback from the "Assumptions"/"Open Questions" of the latest `plan*` and the "Environment-Blocked Findings"/"Self-Doubt" sections (i.e. env-blocked items) of the latest `review-code*`; when there are none, write the explicit placeholder `- None — no items require manual verification`, never leave it empty
 
 ## Comment Body Template
 
@@ -46,6 +47,12 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
+### ⚠️ Manual Verification Required
+
+> Items in this change that need human confirmation/fallback; reviewers can reply under this comment once verified.
+
+- {manual-verify-item}
+
 ### Key Technical Decisions
 
 - {decision-1}

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

@@ -32,6 +32,7 @@
 - 用 `review-code*` 与 `code*` 构建审查历程表
 - 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
+- 需人工校验段落：从最新 `plan*` 的「假设」「未决问题」与最新 `review-code*` 的「环境性遗留」「自我质疑」提取需人工确认/兜底事项；无任何事项时写显式占位 `- 无需人工校验事项`，不得留空
 
 ## 评论体模板
 
@@ -46,6 +47,12 @@
 
 **更新时间**：{当前时间}
 
+### ⚠️ 需人工校验
+
+> 本次改动中需人工确认/兜底的事项；reviewer 校验后可在本评论下回复收尾。
+
+- {manual-verify-item}
+
 ### 关键技术决策
 
 - {decision-1}

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

@@ -189,7 +189,7 @@ 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). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **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 format:
 ```

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

@@ -188,7 +188,7 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 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` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 输出格式：
 ```

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

@@ -106,7 +106,9 @@ 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). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **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).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" 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 blocked/, so read it from `.agents/workspace/blocked/{task-id}/task.md`). This block is independent of "Next step" semantics.
 
 Output format:
 ```
@@ -116,6 +118,11 @@ Blocking reason: {summary}
 Required to unblock: {what's needed}
 Archived to: .agents/workspace/blocked/{task-id}/
 
+Optional: clean up this task's sandbox
+(The task is blocked and moved to blocked/; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
 To unblock when the issue is resolved:
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # Then update task.md: status -> active, remove blocked_at

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

@@ -105,7 +105,9 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 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` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
 ```
@@ -115,6 +117,11 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 解除阻塞所需：{需要什么}
 归档路径：.agents/workspace/blocked/{task-id}/
 
+可选：清理本任务的沙箱
+（任务已阻塞并移到 blocked/，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 解除阻塞时执行：
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # 然后更新 task.md：status -> active，移除 blocked_at

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

@@ -119,7 +119,9 @@ 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). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **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).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" 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.
 
 Output format:
 ```
@@ -129,6 +131,11 @@ Cancellation reason: {reason}
 Status label: {status-label or skipped}
 Target path: .agents/workspace/completed/{task-id}/
 
+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}
+
 Next step - inspect the moved task:
   - Claude Code / OpenCode: /check-task {task-ref}
   - Gemini CLI: /{{project}}:check-task {task-ref}

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

@@ -118,7 +118,9 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 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` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
 ```
@@ -128,6 +130,11 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 状态标签：{status-label 或 skipped}
 目标路径：.agents/workspace/completed/{task-id}/
 
+可选：清理本任务的沙箱
+（任务已归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 下一步 - 查看已转移任务：
   - Claude Code / OpenCode：/check-task {task-ref}
   - Gemini CLI：/{{project}}:check-task {task-ref}

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

@@ -125,7 +125,7 @@ Recommend the appropriate next skill based on the current workflow state. You mu
 >
 > **Important: if the latest review report contains any issue at all, do not use the corresponding review-passed row. Use the corresponding has-issues row instead.**
 >
-> Before rendering the commands in the table below, read `.agents/rules/next-step-output.md` and render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the table commands below 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).
 
 | Current State              | Claude Code / OpenCode                              | Gemini CLI                               | Codex CLI                                           |
 |----------------------------|-----------------------------------------------------|------------------------------------------|-----------------------------------------------------|

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

@@ -124,7 +124,7 @@ description: "查看任务的当前状态和进度"
 >
 > **特别注意：只要最新审查报告中存在任何问题，就不能使用对应「审查通过」行。必须改用对应「审查有问题」行。**
 >
-> 渲染下方表格中的命令前，先读取 `.agents/rules/next-step-output.md`，把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 下方表格中命令的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 | 当前状态           | Claude Code / OpenCode       | Gemini CLI                               | Codex CLI                    |
 |--------------------|------------------------------|------------------------------------------|------------------------------|

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -93,7 +93,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 ### 8. Inform User
 
-> **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 "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **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).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
 
 ```
 Code Scanning alert #{alert-number} dismissed.
@@ -107,6 +109,11 @@ View: {html_url}
 
 Note: it can be reopened on the platform if necessary.
 
+Optional: clean up this task's sandbox
+(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
 Next step - complete and archive the task if a related task exists:
   - Claude Code / OpenCode: /complete-task {task-ref}
   - Gemini CLI: /{{project}}:complete-task {task-ref}

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -93,7 +93,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 ### 8. 告知用户
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 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` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
 
 ```
 Code Scanning 告警 #{alert-number} 已关闭。
@@ -107,6 +109,11 @@ Code Scanning 告警 #{alert-number} 已关闭。
 
 注意：如有需要，可在 平台上重新打开。
 
+可选：清理本任务的沙箱
+（关联任务的沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 下一步 - 完成并归档任务（如有关联任务）：
   - Claude Code / OpenCode：/complete-task {task-ref}
   - Gemini CLI：/agent-infra:complete-task {task-ref}

package/templates/.agents/skills/close-dependabot/SKILL.en.md

@@ -101,7 +101,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 ### 8. Inform User
 
-> **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 "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **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).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
 
 ```
 Security alert #{alert-number} dismissed.
@@ -115,6 +117,11 @@ View: {alert-url}
 
 Note: it can be reopened on the platform if necessary.
 
+Optional: clean up this task's sandbox
+(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
 Next step - complete and archive the task if a related task exists:
   - Claude Code / OpenCode: /complete-task {task-ref}
   - Gemini CLI: /{{project}}:complete-task {task-ref}