@fitlab-ai/agent-infra 0.8.5 → 0.9.0

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

@@ -22,8 +22,8 @@
 - **审查时间**：{timestamp}
 - **审查范围**：{file-count and major modules}
 - **审查基线提交**：{本轮一次性捕获的 R 原文}（仅表示 diff base；详见 `.agents/rules/review-handshake.md`）
-- **审查差异指纹**：{node .agents/scripts/review-diff-fingerprint.js worktree "$R" 原文}
-- **审查快照树**：{node .agents/scripts/review-diff-fingerprint.js worktree "$R" --format json 的 tree 字段}
+- **审查差异指纹**：{git-workflow snapshot 输出的 fingerprint 字段}
+- **审查快照树**：{git-workflow snapshot 输出的 tree 字段}
 - **总体结论**：{通过 / 需要修改 / 拒绝}（恰取一个；禁止写组合短语，否则 verify gate 失败）
 - **发现（AI 可处理）**：0 阻塞项，0 主要，0 次要 / **人工校验**：0
 
@@ -43,12 +43,18 @@
 **说明**：{details}
 **修复建议**：{fix suggestion}
 
-### 次要问题（可选改进）
+### 次要问题（低影响但需闭环）
 
 #### 1. {改进点}
 **文件**：`{file-path}:{line-number}`
 **建议**：{improvement suggestion}
 
+## 非阻塞建议
+
+> 仅记录不影响当前产物完整性、正确性和验收的后续优化；不写入审查分歧账本，不计入 blocker / major / minor，也不影响结论。
+
+- {future optimization}
+
 ## 人工校验项
 
 > AI agent 在本执行环境无法闭环的项；不参与下一轮 refine。维护者在 PR description 中以「待人工验证」清单承接。
@@ -64,7 +70,8 @@
 
 ## 审查分歧账本回写
 
-> 把本轮每条 finding upsert 到 task.md `## 审查分歧账本`：新 finding 追加 `open` 行（id 前缀 `CD-`，stage=code），对执行方上一轮响应按回交义务改 `confirmed` / 置回 `open` / `needs-human-decision`。状态机与证据规则见 `.agents/rules/review-handshake.md`。
+> 本段记录将提交的结构化意图：新 finding 用 `task-ledger finding-upsert`，上一轮响应复核用 `finding-review`；由核心分配 `CD-N` 并校验状态机，禁止手写 task.md 表格。
+> 凡升级为 `needs-human-decision` 的 finding，必须按 `.agents/rules/human-decision-context.md` 在本报告中提供自足详情块，并让 evidence 指向该稳定锚点。
 
 ## 证据原文
 

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

@@ -15,6 +15,7 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 - [ ] Comments and documentation
 - [ ] Consistency with the approved technical plan
 - [ ] The reviewer checked whether the executor missed any key design decision that should be upgraded to `[needs-human-decision]`
+- [ ] Every `needs-human-decision` detail produced this round follows the self-contained structure in `.agents/rules/human-decision-context.md`
 - [ ] Every blocker is backed by reproducible grep/sed/nl evidence; conclusions not directly verified are declared under Self-Doubt
 
 **Common anti-examples**:
@@ -30,6 +31,12 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 3. **Actionable**: suggest a concrete fix
 4. **Severity-based**: clearly distinguish blockers, major issues, and minor issues
 
+## Three-category Decision Tree
+
+1. A correctness, completeness, security, performance, test, or acceptance gap in the current implementation is a formal finding. Assign blocker / major / minor by impact; severity does not control closure, so minor findings must also reach a terminal state.
+2. When there is no known defect but validation requires a real environment, permission, or human operation, classify it as manual-validation.
+3. Only a future optimization that does not affect the current implementation's completeness, correctness, or acceptance is an advisory. Put it only in Non-blocking Advisories; do not add it to the ledger, finding counts, or verdict.
+
 ## Manual Validation Classification
 
 Some findings cannot be closed by an AI agent in the current execution environment, for example:

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

@@ -15,6 +15,7 @@
 - [ ] 代码注释和文档
 - [ ] 与已批准技术方案的一致性
 - [ ] 已复核执行方是否漏标应升级为 `[needs-human-decision]` 的关键设计决策
