@fitlab-ai/agent-infra 0.4.5 → 0.5.1

package/lib/update.js

@@ -139,9 +139,15 @@ async function cmdUpdate() {
   // sync file registry
   const { added, changed } = syncFileRegistry(config);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
+  const sandboxAdded = !config.sandbox;
   const labelsAdded = !config.labels;
   let configChanged = changed;
 
+  if (sandboxAdded) {
+    config.sandbox = structuredClone(defaults.sandbox);
+    configChanged = true;
+  }
+
   if (labelsAdded) {
     config.labels = structuredClone(defaults.labels);
     configChanged = true;
@@ -157,11 +163,19 @@ async function cmdUpdate() {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (labelsAdded) {
-      info(`Default labels.in config added to ${CONFIG_PATH}.`);
+    } else if (sandboxAdded || labelsAdded) {
+      if (sandboxAdded) {
+        info(`Default sandbox config added to ${CONFIG_PATH}.`);
+      }
+      if (labelsAdded) {
+        info(`Default labels.in config added to ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && sandboxAdded) {
+      info(`Default sandbox config added to ${CONFIG_PATH}.`);
+    }
     if (hasNewEntries && labelsAdded) {
       info(`Default labels.in config added to ${CONFIG_PATH}.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,10 @@
     "bootstrap",
     "installer"
   ],
+  "dependencies": {
+    "@clack/prompts": "1.2.0",
+    "picocolors": "1.1.1"
+  },
   "scripts": {
     "build": "node scripts/build-inline.js",
     "prepare": "git config core.hooksPath .github/hooks || true",

package/templates/.agents/rules/pr-sync.md

@@ -0,0 +1,110 @@
+# PR Summary Sync
+
+Read this file before syncing the single reviewer-facing PR summary comment.
+
+## Scope
+
+Current callers:
+- `create-pr`: create or update the summary comment when the PR is opened
+- `commit`: refresh the summary comment on an existing PR when needed
+
+If another skill needs to refresh the PR summary later, point that skill's reference file at this rule first, then document only the skill-specific trigger and failure behavior there.
+
+## Hidden Marker
+
+Use this hidden marker:
+
+```html
+<!-- sync-pr:{task-id}:summary -->
+```
+
+Within one PR, a given `{task-id}` must have only one summary comment with this marker.
+
+## Aggregation Inputs
+
+Aggregate the latest artifacts in the task directory:
+- `plan.md` or the latest `plan-r{N}.md`
+- `implementation.md` or the latest `implementation-r{N}.md`
+- `review.md` or the latest `review-r{N}.md`
+- `refinement.md` or the latest `refinement-r{N}.md`
+
+Aggregation rules:
+- extract 2-4 self-contained technical decisions from `plan*`
+- build the review-history table from `review*` and `refinement*`
+- extract the test summary from `implementation*` or `refinement*`
+- if one artifact class is missing, treat it as "no data for this stage" and continue
+
+## Comment Body Template
+
+Use this canonical comment body template:
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## Review Summary
+
+> **{agent}** · {task-id}
+
+**Updated At**: {current-time}
+
+### Key Technical Decisions
+
+- {decision-1}
+- {decision-2}
+
+### Review History
+
+| Round | Verdict | Finding Counts | Fix Status |
+|-------|---------|----------------|------------|
+| Round 1 | Pending | N/A | N/A |
+
+### Test Results
+
+- {test-summary}
+
+---
+*Generated by {agent} · Internal tracking: {task-id}*
+```
+
+## Comment Lookup And Update
+
+Fetch existing comments through the Issues comments API, not the dedicated PR comments API.
+
+Process:
+1. Fetch existing PR comments and locate the comment ID that starts with `<!-- sync-pr:{task-id}:summary -->`
+2. When rendering the body, always write the current `git rev-parse HEAD` result into `<!-- last-commit: {git-head-sha} -->`
+3. If it does not exist, create it once as a fallback
+4. If it exists and the body is identical, skip the write
+5. If it exists and the body changed, PATCH it in place
+
+When updating an existing comment, use:
+
+```bash
+gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+## Shell Safety Rules
+
+1. Read local artifact content first, then inline the actual text into a `<<'EOF'` heredoc.
+2. Do not use command substitution or variable expansion inside the heredoc.
+3. Do not use `echo` to construct bodies that contain `<!-- -->`; use `cat <<'EOF'` or `printf '%s\n'`.
+
+## Error Handling
+
+| Failure Point | Handling |
+|--------|------|
+| `task.md` cannot be read | skip sync and let the later verification gate report it |
+| aggregation input is missing | warn and continue with the available data |
+| `gh api` GET/PATCH/POST fails | warn and continue; whether the current skill should block is decided by the caller |
+| `pr_number` points to a missing PR | warn with `PR #{pr-number} not found` and continue |
+
+## Result Reporting
+
+Return one of these normalized results so callers can reuse it in Activity Log entries or user output:
+- `summary created`
+- `summary updated`
+- `summary skipped (no diff)`
+- `summary failed: <reason>`

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -0,0 +1,110 @@
+# PR 摘要同步
+
+在同步 reviewer 面向的唯一 PR 摘要评论之前先读取本文件。
+
+## 适用范围
+
+当前调用方：
+- `create-pr`：首次创建或更新 PR 摘要评论
+- `commit`：在已有 PR 上按需刷新摘要评论
+
+如果后续 skill 也需要刷新 PR 摘要，先在对应 skill 的 reference 中引用本 rule，再补充该 skill 自身的触发条件和失败语义。
+
+## 隐藏标记
+
+统一使用以下隐藏标记：
+
+```html
+<!-- sync-pr:{task-id}:summary -->
+```
+
+同一个 PR 中，同一个 `{task-id}` 只能维护一条带该标记的摘要评论。
+
+## 聚合输入
+
+聚合当前任务目录中的最新产物：
+- `plan.md` 或最新 `plan-r{N}.md`
+- `implementation.md` 或最新 `implementation-r{N}.md`
+- `review.md` 或最新 `review-r{N}.md`
+- `refinement.md` 或最新 `refinement-r{N}.md`
+
+聚合规则：
+- 从 `plan*` 提取 2-4 条自包含的关键技术决策
+- 用 `review*` 与 `refinement*` 构建审查历程表
+- 从 `implementation*` 或 `refinement*` 提取测试结果摘要
+- 某一类产物缺失时，按“无该阶段数据”处理并继续生成
+
+## 评论体模板
+
+评论正文使用以下唯一权威模板：
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## 审查摘要
+
+> **{agent}** · {task-id}
+
+**更新时间**：{当前时间}
+
+### 关键技术决策
+
+- {decision-1}
+- {decision-2}
+
+### 审查历程
+
+| 轮次 | 结论 | 问题统计 | 修复状态 |
+|------|------|----------|----------|
+| Round 1 | Pending | N/A | N/A |
+
+### 测试结果
+
+- {test-summary}
+
+---
+*由 {agent} 自动生成 · 内部追踪：{task-id}*
+```
+
+## 评论查找与更新
+
+已有评论必须通过 Issues comments API 获取，而不是单独的 PR comments API。
+
+处理顺序：
+1. 获取 PR 上现有 comments，查找以 `<!-- sync-pr:{task-id}:summary -->` 开头的评论 ID
+2. 渲染评论正文时，始终写入当前 `git rev-parse HEAD` 的结果到 `<!-- last-commit: {git-head-sha} -->`
+3. 不存在时，POST 创建一条新评论作为兜底
+4. 已存在且正文完全相同时，跳过写入
+5. 已存在且正文有变化时，PATCH 原地更新
+
+更新已有评论时，使用如下模式：
+
+```bash
+gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+## Shell 安全规则
+
+1. 先读取本地产物内容，再将实际文本内联到 `<<'EOF'` heredoc 中。
+2. 禁止在 heredoc 中使用命令替换或变量展开。
+3. 构造含 `<!-- -->` 的正文时禁止使用 `echo`，统一使用 `cat <<'EOF'` 或 `printf '%s\n'`。
+
+## 错误处理
+
+| 失败点 | 处理 |
+|--------|------|
+| `task.md` 无法读取 | 跳过同步，交由后续 verification gate 报错 |
+| 聚合输入缺失 | 记警告并按现有数据继续生成 |
+| `gh api` GET/PATCH/POST 失败 | 输出警告并继续；是否阻塞当前 skill 由调用方决定 |
+| `pr_number` 指向的 PR 不存在 | 输出 `PR #{pr-number} not found` 警告并继续 |
+
+## 结果回传
+
+统一回传以下结果之一，供调用方在 Activity Log 或用户输出中复用：
+- `summary created`
+- `summary updated`
+- `summary skipped (no diff)`
+- `summary failed: <reason>`

package/templates/.agents/scripts/validate-artifact.js

@@ -33,6 +33,7 @@ const DEFAULT_RETRY_DELAYS_MS = [3000, 10000];
 const DEFAULT_FRESHNESS_MINUTES = 30;
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
 const ACTIVITY_LOG_PATTERN = /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.+)$/;
+const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 const scriptPath = fileURLToPath(import.meta.url);
 const repoRoot = path.resolve(path.dirname(scriptPath), "..", "..");
@@ -190,6 +191,11 @@ function checkTaskMeta({ taskDir, config }) {
     }
   }
 
+  const branchValidationError = validateTaskBranch(metadata);
+  if (branchValidationError) {
+    return failResult("task-meta", branchValidationError);
+  }
+
   const expectedStep = config.expected_step;
   if (expectedStep && metadata.current_step !== expectedStep) {
     return failResult(
@@ -232,6 +238,40 @@ function checkTaskMeta({ taskDir, config }) {
   return passResult("task-meta", `Task metadata valid (${requiredFields.length} required fields checked)`);
 }
 
+function validateTaskBranch(metadata) {
+  if (isBlank(metadata.branch)) {
+    return null;
+  }
+
+  const projectName = loadProjectName();
+  const expectedPrefix = projectName ? `${projectName}-${metadata.type}-` : "";
+
+  if (expectedPrefix && !String(metadata.branch).startsWith(expectedPrefix)) {
+    return `Invalid branch: expected prefix '${expectedPrefix}', got '${metadata.branch}'`;
+  }
+
+  const slug = expectedPrefix ? String(metadata.branch).slice(expectedPrefix.length) : String(metadata.branch);
+  if (!BRANCH_SLUG_PATTERN.test(slug)) {
+    return `Invalid branch: '${metadata.branch}' must use kebab-case suffixes`;
+  }
+
+  return null;
+}
+
+function loadProjectName() {
+  const configPath = path.join(repoRoot, ".agents", ".airc.json");
+  if (!fs.existsSync(configPath)) {
+    return "";
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return String(config.project || "").trim();
+  } catch {
+    return "";
+  }
+}
+
 function checkArtifact({ taskDir, config, artifactFile }) {
   const resolvedArtifact = resolveArtifactPath(taskDir, config.file_pattern, artifactFile);
   if (!resolvedArtifact.ok) {
@@ -396,6 +436,7 @@ function checkGithubSync({ taskDir, config, artifactFile }) {
     checkStatusLabel,
     checkCommentMarker,
     checkPrCommentMarker,
+    checkPrCommentLastCommit,
     checkCommentContent,
     checkTaskCommentContent,
     checkInLabelsMatchPr,
@@ -540,9 +581,13 @@ function buildSyncContext({ taskDir, config, artifactFile }) {
   }
 
   const issueNumber = parseIssueNumber(task.metadata.issue_number);
+  const prNumber = parsePrNumber(task.metadata.pr_number);
   if (config.when === "issue_number_exists" && !issueNumber) {
     return { earlyReturn: passResult("github-sync", "Skipped: task has no issue_number") };
   }
+  if (config.when === "pr_number_exists" && !prNumber) {
+    return { earlyReturn: passResult("github-sync", "Skipped: task has no pr_number") };
+  }
 
   if (!issueNumber) {
     return { earlyReturn: passResult("github-sync", "Skipped: github-sync not required for this task") };
@@ -568,7 +613,7 @@ function buildSyncContext({ taskDir, config, artifactFile }) {
     artifactFile,
     artifactPath,
     issueNumber,
-    prNumber: parsePrNumber(task.metadata.pr_number),
+    prNumber,
     ownerRepo: ownerRepo.value,
     marker,
     prMarker
@@ -707,6 +752,7 @@ function shouldFetchComments(config) {
   return Boolean(
     config.expected_comment_marker
     || config.expected_pr_comment_marker
+    || config.verify_pr_comment_last_commit_matches_head
     || config.verify_comment_content
     || config.verify_task_comment_content
   );
@@ -771,6 +817,57 @@ function checkPrCommentMarker(context, remoteData) {
   );
 }
 
+function checkPrCommentLastCommit(context, remoteData) {
+  if (!context.config.verify_pr_comment_last_commit_matches_head) {
+    return null;
+  }
+
+  if (!context.prMarker) {
+    return failResult(
+      "github-sync",
+      "verify_pr_comment_last_commit_matches_head requires expected_pr_comment_marker",
+      "check_failed"
+    );
+  }
+
+  const comment = findCommentByMarker(remoteData.prComments, context.prMarker);
+  if (!comment) {
+    return failResult(
+      "github-sync",
+      `Expected PR comment marker '${context.prMarker}' not found on PR #${context.prNumber}`,
+      "check_failed"
+    );
+  }
+
+  const match = String(comment.body || "").match(/<!--\s*last-commit:\s*([0-9a-f]{7,40})\s*-->/i);
+  if (!match) {
+    return failResult(
+      "github-sync",
+      `PR #${context.prNumber} summary comment is missing '<!-- last-commit: <sha> -->' metadata`,
+      "check_failed"
+    );
+  }
+
+  const headResult = withRetry(() => gitText(["rev-parse", "HEAD"], context.taskDir));
+  if (!headResult.ok) {
+    return headResult.type === "check_failed"
+      ? failResult("github-sync", headResult.message, headResult.type)
+      : blockedResult("github-sync", headResult.message, headResult.type);
+  }
+
+  const expectedHead = String(headResult.value || "").trim();
+  const actualHead = match[1].trim();
+  if (expectedHead === actualHead) {
+    return null;
+  }
+
+  return failResult(
+    "github-sync",
+    `PR #${context.prNumber} summary comment last-commit metadata mismatch: expected ${expectedHead}, got ${actualHead}`,
+    "check_failed"
+  );
+}
+
 function checkCommentContent(context, remoteData) {
   if (!context.config.verify_comment_content) {
     return null;
@@ -1179,6 +1276,25 @@ function ghPaginatedJson(args, cwd) {
   return ghJson(args, cwd);
 }
 
+function gitText(args, cwd) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    env: process.env
+  });
+
+  if (result.status !== 0) {
+    const stderr = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    return {
+      ok: false,
+      type: "check_failed",
+      message: stderr || `git ${args.join(" ")} failed`
+    };
+  }
+
+  return { ok: true, value: String(result.stdout || "").trim() };
+}
+
 function withRetry(operation) {
   const delays = getRetryDelays();
   let lastFailure = null;

package/templates/.agents/skills/archive-tasks/SKILL.md

@@ -5,7 +5,10 @@ description: "Archive completed tasks into a date-organized workspace directory"
 
 # Archive Completed Tasks
 
-Move completed tasks from `.agents/workspace/completed/` into `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/` and rebuild the archive index `manifest.md`.
+Move completed tasks from `.agents/workspace/completed/` into `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/` and rebuild a three-level archive index:
+- root manifest: `.agents/workspace/archive/manifest.md`
+- yearly manifest: `.agents/workspace/archive/YYYY/manifest.md`
+- monthly manifest: `.agents/workspace/archive/YYYY/MM/manifest.md`
 
 ## Execution Flow
 
@@ -29,7 +32,7 @@ The script is responsible for:
 - reading `completed_at` from `task.md` frontmatter and falling back to `updated_at`
 - moving task directories directly into `YYYY/MM/DD/TASK-xxx/` without compression
 - skipping already archived, missing, or malformed tasks
-- rebuilding `.agents/workspace/archive/manifest.md` from all archived tasks
+- rebuilding root, yearly, and monthly manifests from all archived tasks
 - printing an archive and skip summary
 
 ### 3. Inform the user
@@ -37,4 +40,4 @@ The script is responsible for:
 Report:
 - how many tasks were archived
 - how many tasks were skipped and why
-- the path to `manifest.md`
+- the path to the root manifest

package/templates/.agents/skills/archive-tasks/SKILL.zh-CN.md

@@ -5,7 +5,10 @@ description: "归档已完成任务到按日期组织的目录"
 
 # 归档已完成任务
 
-将 `.agents/workspace/completed/` 中的已完成任务移动到 `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/`，并重建归档索引 `manifest.md`。
+将 `.agents/workspace/completed/` 中的已完成任务移动到 `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/`，并重建三级归档索引：
+- 根 manifest：`.agents/workspace/archive/manifest.md`
+- 年 manifest：`.agents/workspace/archive/YYYY/manifest.md`
+- 月 manifest：`.agents/workspace/archive/YYYY/MM/manifest.md`
 
 ## 执行流程
 
@@ -29,7 +32,7 @@ bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before
 - 解析 `task.md` frontmatter 中的 `completed_at`（缺失时回退到 `updated_at`）
 - 按 `YYYY/MM/DD/TASK-xxx/` 目录直接移动任务，不压缩
 - 跳过已归档、缺少元数据或不存在的任务
-- 全量重建 `.agents/workspace/archive/manifest.md`
+- 全量重建根 / 年 / 月三级 manifest
 - 输出归档与跳过摘要
 
 ### 3. 告知用户
@@ -37,4 +40,4 @@ bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before
 向用户汇报：
 - 本次归档的任务数量
 - 跳过的任务数量和原因
-- `manifest.md` 的路径
+- 根 manifest 的路径

package/templates/.agents/skills/archive-tasks/scripts/archive-tasks.sh

@@ -208,6 +208,8 @@ should_archive_filtered_task() {
 
 rebuild_manifest() {
   entries_file="$tmpdir/manifest.tsv"
+  month_keys_file="$tmpdir/manifest-months.tsv"
+  year_keys_file="$tmpdir/manifest-years.tsv"
   generated_at=$(date "+%Y-%m-%d %H:%M:%S")
 
   mkdir -p "$ARCHIVE_DIR"
@@ -253,26 +255,107 @@ rebuild_manifest() {
             fi
           fi
 
-          printf '%s\t%s\t%s\t%s\t%s\n' "$completed_at" "$task_id" "$title" "$task_type" "$relative_path" >> "$entries_file"
+          printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$year" "$month" "$completed_at" "$task_id" "$title" "$task_type" "$relative_path" >> "$entries_file"
         done
       done
     done
   done
 
+  find "$ARCHIVE_DIR" -type f -name 'manifest.md' -exec rm -f {} \;
+
+  awk -F'\t' '{print $1 "\t" $2}' "$entries_file" | LC_ALL=C sort -u > "$month_keys_file"
+  awk -F'\t' '{print $1}' "$entries_file" | LC_ALL=C sort -u > "$year_keys_file"
+
+  while IFS="$(printf '\t')" read -r year month; do
+    [ -n "$year" ] || continue
+    [ -n "$month" ] || continue
+
+    month_entries_file="$tmpdir/manifest-${year}-${month}.tsv"
+    month_manifest_path="$ARCHIVE_DIR/$year/$month/manifest.md"
+
+    awk -F'\t' -v target_year="$year" -v target_month="$month" '
+      $1 == target_year && $2 == target_month {
+        print $3 "\t" $4 "\t" $5 "\t" $6 "\t" $7
+      }
+    ' "$entries_file" | LC_ALL=C sort -r > "$month_entries_file"
+
+    month_entry_count=$(wc -l < "$month_entries_file" | tr -d ' ')
+
+    {
+      echo "# Archive Manifest"
+      echo
+      echo "> Auto-generated by archive-tasks. Do not edit manually."
+      echo "> Last updated: $generated_at"
+      echo
+      echo "| Task ID | Title | Type | Completed | Path |"
+      echo "| --- | --- | --- | --- | --- |"
+
+      head -n 1000 "$month_entries_file" | while IFS="$(printf '\t')" read -r completed_at task_id title task_type relative_path; do
+        [ -n "$task_id" ] || continue
+        printf '| %s | %s | %s | %s | %s |\n' "$task_id" "$title" "$task_type" "$completed_at" "$relative_path"
+      done
+
+      if [ "$month_entry_count" -gt 1000 ]; then
+        echo
+        printf '> Showing 1000 of %s entries.\n' "$month_entry_count"
+      fi
+    } > "$month_manifest_path"
+  done < "$month_keys_file"
+
+  while IFS= read -r year; do
+    [ -n "$year" ] || continue
+
+    year_manifest_path="$ARCHIVE_DIR/$year/manifest.md"
+
+    {
+      echo "# Archive Manifest"
+      echo
+      echo "> Auto-generated by archive-tasks. Do not edit manually."
+      echo "> Last updated: $generated_at"
+      echo
+      echo "| Month | Tasks | Manifest |"
+      echo "| --- | --- | --- |"
+
+      awk -F'\t' -v target_year="$year" '
+        $1 == target_year {
+          counts[$2] += 1
+        }
+
+        END {
+          for (month in counts) {
+            print month "\t" counts[month]
+          }
+        }
+      ' "$entries_file" | LC_ALL=C sort -r | while IFS="$(printf '\t')" read -r month task_count; do
+        [ -n "$month" ] || continue
+        printf '| %s | %s | [%s/manifest.md](%s/manifest.md) |\n' "$month" "$task_count" "$month" "$month"
+      done
+    } > "$year_manifest_path"
+  done < "$year_keys_file"
+
   {
     echo "# Archive Manifest"
     echo
     echo "> Auto-generated by archive-tasks. Do not edit manually."
     echo "> Last updated: $generated_at"
     echo
-    echo "| Task ID | Title | Type | Completed | Path |"
-    echo "| --- | --- | --- | --- | --- |"
+    echo "| Year | Tasks | Manifest |"
+    echo "| --- | --- | --- |"
 
-    if [ -s "$entries_file" ]; then
-      LC_ALL=C sort -r "$entries_file" | while IFS="$(printf '\t')" read -r completed_at task_id title task_type relative_path; do
-        printf '| %s | %s | %s | %s | %s |\n' "$task_id" "$title" "$task_type" "$completed_at" "$relative_path"
-      done
-    fi
+    awk -F'\t' '
+      {
+        counts[$1] += 1
+      }
+
+      END {
+        for (year in counts) {
+          print year "\t" counts[year]
+        }
+      }
+    ' "$entries_file" | LC_ALL=C sort -r | while IFS="$(printf '\t')" read -r year task_count; do
+      [ -n "$year" ] || continue
+      printf '| %s | %s | [%s/manifest.md](%s/manifest.md) |\n' "$year" "$task_count" "$year" "$year"
+    done
   } > "$MANIFEST_PATH"
 }
 

package/templates/.agents/skills/commit/SKILL.md

@@ -52,7 +52,15 @@ Append the Commit Activity Log entry and choose exactly one next-step case:
 - ready for review -> `review-task {task-id}`
 - ready for PR -> `create-pr`
 
-## 6. Verification Gate
+## 6. Sync PR Summary When Applicable
+
+When `{task-id}` exists and task.md contains a valid `pr_number`, refresh the PR summary comment `<!-- sync-pr:{task-id}:summary -->` on the PR. Otherwise, skip this step.
+
+> The full trigger conditions, aggregation rules, PATCH/POST flow, shell-safety constraints, and error handling live in `reference/pr-summary-sync.md` (which in turn points to `.agents/rules/pr-sync.md`). Read `reference/pr-summary-sync.md` before executing this step.
+
+Failure handling matches "Update Task Status When Applicable": warn, but do **not** block an already completed `git commit`.
+
+## 7. Verification Gate
 
 If this operation is associated with `{task-id}`, run the verification gate to confirm task metadata and sync state. If there is no task context, skip this step.
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -52,7 +52,15 @@ date "+%Y-%m-%d %H:%M:%S"
 - 准备审查 -> `review-task {task-id}`
 - 准备创建 PR -> `create-pr`
 
-## 6. 完成校验
+## 6. 同步 PR 摘要（按需）
+
+当 `{task-id}` 存在且 task.md 包含有效 `pr_number` 时，刷新 PR 上的 `<!-- sync-pr:{task-id}:summary -->` 摘要评论；否则跳过。
+
+> 完整的触发条件、聚合规则、PATCH/POST 流程、Shell 安全约束和错误处理见 `reference/pr-summary-sync.md`（其内联引用 `.agents/rules/pr-sync.md`）。执行此步骤前先读取 `reference/pr-summary-sync.md`。
+
+失败处理与「按需更新任务状态」一致：警告但**不**阻塞已完成的 `git commit`。
+
+## 7. 完成校验
 
 如果本次操作关联了 `{task-id}`，运行完成校验，确认任务元数据和同步状态符合规范；如果没有任务上下文，跳过本步骤。
 

package/templates/.agents/skills/commit/config/verify.json

@@ -17,6 +17,10 @@
       "expected_action_pattern": "Commit",
       "freshness_minutes": 30
     },
-    "github-sync": null
+    "github-sync": {
+      "when": "pr_number_exists",
+      "expected_pr_comment_marker": "<!-- sync-pr:{task-id}:summary -->",
+      "verify_pr_comment_last_commit_matches_head": true
+    }
   }
 }