@fitlab-ai/agent-infra 0.7.1 → 0.7.2

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,97 @@
+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;
+}
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.1",
+  "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/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。

package/templates/.agents/rules/task-short-id.en.md

@@ -1,27 +1,33 @@
 # Task short id
 
 Task short ids let mobile-style SKILL invocations replace the full 22-char
-`TASK-YYYYMMDD-HHMMSS` with `#NN` while a task is active.
+`TASK-YYYYMMDD-HHMMSS` with bare numeric `N` (recommended) or `#NN` while a
+task is active.
 
 ## Syntax
 
-- Format: `^#\d{shortIdLength}$` (**zero-padded to a fixed width**; with the
-  default `shortIdLength=2`, e.g. `#01`, `#07`, `#42`).
-- **Must** be zero-padded to `shortIdLength` digits (default 2: `#1` is a format
-  error, use `#01`). This keeps things aligned and touch-typeable.
+- Two equivalent literal forms are accepted:
+  - **Bare numeric `N`** (recommended; no shell quoting needed): e.g. `1`, `7`, `42`.
+  - **`#`-prefixed `#N` / `#NN`** (also accepted; bash needs `'...'` quoting): e.g. `#1`, `#01`, `#42`.
+- Resolution: drop leading zeros and take the numeric value `n`; if `n == 0`,
+  reject (reserved); if `n > 10^shortIdLength - 1`, reject (over capacity);
+  otherwise canonicalize to `#${n.padStart(shortIdLength, '0')}` as the
+  registry key.
+- With the default `shortIdLength=2`, capacity is `n ∈ [1, 99]`; registry keys
+  look like `01`, `07`, `42`.
 - `#00` (or `#0` when `shortIdLength=1`) is reserved and never allocated; digits
   only, no letters.
-- The plain `TASK-…` form keeps working everywhere; `#NN` is an alias, not the
-  persisted task id.
+- The plain `TASK-…` form keeps working everywhere; bare numeric / `#NN` is an
+  alias, not the persisted task id.
 
 ## Lifecycle
 
-| Action     | When                                                                 | Effect on registry & task.md                                  |
+| Action     | When                                                                 | Effect on registry                                            |
 |------------|-----------------------------------------------------------------------|---------------------------------------------------------------|
-| alloc      | `create-task`, `import-issue`, `import-codescan`, `import-dependabot` | Assigns lowest free `#NN`; writes `short_id` into task.md.    |
+| alloc      | `create-task`, `import-issue`, `import-codescan`, `import-dependabot` | Assigns lowest free `#NN` in the registry.                    |
 | resolve    | Lifecycle SKILLs (`analyze-task`, `plan-task`, `code-task`, …)        | Looks up `#NN` → full task id. Does not allocate.             |
-| release    | `complete-task`, `cancel-task`, `block-task`, `close-codescan`, `close-dependabot` | Removes the registry entry; leaves task.md `short_id` as a historical value. |
-| re-alloc   | `restore-task`                                                        | Re-allocates a (possibly new) `#NN` and writes it to task.md. |
+| release    | `complete-task`, `cancel-task`, `block-task`, `close-codescan`, `close-dependabot` | Removes the registry entry. |
+| re-alloc   | `restore-task`                                                        | Re-allocates a (possibly new) `#NN` in the registry. |
 
 Short ids are valid only while a task lives in `.agents/workspace/active/`.
 Once it is moved to `completed/`, `blocked/`, or `archive/`, the `#NN` slot is
@@ -48,22 +54,23 @@ archiving all active tasks first (the registry key width depends on it).
 | Entrypoint                                                  | Hit                  | Miss                                                 |
 |-------------------------------------------------------------|----------------------|------------------------------------------------------|
 | SKILL parameter resolver (lifecycle SKILLs)                  | resolve to full id   | **strict error** — short id not found / invalid     |
-| `ai sandbox enter '#NN'` / `ai sandbox exec '#NN' …`        | resolve to full id   | fall back to running-sandbox ls index (`#414`)      |
+| `ai sandbox exec <N \| '#N'>` / `ai sandbox create <N \| '#N'>`           | resolve to full id, then read `branch` from task.md | **strict error** — no ls-index fallback, no literal-branch fallback; hint the user to pass a short id / `TASK-id` / branch name |
 
-`list --verify` is strictly read-only: it reports discrepancies between active
-dir, registry, and `short_id` declared in each `task.md`, but never writes.
+`list --verify` is strictly read-only: it reports discrepancies between the
+active dir and the registry, but never writes.
 
 ## SKILL parameter resolver
 
 Any SKILL (alloc / resolve / release / re-alloc lifecycle entry-points) that
 receives a `{task-id}` argument must follow this contract:
 
