@fitlab-ai/agent-infra 0.4.2 → 0.4.4

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>Semi-automated programming, powered by AI agents.</strong> Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
+  <strong>From issue to merged PR in 9 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
 </p>
 
 <p align="center">
@@ -182,40 +182,30 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 1. **Install** — `npm install -g @fitlab-ai/agent-infra` (or use the shell script wrapper)
 2. **Initialize** — `ai init` in the project root to generate `.agents/.airc.json` and install the seed command
 3. **Render** — run `update-agent-infra` in any AI TUI to detect the bundled template version and generate all managed files
-4. **Develop** — use 28 built-in skills to drive the full lifecycle: `analysis → design → implementation → review → fix → commit`
+4. **Develop** — use built-in skills to drive the full lifecycle: `analysis → design → implementation → review → fix → commit`
 5. **Update** — run `update-agent-infra` again whenever a new template version is available
 
 ### Layered Architecture
 
-```mermaid
-block-beta
-    columns 4
-
-    block:tui:4
-        columns 4
-        claude["Claude Code"] codex["Codex"] gemini["Gemini CLI"] opencode["OpenCode"]
-    end
-
-    space:4
-
-    block:shared:4
-        columns 3
-        skills["28 Skills"] workflows["4 Workflows"] templates["Templates"]
-    end
-
-    space:4
-
-    block:project:4
-        columns 4
-        agents[".agents/"] config[".agents/.airc.json"] workspace[".agents/workspace/"] governance["AGENTS.md"]
-    end
-
-    tui -- "slash commands" --> shared
-    shared -- "renders into" --> project
+```text
+┌───────────────────────────────────────────────────────┐
+│                     AI TUI Layer                      │
+│  Claude Code  ·  Codex  ·  Gemini CLI  ·  OpenCode    │
+└──────────────────────────┬────────────────────────────┘
+                           │ slash commands
+                           ▼
+┌───────────────────────────────────────────────────────┐
+│                     Shared Layer                      │
+│         Skills  ·  Workflows  ·  Templates            │
+└──────────────────────────┬────────────────────────────┘
+                           │ renders into
+                           ▼
+┌───────────────────────────────────────────────────────┐
+│                    Project Layer                      │
+│               .agents/  ·  AGENTS.md                  │
+└───────────────────────────────────────────────────────┘
 ```
 
-GitHub renders Mermaid diagrams natively. If a downstream renderer does not, the text above still explains the system structure.
-
 <a id="what-you-get"></a>
 
 ## What You Get
@@ -227,7 +217,7 @@ my-project/
 ├── .agents/               # Shared AI collaboration config
 │   ├── .airc.json         # Central configuration
 │   ├── workspace/         # Task workspace (git-ignored)
-│   ├── skills/            # 28 built-in AI skills
+│   ├── skills/            # Built-in AI skills
 │   ├── workflows/         # 4 prebuilt workflows
 │   └── templates/         # Task and artifact templates
 ├── .claude/               # Claude Code config and commands
@@ -240,7 +230,7 @@ my-project/
 
 ## Built-in AI Skills
 
-agent-infra ships with **28 built-in AI skills**. They are organized by use case, but they all share the same design goal: every AI TUI should be able to execute the same workflow vocabulary in the same repository.
+agent-infra ships with **a rich set of built-in AI skills**. They are organized by use case, but they all share the same design goal: every AI TUI should be able to execute the same workflow vocabulary in the same repository.
 
 <a id="task-lifecycle"></a>
 
@@ -265,6 +255,7 @@ agent-infra ships with **28 built-in AI skills**. They are organized by use case
 |-------|-------------|------------|----------------------|
 | `check-task` | Inspect the current task status, workflow progress, and next step. | `task-id` | Check progress without modifying task state. |
 | `block-task` | Move a task to blocked state and record the blocker reason. | `task-id`, `reason` (optional) | Pause work when an external dependency or decision is missing. |
+| `restore-task` | Restore local task files from GitHub Issue sync comments. | `issue-number`, `task-id` (optional) | Recover a task workspace after switching machines or clearing local state. |
 
 <a id="issue-and-pr"></a>
 
@@ -273,9 +264,7 @@ agent-infra ships with **28 built-in AI skills**. They are organized by use case
 | Skill | Description | Parameters | Recommended use case |
 |-------|-------------|------------|----------------------|
 | `create-issue` | Create a GitHub Issue from a task file. | `task-id` | Push a local task into GitHub tracking. |
-| `sync-issue` | Post task progress updates back to the linked GitHub Issue. | `task-id` or `issue-number` | Keep stakeholders updated as the task evolves. |
 | `create-pr` | Open a Pull Request to an inferred or explicit target branch. | `task-id` (optional), `target-branch` (optional) | Publish reviewed changes for merge, with optional explicit task linkage after a fresh session. |
-| `sync-pr` | Sync task progress and review metadata into the Pull Request. | `task-id` or `pr-number` | Keep PR metadata aligned with the local task record from either task or PR entrypoints. |
 
 <a id="code-quality"></a>
 
@@ -317,6 +306,7 @@ agent-infra ships with **28 built-in AI skills**. They are organized by use case
 | `refine-title` | Rewrite an Issue or PR title into Conventional Commits format. | `number` | Normalize inconsistent GitHub titles. |
 | `init-labels` | Initialize the repository's standard GitHub label set. | None | Bootstrap labels in a new repository. |
 | `init-milestones` | Initialize the repository's milestone structure. | None | Bootstrap milestone tracking in a new repository. |
+| `archive-tasks` | Archive completed tasks into a date-organized directory with a manifest index. | `[--days N \| --before DATE \| TASK-ID...]` | Periodically clean up the `completed/` directory. |
 | `update-agent-infra` | Update the project's collaboration infrastructure to the latest template version. | None | Refresh shared AI tooling without rebuilding local conventions. |
 
 > Every skill works across supported AI TUIs. The command prefix changes, but the workflow semantics stay the same.
@@ -390,7 +380,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.4.2",
+  "templateVersion": "v0.4.4",
   "files": {
     "managed": [
       ".agents/workspace/README.md",

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>AI Agent 半自动化编程神器。</strong> 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
+  <strong>从 Issue 到合并 PR，只需 9 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
 </p>
 
 <p align="center">
@@ -182,40 +182,30 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 1. **安装** — `npm install -g @fitlab-ai/agent-infra`（或使用 shell 脚本便捷封装）
 2. **初始化** — 在项目根目录运行 `ai init`，生成 `.agents/.airc.json` 并安装种子命令
 3. **渲染** — 在任意 AI TUI 中执行 `update-agent-infra`，检测当前打包模板版本并生成所有受管理文件
-4. **开发** — 使用 28 个内置 skill 驱动完整生命周期：`analysis → design → implementation → review → fix → commit`
+4. **开发** — 使用内置 skill 驱动完整生命周期：`analysis → design → implementation → review → fix → commit`
 5. **升级** — 有新模板版本时再次执行 `update-agent-infra` 即可
 
 ### 分层架构
 
-```mermaid
-block-beta
-    columns 4
-
-    block:tui:4
-        columns 4
-        claude["Claude Code"] codex["Codex"] gemini["Gemini CLI"] opencode["OpenCode"]
-    end
-
-    space:4
-
-    block:shared:4
-        columns 3
-        skills["28 Skills"] workflows["4 Workflows"] templates["Templates"]
-    end
-
-    space:4
-
-    block:project:4
-        columns 4
-        agents[".agents/"] config[".agents/.airc.json"] workspace[".agents/workspace/"] governance["AGENTS.md"]
-    end
-
-    tui -- "slash commands" --> shared
-    shared -- "renders into" --> project
+```text
+┌───────────────────────────────────────────────────────┐
+│                     AI TUI Layer                      │
+│  Claude Code  ·  Codex  ·  Gemini CLI  ·  OpenCode    │
+└──────────────────────────┬────────────────────────────┘
+                           │ slash 命令
+                           ▼
+┌───────────────────────────────────────────────────────┐
+│                     Shared Layer                      │
+│         Skills  ·  Workflows  ·  Templates            │
+└──────────────────────────┬────────────────────────────┘
+                           │ 渲染为
+                           ▼
+┌───────────────────────────────────────────────────────┐
+│                    Project Layer                      │
+│               .agents/  ·  AGENTS.md                  │
+└───────────────────────────────────────────────────────┘
 ```
 
