@fitlab-ai/agent-infra 0.4.1 → 0.4.3

package/templates/.agents/README.md

@@ -1,6 +1,6 @@
 # Multi-AI Collaboration Guide
 
-This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, and others.
+This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode, and others.
 
 ## Dual-Config Architecture
 
@@ -8,10 +8,10 @@ Different AI tools read configuration from different locations:
 
 | AI Tool | Primary Config | Fallback |
 |---------|---------------|----------|
-| Claude Code | `.claude/` (CLAUDE.md, commands/, settings/) | - |
+| Claude Code | `.claude/` (CLAUDE.md, commands/, settings.json) | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
 | Gemini CLI | `AGENTS.md` | - |
-| Cursor | `.cursorrules` or `.cursor/rules/` | `AGENTS.md` |
+| OpenCode | `AGENTS.md` | - |
 | Other AI Tools | `AGENTS.md` | Project README |
 
 - **Claude Code** uses its dedicated `.claude/` directory for project instructions, slash commands, and settings.
@@ -23,10 +23,8 @@ This dual-config approach ensures every AI tool receives appropriate project con
 
 ```
 .agents/                        # AI collaboration config (version-controlled)
-  README.md                     # This file (English)
-  README.zh-CN.md               # Chinese version
+  README.md                     # Collaboration guide
   QUICKSTART.md                 # Quick start guide
-  QUICKSTART.zh-CN.md           # Quick start guide (Chinese)
   templates/                    # Task and document templates
     task.md                     # Task template
     handoff.md                  # AI-to-AI handoff template
@@ -45,7 +43,7 @@ This dual-config approach ensures every AI tool receives appropriate project con
 .claude/                        # Claude Code specific config
   CLAUDE.md                     # Project instructions for Claude
   commands/                     # Slash commands
-  settings/                     # Claude settings
+  settings.json                 # Claude settings
 ```
 
 ## Collaboration Model
