@fitlab-ai/agent-infra 0.7.4 → 0.7.5

package/bin/cli.ts

@@ -12,17 +12,19 @@ if (major < 22) {
 
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
-Usage:
-  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
-  agent-infra help            Show this help message
-  agent-infra init            Initialize a new project with update-agent-infra seed command
-  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra sandbox         Manage Docker-based AI sandboxes
-  agent-infra task            Read-only views over .agents/workspace tasks (ls / show / files / cat / status / log / grep)
-  agent-infra update          Update seed files and sync file registry for an existing project
-  agent-infra version         Show version
+Usage: ai <command> [options]
 
-Shorthand: ai (e.g. ai init)
+Commands:
+  cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  help            Show this help message
+  init            Initialize a new project with update-agent-infra seed command
+  merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  sandbox         Manage Docker-based AI sandboxes
+  task            Read-only views over .agents/workspace tasks (cat / files / grep / log / ls / show / status)
+  update          Update seed files and sync file registry for an existing project
+  version         Show version
+
+'ai' and 'agent-infra' are interchangeable; 'ai' is the shorter form.
 
 Install methods:
   npm:   npm install -g @fitlab-ai/agent-infra
@@ -31,7 +33,7 @@ Install methods:
   curl:  curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh  (runs npm install -g internally)
 
 Examples:
-  cd my-project && agent-infra init
+  cd my-project && ai init
   npx @fitlab-ai/agent-infra init
 `;
 

package/dist/bin/cli.js

@@ -16,17 +16,19 @@ if (major < 22) {
 }
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
-Usage:
-  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
-  agent-infra help            Show this help message
-  agent-infra init            Initialize a new project with update-agent-infra seed command
-  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra sandbox         Manage Docker-based AI sandboxes
-  agent-infra task            Read-only views over .agents/workspace tasks (ls / show / files / cat / status / log / grep)
-  agent-infra update          Update seed files and sync file registry for an existing project
-  agent-infra version         Show version
+Usage: ai <command> [options]
 
-Shorthand: ai (e.g. ai init)
+Commands:
+  cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  help            Show this help message
+  init            Initialize a new project with update-agent-infra seed command
+  merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  sandbox         Manage Docker-based AI sandboxes
+  task            Read-only views over .agents/workspace tasks (cat / files / grep / log / ls / show / status)
+  update          Update seed files and sync file registry for an existing project
+  version         Show version
+
+'ai' and 'agent-infra' are interchangeable; 'ai' is the shorter form.
 
 Install methods:
   npm:   npm install -g @fitlab-ai/agent-infra
@@ -35,7 +37,7 @@ Install methods:
   curl:  curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh  (runs npm install -g internally)
 
 Examples:
-  cd my-project && agent-infra init
+  cd my-project && ai init
   npx @fitlab-ai/agent-infra init
 `;
 const command = process.argv[2] || '';

package/dist/lib/init.js

@@ -70,7 +70,7 @@ function parseLocalSources(input) {
 }
 async function cmdInit() {
     console.log('');
-    console.log('  agent-infra init');
+    console.log('  ai init');
     console.log('  ================================');
     console.log('  Optional template and skill sources can be added now or later in .agents/.airc.json.');
     console.log('');

package/dist/lib/merge.js

@@ -702,7 +702,7 @@ function printReport(report) {
 async function cmdMerge(args) {
     const sourcePath = args[0];
     if (!sourcePath) {
-        throw new Error('Usage: agent-infra merge <source-path>');
+        throw new Error('Usage: ai merge <source-path>');
     }
     const resolvedSource = path.resolve(sourcePath);
     if (!fs.existsSync(resolvedSource)) {

package/dist/lib/sandbox/index.js

@@ -6,9 +6,6 @@ Commands:
                                Enter sandbox or run a command. N (bare) is the
                                recommended form for task short ids (e.g.
                                'ai sandbox exec 11'); '#N' is also accepted.
-  start <branch | TASK-id | N | '#N'>
-                               Start an existing stopped sandbox container
-                               (e.g. after the Docker daemon restarted)
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
@@ -19,6 +16,9 @@ Commands:
   rm <branch> | --all | --purge
                                Remove one sandbox, all sandboxes not bound to an
                                active task (--all), or tear down everything (--purge)
+  start <branch | TASK-id | N | '#N'>
+                               Start an existing stopped sandbox container
+                               (e.g. after the Docker daemon restarted)
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
@@ -47,6 +47,21 @@ export async function runSandbox(args) {
             }
             break;
         }
+        case 'ls': {
+            const { ls } = await import("./commands/ls.js");
+            ls(rest);
+            break;
+        }
+        case 'prune': {
+            const { prune } = await import("./commands/prune.js");
+            await prune(rest);
+            break;
+        }
+        case 'rebuild': {
+            const { rebuild } = await import("./commands/rebuild.js");
+            await rebuild(rest);
+            break;
+        }
         case 'refresh': {
             const { refresh } = await import("./commands/refresh.js");
             const exitCode = await refresh(rest);
@@ -55,24 +70,14 @@ export async function runSandbox(args) {
             }
             break;
         }
-        case 'start': {
-            const { start } = await import("./commands/start.js");
-            await start(rest);
-            break;
-        }
-        case 'ls': {
-            const { ls } = await import("./commands/ls.js");
-            ls(rest);
-            break;
-        }
         case 'rm': {
             const { rm } = await import("./commands/rm.js");
             await rm(rest);
             break;
         }
-        case 'prune': {
-            const { prune } = await import("./commands/prune.js");
-            await prune(rest);
+        case 'start': {
+            const { start } = await import("./commands/start.js");
+            await start(rest);
             break;
         }
         case 'vm': {
@@ -80,11 +85,6 @@ export async function runSandbox(args) {
             await vm(rest);
             break;
         }
-        case 'rebuild': {
-            const { rebuild } = await import("./commands/rebuild.js");
-            await rebuild(rest);
-            break;
-        }
         default:
             throw new Error(`Unknown sandbox command: ${subcommand}`);
     }

package/dist/lib/task/index.js

@@ -34,14 +34,9 @@ export async function runTask(args) {
         return;
     }
     switch (subcommand) {
-        case 'ls': {
-            const { ls } = await import("./commands/ls.js");
-            ls(rest);
-            break;
-        }
-        case 'show': {
-            const { show } = await import("./commands/show.js");
-            show(rest);
+        case 'cat': {
+            const { cat } = await import("./commands/cat.js");
+            cat(rest);
             break;
         }
         case 'files': {
@@ -49,11 +44,6 @@ export async function runTask(args) {
             files(rest);
             break;
         }
-        case 'cat': {
-            const { cat } = await import("./commands/cat.js");
-            cat(rest);
-            break;
-        }
         case 'grep': {
             const { grep } = await import("./commands/grep.js");
             grep(rest);
@@ -64,6 +54,16 @@ export async function runTask(args) {
             log(rest);
             break;
         }
+        case 'ls': {
+            const { ls } = await import("./commands/ls.js");
+            ls(rest);
+            break;
+        }
+        case 'show': {
+            const { show } = await import("./commands/show.js");
+            show(rest);
+            break;
+        }
         case 'status': {
             const { status } = await import("./commands/status.js");
             status(rest);

package/dist/lib/update.js

@@ -83,7 +83,7 @@ function syncFileRegistry(config, platformType, enabledTUIs) {
 }
 async function cmdUpdate() {
     console.log('');
-    console.log('  agent-infra update');
+    console.log('  ai update');
     console.log('  ==================================');
     console.log('');
     // check config exists

package/lib/init.ts

@@ -119,7 +119,7 @@ function parseLocalSources(input: string): SourceEntry[] {
 
 async function cmdInit(): Promise<void> {
   console.log('');
-  console.log('  agent-infra init');
+  console.log('  ai init');
   console.log('  ================================');
   console.log('  Optional template and skill sources can be added now or later in .agents/.airc.json.');
   console.log('');

package/lib/merge.ts

@@ -901,7 +901,7 @@ function printReport(report: MergeReport): void {
 async function cmdMerge(args: string[]): Promise<void> {
   const sourcePath = args[0];
   if (!sourcePath) {
-    throw new Error('Usage: agent-infra merge <source-path>');
+    throw new Error('Usage: ai merge <source-path>');
   }
 
   const resolvedSource = path.resolve(sourcePath);

package/lib/sandbox/index.ts

@@ -6,9 +6,6 @@ Commands:
                                Enter sandbox or run a command. N (bare) is the
                                recommended form for task short ids (e.g.
                                'ai sandbox exec 11'); '#N' is also accepted.
-  start <branch | TASK-id | N | '#N'>
-                               Start an existing stopped sandbox container
-                               (e.g. after the Docker daemon restarted)
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
@@ -19,6 +16,9 @@ Commands:
   rm <branch> | --all | --purge
                                Remove one sandbox, all sandboxes not bound to an
                                active task (--all), or tear down everything (--purge)
+  start <branch | TASK-id | N | '#N'>
+                               Start an existing stopped sandbox container
+                               (e.g. after the Docker daemon restarted)
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
@@ -51,6 +51,21 @@ export async function runSandbox(args: string[]): Promise<void> {
       }
       break;
     }
+    case 'ls': {
+      const { ls } = await import('./commands/ls.ts');
+      ls(rest);
+      break;
+    }
+    case 'prune': {
+      const { prune } = await import('./commands/prune.ts');
+      await prune(rest);
+      break;
+    }
+    case 'rebuild': {
+      const { rebuild } = await import('./commands/rebuild.ts');
+      await rebuild(rest);
+      break;
+    }
     case 'refresh': {
       const { refresh } = await import('./commands/refresh.ts');
       const exitCode = await refresh(rest);
@@ -59,24 +74,14 @@ export async function runSandbox(args: string[]): Promise<void> {
       }
       break;
     }
-    case 'start': {
-      const { start } = await import('./commands/start.ts');
-      await start(rest);
-      break;
-    }
-    case 'ls': {
-      const { ls } = await import('./commands/ls.ts');
-      ls(rest);
-      break;
-    }
     case 'rm': {
       const { rm } = await import('./commands/rm.ts');
       await rm(rest);
       break;
     }
-    case 'prune': {
-      const { prune } = await import('./commands/prune.ts');
-      await prune(rest);
+    case 'start': {
+      const { start } = await import('./commands/start.ts');
+      await start(rest);
       break;
     }
     case 'vm': {
@@ -84,11 +89,6 @@ export async function runSandbox(args: string[]): Promise<void> {
       await vm(rest);
       break;
     }
-    case 'rebuild': {
-      const { rebuild } = await import('./commands/rebuild.ts');
-      await rebuild(rest);
-      break;
-    }
     default:
       throw new Error(`Unknown sandbox command: ${subcommand}`);
   }

package/lib/task/index.ts

@@ -38,14 +38,9 @@ export async function runTask(args: string[]): Promise<void> {
   }
 
   switch (subcommand) {
-    case 'ls': {
-      const { ls } = await import('./commands/ls.ts');
-      ls(rest);
-      break;
-    }
-    case 'show': {
-      const { show } = await import('./commands/show.ts');
-      show(rest);
+    case 'cat': {
+      const { cat } = await import('./commands/cat.ts');
+      cat(rest);
       break;
     }
     case 'files': {
@@ -53,11 +48,6 @@ export async function runTask(args: string[]): Promise<void> {
       files(rest);
       break;
     }
-    case 'cat': {
-      const { cat } = await import('./commands/cat.ts');
-      cat(rest);
-      break;
-    }
     case 'grep': {
       const { grep } = await import('./commands/grep.ts');
       grep(rest);
@@ -68,6 +58,16 @@ export async function runTask(args: string[]): Promise<void> {
       log(rest);
       break;
     }
+    case 'ls': {
+      const { ls } = await import('./commands/ls.ts');
+      ls(rest);
+      break;
+    }
+    case 'show': {
+      const { show } = await import('./commands/show.ts');
+      show(rest);
+      break;
+    }
     case 'status': {
       const { status } = await import('./commands/status.ts');
       status(rest);

package/lib/update.ts

@@ -119,7 +119,7 @@ function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUI
 
 async function cmdUpdate(): Promise<void> {
   console.log('');
-  console.log('  agent-infra update');
+  console.log('  ai update');
   console.log('  ==================================');
   console.log('');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/README.en.md

@@ -8,7 +8,7 @@ so you can quickly find "which ones to read" without opening each file.
 
 ## General Principles
 
-- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Silence during SKILL runs: no user questions by default, plus two exceptions.
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Silence during SKILL runs: no user questions by default, plus the exceptions the rule lists.
 - [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
 - [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
 - [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
@@ -25,6 +25,7 @@ so you can quickly find "which ones to read" without opening each file.
 ## Task Workflow
 
 - [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
+- [`review-handshake.md`](review-handshake.md) — Three-stage bidirectional review handshake: four-state disposition, symmetric evidence, disagreement ledger, convergence and post-review commit gate.
 - [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of `#NN` / bare-number short ids.
 - [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.
 - [`label-milestone-setup.md`](label-milestone-setup.md) — Platform commands to initialize labels / milestones.
@@ -35,7 +36,10 @@ so you can quickly find "which ones to read" without opening each file.
 - [`commit-and-pr.md`](commit-and-pr.md) — Conventional Commits message and PR conventions.
 - [`release-commands.md`](release-commands.md) — Read past releases, query merged PRs, publish release notes.
 
-## Testing & Cross-platform
+## Testing
 
 - [`testing-discipline.md`](testing-discipline.md) — Test-writing discipline: prefer structural asserts, no brittle wording matches.
-- [`cross-platform-tests.md`](cross-platform-tests.md) — Cross-platform test guards: express platform skips via `onPlatforms()`.
+
+## CLI
+
+- [`cli-help-format.md`](cli-help-format.md) — CLI help text conventions: unify display name on `ai`, `Usage:`+`Commands:` structure, alphabetical command order (top-level and namespace-level help only).

package/templates/.agents/rules/README.zh-CN.md

@@ -7,7 +7,7 @@
 
 ## 通用准则
 
-- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — SKILL 执行期禁言：默认不向用户提问，及两类例外。
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — SKILL 执行期禁言：默认不向用户提问，及规则列明的例外。
 - [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
@@ -24,6 +24,7 @@
 ## 任务工作流
 
 - [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
+- [`review-handshake.md`](review-handshake.md) — 三阶段双向审查握手协议：四态处置、对称证据、分歧账本、收敛与 post-review commit 门禁。
 - [`task-short-id.md`](task-short-id.md) — 任务短号 `#NN` / 裸数字的解析、分配与生命周期。
 - [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。
 - [`label-milestone-setup.md`](label-milestone-setup.md) — 初始化 label / milestone 的平台命令集。
@@ -34,7 +35,10 @@
 - [`commit-and-pr.md`](commit-and-pr.md) — Conventional Commits 提交信息与 PR 规范。
 - [`release-commands.md`](release-commands.md) — 读取历史 release、查询已合并 PR、发布 Release notes。
 
-## 测试与跨平台
+## 测试
 
 - [`testing-discipline.md`](testing-discipline.md) — 测试编写纪律：结构性断言优先，禁止脆弱的措辞匹配。
-- [`cross-platform-tests.md`](cross-platform-tests.md) — 跨平台测试守卫：用 `onPlatforms()` 表达平台跳过。
+
+## CLI
+
+- [`cli-help-format.md`](cli-help-format.md) — CLI help 文案约定：展示名统一 `ai`、`Usage:`+`Commands:` 结构、命令按字母序（仅顶层与命名空间级 help）。

package/templates/.agents/rules/cli-help-format.en.md

@@ -0,0 +1,49 @@
+# CLI help text conventions
+
+Unify the help text display structure, display name, and command ordering of the `ai` / `agent-infra` CLI so newly added subcommands follow them automatically and never drift across levels again. Read this file before adding or changing CLI help text.
+
+## Scope
+
+- **Display name `ai`**: applies to **all** user-facing help / usage / banner text — top-level, namespace-level, and the single-line usage / startup banners of leaf commands such as `merge` / `init` / `update`. The only exceptions: the top-level help first line keeps the brand + version line `agent-infra ${VERSION}`, and `@fitlab-ai/agent-infra` in package names / install commands / repo URLs stays as-is.
+- **Structure & ordering** (`Usage:` + `Commands:` structure, alphabetical command order): applies only to levels that carry a `Commands:` listing — top-level help (`bin/cli.ts`) and namespace-level help (e.g. `ai sandbox` / `ai task`). Leaf commands have only a single-line usage and need no `Commands:` structure.
+
+## Display name
+
+- Use **`ai`** as the command display name in help text (the recommended short form; `package.json`'s `bin` registers both `ai` and `agent-infra`).
+- Keep the top-level help first line as the brand + version line `agent-infra ${VERSION} - bootstrap ...` (it is the brand and version marker that several tests anchor on).
+- Keep `@fitlab-ai/agent-infra` in install methods, package names, and repo URLs as-is (those are package names, not command display names).
+
+## List structure
+
+Namespace-level and top-level help follow:
+
+```
+Usage: ai <ns> <command> [options]
+
+Commands:
+  <command>  <description aligned from two spaces>
+  ...
+
+Run 'ai <ns> <command> --help' for details.
+```
+
+- The `Commands:` block uses bare command names (no repeated binary name), two-space indent, descriptions aligned to the longest command name.
+- Namespace-level help ends with a `Run 'ai <ns> <command> --help' for details.` footer.
+- Top-level help has no uniform subcommand `--help` convention, so the footer is not required there; if an `Examples:` section exists, its command display name is also `ai`.
+
+## Ordering
+
+Command lists, `Examples`, and command enumerations embedded in descriptions are all sorted by the **first token of the command, in ascending alphabetical order**:
+
+- Multi-token commands (e.g. `vm status|start|stop`) sort by the first token (`vm`).
+- Commands with angle/square-bracket parameters sort by the command name (the bare word before the parameters).
+- Case-insensitive.
+
+## Checklist for adding a subcommand
+
+When adding a subcommand:
+
+1. Insert the command at the correct alphabetical position in `Commands:`.
+2. If it has examples, insert them at the alphabetical position in `Examples:`.
+3. If a top-level `task` / `sandbox` description has an embedded command enumeration, update its alphabetical order too.
+4. Sync the corresponding help test's **structural** assertions (whether the command appears, whether the `Usage:` / `Commands:` header exists); do not bind to full sentences (see [`testing-discipline.md`](testing-discipline.md)).

package/templates/.agents/rules/cli-help-format.zh-CN.md

@@ -0,0 +1,49 @@
+# CLI help 文案约定
+
+统一 `ai` / `agent-infra` CLI 的 help 文案展示结构、展示名与命令排序，让后续新增子命令自动遵守，避免跨层级再次漂移。新增或调整 CLI help 文案前先读取本文件。
+
+## 适用范围
+
+- **展示名 `ai`**：适用于**所有**面向用户的 help / usage / 交互横幅文案——顶层、命名空间级，以及 `merge` / `init` / `update` 等叶子命令的单行 usage 与启动横幅，统一用 `ai`。唯一例外：顶层 help 首行保留品牌 + 版本行 `agent-infra ${VERSION}`；包名 / 安装命令 / 仓库 URL 中的 `@fitlab-ai/agent-infra` 保持原样。
+- **结构与排序**（`Usage:` + `Commands:` 结构、命令按字母序）：仅适用于带 `Commands:` 子清单的层级——顶层 help（`bin/cli.ts`）与命名空间级 help（如 `ai sandbox` / `ai task`）。叶子命令只有单行 usage，无需 `Commands:` 结构。
+
+## 展示名
+
+- help 文案中的命令展示名统一用 **`ai`**（推荐简写，`package.json` 的 `bin` 同时注册 `ai` 与 `agent-infra`）。
+- 顶层 help 首行保留品牌 + 版本行 `agent-infra ${VERSION} - bootstrap ...`（这是品牌与版本标识，多处测试锚定它）。
+- 安装方式、包名、仓库 URL 中的 `@fitlab-ai/agent-infra` 等保持原样（是包名而非命令展示名）。
+
+## 列表结构
+
+命名空间级与顶层 help 统一为：
+
+```
+Usage: ai <ns> <command> [options]
+
+Commands:
+  <command>  <两空格起对齐的描述>
+  ...
+
+Run 'ai <ns> <command> --help' for details.
+```
+
+- `Commands:` 块用裸命令名（不重复二进制名），两空格缩进，描述按最长命令名对齐。
+- 命名空间级 help 末尾加 `Run 'ai <ns> <command> --help' for details.` footer。
+- 顶层 help 无统一子命令 `--help` 约定，故不强制加该 footer；如有 `Examples:` 段，命令展示名同样用 `ai`。
+
+## 排序
+
+命令清单、`Examples`、描述中内嵌的命令枚举，一律按**命令首 token 的字母升序**排列：
+
+- 多 token 命令（如 `vm status|start|stop`）按首 token（`vm`）排序。
+- 带尖括号 / 方括号参数的命令按命令名（参数前的裸词）排序。
+- 大小写不敏感。
+
+## 新增子命令检查清单
+
+新增一个子命令时：
+
+1. 把命令插入 `Commands:` 的字母序正确位置。
+2. 如有示例，插入 `Examples:` 的字母序位置。
+3. 若顶层 `task` / `sandbox` 等描述中有内嵌命令枚举，同步更新其字母序。
+4. 同步对应 help 测试的**结构性**断言（命令是否出现、`Usage:` / `Commands:` 头是否存在），不要绑定整句文案（见 [`testing-discipline.md`](testing-discipline.md)）。

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

@@ -1,7 +1,7 @@
 # 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.
+> Only the exemption categories listed below may ask the user; any other mid-flow question is a violation.
 
 ## Exemption Categories
 
@@ -27,9 +27,21 @@ 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
 
+### Exemption 3: Entry-point requirement-sufficiency clarification
+
+Allowed only when a SKILL judges, **at its entry point**, whether the current task's requirement information is sufficient for a reliable analysis; it may then ask the user about the **missing requirement information** to converge the requirements. Constraints:
+
+- Limited to the `analyze-task` entry point; ask one question at a time and wait for the answer before asking the next;
+- Used only to fill requirement-sufficiency gaps; it must **not** be used to solicit implementation / technical-choice preferences (those still go into the artifact's `## Open Questions` per the default clause);
+- Exit the questioning and proceed to normal analysis once the question budget is reached or the user says "just analyze / skip".
+
+SKILLs currently covered by this exemption:
+
+- `analyze-task`: when the task description/requirements are insufficient for a reliable analysis, it may ask questions one at a time at the entry point to converge the requirements
+
 ## No-Mid-Flow-Questions Clause (default behavior)
 
-For every SKILL execution context not covered by the two exemptions above, the default behavior is:
+For every SKILL execution context not covered by any exemption 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:

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

@@ -1,7 +1,7 @@
 # 通用规则 - SKILL 执行禁言
 
 > **适用范围**：本规则适用于**所有 SKILL** 的执行过程。
-> 仅以下两类例外可向用户提问；不属于这两类的发问一律按违规处理。
+> 仅以下列出的例外可向用户提问；不属于这些例外的发问一律按违规处理。
 
 ## 例外类型
 
@@ -27,9 +27,21 @@
 - `init-labels`：删除不在最终映射中的旧 label 前可确认
 - `commit`：检测到与用户未提交改动冲突时可停下确认
 
+### 例外 3：入口式需求充分性澄清
+
+仅当 SKILL 在**入口处**判断「当前任务的需求信息是否充分到可以可靠分析」时，可就**缺失的需求信息**向用户提问以收敛需求。约束：
+
+- 仅限 `analyze-task` 入口；一次只问一个问题，等用户回答后再问下一个；
+- 仅用于补齐需求充分性，**不得**借此征求实现方案 / 技术选型偏好（这些仍按禁言铁律写入产物的 `## 未决问题`）；
+- 达到提问预算上限或用户表示「直接分析 / skip」即退出提问，进入正常分析。
+
+当前归入本例外的 SKILL：
+
+- `analyze-task`：任务描述/需求信息不足以支撑可靠分析时，可在入口处逐个提问收敛需求
+
 ## 禁言条款（默认行为）
 
-不属于上述两类例外的所有 SKILL 执行场景，遵循以下默认行为：
+不属于上述任一例外的所有 SKILL 执行场景，遵循以下默认行为：
 
 1. **禁止调用**任何向用户发问的工具（包括但不限于 `AskUserQuestion` 及等价的「征求用户选择」机制）。
 2. **不确定时**，按「最稳健方案」自主推进，不中断对话。最稳健方案的判定优先级：