@fitlab-ai/agent-infra 0.4.0 → 0.4.2

package/templates/.agents/skills/sync-issue/reference/comment-publish.zh-CN.md

@@ -0,0 +1,84 @@
+# 评论发布规则
+
+在创建或更新 Issue 评论之前先读取本文件。
+
+## 拉取已有评论并构建已发布产物集合
+
+使用如下隐藏标记：
+
+```html
+<!-- sync-issue:{task-id}:{file-stem} -->
+```
+
+产物提取规则：
+- 用 `/→\s+(\S+\.md)\s*$/` 从 Activity Log 中提取产物文件名
+- 去掉 `.md` 后缀得到 `{file-stem}`
+- 按 Activity Log 顺序构建产物时间线
+- 固定把 `summary` 追加到最后
+
+产物时间线必须按 Activity Log 顺序构建。只包含任务目录中仍然存在的产物文件。
+常见产物文件名包括 `implementation-r*.md` 和 `review-r*.md`。
+
+已发布集合检测：
+
+```bash
+grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->" "$comments_jsonl"
+```
+
+含义：
+- 找到匹配 -> 该产物已经发布过
+- 没有匹配 -> 该产物本轮可以创建
+
+在开始发布评论前，先定义 `has_unpublished_artifacts`：即时间线中是否还存在任何未发布的非 `summary` 产物。该标志在本轮同步过程中保持不变。
+
+推荐标题映射：
+
+| file-stem | title |
+|---|---|
+| `analysis` | `需求分析` |
+| `analysis-r{N}` | `需求分析（Round {N}）` |
+| `plan` | `技术方案` |
+| `plan-r{N}` | `技术方案（Round {N}）` |
+| `implementation` | `实现报告（Round 1）` |
+| `implementation-r{N}` | `实现报告（Round {N}）` |
+| `refinement` | `修复报告（Round 1）` |
+| `refinement-r{N}` | `修复报告（Round {N}）` |
+| `review` | `审查报告（Round 1）` |
+| `review-r{N}` | `审查报告（Round {N}）` |
+| `summary` | `交付摘要` |
+
+## 按时间线顺序逐个发布上下文产物
+
+始终把 `summary` 放在最后。不要把多个轮次折叠成一条评论。
+
+统一评论格式：
+
+```markdown
+<!-- sync-issue:{task-id}:{file-stem} -->
+## {artifact-title}
+
+{artifact original body or summary body}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+`summary` 处理规则：
+- 如果 `summary` 不存在，就创建它
+- 如果 `summary` 已存在且 `has_unpublished_artifacts=true`，删除旧的 `summary`，并在最后重新创建
+- 如果 `summary` 已存在、`has_unpublished_artifacts=false`，且内容发生变化，则原地 patch 该评论
+- 如果 `summary` 已存在、`has_unpublished_artifacts=false`，且内容没有变化，则不做任何操作
+
+零操作规则：
+- 如果所有产物都已同步，且 `summary` 内容未变化，则不要发布任何内容，并报告 `所有产物已同步，无新内容`
+
+更新已有 `summary` 评论时，使用：
+
+```bash
+gh api "repos/$repo/issues/comments/{summary_comment_id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+不要回退到固定的 `analysis -> plan -> implementation -> review -> summary` 顺序。

package/templates/.agents/skills/sync-issue/reference/label-sync.md

