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

package/templates/.agents/skills/review-task/SKILL.en.md

@@ -12,6 +12,16 @@ Review the latest implementation round and produce `review.md` or `review-r{N}.m
 - This skill reviews code and writes a report; it does not modify product code
 - After executing this skill, you **must** immediately update task.md
 
+Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
+
+## Common Rationalizations and Rebuttals
+
+| Rationalization | Rebuttal |
+|------|------|
+| "It was only one line, so it cannot affect behavior." | Line count is not impact; read the full `git diff` and trace the downstream effect of each change. |
+| "It looks mostly fine, so approve it." | The verdict must be backed by blocker/major/minor counts, and every finding must cite file:line; do not approve from impression. |
+| "The test change looks reasonable, so I can skim it." | Before reviewing test changes, check `.agents/rules/testing-discipline.md` item by item (see the step 4 gate). |
+
 ## Steps
 
 ### 1. Verify Prerequisites
@@ -35,6 +45,7 @@ Read the highest-round implementation artifact and, if present, the highest-roun
 Follow `.agents/workflows/feature-development.yaml` and inspect `git diff` for the full change context.
 
 > Detailed review criteria, severity rules, and reviewer expectations live in `reference/review-criteria.md`. Read `reference/review-criteria.md` before reviewing.
+> Test review gate: when `git diff` touches test files, read `.agents/rules/testing-discipline.md` first and check it item by item, especially "do not add negative assertions when a positive assertion already covers the behavior".
 
 ### 5. Write the Review Report
 
@@ -51,7 +62,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 ```
 
 Update task.md and append:
-`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n} → {artifact-filename}`
+`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {artifact-filename}`
+
+Omit the bracketed segment when env-blocked = 0; append ` (+ {n} env-blocked)` when env-blocked > 0.
 
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
 - Read `.agents/rules/issue-sync.md` before syncing, and complete upstream repository detection plus permission detection
@@ -84,6 +97,8 @@ Choose exactly one branch based on the findings:
 - blockers that can be fixed in a focused pass -> changes requested
 - major redesign or re-implementation needed -> rejected
 
+env-blocked counts do not influence branch selection; they are appended to the summary line only.
+
 > The full four-branch output templates, selection rules, and prohibition clauses live in `reference/output-templates.md`. Read `reference/output-templates.md` before reporting the review result.
 
 Include all TUI command formats in the next-step output. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).

package/templates/.agents/skills/review-task/SKILL.zh-CN.md

@@ -12,6 +12,16 @@ description: "审查任务实现并输出代码审查报告"
 - 本技能只审查代码并写报告，不修改业务代码
 - 执行本技能后，你**必须**立即更新 task.md
 
+版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
+
+## 常见违规借口与反驳
+
+| 借口 | 反驳 |
+|------|------|
+| 「只改了一行，不影响功能」 | 行数不等于影响面；必须读完整 `git diff` 并定位每处改动的下游效果。 |
+| 「大体没问题，给个 Approved」 | 结论必须由 blocker/major/minor 计数支撑，每个问题引用文件:行号，不能凭印象放行。 |
+| 「测试改动看着合理，跳过细看」 | 审查测试变更前必须逐条核对 `.agents/rules/testing-discipline.md`（见步骤 4 门禁）。 |
+
 ## 执行步骤
 
 ### 1. 验证前置条件
@@ -35,6 +45,7 @@ description: "审查任务实现并输出代码审查报告"
 遵循 `.agents/workflows/feature-development.yaml`，并同时检查 `git diff` 获取完整变更上下文。
 
 > 详细审查标准、严重程度划分和 reviewer 关注点见 `reference/review-criteria.md`。执行此步骤前先读取 `reference/review-criteria.md`。
+> 测试审查硬门禁：当 `git diff` 触及测试文件时，必须先读取 `.agents/rules/testing-discipline.md` 并逐条核对（尤其"正向已覆盖时不应再加反向断言"）。
 
 ### 5. 编写审查报告
 