@@ -76,21 +74,21 @@ When one AI completes a phase, it produces a **handoff document** (see `.agents/
 
 Each AI tool has different strengths. Use them accordingly:
 
-| Capability | Claude Code | Codex CLI | Gemini CLI | Cursor |
-|-----------|-------------|-----------|------------|--------|
+| Capability | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+|-----------|-------------|-----------|------------|----------|
 | Codebase analysis | Excellent | Good | Excellent | Good |
-| Code review | Excellent | Good | Good | Fair |
+| Code review | Excellent | Good | Good | Good |
 | Implementation | Good | Excellent | Good | Excellent |
-| Large context | Good | Fair | Excellent | Good |
-| Refactoring | Good | Good | Good | Excellent |
-| Documentation | Excellent | Good | Good | Fair |
+| Large context | Good | Fair | Excellent | Fair |
+| Refactoring | Good | Good | Good | Good |
+| Documentation | Excellent | Good | Good | Good |
 
 ### Recommended Assignments
 
 - **Analysis & Review** - Claude Code (strong reasoning, thorough exploration)
-- **Implementation** - Codex CLI or Cursor (fast code generation, inline editing)
+- **Implementation** - Codex CLI or OpenCode (fast code generation, command-driven editing)
 - **Large Context Tasks** - Gemini CLI (large context window for cross-file analysis)
-- **Quick Edits** - Cursor (IDE integration, fast iteration)
+- **Command-Driven Iteration** - OpenCode (workflow-friendly TUI execution)
 
 ## Quick Start
 
@@ -118,18 +116,33 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 
 1. Use consecutive integers for top-level steps: `1.`, `2.`, `3.`.
 2. Use nested numbering only for child actions that belong to a parent step: `1.1`, `1.2`, `2.1`.
-3. Use `a`, `b`, and `c` markers for branches, conditions, or alternative paths within the same step.
+3. Use `a`, `b`, and `c` markers for branches, conditions, or alternative paths within the same step; keep them scoped to child options rather than standalone decision tracks or output templates.
 4. Do not use intermediate numbers such as `1.5` or `2.5`; if a new standalone step is needed, renumber the following top-level steps.
 5. When renumbering, update every in-document step reference so the instructions remain accurate.
 6. Extract long bash scripts into a sibling `scripts/` directory; the SKILL.md should contain only a single-line invocation (e.g., `bash .agents/skills/<skill>/scripts/<script>.sh`) and a brief summary of the script's responsibilities.
+7. In SKILL.md files and their `reference/` templates, use “Scenario” naming for standalone condition branches, decision paths, or output templates (for example, “Scenario A”).
 
 ### SKILL.md Size Control
 
-- Keep the SKILL.md body within about 500 tokens (roughly 80 lines / 2KB).
-- Move content beyond that threshold into a sibling `reference/` directory.
+- Keep SKILL.md as concise as possible; move detailed rules, long templates, and large script blocks into a sibling `reference/` or `scripts/` directory.
+- Store declarative configuration in a sibling `config/` directory, for example `config/verify.json`.
 - Use explicit navigation in the skeleton, such as: `Read reference/xxx.md before executing this step.`
 - Keep scripts in `scripts/` and execute them instead of inlining long bash blocks.
 
+## Verification Gate
+
+For skills that produce structured artifacts or mutate task state, run the verification gate before claiming completion:
+
+```bash
+node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact-file] [--format json|text]
+```
+
+- Each skill declares its own checks in `config/verify.json`; keep the file focused on what that skill must validate
+- If a skill also prints next-step guidance, run the gate first and only show those instructions after the gate passes
+- For user-facing final validation, prefer `--format text` so the reply contains a readable summary instead of raw JSON
+- Shared validation logic belongs in `.agents/scripts/validate-artifact.js`; do not move detailed rules back into SKILL.md
+- Keep the gate output in the reply as fresh evidence; without output from the current run, do not claim completion
+
 ## FAQ
 
 ### Q: Do I need to configure every AI tool separately?

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

@@ -1,6 +1,6 @@
 # 多 AI 协作指南
 
-本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、Cursor 等。
+本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、OpenCode 等。
 
 ## 双配置架构
 
@@ -8,10 +8,10 @@
 
 | AI 工具 | 主要配置 | 备选配置 |
 |---------|---------|---------|
-| Claude Code | `.claude/`（CLAUDE.md、commands/、settings/） | - |
+| Claude Code | `.claude/`（CLAUDE.md、commands/、settings.json） | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
 | Gemini CLI | `AGENTS.md` | - |
-| Cursor | `.cursorrules` 或 `.cursor/rules/` | `AGENTS.md` |
+| OpenCode | `AGENTS.md` | - |
 | 其他 AI 工具 | `AGENTS.md` | 项目 README |
 
 - **Claude Code** 使用专属的 `.claude/` 目录存放项目指令、斜杠命令和设置。
@@ -23,10 +23,8 @@
 
 ```
 .agents/                        # AI 协作配置（版本控制）
-  README.md                     # 本文件（英文）
-  README.zh-CN.md               # 中文版本
+  README.md                     # 协作指南
   QUICKSTART.md                 # 快速入门指南
-  QUICKSTART.zh-CN.md           # 快速入门指南（中文）
   templates/                    # 任务和文档模板
     task.md                     # 任务模板
     handoff.md                  # AI 间交接模板
@@ -45,7 +43,7 @@
 .claude/                        # Claude Code 专属配置
   CLAUDE.md                     # Claude 项目指令
   commands/                     # 斜杠命令