@@ -0,0 +1,62 @@
+# Label and Issue Type Sync
+
+Read this file before editing `status:`, `in:`, or Issue Type metadata.
+
+## Sync Labels and Issue Type
+
+Initialize labels when needed:
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+If the result is `0`, run `init-labels` and retry this step.
+
+Status label workflow:
+
+```bash
+gh issue view {issue-number} --json labels --jq '.labels[].name | select(startswith("status:"))'
+gh issue edit {issue-number} --remove-label "{status-label}"
+gh issue edit {issue-number} --add-label "{status-label}"
+```
+
+Status decision table:
+
+| Condition | Action |
+|---|---|
+| Issue is closed (`state = CLOSED`) | add no new `status:` label |
+| task lives under `completed/` | add no new `status:` label |
+| task lives under `blocked/` | add `status: blocked` |
+| `current_step` ∈ {`requirement-analysis`, `technical-design`} | add `status: pending-design-work` |
+| `current_step` ∈ {`implementation`, `code-review`, `refinement`} | add `status: in-progress` |
+
+`in:` label workflow:
+
+```bash
+gh label list --search "in: {module}" --limit 10 --json name --jq '.[].name'
+gh issue edit {issue-number} --add-label "in: {module}"
+```
+
+`in:` label flow:
+1. extract changed file paths from implementation artifacts first; fall back to analysis artifacts only when implementation artifacts do not exist
+2. take the first path segment as `{module}`
+3. de-duplicate all inferred modules
+4. check whether each exact `in: {module}` label exists before adding it
+5. add matching labels only; never remove existing `in:` labels
+
+Issue Type workflow:
+
+```bash
+gh api "orgs/$owner/issue-types" --jq '.[].name'
+gh api "repos/$repo/issues/{issue-number}" -X PATCH -f type="{name}"
+```
+
+Issue Type mapping:
+
+| task.md type | GitHub Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, and all other values | `Task` |
+
+If Issue Types are unavailable, record `Issue Type: skipped (not enabled)` and continue.

package/templates/.agents/skills/sync-issue/reference/label-sync.zh-CN.md

@@ -0,0 +1,62 @@
+# Label 和 Issue 类型同步
+
+在编辑 `status:`、`in:` 或 Issue 类型元数据之前先读取本文件。
+
+## 同步 Label 和 Issue 类型
+
+必要时先初始化 label：
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+如果结果是 `0`，先执行 `init-labels`，然后重新执行本步骤。
+
+`status:` label 工作流：
+
+```bash
+gh issue view {issue-number} --json labels --jq '.labels[].name | select(startswith("status:"))'
+gh issue edit {issue-number} --remove-label "{status-label}"
+gh issue edit {issue-number} --add-label "{status-label}"
+```
+
+`status:` 判断表：
+
+| 条件 | 操作 |
+|---|---|
+| Issue 已关闭（`state = CLOSED`） | 不新增 `status:` label |
+| 任务位于 `completed/` 目录下 | 不新增 `status:` label |
+| 任务位于 `blocked/` 目录下 | 添加 `status: blocked` |
+| `current_step` ∈ {`requirement-analysis`, `technical-design`} | 添加 `status: pending-design-work` |
+| `current_step` ∈ {`implementation`, `code-review`, `refinement`} | 添加 `status: in-progress` |
+
+`in:` label 工作流：
+
+```bash
+gh label list --search "in: {module}" --limit 10 --json name --jq '.[].name'
+gh issue edit {issue-number} --add-label "in: {module}"
+```
+
+`in:` label 流程：
+1. 优先从实现产物中提取改动文件路径；只有在不存在实现产物时，才回退到分析产物
+2. 取路径的第一级目录作为 `{module}`
+3. 对推断出的所有模块去重
+4. 仅在对应的精确 `in: {module}` label 存在时才添加
+5. 只添加匹配的 label；绝不移除已有的 `in:` label
+
+Issue 类型工作流：
+
+```bash
+gh api "orgs/$owner/issue-types" --jq '.[].name'
+gh api "repos/$repo/issues/{issue-number}" -X PATCH -f type="{name}"
+```
+
+Issue 类型映射：
+
+| task.md 类型 | GitHub Issue 类型 |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 以及其他所有值 | `Task` |
+
+如果 Issue 类型不可用，记录 `Issue Type: skipped (not enabled)`，然后继续执行。

package/templates/.agents/skills/sync-issue/reference/milestone-sync.md

