@fitlab-ai/agent-infra 0.6.0 → 0.6.2-alpha.1

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

@@ -0,0 +1,155 @@
+# 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, but must keep date fields empty unless the user or source Issue provides explicit dates. 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:
+
+```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
+```
+
+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.
+
+Both flows are idempotent. Rewriting an unchanged value or deleting an already empty field is acceptable.

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

@@ -0,0 +1,155 @@
+# Issue 字段
+
+写入或校验 Issue Type pinned custom fields 前先读取本文件。
+
+## 边界
+
+- 仅在已知 `upstream_repo`、`has_push` 和 Issue 编号后使用本规则。
+- 如果 `has_push=false`，跳过直接字段写入并继续流程。
+- 每次写入前都读取组织当前 Issue Type schema；不要硬编码字段集合。
+- 缺失、空值或无法解析的值直接跳过。字段写入是 best-effort，不应阻断工作流。
+
+## 支持的 task.md frontmatter
+
+所有字段均可选：
+
+| task.md 字段 | Issue 字段 | 值格式 |
+|---|---|---|
+| `priority` | `Priority` | `Urgent`、`High`、`Medium` 或 `Low` |
+| `effort` | `Effort` | `High`、`Medium` 或 `Low` |
+| `start_date` | `Start date` | `YYYY-MM-DD` |
+| `target_date` | `Target date` | `YYYY-MM-DD` |
+
+写入前可规范化本地化选项：
+
+| 输入 | 写入选项 |
+|---|---|
+| `紧急` | `Urgent` |
+| `高` | `High` |
+| `中` | `Medium` |
+| `低` | `Low` |
+
+AI agent 在创建或修订任务时可根据标题与描述推断 `priority` 和 `effort`，但除非用户或来源 Issue 明确提供日期，否则必须保持日期字段为空。`task.md` 中人工填写的值优先。
+
+## GraphQL 参考
+
+读取 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 }
+    }
+  } } }
+}
+```
+
+读取单个 Issue 的当前 type 与字段值：
+
+```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 } } }
+    } }
+  } }
+}
+```
+
+写入或清空字段，以及更新 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` 支持 `fieldId`、`singleSelectOptionId`、`dateValue`、`textValue`、`numberValue` 和 `delete`。
+
+最小命令壳：
+
+```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
+```
+
+未列入本地化映射表的值会按字面量 option name 处理；这是为了支持规范英文输入。
+
+## 流程 A：创建 Issue 后写入字段
+
+1. 如果 `has_push` 不是 `true`，停止本流程。
+2. 从 `$upstream_repo` 解析 `{owner}`，查询 `organization.issueTypes`。
+3. 选择目标 Issue Type 的 `pinnedFields`。
+4. 从 `task.md` 读取非空的 `priority`、`effort`、`start_date` 和 `target_date`。
+5. 对每个值：
+   - 目标 type 未 pin 同名字段时跳过。
+   - single-select 字段先规范化本地化输入，再按 option name 匹配。
+   - date 字段只写入 `YYYY-MM-DD` 值。
+6. 用所有已解析 input 一次性提交 `setIssueFieldValue` mutation。没有 input 时跳过。
+
+## 流程 B：设置 Type 并迁移字段
+
+现有 Issue Type 发生变更时使用本流程。
+
+1. 如果 `has_push` 不是 `true`，停止本流程。
+2. 读取 Issue id、当前 Issue Type、pinned fields 和当前字段值。
+3. 查询组织 Issue Type 列表，解析目标 Issue Type id。
+4. 用目标 Issue Type id 执行 `updateIssueIssueType`。
+5. 解析目标 type 的 pinned fields。
+6. 对每个旧字段值：
+   - 目标 type 有同名字段时重新写入该值。single-select 值按 option name 在目标 type 中重新解析 option id。
+   - 目标 type 没有同名字段时，对旧字段发送 `{ fieldId, delete: true }`。
+7. 用所有迁移 input 一次性提交 `setIssueFieldValue` mutation。迁移 input 为空时跳过。
+
+两个流程均应保持幂等。重复写入未变化的值或删除已为空字段都是可接受的。

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

