@fitlab-ai/agent-infra 0.7.1 → 0.7.3

package/templates/.agents/scripts/task-short-id.js

@@ -32,11 +32,11 @@ function usage() {
     "Usage: task-short-id.js <subcommand> [args]",
     "",
     "Subcommands:",
-    "  alloc <task-id>      Allocate short id for a task; writes registry + short_id to task.md",
+    "  alloc <task-id>      Allocate short id for a task in the registry",
     "  release <task-id>    Release short id (idempotent; exit 0 if not present)",
     "  resolve <#N>         Resolve short id to full task id",
     "  list                 Print registry JSON",
-    "  list --verify        Read-only check; exit 1 if active dir / registry / task.md disagree",
+    "  list --verify        Read-only check; exit 1 if active dir / registry disagree",
     "",
     "Options:",
     "  --active-dir <path>  Override active dir (default: <repo>/.agents/workspace/active)",
@@ -161,17 +161,6 @@ function withRegistryLock(activeDir, fn, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
   }
 }
 
-function writeTaskMdShortId(taskMdPath, shortId) {
-  const content = fs.readFileSync(taskMdPath, "utf8");
-  let updated;
-  if (/^short_id:.*$/m.test(content)) {
-    updated = content.replace(/^short_id:.*$/m, `short_id: ${shortId}`);
-  } else {
-    updated = content.replace(/^(id:.*)$/m, `$1\nshort_id: ${shortId}`);
-  }
-  fs.writeFileSync(taskMdPath, updated);
-}
-
 function padShortId(n, shortIdLength) {
   return String(n).padStart(shortIdLength, "0");
 }
