@fitlab-ai/agent-infra 0.8.4 → 0.9.0

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

@@ -1,191 +1,12 @@
 # Issue Creation
 
-After `create-task` writes the local `task.md`, follow this rule to cascade Issue creation. This rule is referenced internally by `create-task` SKILL.md only; do not invoke it standalone.
-
-## Boundary
-
-- Issue title and body must come from `task.md` only
-- Do not read `analysis.md`, `review-analysis.md`, `plan.md`, `review-plan.md`, `code.md`, or any review-code artifact
-- Persistent outputs are limited to the remote Issue and the `issue_number` written back to `task.md`
-- If Issue creation fails, do not roll back `task.md`; the current task remains valid for the workflow, and the user can later manually fill `issue_number` so other skills' cascade sync takes over
-
-## Steps
-
-### 1. Verify Prerequisites
-
-- `.agents/workspace/active/{task-id}/task.md` must exist
-- Read `.agents/rules/issue-pr-commands.md` first and run its authentication and platform detection commands to confirm `gh auth status` and the current repository are usable
-- Read `.agents/rules/issue-sync.md` first and complete `upstream_repo`, `has_triage`, and `has_push` detection; reuse these variables for every later `gh issue` and repo-level `gh api` call
-- If `task.md` already has a non-empty, non-`N/A` `issue_number`, halt the cascade immediately: return "Task already linked to Issue #{n}, skipping creation" to `create-task` and let it decide how to continue
-
-### 2. Extract Task Information
-
-Pull the following from `task.md`:
-
-- Task title (the first `# ` heading, stripped of `任务：` / `Task:` prefixes) — used to build the Issue title
-- frontmatter fields `type` and (optionally) `milestone`
-
-> The Issue **body** is not extracted by hand here. It is generated deterministically in §3 by the `ai task issue-body` command from the `## 描述` / `## 需求` sections; callers must not assemble it themselves.
-
-Build the Issue title:
-
-| task.md `type` | Conventional Commits type |
-|---|---|
-| `feature` | `feat` |
-| `bugfix`, `bug` | `fix` |
-| `refactor`, `refactoring` | `refactor` |
-| `docs`, `documentation` | `docs` |
-| `chore`, `task`, others | `chore` |
-
-Scope inference: read known module names from `.agents/.airc.json`'s `labels.in` field, then semantically match them against the task title and description; omit `scope` when there is no clear hit. Final title: `{cc_type}({scope}): {task_title}` or `{cc_type}: {task_title}` (preserve the task title verbatim — do not translate or rewrite).
-
-### 3. Build the Issue Body
-
-> **Mechanization boundary (mandatory)**: the Issue body is always produced deterministically by the `ai task issue-body` command; callers only pass the command's stdout to `gh issue create` via `--body-file` and must **not** assemble, rewrite, or truncate the body themselves. The command emits only the task title / `## 描述` / `## 需求` content; every other task.md scaffolding section never enters the body.
-
-Issue Form detection: follow the "Issue Template Detection" section in `.agents/rules/issue-pr-commands.md` to scan `.github/ISSUE_TEMPLATE/*.yml` (excluding `config.yml`).
-
-#### Scenario A: A matching template was detected
-
-Pick the form whose `name` (or filename) best matches the task type (e.g., a task with `type: bugfix` prefers a form whose name contains `bug`); if no match, fall back to a generic form like `other.yml`; if none, take the first form in the directory.
-
-Once the form file `{form-path}` is chosen, let the command render the final body from that Issue Form and write it to the body file `{body-file}` for §5:
-
-```bash
-ai task issue-body {task-id} --template "{form-path}" > "{body-file}"
-```
-
-The command skips `markdown` / `dropdown` / `checkboxes` fields and, for `input` / `textarea` fields, uses `attributes.label` as the heading and deterministically fills the task title / description / requirements by field `id`, writing `N/A` for fields with no reliable source (the field mapping table is the single source of truth inside the command and is not restated here). When the command exits non-zero (missing file / invalid YAML / no `body`), regenerate `{body-file}` with the Scenario B command instead.
-
-#### Scenario B: No template, or template parsing failed
-
-Let the command emit the default body (only `## 描述` + `## 需求`, checkbox text preserved verbatim, missing sections filled with `N/A`) into `{body-file}`:
-
-```bash
-ai task issue-body {task-id} > "{body-file}"
-```
-
-#### Red line: never use the entire task.md as the body
-
-In both Scenario A and B, the body may only come from `ai task issue-body` stdout and contains **only the description + requirements content** (Scenario A is the equivalent content mapped onto template fields).
-
-Wrong example (❌ forbidden): pasting the entire task.md — including scaffolding sections such as `## 分析` / `## 设计` / `## 实现备注` / `## 审查反馈` / `## 审查分歧账本` / `## 人工裁决` / `## 活动日志` / `## 完成检查清单` and `#XXX` placeholders — directly as the Issue body. Those sections only go to the `sync-issue:{task-id}:task` comment, never the body.
-
-### 4. Resolve labels / Issue Type / milestone
-
-#### labels (rough pass)
-
-- Call `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` to fetch the actual labels in the repo (cache as a set)
-- Pick the "expected type label" using the mapping below, keeping only those that exist in the repo set:
-
-  | task.md `type` | label |
-  |---|---|
-  | `bug`, `bugfix` | `type: bug` |
-  | `feature` | `type: feature` |
-  | `enhancement` | `type: enhancement` |
-  | `docs`, `documentation` | `type: documentation` |
-  | `dependency-upgrade` | `type: dependency-upgrade` |
-  | `task`, `chore` | `type: task` |
-  | `refactor`, `refactoring` | `type: enhancement` |
-  | others | skip |
-
-- `in:` labels (rough pass — when in doubt, leave it out): semantically match the task title and description against module names from `labels.in`; explicit mention or strong implication → add `in: {module}`; vague or uncertain → skip. `in:` labels also require the label to actually exist in the repo.
-
-If the final label set is empty, omit the `--label` argument.
-
-#### Issue Type fallback
-
-| task.md `type` | Issue Type |
-|---|---|
-| `bug`, `bugfix` | `Bug` |
-| `feature`, `enhancement` | `Feature` |
-| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, others | `Task` |
-
-When applying the Issue Type, follow the "Set Issue Type" command in `.agents/rules/issue-pr-commands.md`; only when the owner type is `Organization`, first call `gh api orgs/{owner}/issue-types` to list the org's actually available Types, and only set the inferred value when it is present in that list. User repositories, failed owner type probes, and failed writes are non-blocking.
-
-#### milestone
-
-**Mandatory; do not skip.** This section expands `.agents/rules/milestone-inference.md` Phase 1 in place and keeps the same semantics; do not treat it as optional inference.
-
-Select the milestone using these numbered steps, with priority strictly aligned to Phase 1:
-
-1. If `has_triage=false`: omit `--milestone` immediately and skip this section.
-2. List all open milestones in the repository:
-   ```bash
-   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
-     --jq '.[].title'
-   ```
-3. If task.md frontmatter explicitly provides a `milestone` field and that value appears in the step 2 list: use that value directly as `{milestone-arg}` and skip steps 4 / 5.
-4. Filter the step 2 result with `^[0-9]+\.[0-9]+\.x$`.
-   - Non-empty: sort by major and minor numerically, then choose the smallest release line as `{milestone-arg}`.
-5. If step 4 has no candidates: fall back to `General Backlog`.
-   - `General Backlog` exists in the step 2 result: use that milestone.
-   - `General Backlog` does not exist: omit `--milestone` only in this case.
-6. If the step 2 `gh api` call fails (network / authentication error): handle it as "no candidates" and continue to step 5.
-
-When a milestone is selected, pass the release line (or `General Backlog` or the explicit task.md value) as `{milestone-arg}` to the `gh issue create` command in step 5; keep the expansion rule at the end of §5 unchanged.
-
-### 5. Call the GitHub CLI to Create the Issue
-
-Run the "Create Issue" command from `.agents/rules/issue-pr-commands.md`; always use the `{body-file}` produced in §3, overriding the generic command's `--body`:
+After `create-task` writes task.md, create and initialize the Issue through declarative internal intents:
 
 ```bash
-gh issue create -R "$upstream_repo" \
-  --title "{title}" \
-  --body-file "{body-file}" \
-  --assignee @me \
-  {label-args} \
-  {milestone-arg}
+agent-infra-internal platform-issue create {task-id} --agent {agent}
+agent-infra-internal platform-issue sync {task-id} --agent {agent} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 
-- `{body-file}` is the body file produced in §3 by `ai task issue-body`; do **not** switch back to `--body` and assemble the body by hand
-- `{label-args}` is expanded from the result of §4 into multiple `--label "..."`; if empty, omit the entire argument
-- `{milestone-arg}` is only expanded to `--milestone "..."` when `has_triage=true` and milestone is non-empty; otherwise omit
-- `--assignee @me` requires no permission probe; on failure, skip silently
-
-Permission downgrade follows `.agents/rules/issue-sync.md`: `has_triage=false` skips label / milestone settings; `has_push=false` skips Issue Type setting; the rest continues.
-
-After success, parse the Issue number from the output (match only the `https://.../issues/(\d+)` URL form; do not use a loose regex). If parsing fails, halt the cascade and propagate the error back to `create-task`.
-
-### 6. Set Issue Type (Optional)
-
-Execute only when `has_push=true`, the owner type is `Organization`, and the Issue Type inferred in §4 is in the org's actually available list:
-
-```bash
-gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
-  -f type="{issue-type}" --silent
-```
-
-Failure is non-blocking.
-
-### 7. Set Issue Fields (Optional)
-
-If `has_push=true`, read `.agents/rules/issue-fields.md` and follow Flow A to write any applicable non-empty `priority`, `effort`, `start_date`, and `target_date` values from `task.md`.
-
-Field write failures are non-blocking.
-
-### 8. Write Back task.md
-
-Update task.md:
-
-- Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
-- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`)
-
-> Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Create Task`), written by the caller SKILL step 3.
-
-### 9. Return the Result
-
-Hand the following back to the caller `create-task`:
-
-- Issue number `{n}`
-- Issue URL (prefer the URL printed by `gh issue create`; fall back to `https://github.com/$upstream_repo/issues/{n}`)
-- The labels / milestone / Issue Type that were actually applied
-
-`create-task` uses these to pick the "Scenario A: Issue created" output branch and continue with task comment sync and status label setup.
-
-## Error Handling
+The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `issue_number` binding.
 