+- [ ] 本轮所有 `needs-human-decision` 详情均符合 `.agents/rules/human-decision-context.md` 的自足结构
 - [ ] 每条 blocker 都配可复现的 grep/sed/nl 证据，未直接验证的结论已在「自我质疑」声明
 
 **常见反例**：
@@ -30,6 +31,12 @@
 3. **可执行**：给出明确可落地的修复建议
 4. **按严重程度分类**：明确区分 blocker、major 和 minor
 
+## 三类审查项决策树
+
+1. 若问题揭示当前实现或测试存在正确性、完整性、安全性、性能或验收缺口，登记为正式 finding，并按影响赋予 blocker / major / minor；severity 只表示影响大小，minor 也必须闭环。
+2. 若没有已知缺陷，但只能依赖真实环境、权限或人工操作完成验证，归为 manual-validation。
+3. 仅当建议属于未来优化且不影响当前实现的完整性、正确性和验收时，归为 advisory。advisory 只写入「非阻塞建议」，不进入账本、问题计数或 verdict。
+
 ## 人工校验项分类
 
 某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：

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

@@ -3,6 +3,7 @@ name: review-plan
 description: >
   Review the technical plan.
   Use when a technical plan needs review before implementation.
+  Only invoke this skill automatically when the conversation includes a resolvable task reference.
 ---
 
 # Technical Plan Review
@@ -23,24 +24,18 @@ After loading workflow / skill / rules instructions, and before any task-state j
 Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
 
 ```bash
-git status -s
-ls -la .agents/workspace/active/{task-id}/
-tail .agents/workspace/active/{task-id}/task.md
+agent-infra-internal task-snapshot {task-id} --format text
 ```
 
-## Task id short ref
+## Task Context Resolution
 
-> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
 
-## Step Start: Write the started Marker
-
-After prerequisites pass and before this round's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this round's done entry plus a ` [started]` suffix, note `started`):
+> Resolve the task reference, then confirm that the task is in a state or directory supported by this skill and that `task.md` exists; if it cannot be located, handle it as a missing task and stop.
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N}) [started]** by {agent} — started
-```
+## Step Start: Write the started Marker
 
-`ai task log` pairs it with the done entry written when the review completes onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} review-plan.started --agent {agent}`.
 
 ## Steps
 
@@ -48,9 +43,9 @@ After prerequisites pass and before this round's first artifact action, append a
 
 Require `task.md` and at least one plan artifact: `plan.md` or `plan-r{N}.md`.
 
-### 2. Determine Review Round
+### 2. Resolve the Artifact Context
 
-Record `{plan-artifact}`, `{review-round}`, and `{review-artifact}` (`review-plan.md` or `review-plan-r{N}.md`).
+Run `agent-infra-internal task-artifact {task-id} inspect --family review-plan`. Continue only for `ready`; take `{plan-artifact}` from `inputs` and `{review-round}` / `{review-artifact}` from `next.round` / `next.name`. Do not scan rounds or construct names in the skill. Then run the started event and verify the returned identity.
 
 ### 3. Read Plan Context
 
@@ -70,27 +65,20 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-Get the current time:
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
-
-Set `current_step` to `technical-design-review`, refresh task metadata, and append:
-`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}, Manual-validation: {n} → {review-artifact}`
+After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-ledger {task-id} stage-status --stage plan` exactly once. Derive the verdict and next-step branch from `stageStatus.canAdvance`, and blocker/major/minor event counts from `unresolvedFindingCounts`: only `canAdvance=true` permits `approved`; otherwise use `changes-requested` or `rejected`. Then run `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`.
 
 `manual-validation` is the data source for the `Manual-validation` count folded into review rows in `ai task log`; do not add a parallel manual-verification field.
 
-If task.md has a valid `issue_number`, read `.agents/rules/issue-sync.md`, sync the task comment, and publish the `{review-artifact}` comment.
+If task.md has a valid `issue_number`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {agent}`.
 
 ### 7. Run Completion Gate
 
 ```bash
-node .agents/scripts/validate-artifact.js gate review-plan .agents/workspace/active/{task-id} {review-artifact} --format text
+agent-infra-internal task-verify {task-id} review-plan.completed --artifact {review-artifact} --format text
 ```
 
 ### 8. Tell the User
 
 Use the conclusion branch in `reference/output-templates.md` and show all TUI command formats.
 
-> Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `#NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+> Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).

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

@@ -3,6 +3,7 @@ name: review-plan
 description: >
   审查技术方案。
   当技术方案需要在进入实现前接受审查时使用。
+  仅当对话包含可解析的任务引用时才可自动调用本技能。
 ---
 
 # 技术方案审查
@@ -23,26 +24,20 @@ description: >
 运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
 
 ```bash
-git status -s
-ls -la .agents/workspace/active/{task-id}/
-tail .agents/workspace/active/{task-id}/task.md
+agent-infra-internal task-snapshot {task-id} --format text
 ```
 
 状态核对完成前，禁止任何关于外部状态的断言。
 
-## 任务入参短号别名
+## 任务上下文解析
 
-> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
-## 步骤开始：写入 started 标记
+> 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
-确认前置条件后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本轮 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+## 步骤开始：声明 started 事件
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N}) [started]** by {agent} — started
-```
-
-`ai task log` 会把它与审查完成时写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+确认前置条件和产物上下文后、本轮第一个产出动作之前执行 `agent-infra-internal task-event {task-id} review-plan.started --agent {agent}`。
 
 ## 执行步骤
 ### 1. 验证前置条件
@@ -51,12 +46,9 @@ tail .agents/workspace/active/{task-id}/task.md
 - `.agents/workspace/active/{task-id}/task.md`
 - 至少一个方案产物：`plan.md` 或 `plan-r{N}.md`
 
-### 2. 确定审查轮次
+### 2. 解析审查上下文
 
-扫描任务目录并记录：
-- `{plan-artifact}`：最高轮次的方案产物
-- `{review-round}`
-- `{review-artifact}`：`review-plan.md` 或 `review-plan-r{N}.md`
+运行 `agent-infra-internal task-artifact {task-id} inspect --family review-plan`。仅当结果为 `ready` 时继续；从 `inputs` 取得 `{plan-artifact}`，从 `next.round` / `next.name` 取得 `{review-round}` / `{review-artifact}`。不得自行扫描轮次或拼装文件名。随后执行 started 事件并复核返回身份。
 
 ### 3. 阅读方案上下文
 
@@ -76,28 +68,16 @@ tail .agents/workspace/active/{task-id}/task.md
 
 ### 6. 更新任务状态
 
-获取当前时间：
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
-
-更新 task.md：
-- `current_step`：technical-design-review
-- `assigned_to`：{当前代理}
-- `updated_at`：{当前时间}
-- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
-- 追加：
-  `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Review Plan (Round {N})** by {agent} — Verdict: {Approved/Changes Requested/Rejected}, blockers: {n}, major: {n}, minor: {n}, Manual-validation: {n} → {review-artifact}`
+报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后只调用一次 `agent-infra-internal task-ledger {task-id} stage-status --stage plan`，以 `stageStatus.canAdvance` 决定 verdict 和下一步，并以 `unresolvedFindingCounts` 填写 blocker/major/minor：仅 `canAdvance=true` 可用 `approved`，否则必须用 `changes-requested` 或 `rejected`。随后执行 `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`。
 
 `manual-validation` 是 `ai task log` 中 review 行「人工校验点」（EN `Manual-validation`）计数的数据源；不要新增并行人工验证字段。
 
-如果 task.md 中存在有效的 `issue_number`，执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测，然后同步 task 评论并发布 `{review-artifact}` 评论。
+如果 task.md 中存在有效的 `issue_number`，调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`，再调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {agent}`；失败按 `.agents/rules/issue-sync.md` 记录 warning。
 
 ### 7. 完成校验
 
 ```bash
-node .agents/scripts/validate-artifact.js gate review-plan .agents/workspace/active/{task-id} {review-artifact} --format text
+agent-infra-internal task-verify {task-id} review-plan.completed --artifact {review-artifact} --format text
 ```
 
 校验通过后继续告知用户；校验失败则修复报告或 task 状态后重跑。
@@ -106,7 +86,7 @@ node .agents/scripts/validate-artifact.js gate review-plan .agents/workspace/act
 
 按 `reference/output-templates.md` 的结论分支输出，并展示所有 TUI 的下一步命令。
 