@@ -51,7 +62,9 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 ```
 
 更新 task.md，并追加：
-`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n} → {artifact-filename}`
+`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Review (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}[ (+ {n} env-blocked)] → {artifact-filename}`
+
+env-blocked = 0 时省略括号部分；env-blocked > 0 时附加 ` (+ {n} env-blocked)`。
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测
@@ -84,6 +97,8 @@ node .agents/scripts/validate-artifact.js gate review-task .agents/workspace/act
 - 有 blocker，且可集中修复 -> 需要修改
 - 需要重大返工或重新实现 -> 拒绝
 
+env-blocked 的数量不参与分支选择，仅在数字摘要末尾附带显示。
+
 > 完整的 4 分支输出模板、判断规则和禁止条款见 `reference/output-templates.md`。向用户汇报审查结论前先读取 `reference/output-templates.md`。
 
 向用户展示下一步时，必须包含所有 TUI 命令格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。

package/templates/.agents/skills/review-task/config/verify.json

@@ -9,6 +9,7 @@
         "status",
         "created_at",
         "updated_at",
+        "agent_infra_version",
         "current_step",
         "assigned_to"
       ]
@@ -18,6 +19,7 @@
       "required_sections": [
         "审查摘要",
         "问题清单",
+        "环境性遗留",
         "结论与建议"
       ],
       "required_patterns": [
@@ -36,6 +38,7 @@
       "verify_comment_content": true,
       "verify_task_comment_content": true,
       "verify_issue_type": true,
+      "verify_issue_fields": false,
       "verify_milestone": true,
       "expected_status_label_key": "inProgress",
       "expected_comment_marker_key": "artifact"

package/templates/.agents/skills/review-task/reference/output-templates.en.md

@@ -4,8 +4,8 @@ Read this file before presenting the final review result to the user.
 
 ## Choose Exactly One Output Branch
 
-Apply these rules in order:
-1. if `Blocker = 0` and `Major = 0` and `Minor = 0`, use Branch A
+Apply these rules in order (**note: env-blocked counts do not participate in selection**):
+1. if `Blocker = 0` and `Major = 0` and `Minor = 0`, use Branch A (regardless of whether env-blocked > 0)
 2. if `Blocker = 0` and (`Major > 0` or `Minor > 0`), use Branch B
 3. if `Blocker > 0` and the work can be repaired in a focused refinement pass, use Branch C
 4. if the task requires major redesign, broad reimplementation, or a restart, use Branch D
@@ -14,25 +14,30 @@ Prohibitions:
 - never skip the branch-selection step
 - never mix text from different branches
 - if `Blocker > 0`, never output an approval template
+- never count env-blocked findings as blockers / major issues / minor issues, and never use them to trigger Branch B/C/D
 - always include every TUI command format in the selected branch
 
 ### Branch A: Approved with No Findings
 
 ```text
 Task {task-id} review completed. Verdict: approved.
-- Blockers: 0 | Major: 0 | Minor: 0
+- Blockers: 0 | Major: 0 | Minor: 0[ | env-blocked: {n} (outside AI repair scope)]
+[- Review report: .agents/workspace/active/{task-id}/{review-artifact}]
 
 Next step - commit the code:
   - Claude Code / OpenCode: /commit
   - Gemini CLI: /agent-infra:commit
   - Codex CLI: $commit
+
+[When env-blocked > 0, append this final line:]
+Reminder: env-blocked findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /refine-task.
 ```
 
 ### Branch B: Approved with Findings
 
 ```text
 Task {task-id} review completed. Verdict: approved.
-- Blockers: 0 | Major: {n} | Minor: {n}
+- Blockers: 0 | Major: {n} | Minor: {n}[ | env-blocked: {n} (outside AI repair scope)]
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - refine before commit (recommended):
@@ -44,29 +49,39 @@ Or commit directly (skip refinement):
   - Claude Code / OpenCode: /commit
   - Gemini CLI: /agent-infra:commit
   - Codex CLI: $commit
