@fitlab-ai/agent-infra 0.7.3 → 0.7.4

package/lib/task/resolve-ref.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { normalizeShortIdInput } from './short-id.ts';
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+// Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
+// Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.
+const FLAT_WORKSPACE_DIRS = ['active', 'blocked', 'completed'] as const;
+
+type ResolveRefResult =
+  | {
+      ok: true;
+      repoRoot: string;
+      taskId: string;
+      taskDir: string;
+      taskMdPath: string;
+    }
+  | { ok: false; message: string };
+
+function detectRepoRoot(): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    throw new Error('ai task: current directory is not inside a git repository');
+  }
+}
+
+function readShortIdLength(repoRoot: string): number {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+    const v = cfg?.task?.shortIdLength;
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 1) return v;
+  } catch {
+    // fall through to default
+  }
+  return 2;
+}
+
+function resolveShortIdToTaskId(arg: string, repoRoot: string): string {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(`task-short-id.js not found at ${scriptPath}`);
+  }
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], {
+    encoding: 'utf8',
+    cwd: repoRoot
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || '').trim() || `failed to resolve '${arg}'`);
+  }
+  return result.stdout.trim();
+}
+
+function listSortedNumeric(dir: string, width: number): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const pattern = new RegExp(`^\\d{${width}}$`);
+  return fs
+    .readdirSync(dir)
+    .filter((entry) => pattern.test(entry))
+    .sort()
+    .reverse();
+}
+
+function findInArchive(repoRoot: string, taskId: string): string | null {
+  // archive-tasks SKILL writes to .agents/workspace/archive/YYYY/MM/DD/{taskId}/task.md
+  // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
+  // the task id's creation date. So we cannot derive the path from taskId alone;
+  // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
+  const archiveDir = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  for (const year of listSortedNumeric(archiveDir, 4)) {
+    const yearDir = path.join(archiveDir, year);
+    for (const month of listSortedNumeric(yearDir, 2)) {
+      const monthDir = path.join(yearDir, month);
+      for (const day of listSortedNumeric(monthDir, 2)) {
+        const candidate = path.join(monthDir, day, taskId, 'task.md');
+        if (fs.existsSync(candidate)) return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+function findTaskMd(repoRoot: string, taskId: string): string | null {
+  for (const sub of FLAT_WORKSPACE_DIRS) {
+    const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return findInArchive(repoRoot, taskId);
+}
+
+/**
+ * Enumerate every task directory under the flat workspace states
+ * (active / blocked / completed) — archive is intentionally excluded so a
+ * full-tree scan never pulls in cold data. Ordered by state, then task id
+ * ascending, giving callers a deterministic traversal.
+ */
+function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string }[] {
+  const out: { taskId: string; taskDir: string }[] = [];
+  for (const sub of FLAT_WORKSPACE_DIRS) {
+    const base = path.join(repoRoot, '.agents', 'workspace', sub);
+    if (!fs.existsSync(base)) continue;
+    for (const entry of fs.readdirSync(base).sort()) {
+      if (!TASK_ID_RE.test(entry)) continue;
+      const taskDir = path.join(base, entry);
+      if (!fs.existsSync(path.join(taskDir, 'task.md'))) continue;
+      out.push({ taskId: entry, taskDir });
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve a task ref (bare short id, `#N`, or `TASK-YYYYMMDD-HHMMSS`) to its
+ * task directory across active / blocked / completed / archive.
+ *
+ * The returned `message` on failure is command-agnostic (no `ai task <cmd>:`
+ * prefix); callers prepend their own prefix so each command keeps its existing
+ * stderr wording byte-for-byte.
+ */
+function resolveTaskRef(arg: string): ResolveRefResult {
+  const repoRoot = detectRepoRoot();
+  let taskId: string;
+  if (TASK_ID_RE.test(arg)) {
+    taskId = arg;
+  } else {
+    const shortIdLength = readShortIdLength(repoRoot);
+    const normalized = normalizeShortIdInput(arg, { shortIdLength });
+    if (normalized.kind === 'error') {
+      return { ok: false, message: normalized.message };
+    }
+    if (normalized.kind === 'pass') {
+      return {
+        ok: false,
+        message:
+          `'${arg}' is not a valid short id or TASK-id; ` +
+          `expected bare digits, '#N', or 'TASK-YYYYMMDD-HHMMSS'`
+      };
+    }
+    try {
+      taskId = resolveShortIdToTaskId(normalized.value, repoRoot);
+    } catch (e) {
+      return { ok: false, message: (e as Error).message };
+    }
+  }
+  const taskMdPath = findTaskMd(repoRoot, taskId);
+  if (!taskMdPath) {
+    return {
+      ok: false,
+      message: `task ${taskId} not found in active / blocked / completed / archive`
+    };
+  }
+  return { ok: true, repoRoot, taskId, taskDir: path.dirname(taskMdPath), taskMdPath };
+}
+
+export { resolveTaskRef, detectRepoRoot, enumerateTaskDirs, TASK_ID_RE };
+export type { ResolveRefResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "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/README.en.md

@@ -34,6 +34,7 @@ This dual-config approach ensures every AI tool receives appropriate project con
     bug-fix.yaml                # Bug fix workflow
     code-review.yaml            # Code review workflow
     refactoring.yaml            # Refactoring workflow
+  rules/                        # Collaboration rule index (see rules/README.md)
   workspace/                    # Runtime workspace (git-ignored)
     active/                     # Currently active tasks
     blocked/                    # Blocked tasks

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

@@ -34,6 +34,7 @@
     bug-fix.yaml                # 缺陷修复工作流
     code-review.yaml            # 代码审查工作流
     refactoring.yaml            # 重构工作流
+  rules/                        # 协作规则索引（见 rules/README.md）
   workspace/                    # 运行时工作区（已被 git ignore）
     active/                     # 当前活跃任务
     blocked/                    # 被阻塞的任务

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

@@ -0,0 +1,41 @@
+# Rules Index
+
+`.agents/rules/` holds every collaboration rule in this project. Each SKILL loads the
+relevant few on demand; this index groups all rules by domain with a one-line purpose,
+so you can quickly find "which ones to read" without opening each file.
+
+> Maintenance note: when adding or removing `.agents/rules/*.md`, update this index too.
+
+## General Principles
+
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Silence during SKILL runs: no user questions by default, plus two exceptions.
+- [`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.
+
+## Issue / PR
+
+- [`issue-pr-commands.md`](issue-pr-commands.md) — GitHub commands to verify auth and read/write Issues / PRs.
+- [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch PR required checks and pull failure logs (`watch-pr`).
+- [`create-issue.md`](create-issue.md) — Cascading Issue creation after `create-task` writes `task.md`.
+- [`issue-sync.md`](issue-sync.md) — Sync markers and flow for task artifacts ↔ Issue comments / labels / fields.
+- [`issue-fields.md`](issue-fields.md) — Read/write flow for Issue Type pinned fields (Priority/Effort/dates).
+- [`pr-sync.md`](pr-sync.md) — Sync rule for the single reviewer-facing PR summary comment.
+
+## Task Workflow
+
+- [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
+- [`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.
+- [`security-alerts.md`](security-alerts.md) — Commands to import / close Dependabot and Code Scanning alerts.
+
+## Commit & Release
+
+- [`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-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()`.

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

@@ -0,0 +1,40 @@
+# 规则索引
+
+`.agents/rules/` 收录本项目所有协作规则。各 SKILL 执行时按需加载其中若干篇；
+本索引按业务域列出全部规则及其用途，便于快速定位「该读哪几篇」，无需逐文件翻阅。
+
+> 维护提醒：新增或删除 `.agents/rules/*.md` 时，请同步更新本索引。
+
+## 通用准则
+
+- [`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) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
+
+## Issue / PR
+
+- [`issue-pr-commands.md`](issue-pr-commands.md) — 验证平台认证、读写 Issue / PR 的 GitHub 命令集。
+- [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR required checks、拉取失败日志的命令集（`watch-pr`）。
+- [`create-issue.md`](create-issue.md) — `create-task` 落盘后级联创建 Issue 的规则。
+- [`issue-sync.md`](issue-sync.md) — task 产物与 Issue 评论 / 标签 / 字段的同步标记与流程。
+- [`issue-fields.md`](issue-fields.md) — Issue Type pinned 字段（Priority/Effort/日期）的读写流程。
+- [`pr-sync.md`](pr-sync.md) — 面向 reviewer 的唯一 PR 摘要评论的同步规则。
+
+## 任务工作流
+
+- [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
+- [`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 的平台命令集。
+- [`security-alerts.md`](security-alerts.md) — 导入 / 关闭 Dependabot 与 Code Scanning 告警的命令集。
+
+## 提交与发布
+
+- [`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()` 表达平台跳过。

package/templates/.agents/rules/debugging-guide.en.md

@@ -0,0 +1,25 @@
+# General Rule - Structured Debugging Guide
+
+> This file defines the structured triage flow for "test failure / behavior not as expected"; SKILLs that modify code in response to failures (e.g. `code-task`, `watch-pr`) load it on demand before attempting a fix.
+
+## Triggers
+
+When any of the following happens, run this flow before changing code:
+
+- A test fails, or a build / type-check / lint error appears
+- Runtime behavior differs from expectations (output, state, or side effects)
+
+## Core Anti-pattern: No Blind Patch-and-Retry
+
+The "tweak one spot → rerun → still broken → guess another spot" loop hides the real root cause, introduces new defects, and wastes time. A change with no supporting evidence is not a fix.
+
+## Four-phase Flow
+
+1. **Gather evidence**: Read the full error message and stack trace (not just the last line) and pinpoint where it fails; reproduce minimally when needed, and record "actual vs expected behavior".
+2. **Form a hypothesis**: From the evidence, propose a root-cause hypothesis that explains **all** the symptoms rather than a surface symptom; if there are several, rank them by likelihood and testability.
+3. **Verify the hypothesis**: Before changing anything, confirm the hypothesis cheaply—add logging, add a breakpoint, shrink the input, or write a failing test that reproduces it; if it is disproven, return to phase 2.
+4. **Fix the root cause**: Change only the verified root cause (not the symptom), then rerun the relevant tests to confirm they pass; if they still fail, return to phase 1 with the new evidence instead of trial-and-error without evidence.
+
+## Relation to Project Principles
+
+This flow is the debugging-specific form of AGENTS.md's "Think Before Coding" and "Goal-Driven Execution": pin the problem with a reproducible failing case first, then make the fix turn it green.

package/templates/.agents/rules/debugging-guide.zh-CN.md

@@ -0,0 +1,25 @@
+# 通用规则 - 结构化调试指导
+
+> 本文件定义「测试失败 / 行为不符合预期」时的结构化排查流程；`code-task`、`watch-pr` 等会因失败而修改代码的 SKILL 在动手修复前按需加载。
+
+## 触发条件
+
+出现以下任一情况时，先按本流程排查，再改代码：
+
+- 测试失败，或构建 / 类型检查 / lint 报错
+- 运行结果与预期不符（输出、状态或副作用异常）
+
+## 核心反模式：禁止盲目改代码重试
+
+「改一处 → 重跑 → 还错 → 再猜一处」的循环会掩盖真实根因、引入新缺陷、浪费时间。没有证据支撑的修改不算修复。
+
+## 四阶段流程
+
+1. **收集证据**：完整读取错误信息与堆栈（不要只看最后一行），定位失败的具体位置；必要时最小化复现，记录「实际行为 vs 预期行为」。
+2. **形成假设**：基于证据提出能解释**全部**现象的根因假设，而不是停留在表层症状；若有多个假设，按可能性与可验证性排序。
+3. **验证假设**：动手改之前，用最小代价确认假设成立——加日志、加断点、缩小输入，或写一个能复现的失败用例；假设被证伪就回到阶段 2。
+4. **修复根因**：只针对已验证的根因修改（而非症状），改完重跑相关测试确认通过；仍失败则带着新证据回到阶段 1，不在无证据时反复试错。
+
+## 与项目准则的关系
+
+本流程是 AGENTS.md「先思考再动手」「目标驱动执行」在调试场景的具体化：先用可复现的失败用例锁定问题，再让修复使其通过。

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

@@ -88,6 +88,8 @@ Follow the plan in order.
 
 Use the project test commands from the `test` skill and iterate until all required tests pass.
 
+When triaging a test failure or unexpected behavior, first read `.agents/rules/debugging-guide.md` and locate the root cause via its four-phase flow; do not blindly patch and retry.
+
 ### 9. Write the Code Report
 
 Create `.agents/workspace/active/{task-id}/{code-artifact}`.

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

@@ -130,6 +130,8 @@ echo "$result"
 
 如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。
 
+排查测试失败或行为不符合预期时，先读取 `.agents/rules/debugging-guide.md`，按其四阶段流程定位根因，禁止盲目改代码重试。
+
 ### 9. 编写实现报告
 
 创建 `.agents/workspace/active/{task-id}/{code-artifact}`。

package/templates/.agents/skills/watch-pr/SKILL.en.md

@@ -42,7 +42,7 @@ Using the watch command in `.agents/rules/pr-checks-commands.md`, poll `{pr#}`'s
 
 Before running this step, read the "Self-Heal Decision Tree" of `reference/monitor-and-heal.md` and "Resolve a Failing Run id and Pull Logs" of `.agents/rules/pr-checks-commands.md`.
 
-For a failing check: first deterministically resolve its failing run and pull the failure logs per the rule, then classify the failure; only when it is a locatable code-layer failure, make a minimal local fix, run the relevant tests until they pass, then **stage, commit, and push the fix** (`git add` only the related files → `git commit` per `.agents/rules/commit-and-pr.md` → `git push` to the current PR branch, recording the commit SHA), and return to step 2 to re-watch. Count fix attempts; on reaching the hard cap (default 2) or when the run is unlocatable, go to step 4.
+For a failing check: first deterministically resolve its failing run and pull the failure logs per the rule, then classify the failure; before making any local fix, read `.agents/rules/debugging-guide.md` and locate the root cause via its four-phase flow, never blindly patching and retrying; only when it is a locatable code-layer failure, make a minimal local fix, run the relevant tests until they pass, then **stage, commit, and push the fix** (`git add` only the related files → `git commit` per `.agents/rules/commit-and-pr.md` → `git push` to the current PR branch, recording the commit SHA), and return to step 2 to re-watch. Count fix attempts; on reaching the hard cap (default 2) or when the run is unlocatable, go to step 4.
 
 ### 4. Help Exit (Produce-Then-Stop)
 

package/templates/.agents/skills/watch-pr/SKILL.zh-CN.md

@@ -42,7 +42,7 @@ description: "监控 PR 的 required checks 并在失败时自愈"
 
 执行此步骤前，先读取 `reference/monitor-and-heal.md` 的「自愈决策树」与 `.agents/rules/pr-checks-commands.md` 的「解析失败 run id 并拉日志」。
 
-对失败 check：先按规则确定性解析其失败 run 并拉取失败日志、判定失败类别；仅当属可定位的代码层失败时，本地最小化修复、运行对应测试通过后**暂存并提交本次修复再推送**（`git add` 仅相关文件 → 按 `.agents/rules/commit-and-pr.md` `git commit` → `git push` 到当前 PR 分支，并记录 commit SHA），再回到步骤 2 重新监控。修复尝试计数，达硬上限（默认 2）或 run 不可定位 → 转步骤 4。
+对失败 check：先按规则确定性解析其失败 run 并拉取失败日志、判定失败类别；本地修复前先读取 `.agents/rules/debugging-guide.md`，按其四阶段流程定位根因，禁止盲目改代码重试；仅当属可定位的代码层失败时，本地最小化修复、运行对应测试通过后**暂存并提交本次修复再推送**（`git add` 仅相关文件 → 按 `.agents/rules/commit-and-pr.md` `git commit` → `git push` 到当前 PR 分支，并记录 commit SHA），再回到步骤 2 重新监控。修复尝试计数，达硬上限（默认 2）或 run 不可定位 → 转步骤 4。
 
 ### 4. 求助出口（产出后停止）