-> 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `#NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+> 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 ## 完成检查清单
 

package/templates/.agents/skills/review-plan/config/verify.en.json

@@ -20,6 +20,7 @@
       "required_sections": [
         "Review Summary",
         "Findings",
+        "Non-blocking Advisories",
         "Manual Validation Items",
         "Conclusion and Recommendations",
         "State Check",
@@ -30,12 +31,10 @@
       "required_patterns": [
         "^### Approval Decision$",
         "^\\$ "
-      ],
-      "freshness_minutes": 30
+      ]
     },
     "activity-log": {
-      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)",
-      "freshness_minutes": 30
+      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)"
     },
     "platform-sync": {
       "when": "issue_number_exists",

package/templates/.agents/skills/review-plan/config/verify.zh-CN.json

@@ -20,6 +20,7 @@
       "required_sections": [
         "审查摘要",
         "问题清单",
+        "非阻塞建议",
         "人工校验项",
         "结论与建议",
         "状态核对",
@@ -30,12 +31,10 @@
       "required_patterns": [
         "^### 审查决定$",
         "^\\$ "
-      ],
-      "freshness_minutes": 30
+      ]
     },
     "activity-log": {
-      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)",
-      "freshness_minutes": 30
+      "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)"
     },
     "platform-sync": {
       "when": "issue_number_exists",

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

@@ -4,9 +4,9 @@ Read this file before presenting the final review result to the user.
 
 ## Select exactly one output scenario
 
-Evaluate in this order (**manual-validation count does not participate in selection**):
-1. If `Blocker = 0`, `Major = 0`, and `Minor = 0`, use Scenario A, regardless of manual-validation count
-2. If `Blocker = 0` and (`Major > 0` or `Minor > 0`), use Scenario B
+Select from `stage-status` (**manual-validation and advisory counts do not participate**):
+1. If `stageStatus.canAdvance=true`, use Scenario A
+2. If `stageStatus.canAdvance=false` and there are no blockers, use Scenario B
 3. If `Blocker > 0` and the issues can be handled by one focused revision, use Scenario C
 4. If the technical plan needs major redesign, broad rewriting, or a restart, use Scenario D
 
@@ -16,7 +16,9 @@ Rules:
 - If `Blocker > 0`, never use an approved template
 - Never count manual-validation items as blocker / major / minor or use them to trigger Scenario B/C/D
 - The selected scenario must include all TUI command formats
-- The count line always shows 4 numbers: the first three (Blockers / Major / Minor) must be 0 to proceed; the fourth, `Human-decision` (`{h}`), is the number of rows in task.md `## 审查分歧账本` with `stage=plan` and `status=needs-human-decision` — a "pending human ruling" item that need not be zero and does not participate in scenario selection. When `{h} > 0`, before the selected scenario's "Next steps" commands you must expand each pending ruling per the "Pending human-decision pre-block" in `.agents/rules/next-step-output.md` and prompt to resolve them first
+- The count line shows 4 numbers. `Human-decision` (`{h}`) counts this stage's `needs-human-decision` rows; because those rows are unresolved, `{h} > 0` means `canAdvance=false`. Expand the "Pending human-decision pre-block" from `.agents/rules/next-step-output.md` and show revision and re-review paths only.
+
+For Scenarios B/C/D, follow the revision commands with re-review commands: `/review-plan {task-ref}`, `/{{project}}:review-plan {task-ref}`, and `$review-plan {task-ref}`.
 
 ### Scenario A: Approved with no findings
 
@@ -34,23 +36,18 @@ Next step - write code:
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
 ```
 
-### Scenario B: Approved with findings
+### Scenario B: Changes requested (major / minor)
 
 ```text
-Task {task-id} technical plan review completed. Verdict: approved.
+Task {task-id} technical plan review completed. Verdict: changes requested.
 - Blockers: 0 | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
-Next step - revise plan before coding (recommended):
+Next step - revise technical plan:
   - Claude Code / OpenCode: /plan-task {task-ref}
   - Gemini CLI: /{{project}}:plan-task {task-ref}
   - Codex CLI: $plan-task {task-ref}
 