-- Auth failure / command unavailable: return a structured `{code: "AUTH_FAILED", message}` to `create-task`; do not modify task.md
-- Network timeout / DNS failure: `{code: "NETWORK", message}`
-- Template parsing failure, Issue number parsing failure, other anomalies: `{code: "VALIDATION", message}`
-- All failures keep task.md untouched; `create-task` must record the structured error in `## Workflow Warnings` (`severity=ACTION_REQUIRED`, `code=ISSUE_CREATE_FAILED`, `target=issue`) before taking the "Scenario C: failure fallback" output branch and prompting the user to retry manually or fill `issue_number` later
+`planned|applied|no-op|degraded` exit 0, `failed` exits 1, and `blocked` exits 2. Callers must not fall back to direct `gh issue` or GraphQL orchestration.

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

@@ -1,191 +1,25 @@
 # Issue 创建
 
-当 `create-task` 完成本地 `task.md` 落盘后，按本规则级联创建 Issue。本规则仅由 `create-task` SKILL.md 内部引用，不应独立调用。
-
-## 行为边界
-
-- Issue 标题和正文只能来自 `task.md`
-- 不读取 `analysis.md`、`review-analysis.md`、`plan.md`、`review-plan.md`、`code.md` 或代码审查产物
-- 持久产物只有：远端 Issue + `task.md` 中回写的 `issue_number`
-- Issue 创建失败时不回滚 `task.md`；当前 task 仍可继续后续工作流，未来可由用户手动写入 `issue_number`，让其它技能的级联同步接管
-
-## 执行步骤
-
-### 1. 验证前置条件
-
-- `.agents/workspace/active/{task-id}/task.md` 必须存在
-- 先读取 `.agents/rules/issue-pr-commands.md`，按其中的认证与平台检测命令验证 `gh auth status` 和当前仓库可用
-- 先读取 `.agents/rules/issue-sync.md`，完成 `upstream_repo`、`has_triage`、`has_push` 检测；后续所有 `gh issue` 与 repo 级 `gh api` 调用都复用这些变量
-- 如果 `task.md` 中 `issue_number` 已存在且既不为空也不为 `N/A`，立即停止级联：返回"任务已绑定 Issue #{n}，跳过创建"信息给 `create-task`，由调用方决定如何继续
-
-### 2. 提取任务信息
-
-从 `task.md` 提取以下字段：
-
-- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）—— 用于构造 Issue 标题
-- frontmatter 中的 `type` 与（可选的）`milestone`
-
-> Issue **正文**不在此处手工提取。正文由 §3 调用 `ai task issue-body` 命令从 `## 描述` / `## 需求` 段确定性生成，调用方不得自行拼装。
-
-构造 Issue 标题：
-
-| task.md `type` | Conventional Commits type |
-|---|---|
-| `feature` | `feat` |
-| `bugfix`, `bug` | `fix` |
-| `refactor`, `refactoring` | `refactor` |
-| `docs`, `documentation` | `docs` |
-| `chore`, `task` 或其它 | `chore` |
-
-scope 推断：从 `.agents/.airc.json` 的 `labels.in` 字段读取已知模块名，再与任务标题/描述做语义匹配；没有清晰命中时省略 scope。最终标题：`{cc_type}({scope}): {task_title}` 或 `{cc_type}: {task_title}`（任务标题保留原文，不要翻译或改写）。
-
-### 3. 构建 Issue 正文
-
-> **机械化边界（必须遵守）**：Issue 正文一律由 `ai task issue-body` 命令确定性生成；调用方只把命令 stdout 作为 `gh issue create` 的 `--body-file` 传入，**不得**自行拼装、改写或截断正文。命令只输出 task 标题 / `## 描述` / `## 需求` 对应内容，task.md 其余脚手架段落永不进入 body。
-
-Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板检测" 规则扫描 `.github/ISSUE_TEMPLATE/*.yml`（排除 `config.yml`）。
-
-#### 场景 A：检测到匹配模板
-
-按模板顶层 `name` 与任务类型挑选最匹配的 form（如任务 `type: bugfix` 优先选名称含 `bug` 的模板）；找不到匹配时，回退到通用 form（如 `other.yml`），仍找不到时取目录中第一个 form。
-
-确定模板文件 `{form-path}` 后，由命令按该 Issue Form 渲染最终正文，并写入正文文件 `{body-file}` 供 §5 使用：
-
-```bash
-ai task issue-body {task-id} --template "{form-path}" > "{body-file}"
-```
-
-命令跳过 `markdown` / `dropdown` / `checkboxes` 字段，对 `input` / `textarea` 字段以 `attributes.label` 作标题、按字段 `id` 确定性填入 task 标题 / 描述 / 需求，无可靠映射源的字段填 `N/A`（字段映射表是命令内的单一真源，不在本规则重述）。命令退出码非 0（文件缺失 / 非法 YAML / 无 `body`）时，改用场景 B 命令重新生成 `{body-file}`。
-
-#### 场景 B：无模板或解析失败
-
-由命令输出默认正文（仅 `## 描述` + `## 需求`，复选框逐字保留，缺失段落填 `N/A`），写入 `{body-file}`：
-
-```bash
-ai task issue-body {task-id} > "{body-file}"
-```
-
-#### 红线：禁止把整份 task.md 当 body
-
-无论场景 A / B，body 只能来自 `ai task issue-body` 的 stdout，**只含 描述 + 需求两段内容**（场景 A 为按模板字段映射后的等价内容）。
-
-错误示范（❌ 禁止）：把含 `## 分析` / `## 设计` / `## 实现备注` / `## 审查反馈` / `## 审查分歧账本` / `## 人工裁决` / `## 活动日志` / `## 完成检查清单` 等脚手架段落、以及 `#XXX` 占位的整份 task.md 直接作为 Issue body。这些段落只走 `sync-issue:{task-id}:task` 评论，绝不进 body。
-
-### 4. 解析 labels / Issue Type / milestone
-
-#### labels（粗选）
-
-- 调用 `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` 获取仓库实际存在的 label 列表（缓存为 set）
-- 按以下映射挑出"应有的 type label"，仅保留仓库 set 中实际存在的：
-
-  | task.md `type` | label |
-  |---|---|
-  | `bug`, `bugfix` | `type: bug` |
-  | `feature` | `type: feature` |
-  | `enhancement` | `type: enhancement` |
-  | `docs`, `documentation` | `type: documentation` |
-  | `dependency-upgrade` | `type: dependency-upgrade` |
-  | `task`, `chore` | `type: task` |
-  | `refactor`, `refactoring` | `type: enhancement` |
-  | 其它 | 跳过 |
-
-- `in:` label（粗选，宁缺毋滥）：根据任务标题与描述对 `labels.in` 中的模块名做语义匹配；明确提及或强烈暗示 → 添加 `in: {module}`；模糊或不确定 → 不添加。`in:` label 同样要求仓库实际存在。
-
-最终 label 集合若为空，省略 `--label` 参数。
-
-#### Issue Type fallback
-
-| task.md `type` | Issue Type |
-|---|---|
-| `bug`, `bugfix` | `Bug` |
-| `feature`, `enhancement` | `Feature` |
-| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 及其它 | `Task` |
-
-实际设置时按 `.agents/rules/issue-pr-commands.md` 的 "设置 Issue Type" 命令；仅当 owner type 为 `Organization` 时，先调 `gh api orgs/{owner}/issue-types` 列出 org 实际可用的 Type，并且仅当推断值在列表中时才设置；个人仓库、owner type 探测失败或设置失败都不阻断流程。
-
-#### milestone
-
-**必须执行，不得跳过**。本节是 `.agents/rules/milestone-inference.md` 阶段 1 的就地展开，语义与之对齐；不要把它当成"可选推断"。
-
-按以下编号步骤选取 milestone（优先级与阶段 1 严格一致）：
-
-1. 如果 `has_triage=false`：直接省略 `--milestone`，跳过本节。
-2. 列出仓库 open 状态的全部 milestone：
-   ```bash
-   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
-     --jq '.[].title'
-   ```
-3. 如果 `task.md` frontmatter 显式给出 `milestone` 字段，且该值出现在步骤 2 列表中：直接使用该值作为 `{milestone-arg}`，跳过步骤 4 / 5。
-4. 用正则 `^[0-9]+\.[0-9]+\.x$` 过滤步骤 2 结果。
-   - 非空：按 major、minor 数值升序排序，取最小的版本线作为 `{milestone-arg}`。
-5. 步骤 4 候选为空：尝试回退到 `General Backlog`。
-   - 步骤 2 结果中存在 `General Backlog`：使用该 milestone。
-   - 不存在 `General Backlog`：仅在此情况下省略 `--milestone`。
-6. 步骤 2 的 `gh api` 调用失败（网络 / 认证错误）：按"无候选"处理，落到步骤 5。
-
-设置成功时把版本线（或 `General Backlog` 或 task.md 显式值）作为 `{milestone-arg}` 带入步骤 5 的 `gh issue create` 命令；§5 末尾的展开规则保持不变。
-
-### 5. 调用 GitHub CLI 创建 Issue
-
-按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行；正文统一用 §3 生成的 `{body-file}`，覆盖通用命令的 `--body`：
+当 `create-task` 完成本地 `task.md` 落盘后，通过声明式内部命令创建 Issue：
 
 ```bash
-gh issue create -R "$upstream_repo" \
-  --title "{title}" \
-  --body-file "{body-file}" \
-  --assignee @me \
-  {label-args} \
-  {milestone-arg}
+agent-infra-internal platform-issue create {task-id} --agent {agent}
 ```
 
