@fitlab-ai/agent-infra 0.7.1 → 0.7.3

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

@@ -0,0 +1,62 @@
+# PR 检查平台命令（GitHub）
+
+在监控 PR 的 required checks、解析失败 run、拉取失败日志或读取当前分支 PR 前先读取本文件。`watch-pr` 技能的平台专属命令集中在此，技能正文与 `reference/` 保持平台无关。
+
+## 当前分支 PR / 仓库信息
+
+```bash
+gh pr view --json number -q .number          # 当前分支对应的 PR 号
+gh pr view {pr#} --json headRefOid -q .headRefOid   # PR head SHA
+gh repo view --json nameWithOwner -q .nameWithOwner # {owner}/{repo}
+```
+
+`gh` 未认证或命令失败时，按调用方技能的错误处理停止或降级。
+
+## 监控 required checks
+
+```bash
+gh pr checks {pr#} --required --watch --fail-fast -i 30 \
+  --json name,bucket,link,workflow
+```
+
+- `--required`：只纳入仓库分支保护标记为 required 的 checks。
+- `--watch`：阻塞直到这些 checks 全部跑完；`--fail-fast`：出现首个失败即退出 watch。
+- `-i 30`：轮询间隔 30 秒（退避）。**总时长上限默认 30 分钟（1800 秒）**：按执行环境选用对应的超时方式，超时即按「挂起」处理（退出码 8）。
+  - POSIX shell：`timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
+  - PowerShell（Windows）：用作业超时——
+    ```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; <按「挂起」处理> }
+    ```
+  - 平台中立回退（无外部超时工具时）：记录开始时间，循环执行**不带** `--watch` 的 `gh pr checks {pr#} --required --json name,bucket,link,workflow`，每轮 sleep `-i` 秒并检查 `bucket` 是否仍有 `pending`；累计时长 ≥ 1800 秒仍未结束 → 退出循环按「挂起」处理。
+- `--json` 的 `bucket` 字段把每个 check 归类为 `pass` / `fail` / `pending` / `skipping` / `cancel`。
+
+退出码语义：
+
+| 退出码 | 含义 | 结果分类 |
+|--------|------|----------|
+| 0 | 全部 required checks 通过 | 全绿 |
+| 1 | 至少一个失败 / 出错 | 失败 |
+| 8 | 仍有 pending（watch 超时或被 `timeout` 截断） | 挂起 |
+
+旧版 `gh`（< 2.93）若不支持 `--required`：回退为 `gh pr checks {pr#} --watch --fail-fast`（即「所有 check 必须 success」），并在求助/报告中注明该降级、建议升级 `gh`。
+
+## 解析失败 run id 并拉日志
+
+`gh pr checks --json` 不直接返回 run id，但返回失败 check 的 `link`（指向 run/job 的 URL）。按确定性顺序解析：
+
+1. 从失败 check 的 `link` 用正则提取：`https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → 第 1 组为 run id（可选第 2 组为 job id）。
+2. `link` 非 run URL 或无法解析时，用 head SHA 查 check-runs：
+   ```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'
+   ```
+   再从 `details_url` 同法提取 run id。
+3. 两路都拿不到 run id → 视为「不可定位」，按技能的求助出口处理，不盲目自愈。
+
+拿到 run id 后拉失败日志：
+
+```bash
+gh run view {run-id} --log-failed
+```

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# PR 检查平台命令
+
+当前代码平台未内置 Pull Request 检查命令支持。
+
+自定义平台会跳过平台专属的检查监控，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行 `watch-pr` 技能。

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

@@ -32,6 +32,7 @@ Aggregation rules:
 - 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
+- Manual verification section: extract items requiring human confirmation/fallback from the "Assumptions"/"Open Questions" of the latest `plan*` and the "Environment-Blocked Findings"/"Self-Doubt" sections (i.e. env-blocked items) of the latest `review-code*`; when there are none, write the explicit placeholder `- None — no items require manual verification`, never leave it empty
 
 ## Comment Body Template
 
@@ -46,6 +47,12 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
+### ⚠️ Manual Verification Required
+
+> Items in this change that need human confirmation/fallback; reviewers can reply under this comment once verified.
+
+- {manual-verify-item}
+
 ### Key Technical Decisions
 
 - {decision-1}

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

@@ -32,6 +32,7 @@
 - 用 `review-code*` 与 `code*` 构建审查历程表
 - 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
+- 需人工校验段落：从最新 `plan*` 的「假设」「未决问题」与最新 `review-code*` 的「环境性遗留」「自我质疑」提取需人工确认/兜底事项；无任何事项时写显式占位 `- 无需人工校验事项`，不得留空
 
 ## 评论体模板
 
@@ -46,6 +47,12 @@
 
 **更新时间**：{当前时间}
 
+### ⚠️ 需人工校验
+
+> 本次改动中需人工确认/兜底的事项；reviewer 校验后可在本评论下回复收尾。
+
+- {manual-verify-item}
+
 ### 关键技术决策
 
 - {decision-1}

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`).

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

