@fitlab-ai/agent-infra 0.7.0 → 0.7.2

package/lib/update.ts

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { info, ok, err } from './log.ts';
 import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
+import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.ts';
+import type { BuiltinTUIId } from './builtin-tuis.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -17,14 +19,17 @@ type UpdateConfig = {
   platform?: { type?: string };
   requiresPullRequest?: boolean;
   sandbox?: Record<string, unknown>;
+  task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
+  tuis?: unknown;
 };
 
 type Defaults = {
   platform: { type: string };
   requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
 };
@@ -45,7 +50,7 @@ function isPathOwnedByOtherPlatform(relativePath: string, platformType: string):
   return candidate !== platformType;
 }
 
-function syncFileRegistry(config: UpdateConfig, platformType: string) {
+function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUIs: Set<BuiltinTUIId>) {
   config.files ||= {};
   const before = JSON.stringify({
     files: {
@@ -67,6 +72,7 @@ function syncFileRegistry(config: UpdateConfig, platformType: string) {
 
   for (const entry of defaults.files.managed) {
     if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
+    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
     if (!allExisting.includes(entry)) {
       config.files.managed.push(entry);
       added.managed.push(entry);
@@ -74,6 +80,7 @@ function syncFileRegistry(config: UpdateConfig, platformType: string) {
   }
   for (const entry of defaults.files.merged) {
     if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
+    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
     if (!allExisting.includes(entry)) {
       config.files.merged.push(entry);
       added.merged.push(entry);
@@ -118,6 +125,7 @@ async function cmdUpdate(): Promise<void> {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
+  const enabledTUIs = resolveEnabledTUIs(config.tuis);
   const replacements = { project, org };
 
   info(`Updating seed files for: ${project}`);
@@ -150,35 +158,42 @@ async function cmdUpdate(): Promise<void> {
     // Ignore missing legacy script from pre-ESM installs.
   }
 
-  // update Claude command
-  renderFile(
-    path.join(templateDir, '.claude', 'commands', claudeSrc),
-    path.join('.claude', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Updated .claude/commands/update-agent-infra.md');
+  // update Claude command (only if enabled)
+  if (enabledTUIs.has('claude-code')) {
+    renderFile(
+      path.join(templateDir, '.claude', 'commands', claudeSrc),
+      path.join('.claude', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Updated .claude/commands/update-agent-infra.md');
+  }
 
-  // update Gemini command
-  renderFile(
-    path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-    path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-    replacements
-  );
-  ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
+  // update Gemini command (only if enabled)
+  if (enabledTUIs.has('gemini-cli')) {
+    renderFile(
+      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
+      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
+      replacements
+    );
+    ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
+  }
 
-  // update OpenCode command
-  renderFile(
-    path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-    path.join('.opencode', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Updated .opencode/commands/update-agent-infra.md');
+  // update OpenCode command (only if enabled)
+  if (enabledTUIs.has('opencode')) {
+    renderFile(
+      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
+      path.join('.opencode', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Updated .opencode/commands/update-agent-infra.md');
+  }
 
   // sync file registry
-  const { added, changed } = syncFileRegistry(config, platformType);
+  const { added, changed } = syncFileRegistry(config, platformType, enabledTUIs);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;
+  const taskAdded = !config.task;
   const labelsAdded = !config.labels;
   const requiresPullRequestAdded = config.requiresPullRequest === undefined;
   let configChanged = changed;
@@ -193,6 +208,11 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
+  if (taskAdded) {
+    config.task = structuredClone(defaults.task);
+    configChanged = true;
+  }
+
   if (labelsAdded) {
     config.labels = structuredClone(defaults.labels);
     configChanged = true;
@@ -213,13 +233,16 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || labelsAdded || requiresPullRequestAdded) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
       if (sandboxAdded) {
         info(`Default sandbox config added to ${CONFIG_PATH}.`);
       }
+      if (taskAdded) {
+        info(`Default task.shortIdLength=${defaults.task.shortIdLength} added to ${CONFIG_PATH}.`);
+      }
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
@@ -232,6 +255,9 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && sandboxAdded) {
       info(`Default sandbox config added to ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && taskAdded) {
+      info(`Default task.shortIdLength=${defaults.task.shortIdLength} added to ${CONFIG_PATH}.`);
+    }
     if (hasNewEntries && labelsAdded) {
       info(`Default labels.in config added to ${CONFIG_PATH}.`);
     }
@@ -249,12 +275,27 @@ async function cmdUpdate(): Promise<void> {
   console.log('');
   ok('Seed files updated successfully!');
   console.log('');
-  console.log('  Next step: run the full update in your AI TUI:');
-  console.log('');
-  console.log('    Claude Code / OpenCode:  /update-agent-infra');
-  console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-  console.log('    Codex CLI:               $update-agent-infra');
-  console.log('');
+  if (enabledTUIs.size === 0) {
+    console.log('  No built-in TUI enabled (tuis: []).');
+    console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
+    console.log('');
+  } else {
+    console.log('  Next step: run the full update in your AI TUI:');
+    console.log('');
+    const claudeOrOpencode: string[] = [];
+    if (enabledTUIs.has('claude-code')) claudeOrOpencode.push('Claude Code');
+    if (enabledTUIs.has('opencode')) claudeOrOpencode.push('OpenCode');
+    if (claudeOrOpencode.length > 0) {
+      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
+    }
+    if (enabledTUIs.has('gemini-cli')) {
+      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
+    }
+    if (enabledTUIs.has('codex')) {
+      console.log('    Codex CLI:               $update-agent-infra');
+    }
+    console.log('');
+  }
 }
 
 export { cmdUpdate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

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

@@ -210,6 +210,38 @@ The `files` field in `.agents/.airc.json` groups project files into three catego
 
 `ejected` entries support literal paths or globs, using the same matching rules as `merged`.
 
+## Built-in TUI Selection
+
+Use the top-level `.agents/.airc.json` `tuis` array to pick which built-in TUIs (`claude-code`, `codex`, `gemini-cli`, `opencode`) agent-infra should install command files for and keep in sync.
+
+| Value | Meaning |
+|-------|---------|
+| `tuis` missing or `null` | All four built-in TUIs are enabled (backward-compatible default for legacy `.airc.json` predating this field). |
+| `tuis: []` | No built-in TUI is managed. Use this when the project only relies on `customTUIs` and does not need any built-in command files installed. |
+| `tuis: [<subset>]` | Only the listed TUIs are managed. Unknown ids are ignored. |
+
+`ai init` includes an interactive multi-select for this field:
+
+- Press Enter to accept the default (all built-in TUIs enabled).
+- Type comma-separated numbers or ids (e.g. `1,3` or `claude-code,opencode`) to keep a subset.
+- Type `none` to explicitly disable every built-in TUI (typically combined with a `customTUIs` entry added later).
+- Invalid input (duplicate, out-of-range, unknown id, whitespace-only) aborts init with a non-zero exit code.
+
+### Side effects of disabling a TUI
+
+When you disable a built-in TUI (either via `ai init` or by hand-editing `.airc.json`), the next `ai update` / `update-agent-infra` will:
+
+- skip seed command writes for that TUI (e.g. `.gemini/commands/<project>/update-agent-infra.toml`);
+- skip the TUI's owned default entries when backfilling `files.managed` / `files.merged`;
+- **clean up existing files** under the TUI's owned path prefix (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`) — these are listed in `report.managed.removed`, mirroring the cleanup behavior when switching `platform`.
+
+To opt a specific file out of this cleanup, list it in `files.ejected`; ejected entries owned by disabled TUIs are preserved as-is and are not re-created by sync.
+
+### Relation to other config fields
+
+- `tuis` controls **which TUI command files agent-infra writes and maintains**. It is independent from `sandbox.tools`, which controls **which CLIs the sandbox image installs**. Toggling one does not affect the other; the README for `sandbox.tools` lives in the Sandbox section.
+- `tuis` is independent from `customTUIs` (see below). CustomTUI command files are not removed when you disable a built-in TUI, even if the customTUI's `dir` falls under that TUI's owned prefix (e.g. a customTUI configured with `dir: ".codex/commands"` is preserved when `codex` is disabled).
+
 ## Custom TUI Configuration
 
 Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.

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

@@ -210,6 +210,38 @@ args: "<task-id>"   # 可选
 
 `ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
 
+## 内建 TUI 选择
+
+`.agents/.airc.json` 顶层 `tuis` 数组用于决定 agent-infra 应当为哪些内建 TUI（`claude-code`、`codex`、`gemini-cli`、`opencode`）安装并维护命令文件。
+
+| 取值 | 含义 |
+|------|------|
+| `tuis` 缺失或为 `null` | 启用全部四个内建 TUI（向后兼容默认，适用于本字段引入之前的 `.airc.json`） |
+| `tuis: []` | 不维护任何内建 TUI。适用于只依赖 `customTUIs`、不需要安装任何内建命令文件的项目 |
+| `tuis: [<子集>]` | 仅维护列出的 TUI；未知 id 会被忽略 |
+
+`ai init` 会通过交互式多选询问该字段：
+
+- 直接回车 = 接受默认值（全部内建 TUI 启用）。
+- 输入逗号分隔的编号或 id（如 `1,3` 或 `claude-code,opencode`）= 只保留子集。
+- 输入 `none` = 明确不启用任何内建 TUI（通常配合后续在 `customTUIs` 添加条目使用）。
+- 非法输入（重复、超界、未知 id、纯空白）会让 init 以非零退出码终止。
+
+### 取消某个 TUI 的副作用
+
+通过 `ai init` 或手工编辑 `.airc.json` 取消某个内建 TUI 后，下一次 `ai update` / `update-agent-infra` 会：
+
+- 跳过该 TUI 的 seed 命令文件写入（例如 `.gemini/commands/<project>/update-agent-infra.toml`）；
+- 在回填 `files.managed` / `files.merged` 时跳过该 TUI owned 的默认条目；
+- **物理清理**该 TUI owned 路径前缀（`.claude/`、`.codex/`、`.gemini/`、`.opencode/`）下的已有文件——清理列表会出现在 `report.managed.removed`，与切换 `platform` 时的清理行为一致。
+
+若希望保留某个具体文件，把它加入 `files.ejected`：被 ejected 的、属于已取消 TUI 的条目会保持原状，sync 不会重新创建也不会删除。
+
+### 与其他配置字段的关系
+
+- `tuis` 控制 **agent-infra 写入与维护哪些 TUI 的命令文件**，与 `sandbox.tools`（控制**沙箱镜像里安装哪些 CLI**）相互独立。两者互不影响；`sandbox.tools` 的说明见 Sandbox 一节。
+- `tuis` 与 `customTUIs`（见下）相互独立。取消某个内建 TUI 时 customTUI 命令文件不会被清理，即便 customTUI 的 `dir` 落在该 TUI 的 owned 前缀下（例如 `dir: ".codex/commands"` 的 customTUI 在 `codex` 被取消时仍会保留）。
+
 ## 自定义 TUI 配置
 
 当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。

package/templates/.agents/hooks/auto-resume.sh

@@ -0,0 +1,87 @@
+#!/bin/sh
+# StopFailure hook: auto-resume Claude Code after a recoverable API error.
+#
+# Fires when a turn ends due to an API error. Runs four gates and, if all pass,
+# injects a "please continue" message into the current tmux pane via send-keys.
+# StopFailure output and exit code are ignored by Claude Code, so recovery is
+# delivered out-of-band through tmux; every exit path here returns 0 and the
+# only observable trace is the log file.
+#
+# Intentionally NOT using `set -e`: the network probe, tmux and state-file
+# writes may fail locally without warranting an abort of the whole script.
+
+LOG="$HOME/.claude/auto-resume.log"
+STATE_DIR="$HOME/.claude/auto-resume.state"
+WHITELIST="unknown server_error overloaded"
+WINDOW=1800
+MAX=10
+PROBE_URL="https://api.anthropic.com/"
+PROBE_DEADLINE=60
+RESUME_TEXT="Unexpected interruption. Please continue the unfinished operation."
+
+log() {
+  mkdir -p "$HOME/.claude" 2>/dev/null
+  printf '%s %s\n' "$(date '+%Y-%m-%d %H:%M:%S%z')" "$1" >> "$LOG"
+  lines=$(wc -l < "$LOG" 2>/dev/null | tr -cd '0-9')
+  [ -z "$lines" ] && lines=0
+  if [ "$lines" -gt 5000 ]; then
+    tail -n 2500 "$LOG" > "$LOG.tmp" 2>/dev/null && mv "$LOG.tmp" "$LOG"
+  fi
+}
+
+# Read the StopFailure payload once, then extract session_id and error. The
+# `error` field identifies the API error type and drives the whitelist gate.
+payload=$(cat)
+session_id=$(printf '%s' "$payload" | node -e 'let c=[];process.stdin.on("data",d=>c.push(d));process.stdin.on("end",()=>{try{const p=JSON.parse(Buffer.concat(c).toString());process.stdout.write(String(p.session_id||""))}catch{process.stdout.write("")}})' 2>/dev/null)
+error=$(printf '%s' "$payload" | node -e 'let c=[];process.stdin.on("data",d=>c.push(d));process.stdin.on("end",()=>{try{const p=JSON.parse(Buffer.concat(c).toString());process.stdout.write(String(p.error||""))}catch{process.stdout.write("")}})' 2>/dev/null)
+
+# Gate 1: only act inside a tmux pane; stay silent everywhere else.
+if [ -z "$TMUX_PANE" ]; then
+  log "not in tmux, skip (error=$error)"
+  exit 0
+fi
+
+# Gate 2: only recover from the whitelisted, retriable error types.
+case " $WHITELIST " in
+  *" $error "*) : ;;
+  *) log "blocked: non-recoverable error=$error"; exit 0 ;;
+esac
+
+# Gate 3: back off after MAX fires within a WINDOW-second sliding window per session.
+mkdir -p "$STATE_DIR" 2>/dev/null
+# Treat the payload session_id as untrusted: sanitize to a safe filename so a
+# value like "../outside" cannot write the state file outside STATE_DIR.
+safe_session=$(printf '%s' "${session_id:-nosession}" | tr -c 'A-Za-z0-9._-' '_')
+f="$STATE_DIR/$safe_session.count"
+now=$(date +%s)
+if [ -f "$f" ]; then
+  awk -v n="$now" -v w="$WINDOW" '$1 > n - w' "$f" > "$f.tmp" 2>/dev/null && mv "$f.tmp" "$f"
+fi
+# BSD `wc -l` (macOS) pads the count with leading spaces; strip to bare digits
+# so the integer compare and the log line stay portable across GNU/BSD.
+count=$( [ -f "$f" ] && wc -l < "$f" 2>/dev/null | tr -cd '0-9' || echo 0 )
+[ -z "$count" ] && count=0
+if [ "$count" -ge "$MAX" ]; then
+  log "backoff: $count fires in 30m, skip (error=$error)"
+  exit 0
+fi
+echo "$now" >> "$f"
+
+# Gate 4: wait until the API is reachable again, up to PROBE_DEADLINE seconds.
+# No --fail: any HTTP response (incl. 401/404) proves TLS/network connectivity.
+waited=0
+until curl -s -o /dev/null --max-time 3 "$PROBE_URL"; do
+  waited=$((waited + 3))
+  if [ "$waited" -ge "$PROBE_DEADLINE" ]; then
+    log "probe timeout after ${waited}s, skip (error=$error)"
+    exit 0
+  fi
+  sleep 3
+done
+log "probe ok after ${waited}s (error=$error)"
+
+# Inject: Escape first to leave any non-input TUI state, then the resume text.
+tmux send-keys -t "$TMUX_PANE" Escape 2>/dev/null
+tmux send-keys -t "$TMUX_PANE" "$RESUME_TEXT" Enter 2>/dev/null
+log "send-keys done (error=$error)"
+exit 0

package/templates/.agents/rules/create-issue.github.en.md

@@ -180,7 +180,7 @@ Update task.md:
 - Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
 - Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
 
-> Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Task Created`), written by the caller SKILL step 3.
+> Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Create Task`), written by the caller SKILL step 3.
 
 ### 9. Return the Result
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -180,7 +180,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 - 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
 - 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
 
-> 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Task Created`），由调用方 SKILL 步骤 3 写入。
+> 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Create Task`），由调用方 SKILL 步骤 3 写入。
 
 ### 9. 返回结果
 

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -81,7 +81,10 @@ if [ "$has_triage" = "true" ]; then
 fi
 ```
 
-6. If `has_triage=false`, the target milestone does not exist, or the branch ancestry cannot be determined reliably, keep the original milestone unchanged
+6. Keep the original milestone unchanged only in the following cases (otherwise narrow per step 5):
+   - Trunk mode with no open concrete version under the release line — the `code-task` / `create-pr` `verify_milestone_specific` gate will fail and prompt maintainers to create the missing concrete version
+   - Multi-release-line mode when both `git merge-base --is-ancestor` checks are unreliable or the remote refs are missing
+   - In any mode, `has_triage=false` (the bot will reconcile later)
 
 Suggested concrete-version query:
 

package/templates/.agents/rules/milestone-inference.github.zh-CN.md

@@ -81,7 +81,10 @@ if [ "$has_triage" = "true" ]; then
 fi
 ```
 
-6. 如果 `has_triage=false`、目标 milestone 不存在，或无法可靠判断 -> 保持原 milestone 不变
+6. 仅在以下情况保持原 milestone 不变（其余情形必须按步骤 5 收窄）：
+   - 主干模式下版本线下没有 open 具体版本 —— `code-task` / `create-pr` 的 `verify_milestone_specific` gate 会 FAIL，提醒维护者补建具体版本
+   - 多版本分支模式下 `git merge-base --is-ancestor` 两条判断都不可靠或远程引用缺失
+   - 任意模式下 `has_triage=false`（由 bot 后补）
 
 具体版本查询建议：
 

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

@@ -0,0 +1,59 @@
+# 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.
+
+## Placeholder semantics
+
+| Placeholder | Meaning | Rendered form |
+|-------------|---------|---------------|
+| `{task-ref}` | Current task **short id** | `#`-prefixed, e.g. `#15`; falls back to the full `TASK-id` when unavailable |
+| `{task-id}` | Current task **full id** | `TASK-YYYYMMDD-HHMMSS` |
+
+## Scope
+
+- **Next-step TUI commands** (`/analyze-task`, `/{{project}}:review-code`, `$create-pr`, etc., including commands inside Markdown table cells) → always use `{task-ref}` (short id).
+- **"Task info" / "Task status" structured field lines** → show full id and short id together: `- Task ID: {task-id} (short id {task-ref})`.
+- **Report titles** (`Task {task-id} ... completed`) and **artifact paths** (`.agents/workspace/active/{task-id}/...`) → keep the full `{task-id}` (physical path and archive key, must not change).
+
+## Obtaining the short id (`{task-ref}`)
+
+The single source of truth for short ids is the registry `.agents/workspace/active/.short-ids.json` (via `task-short-id.js`). **Never** read the `short_id` field from task.md frontmatter (that field is not authoritative).
+
+Once the full `$task_id` is resolved, use the snippet below to look up the short id; it returns `#NN` on hit and falls back to the full `TASK-id` on miss:
+
+```bash
+task_ref=$(node -e '
+const cp=require("child_process");
+const out=cp.execSync("node .agents/scripts/task-short-id.js list",{encoding:"utf8"});
+const ids=(JSON.parse(out).ids)||{};
+const full=process.argv[1];
+const hit=Object.entries(ids).find(([,v])=>v===full);
+process.stdout.write(hit?("#"+hit[0]):full);
+' "$task_id")
+# Example: $task_id=TASK-20260613-225809 -> task_ref=#15
+```
+
+## Fallback conditions
+
+`{task-ref}` falls back to the full `TASK-id` in these cases (i.e. the registry has no matching short id):
+
+- **Unallocated**: very early paths before `create-task` / `import-*` / `restore-task` has allocated a short id.
+- **Released**: after a task is archived by `complete-task` / `cancel-task` / `block-task` / `close-codescan` / `close-dependabot`, its short id is immediately removed from the registry. The terminal/summary lines of these archival skills therefore fall back to the full `TASK-id` naturally, with no special-casing.
+
+`restore-task` re-allocates a short id when restoring a task (possibly different from before); the snippet picks up the new short id.
+
+## `#` prefix and shell quoting
+
+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)
+
+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:
+
+```text
+Completed at: YYYY-MM-DD HH:mm:ss
+```
+
+- Value command (local timezone, no offset): `date "+%Y-%m-%d %H:%M:%S"`
+- Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the env-blocked reminder), the completion line goes after that reminder.
+- This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.

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

@@ -0,0 +1,59 @@
+# 下一步输出规则
+
+各 skill 在「告知用户」步骤渲染「下一步」命令与「任务信息」段时，统一按本规则呈现任务 ID 形态。渲染下一步前先读取本文件。
+
+## 占位符语义
+
+| 占位符 | 含义 | 渲染形态 |
+|--------|------|----------|
+| `{task-ref}` | 当前任务**短号** | 带 `#` 前缀，如 `#15`；取不到时回退完整 `TASK-id` |
+| `{task-id}` | 当前任务**完整 ID** | `TASK-YYYYMMDD-HHMMSS` |
+
+## 适用范围
+
+- **下一步 TUI 命令**（`/analyze-task`、`/{{project}}:review-code`、`$create-pr` 等，含 Markdown 表格单元格内的命令）→ 一律用 `{task-ref}`（短号）。
+- **「任务信息」/「任务状态」结构化字段行** → 完整 ID 与短号同显：`- 任务 ID：{task-id}（短号 {task-ref}）`。
+- **报告标题**（`任务 {task-id} ... 完成`）与**产出文件路径**（`.agents/workspace/active/{task-id}/...`）→ 保持完整 `{task-id}`（物理路径与归档键，不可改）。
+
+## 取短号（`{task-ref}`）
+
+短号唯一真源是注册表 `.agents/workspace/active/.short-ids.json`（经 `task-short-id.js`）。**禁止**读取 task.md frontmatter 的 `short_id` 字段（该字段不可信）。
+
+在已解析出完整 `$task_id` 后，用以下片段反查短号；命中返回 `#NN`，未命中自动回退完整 `TASK-id`：
+
+```bash
+task_ref=$(node -e '
+const cp=require("child_process");
+const out=cp.execSync("node .agents/scripts/task-short-id.js list",{encoding:"utf8"});
+const ids=(JSON.parse(out).ids)||{};
+const full=process.argv[1];
+const hit=Object.entries(ids).find(([,v])=>v===full);
+process.stdout.write(hit?("#"+hit[0]):full);
+' "$task_id")
+# 示例：$task_id=TASK-20260613-225809 -> task_ref=#15
+```
+
+## 回退条件
+
+`{task-ref}` 在以下情况回退为完整 `TASK-id`（即注册表查不到对应短号）：
+
+- **未分配**：任务尚未经 `create-task` / `import-*` / `restore-task` 分配短号的极早期路径。
+- **已释放**：任务经 `complete-task` / `cancel-task` / `block-task` / `close-codescan` / `close-dependabot` 归档后，短号立即从注册表移除。这些归档类 skill 的终态/摘要行因此自然回退完整 `TASK-id`，无需特判。
+
+`restore-task` 恢复任务时会重新分配短号（可能与历史不同），片段会取到新短号。
+
+## `#` 前缀与 shell 引用
+
+短号统一渲染为带 `#` 前缀的 `#NN`，与 task.md frontmatter 的 `short_id` 渲染一致。`#` 在 bash 中是注释起始符，示例命令若直接粘贴需视 TUI 而定（裸数字 `NN` 与 `#NN` 都被 `task-short-id.js resolve` 接受）。
+
+## 完成时间收尾行（Completed at）
+
+所有读取本规则、并向用户渲染「下一步 / 告知用户」输出的 skill，在面向用户输出的**绝对最后一行**统一追加一行完成时间，便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
+
+```text
+Completed at: YYYY-MM-DD HH:mm:ss
+```
+
+- 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
+- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 env-blocked 提醒），收尾行排在该提醒行之后。
+- 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。