@@ -0,0 +1,37 @@
+# Milestone Sync
+
+Read this file before selecting or editing the Issue milestone.
+
+## Sync the Milestone
+
+Milestone priority:
+1. existing Issue milestone
+2. explicit `milestone` field in task.md
+3. inferred version line from the current branch
+4. `General Backlog`
+
+Inference scenarios when `task.md` does not set `milestone` explicitly:
+1. detect the current branch with `git branch --show-current`
+2. Scenario A: if the current branch matches `{major}.{minor}.x`, use that exact line milestone
+3. Scenario B: if the current branch is `main` or `master`, inspect existing `{major}.{minor}.x` branches
+4. Scenario B result: when a highest existing line `X.Y.x` exists, target `(X+1).0.x`
+5. Scenario C: if no branch rule yields a version line, inspect the latest `vX.Y.Z` tag and fall back to `X.Y.x`
+6. Scenario C fallback: if no branch or tag rule yields a version line, fall back to `General Backlog`
+
+Fallback and assignment logic:
+1. preserve an existing Issue milestone when one is already set
+2. otherwise prefer an explicit `milestone` field from `task.md`
+3. otherwise apply the branch/tag scenario inference above
+4. if the inferred target milestone does not exist, downgrade to `General Backlog`
+5. if `General Backlog` also does not exist, record `Milestone: skipped (not found)` and stop milestone sync
+6. once a milestone title is resolved, assign it and record either `{target} (assigned)` or `General Backlog (fallback)`
+
+Useful commands:
+
+```bash
+gh issue view {issue-number} --json milestone
+git branch --show-current
+git branch -a | grep -oE '[0-9]+\.[0-9]+\.x'
+git tag --list 'v*' --sort=-v:refname | head -1
+gh issue edit {issue-number} --milestone "{milestone-title}"
+```

package/templates/.agents/skills/sync-issue/reference/milestone-sync.zh-CN.md

@@ -0,0 +1,37 @@
+# 里程碑同步
+
+在选择或编辑 Issue 里程碑之前先读取本文件。
+
+## 同步里程碑
+
+里程碑优先级：
+1. Issue 当前已有的里程碑
+2. task.md 中显式设置的 `milestone` 字段
+3. 从当前分支推断出的版本线里程碑
+4. `General Backlog`
+
+当 task.md 没有显式设置 `milestone` 时，按以下场景推断：
+1. 用 `git branch --show-current` 检测当前分支
+2. 场景 A：如果当前分支匹配 `{major}.{minor}.x`，直接使用该版本线里程碑
+3. 场景 B：如果当前分支是 `main` 或 `master`，检查现有的 `{major}.{minor}.x` 分支
+4. 场景 B 结果：当存在最高版本线 `X.Y.x` 时，目标使用 `(X+1).0.x`
+5. 场景 C：如果分支规则无法得出版本线，则检查最新的 `vX.Y.Z` tag，并回退到 `X.Y.x`
+6. 场景 C 回退：如果分支和 tag 规则都无法得出版本线，则回退到 `General Backlog`
+
+回退与赋值逻辑：
+1. 如果 Issue 已经有里程碑，优先保留
+2. 否则优先使用 task.md 中显式设置的 `milestone`
+3. 否则应用上面的分支 / tag 场景推断规则
+4. 如果推断出的目标里程碑不存在，则降级为 `General Backlog`
+5. 如果 `General Backlog` 也不存在，则记录 `Milestone: skipped (not found)`，并停止 milestone 同步
+6. 一旦解析出里程碑标题，就执行赋值，并记录 `{target} (assigned)` 或 `General Backlog (fallback)`
+
+常用命令：
+
+```bash
+gh issue view {issue-number} --json milestone
+git branch --show-current
+git branch -a | grep -oE '[0-9]+\.[0-9]+\.x'
+git tag --list 'v*' --sort=-v:refname | head -1
+gh issue edit {issue-number} --milestone "{milestone-title}"
+```

package/templates/.agents/skills/sync-pr/SKILL.md

@@ -1,296 +1,63 @@
 ---
 name: sync-pr
-description: >
-  Sync task progress to the related Pull Request, including PR metadata sync and a single idempotent review summary.
-  Triggered when the user asks to sync progress to PR. Argument: task-id.
+description: "Sync task progress to a Pull Request"
 ---
 
 # Sync Progress to PR
 
-Sync task progress to the related Pull Request. Argument: task-id.
+Sync PR metadata and keep one reviewer-facing summary comment up to date.
 
 ## Execution Flow
 
-### 1. Verify the Task Exists
+### 1. Parse the Argument
 
