@fitlab-ai/agent-infra 0.7.0 → 0.7.2

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

@@ -0,0 +1,133 @@
+# Task short id
+
+Task short ids let mobile-style SKILL invocations replace the full 22-char
+`TASK-YYYYMMDD-HHMMSS` with bare numeric `N` (recommended) or `#NN` while a
+task is active.
+
+## Syntax
+
+- 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; bare numeric / `#NN` is an
+  alias, not the persisted task id.
+
+## Lifecycle
+
+| Action     | When                                                                 | Effect on registry                                            |
+|------------|-----------------------------------------------------------------------|---------------------------------------------------------------|
+| 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. |
+| 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
+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 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 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}` matches `^[#]?[0-9]+$` (bare numeric `N` or `#`-prefixed `#N`):
+
+```bash
+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}"
+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
+
+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-…" } }`
+- 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`; 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 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 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.
+- **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
+
+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.

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

@@ -0,0 +1,105 @@
+# 任务短号
+
+短号让所有 SKILL 在 active 任务生命周期内可以用 `#NN` 或裸数字 `N`（推荐）替代
+完整的 22 字符 `TASK-YYYYMMDD-HHMMSS`。
+
+## 语法
+
+- 字面接受两种等价形式：
+  - **裸数字 `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。
+
+## 生命周期
+
+| 动作      | 触发时机                                                                                     | 注册表效应                                                       |
+|-----------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------|
+| 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`          | 从注册表移除。                                                   |
+| re-alloc  | `restore-task`                                                                              | 重新分配（可能与历史不同），写入注册表。                         |
+
+短号仅在任务处于 `.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 exec <N \| '#N'>` / `ai sandbox create <N \| '#N'>`           | 解析为完整 task id 后查 task.md 取 `branch` | **严格报错** —— 不再回退到 ls 行号或字面分支名；提示用任务短号 / `TASK-id` / 分支名 |
+
+`list --verify` 严格只读：报告 active 目录 / 注册表 两者差异，但不修改任何状态。
+
+## SKILL 入参解析
+
+任意 SKILL（含 alloc / resolve / release / re-alloc 四类生命周期入口）在收到
+`{task-id}` 入参后，必须按以下契约处理：
+
+1. 如果 `{task-id}` 字面匹配 `^[#]?[0-9]+$`（裸数字 `N` 或 `#`-前缀 `#N`）：
+
+```bash
+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
+  task_id="{task-id}"
+fi
+```
+
+2. 后续所有命令把 `{task-id}` 视为 `$task_id`（已是完整 `TASK-YYYYMMDD-HHMMSS` 形式）
+3. 解析失败的退出码语义参见「错误场景」段；不要在 SKILL 中重写错误处理
+
+## 存储位置
+
+短号是纯本地状态，唯一持久化在注册表 `.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` 时按需自动创建；不存在时按空注册表处理
+- 短号只由显式 `alloc`（`create-task` / `import-*` / `restore-task`）分配；`resolve` / `list` / `release` 不分配，仅在执行时自动清理指向非 active 任务的 stale entry
+- 归档（complete-task / cancel-task / block-task / close-*）后注册表 entry 立即删除，短号可被新任务复用；归档后引用任务一律用完整 `TASK-…` id
+
+`resolve(<N|'#N'>)` 工作流：① 校验入参匹配 `^[#]?[0-9]+$` → ② 去前导零取
+数值 `n`，按 `n` 是否 `== 0`（保留）/ `> 10^shortIdLength - 1`（超容量）/
+正常 三类处理 → ③ 正常时以 `n.padStart(shortIdLength, '0')` 作为 key 查
+注册表 `ids` → ④ 命中返回完整 task id，未命中按 `list --verify` 给出修复指引退出 1。
+
+## 错误场景
+
+- **短号不存在**：注册表中无对应 key。可能是任务已归档（短号已释放）或输入错误。退出码 1。
+- **注册表损坏**（同一 taskId 出现多次或 JSON 无法解析）：退出码 2，需人工处理。
+- **保留键**：解析后 `n == 0`（输入如 `0`、`#0`、`#00`）。退出码 1。
+- **超容量**：解析后 `n > 10^shortIdLength - 1`（如 `shortIdLength=2` 下 `100` 或 `#100`）。退出码 1。
+- **参数格式错误**：入参既不是 `^[#]?[0-9]+$` 也不是 `TASK-id`（如 `#abc`、`#`、`5.5`）。退出码 1。
+
+## 跨 TUI 引号要求
+
+裸数字 `N` 在所有 shell 与 TUI 中都安全无需引号，推荐写法：
+`ai sandbox exec 11 'npm test'`、`/review-analysis 11`。
+
+`#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;
 }