@fitlab-ai/agent-infra 0.7.0 → 0.7.2

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

@@ -0,0 +1,556 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const SHORT_ID_RE = /^#\d+$/;
+const REGISTRY_NAME = ".short-ids.json";
+const LOCK_NAME = ".short-ids.json.lock";
+const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+// Kept in sync with lib/defaults.json's task.shortIdLength. Used when there is
+// no `--short-id-length` flag and no readable `task.shortIdLength` in
+// .agents/.airc.json (e.g. the project upgraded but hasn't re-run
+// ai update-agent-infra to backfill the field).
+const DEFAULT_SHORT_ID_LENGTH = 2;
+
+// process.stdout.write / process.stderr.write are non-blocking when the
+// destination is a pipe (e.g. when spawned via child_process.spawnSync). On
+// some platforms (notably macOS) the Node process can exit before the buffer
+// flushes, leaving the parent with empty stdout. Use fs.writeSync to guarantee
+// synchronous, fully-flushed writes — this is critical because the parent
+// CLI/test code relies on stdout to carry the resolved task id / short id.
+function writeStdout(text) {
+  fs.writeSync(1, text);
+}
+
+function writeStderr(text) {
+  fs.writeSync(2, text);
+}
+
+function usage() {
+  return [
+    "Usage: task-short-id.js <subcommand> [args]",
+    "",
+    "Subcommands:",
+    "  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 disagree",
+    "",
+    "Options:",
+    "  --active-dir <path>  Override active dir (default: <repo>/.agents/workspace/active)",
+    "  --short-id-length N  Override configured width (default: from .airc.json or 2)"
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const args = { positional: [], activeDir: null, shortIdLength: null, verify: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--active-dir") {
+      args.activeDir = argv[++i];
+    } else if (a === "--short-id-length") {
+      args.shortIdLength = Number(argv[++i]);
+    } else if (a === "--verify") {
+      args.verify = true;
+    } else if (a === "-h" || a === "--help") {
+      args.help = true;
+    } else if (a.startsWith("--")) {
+      throw new Error(`Unknown option: ${a}`);
+    } else {
+      args.positional.push(a);
+    }
+  }
+  return args;
+}
+
+function findRepoRoot(start) {
+  let dir = path.resolve(start || process.cwd());
+  for (;;) {
+    if (fs.existsSync(path.join(dir, ".agents", ".airc.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readShortIdLength(repoRoot, override) {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 1) {
+    return override;
+  }
+  if (!repoRoot) return DEFAULT_SHORT_ID_LENGTH;
+  try {
+    const cfgPath = path.join(repoRoot, ".agents", ".airc.json");
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+    const v = cfg && cfg.task && cfg.task.shortIdLength;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 1) return v;
+  } catch {
+    // ignore
+  }
+  return DEFAULT_SHORT_ID_LENGTH;
+}
+
+function readRegistry(registryPath) {
+  if (!fs.existsSync(registryPath)) {
+    return { version: 1, ids: {} };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(registryPath, "utf8");
+  } catch (e) {
+    writeStderr(`Error: cannot read registry ${registryPath}: ${e.message}\n`);
+    process.exit(2);
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || !data.ids || typeof data.ids !== "object") {
+      writeStderr(`Error: registry ${registryPath} has invalid schema\n`);
+      process.exit(2);
+    }
+    if (data.version !== 1) data.version = 1;
+    return data;
+  } catch (e) {
+    writeStderr(`Error: registry ${registryPath} is not valid JSON: ${e.message}\n`);
+    process.exit(2);
+  }
+}
+
+function writeRegistryAtomic(data, registryPath) {
+  const tmpPath = `${registryPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(data, null, 2)}\n`);
+  fs.renameSync(tmpPath, registryPath);
+}
+
+function withRegistryLock(activeDir, fn, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
+  fs.mkdirSync(activeDir, { recursive: true });
+  const lockDir = path.join(activeDir, LOCK_NAME);
+  const start = Date.now();
+  for (;;) {
+    try {
+      fs.mkdirSync(lockDir, { recursive: false });
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      if (Date.now() - start > timeoutMs) {
+        writeStderr(`Error: registry lock timeout after ${timeoutMs}ms\n`);
+        process.exit(3);
+      }
+      const elapsed = Date.now() - start;
+      const wait = Math.min(500, 50 * Math.pow(2, Math.floor(elapsed / 200)));
+      const deadline = Date.now() + wait;
+      while (Date.now() < deadline) {
+        /* busy wait, ms-scale */
+      }
+    }
+  }
+  // Register cleanup that runs even on process.exit (which skips try/finally).
+  const cleanup = () => {
+    try {
+      fs.rmdirSync(lockDir);
+    } catch {
+      /* lock-dir already removed */
+    }
+  };
+  process.once("exit", cleanup);
+  try {
+    return fn();
+  } finally {
+    process.removeListener("exit", cleanup);
+    cleanup();
+  }
+}
+
+function padShortId(n, shortIdLength) {
+  return String(n).padStart(shortIdLength, "0");
+}
+
+function allocateMinFreeInt(registry, shortIdLength) {
+  const maxN = Math.pow(10, shortIdLength) - 1;
+  for (let n = 1; n <= maxN; n += 1) {
+    if (!registry.ids[padShortId(n, shortIdLength)]) return n;
+  }
+  return null;
+}
+
+function parseShortIdArg(arg, shortIdLength) {
+  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 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);
+  }
+  if (n > max) {
+    writeStderr(
+      `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 String(n).padStart(L, "0");
+}
+
+function planTransaction(registry, activeDir, shortIdLength) {
+  const maxN = Math.pow(10, shortIdLength) - 1;
+
+  // A1: active task id set
+  const activeTaskIds = new Set(
+    fs
+      .readdirSync(activeDir)
+      .filter((d) => TASK_ID_RE.test(d))
+      .filter((d) => fs.existsSync(path.join(activeDir, d, "task.md")))
+  );
+
+  // 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);
+  }
+
+  const projectedIds = { ...registry.ids };
+  for (const key of pendingRegistryDeletes) delete projectedIds[key];
+
+  // A3: duplicate key detection (after stale cleanup)
+  const taskIdToKey = new Map();
+  for (const [key, taskId] of Object.entries(projectedIds)) {
+    if (taskIdToKey.has(taskId)) {
+      const existingKey = taskIdToKey.get(taskId);
+      writeStderr(
+        `Error: duplicate registry entries for taskId ${taskId} at keys [#${existingKey}, #${key}]; manual resolution required\n`
+      );
+      process.exit(2);
+    }
+    taskIdToKey.set(taskId, key);
+  }
+
+  // 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 tx = {
+    _registry: registry,
+    _activeDir: activeDir,
+    _registrySnapshot: { ...registry.ids },
+    _pendingRegistryDeletes: pendingRegistryDeletes,
+    _plannedRegistryWrites: plannedRegistryWrites,
+    _projectedIds: projectedIds,
+    _taskIdToKey: taskIdToKey,
+    _shortIdLength: shortIdLength,
+    _maxN: maxN,
+
+    planAlloc(taskId) {
+      const taskMdPath = path.join(activeDir, taskId, "task.md");
+      if (!fs.existsSync(taskMdPath)) {
+        throw new Error(`planAlloc: task.md not found for ${taskId}`);
+      }
+      if (this._taskIdToKey.has(taskId)) {
+        return this._taskIdToKey.get(taskId);
+      }
+      const inUse = Object.keys(this._projectedIds).length;
+      if (inUse >= this._maxN) {
+        throw new Error(
+          `Error: short id width exhausted (current shortIdLength=${this._shortIdLength}, ` +
+            `${inUse}/${this._maxN} slots in use). Archive some active tasks or raise task.shortIdLength.`
+        );
+      }
+      const n = allocateMinFreeInt({ ids: this._projectedIds }, this._shortIdLength);
+      const key = padShortId(n, this._shortIdLength);
+      this._projectedIds[key] = taskId;
+      this._taskIdToKey.set(taskId, key);
+      this._plannedRegistryWrites.push({ key, taskId });
+      return key;  // zero-padded; matches registry key
+    },
+
+    planRelease(taskId) {
+      const key = this._taskIdToKey.get(taskId);
+      if (!key) return; // idempotent
+      this._plannedRegistryWrites = this._plannedRegistryWrites.filter(
+        (w) => w.taskId !== taskId
+      );
+      this._pendingRegistryDeletes.push(key);
+      delete this._projectedIds[key];
+      this._taskIdToKey.delete(taskId);
+    },
+
+    commit(registryPath) {
+      // 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;
+      }
+      try {
+        writeRegistryAtomic(this._registry, registryPath);
+      } catch (e) {
+        this._registry.ids = this._registrySnapshot;
+        throw new Error(`Failed to persist registry to ${registryPath}: ${e.message}`);
+      }
+    }
+  };
+
+  return tx;
+}
+
+function verifyRegistry(registry, activeDir) {
+  const activeTaskIds = new Set(
+    fs
+      .readdirSync(activeDir)
+      .filter((d) => TASK_ID_RE.test(d))
+      .filter((d) => fs.existsSync(path.join(activeDir, d, "task.md")))
+  );
+  const registryTaskIds = new Set(Object.values(registry.ids));
+  const missing_in_registry = [];
+  for (const taskId of activeTaskIds) {
+    if (!registryTaskIds.has(taskId)) {
+      missing_in_registry.push({ taskId });
+    }
+  }
+  const orphans_in_registry = [];
+  for (const [key, taskId] of Object.entries(registry.ids)) {
+    if (!activeTaskIds.has(taskId)) {
+      orphans_in_registry.push({ key: `#${key}`, taskId });
+    }
+  }
+  const taskIdToKeys = new Map();
+  for (const [key, taskId] of Object.entries(registry.ids)) {
+    if (!taskIdToKeys.has(taskId)) taskIdToKeys.set(taskId, []);
+    taskIdToKeys.get(taskId).push(key);
+  }
+  const duplicate_registry_keys = [];
+  for (const [taskId, keys] of taskIdToKeys) {
+    if (keys.length > 1) {
+      duplicate_registry_keys.push({ taskId, keys: keys.map((k) => `#${k}`) });
+    }
+  }
+  return {
+    missing_in_registry,
+    orphans_in_registry,
+    duplicate_registry_keys
+  };
+}
+
+function cmdAlloc(taskId, activeDir, registryPath, shortIdLength) {
+  if (!TASK_ID_RE.test(taskId)) {
+    writeStderr(`Error: invalid task id format '${taskId}'\n`);
+    process.exit(1);
+  }
+  return withRegistryLock(activeDir, () => {
+    const taskMdPath = path.join(activeDir, taskId, "task.md");
+    if (!fs.existsSync(taskMdPath)) {
+      writeStderr(`Error: task ${taskId} not found in ${activeDir} (no task.md)\n`);
+      process.exit(1);
+    }
+    const registry = readRegistry(registryPath);
+    const tx = planTransaction(registry, activeDir, shortIdLength);
+    let shortId;
+    try {
+      shortId = tx.planAlloc(taskId);
+    } catch (e) {
+      writeStderr(`${e.message}\n`);
+      process.exit(2);
+    }
+    try {
+      tx.commit(registryPath);
+    } catch (e) {
+      writeStderr(`${e.message}\n`);
+      process.exit(1);
+    }
+    // shortId is already zero-padded (returned by tx.planAlloc; matches registry key)
+    writeStdout(`#${shortId}\n`);
+  });
+}
+
+function cmdRelease(taskId, activeDir, registryPath, shortIdLength) {
+  if (!TASK_ID_RE.test(taskId)) {
+    writeStderr(`Error: invalid task id format '${taskId}'\n`);
+    process.exit(1);
+  }
+  return withRegistryLock(activeDir, () => {
+    const registry = readRegistry(registryPath);
+    const tx = planTransaction(registry, activeDir, shortIdLength);
+    tx.planRelease(taskId);
+    try {
+      tx.commit(registryPath);
+    } catch (e) {
+      writeStderr(`${e.message}\n`);
+      process.exit(1);
+    }
+    // idempotent exit 0
+  });
+}
+
+function cmdResolve(shortIdArg, activeDir, registryPath, shortIdLength) {
+  // 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);
+    const tx = planTransaction(registry, activeDir, shortIdLength);
+    const taskId = tx._projectedIds[key];
+    if (!taskId) {
+      const hasPendingMutations =
+        tx._plannedRegistryWrites.length > 0 ||
+        tx._pendingRegistryDeletes.length > 0;
+      if (hasPendingMutations) {
+        try {
+          tx.commit(registryPath);
+        } catch (e) {
+          writeStderr(`${e.message}\n`);
+          process.exit(1);
+        }
+      }
+      if (Object.keys(tx._projectedIds).length === 0) {
+        writeStderr(
+          `Error: short id '#${key}' not found; active task registry is empty.\n`
+        );
+      } else {
+        writeStderr(
+          `Error: short id '#${key}' not found in active task registry ` +
+            `(it may have been cleaned up after archival; check 'task-short-id.js list').\n`
+        );
+      }
+      process.exit(1);
+    }
+    try {
+      tx.commit(registryPath);
+    } catch (e) {
+      writeStderr(`${e.message}\n`);
+      process.exit(1);
+    }
+    writeStdout(`${taskId}\n`);
+  });
+}
+
+function cmdList(activeDir, registryPath, verify) {
+  if (!verify) {
+    const registry = readRegistry(registryPath);
+    writeStdout(`${JSON.stringify(registry, null, 2)}\n`);
+    return;
+  }
+  const registry = readRegistry(registryPath);
+  if (!fs.existsSync(activeDir)) {
+    writeStdout("");
+    return;
+  }
+  const diff = verifyRegistry(registry, activeDir);
+  const hasIssues =
+    diff.missing_in_registry.length > 0 ||
+    diff.orphans_in_registry.length > 0 ||
+    diff.duplicate_registry_keys.length > 0;
+  if (hasIssues) {
+    writeStdout(`${JSON.stringify(diff, null, 2)}\n`);
+    process.exit(1);
+  }
+  // consistent: empty stdout, exit 0
+}
+
+function main(argv) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    writeStderr(`${e.message}\n${usage()}\n`);
+    process.exit(1);
+  }
+  if (args.help || args.positional.length === 0) {
+    writeStdout(`${usage()}\n`);
+    return;
+  }
+  const subcommand = args.positional[0];
+  const repoRoot = findRepoRoot(process.cwd());
+  const activeDir = args.activeDir
+    ? path.resolve(args.activeDir)
+    : repoRoot
+    ? path.join(repoRoot, ".agents", "workspace", "active")
+    : null;
+  if (!activeDir) {
+    writeStderr(
+      `Error: cannot locate active dir (no .agents/.airc.json found above ${process.cwd()})\n`
+    );
+    process.exit(2);
+  }
+  const shortIdLength = readShortIdLength(repoRoot, args.shortIdLength);
+  const registryPath = path.join(activeDir, REGISTRY_NAME);
+
+  switch (subcommand) {
+    case "alloc":
+      if (!args.positional[1]) {
+        writeStderr(`Usage: alloc <task-id>\n`);
+        process.exit(1);
+      }
+      return cmdAlloc(args.positional[1], activeDir, registryPath, shortIdLength);
+    case "release":
+      if (!args.positional[1]) {
+        writeStderr(`Usage: release <task-id>\n`);
+        process.exit(1);
+      }
+      return cmdRelease(args.positional[1], activeDir, registryPath, shortIdLength);
+    case "resolve":
+      if (!args.positional[1]) {
+        writeStderr(`Usage: resolve <#N>\n`);
+        process.exit(1);
+      }
+      return cmdResolve(args.positional[1], activeDir, registryPath, shortIdLength);
+    case "list":
+      return cmdList(activeDir, registryPath, args.verify);
+    default:
+      writeStderr(`Unknown subcommand: ${subcommand}\n${usage()}\n`);
+      process.exit(1);
+  }
+}
+
+// Compare canonicalized (symlink-resolved) paths so this script still runs as a
+// CLI when invoked through a temp-dir symlink (notably /var/folders on macOS,
+// which is a symlink to /private/var/folders; process.argv[1] keeps the
+// symlinked path while import.meta.url is auto-resolved to the realpath).
+const isCli = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const realEntry = fs.realpathSync(entry);
+    const realModule = fs.realpathSync(fileURLToPath(import.meta.url));
+    return realEntry === realModule;
+  } catch {
+    return false;
+  }
+})();
+
+if (isCli) {
+  main(process.argv.slice(2));
+}
+
+export {
+  TASK_ID_RE,
+  SHORT_ID_RE,
+  REGISTRY_NAME,
+  parseArgs,
+  findRepoRoot,
+  readShortIdLength,
+  readRegistry,
+  writeRegistryAtomic,
+  withRegistryLock,
+  padShortId,
+  parseShortIdArg,
+  allocateMinFreeInt,
+  planTransaction,
+  verifyRegistry,
+  cmdAlloc,
+  cmdRelease,
+  cmdResolve,
+  cmdList,
+  main
+};

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

@@ -27,6 +27,10 @@ tail .agents/workspace/active/{task-id}/task.md
 
 Before the state check is complete, do not make external-state assertions such as "the code is unchanged", "tests passed", or "there are no other references", including in reasoning. This gate is only a structural floor; evidence pairing and authenticity still require the report template and review discipline.
 
+## Task id short ref
+
+> 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
 
 ### 1. Verify Prerequisites
@@ -61,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.
@@ -150,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):
@@ -187,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 "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
 
 Output format:
 ```
@@ -202,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

@@ -27,8 +27,11 @@ tail .agents/workspace/active/{task-id}/task.md
 
 状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。
 
-## 执行步骤
+## 任务入参短号别名
+
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 执行步骤
 ### 1. 验证前置条件
 
 检查必要文件：
@@ -61,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`。
@@ -150,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`，执行以下同步操作（任一失败则跳过并继续）：
@@ -187,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`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
 
 输出格式：
 ```
@@ -202,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": {