@@ -1,25 +1,27 @@
 # 任务短号
 
-短号让所有 SKILL 在 active 任务生命周期内可以用 `#NN` 替代完整的 22 字符
-`TASK-YYYYMMDD-HHMMSS`。
+短号让所有 SKILL 在 active 任务生命周期内可以用 `#NN` 或裸数字 `N`（推荐）替代
+完整的 22 字符 `TASK-YYYYMMDD-HHMMSS`。
 
 ## 语法
 
-- 格式：`^#\d{shortIdLength}$`（**零填充到固定宽度**；默认 `shortIdLength=2` 时
-  形如 `#01`、`#07`、`#42`）。
-- **必须**零填充到 `shortIdLength` 位（默认 2 位：`#1` 视为格式错误，应输入
-  `#01`）。这是为了视觉对齐与盲打体验。
+- 字面接受两种等价形式：
+  - **裸数字 `N`**（推荐，无需 shell 引号）：如 `1`、`7`、`42`。
+  - **`#`-前缀 `#N` / `#NN`**（也接受；但 bash 需 `'...'` 引号）：如 `#1`、`#01`、`#42`。
+- 解析规则：去前导零后取数值 `n`，若 `n == 0` 报错（保留）；若 `n > 10^shortIdLength - 1`
+  报错（超容量）；否则归一化为 `#${n.padStart(shortIdLength, '0')}`，作为注册表 key。
+- 默认 `shortIdLength=2` 时容量 `n ∈ [1, 99]`，注册表 key 形如 `01`、`07`、`42`。
 - `#00`（或 `shortIdLength=1` 时 `#0`）保留、永不分配；纯数字、不引入字母。
-- 完整 `TASK-…` 入参在所有路径下行为与现状等价；`#NN` 只是别名，不是持久化任务 ID。
+- 完整 `TASK-…` 入参在所有路径下行为与现状等价；`#NN` / 裸数字只是别名，不是持久化任务 ID。
 
 ## 生命周期
 
-| 动作      | 触发时机                                                                                     | 注册表 / task.md 效应                                            |
+| 动作      | 触发时机                                                                                     | 注册表效应                                                       |
 |-----------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------|
-| alloc     | `create-task`、`import-issue`、`import-codescan`、`import-dependabot`                       | 分配最小可用 `#NN`，写入 task.md 的 `short_id` 字段。              |
+| alloc     | `create-task`、`import-issue`、`import-codescan`、`import-dependabot`                       | 分配最小可用 `#NN`，写入注册表。                                  |
 | 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。               |
+| release   | `complete-task`、`cancel-task`、`block-task`、`close-codescan`、`close-dependabot`          | 从注册表移除。                                                   |
+| re-alloc  | `restore-task`                                                                              | 重新分配（可能与历史不同），写入注册表。                         |
 
 短号仅在任务处于 `.agents/workspace/active/` 期间有效；任务移动到
 `completed/` / `blocked/` / `archive/` 后短号立即释放，可被新任务复用。