-- `{body-file}` 为 §3 由 `ai task issue-body` 生成的正文文件；**不得**改用 `--body` 自行拼装正文
-- `{label-args}` 由 §4 计算结果展开为多个 `--label "..."`；为空则整体省略
-- `{milestone-arg}` 仅当 `has_triage=true` 且 milestone 非空时展开为 `--milestone "..."`；否则整体省略
-- `--assignee @me` 不做权限预判，失败时静默跳过
-
-权限降级规则按 `.agents/rules/issue-sync.md`：`has_triage=false` 时跳过 label / milestone 设置；`has_push=false` 时跳过 Issue Type 设置；其余流程继续。
-
-创建成功后从输出中解析 Issue 编号（仅匹配 `https://.../issues/(\d+)` URL 形式，不要使用宽松正则）；解析失败时停止级联并把错误传回 `create-task`。
-
-### 6. 设置 Issue Type（可选）
+命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `issue_number`。
 
-仅当 `has_push=true`、owner type 为 `Organization`，且 §4 推断的 Issue Type 在 org 实际可用列表中时执行：
+创建后的初始元数据使用同一适配层同步：
 
 ```bash
-gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
-  -f type="{issue-type}" --silent
+agent-infra-internal platform-issue sync {task-id} --agent {agent} \
+  --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 
-设置失败不阻断流程。
-
-### 7. 设置 Issue 字段（可选）
-
-如果 `has_push=true`，读取 `.agents/rules/issue-fields.md`，按流程 A 写入 `task.md` 中适用且非空的 `priority`、`effort`、`start_date` 和 `target_date`。
-
-字段写入失败不阻断流程。
-
-### 8. 回写 task.md
-
-更新 task.md：
-
-- 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
-- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'`）
-
-> 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Create Task`），由调用方 SKILL 步骤 3 写入。
-
-### 9. 返回结果
-
-把以下信息回传给调用方 `create-task`：
-
-- Issue 编号 `{n}`
-- Issue URL（首选 `gh issue create` 输出中的 URL；缺失时拼 `https://github.com/$upstream_repo/issues/{n}`）
-- 实际应用的 labels / milestone / Issue Type
-
-`create-task` 据此选择"场景 A：已创建 Issue"输出分支并继续执行后续 task 评论同步与 status label 设置。
+## 结果处理
 
