@fitlab-ai/agent-infra 0.7.0 → 0.7.1

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.1",
   "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/rules/task-short-id.en.md

@@ -0,0 +1,141 @@
+# 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.
+
+## 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.
+- `#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.
+
+## Lifecycle
+
+| Action     | When                                                                 | Effect on registry & task.md                                  |
+|------------|-----------------------------------------------------------------------|---------------------------------------------------------------|
+| alloc      | `create-task`, `import-issue`, `import-codescan`, `import-dependabot` | Assigns lowest free `#NN`; writes `short_id` into task.md.    |
+| 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. |
+
+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
+freed and may be reused by a new task.
+
+## Configuration
+
+```jsonc
+// .agents/.airc.json
+{
+  "task": {
+    "shortIdLength": 2  // default; capacity = 99 (#01–#99). Set to 3 for #001–#999.
+  }
+}
+```
+
+When all slots for the configured width are in use, `alloc` fails with a clear
+error suggesting either archiving some tasks or raising `task.shortIdLength`.
+There is no silent extension or truncation. Changing `shortIdLength` requires
+archiving all active tasks first (the registry key width depends on it).
+
+## `#NN` resolution scope (split by entrypoint)
+
+| 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`)      |
+
+`list --verify` is strictly read-only: it reports discrepancies between active
+dir, registry, and `short_id` declared in each `task.md`, 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 `#`:
+
+```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.
+  task_id=$(node .agents/scripts/task-short-id.js resolve "{task-id}") || exit 1
+else
+  task_id="{task-id}"
+fi
+```
+
+2. Every downstream command treats `{task-id}` as `$task_id` (already the full
+   `TASK-YYYYMMDD-HHMMSS` form).
+3. Error-code semantics for resolve are documented under "Error scenarios"; do
+   not reimplement error handling inside each SKILL.
+
+## 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**:
+
+- Path: `<repo-root>/.agents/workspace/active/.short-ids.json`
+- Schema: `{ "version": 1, "ids": { "01": "TASK-20260609-192644", "02": "TASK-…" } }`
+- Keys are zero-padded decimal strings of `task.shortIdLength` digits; values are
+  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).
+- 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.
+
+## 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.
+- **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.
+
+## Cross-TUI quoting
+
+Bash treats `#` as a comment marker. Always single-quote: `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`).

package/templates/.agents/rules/task-short-id.zh-CN.md

