@fitlab-ai/agent-infra 0.6.5 → 0.7.1

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

@@ -1,6 +1,6 @@
 # Milestone 推断规则
 
-在 `create-task` 的平台规则、`implement-task` 或 `create-pr` 处理 milestone 之前先读取本文件。
+在 `create-task` 的平台规则、`code-task` 或 `create-pr` 处理 milestone 之前先读取本文件。
 
 ## 通用原则
 
@@ -56,7 +56,7 @@ fi
 
 如果 `has_triage=false`、推断结果为空、或 `gh issue edit` 失败，跳过并继续，不阻断 `import-issue` 工作流。
 
-## 阶段 2：`implement-task`
+## 阶段 2：`code-task`
 
 目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -0,0 +1,57 @@
+# General Rule - No Mid-Flow Questions During SKILL Execution
+
+> **Scope**: this rule applies to **all SKILL** executions.
+> Only the two exemption categories below may ask the user; any other mid-flow question is a violation.
+
+## Exemption Categories
+
+### Exemption 1: Literal clarification of entry-point natural-language input
+
+Allowed only when the SKILL's core responsibility is to process **natural-language input the user provided in this invocation**, and that input is unparseable or self-contradictory. The clarification must be about the **literal input itself**; it must not be used to solicit implementation preferences.
+
+SKILLs currently covered by this exemption:
+
+- `create-task`: may clarify the task description itself when the user-provided description is unclear
+- `refine-title`: requires the user's final confirmation (y/n) for a generated title
+
+### Exemption 2: Short confirmation before truly irreversible destructive operations
+
+Any SKILL may pause briefly before the following irreversible operations; routine design choices do not qualify:
+
+- `git push --force`, `rm -rf` against the user's worktree, etc.
+- Deleting or overwriting shared remote resources (e.g., shared GitHub labels)
+- Overwriting uncommitted local changes
+
+SKILLs currently covered by this exemption:
+
+- `init-labels`: may confirm before deleting legacy labels not in the final mapping
+- `commit`: may stop and confirm when its plan conflicts with the user's uncommitted changes
+
+## No-Mid-Flow-Questions Clause (default behavior)
+
+For every SKILL execution context not covered by the two exemptions above, the default behavior is:
+
+1. Do not call any user-question tool, including but not limited to `AskUserQuestion` and equivalent mechanisms that ask the user to choose.
+2. When uncertain, proceed with the most robust option without interrupting the flow. Use this priority order:
+   1. Prefer the option consistent with existing code, documentation, and rules
+   2. Prefer the more reversible option
+   3. Prefer the option with the smaller impact area
+3. If assumptions or open questions exist, write them into fixed artifact sections instead of leaving them suspended in the conversation:
+   - English artifacts use `## Assumptions` / `## Open Questions`; Chinese artifacts use `## 假设` / `## 未决问题`
+   - Meaning: the assumptions section records assumptions used for this run that may be revisited later; the open questions section records unresolved questions for human review
+   - If the artifact template does not reserve these sections, append them as needed. If there are no assumptions or open questions, do not force empty sections.
+
+## Human Review Checkpoint Semantics
+
+A mandatory human review checkpoint means:
+
+- Stop after producing the artifact: once the skill finishes an artifact such as `plan.md`, end the current invocation and wait for the user to explicitly trigger the next skill command
+- Do not pause mid-process to ask for input: do not insert interruptions such as "Do you prefer option A or B?" between execution steps
+
+If a key decision needs human judgment during execution, follow the assumptions and open questions rule above: record it in the artifact's "Open Questions" / `未决问题` section for the user to address at the review checkpoint.
+
+## Anchor Location
+
+This rule's sole global anchor lives in the project-level AGENTS.md "AI Behavior Principles" preamble, which every AI tool loads. Individual SKILL.md files no longer reference this rule, so no per-skill duplicate bullet needs to be maintained.
+
+When executing any SKILL, if AGENTS.md's preamble notes "follow this rule first," the LLM should **proactively Read** this file to load the complete exemption list and concrete constraints.

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -0,0 +1,57 @@
+# 通用规则 - SKILL 执行禁言
+
+> **适用范围**：本规则适用于**所有 SKILL** 的执行过程。
+> 仅以下两类例外可向用户提问；不属于这两类的发问一律按违规处理。
+
+## 例外类型
+
+### 例外 1：入口式自然语言入参的字面澄清
+
+仅当 SKILL 的本职职责就是处理**用户当次提供的自然语言入参**时，如果该入参无法解析或自相矛盾，可直接就**该入参字面**向用户澄清。不允许借此征求实现方案的偏好。
+
+当前归入本例外的 SKILL：
+
+- `create-task`：用户提供的任务描述不清晰时可澄清描述本身
+- `refine-title`：生成的新标题需要用户最终确认（y/n）
+
+### 例外 2：不可逆破坏性操作前的短暂确认
+
+任何 SKILL 在以下不可逆操作前可短暂确认；常规方案选择不属于此类：
+
+- `git push --force`、`rm -rf` 用户工作树等
+- 删除/覆盖远端共享资源（如 GitHub 共享 label）
+- 覆盖用户未提交的本机改动
+
+当前归入本例外的 SKILL：
+
+- `init-labels`：删除不在最终映射中的旧 label 前可确认
+- `commit`：检测到与用户未提交改动冲突时可停下确认
+
+## 禁言条款（默认行为）
+
+不属于上述两类例外的所有 SKILL 执行场景，遵循以下默认行为：
+
+1. **禁止调用**任何向用户发问的工具（包括但不限于 `AskUserQuestion` 及等价的「征求用户选择」机制）。
+2. **不确定时**，按「最稳健方案」自主推进，不中断对话。最稳健方案的判定优先级：
+   1. 与现有代码 / 文档 / 规则一致的方案优先
+   2. 可逆性更高的方案优先
+   3. 影响面更小的方案优先
+3. **如存在假设或未决问题**，写入产物中的固定段落，不在对话中悬置：
+   - 中文产物用 `## 假设` / `## 未决问题`；英文产物用 `## Assumptions` / `## Open Questions`
+   - 含义：`假设` 段记录本次按某假设推进、未来若假设不成立可推翻；`未决问题` 段记录本次未决、需要人工审查时裁定的问题
+   - 产物模板未预留这两段时，按需追加；没有假设或未决问题时不必强行写空段。
+
+## 人工审查检查点语义
+
+「强制性人工审查检查点」（mandatory human review checkpoint）的语义是：
+
+- **产出后停止**：技能完成产物（如 `plan.md`）后立即结束本轮调用，等待用户主动触发下一个技能命令
+- **不是过程中暂停征求意见**：不允许在执行步骤之间插入「请问您倾向 A 还是 B？」之类的中断
+
+如果在执行过程中发现需要用户裁定的关键决策，按上文「假设与未决问题」处理，记录到产物的「未决问题」/`Open Questions` 段落，由用户在审查检查点统一回应。
+
+## 锚点位置
+
+本规则的唯一全局锚点在项目级 AGENTS.md 的「AI 行为准则」preamble，所有 AI 工具加载 AGENTS.md 时即可见。各 SKILL.md 不再单独引用本规则，避免在每个 SKILL 顶部维护重复 bullet。
+
+LLM 在执行任一 SKILL 时，若 AGENTS.md 的 preamble 已说明「优先遵循本规则」，应**主动 Read** 本文件以获取完整的例外列表与具体约束。

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