-## 错误处理
+- `planned|applied|no-op|degraded`：exit 0；调用方按 operations 继续评论同步。
+- `failed`：exit 1；调用方登记 `ISSUE_CREATE_FAILED` warning，不伪造绑定。
+- `blocked`：exit 2；认证、网络或创建 outcome 不确定，调用方保留远端 identity 证据并停止盲目重试。
+- 已绑定有效 Issue 时只验证绑定并返回 no-op，绝不重复创建。
 
-- 认证失败 / 命令不可用：返回结构化错误 `{code: "AUTH_FAILED", message}` 给 `create-task`，不修改 task.md
-- 网络超时 / DNS 失败：`{code: "NETWORK", message}`
-- 模板解析失败、Issue 编号解析失败、其它异常：`{code: "VALIDATION", message}`
-- 任意失败均不回滚 task.md；`create-task` 必须把结构化错误写入 `## 工作流告警`（`severity=ACTION_REQUIRED`，`code=ISSUE_CREATE_FAILED`，`target=issue`），再走"场景 C 失败兜底"输出，提示用户手动重试或在事后写入 `issue_number`
+自定义或空平台返回 no-op/degraded；调用方不得回退到直接 `gh issue` 或 GraphQL 编排。

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

@@ -1,5 +1,5 @@
 # Issue 创建
 