-GitHub 原生支持 Mermaid 渲染。即使某些下游渲染器不支持，上方文字也足以传达系统结构。
-
 <a id="what-you-get"></a>
 
 ## 安装效果
@@ -227,7 +217,7 @@ my-project/
 ├── .agents/               # 共享 AI 协作配置
 │   ├── .airc.json         # 中央配置文件
 │   ├── workspace/         # 任务工作区（git 忽略）
-│   ├── skills/            # 28 个内置 AI skills
+│   ├── skills/            # 内置 AI skills
 │   ├── workflows/         # 4 个预置工作流
 │   └── templates/         # 任务与产物模板
 ├── .claude/               # Claude Code 配置与命令
@@ -240,7 +230,7 @@ my-project/
 
 ## 内置 AI Skills
 
-agent-infra 内置 **28 个 AI skills**。它们按使用场景分组，但共享同一个核心目标：无论使用哪种 AI TUI，都能在同一仓库里执行相同的工作流词汇和协作约定。
+agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组，但共享同一个核心目标：无论使用哪种 AI TUI，都能在同一仓库里执行相同的工作流词汇和协作约定。
 
 <a id="task-lifecycle"></a>
 
@@ -265,6 +255,7 @@ agent-infra 内置 **28 个 AI skills**。它们按使用场景分组，但共
 |-------|------|------|---------|
 | `check-task` | 查看当前任务状态、工作流进度和下一步建议。 | `task-id` | 不修改任务状态，仅检查当前进展。 |
 | `block-task` | 将任务标记为阻塞并记录阻塞原因。 | `task-id`、`reason`（可选） | 缺少外部依赖、决策或资源时暂停任务。 |
