@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -1,237 +1,47 @@
-# Issue / PR 平台命令
+# PR 平台意图命令
 
-在需要验证平台认证、读取 Issue / PR，或执行 Issue / PR 创建与更新前先读取本文件。
+PR 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 
-## 认证与仓库信息
-
-先验证 GitHub CLI 可用且已认证：
-
-```bash
-gh auth status
-gh repo view --json nameWithOwner
-```
-
-如果任一命令失败，按调用该规则的 skill 约定停止或降级。
-
-## Upstream 仓库与权限检测
-
-在后续任何 `gh issue` 或 `gh api "repos/..."` 操作之前，先按 `.agents/rules/issue-sync.md` 完成 `upstream_repo`、`has_triage` 和 `has_push` 检测。
-
-- 后续所有 `gh issue` 命令统一使用 `-R "$upstream_repo"`
-- 后续所有 repo 级 `gh api` 命令统一使用 `"repos/$upstream_repo/..."`
-- `gh pr *` 命令保持作用于当前仓库，不额外加 `-R`
-- `gh api "orgs/{owner}/..."` 这类 org 级命令保持不变
-
-## Issue 模板检测
-
-使用以下命令检测 GitHub Issue Forms：
-
-```bash
-rg --files .github/ISSUE_TEMPLATE -g '*.yml' -g '!config.yml'
-```
-
-创建 Issue 前先读取匹配的 form 文件。目录不存在或没有匹配 form 时，使用调用方定义的 fallback 正文格式。
-
-常见候选模板：
-- `bug_report.yml`：bug 工作
-- `question.yml`：问题或排查工作
-- `feature_request.yml`：功能工作
-- `documentation.yml`：文档工作
-- `other.yml`：通用 fallback
-
-对 GitHub Issue Forms，检查匹配 form 的：
-- `name`
-- `type:`
-- `labels:`
-- `body:`
-
-字段处理规则：
-- `textarea` 和 `input`：使用 `attributes.label` 作为 markdown 标题，并从 task.md 填充值
-- `markdown`：跳过模板说明文案
-- `dropdown` 和 `checkboxes`：跳过
-- task.md 缺少合适值时，写入 `N/A`
-
-建议字段映射：
-
-| 模板字段提示 | task.md 来源 |
-|---|---|
-| `summary`, `title` | 任务标题 |
-| `description`, `problem`, `what happened`, `issue-description`, `current-content` | 任务描述 |
-| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | 需求列表 |
-| 其他 `textarea` / `input` 字段 | 任务描述，否则 `N/A` |
-
-## Issue 读取与创建
-
-读取 Issue：
-
-```bash
-gh issue view {issue-number} -R "$upstream_repo" --json number,title,body,labels,state,milestone,url
-```
-
-创建 Issue：
-
-```bash
-gh issue create -R "$upstream_repo" --title "{title}" --body "{body}" --assignee @me {label-args} {milestone-arg}
-```
-
-- `{label-args}` 由调用方按有效 label 列表展开为多个 `--label`
-- 仅当 `has_triage=true` 时传入 `{label-args}`；否则整体省略并继续
-- 没有有效 label 时省略全部 `--label`
-- 仅当 `has_triage=true` 时传入 `{milestone-arg}`；否则整体省略并继续
-- `{milestone-arg}` 为空时整体省略
-
-设置 Issue Type：
-
-```bash
-owner_type=$(gh api "repos/$upstream_repo" --jq '.owner.type // empty' 2>/dev/null || true)
-if [ "$owner_type" = "Organization" ]; then
-  owner=${upstream_repo%%/*}
-  gh api "orgs/$owner/issue-types" --jq '.[].name'
-  gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-type}" --silent
-fi
-```
-
-- 仅当 `has_push=true` 时执行 Issue Type 设置；否则跳过并继续
-- 仅当 owner type 为 `Organization` 时查询和设置 Issue Type；个人仓库或 owner type 探测失败时跳过并继续
-- 变更现有 Issue Type 时，先读取 `.agents/rules/issue-fields.md` 并使用流程 B，确保同名 pinned fields 迁移，且新 type 不包含的字段被清空
-
-## Issue 更新
-
-更新标题、label、assignee 或 milestone 时使用：
-
-```bash
-gh issue edit {issue-number} -R "$upstream_repo" {edit-args}
-```
-
-常见参数：
-- `--title "{title}"`
-- `--add-label "{label}"`（仅当 `has_triage=true`）
-- `--remove-label "{label}"`（仅当 `has_triage=true`）
-- `--add-assignee @me`
-- `--milestone "{milestone}"`（仅当 `has_triage=true`）
-
-Assignee 同步不做权限预判；如果命令失败，按调用方约定静默跳过。
-
-关闭 Issue：
-
-```bash
-gh issue close {issue-number} -R "$upstream_repo" --reason "{reason}"
-```
-
-## Issue 评论读取
-
-读取 Issue 评论或按隐藏标记查找已有评论：
-
-```bash
-gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
-```
-
-## 历史任务评论扫描
-
-`find-existing-task.js` 仅消费 stdin，不直接调用 `gh`。由 AI 按宿主 OS 选择下面的 pipeline 命令。
-
-POSIX（bash / zsh）：
-
-```bash
-set -o pipefail
-gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
-  --paginate --jq '.[] | @json' \
-  | node .agents/scripts/find-existing-task.js
-```
-
-Windows（PowerShell 7+ / pwsh）：
-
-```powershell
-$ErrorActionPreference = 'Stop'
-gh api "repos/$upstream_repo/issues/{issue-number}/comments" `
-  --paginate --jq '.[] | @json' |
-  node .agents/scripts/find-existing-task.js
-if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-```
-
-在 PowerShell 5.1 上需先显式启用 UTF-8 stdio，否则 pipe 可能损坏多字节字符：
-
-```powershell
-[Console]::OutputEncoding = $OutputEncoding = [System.Text.UTF8Encoding]::new()
-```
-
-## PR 模板与元数据辅助命令
-
-存在仓库 PR 模板时读取：
-
-```bash
-cat .github/PULL_REQUEST_TEMPLATE.md
-```
-
-参考最近合并的 PR 风格：
-
-```bash
-gh pr list --limit 3 --state merged --json number,title,body
-```
-
-PR 元数据同步前验证标准 type labels 是否存在：
+## 定位
 
 ```bash