@@ -44,21 +46,20 @@
 | 入口                                                       | 注册表命中            | 注册表未命中                                            |
 |-----------------------------------------------------------|----------------------|--------------------------------------------------------|
 | SKILL 入参解析器（生命周期 SKILL）                          | 解析为完整 task id    | **严格报错** —— 短号不存在 / 格式错误                  |
-| `ai sandbox enter '#NN'` / `ai sandbox exec '#NN' …`      | 解析为完整 task id    | 回退到 running sandbox 的 ls 行号语义（保留 #414 行为）|
+| `ai sandbox exec <N \| '#N'>` / `ai sandbox create <N \| '#N'>`           | 解析为完整 task id 后查 task.md 取 `branch` | **严格报错** —— 不再回退到 ls 行号或字面分支名；提示用任务短号 / `TASK-id` / 分支名 |
 
-`list --verify` 严格只读：报告 active 目录 / 注册表 / 各 task.md 的 `short_id`
-三者差异，但不修改任何状态。
+`list --verify` 严格只读：报告 active 目录 / 注册表 两者差异，但不修改任何状态。
 
 ## SKILL 入参解析
 
 任意 SKILL（含 alloc / resolve / release / re-alloc 四类生命周期入口）在收到
 `{task-id}` 入参后，必须按以下契约处理：
 
