@fitlab-ai/agent-infra 0.7.1 → 0.7.3

package/lib/task/frontmatter.ts

@@ -0,0 +1,30 @@
+type Frontmatter = Record<string, string>;
+
+function parseTaskFrontmatter(content: string): Frontmatter {
+  const result: Frontmatter = {};
+  if (!content.startsWith('---')) return result;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return result;
+  const body = content.slice(3, end);
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim()) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim();
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function extractTitle(content: string): string {
+  for (const line of content.split('\n')) {
+    const m = /^#\s+(?:任务[:：]?\s*)?(.+)$/.exec(line.trim());
+    if (m && m[1]) return m[1].trim();
+  }
+  return '';
+}
+
+export { parseTaskFrontmatter, extractTitle };
+export type { Frontmatter };

package/lib/task/index.ts

@@ -0,0 +1,44 @@
+const USAGE = `Usage: ai task <command> [options]
+
+Commands:
+  ls [--all | --blocked | --completed]   List tasks (default: active)
+  show <N | #N | TASK-id>                Print a task.md
+
+Examples:
+  ai task ls
+  ai task show 11
+  ai task show TASK-20260612-162737
+
+Run 'ai task <command> --help' for details.`;
+
+export async function runTask(args: string[]): Promise<void> {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand) {
+    process.stdout.write(`${USAGE}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  switch (subcommand) {
+    case 'ls': {
+      const { ls } = await import('./commands/ls.ts');
+      ls(rest);
+      break;
+    }
+    case 'show': {
+      const { show } = await import('./commands/show.ts');
+      show(rest);
+      break;
+    }
+    default:
+      process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
+      process.stdout.write(`${USAGE}\n`);
+      process.exitCode = 1;
+  }
+}

package/lib/task/short-id.ts

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REGISTRY_NAME = '.short-ids.json';
+
+type NormalizeResult =
+  | { kind: 'shortId'; value: string }
+  | { kind: 'pass'; value: string }
+  | { kind: 'error'; message: string };
+
+type NormalizeOpts = { shortIdLength: number };
+
+function normalizeShortIdInput(input: string, opts: NormalizeOpts): NormalizeResult {
+  const L = opts.shortIdLength;
+  const m = /^#?(\d+)$/.exec(input);
+  if (!m) {
+    return { kind: 'pass', value: input };
+  }
+  const n = Number(m[1]);
+  if (n === 0) {
+    return {
+      kind: 'error',
+      message: `short id '${input}' is invalid (#${'0'.repeat(L)} is reserved)`
+    };
+  }
+  const max = Math.pow(10, L) - 1;
+  if (n > max) {
+    return {
+      kind: 'error',
+      message: `short id ${n} exceeds shortIdLength=${L} capacity (max=${max}); archive tasks or raise task.shortIdLength in .agents/.airc.json`
+    };
+  }
+  return { kind: 'shortId', value: `#${String(n).padStart(L, '0')}` };
+}
+
+type RegistrySchema = {
+  version: number;
+  ids: Record<string, string>;
+};
+
+function readRegistry(repoRoot: string): RegistrySchema | null {
+  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  if (!fs.existsSync(registryPath)) return null;
+  try {
+    const raw = fs.readFileSync(registryPath, 'utf8');
+    const data = JSON.parse(raw) as RegistrySchema;
+    if (!data || typeof data !== 'object' || !data.ids) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function readBranchFromTaskMd(repoRoot: string, taskId: string): string | null {
+  const taskMdPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+  if (!fs.existsSync(taskMdPath)) return null;
+  const content = fs.readFileSync(taskMdPath, 'utf8');
+  const m = content.match(/^branch:\s*(.+)$/m);
+  if (!m || !m[1]) return null;
+  return m[1].trim().replace(/^(["'])(.*)\1$/, '$2');
+}
+
+function loadShortIdByTaskId(repoRoot: string): Map<string, string> {
+  const registry = readRegistry(repoRoot);
+  const map = new Map<string, string>();
+  if (!registry) return map;
+  for (const [key, taskId] of Object.entries(registry.ids)) {
+    map.set(taskId, `#${key}`);
+  }
+  return map;
+}
+
+/**
+ * Resolve a branch to its active-task short id (`#NN`), or `null` when no
+ * active task is bound to that branch.
+ *
+ * Two-state semantics: this only consults the active registry
+ * (`active/.short-ids.json`) plus each `active/{taskId}/task.md`. Tasks moved
+ * to completed/blocked/cancelled/archive have already released their short id,
+ * so their branches return `null` — in `ai sandbox ls` that surfaces as `-`,
+ * meaning the sandbox is free to remove.
+ */
+function lookupShortIdByBranch(
+  branch: string,
+  repoRoot: string,
+  _opts?: { shortIdLength?: number }
+): string | null {
+  const registry = readRegistry(repoRoot);
+  if (!registry) return null;
+  const matches: string[] = [];
+  for (const [key, taskId] of Object.entries(registry.ids)) {
+    const taskBranch = readBranchFromTaskMd(repoRoot, taskId);
+    if (taskBranch && taskBranch === branch) {
+      matches.push(`#${key}`);
+    }
+  }
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    process.stderr.write(
+      `Warning: branch '${branch}' is bound to multiple active tasks: ${matches.join(', ')}; using ${matches[0]}\n`
+    );
+  }
+  return matches[0]!;
+}
+
+export { normalizeShortIdInput, lookupShortIdByBranch, loadShortIdByTaskId };
+export type { NormalizeResult, NormalizeOpts };

package/lib/update.ts

@@ -17,7 +17,8 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
-  requiresPullRequest?: boolean;
+  requiresPullRequest?: boolean;       // legacy field; read-only, migrated to prFlow then removed
+  prFlow?: 'required' | 'disabled';
   sandbox?: Record<string, unknown>;
   task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
@@ -27,7 +28,6 @@ type UpdateConfig = {
 
 type Defaults = {
   platform: { type: string };
-  requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
@@ -41,6 +41,25 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
+// One-time migration of the legacy project-level PR switch to the three-state
+// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
+// strong constraint `required`; `false` maps to `disabled`. A missing or
+// already-migrated config is left untouched (idempotent). Returns the new
+// prFlow value when a migration happened, otherwise null.
+function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
+  if (config.requiresPullRequest === true) {
+    delete config.requiresPullRequest;
+    config.prFlow = 'required';
+    return 'required';
+  }
+  if (config.requiresPullRequest === false) {
+    delete config.requiresPullRequest;
+    config.prFlow = 'disabled';
+    return 'disabled';
+  }
+  return null;
+}
+
 function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
   const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
   if (!top.startsWith('.')) return false;
@@ -195,7 +214,7 @@ async function cmdUpdate(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
-  const requiresPullRequestAdded = config.requiresPullRequest === undefined;
+  const prFlowMigrated = migratePrFlow(config);
   let configChanged = changed;
 
   if (platformAdded) {
@@ -218,8 +237,7 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
-  if (requiresPullRequestAdded) {
-    config.requiresPullRequest = defaults.requiresPullRequest;
+  if (prFlowMigrated) {
     configChanged = true;
   }
 
@@ -233,7 +251,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -246,8 +264,8 @@ async function cmdUpdate(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
-      if (requiresPullRequestAdded) {
-        info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+      if (prFlowMigrated) {
+        info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
@@ -264,8 +282,8 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && requiresPullRequestAdded) {
-      info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+    if (hasNewEntries && prFlowMigrated) {
+      info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
     fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "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/hooks/auto-resume.sh

@@ -0,0 +1,104 @@
+#!/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 the resume message with a deliberately timing-insensitive sequence:
+#   1. Escape leaves any non-input TUI state.
+#   2. A 1s settle covers every known TUI escape timeout (vim 1000ms,
+#      xterm/readline 50ms) so the next bytes are delivered as fresh input
+#      instead of being folded into the escape sequence (the dropped-`U` race).
+#   3. The text travels through a NAMED paste buffer pasted with bracketed
+#      paste (-p): the TUI ingests it as a single paste rather than per-character
+#      keypresses, so no leading char is eaten and the body is not read as a
+#      submit. The named buffer (-b) guarantees we paste exactly this text, and
+#      -d deletes it afterward so the user's anonymous paste stack is untouched.
+#   4. Enter is a separate send-keys after the paste, so the submit signal is
+#      never merged into the pasted content (the must-press-Enter race).
+# Every step stays non-blocking (2>/dev/null, exit 0 below) and logs a WARN on
+# failure so the log can localize which tmux step broke.
+log "tmux inject start (error=$error)"
+tmux send-keys -t "$TMUX_PANE" Escape 2>/dev/null || log "WARN: tmux Escape failed (error=$error)"
+sleep 1
+tmux set-buffer -b auto-resume -- "$RESUME_TEXT" 2>/dev/null || log "WARN: tmux set-buffer failed (error=$error)"
+tmux paste-buffer -t "$TMUX_PANE" -b auto-resume -p -d 2>/dev/null || log "WARN: tmux paste-buffer failed (error=$error)"
+tmux send-keys -t "$TMUX_PANE" Enter 2>/dev/null || log "WARN: tmux Enter failed (error=$error)"
+log "tmux inject 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,62 @@
+# Next-Step Output Rule
+
+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
+
+| 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`).
+
+## Agent output trailing line (Completed at)
+
+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
+```
+
+- 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,62 @@
+# 下一步输出规则
+
+本文件定义 skill「告知用户 / 下一步」输出的两类**相互独立**的规则；渲染最终输出前先读取本文件并同时落实两者：
+
+1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
+2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
+
+## 占位符语义
+
+| 占位符 | 含义 | 渲染形态 |
+|--------|------|----------|
+| `{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` 接受）。
+
+## Agent 输出收尾行（Completed at）
+
+本节是与「下一步输出结构」**并列的独立规则**，不隶属于「下一步」块。任何向用户渲染输出的 skill 都必须在面向用户输出的**绝对最后一行**追加完成时间收尾行——包括**声明「不渲染下一步命令」的 complete-task**，以及前置条件未满足而提前 return 的**错误 / 早退路径**。便于用户在 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。

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
+```