-Search for the task in this order:
-- `.agents/workspace/active/{task-id}/task.md`
-- `.agents/workspace/completed/{task-id}/task.md`
-- `.agents/workspace/blocked/{task-id}/task.md`
-
-Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, for example `TASK-20260306-143022`
-
-### 2. Read Task Information
-
-Extract from task.md:
-- `pr_number` (required; if missing, prompt the user)
-- `type`
-- `issue_number` (if applicable)
-- `current_step`
-- task title, description, status
-- `created_at`, `updated_at`, `last_synced_to_pr_at` (if present)
-
-### 3. Read Context Files
-
-Check and read these files if they exist:
-- highest-round `plan.md` / `plan-r{N}.md` - technical plan
-- `implementation.md`, `implementation-r{N}.md` - implementation reports
-- `review.md`, `review-r{N}.md` - review reports
-- `refinement.md`, `refinement-r{N}.md` - refinement reports
-- highest-round `analysis.md` / `analysis-r{N}.md` - analysis input only as fallback for `in:` labels
-
-### 4. Resolve Repository Coordinates and Check Whether the Label System Has Been Initialized
-
-Resolve repository coordinates first so later milestone queries and comment sync steps can reuse them:
-
-```bash
-repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
-owner="${repo%%/*}"
-```
-
-Run:
-
-```bash
-gh label list --search "type:" --limit 1 --json name --jq 'length'
-```
-
-Rules:
-- returns `0` -> standard labels are missing; run the `init-labels` skill first, then retry this step
-- returns non-zero -> continue with PR metadata sync
-
-### 5. Sync the Type Label
-
-Map task.md `type` using this table:
-
-| task.md type | GitHub label |
-|---|---|
-| bug, bugfix | `type: bug` |
-| feature | `type: feature` |
-| enhancement | `type: enhancement` |
-| refactor, refactoring | `type: enhancement` |
-| documentation | `type: documentation` |
-| dependency-upgrade | `type: dependency-upgrade` |
-| task | `type: task` |
-| anything else | skip |
-
-If the value maps to a label, run:
-
-```bash
-gh pr edit {pr-number} --add-label "{type-label}"
-```
-
-Do not create new type labels.
-
-### 6. Sync `in:` Labels
-
-Extract affected modules from implementation reports first, or analysis as fallback:
-- prefer file paths listed under `## Modified Files`, especially `### New Files` / `### Modified Files`, in `implementation.md` and `implementation-r{N}.md`
-- if implementation reports do not exist yet, fall back to affected files from analysis
-
-For each file path:
-1. take the first-level directory as `{module}`
-2. deduplicate
-3. verify that the label exists:
-
-```bash
-gh label list --search "in: {module}" --limit 10 --json name --jq '.[].name'
-```
-
-4. only when the exact `in: {module}` label exists, run:
-
-```bash
-gh pr edit {pr-number} --add-label "in: {module}"
-```
-
-5. only add labels; do not remove existing `in:` labels
-
-### 7. Sync the Milestone
-
-Assign a line milestone to the PR using the same inference strategy as `sync-issue`.
-
-**a) Check whether the PR already has a milestone**
-
-Run:
-
-```bash
-gh pr view {pr-number} --json milestone --jq '.milestone.title // empty'
-```
-
-If the result is non-empty, preserve it and record `Milestone: {existing} (preserved)`.
-
-**b) Check whether task.md explicitly sets `milestone`**
-
-If frontmatter contains a non-empty `milestone`, use it as the target milestone.
-
-**c) Infer the target line milestone**
-
-When task.md does not explicitly set `milestone`, infer in this order:
-
-1. Detect the current branch:
-
-```bash
-git branch --show-current
-```
-
-- if the branch name matches `{major}.{minor}.x`, use `{major}.{minor}.x`
-
-2. If the current branch is `main` or `master`, detect existing release branches:
+Accept either `task-id` or PR number. For PR-number input, resolve the task with:
 
 ```bash
-git branch -a | grep -oE '[0-9]+\.[0-9]+\.x' | sort -V | tail -1
+grep -rl "^pr_number: {pr-number}$" \
+  .agents/workspace/active/ \
+  .agents/workspace/blocked/ \
+  .agents/workspace/completed/ \
+  2>/dev/null | head -1
 ```
 