-gh label list --search "type:" --limit 1 --json name --jq 'length'
+agent-infra-internal platform-pr inspect {task-id}
 ```
 
-如果结果是 `0`，先运行 `init-labels`，再重试 PR 元数据同步。
-
-## PR 读取与创建
+返回已绑定 PR 的规范身份；未绑定时返回 `PR_NOT_LINKED`。调用方不得按标题模糊匹配。
 
-读取 PR：
-
-```bash
-gh pr view {pr-number} --json number,title,body,labels,state,milestone,url,files
-```
+## 创建或恢复
 
-列出 PR：
+调用方把标题和正文分别写入临时文件，然后执行：
 
 ```bash
-gh pr list --state {state} --base {base-branch} --json number,title,url,headRefName,baseRefName
+agent-infra-internal platform-pr create {task-id} \
+  --agent {agent} --base {target-branch} --head {current-branch} \
+  --title-file {title-file} --body-file {body-file}
 ```
 
-按 head 分支查询当前分支是否存在开放 PR（`commit` 推送收尾用）：
+core 会先按 upstream、head 和 base 精确定位；唯一既有 PR 会复用并绑定，零个才创建，多个稳定失败。远端结果未知时重新精确定位，不盲重建。`--dry-run` 只返回计划。
 
-```bash
-gh pr list --head "{branch}" --state open --json number,url --jq '.[0].url // empty'
-```
-
-创建 PR：
+## 显式绑定
 
 ```bash