+| `restore-task` | 从 GitHub Issue 同步评论中还原本地任务文件。 | `issue-number`、`task-id`（可选） | 换机器或清空本地状态后恢复任务工作区。 |
 
 <a id="issue-and-pr"></a>
 
@@ -273,9 +264,7 @@ agent-infra 内置 **28 个 AI skills**。它们按使用场景分组，但共
 | Skill | 描述 | 参数 | 推荐场景 |
 |-------|------|------|---------|
 | `create-issue` | 根据任务文件创建 GitHub Issue。 | `task-id` | 需要把本地任务同步到 GitHub 跟踪时。 |
-| `sync-issue` | 将任务进度同步回关联的 GitHub Issue。 | `task-id` 或 `issue-number` | 任务推进过程中持续同步状态。 |
 | `create-pr` | 向推断出的目标分支或显式指定分支创建 Pull Request。 | `task-id`（可选）、`target-branch`（可选） | 变更准备合入时创建 PR；清空上下文后也可显式传入任务关联。 |
-| `sync-pr` | 将任务进度和审查元数据同步到 Pull Request。 | `task-id` 或 `pr-number` | 允许从任务入口或 PR 入口同步，让 PR 元数据与本地任务记录保持一致。 |
 
 <a id="code-quality"></a>
 
@@ -317,6 +306,7 @@ agent-infra 内置 **28 个 AI skills**。它们按使用场景分组，但共
 | `refine-title` | 将 Issue 或 PR 标题重构为 Conventional Commits 格式。 | `number` | GitHub 标题格式不规范时。 |
 | `init-labels` | 初始化仓库标准 GitHub labels 体系。 | 无 | 新仓库首次配置 labels 时。 |
 | `init-milestones` | 初始化仓库 milestones 结构。 | 无 | 新仓库首次建立里程碑时。 |
+| `archive-tasks` | 将已完成任务按日期归档到目录中，并生成 `manifest` 索引。 | `[--days N \| --before DATE \| TASK-ID...]` | 需要定期清理 `completed/` 目录时。 |
 | `update-agent-infra` | 将项目协作基础设施升级到最新模板版本。 | 无 | 需要刷新共享 AI 工具层时。 |
 
 > 所有 skills 都可跨支持的 AI TUI 复用。变化的只是命令前缀，工作流语义保持一致。
@@ -390,7 +380,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.4.2",
+  "templateVersion": "v0.4.4",
   "files": {
     "managed": [
       ".agents/workspace/README.md",

package/lib/defaults.json

@@ -1,8 +1,13 @@
 {
+  "labels": {
+    "in": {}
+  },
   "files": {
     "managed": [
       ".agents/QUICKSTART.md",
       ".agents/README.md",
+      ".agents/rules/",
+      ".agents/scripts/",
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",

package/lib/init.js

@@ -162,6 +162,7 @@ async function cmdInit() {
     org: orgName,
     language,
     templateVersion: VERSION,
+    labels: structuredClone(defaults.labels),
     files: structuredClone(defaults.files)
   };
 

package/lib/update.js

@@ -139,8 +139,15 @@ async function cmdUpdate() {
   // sync file registry
   const { added, changed } = syncFileRegistry(config);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
+  const labelsAdded = !config.labels;
+  let configChanged = changed;
 
-  if (changed) {
+  if (labelsAdded) {
+    config.labels = structuredClone(defaults.labels);
+    configChanged = true;
+  }
+
+  if (configChanged) {
     console.log('');
     if (hasNewEntries) {
       info(`New file entries synced to ${CONFIG_PATH}:`);
@@ -150,9 +157,14 @@ 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 {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && labelsAdded) {
+      info(`Default labels.in config added to ${CONFIG_PATH}.`);
+    }
     fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
   "scripts": {
     "build": "node scripts/build-inline.js",
     "prepare": "git config core.hooksPath .github/hooks || true",
-    "test": "node scripts/build-inline.js --check && node --test tests/*.test.js",
-    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/*.test.js"
+    "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js",
+    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js"
   }
 }

package/templates/.agents/README.md

@@ -124,11 +124,25 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 
 ### 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

@@ -124,11 +124,25 @@
 
 ### 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,194 @@
+# 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.
+
+## Assignee Sync
+
+When a skill creates or imports an Issue, automatically add the current executor as assignee:
+
+- `create-issue`: use `--assignee @me` in the `gh issue create` command
+- `import-issue`: run `gh issue edit {issue-number} --add-assignee @me 2>/dev/null || true` after import
+
+`@me` is resolved by `gh` CLI to the authenticated user. The operation is idempotent (adding an existing assignee is a no-op). If the command fails (e.g. insufficient permissions), skip and continue.
+
+## `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.