-  settings/                     # Claude 设置
+  settings.json                 # Claude 设置
 ```
 
 ## 协作模型
@@ -76,26 +74,26 @@
 
 每个 AI 工具有不同的优势，请据此分配任务：
 
-| 能力 | Claude Code | Codex CLI | Gemini CLI | Cursor |
-|-----|-------------|-----------|------------|--------|
+| 能力 | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+|-----|-------------|-----------|------------|----------|
 | 代码库分析 | 优秀 | 良好 | 优秀 | 良好 |
-| 代码审查 | 优秀 | 良好 | 良好 | 一般 |
+| 代码审查 | 优秀 | 良好 | 良好 | 良好 |
 | 代码实现 | 良好 | 优秀 | 良好 | 优秀 |
-| 大上下文处理 | 良好 | 一般 | 优秀 | 良好 |
-| 重构 | 良好 | 良好 | 良好 | 优秀 |
-| 文档编写 | 优秀 | 良好 | 良好 | 一般 |
+| 大上下文处理 | 良好 | 一般 | 优秀 | 一般 |
+| 重构 | 良好 | 良好 | 良好 | 良好 |
+| 文档编写 | 优秀 | 良好 | 良好 | 良好 |
 
 ### 推荐分配
 
 - **分析和审查** - Claude Code（推理能力强，探索全面）
-- **代码实现** - Codex CLI 或 Cursor（代码生成快，内联编辑）
+- **代码实现** - Codex CLI 或 OpenCode（代码生成快，命令式工作流顺手）
 - **大上下文任务** - Gemini CLI（大上下文窗口，适合跨文件分析）
-- **快速编辑** - Cursor（IDE 集成，快速迭代）
+- **命令式迭代** - OpenCode（适合按工作流连续推进）
 
 ## 快速入门
 
-1. **阅读快速入门指南**：参见 `QUICKSTART.zh-CN.md` 获取分步说明。
-2. **创建任务**：将 `.agents/templates/task.zh-CN.md` 复制到 `.agents/workspace/active/`。
+1. **阅读快速入门指南**：参见 `QUICKSTART.md` 获取分步说明。
+2. **创建任务**：将 `.agents/templates/task.md` 复制到 `.agents/workspace/active/`。
 3. **分配给 AI**：更新任务元数据中的 `assigned_to` 字段。
 4. **执行工作流**：按照 `.agents/workflows/` 中相应的工作流执行。
 5. **交接**：切换 AI 时，从模板创建交接文档。
@@ -118,18 +116,33 @@
 
 1. 顶级步骤使用连续整数：`1.`、`2.`、`3.`。
 2. 只有父步骤下的从属动作才使用子步骤：`1.1`、`1.2`、`2.1`。
-3. 同一步中的分支、条件或多种可能性使用 `a`、`b`、`c` 标记。
+3. 同一步中的从属选项、条件分支或并列可能性使用 `a`、`b`、`c` 标记；仅用于步骤内部的子项展开，不用于命名独立的决策路径或输出模板。
 4. 不要使用 `1.5`、`2.5` 这类中间编号；如新增独立步骤，应整体顺延后续编号。
 5. 调整编号时，必须同步更新文中的步骤引用，确保说明、命令和检查点一致。
 6. 长 bash 脚本应从 SKILL.md 提取到同级 `scripts/` 目录中，SKILL.md 只保留单行调用（如 `bash .agents/skills/<skill>/scripts/<script>.sh`）和对脚本职责的概要说明。
+7. 在 SKILL.md 及其 `reference/` 模板中，如需为独立的条件分流、决策路径或输出模板命名，统一使用“场景”命名（例如使用“场景 A”）。
 
 ### SKILL.md 体积控制
 
-- SKILL.md 正文控制在约 500 tokens（约 80 行 / 2KB）以内。
-- 超过阈值的内容拆分到同级 `reference/` 目录。
+- SKILL.md 正文尽可能精简，把详细规则、长模板和大段脚本拆分到同级 `reference/` 或 `scripts/` 目录。
+- 声明式配置统一放在同级 `config/` 目录，例如 `config/verify.json`。
 - 骨架中使用明确导航，例如：`执行此步骤前，先读取 reference/xxx.md。`
 - 长脚本继续放在 `scripts/` 目录，优先执行脚本而不是内联大段 bash。
 
+## 完成校验
+
+对会产生结构化产物或任务状态变更的 skill，统一在结束前运行完成校验：
+
+```bash
+node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact-file] [--format json|text]
+```
+
+- 每个 skill 在自己的 `config/verify.json` 中声明需要检查的事项
+- 如果 skill 还会展示“下一步”提示，必须先通过完成校验，再输出这些指引
+- 面向用户展示最终校验结果时，优先使用 `--format text` 输出可读摘要，而不是原始 JSON
+- 共享逻辑集中在 `.agents/scripts/validate-artifact.js`，不要把详细校验规则重新塞回 SKILL.md
+- 在回复中保留当次校验输出作为当次验证输出；没有当次校验输出，不得声明完成
+
 ## 常见问题
 
 ### Q：我需要单独配置每个 AI 工具吗？

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

@@ -0,0 +1,185 @@
+# Issue Sync Rules
+
+Read this file before a task skill updates a GitHub Issue.
+
+## Direct `status:` Label Updates
+
+If task.md contains a valid `issue_number` (not empty and not `N/A`) and the Issue state is `OPEN`, replace every existing `status:` label and add the target one:
+
+```bash
+state=$(gh issue view {issue-number} --json state --jq '.state' 2>/dev/null)
+if [ "$state" = "OPEN" ]; then
+  gh issue view {issue-number} --json labels \
+    --jq '.labels[].name | select(startswith("status:"))' 2>/dev/null \
+  | while IFS= read -r label; do
+      [ -z "$label" ] && continue
+      gh issue edit {issue-number} --remove-label "$label" 2>/dev/null || true
+    done
+  gh issue edit {issue-number} --add-label "{target-status-label}" 2>/dev/null || true
+fi
+```
+
+Use `while IFS= read -r label` so labels like `status: in-progress` are handled line-by-line instead of being split on spaces.
+
+If `gh` fails, skip and continue. Do not fail the skill.
+
+## `in:` Label Sync
+
+Read the `labels.in` mapping from `.agents/.airc.json`.
+
+```bash
+git diff {base-branch}...HEAD --name-only
+```
+
+`{base-branch}` is usually `main`; in PR context, use the PR's base branch.
+
+### When a mapping exists (precise add/remove)
+
+1. Collect the full set of changed files in the branch
+2. Match each file against the directory prefixes in `labels.in` to compute the expected `in:` label set
+3. Query the current `in:` labels on the Issue or PR
+4. Apply the diff:
+   - expected but missing -> `gh issue edit {issue-number} --add-label "in: {module}" 2>/dev/null || true`
+   - present but no longer expected -> `gh issue edit {issue-number} --remove-label "in: {module}" 2>/dev/null || true`
+
+### When no mapping exists (add-only fallback)
+
+If `.airc.json` has no `labels.in` field or it is empty:
+1. query existing repository `in:` labels
+2. derive the top-level directory from each changed file
+3. add matching labels only and never remove existing `in:` labels
+
+## Artifact Comment Publishing
+
+The hidden marker must remain compatible:
+
+```html
+<!-- sync-issue:{task-id}:{file-stem} -->
+```
+
+Check for an existing comment before publishing:
+
+```bash
+gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[].body' \
+  | grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->"
+```
+
+Skip publishing when the marker already exists.
+
+Publishing flow:
+
+1. Read the local artifact file in full first
+2. Inline the full file contents as `{artifact body}`
+3. Do not summarize, rewrite, or truncate the artifact body
+
+Use this format:
+
+```markdown
+<!-- sync-issue:{task-id}:{file-stem} -->
+## {artifact-title}
+
+{artifact body}
+
+---
+*Generated by AI · Internal tracking: {task-id}*
+```
+
+`summary` comments need extra handling:
+- find an existing `<!-- sync-issue:{task-id}:summary -->` comment ID first
+- create the comment when none exists
+- patch the existing comment in place when the body changed
+
+```bash
+summary_comment_id=$(gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[] | select(.body | startswith("<!-- sync-issue:{task-id}:summary -->")) | .id' \
+  | head -n 1)
+gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+## task.md Comment Sync
+
+Hidden marker:
+
+```html
+<!-- sync-issue:{task-id}:task -->
+```
+
+Use an idempotent update path for `task.md`:
+
+1. Read the full `task.md`
+2. Wrap the YAML frontmatter (content between the `---` delimiters) inside a `<details><summary>Metadata (frontmatter)</summary>` block with a `yaml` code fence; render the remaining body as normal Markdown
+3. Use `task` as `{file-stem}`
+4. Find an existing comment ID for the marker
+5. Create the comment when none exists
+6. PATCH the comment in place when the body changed
+7. Skip when the body is unchanged
+
+task.md comment format:
+
+```markdown
+<!-- sync-issue:{task-id}:task -->
+## Task File
+
+<details><summary>Metadata (frontmatter)</summary>
+
+​```yaml
+---
+{frontmatter fields}
+---
+​```
+
+</details>
+
+{task.md body after frontmatter}
+
+---
+*Generated by AI · Internal tracking: {task-id}*
+```
+
+When restoring, extract the frontmatter from the `<details>` block and reassemble with the body to recover the original `task.md`.
+
+Title mapping:
+- `task` -> `Task File`
+
+## Backfill Rules (run before `/complete-task` archives)
+
+- Scan `task.md`, `analysis*.md`, `plan*.md`, `implementation*.md`, `review*.md`, and `refinement*.md` in the task directory
+- Check whether each `{file-stem}` was already published by its hidden marker; publish only missing artifacts
+- Backfill only appends missing comments; never delete or reorder existing comments
+- Derive the previous and next neighbors from Activity Log order and add this note below the title:
+
+```markdown
+> ⚠️ This comment was backfilled. In the timeline it belongs after "{previous-artifact-title}" and before "{next-artifact-title}".
+```
+
+- If only one neighbor exists, keep only that side of the note; if neither exists, omit the note
+
+Title mapping:
+- `task` -> `Task File`
+- `analysis` / `analysis-r{N}` -> `Requirements Analysis` / `Requirements Analysis (Round {N})`
+- `plan` / `plan-r{N}` -> `Technical Plan` / `Technical Plan (Round {N})`
+- `implementation` / `implementation-r{N}` -> `Implementation Report (Round 1)` / `Implementation Report (Round {N})`
+- `review` / `review-r{N}` -> `Review Report (Round 1)` / `Review Report (Round {N})`
+- `refinement` / `refinement-r{N}` -> `Refinement Report (Round 1)` / `Refinement Report (Round {N})`
+- `summary` -> `Delivery Summary`
+
+## Requirement Checkbox Sync
+
+Extract checked `- [x]` items from the `## Requirements` section in task.md. Skip when none exist.
+
+Read the current Issue body:
+
+```bash
+gh issue view {issue-number} --json body --jq '.body'
+```
+
+Replace matching `- [ ] {text}` lines with `- [x] {text}` only when the body actually changes, then PATCH the full body with `gh api`.
+
+## Shell Safety Rules
+
+1. Read the artifact first, then inline the real text into the heredoc body. Do not use command substitution or variable expansion inside `<<'EOF'`.
+2. Do not use `echo` to build content containing `<!-- -->`. Use `cat <<'EOF'` or `printf '%s\n'` instead.

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

@@ -0,0 +1,185 @@
+# Issue 同步规则
+
+在任务技能需要更新 GitHub Issue 时先读取本文件。
+
+## status: label 直设
+
+如果 task.md 中存在有效的 `issue_number`（非空、非 `N/A`），且 Issue 状态为 `OPEN`，则替换所有 `status:` label 并设置目标值：
+
+```bash
+state=$(gh issue view {issue-number} --json state --jq '.state' 2>/dev/null)
+if [ "$state" = "OPEN" ]; then
+  gh issue view {issue-number} --json labels \
+    --jq '.labels[].name | select(startswith("status:"))' 2>/dev/null \
+  | while IFS= read -r label; do
+      [ -z "$label" ] && continue
+      gh issue edit {issue-number} --remove-label "$label" 2>/dev/null || true
+    done
+  gh issue edit {issue-number} --add-label "{target-status-label}" 2>/dev/null || true
+fi
+```
+
+使用 `while IFS= read -r label` 按行处理，可避免 `status: in-progress` 这类含空格 label 被 shell 按空格拆开。
+
+如果 `gh` 命令失败，跳过并继续，不中断技能执行。
+
+## `in:` label 同步
+
+读取 `.agents/.airc.json` 的 `labels.in` 映射。
+
+```bash
+git diff {base-branch}...HEAD --name-only
+```
+
+`{base-branch}` 通常为 `main`；如果在 PR 上下文中，则使用 PR 的 base branch。
+
+### 有映射时（精确增删）
+
+1. 获取分支全部改动文件
+2. 对每个文件按目录前缀匹配 `labels.in` 中的值，得到"应有的 `in:` labels"集合
+3. 查询 Issue/PR 当前的 `in:` labels
+4. 差集比较：
+   - 应有但没有 → `gh issue edit {issue-number} --add-label "in: {module}" 2>/dev/null || true`
+   - 有但不应有 → `gh issue edit {issue-number} --remove-label "in: {module}" 2>/dev/null || true`
+
+### 无映射时（只增不删回退）
+
+如果 `.airc.json` 中不存在 `labels.in` 或为空对象：
+1. 查询仓库已有 `in:` labels
+2. 从改动文件提取第一级目录
+3. 仅添加匹配的 label，不移除已有 `in:` label
+
+## 产物评论发布
+
+隐藏标记必须保持兼容：
+
+```html
+<!-- sync-issue:{task-id}:{file-stem} -->
+```
+
+发布前先检查是否已存在同标记评论：
+
+```bash
+gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[].body' \
+  | grep -qF "<!-- sync-issue:{task-id}:{file-stem} -->"
+```
+
+如果已存在则跳过。
+
+发布流程：
+
+1. 先读取本地产物文件全文
+2. 将文件全文作为 `{artifact body}` 原文内联到评论中
+3. 禁止自行组织摘要、改写或截断正文
+
+评论格式统一为：
+
+```markdown
+<!-- sync-issue:{task-id}:{file-stem} -->
+## {artifact-title}
+
+{artifact body}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+`summary` 评论需要额外处理：
+- 先查找已有 `<!-- sync-issue:{task-id}:summary -->` 评论的 ID
+- 不存在则创建
+- 已存在且正文有变化时，使用 `gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body=...` 原地更新
+
+```bash
+summary_comment_id=$(gh api "repos/{owner}/{repo}/issues/{issue-number}/comments" \
+  --paginate --jq '.[] | select(.body | startswith("<!-- sync-issue:{task-id}:summary -->")) | .id' \
+  | head -n 1)
+gh api "repos/{owner}/{repo}/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
+{comment-body}
+EOF
+)"
+```
+
+## task.md 评论同步
+
+隐藏标记：
+
+```html
+<!-- sync-issue:{task-id}:task -->
+```
+
+`task.md` 使用幂等更新路径：
+
+1. 读取 `task.md` 全文
+2. 将 YAML frontmatter（`---` 到 `---` 之间的内容）包裹在 `<details><summary>元数据 (frontmatter)</summary>` 和 `` ```yaml `` 代码块中，其余正文保持原样作为 Markdown 渲染
+3. 使用 `task` 作为 `{file-stem}`
+4. 查找已有标记评论 ID
+5. 不存在则创建
+6. 已存在且正文有变化则 PATCH 原地更新
+7. 已存在且正文相同则跳过
+
+task.md 评论格式：
+
+```markdown
+<!-- sync-issue:{task-id}:task -->
+## 任务文件
+
+<details><summary>元数据 (frontmatter)</summary>
+
+​```yaml
+---
+{frontmatter fields}
+---
+​```
+
+</details>
+
+{task.md body after frontmatter}
+
+---
+*由 AI 自动生成 · 内部追踪：{task-id}*
+```
+
+还原时，从 `<details>` 块中提取 frontmatter，与正文拼合恢复为原始 `task.md`。
+
+评论标题映射：
+- `task` -> `任务文件`
+
+## 补发规则（`/complete-task` 归档前执行）
+
+- 扫描任务目录中的 `task.md`、`analysis*.md`、`plan*.md`、`implementation*.md`、`review*.md`、`refinement*.md`
+- 对每个 `{file-stem}` 用隐藏标记检查是否已发布；未发布则补发，已发布则跳过
+- 补发只追加缺失评论，不删除或重排已有评论
+- 位置说明从 Activity Log 推导时间线中的前后邻居，并加在评论标题下方：
+
+```markdown
+> ⚠️ 本评论为补发产物，按时间线应位于「{前一个产物标题}」之后、「{后一个产物标题}」之前。
+```
+
+- 如果只有前邻居或后邻居，仅保留存在的一侧说明；如果两侧都不存在，则不添加位置说明
+
+标题映射：
+- `task` -> `任务文件`
+- `analysis` / `analysis-r{N}` -> `需求分析` / `需求分析（Round {N}）`
+- `plan` / `plan-r{N}` -> `技术方案` / `技术方案（Round {N}）`
+- `implementation` / `implementation-r{N}` -> `实现报告（Round 1）` / `实现报告（Round {N}）`
+- `review` / `review-r{N}` -> `审查报告（Round 1）` / `审查报告（Round {N}）`
+- `refinement` / `refinement-r{N}` -> `修复报告（Round 1）` / `修复报告（Round {N}）`
+- `summary` -> `交付摘要`
+
+## 需求复选框同步
+
+从 task.md 的 `## 需求` 段落提取已勾选的 `- [x]` 条目；如果没有，跳过。
+
+读取 Issue 当前正文：
+
+```bash
+gh issue view {issue-number} --json body --jq '.body'
+```
+
+按复选框文本匹配，将对应的 `- [ ] {text}` 单向替换为 `- [x] {text}`。只有正文实际变化时，才使用 `gh api` PATCH 更新完整 body。
+
+## Shell 安全规则
+
+1. 先用 Read 工具读取产物全文，再把实际文本内联到 heredoc 中；禁止在 `<<'EOF'` 内使用命令替换或变量展开。
+2. 构造含 `<!-- -->` 的内容时禁止使用 `echo`；统一使用 `cat <<'EOF'` heredoc 或 `printf '%s\n'`。