-当前代码平台未提供 Issue 创建规则。
+当前代码平台未提供 Issue 适配器；`platform-issue create` 返回结构化 no-op/degraded 结果。
 
 `create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `code-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。

package/templates/.agents/rules/human-decision-context.en.md

@@ -0,0 +1,36 @@
+# Human Decision Context Contract
+
+This rule governs every new `[needs-human-decision]` detail block produced by analyze, plan, code, and their three review workflows. Historical details do not need migration.
+
+## Self-contained Context
+
+A maintainer must be able to decide without asking a model to reconstruct context. Every item must state its background, decision objective, impact scope, risks, recommended option, and recommendation rationale. It must provide at least two options, each with both benefits and costs.
+
+## Canonical Structure
+
+```markdown
+### {AN-N|PL-N|CD-N|HD-N}: {Title} [needs-human-decision]
+
+- **Background**: {facts, constraints, and why a decision is needed}
+- **Decision Objective**: {the single choice that must be made}
+- **Impact Scope**: {affected behavior, files, users, or precedent}
+- **Risks**: {risks of the wrong choice, delay, or no decision}
+- **Recommended Option**: {Option A/B/...}
+- **Recommendation Rationale**: {reason based on benefits, costs, and constraints}
+
+#### Option A: {Name}
+
+- **Benefits**: {benefits of this option}
+- **Costs**: {costs and limitations of this option}
+
+#### Option B: {Name}
+
+- **Benefits**: {benefits of this option}
+- **Costs**: {costs and limitations of this option}
+```
+
+Option C and supporting evidence may be added, but none of the fields above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row, whose evidence must point to this stable heading anchor.
+
+## Decision Closure
+
+Use `ai task decisions <task-ref> <ordinal|ledger-id>` to inspect full context and `ai decide <task-ref> <ordinal|ledger-id> <decision>` to record the ruling. `ai decide` updates the row to `human-decided`, creates an independent `HDR-N` record, and updates evidence and the activity log; do not manually imitate only part of that transaction.