-Or proceed directly to coding:
-  - Claude Code / OpenCode: /code-task {task-ref}
-  - Gemini CLI: /{{project}}:code-task {task-ref}
-  - Codex CLI: $code-task {task-ref}
-
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
 ```

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

@@ -4,9 +4,9 @@
 
 ## 选择唯一输出场景
 
-按以下顺序判断（**注意：manual-validation 数量不参与判断**）：
-1. 如果 `Blocker = 0` 且 `Major = 0` 且 `Minor = 0`，使用场景 A（不管 manual-validation 是否 > 0）
-2. 如果 `Blocker = 0` 且（`Major > 0` 或 `Minor > 0`），使用场景 B
+按 `stage-status` 结果判断（**注意：manual-validation 和 advisory 数量不参与判断**）：
+1. 如果 `stageStatus.canAdvance=true`，使用场景 A
+2. 如果 `stageStatus.canAdvance=false` 且无 blocker，使用场景 B
 3. 如果 `Blocker > 0`，且问题可以通过一次聚焦修复解决，使用场景 C
 4. 如果技术方案需要重大重构、大范围重写或整体重来，使用场景 D
 
@@ -16,7 +16,9 @@
 - 只要 `Blocker > 0`，就绝对不能输出通过模板
 - manual-validation 项绝对不能被计入 blocker / major / minor 计数，也不能用作触发场景 B/C/D 的依据
 - 所选场景中必须包含所有 TUI 命令格式
-- 计数行固定显示 4 个数字：前三项（阻塞 / 主要 / 次要）必须为 0 才进下一步；第四项 `人工裁决`（`{h}`）= task.md `## 审查分歧账本` 中 `stage=plan` 且 `status=needs-human-decision` 的行数，是「待人裁」项、不要求归零，也不参与场景判断。当 `{h} > 0` 时，必须在选定场景的「下一步」命令之前，按 `.agents/rules/next-step-output.md`「人工裁决待办前置块」逐项展开裁决项并提示先完成裁决
+- 计数行固定显示 4 个数字。`人工裁决`（`{h}`）是本阶段 `needs-human-decision` 行数；它属于未闭环账本状态，因此 `{h} > 0` 时 `canAdvance=false`，必须按 `.agents/rules/next-step-output.md` 的「人工裁决待办前置块」展开详情，并只输出修订与复审路径。
+
+场景 B/C/D 在修订命令后继续列出复审命令：`/review-plan {task-ref}`、`/{{project}}:review-plan {task-ref}`、`$review-plan {task-ref}`。
 
 ### 场景 A：通过且无问题
 
@@ -34,23 +36,18 @@
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
 ```
 
-### 场景 B：通过但有问题
+### 场景 B：需要修改（major / minor）
 
 ```text
-任务 {task-id} 技术方案审查完成。结论：通过。
+任务 {task-id} 技术方案审查完成。结论：需要修改。
 - 阻塞项：0 | 主要问题：{n} | 次要问题：{n} | 人工裁决：{h}
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
-下一步 - 修订方案后编码（推荐）：
+下一步 - 修订技术方案：
   - Claude Code / OpenCode：/plan-task {task-ref}
   - Gemini CLI：/{{project}}:plan-task {task-ref}
   - Codex CLI：$plan-task {task-ref}
 