@@ -185,24 +174,34 @@ function allocateMinFreeInt(registry, shortIdLength) {
 }
 
 function parseShortIdArg(arg, shortIdLength) {
-  const re = new RegExp(`^#\\d{${shortIdLength}}$`);
-  if (!re.test(arg)) {
-    const example =
-      shortIdLength === 1 ? "'#1'" : shortIdLength === 2 ? "'#01'" : `'#${"0".repeat(shortIdLength - 1)}1'`;
+  const L = shortIdLength;
+  const max = Math.pow(10, L) - 1;
+  // Accept bare numeric or '#'-prefixed; canonicalize to zero-padded key.
+  // Bare numeric is the recommended form (no shell quoting needed).
+  const m = /^#?(\d+)$/.exec(arg);
+  if (!m) {
     writeStderr(
       `Error: invalid short id format '${arg}', ` +
-        `expected #${"N".repeat(shortIdLength)} (${shortIdLength}-digit zero-padded; e.g. ${example})\n`
+        `expected bare digits (recommended) or '#'-prefixed digits; ` +
+        `e.g. '11' or '#11' (shortIdLength=${L}, max=${max})\n`
+    );
+    process.exit(1);
+  }
+  const n = Number(m[1]);
+  if (n === 0) {
+    writeStderr(
+      `Error: short id '${arg}' is invalid (#${"0".repeat(L)} is reserved)\n`
     );
     process.exit(1);
   }
-  const key = arg.slice(1);
-  if (Number(key) === 0) {
+  if (n > max) {
     writeStderr(
-      `Error: short id '${arg}' is invalid (#${"0".repeat(shortIdLength)} is reserved)\n`
+      `Error: short id ${n} exceeds shortIdLength=${L} capacity (max=${max}); ` +
+        `archive tasks or raise task.shortIdLength in .agents/.airc.json\n`
     );
     process.exit(1);
   }
-  return key;
+  return String(n).padStart(L, "0");
 }
 
 function planTransaction(registry, activeDir, shortIdLength) {
@@ -216,7 +215,7 @@ function planTransaction(registry, activeDir, shortIdLength) {
       .filter((d) => fs.existsSync(path.join(activeDir, d, "task.md")))
   );
 
-  // A2: stale entries
+  // A2: stale entries (registry points at a task no longer active)
   const pendingRegistryDeletes = [];
   for (const [key, taskId] of Object.entries(registry.ids)) {
     if (!activeTaskIds.has(taskId)) pendingRegistryDeletes.push(key);
@@ -238,106 +237,17 @@ function planTransaction(registry, activeDir, shortIdLength) {
     taskIdToKey.set(taskId, key);
   }
 
-  // A4: classify each active task
+  // The registry is the sole source of truth: short ids are allocated only by
+  // explicit `alloc` (planAlloc), never inferred from task.md or auto-allocated
+  // for active tasks. Read paths (resolve/list) only run stale cleanup (A2).
   const plannedRegistryWrites = [];
-  const plannedTaskMdWrites = [];
-  const pendingAlloc = [];
-
-  for (const taskId of activeTaskIds) {
-    const taskMdPath = path.join(activeDir, taskId, "task.md");
-    const originalStat = fs.statSync(taskMdPath);
-    const originalContent = fs.readFileSync(taskMdPath, "utf8");
-    const existing = originalContent.match(/^short_id:\s*(#\d+)\s*$/m);
-
-    if (existing) {
-      const declared = existing[1];
-      const n = declared.slice(1);
-      if (projectedIds[n] === taskId) continue; // 4a
-      if (taskIdToKey.has(taskId)) {
-        const registryKey = taskIdToKey.get(taskId);
-        writeStderr(
-          `Inconsistent: task ${taskId} declares ${declared} but registry holds it at #${registryKey}\n`
-        );
-        process.exit(2);
-      }
-      if (projectedIds[n] && projectedIds[n] !== taskId) {
-        writeStderr(
-          `Inconsistent: task ${taskId} declares ${declared} but registry maps ${declared} to ${projectedIds[n]}\n`
-        );
-        process.exit(2);
-      }
-      // 4d
-      plannedRegistryWrites.push({ key: n, taskId });
-      projectedIds[n] = taskId;
-      taskIdToKey.set(taskId, n);
-      continue;
-    }
-
-    if (taskIdToKey.has(taskId)) {
-      // 4e
-      const registryKey = taskIdToKey.get(taskId);
-      plannedTaskMdWrites.push({
-        taskMdPath,
-        originalContent,
-        originalAtime: originalStat.atime,
-        originalMtime: originalStat.mtime,
-        shortId: `#${registryKey}`,
-        kind: "4e"
-      });
-      continue;
-    }
-
-    // 4f: deferred
-    pendingAlloc.push({
-      taskId,
-      taskMdPath,
-      originalContent,
-      originalAtime: originalStat.atime,
-      originalMtime: originalStat.mtime
-    });
-  }
-
-  // A5: capacity pre-check
-  const availableSlots = maxN - Object.keys(projectedIds).length;
-  if (pendingAlloc.length > availableSlots) {
-    writeStderr(
-      `Error: cold-start migration needs ${pendingAlloc.length} short id(s) but only ${availableSlots} ` +
-        `slot(s) available (capacity=${maxN}, in-use after stale-cleanup=${Object.keys(projectedIds).length}). ` +
-        `Archive some active tasks (complete-task / cancel-task / block-task) ` +
-        `or raise task.shortIdLength in .agents/.airc.json.\n`
-    );
-    process.exit(2);
-  }
-
-  pendingAlloc.sort((a, b) => a.taskId.localeCompare(b.taskId));
-
-  for (const item of pendingAlloc) {
-    const n = allocateMinFreeInt({ ids: projectedIds }, shortIdLength);
-    if (n === null) {
-      throw new Error("Internal invariant: pendingAlloc capacity check failed");
-    }
-    const key = padShortId(n, shortIdLength);
-    projectedIds[key] = item.taskId;
-    taskIdToKey.set(item.taskId, key);
-    plannedRegistryWrites.push({ key, taskId: item.taskId });
-    plannedTaskMdWrites.push({
-      taskMdPath: item.taskMdPath,
-      originalContent: item.originalContent,
-      originalAtime: item.originalAtime,
-      originalMtime: item.originalMtime,
-      shortId: `#${key}`,
-      kind: "4f"
-    });
-  }
 
-  // Build transaction object
   const tx = {
     _registry: registry,
     _activeDir: activeDir,
     _registrySnapshot: { ...registry.ids },
     _pendingRegistryDeletes: pendingRegistryDeletes,
     _plannedRegistryWrites: plannedRegistryWrites,
-    _plannedTaskMdWrites: plannedTaskMdWrites,
     _projectedIds: projectedIds,
     _taskIdToKey: taskIdToKey,
     _shortIdLength: shortIdLength,
@@ -363,20 +273,6 @@ function planTransaction(registry, activeDir, shortIdLength) {
       this._projectedIds[key] = taskId;
       this._taskIdToKey.set(taskId, key);
       this._plannedRegistryWrites.push({ key, taskId });
-      const originalStat = fs.statSync(taskMdPath);
-      const originalContent = fs.readFileSync(taskMdPath, "utf8");
-      // If task.md already declares the same short id (e.g. R-alloc replay), skip writing.
-      const existing = originalContent.match(/^short_id:\s*(#\d+)\s*$/m);
-      if (!existing || existing[1] !== `#${key}`) {
-        this._plannedTaskMdWrites.push({
-          taskMdPath,
-          originalContent,
-          originalAtime: originalStat.atime,
-          originalMtime: originalStat.mtime,
-          shortId: `#${key}`,
-          kind: "caller-alloc"
-        });
-      }
       return key;  // zero-padded; matches registry key
     },
 
@@ -386,54 +282,22 @@ function planTransaction(registry, activeDir, shortIdLength) {
       this._plannedRegistryWrites = this._plannedRegistryWrites.filter(
         (w) => w.taskId !== taskId
       );
-      this._plannedTaskMdWrites = this._plannedTaskMdWrites.filter(
-        (w) => path.basename(path.dirname(w.taskMdPath)) !== taskId
-      );
       this._pendingRegistryDeletes.push(key);
       delete this._projectedIds[key];
       this._taskIdToKey.delete(taskId);
     },
 
     commit(registryPath) {
-      // B1: apply registry mutation in memory
+      // Apply registry mutation in memory, then persist atomically.
       for (const key of this._pendingRegistryDeletes) delete this._registry.ids[key];
       for (const { key, taskId } of this._plannedRegistryWrites) {
         this._registry.ids[key] = taskId;
       }
-
-      const completedWrites = [];
-      const rollback = (reason) => {
-        for (const done of completedWrites.reverse()) {
-          try {
-            fs.writeFileSync(done.taskMdPath, done.originalContent);
-            fs.utimesSync(done.taskMdPath, done.originalAtime, done.originalMtime);
-          } catch {
-            /* best-effort */
-          }
-        }
-        this._registry.ids = this._registrySnapshot;
-        const tail =
-          completedWrites.length > 0
-            ? `; rolled back ${completedWrites.length} prior task.md write(s)`
-            : "";
-        throw new Error(`${reason}${tail}`);
-      };
-
-      // B2: write task.md per plan
-      for (const write of this._plannedTaskMdWrites) {
-        try {
-          writeTaskMdShortId(write.taskMdPath, write.shortId);
-          completedWrites.push(write);
-        } catch (e) {
-          rollback(`Failed to write short_id to ${write.taskMdPath}: ${e.message}`);
-        }
-      }
-
-      // B3: atomic registry persistence
       try {
         writeRegistryAtomic(this._registry, registryPath);
       } catch (e) {
-        rollback(`Failed to persist registry to ${registryPath}: ${e.message}`);
+        this._registry.ids = this._registrySnapshot;
+        throw new Error(`Failed to persist registry to ${registryPath}: ${e.message}`);
       }
     }
   };
@@ -449,27 +313,10 @@ function verifyRegistry(registry, activeDir) {
       .filter((d) => fs.existsSync(path.join(activeDir, d, "task.md")))
   );
   const registryTaskIds = new Set(Object.values(registry.ids));
-  const taskmdShortIds = new Map();
-  for (const taskId of activeTaskIds) {
-    const taskMdPath = path.join(activeDir, taskId, "task.md");
-    const content = fs.readFileSync(taskMdPath, "utf8");
-    const m = content.match(/^short_id:\s*(#\d+)\s*$/m);
-    taskmdShortIds.set(taskId, m ? m[1] : null);
-  }
   const missing_in_registry = [];
   for (const taskId of activeTaskIds) {
     if (!registryTaskIds.has(taskId)) {
-      missing_in_registry.push({ taskId, declared: taskmdShortIds.get(taskId) });
-    }
-  }
-  const missing_in_taskmd = [];
-  for (const [key, taskId] of Object.entries(registry.ids)) {
-    if (!activeTaskIds.has(taskId)) continue;
-    const declared = taskmdShortIds.get(taskId);
-    if (declared === null) {
-      missing_in_taskmd.push({ taskId, expected: `#${key}` });
-    } else if (declared !== `#${key}`) {
-      missing_in_taskmd.push({ taskId, expected: `#${key}`, declared });
+      missing_in_registry.push({ taskId });
     }
   }
   const orphans_in_registry = [];
@@ -491,7 +338,6 @@ function verifyRegistry(registry, activeDir) {
   }
   return {
     missing_in_registry,
-    missing_in_taskmd,
     orphans_in_registry,
     duplicate_registry_keys
   };
@@ -548,8 +394,8 @@ function cmdRelease(taskId, activeDir, registryPath, shortIdLength) {
 }
 
 function cmdResolve(shortIdArg, activeDir, registryPath, shortIdLength) {
-  // Strict width match + reserved key check; on invalid arg, parseShortIdArg writes full
-  // stderr (including "expected #NN (N-digit zero-padded; e.g. '#01')") and exits 1.
+  // Accepts bare digits ('11') or '#'-prefixed form ('#11', '#11', '#005'); normalized by
+  // numeric value with capacity check (n > 10^L-1) and reserved-zero rejection.
   const key = parseShortIdArg(shortIdArg, shortIdLength);
   return withRegistryLock(activeDir, () => {
     const registry = readRegistry(registryPath);
@@ -558,8 +404,7 @@ function cmdResolve(shortIdArg, activeDir, registryPath, shortIdLength) {
     if (!taskId) {
       const hasPendingMutations =
         tx._plannedRegistryWrites.length > 0 ||
-        tx._pendingRegistryDeletes.length > 0 ||
-        tx._plannedTaskMdWrites.length > 0;
+        tx._pendingRegistryDeletes.length > 0;
       if (hasPendingMutations) {
         try {
           tx.commit(registryPath);
@@ -604,7 +449,6 @@ function cmdList(activeDir, registryPath, verify) {
   const diff = verifyRegistry(registry, activeDir);
   const hasIssues =
     diff.missing_in_registry.length > 0 ||
-    diff.missing_in_taskmd.length > 0 ||
     diff.orphans_in_registry.length > 0 ||
     diff.duplicate_registry_keys.length > 0;
   if (hasIssues) {
@@ -699,7 +543,6 @@ export {
   readRegistry,
   writeRegistryAtomic,
   withRegistryLock,
-  writeTaskMdShortId,
   padShortId,
   parseShortIdArg,
   allocateMinFreeInt,

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -29,7 +29,7 @@ Before the state check is complete, do not make external-state assertions such a
 
 ## Task id short ref
 
-> If `{task-id}` begins with `#`, follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
 ## Steps
 
@@ -65,6 +65,8 @@ If `task.md` contains these source fields, also read the corresponding source in
 - `codescan_alert_number` - Code Scanning alert
 - `security_alert_number` - Dependabot alert
 
+**Round ≥ 2: respond to the prior review (only when a review artifact exists)**: if the task directory contains `review-analysis.md` / `review-analysis-r{N}.md`, read the highest-round review report; add a `## Response to Prior Review` section to this round's analysis artifact, and for each finding verify it via Read/Grep before acting (holds → accept and fix; judged hallucinated/unfounded → rebut with counter-evidence rather than defaulting to compliance); record any open disagreement under `## Open Questions`. Round 1 has no review, so skip this section.
+
 ### 4. Perform Requirements Analysis
 
 Before analysis begins: if `start_date` in the frontmatter is empty, write today's date immediately (command: `date +%F`, format `YYYY-MM-DD`); keep any existing value. Before writing, read `.agents/rules/version-stamp.md` and refresh `updated_at` / `agent_infra_version` at the same time.
@@ -154,15 +156,11 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - Mark requirement-analysis as complete in workflow progress and include the actual round when the task template supports it
 - Before appending the workflow Activity Log entry, re-estimate `priority` based on the analysis findings (business impact, risks, dependencies, blockers). If the re-estimated value differs from the current value in `task.md`:
   - Overwrite the `priority` field in frontmatter with the new value
-  - Prepend an Activity Log entry recording the transition (placed before the `Requirement Analysis (Round N)` entry):
-    ```
-    - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analysis Re-estimate** by {agent} — priority {old} → {new} (rationale: {short basis grounded in this analysis})
-    ```
-  Both entries may share the same timestamp; ordering is conveyed by list position only.
-  If the re-estimated value matches the current value, skip the Re-estimate entry. The Flow A sync that follows reads the possibly updated frontmatter and propagates the new value to the Issue automatically.
+  - Append a `## Priority Re-estimate` section to this round's analysis artifact `{analysis-artifact}`, recording: `priority {old} → {new} (rationale: {short basis grounded in this analysis})`
+  If the re-estimated value matches the current value, skip it: do not write the `## Priority Re-estimate` section. The Flow A sync that follows reads the possibly updated frontmatter and propagates the new value to the Issue automatically.
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analyze Task (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
   ```
 
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
@@ -191,7 +189,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
 
 Output format:
 ```
@@ -206,9 +204,9 @@ Output file:
 - Analysis report: .agents/workspace/active/{task-id}/{analysis-artifact}
 
 Next step - review the analysis:
-  - Claude Code / OpenCode: /review-analysis {task-id}
-  - Gemini CLI: /{{project}}:review-analysis {task-id}
-  - Codex CLI: $review-analysis {task-id}
+  - Claude Code / OpenCode: /review-analysis {task-ref}
+  - Gemini CLI: /{{project}}:review-analysis {task-ref}
+  - Codex CLI: $review-analysis {task-ref}
 ```
 
 ## Completion Checklist

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -29,7 +29,7 @@ tail .agents/workspace/active/{task-id}/task.md
 
 ## 任务入参短号别名
 
-> 如果 `{task-id}` 入参以 `#` 开头，先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
 ## 执行步骤
 ### 1. 验证前置条件
@@ -64,6 +64,8 @@ tail .agents/workspace/active/{task-id}/task.md
 - `codescan_alert_number` - Code Scanning 告警
 - `security_alert_number` - Dependabot 告警
 
+**Round ≥ 2：响应上一轮审查（仅当存在审查产物时）**：若任务目录存在 `review-analysis.md` / `review-analysis-r{N}.md`，读取最高轮次的审查报告；在本轮分析产物中新增 `## 对上一轮审查的响应` 段，对每条发现先 Read/Grep 核实再处置（成立 → 接受并修正；判定为幻觉/不成立 → 附反证反驳，不默认顺从），未决分歧写入 `## 未决问题`。Round 1 无审查，跳过本段。
+
 ### 4. 执行需求分析
 
 开始分析前：若 frontmatter 的 `start_date` 为空，立即写入当日日期（命令 `date +%F`，格式 `YYYY-MM-DD`）；已有值则保留。写入前先读取 `.agents/rules/version-stamp.md`，并同步刷新 `updated_at` / `agent_infra_version`。
@@ -153,15 +155,11 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 在工作流进度中标记 requirement-analysis 为已完成，并注明实际轮次（如果任务模板支持）
 - 在追加工作流 Activity Log 条目之前，基于分析结果（业务影响、风险、依赖、阻塞条件）重估 `priority`。若重估值与 `task.md` 当前值不一致：
   - 用新值覆盖 frontmatter 的 `priority` 字段
-  - 在 `Requirement Analysis (Round N)` 条目之前追加一条转移记录：
-    ```
-    - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analysis Re-estimate** by {agent} — priority {old} → {new} (rationale: {基于本轮分析的简短依据})
-    ```
-  两条条目可共用同一时间戳，顺序仅通过列表位置表达。
-  若重估值与当前值一致，跳过 Re-estimate 条目。后续 Flow A 同步会读取可能更新过的 frontmatter，并自动把新值同步到 Issue。
+  - 在本轮分析产物 `{analysis-artifact}` 中追加 `## 优先级重估` 段，记录一条：`priority {old} → {new} (rationale: {基于本轮分析的简短依据})`
+  若重估值与当前值一致，跳过：不写入 `## 优先级重估` 段。后续 Flow A 同步会读取可能更新过的 frontmatter，并自动把新值同步到 Issue。
 - **追加**到 `## Activity Log`（不要覆盖之前的记录）：
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analyze Task (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
   ```
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
@@ -190,7 +188,7 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 输出格式：
 ```
@@ -205,9 +203,9 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 - 分析报告：.agents/workspace/active/{task-id}/{analysis-artifact}
 
 下一步 - 审查需求分析：
-  - Claude Code / OpenCode：/review-analysis {task-id}
-  - Gemini CLI：/agent-infra:review-analysis {task-id}
-  - Codex CLI：$review-analysis {task-id}
+  - Claude Code / OpenCode：/review-analysis {task-ref}
+  - Gemini CLI：/agent-infra:review-analysis {task-ref}
+  - Codex CLI：$review-analysis {task-ref}
 ```
 
 ## 完成检查清单

package/templates/.agents/skills/analyze-task/config/verify.en.json

@@ -32,7 +32,7 @@
       ]
     },
     "activity-log": {
-      "expected_action_pattern": "Requirement Analysis \\(Round \\d+\\)",
+      "expected_action_pattern": "(Analyze Task|Requirement Analysis) \\(Round \\d+\\)",
       "freshness_minutes": 30
     },
     "platform-sync": {

package/templates/.agents/skills/analyze-task/config/verify.zh-CN.json

@@ -32,7 +32,7 @@
       ]
     },
     "activity-log": {
-      "expected_action_pattern": "Requirement Analysis \\(Round \\d+\\)",
+      "expected_action_pattern": "(Analyze Task|Requirement Analysis) \\(Round \\d+\\)",
       "freshness_minutes": 30
     },
     "platform-sync": {

package/templates/.agents/skills/block-task/SKILL.en.md

@@ -21,7 +21,7 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 ## Task id short ref
 
-> If `{task-id}` begins with `#`, follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
 ## Steps
 
@@ -56,7 +56,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Blocked** by {agent} — {one-line reason}
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Block Task** by {agent} — {one-line reason}
   ```
 
 Add a blocking information section to task.md.
@@ -106,7 +106,9 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to blocked/, so read it from `.agents/workspace/blocked/{task-id}/task.md`). This block is independent of "Next step" semantics.
 
 Output format:
 ```
@@ -116,14 +118,19 @@ Blocking reason: {summary}
 Required to unblock: {what's needed}
 Archived to: .agents/workspace/blocked/{task-id}/
 
+Optional: clean up this task's sandbox
+(The task is blocked and moved to blocked/; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
 To unblock when the issue is resolved:
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # Then update task.md: status -> active, remove blocked_at
 
 Next step - check task status after unblocking:
-  - Claude Code / OpenCode: /check-task {task-id}
-  - Gemini CLI: /{{project}}:check-task {task-id}
-  - Codex CLI: $check-task {task-id}
+  - Claude Code / OpenCode: /check-task {task-ref}
+  - Gemini CLI: /{{project}}:check-task {task-ref}
+  - Codex CLI: $check-task {task-ref}
 ```
 
 

package/templates/.agents/skills/block-task/SKILL.zh-CN.md

@@ -21,7 +21,7 @@ description: "标记任务为阻塞状态并记录原因"
 
 ## 任务入参短号别名
 
-> 如果 `{task-id}` 入参以 `#` 开头，先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
 ## 执行步骤
 ### 1. 验证任务存在
@@ -55,7 +55,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
 - **追加**到 `## Activity Log`（不要覆盖之前的记录）：
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Blocked** by {agent} — {一行原因}
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Block Task** by {agent} — {一行原因}
   ```
 
 在 task.md 中添加阻塞信息部分。
@@ -105,7 +105,9 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
 ```
@@ -115,14 +117,19 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 解除阻塞所需：{需要什么}
 归档路径：.agents/workspace/blocked/{task-id}/
 
+可选：清理本任务的沙箱
+（任务已阻塞并移到 blocked/，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 解除阻塞时执行：
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # 然后更新 task.md：status -> active，移除 blocked_at
 
 下一步 - 检查任务状态（解除阻塞后）：
-  - Claude Code / OpenCode：/check-task {task-id}
-  - Gemini CLI：/agent-infra:check-task {task-id}
-  - Codex CLI：$check-task {task-id}
+  - Claude Code / OpenCode：/check-task {task-ref}
+  - Gemini CLI：/agent-infra:check-task {task-ref}
+  - Codex CLI：$check-task {task-ref}
 ```
 
 

package/templates/.agents/skills/block-task/config/verify.json

@@ -18,7 +18,7 @@
       "require_blocked_at": true
     },
     "activity-log": {
-      "expected_action_pattern": "Blocked",
+      "expected_action_pattern": "(Block Task|Blocked)",
       "freshness_minutes": 30
     },
     "platform-sync": {

package/templates/.agents/skills/cancel-task/SKILL.en.md

@@ -15,7 +15,7 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 ## Task id short ref
 
-> If `{task-id}` begins with `#`, follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
 ## Steps
 
@@ -57,7 +57,7 @@ Update `task.md` in the task directory:
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):
   ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Cancelled** by {agent} — {one-line cancellation reason}
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Cancel Task** by {agent} — {one-line cancellation reason}
   ```
 
 ### 4. Move the Task
@@ -119,7 +119,9 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to completed/, so read it from `.agents/workspace/completed/{task-id}/task.md`). This block is independent of "Next steps" semantics.
 
 Output format:
 ```
@@ -129,10 +131,15 @@ Cancellation reason: {reason}
 Status label: {status-label or skipped}
 Target path: .agents/workspace/completed/{task-id}/
 
+Optional: clean up this task's sandbox
+(The task is archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+
+ai sandbox rm {branch}
+
 Next step - inspect the moved task:
-  - Claude Code / OpenCode: /check-task {task-id}
-  - Gemini CLI: /{{project}}:check-task {task-id}
-  - Codex CLI: $check-task {task-id}
+  - Claude Code / OpenCode: /check-task {task-ref}
+  - Gemini CLI: /{{project}}:check-task {task-ref}
+  - Codex CLI: $check-task {task-ref}
 ```