-gh pr create --base "{target-branch}" --title "{title}" --assignee @me \
-  {label-args} {milestone-arg} \
-  --body "$(cat <<'EOF'
-{pr-body}
-EOF
-)"
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
 ```
 
-- `{label-args}` 由调用方按有效 label 列表展开为多个 `--label "{label}"`
-- 仅当 `has_triage=true` 时传入 `{label-args}`；否则整体省略并继续
-- 没有有效 label 时省略全部 `--label`
-- `{milestone-arg}` 展开为 `--milestone "{milestone}"`
-- 仅当 `has_triage=true` 时传入 `{milestone-arg}`；否则整体省略并继续
-- `{milestone-arg}` 为空时整体省略
-
-## PR 更新
+冲突绑定稳定失败且不修改 `task.md`。
 
-更新 PR 标题、label 或 milestone：
+## 元数据同步
 
 ```bash
-gh pr edit {pr-number} {edit-args}
+agent-infra-internal platform-pr sync {task-id} \
+  --agent {agent} --metadata --closing-issue
 ```
 
-常见参数：
-- `--title "{title}"`
-- `--add-label "{label}"`
-- `--remove-label "{label}"`
-- `--milestone "{milestone}"`
+core 从关联 Issue 复制 type / `in:` labels、assignee、具体 milestone，并确保 closing association。权限不足返回逐项 `skipped` 和顶层 `degraded`；不得反向修改 Issue。
 
-## 错误处理
+## 状态语义
 
-- 读取失败：按调用方规则决定停止还是跳过
-- 更新失败：如果调用方标记为 best-effort，输出警告并继续
-- 权限不足：按 `has_triage` / `has_push` 分支跳过直接写操作，不阻塞调用方
-- `@me` 由 `gh` CLI 解析为当前认证用户
+- `planned|applied|no-op|degraded`：退出码 0。
+- `failed`：退出码 1，确定性输入或远端错误。
+- `blocked`：退出码 2，网络、认证或结果未知，需要人工介入或安全重跑。
+- 创建后摘要或元数据同步失败不得回滚 PR；调用方按所属 SKILL 记录 warning。

package/templates/.agents/rules/issue-pr-commands.zh-CN.md

@@ -1,5 +1,47 @@
-# Issue 和 PR 命令
+# PR 平台意图命令
 
-当前代码平台未内置 Issue 或 Pull Request 命令支持。
+PR 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 
-自定义平台会跳过平台专属自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行工作流。
+## 定位
+
+```bash
+agent-infra-internal platform-pr inspect {task-id}
+```
+
+返回已绑定 PR 的规范身份；未绑定时返回 `PR_NOT_LINKED`。调用方不得按标题模糊匹配。
+
+## 创建或恢复
+
+调用方把标题和正文分别写入临时文件，然后执行：
+
+```bash
+agent-infra-internal platform-pr create {task-id} \
+  --agent {agent} --base {target-branch} --head {current-branch} \
+  --title-file {title-file} --body-file {body-file}
+```
+
+core 会先按 upstream、head 和 base 精确定位；唯一既有 PR 会复用并绑定，零个才创建，多个稳定失败。远端结果未知时重新精确定位，不盲重建。`--dry-run` 只返回计划。
+
+## 显式绑定
+
+```bash
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
+```
+
+冲突绑定稳定失败且不修改 `task.md`。
+
+## 元数据同步
+
+```bash
+agent-infra-internal platform-pr sync {task-id} \
+  --agent {agent} --metadata --closing-issue
+```
+
+core 从关联 Issue 复制 type / `in:` labels、assignee、具体 milestone，并确保 closing association。权限不足返回逐项 `skipped` 和顶层 `degraded`；不得反向修改 Issue。
+
+## 状态语义
+
+- `planned|applied|no-op|degraded`：退出码 0。
+- `failed`：退出码 1，确定性输入或远端错误。
+- `blocked`：退出码 2，网络、认证或结果未知，需要人工介入或安全重跑。
+- 创建后摘要或元数据同步失败不得回滚 PR；调用方按所属 SKILL 记录 warning。

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

@@ -14,6 +14,6 @@ These hidden markers are the canonical registry for Issue synchronization:
 
 Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
 
-This code platform does not provide built-in issue synchronization.
+This code platform does not provide an Issue adapter. `platform-issue` returns structured no-op/degraded operations.
 
 Issue metadata, labels, milestones, assignees, and comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and platform adapters. Continue writing local task artifacts normally.

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

@@ -1,9 +1,7 @@
-# Issue Sync Rules
+# Issue Sync
 
 ## Marker Registry
 
-These hidden markers are the canonical registry for Issue synchronization:
-
 | Key | Marker |
 |---|---|
 | `task` | `<!-- sync-issue:{task-id}:task -->` |
@@ -12,312 +10,27 @@ These hidden markers are the canonical registry for Issue synchronization:
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
-Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
-
-Read this file before a task skill updates a GitHub Issue.
-
-## Upstream Repository Detection
-
-When an external contributor runs `gh` inside a fork, the default target is the fork instead of the upstream repository. Detect the upstream repository first and reuse `upstream_repo` for every later `gh issue` and `gh api "repos/..."` operation.
-
-```bash
-upstream_repo=$(gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
-  --jq 'if .fork then .parent.full_name else .full_name end' 2>/dev/null)
-```
-
-- non-fork repository: returns the current repository `full_name`
-- fork repository: returns the parent repository `full_name`
-- every later `gh issue` command must use `-R "$upstream_repo"`
-- every later `gh api "repos/..."` command must use `"repos/$upstream_repo/..."`
-
-## Permission Detection
-
-Run one permission check against the upstream repository before any write operation. When detection fails, treat it as no permission so the workflow degrades safely.
-
-```bash
-repo_perms=$(gh api "repos/$upstream_repo" --jq '.permissions' 2>/dev/null || echo '{}')
-has_triage=$(printf '%s' "$repo_perms" | grep -q '"triage":true' 2>/dev/null && echo true || echo false)
-has_push=$(printf '%s' "$repo_perms" | grep -q '"push":true' 2>/dev/null && echo true || echo false)
-```
-
-Operation-to-permission mapping:
-
-| Operation | Required permission | Notes |
-|------|---------|------|
-| add/remove labels | `has_triage` | triage is the minimum permission |
-| add/remove milestones | `has_triage` | same as above |
-| edit Issue body | `has_triage` | used by requirement checkbox sync |
-| set Issue Type | `has_push` | requires write permission |
-| set Issue fields | `has_push` | pinned custom fields; failures are non-blocking |
-| set assignee | no check | skip directly when it fails |
-| publish/update comments | no check | allowed for authenticated users in public repositories |
-
-## Degradation Rules
-
-| Level | Operation type | With permission | Without permission |
-|------|---------|--------|--------|
-| silent degradation | label / milestone / Issue Type / Issue fields | run the `gh` command directly and also update the task comment | skip direct `gh` writes, update only the task comment, let the bot backfill |
-| direct skip | assignee | run the `gh` command directly | do nothing else |
-| normal execution | comments | run normally | run normally |
-
-Key rules:
-
-- task comment sync must continue whether write permission exists or not
-- insufficient permission only affects direct Issue metadata writes and must not stop the skill
-- keep the existing `2>/dev/null || true` error-tolerance pattern
-
-When the caller has a `{task-id}` / task directory, permission degradation or critical sync failure must be recorded in `## Workflow Warnings`:
-
-```bash
-node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
-  --step issue-sync --severity IMPORTANT --code PERMISSION_DEGRADED \
-  --target "{operation}" --message "{reason}" \
-  --action "Wait for the bot/maintainer to backfill, or rerun the workflow step after permissions are available"
-```
-
-Comment create/update failures and exhausted network retries that affect reviewer visibility use `severity=ACTION_REQUIRED` with `code=COMMENT_SYNC_FAILED` or `NETWORK_RETRY_EXHAUSTED`.
-
-## External Contributor Locking
-
-Maintainers (`has_triage=true`) are never blocked. External contributors (`has_triage=false`) must check whether the current task already has a `task` comment author on the Issue before they start.
-
-```bash
-task_comment_author=$(gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
-  --paginate --jq '[.[] | select(.body | test("<!-- sync-issue:{task-id}:task -->")) | .user.login] | first' \
-  2>/dev/null || echo "")
-current_user=$(gh api user --jq '.login' 2>/dev/null || echo "")
-```
-
-Decision rules:
-
-- no `task` comment exists: allow execution
-- the `task` comment author is the current user: allow continuation
-- the `task` comment author is another user: stop immediately and ask the contributor to coordinate with a maintainer before taking over
-
-## Direct `status:` Label Updates
-
-Algorithm note: keep the flow below aligned with `.github/scripts/sync-labels-to-set.sh` (set-diff sync). This is the AI agent-side equivalent implementation for the `target_set = {"{target-status-label}"}` case. If either side changes, update the other one in the same patch to avoid drift between the agent and the bot.
-
-If task.md contains a valid `issue_number` (not empty and not `N/A`) and the Issue state is `OPEN`, sync the `status:` labels to the target value with an idempotent set diff:
-
-```bash
-state=$(gh issue view {issue-number} -R "$upstream_repo" --json state --jq '.state' 2>/dev/null)
-if [ "$state" = "OPEN" ]; then
-  current_status_labels=$(gh issue view {issue-number} -R "$upstream_repo" \
-    --json labels --jq '.labels[].name | select(startswith("status:"))' 2>/dev/null || true)
-  printf '%s\n' "$current_status_labels" | while IFS= read -r label; do
-    [ -z "$label" ] && continue
-    if [ "$label" != "{target-status-label}" ] && [ "$has_triage" = "true" ]; then
-      gh issue edit {issue-number} -R "$upstream_repo" --remove-label "$label" 2>/dev/null || true
-    fi
-  done
-  if [ "$has_triage" = "true" ] && ! printf '%s\n' "$current_status_labels" | grep -qxF "{target-status-label}"; then
-    gh issue edit {issue-number} -R "$upstream_repo" --add-label "{target-status-label}" 2>/dev/null || true
-  fi
-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 `has_triage=false`, skip direct label changes, update only the task comment, and let the bot backfill from the latest task metadata.
-
-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:
-
-- When the `create-task` platform rule triggers Issue creation: use `--assignee @me` in `gh issue create` and include `-R "$upstream_repo"`
-- `import-issue`: run `gh issue edit {issue-number} -R "$upstream_repo" --add-assignee @me 2>/dev/null || true` after import
-
-`@me` is resolved by `gh` CLI to the authenticated user. The operation is idempotent. If the command fails, skip it directly and do not provide a fallback path.
-
-## `in:` Label Sync
-
-> **Trigger timing**: run `in:` label sync only after code is committed (the `commit` skill). Do not run it during `code-task`. During `create-pr`, only copy the labels from the Issue to the PR without recomputing them.
-
-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 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: only when `has_triage=true`, run `gh issue edit {issue-number} -R "$upstream_repo" --add-label "in: {module}" 2>/dev/null || true`
-   - present but no longer expected: only when `has_triage=true`, run `gh issue edit {issue-number} -R "$upstream_repo" --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. only when `has_triage=true`, add matching labels and never remove existing `in:` labels
-
-If `has_triage=false`, skip direct `in:` label edits and keep task comment sync as the source for later automation backfill.
-
-## Artifact Comment Publishing
-
-The hidden marker must remain compatible:
-
-```html
-<!-- sync-issue:{task-id}:{file-stem} -->
-```
-
-Check for an existing comment before publishing:
+Comments use `platform-comment`; Issue resources use `platform-issue`:
 
 ```bash
-gh api "repos/$upstream_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}
-
-> **{agent}** · {task-id}
-
-{artifact body}
-
----
-*Generated by {agent} · Internal tracking: {task-id}*
-```
-
-`{agent}` is the name of the AI agent currently executing the skill (for example `claude`, `codex`, or `gemini`).
-
-`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 by using `gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body=...`
-
-```bash
-summary_comment_id=$(gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
-  --paginate --jq '.[] | select(.body | startswith("<!-- sync-issue:{task-id}:summary -->")) | .id' \
-  | head -n 1)
-gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
-{comment-body}
-EOF
-)"
-```
-
-Comment publishing is not gated by `has_triage` or `has_push`.
-
-If comment lookup, creation, or update fails and the caller has a task directory, record a Workflow Warning (`step=issue-sync`, `severity=ACTION_REQUIRED`, `code=COMMENT_SYNC_FAILED`, `target={file-stem}`) and surface it in the final Workflow Warnings output block.
-
-## 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, then 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
-
-> **{agent}** · {task-id}
-
-<details><summary>Metadata (frontmatter)</summary>
-
-​```yaml
----
-{frontmatter fields}
----
-​```
-
-</details>
-
-{task.md body after frontmatter}
-
----
-*Generated by {agent} · Internal tracking: {task-id}*
+agent-infra-internal platform-issue inspect {task-id}
+agent-infra-internal platform-issue create {task-id} --agent {agent}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {agent}
+agent-infra-internal platform-issue sync {task-id} --agent {agent} {desired-state-flags}
 ```
 