package/templates/.agents/rules/human-decision-context.zh-CN.md

@@ -0,0 +1,36 @@
+# 人工裁决上下文契约
+
+本规则约束 analyze、plan、code 及三类 review 工作流中新建的所有 `[needs-human-decision]` 详情块。历史详情无需迁移。
+
+## 自足性要求
+
+详情必须让维护者无需模型二次推理即可理解并裁决。每项必须明确说明背景、裁决目标、影响范围、风险、推荐方案与推荐理由，并至少提供两个可选方案；每个方案都必须同时列出收益和代价。
+
+## 规范结构
+
+```markdown
+### {AN-N|PL-N|CD-N|HD-N}：{标题} [needs-human-decision]
+
+- **背景**：{为何需要裁决；已知事实与约束}
+- **裁决目标**：{本次必须确定的唯一选择}
+- **影响范围**：{受影响的功能、文件、用户或后续先例}
+- **风险**：{错误选择、延期或不裁决的风险}
+- **推荐方案**：{方案 A/B/...}
+- **推荐理由**：{基于收益、代价和约束的理由}
+
+#### 方案 A：{名称}
+
+- **收益**：{选择该方案的收益}
+- **代价**：{选择该方案的成本与局限}
+
+#### 方案 B：{名称}
+
+- **收益**：{选择该方案的收益}
+- **代价**：{选择该方案的成本与局限}
+```
+
+可增加方案 C 或补充证据，但不得省略上述字段或把多个方案压缩为无法分别比较的一行。标题 ID 必须与 task.md `## 审查分歧账本` 行一致，evidence 必须指向该标题的稳定锚点。
+
+## 裁决闭环
+
+使用 `ai task decisions <task-ref> <序号|账本ID>` 查看完整详情，使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 写入裁决。`ai decide` 负责把目标行更新为 `human-decided`、创建独立 `HDR-N` 记录、更新 evidence 与活动日志；不得手工模拟其中一部分写入。

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