+
+[When env-blocked > 0, append this final line:]
+Reminder: env-blocked findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /refine-task.
 ```
 
 ### Branch C: Changes Requested
 
 ```text
 Task {task-id} review completed. Verdict: changes requested.
-- Blockers: {n} | Major: {n} | Minor: {n}
+- Blockers: {n} | Major: {n} | Minor: {n}[ | env-blocked: {n} (outside AI repair scope)]
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - fix the findings:
   - Claude Code / OpenCode: /refine-task {task-id}
   - Gemini CLI: /agent-infra:refine-task {task-id}
   - Codex CLI: $refine-task {task-id}
+
+[When env-blocked > 0, append this final line:]
+Reminder: env-blocked findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /refine-task.
 ```
 
 ### Branch D: Rejected
 
 ```text
 Task {task-id} review completed. Verdict: rejected, major rework required.
+- Blockers: {n} | Major: {n} | Minor: {n}[ | env-blocked: {n} (outside AI repair scope)]
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - re-implement:
   - Claude Code / OpenCode: /implement-task {task-id}
   - Gemini CLI: /agent-infra:implement-task {task-id}
   - Codex CLI: $implement-task {task-id}
+
+[When env-blocked > 0, append this final line:]
+Reminder: env-blocked findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /refine-task.
 ```

package/templates/.agents/skills/review-task/reference/output-templates.zh-CN.md

@@ -4,8 +4,8 @@
 
 ## 选择唯一输出场景
 
-按以下顺序判断：
-1. 如果 `Blocker = 0` 且 `Major = 0` 且 `Minor = 0`，使用场景 A
+按以下顺序判断（**注意：env-blocked 数量不参与判断**）：
+1. 如果 `Blocker = 0` 且 `Major = 0` 且 `Minor = 0`，使用场景 A（不管 env-blocked 是否 > 0）
 2. 如果 `Blocker = 0` 且（`Major > 0` 或 `Minor > 0`），使用场景 B
 3. 如果 `Blocker > 0`，且问题可以通过一次聚焦修复解决，使用场景 C
 4. 如果任务需要重大重构、大范围重写或整体重来，使用场景 D
@@ -14,25 +14,30 @@
 - 不要跳过场景判断步骤
 - 不要混用不同场景的文案
 - 只要 `Blocker > 0`，就绝对不能输出通过模板
+- env-blocked 项绝对不能被计入 blocker / major / minor 计数，也不能用作触发场景 B/C/D 的依据
 - 所选场景中必须包含所有 TUI 命令格式
 
 ### 场景 A：通过且无问题
 
 ```text
 任务 {task-id} 代码审查完成。结论：通过。
-- 阻塞项：0 | 主要问题：0 | 次要问题：0
+- 阻塞项：0 | 主要问题：0 | 次要问题：0[ | 环境性遗留：{n}（不在 AI 修复范围）]
+[- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}]
 
 下一步 - 提交代码：
   - Claude Code / OpenCode：/commit
   - Gemini CLI：/agent-infra:commit
   - Codex CLI：$commit
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /refine-task。
 ```
 
 ### 场景 B：通过但有问题
 
 ```text
 任务 {task-id} 代码审查完成。结论：通过。
-- 阻塞项：0 | 主要问题：{n} | 次要问题：{n}
+- 阻塞项：0 | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修复问题后提交（推荐）：
@@ -44,29 +49,39 @@
   - Claude Code / OpenCode：/commit
   - Gemini CLI：/agent-infra:commit
   - Codex CLI：$commit
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /refine-task。
 ```
 
 ### 场景 C：需要修改
 
 ```text
 任务 {task-id} 代码审查完成。结论：需要修改。
-- 阻塞项：{n} | 主要问题：{n} | 次要问题：{n}
+- 阻塞项：{n} | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修复问题：
   - Claude Code / OpenCode：/refine-task {task-id}
   - Gemini CLI：/agent-infra:refine-task {task-id}
   - Codex CLI：$refine-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /refine-task。
 ```
 
 ### 场景 D：拒绝
 
 ```text
 任务 {task-id} 代码审查完成。结论：拒绝，需要重大返工。
