@fitlab-ai/agent-infra 0.9.0 → 0.9.2

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

@@ -15,22 +15,20 @@ Rules:
 - Do not mix text from multiple scenarios
 - 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 selected scenario must generate `{next-step-commands}` through the shared helper
 - 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
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: approved.
 - Blockers: 0 | Major issues: 0 | Minor issues: 0 | Human-decision: {h}
 [- Review report: .agents/workspace/active/{task-id}/{review-artifact}]
 
 Next step - write code:
-  - Claude Code / OpenCode: /code-task {task-ref}
-  - Gemini CLI: /{{project}}:code-task {task-ref}
-  - Codex CLI: $code-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -38,15 +36,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario B: Changes requested (major / minor)
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 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 technical plan:
-  - Claude Code / OpenCode: /plan-task {task-ref}
-  - Gemini CLI: /{{project}}:plan-task {task-ref}
-  - Codex CLI: $plan-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -54,15 +52,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario C: Changes requested
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: changes requested.
 - Blockers: {n} | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 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}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -70,15 +68,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario D: Rejected
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: rejected, redesign required.
 - Blockers: {n} | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - redesign:
-  - Claude Code / OpenCode: /plan-task {task-ref}
-  - Gemini CLI: /{{project}}:plan-task {task-ref}
-  - Codex CLI: $plan-task {task-ref}
+{next-step-commands}
 
 [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

@@ -15,22 +15,20 @@
 - 不要混用不同场景的文案
 - 只要 `Blocker > 0`，就绝对不能输出通过模板
 - manual-validation 项绝对不能被计入 blocker / major / minor 计数，也不能用作触发场景 B/C/D 的依据
-- 所选场景中必须包含所有 TUI 命令格式
+- 所选场景必须通过统一 helper 生成 `{next-step-commands}`
 - 计数行固定显示 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：通过且无问题
 
+使用 `agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：通过。
 - 阻塞项：0 | 主要问题：0 | 次要问题：0 | 人工裁决：{h}
 [- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}]
 
 下一步 - 编写代码：
-  - Claude Code / OpenCode：/code-task {task-ref}
-  - Gemini CLI：/{{project}}:code-task {task-ref}
-  - Codex CLI：$code-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -38,15 +36,15 @@
 
 ### 场景 B：需要修改（major / minor）
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {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}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -54,15 +52,15 @@
 
 ### 场景 C：需要修改
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：需要修改。
 - 阻塞项：{n} | 主要问题：{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}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -70,15 +68,15 @@
 
 ### 场景 D：拒绝
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：拒绝，需要重新设计。
 - 阻塞项：{n} | 主要问题：{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}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。

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

@@ -22,7 +22,55 @@ Use this template when writing `review-plan.md` or `review-plan-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 / **Manual validation**: 0
+- **Findings (AI-actionable)**: {unresolved-blockers} blockers, {unresolved-major} majors, {unresolved-minor} minors / **Manual validation**: 0
+
+## Review Coverage Declaration
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | {scope actually reviewed} | {artifact / file:line / command} | {finding or conclusion} | {gap or assumption} |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| {registry token} | {trigger or non-trigger evidence} | {yes / no / not-applicable} | {lens result} |
+
+## Technical Plan Architecture Coverage
+
+| assessment_id | classification | trigger_evidence | review_depth | result_or_gap |
+|---------------|----------------|------------------|--------------|---------------|
+| architecture-significance | {ordinary / architecture-significant} | {artifact / file:line / source_id} | {proportional / mini-atam} | {covered / gap} |
+
+> Scenario A (`ordinary`): keep the table above, record `Mini-ATAM: not-applicable` with a reviewable reason, and delete the Scenario B tables.
+>
+> Scenario B (`architecture-significant`): keep the table above and the five tables below, and delete the Scenario A guidance.
+
+| quality_scenario_id | source_id | business_driver | quality_attribute | priority | stimulus | context | expected_response | measure | result_or_gap |
+|---------------------|-----------|-----------------|-------------------|----------|----------|---------|-------------------|---------|---------------|
+| {stable identifier} | {source identifier} | {business driver} | {quality attribute} | {priority} | {stimulus} | {context} | {expected response} | {verifiable measure} | {covered / gap} |
+
+| decision_id | selected_option | alternative_option | benefit | cost | assumption | rejection_reason | result_or_gap |
+|-------------|-----------------|--------------------|---------|------|------------|------------------|---------------|
+| {stable identifier} | {selected option} | {reasonable alternative} | {primary benefit} | {primary cost} | {assumption} | {rejection reason} | {covered / gap} |
+
+| risk_id | decision_id | risk_or_sensitivity | affected_quality_attributes | tradeoff | mitigation_or_validation | result_or_gap |
+|---------|-------------|---------------------|-----------------------------|----------|--------------------------|---------------|
+| {stable identifier} | {decision identifier} | {risk or sensitivity point} | {affected quality attributes} | {trade-off} | {mitigation or validation} | {covered / gap} |
+
+| decision_id | door_type | reversal_cost | migration_or_rollback | decision_status | result_or_gap |
+|-------------|-----------|---------------|-----------------------|-----------------|---------------|
+| {decision identifier} | {two-way / one-way} | {reversal cost} | {migration or rollback path} | {resolved / needs-human-decision} | {covered / gap} |
+
+| evolution_id | scenario_type | source_id | confirmation_status | change_scenario | affected_scope | verification | result_or_gap |
+|--------------|---------------|-----------|---------------------|-----------------|----------------|--------------|---------------|
+| {stable identifier} | {evolution / migration / rollback / compatibility / operations} | {source identifier} | {confirmed / unconfirmed / not-applicable} | {change scenario} | {affected scope} | {verification and continuous-validation entry point} | {covered / gap / not-applicable} |
+
+> An `unconfirmed` future scenario must not become a current hard requirement. Keep `not-applicable` with evidence for each inapplicable item.
+
+## Traceability Matrix
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| {source identifier} | {approved requirement} | {decision/step/test strategy} | {verification evidence} | {covered / gap} |
 
 ## Findings
 
@@ -30,15 +78,23 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 
 #### 1. {Issue title}
 **File**: `{file-path}:{line-number}`
-**Description**: {details}
-**Suggested Fix**: {fix suggestion}
+**Scenario**: {scenario}
+**Impact**: {impact}
+**Evidence**: {reproducible evidence}
+**Confidence**: {high / medium / low}
+**Unverified Assumptions**: {assumptions or none}
+**Fix Direction**: {fix direction}
 
 ### Major Issues (should fix)
 
 #### 1. {Issue title}
 **File**: `{file-path}:{line-number}`
-**Description**: {details}
-**Suggested Fix**: {fix suggestion}
+**Scenario**: {scenario}
+**Impact**: {impact}
+**Evidence**: {reproducible evidence}
+**Confidence**: {high / medium / low}
+**Unverified Assumptions**: {assumptions or none}
+**Fix Direction**: {fix direction}
 
 ### Minor Issues (low impact, closure required)
 

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

@@ -22,7 +22,55 @@
 - **审查时间**：{timestamp}
 - **审查范围**：{file-count and major modules}
 - **总体结论**：{通过 / 需要修改 / 拒绝}
-- **发现（AI 可处理）**：0 阻塞项，0 主要，0 次要 / **人工校验**：0
+- **发现（AI 可处理）**：{unresolved-blockers} 阻塞项，{unresolved-major} 主要，{unresolved-minor} 次要 / **人工校验**：0
+
+## 检视覆盖声明
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | {本遍实际范围} | {artifact / file:line / command} | {发现或结论} | {缺口或假设} |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| {registry token} | {命中或未命中证据} | {yes / no / not-applicable} | {专项结论} |
+
+## 技术方案架构覆盖
+
+| assessment_id | classification | trigger_evidence | review_depth | result_or_gap |
+|---------------|----------------|------------------|--------------|---------------|
+| architecture-significance | {ordinary / architecture-significant} | {artifact / file:line / source_id} | {proportional / mini-atam} | {covered / gap} |
+
+> 场景 A（`ordinary`）：保留上表，记录 `Mini-ATAM: not-applicable` 及可复核理由，并删除场景 B 的表格。
+>
+> 场景 B（`architecture-significant`）：保留上表和以下五张表，并删除场景 A 的说明。
+
+| quality_scenario_id | source_id | business_driver | quality_attribute | priority | stimulus | context | expected_response | measure | result_or_gap |
+|---------------------|-----------|-----------------|-------------------|----------|----------|---------|-------------------|---------|---------------|
+| {稳定标识} | {来源标识} | {业务驱动} | {质量属性} | {优先级} | {触发} | {上下文} | {期望响应} | {可验证度量} | {covered / gap} |
+
+| decision_id | selected_option | alternative_option | benefit | cost | assumption | rejection_reason | result_or_gap |
+|-------------|-----------------|--------------------|---------|------|------------|------------------|---------------|
+| {稳定标识} | {所选方案} | {合理替代方案} | {主要收益} | {主要代价} | {假设} | {不采用原因} | {covered / gap} |
+
+| risk_id | decision_id | risk_or_sensitivity | affected_quality_attributes | tradeoff | mitigation_or_validation | result_or_gap |
+|---------|-------------|---------------------|-----------------------------|----------|--------------------------|---------------|
+| {稳定标识} | {决策标识} | {风险或敏感点} | {受影响质量属性} | {权衡} | {缓解或验证} | {covered / gap} |
+
+| decision_id | door_type | reversal_cost | migration_or_rollback | decision_status | result_or_gap |
+|-------------|-----------|---------------|-----------------------|-----------------|---------------|
+| {决策标识} | {two-way / one-way} | {逆转成本} | {迁移或回滚路径} | {resolved / needs-human-decision} | {covered / gap} |
+
+| evolution_id | scenario_type | source_id | confirmation_status | change_scenario | affected_scope | verification | result_or_gap |
+|--------------|---------------|-----------|---------------------|-----------------|----------------|--------------|---------------|
+| {稳定标识} | {evolution / migration / rollback / compatibility / operations} | {来源标识} | {confirmed / unconfirmed / not-applicable} | {变化场景} | {影响范围} | {验证方式与持续验证入口} | {covered / gap / not-applicable} |
+
+> `unconfirmed` 的未来场景不得升级为当前硬性需求；不适用项保留 `not-applicable` 及证据。
+
+## 追踪矩阵
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| {来源标识} | {已批准需求} | {设计决策/步骤/测试策略} | {验证证据} | {covered / gap} |
 
 ## 问题清单
 
@@ -30,15 +78,23 @@
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 主要问题（建议修复）
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 次要问题（低影响但需闭环）
 

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

@@ -23,35 +23,32 @@ Follow the `design-review` step in `.agents/workflows/feature-development.yaml`.
 - Introducing unnecessary abstractions, configuration, or frameworks for a single-use requirement
 - Asserting a `file:line` or behavior from memory or impression without verifying via rg/nl
 
-## Common Review Principles
+## Shared Method and Classification Boundary
 
-1. **Strict but fair**: identify issues and acknowledge solid work
-2. **Specific**: cite exact file paths and line numbers
-3. **Actionable**: suggest a concrete fix
-4. **Severity-based**: clearly distinguish blockers, major issues, and minor issues
+Read `.agents/rules/review-method.md` first and apply its five-pass protocol, risk lenses, and finding evidence contract. Finding, manual-validation, advisory, and `needs-human-decision` state semantics remain governed by `.agents/rules/review-handshake.md`. This file adds only plan-stage criteria.
 
-## 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.
+Also inspect the latest technical plan artifact, latest requirement-analysis review artifact, and `task.md` Activity Log so the report reflects the full design context.
 
-## Manual Validation Classification
+## Technical Plan Architecture Coverage
 
-Some findings cannot be closed by an AI agent in the current execution environment, for example:
+First record an `architecture-significance` classification with locatable evidence in every round. Classify the plan as `architecture-significant` when any of these areas changes materially:
 
-- Missing Docker / sandbox access for end-to-end validation
-- Missing a specific OS for macOS-only behavior
-- Missing third-party accounts / OAuth
-- Missing privileged operations such as root, sudo, or special network access
+- responsibility or component boundaries;
+- cross-component data or control flow;
+- public or compatibility interfaces;
+- data ownership or persistence;
+- deployment or operations topology;
+- trust boundaries;
+- trade-offs between priority quality attributes;
+- high-cost or irreversible decisions.
 
-**Decision tree**: "Can the AI agent close this item independently without changing the environment?"
-- Yes -> blocker / major / minor, based on risk
-- No -> **manual-validation** (a manual-validation meta-category, not part of severity ordering)
+If none applies, classify the plan as `ordinary`, use `proportional` depth, and record only the classification evidence plus a reviewable reason why Mini-ATAM is `not-applicable`. If any applies, use `mini-atam` depth and complete this review:
 
-Where manual-validation items go:
-- Record them in an independent review report section named "Manual Validation Items"
-- Record the done-note source field as `Manual-validation: 1`; `ai task log` normalizes it into review rows
-- Do **not** include them in the code-task fix loop; maintainers carry them in the PR description under manual verification
+1. Trace business drivers and sourced priority quality attributes to approved requirements and constraints.
+2. Record stimulus, context, expected response, and a verifiable measure for each quality-attribute scenario.
+3. Compare each selected architecture decision with at least one reasonable alternative across benefit, cost, assumption, and rejection reason. Architecture-style or design-pattern counts are not evidence of fitness.
+4. Identify risks, sensitivity points, and quality-attribute trade-offs, including mitigation or validation.
+5. Mark each key decision as `two-way` or `one-way`, including reversal cost and migration or rollback path.
+6. Consider `evolution`, `migration`, `rollback`, `compatibility`, and `operations` scenarios individually, mapping affected scope, verification, and the continuous-validation entry point.
 
-Also inspect the latest technical plan artifact, latest requirement-analysis review artifact, and `task.md` Activity Log so the report reflects the full design context.
+For an inapplicable lifecycle scenario, record `not-applicable` and evidence. An `unconfirmed` future scenario must not become a current hard requirement. `one-way` describes reversibility only; upgrade a decision to `needs-human-decision` only when it also meets the existing source and impact tests.

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

@@ -23,35 +23,32 @@
 - 为单次需求引入不必要的新抽象、配置或框架
 - 凭印象或记忆断言 `file:line`/行为，没有用 rg/nl 复核就下结论
 
-## 通用审查原则
+## 共享方法与分类边界
 
-1. **严格但公正**：既要指出问题，也要承认做得好的部分
-2. **具体**：引用准确的文件路径和行号
-3. **可执行**：给出明确可落地的修复建议
-4. **按严重程度分类**：明确区分 blocker、major 和 minor
+先读取 `.agents/rules/review-method.md`，按其五遍协议、风险镜头和 finding 证据契约执行；finding、manual-validation、advisory 与 `needs-human-decision` 的状态语义以 `.agents/rules/review-handshake.md` 为准。本文件只补充技术方案阶段的专项判断。
 
-## 三类审查项决策树
-
-1. 若问题揭示当前方案缺少约束、风险、接口边界、验证策略或可实施性，登记为正式 finding，并按影响赋予 blocker / major / minor；severity 只表示影响大小，minor 也必须闭环。
-2. 若没有已知缺陷，但只能依赖真实环境、权限或人工操作完成验证，归为 manual-validation。
-3. 仅当建议属于未来优化且不影响当前方案的完整性、正确性和验收时，归为 advisory。advisory 只写入「非阻塞建议」，不进入账本、问题计数或 verdict。
+同时检查最新技术方案产物、最新需求分析审查产物和 `task.md` Activity Log，确保报告反映完整的设计上下文。
 
-## 人工校验项分类
+## 技术方案架构专项覆盖
 
-某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：
+每轮先用可定位证据记录 `architecture-significance` 分类。以下任一项发生实质变化即分类为 `architecture-significant`：
 
-- 缺 Docker / 沙箱而无法跑端到端验证
-- 缺特定 OS（macOS-only 行为）
-- 缺第三方账号 / OAuth
-- 缺特权操作（root、sudo、特殊网络）
+- 职责或组件边界；
+- 跨组件数据流或控制流；
+- 公开接口或兼容接口；
+- 数据所有权或持久化；
+- 部署或运维拓扑；
+- 信任边界；
+- 优先质量属性之间的权衡；
+- 高成本或不可逆决策。
 
-**分类决策树**：「AI agent 能否在不改环境的前提下独立闭环这一项？」
-- 是 -> blocker / major / minor 之一（按风险定档）
-- 否 -> **manual-validation**（人工校验元类目，不参与严重程度排序）
+未命中时分类为 `ordinary`，使用 `proportional` 深度，只记录分类证据以及 Mini-ATAM `not-applicable` 的可复核理由。命中时使用 `mini-atam` 深度并完成以下检视：
 
-manual-validation 项的去向：
-- 写入 review 报告独立段落「人工校验项」
-- 在 done note 中写入源字段 `Manual-validation: 1`；`ai task log` 归一化展示到 review 行
-- **不**进入 code-task 修复循环；维护者在 PR description 中以「待人工验证」清单形式承接
+1. 从已批准需求和约束追踪业务驱动及有来源的优先质量属性。
+2. 为质量属性场景记录 stimulus、context、expected response 和可验证 measure。
+3. 对所选架构决策与至少一个合理替代方案比较 benefit、cost、assumption 和 rejection reason；不得以架构风格或设计模式数量代替适配性判断。
+4. 识别风险、敏感点及质量属性间的 trade-off，并记录缓解或验证方式。
+5. 将关键决策标记为 `two-way` 或 `one-way`，记录逆转成本以及迁移或回滚路径。
+6. 逐项考虑 `evolution`、`migration`、`rollback`、`compatibility`、`operations` 场景，并映射影响范围、验证方式和持续验证入口。
 
-同时检查最新技术方案产物、最新需求分析审查产物和 `task.md` Activity Log，确保报告反映完整的设计上下文。
+不适用的生命周期场景必须写 `not-applicable` 及证据。`unconfirmed` 的未来场景不得升级为当前硬性需求。`one-way` 只描述可逆性；只有同时满足既有来源测试和影响测试时，才升级为 `needs-human-decision`。

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

@@ -0,0 +1,22 @@
+---
+name: run-task
+description: >
+  Orchestrate lifecycle stages from the task's current state with fresh executors/reviewers and one-use provenance receipts.
+  Use when one entry should advance an existing task until a safe commit or stable pause.
+---
+
+# Run Task Lifecycle
+
+The orchestrator delegates only and never executes a stage skill itself. First read `.agents/rules/no-mid-flow-questions.md` and `.agents/rules/lifecycle-orchestration.md`.
+
+1. Resolve the task and run `agent-infra-internal task-snapshot {task-id} --format text`.
+2. Run `agent-infra-internal task-orchestration {task-id} begin-or-resume`; stop on structured paused/completed results.
+3. Run `route` and use its single action, role, round, and artifact. Never infer routing from review prose.
+4. Run `agent-infra-internal task-orchestration {task-id} prepare --client {client}` so core records the workspace baseline, then start the specified executor/reviewer with the current client's fresh native subagent mechanism. Pass only the short task reference, skill name, and minimal handoff; never pass receipt identity or inherit orchestrator history.
+5. Native start/stop hooks correlate the unique pending delegation and let core compute workspace changes and seal the receipt. After the child returns, run `advance`. Repeat step 3 only for `running`; stop immediately for `paused` or `completed`.
+6. Create a new child every round and never follow up with an old reviewer. Capability, hook, identity, model fallback, ledger, or fingerprint failures must call `pause` and fail closed.
+7. On pause or completion, run the matching typed verification and report the structured run summary, pause reason, or commit endpoint.
+
+## Stop
+
+The first release ends after a safe `commit`; do not create a PR, monitor checks, or complete the task.

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

@@ -0,0 +1,22 @@
+---
+name: run-task
+description: >
+  从任务当前状态持续编排生命周期阶段，并用 fresh executor/reviewer 与一次性 receipt 验证隔离来源。
+  当用户希望通过单一入口推进已有任务直到安全提交或稳定暂停时使用。
+---
+
+# 运行任务生命周期
+
+总控只编排，不直接执行任何阶段技能。执行前先读取 `.agents/rules/no-mid-flow-questions.md` 与 `.agents/rules/lifecycle-orchestration.md`。
+
+1. 解析任务引用并执行 `agent-infra-internal task-snapshot {task-id} --format text`。
+2. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume`；若为 paused/completed，按结构化结果停止。
+3. 调用 `route` 并读取唯一 action、role、round 和 artifact；不得从审查文案自行推断。
+4. 调用 `agent-infra-internal task-orchestration {task-id} prepare --client {client}`；核心自动记录工作区基线。成功后用当前客户端的 fresh 原生子 Agent 启动指定 executor/reviewer，只传短任务引用、skill 名和最小交接摘要，不传 receipt identity，不继承总控历史。
+5. 原生 start/stop hook 通过唯一 pending delegation 自动关联任务，并由核心计算工作区变化、封存 receipt；子 Agent 返回后调用 `advance`。只有 `running` 才重复步骤 3；`paused` 或 `completed` 立即停止。
+6. 每轮创建新 child；禁止 follow-up 复用 reviewer。任何 capability、hook、身份、模型降级、账本或 fingerprint 异常都调用 `pause` 并失败关闭。
+7. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因或 commit 终点告知用户。
+
+## 停止
+
+首版在安全 `commit` 后结束；不要继续创建 PR、监控 checks 或完成任务。

package/templates/.agents/skills/run-task/config/verify.en.json

@@ -0,0 +1,9 @@
+{
+  "skill": "run-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
+    },
+    "orchestration-state": {}
+  }
+}

package/templates/.agents/skills/run-task/config/verify.zh-CN.json

@@ -0,0 +1,9 @@
+{
+  "skill": "run-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
+    },
+    "orchestration-state": {}
+  }
+}

package/templates/.agents/skills/test/SKILL.en.md

@@ -90,11 +90,11 @@ If tests fail:
 
 After tests pass, suggest committing the changes:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. 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).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
+
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit`.
 
 ```
 Next step - commit changes:
-  - Claude Code / OpenCode: /commit
-  - Gemini CLI: /{{project}}:commit
-  - Codex CLI: $commit
+{next-step-commands}
 ```

package/templates/.agents/skills/test/SKILL.zh-CN.md

@@ -88,11 +88,11 @@ description: >
 
 测试通过后，建议提交变更：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
+
+使用 `agent-infra-internal agent-client next-steps --skill commit` 生成本场景的 `{next-step-commands}`。
 
 ```
 下一步 - 提交代码：
-  - Claude Code / OpenCode：/commit
-  - Gemini CLI：/{{project}}:commit
-  - Codex CLI：$commit
+{next-step-commands}
 ```

package/templates/.agents/skills/test-integration/SKILL.en.md

@@ -52,13 +52,13 @@ If tests fail:
 
 After tests pass, suggest committing the changes:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. 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).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