-- if the highest release branch is `X.Y.x`, target `(X+1).0.x`
-- otherwise inspect the latest tag:
+If no task matches, output `No task found associated with PR #{pr-number}`.
 
-```bash
-git tag --list 'v*' --sort=-v:refname | head -1
-```
-
-- when the latest tag parses as `X.Y.Z`, target `X.Y.x`
-
-3. If none of the above yields a result, fall back to `General Backlog`
-
-**d) Find and set the milestone**
-
-Run:
-
-```bash
-gh api "repos/$repo/milestones" --paginate \
-  --jq '.[] | select(.title=="{target}") | .title' | head -1
-```
-
-- if the target does not exist, fall back to `General Backlog`
-- if `General Backlog` also does not exist, record `Milestone: skipped (not found)`
-- once a milestone title is found, run:
-
-```bash
-gh pr edit {pr-number} --milestone "{milestone-title}"
-```
-
-### 8. Sync Development Linking
-
-If task.md contains `issue_number`, ensure the PR body links the Issue.
-
-1. Read the PR body:
-
-```bash
-gh pr view {pr-number} --json body --jq '.body // ""'
-```
-
-2. Check whether the body already contains any of:
-- `Closes #{issue-number}`
-- `Fixes #{issue-number}`
-- `Resolves #{issue-number}`
-
-3. If any keyword already exists, skip the update
-4. Otherwise append this to the end of the body:
-
-```bash
-gh pr edit {pr-number} --body "$(cat <<'EOF'
-{existing-body}
-
-Closes #{issue-number}
-EOF
-)"
-```
-
-5. If task.md does not contain `issue_number`, record `Development: N/A`
+### 2. Verify the Task Exists
 
-### 9. Create or Update the Single Idempotent Review Summary
+Search active, blocked, and completed task directories and lock onto the matching task folder before continuing.
 
-Reuse the repository coordinates resolved in step 4, then fetch existing PR comments:
+### 3. Read Task Information
 
-```bash
-pr_comments_jsonl="$(mktemp)"
-
-gh api "repos/$repo/issues/{pr-number}/comments" \
-  --paginate \
-  --jq '.[] | {id, body}' > "$pr_comments_jsonl"
-```
-
-Use this hidden marker to identify the unique summary comment:
-
-```html
-<!-- sync-pr:{task-id}:summary -->
-```
-
-Extract the existing summary comment id:
-
-```bash
-summary_comment_id="$(
-  jq -r 'select(.body | contains("<!-- sync-pr:{task-id}:summary -->")) | .id' \
-    "$pr_comments_jsonl" | head -1
-)"
-```
-
-Summary requirements:
-- target reviewers instead of restating the full PR diff
-- extract 2-4 key technical decisions from `## Decision`, `## Technical Approach`, and `## Implementation Steps` in `plan.md`
-- each key technical decision must be self-contained; do not reference internal document labels or jargon such as `Option A/B`
-- build a review-history table from `review.md`, `review-r{N}.md`, `refinement.md`, and `refinement-r{N}.md`
-- extract test results from `implementation.md` or `refinement.md`
-
-Recommended review-history columns:
-- `Round`
-- `Verdict`
-- `Issue Counts`, for example `B:1 M:2 m:0`
-- `Fix Status`
-
-If no review artifacts exist yet, use a placeholder row such as `Round 1 | Pending | N/A | N/A`.
+Extract `pr_number`, `issue_number`, task title, type, and the latest timestamps from task.md.
 
-Candidate comment format:
+### 4. Read Context Files
 
-```markdown
-<!-- sync-pr:{task-id}:summary -->
-## Review Summary
+Read the latest plan, implementation, review, and refinement artifacts that will inform PR metadata and the reviewer summary.
 
-**Task**: {task-id}
-**Updated At**: {current-time}
+### 5. Resolve Repository Coordinates and Label Readiness
 
-### Key Technical Decisions
+Resolve `repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"` and verify whether `type:` labels have been initialized.
 
-- {decision-1}
-- {decision-2}
+### 6. Sync Metadata
 
-### Review History
+Sync the mapped type label, relevant `in:` labels, and milestone onto the PR.
 