-1. If `{task-id}` starts with `#`:
+1. If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric `N` or `#`-prefixed `#N`):
 
 ```bash
-if [[ "{task-id}" == "#"* ]]; then
-  # The script writes the full error message (including "expected #NN
-  # (N-digit zero-padded; e.g. '#01')") to stderr; callers only forward the exit.
+if [[ "{task-id}" =~ ^[#]?[0-9]+$ ]]; then
+  # The script writes the full error message (covering reserved / exceeds
+  # shortIdLength capacity / malformed input) to stderr; callers only forward
+  # the exit.
   task_id=$(node .agents/scripts/task-short-id.js resolve "{task-id}") || exit 1
 else
   task_id="{task-id}"
@@ -77,14 +84,8 @@ fi
 
 ## Storage
 
-The short id system persists state in two places that stay in sync at rest:
-
-| Location | Written by | Read by | Removed by |
-|---|---|---|---|
-| `.agents/workspace/active/.short-ids.json` (registry) | `alloc` / cold-start migration | `resolve` (authoritative) / `list` / `list --verify` | `release` / cold-start stale cleanup |
-| `short_id` frontmatter field in each task.md | `alloc` / cold-start migration | `list --verify` (consistency check) | **never** (kept as historical value after archive) |
-
-**Registry**:
+Short ids are pure local state, persisted only in the registry
+`.agents/workspace/active/.short-ids.json`; task.md does not hold the short id:
 
 - Path: `<repo-root>/.agents/workspace/active/.short-ids.json`
 - Schema: `{ "version": 1, "ids": { "01": "TASK-20260609-192644", "02": "TASK-…" } }`
@@ -92,50 +93,41 @@ The short id system persists state in two places that stay in sync at rest:
   full `TASK-…` task ids.
 - Automatically git-ignored (the whole active workspace is ignored; no new
   ignore entry needed).
-- Created on demand by the first `alloc` / `resolve`; an absent file is treated
-  as an empty registry.
-
-**`short_id` field in task.md**:
-
-- Lives in frontmatter, immediately after `id`; formatted `short_id: #01`.
-- Matches the registry key byte-for-byte (including the `#` prefix).
+- Created on demand by the first `alloc`; an absent file is treated as an empty
+  registry.
+- Short ids are assigned only by an explicit `alloc` (`create-task` /
+  `import-*` / `restore-task`); `resolve` / `list` / `release` never allocate —
+  they only clean up stale entries pointing at non-active tasks.
 - After archive (complete-task / cancel-task / block-task / close-*) the
-  registry entry is deleted immediately (the short id can be reused), but the
-  `short_id` field in task.md is kept as a historical value. The resolver
-  trusts the registry only.
-- Cold-start migration: the first `alloc` / `resolve` after an upgrade scans
-  the active directory and fills in the missing field for legacy tasks; the
-  field write is constrained (does NOT refresh `updated_at` /
-  `agent_infra_version` and does NOT append Activity Log).
-
-`resolve('#NN')` workflow: ① validate arg matches `^#\d{shortIdLength}$` →
-② look up `NN` directly as the registry `ids` key → ③ return full task id on
-hit; on miss, exit 1 with the `list --verify` repair hint.
+  registry entry is deleted immediately and the short id may be reused; archived
+  tasks are referenced by their full `TASK-…` id.
+
+`resolve(<N|'#N'>)` workflow: ① validate arg matches `^[#]?[0-9]+$` →
+② strip leading zeros and take the numeric value `n`; classify as reserved
+(`n == 0`) / over capacity (`n > 10^shortIdLength - 1`) / normal → ③ on
+normal, use `n.padStart(shortIdLength, '0')` as the registry `ids` key
+→ ④ return full task id on hit; on miss, exit 1 with the `list --verify`
+repair hint.
 
 ## Error scenarios
 
-- **Short id not found**: the registry has no entry for `#NN`. Either the task
-  was archived (release freed the slot) or the input is wrong.
+- **Short id not found**: the registry has no entry for the resolved key.
+  Either the task was archived (release freed the slot) or the input is
+  wrong. Exit code 1.
 - **Registry corruption** (duplicate registry entries for the same task id, or
   the JSON is unparsable): exit code 2; manual cleanup required.
-- **Parameter format error** (e.g. `#00`, `#abc`, `#`, or `#1` when
-  `shortIdLength=2`): exit code 1.
+- **Reserved key**: the resolved `n == 0` (inputs like `0`, `#0`, `#00`). Exit code 1.
+- **Over capacity**: the resolved `n > 10^shortIdLength - 1` (e.g. `100` or
+  `#100` when `shortIdLength=2`). Exit code 1.
+- **Parameter format error**: input matches neither `^[#]?[0-9]+$` nor a
+  `TASK-id` (e.g. `#abc`, `#`, `5.5`). Exit code 1.
 
 ## Cross-TUI quoting
 
-Bash treats `#` as a comment marker. Always single-quote: `ai sandbox exec '#03' 'npm test'`.
+Bare numeric `N` is safe in every shell and TUI without quoting (recommended):
+`ai sandbox exec 11 'npm test'`, `/review-analysis 11`.
+
+The `#N` / `#NN` form is also accepted; but bash treats `#` as a comment
+marker, so it must be single-quoted: `ai sandbox exec '#03' 'npm test'`.
 Claude Code / Codex / Gemini CLI / OpenCode all forward `#NN` to SKILL
 `ARGUMENTS` literally when quoted.
-
-## Cold-start migration
-
-When a project upgrades to a version with this feature, the first call to
-`alloc` / `resolve` runs the cold-start path:
-
-- Active tasks whose `task.md` lacks `short_id` get one allocated and written
-  back (the only frontmatter mutation; `updated_at` / `agent_infra_version`
-  are **not** refreshed and Activity Log is **not** appended).
-- If active task count exceeds `shortIdLength` capacity, the migration aborts
-  **before any write** with a capacity error.
-- If a partial write fails midway, `tx.commit()` rolls all task.md files back to
-  their original content (including `mtime` / `atime`).