@@ -1,155 +1,11 @@
 # Issue Fields
 
-Read this file before writing or verifying Issue Type pinned custom fields.
-
-## Boundary
-
-- Use this rule only after `upstream_repo`, `has_push`, and the Issue number are known.
-- If `has_push=false`, skip direct field writes and continue.
-- Fetch the organization's current Issue Type schema before each write; do not hard-code the field set.
-- Missing, empty, or unresolvable values are skipped. Field writes are best-effort and must not block the workflow.
-
-## Supported Task Frontmatter
-
-All fields are optional:
-
-| task.md field | Issue field | Value format |
-|---|---|---|
-| `priority` | `Priority` | `Urgent`, `High`, `Medium`, or `Low` |
-| `effort` | `Effort` | `High`, `Medium`, or `Low` |
-| `start_date` | `Start date` | `YYYY-MM-DD` |
-| `target_date` | `Target date` | `YYYY-MM-DD` |
-
-Localized option input may be normalized before writing:
-
-| Input | Stored option |
-|---|---|
-| `紧急` | `Urgent` |
-| `高` | `High` |
-| `中` | `Medium` |
-| `低` | `Low` |
-
-AI agents may infer `priority` and `effort` from the title and description when creating or refining tasks. Date fields are factual, not estimated: `start_date` is written by the analyze stage (the analysis start date) and `target_date` by the complete stage (the completion date). Human edits in `task.md` take precedence.
-
-## GraphQL Reference
-
-Read Issue Type pinned fields:
-
-```graphql
-query($owner:String!){
-  organization(login:$owner){ issueTypes(first:20){ nodes{
-    id name
-    pinnedFields{
-      __typename
-      ... on IssueFieldSingleSelect{ id name options{ id name } }
-      ... on IssueFieldDate{ id name }
-      ... on IssueFieldText{ id name }
-      ... on IssueFieldNumber{ id name }
-    }
-  } } }
-}
-```
-
-Read one Issue's current type and field values:
-
-```graphql
-query($owner:String!,$name:String!,$number:Int!){
-  repository(owner:$owner,name:$name){ issue(number:$number){
-    id
-    issueType{ name pinnedFields{
-      __typename
-      ... on IssueFieldSingleSelect{ id name options{ id name } }
-      ... on IssueFieldDate{ id name }
-      ... on IssueFieldText{ id name }
-      ... on IssueFieldNumber{ id name }
-    } }
-    issueFieldValues(first:50){ nodes{
-      __typename
-      ... on IssueFieldSingleSelectValue{ name optionId field{ ... on IssueFieldSingleSelect{ name } } }
-      ... on IssueFieldDateValue{ value field{ ... on IssueFieldDate{ name } } }
-      ... on IssueFieldTextValue{ value field{ ... on IssueFieldText{ name } } }
-      ... on IssueFieldNumberValue{ value field{ ... on IssueFieldNumber{ name } } }
-    } }
-  } }
-}
-```
-
-Write or clear fields and update Issue Type:
-
-```graphql
-mutation($issueId:ID!,$issueFields:[IssueFieldCreateOrUpdateInput!]!){
-  setIssueFieldValue(input:{issueId:$issueId,issueFields:$issueFields}){ issue{ id } }
-}
-
-mutation($issueId:ID!,$issueTypeId:ID){
-  updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$issueTypeId}){ issue{ id } }
-}
-```
-
-`IssueFieldCreateOrUpdateInput` supports `fieldId`, `singleSelectOptionId`, `dateValue`, `textValue`, `numberValue`, and `delete`.
-
-Minimal command shells:
+Synchronize Issue Type and pinned fields through one intent:
 
 ```bash
-gh api graphql \
-  -f query='query($owner:String!){organization(login:$owner){issueTypes(first:20){nodes{id name pinnedFields{__typename ... on IssueFieldSingleSelect{id name options{id name}} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}}}}}' \
-  -F owner="{owner}"
-
-gh api graphql \
-  -f query='query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){id issueType{name pinnedFields{__typename ... on IssueFieldSingleSelect{id name options{id name}} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}} issueFieldValues(first:50){nodes{__typename ... on IssueFieldSingleSelectValue{name optionId field{... on IssueFieldSingleSelect{name}}} ... on IssueFieldDateValue{value field{... on IssueFieldDate{name}}} ... on IssueFieldTextValue{value field{... on IssueFieldText{name}}} ... on IssueFieldNumberValue{value field{... on IssueFieldNumber{name}}}}}}}}' \
-  -F owner="{owner}" -F name="{repo}" -F number="{issue-number}"
-
-gh api graphql --input - <<'JSON'
-{
-  "query": "mutation($issueId:ID!,$issueFields:[IssueFieldCreateOrUpdateInput!]!){setIssueFieldValue(input:{issueId:$issueId,issueFields:$issueFields}){issue{id}}}",
-  "variables": {
-    "issueId": "{issue-id}",
-    "issueFields": [
-      { "fieldId": "{field-id}", "singleSelectOptionId": "{option-id}" },
-      { "fieldId": "{date-field-id}", "dateValue": "YYYY-MM-DD" },
-      { "fieldId": "{old-field-id}", "delete": true }
-    ]
-  }
-}
-JSON
-
-gh api graphql --input - <<'JSON'
-{
-  "query": "mutation($issueId:ID!,$issueTypeId:ID){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$issueTypeId}){issue{id}}}",
-  "variables": {
-    "issueId": "{issue-id}",
-    "issueTypeId": "{issue-type-id}"
-  }
-}
-JSON
+agent-infra-internal platform-issue sync {task-id} --agent {agent} --issue-type --fields
 ```
 