-When restoring, extract the frontmatter from the `<details>` block and reassemble it with the body to recover the original `task.md`.
-
-Title mapping:
+The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.
 
-- `task` -> `Task File`
+`planned|applied|no-op|degraded` exit 0; `failed` exits 1; `blocked` exits 2.
 
-task comment sync always runs and is never downgraded.
-
-## Backfill Rules (run before `/complete-task` archives)
-
-- Scan `task.md`, `analysis*.md`, `review-analysis*.md`, `plan*.md`, `review-plan*.md`, `code*.md`, and `review-code*.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 and never deletes or reorders existing comments
-- Resolve `{agent}` for backfilled comments in this order:
-  1. match the artifact filename in Activity Log (for example `→ analysis.md`) and extract the executor from `by {agent}`
-  2. if no match is found, fall back to `assigned_to` in task.md frontmatter
-  3. if `assigned_to` is also unavailable, use the current backfilling agent
-- 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})`
-- `review-analysis` / `review-analysis-r{N}` -> `Requirements Analysis Review (Round 1)` / `Requirements Analysis Review (Round {N})`
-- `plan` / `plan-r{N}` -> `Technical Plan` / `Technical Plan (Round {N})`
-- `review-plan` / `review-plan-r{N}` -> `Technical Plan Review (Round 1)` / `Technical Plan Review (Round {N})`
-- `code` / `code-r{N}` -> `Code Report (Round 1)` / `Code Report (Round {N})`
-- `review-code` / `review-code-r{N}` -> `Code Review (Round 1)` / `Code Review (Round {N})`
-- `summary` -> `Delivery Summary`
-
-Backfilled comments are also not gated by `has_triage` or `has_push`.
-
-## Requirement Checkbox Sync
-
-Extract checked `- [x]` items from the `## Requirements` section in task.md. Skip when none exist.
-
-Read the current Issue body:
+Map material degraded/failed/blocked results to workflow warnings through the structured intent; callers must not edit warning rows directly:
 
 ```bash
-gh issue view {issue-number} -R "$upstream_repo" --json body --jq '.body'
+agent-infra-internal task-warning {task-id} add \
+  --step issue-sync --severity {severity} --code {code} \
+  --target {target} --message {message} --action {action}
 ```
 
-Replace matching `- [ ] {text}` lines with `- [x] {text}`. Use `gh api` to PATCH the full body only when the body changed and `has_triage=true`.
-
-If `has_triage=false`, skip the body PATCH, update only the task comment, and let the bot backfill from the latest task state.
-
-## Shell Safety Rules
+## Backfill
 
-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.
+During completion, artifact comments are replayed with `--kind artifact --artifact <file> --backfill`. If the remote Issue has no matching marker, the core creates a comment with a historical-backfill notice. If a valid base or chunk marker set already exists, the core returns `no-op` and preserves the existing bodies and chunks. Marker conflicts still fail without writes.