@fitlab-ai/agent-infra 0.7.3 → 0.7.5

package/lib/task/commands/status.ts

@@ -0,0 +1,302 @@
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolveTaskRef } from '../resolve-ref.ts';
+import { enumerateArtifacts, type Artifact } from '../artifacts.ts';
+import { parseTaskFrontmatter, extractTitle, type Frontmatter } from '../frontmatter.ts';
+import { loadShortIdByTaskId } from '../short-id.ts';
+
+const USAGE = `Usage: ai task status <N | #N | TASK-id>
+
+Prints an aggregated "health check" view for a task: header, metadata, an
+artifacts summary, git branch state, and best-effort GitHub issue/PR status.
+  <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+
+Git and Platform rows are best-effort: a failed git/gh call degrades that row to
+'-' without failing the command.
+`;
+
+const DASH = '-';
+
+// Subprocess boundary: the single place this command shells out. Injectable so
+// the collectors below can be unit-tested without spawning git/gh. Returns the
+// command's stdout; throws (like execFileSync) on a non-zero exit or spawn error.
+type Runner = (file: string, args: string[]) => string;
+
+function makeRunner(cwd: string): Runner {
+  return (file, args) =>
+    execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+// Run `run` and swallow any failure into null, so a single failing git/gh call
+// degrades only its own field instead of aborting the whole view.
+function tryRun(run: Runner, file: string, args: string[]): string | null {
+  try {
+    return run(file, args);
+  } catch {
+    return null;
+  }
+}
+
+// Frontmatter keys shown in the Metadata section, in a fixed display order.
+const METADATA_KEYS = [
+  'type',
+  'status',
+  'current_step',
+  'priority',
+  'effort',
+  'branch',
+  'assigned_to',
+  'created_at',
+  'updated_at',
+  'issue_number',
+  'pr_status'
+] as const;
+
+function collectMetadata(fm: Frontmatter): [string, string][] {
+  return METADATA_KEYS.map((key) => [key, fm[key] ? fm[key]! : DASH]);
+}
+
+// Workflow stages in timeline order; artifacts are bucketed by filename prefix.
+// `review-*` prefixes are matched before their bare counterparts so that, e.g.,
+// `review-analysis.md` is never swallowed by the `analysis` bucket.
+const STAGE_ORDER = [
+  'analysis',
+  'review-analysis',
+  'plan',
+  'review-plan',
+  'code',
+  'review-code',
+  'task',
+  'other'
+] as const;
+
+function stageOf(name: string): string {
+  const stem = name.replace(/\.md$/, '');
+  if (stem === 'task') return 'task';
+  if (stem.startsWith('review-analysis')) return 'review-analysis';
+  if (stem.startsWith('review-plan')) return 'review-plan';
+  if (stem.startsWith('review-code')) return 'review-code';
+  if (stem.startsWith('analysis')) return 'analysis';
+  if (stem.startsWith('plan')) return 'plan';
+  if (stem.startsWith('code')) return 'code';
+  return 'other';
+}
+
+// Group artifacts by workflow stage, preserving the input order (mtime ascending
+// from enumerateArtifacts) within each stage and dropping empty stages.
+function groupArtifacts(artifacts: Artifact[]): { stage: string; files: string[] }[] {
+  const byStage = new Map<string, string[]>();
+  for (const artifact of artifacts) {
+    const stage = stageOf(artifact.name);
+    const bucket = byStage.get(stage);
+    if (bucket) bucket.push(artifact.name);
+    else byStage.set(stage, [artifact.name]);
+  }
+  const groups: { stage: string; files: string[] }[] = [];
+  for (const stage of STAGE_ORDER) {
+    const files = byStage.get(stage);
+    if (files && files.length > 0) groups.push({ stage, files });
+  }
+  return groups;
+}
+
+type GitInfo = {
+  current: string;
+  frontmatter: string;
+  match: string;
+  exists: string;
+  uncommitted: string;
+  aheadBehind: string;
+};
+
+// `frontmatterBranch` is the task.md `branch` field (caller passes '' when absent).
+// It is read straight from frontmatter and never depends on a subprocess, so it
+// keeps its value even when every git call fails. All other fields degrade to '-'
+// on failure of their own command.
+function collectGit(frontmatterBranch: string, run: Runner): GitInfo {
+  const frontmatter = frontmatterBranch ? frontmatterBranch : DASH;
+
+  let current = DASH;
+  const cur = tryRun(run, 'git', ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (cur !== null && cur.trim()) current = cur.trim();
+
+  let match = DASH;
+  if (current !== DASH && frontmatter !== DASH) {
+    match = current === frontmatter ? 'yes' : 'no';
+  }
+
+  let exists = DASH;
+  if (frontmatter !== DASH) {
+    const verified = tryRun(run, 'git', ['rev-parse', '--verify', '--quiet', `refs/heads/${frontmatter}`]);
+    exists = verified === null ? 'no' : 'yes';
+  }
+
+  let uncommitted = DASH;
+  const porcelain = tryRun(run, 'git', ['status', '--porcelain']);
+  if (porcelain !== null) {
+    const changed = porcelain.split('\n').filter((line) => line.trim() !== '');
+    uncommitted = changed.length === 0 ? 'clean' : `${changed.length} file(s)`;
+  }
+
+  let aheadBehind = DASH;
+  if (frontmatter !== DASH) {
+    const counts = tryRun(run, 'git', [
+      'rev-list',
+      '--left-right',
+      '--count',
+      `${frontmatter}...${frontmatter}@{upstream}`
+    ]);
+    if (counts !== null) {
+      const parts = counts.trim().split(/\s+/);
+      if (parts.length === 2) aheadBehind = `${parts[0]} ahead / ${parts[1]} behind`;
+    }
+  }
+
+  return { current, frontmatter, match, exists, uncommitted, aheadBehind };
+}
+
+type PlatformInfo = { issue: string; pr: string };
+
+function collectPlatform(fm: Frontmatter, run: Runner): PlatformInfo {
+  let issue = DASH;
+  if (fm.issue_number && /^\d+$/.test(fm.issue_number)) {
+    const out = tryRun(run, 'gh', ['issue', 'view', fm.issue_number, '--json', 'state,labels']);
+    if (out !== null) {
+      try {
+        const data = JSON.parse(out);
+        const labels = Array.isArray(data.labels)
+          ? data.labels.map((label: { name: string }) => label.name).join(', ')
+          : '';
+        issue = labels ? `${data.state} [${labels}]` : `${data.state}`;
+      } catch {
+        issue = DASH;
+      }
+    }
+  }
+
+  let pr = DASH;
+  if (fm.pr_status === 'created' && fm.pr_number && /^\d+$/.test(fm.pr_number)) {
+    const out = tryRun(run, 'gh', ['pr', 'view', fm.pr_number, '--json', 'state,statusCheckRollup']);
+    if (out !== null) {
+      try {
+        const data = JSON.parse(out);
+        const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
+        const passed = rollup.filter(
+          (check: { conclusion?: string; state?: string }) =>
+            check.conclusion === 'SUCCESS' || check.state === 'SUCCESS'
+        ).length;
+        pr = rollup.length > 0 ? `${data.state}, checks: ${passed}/${rollup.length}` : `${data.state}`;
+      } catch {
+        pr = DASH;
+      }
+    }
+  }
+
+  return { issue, pr };
+}
+
+type StatusModel = {
+  taskId: string;
+  shortId: string;
+  title: string;
+  issueNumber: string;
+  metadata: [string, string][];
+  artifacts: { count: number; groups: { stage: string; files: string[] }[] };
+  git: GitInfo;
+  platform: PlatformInfo;
+};
+
+// Indent each label/value pair by two spaces and pad labels to a common width so
+// every section reads as an aligned "key   value" block.
+function renderPairs(rows: [string, string][]): string[] {
+  const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
+  return rows.map(([label, value]) => `  ${label.padEnd(width)}  ${value}`.trimEnd());
+}
+
+function renderStatus(model: StatusModel): string[] {
+  const lines: string[] = [];
+
+  lines.push(`Task ${model.taskId}  (${model.shortId})`);
+  if (model.title) lines.push(model.title);
+
+  lines.push('', 'Metadata', ...renderPairs(model.metadata));
+
+  lines.push('', `Artifacts (${model.artifacts.count})`);
+  if (model.artifacts.groups.length === 0) {
+    lines.push('  (none)');
+  } else {
+    lines.push(...renderPairs(model.artifacts.groups.map((group) => [group.stage, group.files.join(', ')])));
+  }
+
+  lines.push(
+    '',
+    'Git',
+    ...renderPairs([
+      ['current', model.git.current],
+      ['frontmatter', model.git.frontmatter],
+      ['match', model.git.match],
+      ['exists', model.git.exists],
+      ['uncommitted', model.git.uncommitted],
+      ['ahead/behind', model.git.aheadBehind]
+    ])
+  );
+
+  const issueLabel = model.issueNumber ? `issue #${model.issueNumber}` : 'issue';
+  lines.push(
+    '',
+    'Platform',
+    ...renderPairs([
+      [issueLabel, model.platform.issue],
+      ['pr', model.platform.pr]
+    ])
+  );
+
+  return lines;
+}
+
+function status(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    if (args.length === 0) process.exitCode = 1;
+    return;
+  }
+
+  const resolved = resolveTaskRef(args[0]!);
+  if (!resolved.ok) {
+    process.stderr.write(`ai task status: ${resolved.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const fm = parseTaskFrontmatter(content);
+  const run = makeRunner(resolved.repoRoot);
+  const artifacts = enumerateArtifacts(resolved.taskDir);
+
+  const model: StatusModel = {
+    taskId: resolved.taskId,
+    shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
+    title: extractTitle(content),
+    issueNumber: fm.issue_number && /^\d+$/.test(fm.issue_number) ? fm.issue_number : '',
+    metadata: collectMetadata(fm),
+    artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
+    git: collectGit(fm.branch ?? '', run),
+    platform: collectPlatform(fm, run)
+  };
+
+  for (const line of renderStatus(model)) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+export {
+  status,
+  makeRunner,
+  collectMetadata,
+  groupArtifacts,
+  collectGit,
+  collectPlatform,
+  renderStatus,
+  METADATA_KEYS
+};
+export type { Runner, GitInfo, PlatformInfo, StatusModel };

package/lib/task/index.ts

@@ -1,13 +1,25 @@
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
+  cat <ref> <artifact | N>               Print a task artifact (by name or number)
+  files <ref>                            List artifacts in a task dir (numbered)
+  grep <pattern> [ref] [artifact | N]    Literal search across task artifacts (omit ref to scan all)
+  log <ref>                              Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
   show <N | #N | TASK-id>                Print a task.md
+  status <ref>                           Aggregated status view (metadata / artifacts / git / platform)
 
 Examples:
+  ai task cat 11 analysis
+  ai task cat 11 3
+  ai task files 11
+  ai task grep resolveArtifact
+  ai task grep resolveArtifact 11
+  ai task log 11
   ai task ls
   ai task show 11
   ai task show TASK-20260612-162737
+  ai task status 11
 
 Run 'ai task <command> --help' for details.`;
 
@@ -26,6 +38,26 @@ export async function runTask(args: string[]): Promise<void> {
   }
 
   switch (subcommand) {
+    case 'cat': {
+      const { cat } = await import('./commands/cat.ts');
+      cat(rest);
+      break;
+    }
+    case 'files': {
+      const { files } = await import('./commands/files.ts');
+      files(rest);
+      break;
+    }
+    case 'grep': {
+      const { grep } = await import('./commands/grep.ts');
+      grep(rest);
+      break;
+    }
+    case 'log': {
+      const { log } = await import('./commands/log.ts');
+      log(rest);
+      break;
+    }
     case 'ls': {
       const { ls } = await import('./commands/ls.ts');
       ls(rest);
@@ -36,6 +68,11 @@ export async function runTask(args: string[]): Promise<void> {
       show(rest);
       break;
     }
+    case 'status': {
+      const { status } = await import('./commands/status.ts');
+      status(rest);
+      break;
+    }
     default:
       process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
       process.stdout.write(`${USAGE}\n`);

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/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.3",
+  "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/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,45 @@
+# 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 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.
+
+## 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.
+- [`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.
+- [`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
+
+- [`testing-discipline.md`](testing-discipline.md) — Test-writing discipline: prefer structural asserts, no brittle wording matches.
+
+## 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

@@ -0,0 +1,44 @@
+# 规则索引
+
+`.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) — 任务语义识别与工作流命令映射。
+- [`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 的平台命令集。
+- [`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) — 测试编写纪律：结构性断言优先，禁止脆弱的措辞匹配。
+
+## CLI
+
+- [`cli-help-format.md`](cli-help-format.md) — CLI help 文案约定：展示名统一 `ai`、`Usage:`+`Commands:` 结构、命令按字母序（仅顶层与命名空间级 help）。