+- 阻塞项：{n} | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 重新实现：
   - Claude Code / OpenCode：/implement-task {task-id}
   - Gemini CLI：/agent-infra:implement-task {task-id}
   - Codex CLI：$implement-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /refine-task。
 ```

package/templates/.agents/skills/review-task/reference/report-template.en.md

@@ -19,6 +19,7 @@ Use this template when writing `review.md` or `review-r{N}.md`.
 - **Review Time**: {timestamp}
 - **Scope**: {file-count and major modules}
 - **Overall Verdict**: {Approved / Changes Requested / Rejected}
+- **Findings (AI-actionable)**: 0 blockers, 0 majors, 0 minors / **env-blocked**: 0
 
 ## Findings
 
@@ -42,6 +43,18 @@ Use this template when writing `review.md` or `review-r{N}.md`.
 **File**: `{file-path}:{line-number}`
 **Suggestion**: {improvement suggestion}
 
+## Environment-Blocked Findings
+
+> Items the AI agent cannot close in the current execution environment; they do not participate in the next refine round. Maintainers carry them in the PR description as a "manual verification required" checklist.
+
+#### 1. {environment-blocked finding title}
+**File**: `{file-path}:{line-number}` (if applicable)
+**Description**: {details}
+**Required Environment**: {e.g. Docker sandbox / macOS host / privileged root / third-party account}
+**Manual Verification Steps**: {steps for the human verifier}
+
+> If this round has no env-blocked findings, keep the section heading and write "None".
+
 ## Highlights
 
 - {what went well}

package/templates/.agents/skills/review-task/reference/report-template.zh-CN.md

@@ -19,6 +19,7 @@
 - **审查时间**：{timestamp}
 - **审查范围**：{file-count and major modules}
 - **总体结论**：{通过 / 需要修改 / 拒绝}
+- **发现（AI 可处理）**：0 阻塞项，0 主要，0 次要 / **env-blocked**：0
 
 ## 问题清单
 
@@ -42,6 +43,18 @@
 **文件**：`{file-path}:{line-number}`
 **建议**：{improvement suggestion}
 
+## 环境性遗留
+
+> AI agent 在本执行环境无法闭环的项；不参与下一轮 refine。维护者在 PR description 中以「待人工验证」清单承接。
+
+#### 1. {环境性项标题}
+**文件**：`{file-path}:{line-number}`（如适用）
+**说明**：{details}
+**所需环境**：{e.g. Docker 沙箱 / macOS host / 特权 root / 第三方账号}
+**待人工执行的验证步骤**：{steps for the human verifier}
+
+> 如本轮无 env-blocked 项，保留段落标题并写「（无）」。
+
 ## 亮点
 
 - {what went well}

package/templates/.agents/skills/review-task/reference/review-criteria.en.md

@@ -21,4 +21,22 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 3. **Actionable**: suggest a concrete fix
 4. **Severity-based**: distinguish blockers, major issues, and minor improvements
 
+## Environment-Blocked Classification
+
+Some findings cannot be closed by the AI agent in the current execution environment, for example:
+
+- missing Docker / sandbox access for end-to-end verification
+- missing a specific OS (macOS-only behavior)
+- missing a third-party account / OAuth access
+- missing privileged operations (root, sudo, special network access)
+
+**Classification decision tree**: "Can the AI agent close this without changing the environment?"
+- yes -> one of blocker / major / minor (based on risk)
+- no -> **env-blocked** (a meta-category, not part of severity ordering)
+
+Where env-blocked findings go:
+- record them in the independent review report section "Environment-Blocked Findings"
+- append them to the end of numeric summaries (for example, `(+ 1 env-blocked)`)
+- do **not** send them into the refine loop; maintainers carry them in the PR description as a "manual verification required" checklist
+
 Also inspect `git diff` so the report reflects the full change context.

package/templates/.agents/skills/review-task/reference/review-criteria.zh-CN.md

@@ -21,4 +21,22 @@
 3. **可执行**：给出明确可落地的修复建议
 4. **按严重程度分类**：明确区分 blocker、major 和 minor
 
+## 环境性遗留分类
+
+某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：
+
+- 缺 Docker / 沙箱而无法跑端到端验证
+- 缺特定 OS（macOS-only 行为）
+- 缺第三方账号 / OAuth
+- 缺特权操作（root、sudo、特殊网络）
+
+**分类决策树**：「AI agent 能否在不改环境的前提下独立闭环这一项？」
+- 是 -> blocker / major / minor 之一（按风险定档）
+- 否 -> **env-blocked**（元类目，不参与严重程度排序）
+
+env-blocked 项的去向：
+- 写入 review 报告独立段落「环境性遗留」
+- 在数字摘要末尾附带显示（如 `(+ 1 env-blocked)`）
+- **不**进入 refine 循环；维护者在 PR description 中以「待人工验证」清单形式承接
+
 同时检查 `git diff`，确保报告反映完整的变更上下文。

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -26,13 +26,13 @@ const DEFAULTS = {
   "sandbox": {
     "engine": null,
     "runtimes": [
-      "node20"
+      "node22"
     ],
     "tools": [
       "claude-code",
       "codex",
-      "opencode",
-      "gemini-cli"
+      "gemini-cli",
+      "opencode"
     ],
     "dockerfile": null,
     "vm": {
@@ -48,6 +48,7 @@ const DEFAULTS = {
     "managed": [
       ".agents/QUICKSTART.md",
       ".agents/README.md",
+      ".agents/hooks/",
       ".agents/rules/",
       ".agents/scripts/",
       ".agents/skills/",
@@ -55,7 +56,7 @@ const DEFAULTS = {
       ".agents/workflows/",
       ".agents/workspace/README.md",
       ".claude/commands/",
-      ".claude/hooks/",
+      ".codex/hooks.json",
       ".gemini/commands/",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",

package/templates/.agents/templates/task.en.md

@@ -6,6 +6,11 @@ workflow: feature-development  # feature-development | bug-fix | code-review | r
 status: open                   # open | in-progress | review | blocked | completed
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
+agent_infra_version: v0.0.0    # Current agent-infra version; refreshed by workflow commands
+priority:                       # Optional Issue field: Urgent | High | Medium | Low
+effort:                         # Optional Issue field: High | Medium | Low
+start_date:                     # Optional Issue field for Feature: YYYY-MM-DD
+target_date:                    # Optional Issue field for Feature: YYYY-MM-DD
 current_step: analysis         # analysis | design | implementation | review | fix | commit
 assigned_to:                   # claude | codex | gemini | opencode | human
 ---

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

@@ -6,6 +6,11 @@ workflow: feature-development  # feature-development | bug-fix | code-review | r
 status: open                   # open | in-progress | review | blocked | completed
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
+agent_infra_version: v0.0.0    # 当前 agent-infra 版本；由工作流命令刷新
+priority:                       # 可选 Issue 字段：Urgent | High | Medium | Low
+effort:                         # 可选 Issue 字段：High | Medium | Low
+start_date:                     # Feature 可选 Issue 字段：YYYY-MM-DD
+target_date:                    # Feature 可选 Issue 字段：YYYY-MM-DD
 current_step: analysis         # analysis | design | implementation | review | fix | commit
 assigned_to:                   # claude | codex | gemini | opencode | human
 ---

package/templates/.claude/settings.json

@@ -24,7 +24,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh .claude/hooks/check-version-format.sh",
+            "command": "sh \"$(git rev-parse --show-toplevel)/.agents/hooks/check-version-format.sh\"",
             "timeout": 5
           }
         ]

package/templates/.codex/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$(git rev-parse --show-toplevel)/.agents/hooks/check-version-format.sh\"",
+            "timeout": 5,
+            "statusMessage": "Checking template version before git commit"
+          }
+        ]
+      }
+    ]
+  }
+}