@@ -0,0 +1,124 @@
+# 任务短号
+
+短号让所有 SKILL 在 active 任务生命周期内可以用 `#NN` 替代完整的 22 字符
+`TASK-YYYYMMDD-HHMMSS`。
+
+## 语法
+
+- 格式：`^#\d{shortIdLength}$`（**零填充到固定宽度**；默认 `shortIdLength=2` 时
+  形如 `#01`、`#07`、`#42`）。
+- **必须**零填充到 `shortIdLength` 位（默认 2 位：`#1` 视为格式错误，应输入
+  `#01`）。这是为了视觉对齐与盲打体验。
+- `#00`（或 `shortIdLength=1` 时 `#0`）保留、永不分配；纯数字、不引入字母。
+- 完整 `TASK-…` 入参在所有路径下行为与现状等价；`#NN` 只是别名，不是持久化任务 ID。
+
+## 生命周期
+
+| 动作      | 触发时机                                                                                     | 注册表 / task.md 效应                                            |
+|-----------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------|
+| alloc     | `create-task`、`import-issue`、`import-codescan`、`import-dependabot`                       | 分配最小可用 `#NN`，写入 task.md 的 `short_id` 字段。              |
+| resolve   | 生命周期 SKILL（`analyze-task` / `plan-task` / `code-task` / `review-*` / `commit` / …）    | `#NN` → 完整 task id 查询，不分配。                              |
+| release   | `complete-task`、`cancel-task`、`block-task`、`close-codescan`、`close-dependabot`          | 从注册表移除；task.md 的 `short_id` 字段保留作为历史值。          |
+| re-alloc  | `restore-task`                                                                              | 重新分配（可能与历史不同），写入注册表与 task.md。               |
+
+短号仅在任务处于 `.agents/workspace/active/` 期间有效；任务移动到
+`completed/` / `blocked/` / `archive/` 后短号立即释放，可被新任务复用。
+
+## 配置
+
+```jsonc
+// .agents/.airc.json
+{
+  "task": {
+    "shortIdLength": 2  // 默认；容量 = 99（#01–#99）。改为 3 时容量 = #001–#999。
+  }
+}
+```
+
+当前位宽容量耗尽时，`alloc` 给出明确错误并建议「归档若干任务」或「调高
+`task.shortIdLength`」两种修复路径；不静默扩位、不静默截断。
+切换 `shortIdLength` 配置需要先归档所有 active 任务（注册表 key 宽度依赖配置）。
+
+## `#NN` 解析作用域（按入口二分）
+
+| 入口                                                       | 注册表命中            | 注册表未命中                                            |
+|-----------------------------------------------------------|----------------------|--------------------------------------------------------|
+| SKILL 入参解析器（生命周期 SKILL）                          | 解析为完整 task id    | **严格报错** —— 短号不存在 / 格式错误                  |
+| `ai sandbox enter '#NN'` / `ai sandbox exec '#NN' …`      | 解析为完整 task id    | 回退到 running sandbox 的 ls 行号语义（保留 #414 行为）|
+
+`list --verify` 严格只读：报告 active 目录 / 注册表 / 各 task.md 的 `short_id`
+三者差异，但不修改任何状态。
+
+## SKILL 入参解析
+
+任意 SKILL（含 alloc / resolve / release / re-alloc 四类生命周期入口）在收到
+`{task-id}` 入参后，必须按以下契约处理：
+
+1. 如果 `{task-id}` 字面以 `#` 开头：
+
+```bash
+if [[ "{task-id}" == "#"* ]]; then
+  # 脚本本身已输出完整错误（含「expected #NN (N-digit zero-padded; e.g. '#01')」）；
+  # 调用方只需透传退出码
+  task_id=$(node .agents/scripts/task-short-id.js resolve "{task-id}") || exit 1
+else
+  task_id="{task-id}"
+fi
+```
+
+2. 后续所有命令把 `{task-id}` 视为 `$task_id`（已是完整 `TASK-YYYYMMDD-HHMMSS` 形式）
+3. 解析失败的退出码语义参见「错误场景」段；不要在 SKILL 中重写错误处理
+
+## 存储位置
+
+短号系统跨两处持久化状态，二者在稳态时一一对应：
+
+| 位置 | 写入时机 | 读取时机 | 删除时机 |
+|---|---|---|---|
+| `.agents/workspace/active/.short-ids.json`（注册表） | `alloc` / 冷启动迁移 | `resolve` 唯一权威源 / `list` / `list --verify` | `release` / 冷启动 stale 清理 |
+| 各 task.md frontmatter 的 `short_id` 字段 | `alloc` / 冷启动迁移 | `list --verify`（比对一致性） | **永不删除**（归档后保留为历史值） |
+
+**注册表**：
+
+- 路径：`<repo-root>/.agents/workspace/active/.short-ids.json`
+- Schema：`{ "version": 1, "ids": { "01": "TASK-20260609-192644", "02": "TASK-…" } }`
+- key 是零填充到 `task.shortIdLength` 位的字符串，value 是完整 `TASK-…` task id
+- 自动 git ignore（active 工作区整体 ignore；无需新增 ignore 条目）
+- 首次 `alloc` / `resolve` 时按需自动创建；不存在时按空注册表处理
+
+**task.md `short_id` 字段**：
+
+- 在 frontmatter 中、紧跟 `id` 字段之后；格式 `short_id: #01`
+- 与注册表 key 字面一致（含 `#` 前缀）
+- 归档（complete-task / cancel-task / block-task / close-*）后：注册表 entry 立即
+  删除（短号可被新任务复用），但 task.md `short_id` 字段保留作为历史值。解析器
+  只信任注册表
+- 冷启动迁移：升级 agent-infra 后首次 alloc / resolve 路径会扫描所有 active
+  目录并为缺字段的 task.md 补发短号；补发受字段保护约束（不刷新
+  `updated_at` / `agent_infra_version`、不追加 Activity Log）
+
+`resolve('#NN')` 工作流：① 校验入参严格匹配 `^#\d{shortIdLength}$` → ② 直接以
+`NN` 作为 key 查注册表 `ids` → ③ 命中返回完整 task id，未命中按 `list --verify`
+给出修复指引退出 1。
+
+## 错误场景
+
+- **短号不存在**：注册表中无 `#NN`。可能是任务已归档（短号已释放）或输入错误。
+- **注册表损坏**（同一 taskId 出现多次或 JSON 无法解析）：退出码 2，需人工处理。
+- **参数格式错误**（如 `#00`、`#abc`、`#`、`#1` 当 `shortIdLength=2` 时）：退出码 1。
+
+## 跨 TUI 引号要求
+
+bash 中 `#` 是注释起始符，必须单引号：`ai sandbox exec '#03' 'npm test'`。
+Claude Code / Codex / Gemini CLI / OpenCode 在加引号时都能把 `#NN` 字面传递到
+SKILL 的 `ARGUMENTS`。
+
+## 冷启动迁移
+
+升级 agent-infra 后，首次 `alloc` / `resolve` 调用会触发冷启动迁移：
+
+- 所有 active task.md 缺 `short_id` 字段时自动补发并回写（仅修改 `short_id`
+  一行，不刷新 `updated_at` / `agent_infra_version`，不追加 Activity Log）。
+- 若 active 任务总数超过 `shortIdLength` 容量，**在任何写入之前**报错退出 2。
+- 若 task.md 写入中途失败，`tx.commit()` 按缓存的原内容回滚所有已写文件（含
+  `mtime` / `atime` 恢复）。