-1. 如果 `{task-id}` 字面以 `#` 开头：
+1. 如果 `{task-id}` 字面匹配 `^[#]?[0-9]+$`（裸数字 `N` 或 `#`-前缀 `#N`）：
 
 ```bash
-if [[ "{task-id}" == "#"* ]]; then
-  # 脚本本身已输出完整错误（含「expected #NN (N-digit zero-padded; e.g. '#01')」）；
+if [[ "{task-id}" =~ ^[#]?[0-9]+$ ]]; then
+  # 脚本本身已输出完整错误（含 reserved / exceeds shortIdLength capacity 等场景）；
   # 调用方只需透传退出码
   task_id=$(node .agents/scripts/task-short-id.js resolve "{task-id}") || exit 1
 else
@@ -71,54 +72,34 @@ fi
 
 ## 存储位置
 
-短号系统跨两处持久化状态，二者在稳态时一一对应：
-
-| 位置 | 写入时机 | 读取时机 | 删除时机 |
-|---|---|---|---|
-| `.agents/workspace/active/.short-ids.json`（注册表） | `alloc` / 冷启动迁移 | `resolve` 唯一权威源 / `list` / `list --verify` | `release` / 冷启动 stale 清理 |
-| 各 task.md frontmatter 的 `short_id` 字段 | `alloc` / 冷启动迁移 | `list --verify`（比对一致性） | **永不删除**（归档后保留为历史值） |
-
-**注册表**：
+短号是纯本地状态，唯一持久化在注册表 `.agents/workspace/active/.short-ids.json`，task.md 不持有短号：
 
 - 路径：`<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` 字段**：
+- 首次 `alloc` 时按需自动创建；不存在时按空注册表处理
+- 短号只由显式 `alloc`（`create-task` / `import-*` / `restore-task`）分配；`resolve` / `list` / `release` 不分配，仅在执行时自动清理指向非 active 任务的 stale entry
+- 归档（complete-task / cancel-task / block-task / close-*）后注册表 entry 立即删除，短号可被新任务复用；归档后引用任务一律用完整 `TASK-…` 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。
+`resolve(<N|'#N'>)` 工作流：① 校验入参匹配 `^[#]?[0-9]+$` → ② 去前导零取
+数值 `n`，按 `n` 是否 `== 0`（保留）/ `> 10^shortIdLength - 1`（超容量）/
+正常 三类处理 → ③ 正常时以 `n.padStart(shortIdLength, '0')` 作为 key 查
+注册表 `ids` → ④ 命中返回完整 task id，未命中按 `list --verify` 给出修复指引退出 1。
 
 ## 错误场景
 
-- **短号不存在**：注册表中无 `#NN`。可能是任务已归档（短号已释放）或输入错误。
+- **短号不存在**：注册表中无对应 key。可能是任务已归档（短号已释放）或输入错误。退出码 1。
 - **注册表损坏**（同一 taskId 出现多次或 JSON 无法解析）：退出码 2，需人工处理。
-- **参数格式错误**（如 `#00`、`#abc`、`#`、`#1` 当 `shortIdLength=2` 时）：退出码 1。
+- **保留键**：解析后 `n == 0`（输入如 `0`、`#0`、`#00`）。退出码 1。
+- **超容量**：解析后 `n > 10^shortIdLength - 1`（如 `shortIdLength=2` 下 `100` 或 `#100`）。退出码 1。
+- **参数格式错误**：入参既不是 `^[#]?[0-9]+$` 也不是 `TASK-id`（如 `#abc`、`#`、`5.5`）。退出码 1。
 
 ## 跨 TUI 引号要求
 
-bash 中 `#` 是注释起始符，必须单引号：`ai sandbox exec '#03' 'npm test'`。
-Claude Code / Codex / Gemini CLI / OpenCode 在加引号时都能把 `#NN` 字面传递到
-SKILL 的 `ARGUMENTS`。
-
-## 冷启动迁移
-
-升级 agent-infra 后，首次 `alloc` / `resolve` 调用会触发冷启动迁移：
+裸数字 `N` 在所有 shell 与 TUI 中都安全无需引号，推荐写法：
+`ai sandbox exec 11 'npm test'`、`/review-analysis 11`。
 
-- 所有 active task.md 缺 `short_id` 字段时自动补发并回写（仅修改 `short_id`
-  一行，不刷新 `updated_at` / `agent_infra_version`，不追加 Activity Log）。
-- 若 active 任务总数超过 `shortIdLength` 容量，**在任何写入之前**报错退出 2。
-- 若 task.md 写入中途失败，`tx.commit()` 按缓存的原内容回滚所有已写文件（含
-  `mtime` / `atime` 恢复）。
+`#N` / `#NN` 写法也接受；但 bash 中 `#` 是注释起始符，必须单引号：
+`ai sandbox exec '#03' 'npm test'`。Claude Code / Codex / Gemini CLI / OpenCode
+在加引号时都能把 `#NN` 字面传递到 SKILL 的 `ARGUMENTS`。

package/templates/.agents/scripts/platform-adapters/platform-sync.github.js

@@ -5,6 +5,7 @@ import spawn from "cross-spawn";
 
 const CHECK_TYPE = "platform-sync";
 const DEFAULT_RETRY_DELAYS_MS = [3000, 10000];
+const VERSION_LINE_REGEX = /^[0-9]+\.[0-9]+\.x$/;
 const FRONTMATTER_FIELD_MAP = {
   priority: "Priority",
   effort: "Effort",
@@ -811,6 +812,22 @@ function checkMilestone(context, remoteData) {
     );
   }
 
+  if (context.config.verify_milestone_specific) {
+    const issueTitle = remoteData.issue.milestone.title;
+    if (VERSION_LINE_REGEX.test(issueTitle)) {
+      return failResult(CHECK_TYPE,
+        `Issue #${context.issueNumber} milestone '${issueTitle}' is a release line; narrow to a specific version (e.g. ${issueTitle.replace(/\.x$/, ".N")}) before continuing`,
+        "check_failed"
+      );
+    }
+    if (context.prNumber && remoteData.prMilestone?.title && VERSION_LINE_REGEX.test(remoteData.prMilestone.title)) {
+      return failResult(CHECK_TYPE,
+        `PR #${context.prNumber} milestone '${remoteData.prMilestone.title}' is a release line; narrow to a specific version before continuing`,
+        "check_failed"
+      );
+    }
+  }
+
   return null;
 }