@@ -24,14 +24,13 @@ Within one PR, a given `{task-id}` must have only one summary comment with this
 
 Aggregate the latest artifacts in the task directory:
 - `plan.md` or the latest `plan-r{N}.md`
-- `implementation.md` or the latest `implementation-r{N}.md`
-- `review.md` or the latest `review-r{N}.md`
-- `refinement.md` or the latest `refinement-r{N}.md`
+- `code.md` or the latest `code-r{N}.md`
+- `review-code.md` or the latest `review-code-r{N}.md`
 
 Aggregation rules:
 - extract 2-4 self-contained technical decisions from `plan*`
-- build the review-history table from `review*` and `refinement*`
-- extract the test summary from `implementation*` or `refinement*`
+- build the review-history table from `review-code*` and `code*`
+- extract the test summary from `code*`
 - if one artifact class is missing, treat it as "no data for this stage" and continue
 
 ## Comment Body Template

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

@@ -24,14 +24,13 @@
 
 聚合当前任务目录中的最新产物：
 - `plan.md` 或最新 `plan-r{N}.md`
-- `implementation.md` 或最新 `implementation-r{N}.md`
-- `review.md` 或最新 `review-r{N}.md`
-- `refinement.md` 或最新 `refinement-r{N}.md`
+- `code.md` 或最新 `code-r{N}.md`
+- `review-code.md` 或最新 `review-code-r{N}.md`
 
 聚合规则：
 - 从 `plan*` 提取 2-4 条自包含的关键技术决策
-- 用 `review*` 与 `refinement*` 构建审查历程表
-- 从 `implementation*` 或 `refinement*` 提取测试结果摘要
+- 用 `review-code*` 与 `code*` 构建审查历程表
+- 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
 
 ## 评论体模板