@@ -88,6 +88,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-typ
 ```
 
 - set the Issue Type only when `has_push=true`; otherwise skip and continue
+- when changing an existing Issue Type, read `.agents/rules/issue-fields.md` and use Flow B so same-name pinned fields are migrated and fields absent from the new type are cleared
 
 ## Update Issues
 

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

@@ -88,6 +88,7 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH -f type="{issue-typ
 ```
 
 - 仅当 `has_push=true` 时执行 Issue Type 设置；否则跳过并继续
+- 变更现有 Issue Type 时，先读取 `.agents/rules/issue-fields.md` 并使用流程 B，确保同名 pinned fields 迁移，且新 type 不包含的字段被清空
 
 ## Issue 更新
 

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

@@ -48,6 +48,7 @@ Operation-to-permission mapping:
 | 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 |
 
@@ -55,7 +56,7 @@ Operation-to-permission mapping:
 
 | Level | Operation type | With permission | Without permission |
 |------|---------|--------|--------|
-| silent degradation | label / milestone / Issue Type | run the `gh` command directly and also update the task comment | skip direct `gh` writes, update only the task comment, let the bot backfill |
+| 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 |
 

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

@@ -48,6 +48,7 @@ has_push=$(printf '%s' "$repo_perms" | grep -q '"push":true' 2>/dev/null && echo
 | 设置/移除 milestone | `has_triage` | 同上 |
 | 编辑 Issue body | `has_triage` | 需求复选框同步使用 |
 | 设置 Issue Type | `has_push` | 需要 write 权限 |
+| 设置 Issue 字段 | `has_push` | pinned custom fields；失败不阻断 |
 | 设置 assignee | 不检测 | 无权限时直接跳过 |
 | 发布/更新评论 | 无需检测 | 公开仓库中认证用户可执行 |
 
@@ -55,7 +56,7 @@ has_push=$(printf '%s' "$repo_perms" | grep -q '"push":true' 2>/dev/null && echo
 
 | 层级 | 操作类型 | 有权限 | 无权限 |
 |------|---------|--------|--------|
-| 静默降级 | label / milestone / Issue Type | 直接执行 `gh` 命令，同时更新 task 留言 | 跳过 `gh` 直接操作，仅更新 task 留言，由 bot 补位 |
+| 静默降级 | label / milestone / Issue Type / Issue 字段 | 直接执行 `gh` 命令，同时更新 task 留言 | 跳过 `gh` 直接操作，仅更新 task 留言，由 bot 补位 |
 | 直接跳过 | assignee | 直接执行 `gh` 命令 | 不做任何替代 |
 | 正常执行 | 评论 | 正常执行 | 正常执行 |
 

package/templates/.agents/rules/release-commands.github.en.md

@@ -1,6 +1,6 @@
 # Release Platform Commands
 
-Read this file before loading release history, querying merged PRs, or creating a draft release.
+Read this file before loading release history, querying merged PRs, or publishing the Release notes.
 
 ## Query Releases
 
@@ -37,10 +37,16 @@ gh issue view {issue-number} --json number,title,labels,url,author
 
 Map GitHub no-reply emails with this rule: if `Name <email>` contains an email matching `(\d+\+)?(\S+?)@users\.noreply\.github\.com`, use the second capture group lowercased as the login. This covers both `{id}+{login}@users.noreply.github.com` and `{login}@users.noreply.github.com`.
 
-## Create a Draft Release
+## Publish the Release Notes
+
+The GitHub Release for `v{version}` is created and published automatically by the release workflow so Homebrew bottles have a stable upload target. This command writes the curated notes onto that existing Release, falling back to creating it if it does not exist yet.
 
 ```bash
-gh release create "v{version}" --draft --title "v{version}" --notes-file "{notes-file}"
+if gh release view "v{version}" >/dev/null 2>&1; then
+  gh release edit "v{version}" --notes-file "{notes-file}"
+else
+  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
+fi
 ```
 
 If commands fail, stop or escalate according to the calling skill.

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

@@ -1,6 +1,6 @@
 # Release 平台命令
 
-在读取历史 release、查询已合并 PR，或创建 draft release 前先读取本文件。
+在读取历史 release、查询已合并 PR，或发布 Release notes 前先读取本文件。
 
 ## Release 查询
 
@@ -37,10 +37,16 @@ gh issue view {issue-number} --json number,title,labels,url,author
 
 GitHub no-reply 邮箱映射规则：如果 `Name <email>` 中的 email 匹配 `(\d+\+)?(\S+?)@users\.noreply\.github\.com`，使用第二个捕获组的小写形式作为 login。该规则同时覆盖 `{id}+{login}@users.noreply.github.com` 和 `{login}@users.noreply.github.com`。
 
-## 创建 Draft Release
+## 发布 Release notes
+
+`v{version}` 的 GitHub Release 由 release 工作流自动创建并发布，为 Homebrew bottle 提供稳定的上传落点。本命令把精修后的 notes 写到这个已存在的 Release 上；若 Release 尚不存在则兜底创建。
 
 ```bash
-gh release create "v{version}" --draft --title "v{version}" --notes-file "{notes-file}"
+if gh release view "v{version}" >/dev/null 2>&1; then
+  gh release edit "v{version}" --notes-file "{notes-file}"
+else
+  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
+fi
 ```
 
 失败时按调用方规则停止或提示人工介入。

package/templates/.agents/rules/task-management.en.md

@@ -13,16 +13,24 @@ Map user intent to the corresponding workflow command:
 ## Task State Management
 
 - Update the corresponding `task.md` immediately after every workflow command
-- At minimum, synchronize `current_step`, `updated_at`, `assigned_to`, and the current-round artifact reference
+- At minimum, synchronize `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`, and the current-round artifact reference
+- Before updating `agent_infra_version`, read `.agents/rules/version-stamp.md`
 - Activity Log entries are append-only and must never overwrite history
 
 ## Required State Updates by Command
 
-- `import-issue`: update `current_step`, `updated_at`, `assigned_to`
-- `analyze-task`: update `current_step`, `updated_at`, `assigned_to`
-- `plan-task`: update `current_step`, `updated_at`
-- `implement-task`: update `current_step`, `updated_at`
-- `review-task`: update `current_step`, `updated_at`
-- `refine-task`: update `current_step`, `updated_at`
-- `complete-task`: update `status`, `completed_at`, `updated_at`
-- `block-task`: update `status`, `blocked_at`, `blocked_reason`
+- `create-task`: create `branch`, `workflow`, `status`, `created_at`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `import-issue`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `import-codescan`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `import-dependabot`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `restore-task`: update `status`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `analyze-task`: update `current_step`, `updated_at`, `assigned_to`, `agent_infra_version`
+- `plan-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `implement-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `review-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `refine-task`: update `current_step`, `updated_at`, `agent_infra_version`
+- `create-pr`: update `pr_number`, `updated_at`, `agent_infra_version`
+- `commit`: update `updated_at`, `agent_infra_version`; update `current_step` when needed (see `commit/reference/task-status-update.md`)
+- `complete-task`: update `status`, `current_step`, `completed_at`, `updated_at`, `agent_infra_version`
+- `block-task`: update `status`, `blocked_at`, `blocked_reason`, `updated_at`, `agent_infra_version`
+- `cancel-task`: update `status`, `cancelled_at`, `cancel_reason`, `updated_at`, `agent_infra_version`

package/templates/.agents/rules/task-management.zh-CN.md

@@ -13,16 +13,24 @@
 ## 任务状态管理
 
 - 每次执行工作流命令后，必须立即更新对应任务的 `task.md`
-- 至少同步 `current_step`、`updated_at`、`assigned_to`，以及本轮产物引用
+- 至少同步 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`，以及本轮产物引用
+- 更新 `agent_infra_version` 前，先读取 `.agents/rules/version-stamp.md`
 - Activity Log 只能追加，不能覆盖历史记录
 
 ## 常见命令的状态更新要求
 
-- `import-issue`：更新 `current_step`、`updated_at`、`assigned_to`
-- `analyze-task`：更新 `current_step`、`updated_at`、`assigned_to`
-- `plan-task`：更新 `current_step`、`updated_at`
-- `implement-task`：更新 `current_step`、`updated_at`
-- `review-task`：更新 `current_step`、`updated_at`
-- `refine-task`：更新 `current_step`、`updated_at`
-- `complete-task`：更新 `status`、`completed_at`、`updated_at`
-- `block-task`：更新 `status`、`blocked_at`、`blocked_reason`
+- `create-task`：创建 `branch`、`workflow`、`status`、`created_at`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `import-issue`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `import-codescan`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `import-dependabot`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `restore-task`：更新 `status`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `analyze-task`：更新 `current_step`、`updated_at`、`assigned_to`、`agent_infra_version`
+- `plan-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `implement-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `review-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `refine-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
+- `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
+- `commit`：更新 `updated_at`、`agent_infra_version`；必要时更新 `current_step`（详见 `commit/reference/task-status-update.md`）
+- `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`
+- `block-task`：更新 `status`、`blocked_at`、`blocked_reason`、`updated_at`、`agent_infra_version`
+- `cancel-task`：更新 `status`、`cancelled_at`、`cancel_reason`、`updated_at`、`agent_infra_version`

package/templates/.agents/rules/testing-discipline.en.md

@@ -0,0 +1,40 @@
+# Common Rule - Testing Discipline
+
+> This file carries detailed examples for test-writing discipline. AGENTS.md (and CLAUDE.md) keep only concise testing rules and point here to avoid inflating high-frequency context.
+
+## Background
+
+A batch of fragile keyword-matching assertions once had to be replaced with structural checks (valid frontmatter, step numbering, reference integrity, zh-CN variants, and size thresholds). Lesson: binding tests to natural-language wording, or using assertions to "remember a deleted concept", creates endless test debt.
+
+## Example: do not add negative assertions when a positive assertion already covers the behavior
+
+When a positive assertion already covers the expected behavior, do not add another negative assertion for "the opposite should not appear".
+
+Bad:
+```ts
+assert.match(content, /^name: implement-task$/m);    // The positive assertion already covers the expected value.
+assert.doesNotMatch(content, /^name: wrong-name$/m); // Redundant: permanently remembers a value that should not appear.
+```
+
+Good:
+```ts
+assert.match(content, /^name: implement-task$/m);    // The positive assertion is enough.
+```
+
+If the positive assertion passes, the value is correct. The extra negative assertion adds no protection, only maintenance cost, and can become a test that permanently remembers a concept after the feature is gone.
+
+## RED-GREEN-REFACTOR rhythm
+
+During implementation, turn the requirement into a test for observable behavior before writing the code:
+
+1. **RED**: First write a failing test that reproduces the requirement or defect, and confirm that it really fails. The test should cover business behavior, inputs and outputs, or user-visible results, not internal implementation details.
+2. **GREEN**: Write the smallest amount of code needed to make the failing test pass. Do not expand behavior that is not covered by the test or the requirement.
+3. **REFACTOR**: After the tests are green, clean up names, structure, or duplication; keep the same test set passing before and after the refactor.
+
+This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success criterion first, then make the implementation satisfy it.
+
+## Test anti-patterns
+
+- **Over-mocking**: Stub only real boundaries such as network, filesystem, time, or randomness; do not mock the logic of the unit under test, or the test only proves that the mock followed the script.
+- **Testing implementation details**: Prefer assertions on public APIs, artifacts, state changes, or error results; avoid assertions on private functions, internal call order, or temporary data structures.
+- **Insufficient assertions**: Assertions must pin down concrete expected values; do not replace checks on key fields, counts, and boundaries with "does not throw" or "result exists".

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -0,0 +1,40 @@
+# 通用规则 - 测试编写纪律
+
+> 本文件承载测试编写的正反例细节；AGENTS.md（及 CLAUDE.md）的「测试编写规约」只保留精简条目并指向此处，避免高频上下文膨胀。
+
+## 背景
+
+曾有一批脆弱的关键词匹配断言需要整体替换为结构性检查（frontmatter 合法性、步骤编号、引用完整性、zh-CN 变体、体积阈值）。教训：绑定自然语言措辞、或用断言"记住一个已删除概念"，都会形成无止境的测试债务。
+
+## 正反例：正向断言已覆盖时，不应再加反向断言
+
+当正向断言已覆盖期望行为，就不要再为"反面不应出现"补一条反向断言。
+
+❌ 反例：
+```ts
+assert.match(content, /^name: implement-task$/m);    // 正向已覆盖期望值
+assert.doesNotMatch(content, /^name: wrong-name$/m); // 多余：永久记住一个不该出现的值
+```
+
+✅ 正例：
+```ts
+assert.match(content, /^name: implement-task$/m);    // 正向断言已足够
+```
+
+正向断言通过即证明值正确；额外的反向断言不增加保护，只增加维护成本，并会在功能删除后退化为"测试永久记住一个不再存在的概念"。
+
+## RED-GREEN-REFACTOR 节奏
+
+实现阶段先把需求转成可观察行为的测试，再写代码：
+
+1. **RED**：先写一个能复现需求或缺陷的失败用例，并确认它确实失败。测试应覆盖业务行为、输入输出或用户可见结果，不绑定内部实现细节。
+2. **GREEN**：写最少代码让失败用例通过。不要顺手扩展未被测试和未被需求覆盖的行为。
+3. **REFACTOR**：在测试全绿后整理命名、结构或重复代码；重构前后保持同一组测试通过。
+
+这与 AGENTS.md 的「目标驱动执行」一致：先定义可验证成功标准，再让实现满足它。
+
+## 测试反模式
+
+- **mock 过度**：只在网络、文件系统、时间、随机数等真实边界打桩；不要 mock 被测对象自身逻辑，否则测试只验证 mock 是否按预设运行。
+- **测试实现细节**：优先断言公开接口、产物、状态变化或错误结果；避免断言私有函数、内部调用顺序、临时数据结构。
+- **断言不充分**：断言必须锁定具体期望值；不要用"只要不抛异常""结果存在即可"替代对关键字段、数量和边界的验证。

package/templates/.agents/rules/version-stamp.en.md

@@ -0,0 +1,29 @@
+# General Rule - agent-infra Version Stamp
+
+## When to Write
+
+Every time a workflow creates or updates `task.md` frontmatter, also write `agent_infra_version`.
+
+This field records the `agent-infra` CLI version that last wrote the task metadata, and is refreshed together with `updated_at`.
+
+## Value Command
+
+```bash
+agent_infra_version=$(ai version --raw 2>/dev/null || echo "unknown")
+```
+
+- On success, write the command output directly, for example `vX.Y.Z` or `vX.Y.Z-alpha.0`
+- Do not add the `v` prefix in the writer
+- If the command fails, write `unknown`
+
+## Frontmatter Field
+
+```yaml
+agent_infra_version: {agent_infra_version}
+```
+
+## Compatibility
+
+- Historical tasks may not have this field; reading or restoring tasks must not block on that alone
+- When present, the value must be `vX.Y.Z`, `vX.Y.Z-prerelease`, a version with SemVer build metadata, or `unknown`
+- Issue / PR comment sync does not need special handling; frontmatter mirroring naturally includes this field

package/templates/.agents/rules/version-stamp.zh-CN.md

@@ -0,0 +1,29 @@
+# 通用规则 - agent-infra 版本戳
+
+## 写入时机
+
+每次创建或更新 `task.md` frontmatter 时，同步写入 `agent_infra_version`。
+
+该字段表示最后一次写入该任务元数据的 `agent-infra` CLI 版本，与 `updated_at` 同步刷新。
+
+## 取值命令
+
+```bash
+agent_infra_version=$(ai version --raw 2>/dev/null || echo "unknown")
+```
+
+- 命令成功时，值必须直接使用输出结果，例如 `vX.Y.Z` 或 `vX.Y.Z-alpha.0`
+- 不要在写入端自行拼接 `v` 前缀
+- 命令失败时写入 `unknown`
+
+## frontmatter 字段
+
+```yaml
+agent_infra_version: {agent_infra_version}
+```
+
+## 兼容性
+
+- 历史任务可能缺少该字段；读取或恢复任务时不得因此阻塞
+- 字段存在时，值必须是 `vX.Y.Z`、`vX.Y.Z-prerelease`、带 SemVer build 元数据的版本，或 `unknown`
+- 同步 Issue / PR 评论时无需额外处理；frontmatter 镜像会自然包含该字段