-Values not listed in the localization table are treated as literal option names, which is intended for canonical English input.
-
-## Flow A: Write Fields After Issue Creation
-
-1. Stop if `has_push` is not `true`.
-2. Resolve `{owner}` from `$upstream_repo` and query `organization.issueTypes`.
-3. Select the target Issue Type's `pinnedFields`.
-4. Read non-empty `priority`, `effort`, `start_date`, and `target_date` values from `task.md`.
-5. For each value:
-   - Skip it when the target type does not pin a same-name field.
-   - For single-select fields, normalize localized input and match the option by name.
-   - For date fields, write only `YYYY-MM-DD` values.
-6. Submit one `setIssueFieldValue` mutation with all resolved inputs. If no input remains, skip.
-
-## Flow B: Set Type And Migrate Fields
-
-Use this flow whenever an existing Issue Type is changed.
-
-1. Stop if `has_push` is not `true`.
-2. Read the Issue id, current Issue Type, pinned fields, and current field values.
-3. Query the organization Issue Type list and resolve the target Issue Type id.
-4. Run `updateIssueIssueType` with the target Issue Type id.
-5. Resolve the target type's pinned fields.
-6. For each old field value:
-   - If the target type has a same-name field, write the value again. For single-select values, resolve the target option id by option name.
-   - If the target type does not have a same-name field, send `{ fieldId, delete: true }` for the old field.
-7. Submit one `setIssueFieldValue` mutation with all migration inputs. Empty migrations are skipped.
+Supported task.md mappings are `priority` → `Priority`, `effort` → `Effort`, `start_date` → `Start date`, and `target_date` → `Target date`. The core normalizes localized priority/effort options and validates `YYYY-MM-DD` dates.
 
-Both flows are idempotent. Rewriting an unchanged value or deleting an already empty field is acceptable.
+The adapter reads the organization's current schema on every run and never hardcodes Type, field, or option IDs. When Type changes it migrates same-name values and deletes values unsupported by the target Type. Personal repositories or `push=false` skip only Type/field operations.