package/templates/.agents/rules/task-management.en.md

@@ -5,10 +5,12 @@
 Map user intent to the corresponding workflow command:
 - "analyze issue #123" -> `import-issue`
 - "analyze task TASK-20260306-143022" -> `analyze-task`
+- "review requirement analysis" -> `review-analysis`
 - "design a plan" -> `plan-task`
-- "implement" or "build" -> `implement-task`
-- "review" -> `review-task`
-- "fix review feedback" -> `refine-task`
+- "review a plan" or "review technical design" -> `review-plan`
+- "implement" or "build" -> `code-task`
+- "code review" or "review code" -> `review-code`
+- "fix review feedback" -> `code-task`
 
 ## Task State Management
 
@@ -25,10 +27,11 @@ Map user intent to the corresponding workflow command:
 - `import-dependabot`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
 - `restore-task`: update `status`, `updated_at`, `assigned_to`, `agent_infra_version`
 - `analyze-task`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `review-analysis`: update `current_step`, `updated_at`, `agent_infra_version`
 - `plan-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `implement-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `review-task`: update `current_step`, `updated_at`, `agent_infra_version`
-- `refine-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `review-plan`: update `current_step`, `updated_at`, `agent_infra_version`
+- `code-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `review-code`: update `current_step`, `updated_at`, `agent_infra_version`
 - `create-pr`: update `pr_number`, `updated_at`, `agent_infra_version`
 - `commit`: update `updated_at`, `agent_infra_version`; update `current_step` when needed (see `commit/reference/task-status-update.md`)
 - `complete-task`: update `status`, `current_step`, `completed_at`, `updated_at`, `agent_infra_version`

package/templates/.agents/rules/task-management.zh-CN.md

@@ -5,10 +5,12 @@
 根据用户意图自动映射到对应工作流命令：
 - “分析 issue #123” -> `import-issue`
 - “分析任务 TASK-20260306-143022” -> `analyze-task`
+- “审查需求分析” -> `review-analysis`
 - “设计方案” -> `plan-task`
-- “实施/实现” -> `implement-task`
-- “审查” -> `review-task`
-- “修复审查问题” -> `refine-task`
+- “审查方案/审查技术方案” -> `review-plan`
+- “实施/实现” -> `code-task`
+- “审查代码/代码审查” -> `review-code`
+- “修复审查问题” -> `code-task`
 
 ## 任务状态管理
 
@@ -25,10 +27,11 @@
 - `import-dependabot`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
 - `restore-task`：更新 `status`、`updated_at`、`assigned_to`、`agent_infra_version`
 - `analyze-task`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `review-analysis`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `plan-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `implement-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `review-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `refine-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `review-plan`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `code-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `review-code`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
 - `commit`：更新 `updated_at`、`agent_infra_version`；必要时更新 `current_step`（详见 `commit/reference/task-status-update.md`）
 - `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`

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` 恢复）。

package/templates/.agents/rules/testing-discipline.en.md

@@ -12,13 +12,13 @@ When a positive assertion already covers the expected behavior, do not add anoth
 
 Bad:
 ```ts
-assert.match(content, /^name: implement-task$/m);    // The positive assertion already covers the expected value.
+assert.match(content, /^name: code-task$/m);         // The positive assertion already covers the expected value.
 assert.doesNotMatch(content, /^name: wrong-name$/m); // Redundant: permanently remembers a value that should not appear.
 ```
 
 Good:
 ```ts
-assert.match(content, /^name: implement-task$/m);    // The positive assertion is enough.
+assert.match(content, /^name: code-task$/m);         // The positive assertion is enough.
 ```
 
 If the positive assertion passes, the value is correct. The extra negative assertion adds no protection, only maintenance cost, and can become a test that permanently remembers a concept after the feature is gone.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -12,13 +12,13 @@
 
 ❌ 反例：
 ```ts
-assert.match(content, /^name: implement-task$/m);    // 正向已覆盖期望值
+assert.match(content, /^name: code-task$/m);         // 正向已覆盖期望值
 assert.doesNotMatch(content, /^name: wrong-name$/m); // 多余：永久记住一个不该出现的值
 ```
 
 ✅ 正例：
 ```ts
-assert.match(content, /^name: implement-task$/m);    // 正向断言已足够
+assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 ```
 
 正向断言通过即证明值正确；额外的反向断言不增加保护，只增加维护成本，并会在功能删除后退化为"测试永久记住一个不再存在的概念"。