-或直接进入编码：
-  - Claude Code / OpenCode：/code-task {task-ref}
-  - Gemini CLI：/{{project}}:code-task {task-ref}
-  - Codex CLI：$code-task {task-ref}
-
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
 ```

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

@@ -40,12 +40,18 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 **Description**: {details}
 **Suggested Fix**: {fix suggestion}
 
-### Minor Issues (optional improvements)
+### Minor Issues (low impact, closure required)
 
 #### 1. {Improvement point}
 **File**: `{file-path}:{line-number}`
 **Suggestion**: {improvement suggestion}
 
+## Non-blocking Advisories
+
+> Record only future optimizations that do not affect the current artifact's completeness, correctness, or acceptance. Advisories do not enter the disagreement ledger, finding counts, or verdict.
+
+- {future optimization}
+
 ## Manual Validation Items
 
 > Items the AI agent cannot close in the current execution environment; they do not participate in the next plan round. Maintainers carry them in the PR description as a "manual verification required" checklist.
@@ -61,7 +67,8 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 
 ## Review Disagreement Ledger Writeback
 
-> Upsert each finding this round into the task.md disagreement ledger: append an `open` row for new findings (id prefix `PL-`, stage=plan); per the hand-back duty set the executor's prior-round responses to `confirmed` / back to `open` / `needs-human-decision`. State machine and evidence rules: `.agents/rules/review-handshake.md`.
+> Record the structured intents to submit: use `task-ledger finding-upsert` for new findings and `finding-review` for prior responses. The core allocates `PL-N` and validates transitions; do not edit task.md table rows.
+> Every finding escalated to `needs-human-decision` must include a self-contained detail block per `.agents/rules/human-decision-context.md`, with evidence pointing to that stable anchor.
 
 ## Evidence
 

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

@@ -40,12 +40,18 @@
 **说明**：{details}
 **修复建议**：{fix suggestion}
 
-### 次要问题（可选改进）
+### 次要问题（低影响但需闭环）
 
 #### 1. {改进点}
 **文件**：`{file-path}:{line-number}`
 **建议**：{improvement suggestion}
 
+## 非阻塞建议
+
+> 仅记录不影响当前产物完整性、正确性和验收的后续优化；不写入审查分歧账本，不计入 blocker / major / minor，也不影响结论。
+
+- {future optimization}
+
 ## 人工校验项
 
 > AI agent 在本执行环境无法闭环的项；不参与下一轮 refine。维护者在 PR description 中以「待人工验证」清单承接。
@@ -61,7 +67,8 @@
 
 ## 审查分歧账本回写
 
-> 把本轮每条 finding upsert 到 task.md `## 审查分歧账本`：新 finding 追加 `open` 行（id 前缀 `PL-`，stage=plan），对执行方上一轮响应按回交义务改 `confirmed` / 置回 `open` / `needs-human-decision`。状态机与证据规则见 `.agents/rules/review-handshake.md`。
+> 本段记录将提交的结构化意图：新 finding 用 `task-ledger finding-upsert`，上一轮响应复核用 `finding-review`；由核心分配 `PL-N` 并校验状态机，禁止手写 task.md 表格。
+> 凡升级为 `needs-human-decision` 的 finding，必须按 `.agents/rules/human-decision-context.md` 在本报告中提供自足详情块，并让 evidence 指向该稳定锚点。
 
 ## 证据原文
 

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

@@ -14,6 +14,7 @@ Follow the `design-review` step in `.agents/workflows/feature-development.yaml`.
 - [ ] Risks, migration, rollback, or compatibility handling are sufficient
 - [ ] The plan avoids over-design and unrelated scope expansion
 - [ ] The reviewer checked whether the executor missed any key design decision that should be upgraded to `[needs-human-decision]`
+- [ ] Every `needs-human-decision` detail produced this round follows the self-contained structure in `.agents/rules/human-decision-context.md`
 - [ ] Every blocker is backed by reproducible grep/sed/nl evidence; conclusions not directly verified are declared under Self-Doubt
 
 **Common anti-examples**:
@@ -29,6 +30,12 @@ Follow the `design-review` step in `.agents/workflows/feature-development.yaml`.
 3. **Actionable**: suggest a concrete fix
 4. **Severity-based**: clearly distinguish blockers, major issues, and minor issues
 
+## Three-category Decision Tree
+
+1. A gap in constraints, risks, interface boundaries, validation strategy, or implementability is a formal finding. Assign blocker / major / minor by impact; severity does not control closure, so minor findings must also reach a terminal state.
+2. When there is no known defect but validation requires a real environment, permission, or human operation, classify it as manual-validation.
+3. Only a future optimization that does not affect the current plan's completeness, correctness, or acceptance is an advisory. Put it only in Non-blocking Advisories; do not add it to the ledger, finding counts, or verdict.
+
 ## Manual Validation Classification
 
 Some findings cannot be closed by an AI agent in the current execution environment, for example:

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

@@ -14,6 +14,7 @@
 - [ ] 风险、迁移、回滚或兼容性处理是否充分
 - [ ] 方案是否避免过度设计和无关扩张
 - [ ] 已复核执行方是否漏标应升级为 `[needs-human-decision]` 的关键设计决策
+- [ ] 本轮所有 `needs-human-decision` 详情均符合 `.agents/rules/human-decision-context.md` 的自足结构
 - [ ] 每条 blocker 都配可复现的 grep/sed/nl 证据，未直接验证的结论已在「自我质疑」声明
 
 **常见反例**：
@@ -29,6 +30,12 @@
 3. **可执行**：给出明确可落地的修复建议
 4. **按严重程度分类**：明确区分 blocker、major 和 minor
 