+
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit`.
 
 ```
 Next step - commit changes:
-  - Claude Code / OpenCode: /commit
-  - Gemini CLI: /{{project}}:commit
-  - Codex CLI: $commit
+{next-step-commands}
 ```
 
 ## Notes

package/templates/.agents/skills/test-integration/SKILL.zh-CN.md

@@ -52,13 +52,13 @@ description: >
 
 测试通过后，建议提交变更：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+> 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
+
+使用 `agent-infra-internal agent-client next-steps --skill commit` 生成本场景的 `{next-step-commands}`。
 
 ```
 下一步 - 提交代码：
-  - Claude Code / OpenCode：/commit
-  - Gemini CLI：/{{project}}:commit
-  - Codex CLI：$commit
+{next-step-commands}
 ```
 
 ## 注意事项

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

@@ -51,7 +51,7 @@ The script outputs JSON to stdout. Parse and record the report.
 - `managed.conflicts`: guarded managed files with unknown origin, two-sided changes, or ownership that cannot be proven during a platform switch; list each target, reason, and three-way hash
 - `managed.removed`: deleted managed files (including old paths removed during template migrations)
 - `managed.skippedPlatform`: managed / merged entries skipped because they belong to a different platform
-- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in TUI that is disabled in `tuis` (customTUI command files under the same path prefix are preserved)
+- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (legacy `tuis` is migration-only; customTUI command files under the same path prefix are preserved)
 - `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
@@ -147,13 +147,13 @@ Based on the script report and merged results, output a complete update report i
 
 If there are changes to submit, add:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. 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).
+> Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
+
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit`.
 
 ```
 Next step - commit changes:
-  - Claude Code / OpenCode: /commit
-  - Gemini CLI: /{{project}}:commit
-  - Codex CLI: $commit
+{next-step-commands}
 ```
 
 Output the report, then **STOP** — do not make other changes to the project.