-| Round | Verdict | Issue Counts | Fix Status |
-|-------|---------|--------------|------------|
-| Round 1 | Pending | N/A | N/A |
+> PR-state safeguards, milestone inference, and metadata skip rules for closed or merged PRs live in `reference/delivery-detection.md`. Read `reference/delivery-detection.md` before editing PR metadata.
 
-### Test Results
+### 7. Sync Development Linking
 
-- {test-summary}
+If `issue_number` exists, ensure the PR body contains `Closes #{issue-number}` or an equivalent closing keyword.
 
----
-*Generated by AI · Internal Tracking: {task-id}*
-```
+### 8. Publish the Reviewer Summary
 
-Idempotency rules:
-- if `summary_comment_id` is empty -> create a new comment
-- if `summary_comment_id` exists and content changed -> update the existing comment
-- if `summary_comment_id` exists and content did not change -> skip
+> Hidden markers, idempotent summary comment updates, review-history formatting, and comment create/update rules live in `reference/comment-publish.md`. Read `reference/comment-publish.md` before publishing the summary.
 
-To create a new comment, run:
+> **Shell Safety Rules** (read before publishing comments):
+> 1. `{comment-body}` must be replaced with **actual inline text**. Read the file with the Read tool first, then paste the full content into the heredoc body. **Do NOT** use `$(cat ...)`, `$(< ...)`, `$(...)`, or `${...}` inside `<<'EOF'`. Quoted heredocs suppress all command substitution and variable expansion, so those expressions will be output as literal text.
+> 2. When constructing strings that contain `<!-- -->`, **do NOT use `echo`**. In bash/zsh, `echo` escapes `!` as `\!`, which makes hidden markers visible. Build all comment content with `cat <<'EOF'` heredocs or `printf '%s\n'`.
 
-```bash
-gh api "repos/$repo/issues/{pr-number}/comments" -X POST -f body="$(cat <<'EOF'
-{comment-body}
-EOF
-)"
-```
-
-To update the existing comment, run:
-
-```bash
-gh api "repos/$repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
-{comment-body}
-EOF
-)"
-```
-
-### 10. Update Task Status
+### 9. Update Task Status
 
 Get the current time:
 
@@ -298,37 +65,23 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-Add or update `last_synced_to_pr_at` in task.md with `{current-time}`.
-- **Append** to `## Activity Log` (do NOT overwrite previous entries):
-  ```
-  - {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — PR metadata synced, summary {created|updated|skipped} on PR #{pr-number}
-  ```
-
-### 11. Inform the User
+Update `last_synced_to_pr_at` and append the Sync to PR Activity Log entry.
 
-```
-Progress synced to PR #{pr-number}.
-
-Synchronized:
-- Labels: {type-label-result}, {in-label-result}
-- Milestone: {milestone-result}
-- Development: {development-result}
-- Summary: {created|updated|skipped}
+### 10. Inform the User
 
-View: https://github.com/{owner}/{repo}/pull/{pr-number}
-```
+Report the synchronized labels, milestone, development status, summary result, and PR URL.
 
 ## Notes
 
-1. `sync-pr` is reviewer-facing. Keep one summary comment only, rather than publishing every artifact round to the PR.
-2. PR metadata sync must be safe to repeat. Re-runs should fill gaps without creating noise.
-3. Because Pull Requests share the Issue comments API, create the summary comment through `issues/{pr-number}/comments`.
-4. If `issue_number` is missing, record `Development: N/A` instead of failing the whole flow.
+- The hidden summary marker must stay `<!-- sync-pr:{task-id}:summary -->`
+- Keep exactly one summary comment for reviewers
+- If the PR is already closed or merged, report `PR #{number} is closed/merged, metadata sync skipped`
+- Follow the Step 8 shell safety rules when publishing comments: do not rely on command substitution inside quoted heredocs, and do not use `echo` for HTML comment markers
 
 ## Error Handling
 
+- No task found for the PR: `No task found associated with PR #{pr-number}`
 - Task not found: `Task {task-id} not found`
 - Missing PR number: `Task has no pr_number field`
 - PR not found: `PR #{number} not found`
-- PR is closed or merged: `PR #{number} is closed/merged, metadata sync skipped`
 - GitHub CLI auth failed: `Please check GitHub CLI authentication`