+## 三类审查项决策树
+
+1. 若问题揭示当前方案缺少约束、风险、接口边界、验证策略或可实施性，登记为正式 finding，并按影响赋予 blocker / major / minor；severity 只表示影响大小，minor 也必须闭环。
+2. 若没有已知缺陷，但只能依赖真实环境、权限或人工操作完成验证，归为 manual-validation。
+3. 仅当建议属于未来优化且不影响当前方案的完整性、正确性和验收时，归为 advisory。advisory 只写入「非阻塞建议」，不进入账本、问题计数或 verdict。
+
 ## 人工校验项分类
 
 某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：

package/templates/.agents/skills/update-agent-infra/SKILL.en.md

@@ -41,7 +41,7 @@ The script outputs JSON to stdout. Parse and record the report.
 
 **Key fields**:
 - `error`: error message (if non-empty, stop and report)
-- `templateVersion`: current template source version
+- `templateVersion`: exact `v`-prefixed SemVer of the template source package (including prerelease or build metadata)
 - `templateRoot`: absolute path to the template file root directory
 - `templateSources.conflicts`: external template source conflicts; explicitly
   list these in the report so users know which files were ignored because a
@@ -55,7 +55,6 @@ The script outputs JSON to stdout. Parse and record the report.
 - `merged.pending`: list of merged files for AI to process
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
 - `registryAdded`: newly added file registry entries
-- `selfUpdate`: whether this is a self-update scenario
 - `configUpdated`: whether `.agents/.airc.json` was updated
 
 If `managed.conflicts` is non-empty, output every conflict and stop immediately before Phase B. Do not overwrite a conflicting file or advance its `files.managedBaselines` entry.

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -35,7 +35,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 
 **关键字段**：
 - `error`：错误信息（如非空则停止并报告）
-- `templateVersion`：模板源当前版本
+- `templateVersion`：模板源包的精确 `v` 前缀 SemVer（可包含 prerelease 或 build metadata）
 - `templateRoot`：模板文件根目录绝对路径
 - `templateSources.conflicts`：外部模板源冲突列表；报告中必须显式展示，说明哪些文件因内置模板或后续外部源获胜而被忽略
 - `managed.written` / `managed.created`：已更新/新建的 managed 文件
@@ -47,7 +47,6 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 - `merged.pending`：需要 AI 处理的 merged 文件列表
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
 - `registryAdded`：新增的文件注册条目
-- `selfUpdate`：是否为自更新模式
 - `configUpdated`：`.agents/.airc.json` 是否已更新
 
 如果 `managed.conflicts` 非空，输出全部冲突并立即停止，不进入阶段 B；禁止覆盖冲突文件或推进其 `files.managedBaselines`。

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

@@ -13,7 +13,6 @@
  * Output: JSON report to stdout.
  */
 
-import childProcess from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -69,6 +68,7 @@ const DEFAULTS = {
       ".claude/commands/",
       ".codex/hooks.json",
       ".gemini/commands/",
+      ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
       ".github/workflows/metadata-sync.yml",
@@ -106,7 +106,7 @@ const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
 const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
 const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
 // Add a new identifier here only after shipping matching .{platform}. template variants.
-const KNOWN_PLATFORMS = new Set(['github']);
+const KNOWN_PLATFORMS = new Set(['github', 'none']);
 const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 
 // Single source of truth for built-in TUI ids and owned path prefixes.
@@ -870,14 +870,6 @@ function isBinary(fp) {
   return false;
 }
 
-function gitUrl(dir) {
-  try {
-    return childProcess.execSync('git remote get-url origin', {
-      cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-  } catch { return null; }
-}
-
 function langSelect(rels, lang, allSet, project) {
   const sel = new Map();
 
@@ -1020,8 +1012,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     },
     ejected: { created: [], skipped: [] },
     merged:  { pending: [] },
-    configUpdated: false,
-    selfUpdate: false
+    configUpdated: false
   };
   const customTUIs = validateCustomTUIs(projectRoot, customTUIsConfig, report);
   const customTUICommandTargets = buildCustomTUICommandTargets(
@@ -1365,9 +1356,6 @@ function syncTemplates(projectRoot, templateRootOverride) {
     ([target, template]) => ({ target, template })
   );
 
-  const projUrl = gitUrl(projectRoot);
-  report.selfUpdate = !!(projUrl && /fitlab-ai\/agent-infra/.test(projUrl));
-
   const hasChanges = (
     report.managed.written.length +
     report.managed.created.length +