flower-trellis 0.4.12-beta.1 → 0.4.12-beta.2

package/enhancements/0.6/.agents/skills/trellis-check-all/SKILL.md

@@ -1,357 +1,351 @@
 ---
 name: trellis-check-all
-description: "Full pre-commit/PR review in 3 steps: spec-trio implementation correctness (code ↔ prd.md / design.md / implement.md when present) → 5-dim assumption validation (API, component context, data history/flow, tests) → cross-layer completeness + spec compliance (delegates to trellis-check). Pauses on ❌. Triggers: 「全面检查」「提交前检查」「check-all」「从 PRD 到代码过一遍」「从三件套到代码过一遍」. For lint/spec-only, use trellis-check directly."
+description: "提交前或 PR 前的全维度只读审查：规划三件套实现正确性 -> 关键假设验证 -> 跨层完整性与规范。默认 collect-all，不在用户确认修复范围前修改代码。触发：全面检查、提交前检查、check-all、从 PRD/三件套到代码过一遍。仅需 lint/spec 时使用 trellis-check。"
 ---
-# Check All — 全维度代码检查
+# Check All 全维度代码检查
 
-依次执行三个维度的代码检查，一次性完成全维度质量验证。
+依次检查规划正确性、实现假设、跨层完整性与规范性。默认采用 **audit-only collect-all**：先完成所有可继续的只读检查，统一报告问题，再由用户一次确认修复范围。
 
-> 顺序逻辑：**正确性 → 假设验证 → 完整性+规范性**
-> 先保证"做对了"，再保证"做全了"，最后保证"写好了"。
+> 顺序：做对了 -> 假设成立 -> 做全了且写得规范。
 
 ---
 
-## 执行模式
+## 核心边界
+
+1. **检查阶段只读**：可以读文件、搜索、运行无业务写入副作用的 lint、typecheck 和测试；不得编辑代码、配置、测试或任务规格。
+2. **问题统一收集**：普通实现偏差、测试失败、lint/typecheck 失败和假设错误都记录到问题集合，继续其余可执行检查，不逐项询问。
+3. **修改前只确认一次**：全部检查结束后，通过统一报告让用户选择 `修复全部`、按问题 ID 修复或仅保留报告。
+4. **委托规则不改变只读边界**：Step 3 只复用 `trellis-check` 的检查清单和验证方法，忽略其中任何“直接修复”“失败后先修复”的指令。
+5. **真正阻塞才中途暂停**：只有以下情况可以提前停止：
+   - 规划或业务行为互相冲突，无法判断正确实现；
+   - 已发现的问题使后续检查前提失效，继续会产生误导结论；
+   - 后续验证可能修改生产数据、调用有副作用的外部系统或执行破坏性操作。
 
-**各 Step 的具体 check 在主对话中直接展开执行，不要用 Agent 工具委派给子 agent 跑。**
+中途停止时也要使用本 skill 的统一问题模型，报告已完成范围和阻塞原因；只询问解除阻塞所需的业务或安全决策，不进入逐项修复问答。
+
+---
 
-原因：
-- 各 Step 中存在"发现问题立即暂停询问用户"的交互点，子 agent 无法交互式暂停
-- 检查结果的具体细节（哪一行、哪个假设错了）对后续修复很关键，子 agent 的摘要式返回会丢失细节
+## 执行模式
 
-**例外**：仅当用户显式要求"用子 agent 跑各 Step"或"并行执行"时，才使用 Agent 工具委派。
+- `inline check-all`：主会话直接执行本 skill。
+- `subagent check-all`：subagent 只负责 audit-only 检查并返回结构化结果；主会话负责展示报告、询问一次修复范围和协调后续修复。
+- subagent 不得自行修复，也不得代替用户选择修复范围。
+- 路由由 `trellis-route(target=check)` 决定；本 skill 不自行切换 inline/subagent。
 
 ---
 
-## 三个维度（按顺序执行）
+## 三个检查维度
+
+| 顺序 | 维度 | 检查内容 | 对照物 |
+| --- | --- | --- | --- |
+| 1 | 三件套实现 | 规划是否正确落地 | `prd.md` + 可选 `design.md` / `implement.md` |
+| 2 | 实现假设 | API、组件、历史数据、数据流和测试假设是否成立 | 源码、真实契约、可用验证证据 |
+| 3 | 完整性与规范 | 影响面是否同步、代码是否符合 spec、验证是否通过 | 实际变更范围 + 项目 spec |
 
-| 顺序 | 维度 | 检查什么 | 对照物 |
-|------|------|---------|--------|
-| 1 | 三件套实现 | 实现对不对 | `prd.md`（必读）+ `design.md` / `implement.md`（若存在） |
-| 2 | 假设验证 | 假设对不对 | 源码/真实数据 |
-| 3 | 完整性+规范性（trellis-check） | 改全了没 + 写得规范吗 | git diff 影响范围 + spec 开发规范 |
+维度状态统一使用：`通过`、`未通过`、`部分验证`、`阻塞`、`N/A`。
 
 ---
 
-## Step 0: 确认变更范围
+## Step 0：确认范围与适用性
+
+### 0.1 确认变更范围
+
+默认工作区检查：
 
 ```bash
-git diff --name-only
+git status --short
+git diff --name-only HEAD
+git ls-files --others --exclude-standard
 git log --oneline -10
 ```
 
-如果无变更，提示用户并终止。
+`git diff --name-only HEAD` 用于覆盖 staged + unstaged 的已跟踪文件，未跟踪文件由 `git ls-files` 补充。不能只用 `git diff --name-only` 判断“无变更”。
 
-读取当前任务的规划三件套：`prd.md`（必读，没有则跳过 Step 1 从 Step 2 开始）、`design.md`（若存在）、`implement.md`（若存在）。三件套由 trellis 的 session hook 自动加载，或手动确认任务目录。
+如果用户要求检查已经提交的 PR/分支改动，先确认目标基线，再使用 merge-base 对应的 diff 范围；`git log -10` 不能替代 PR 变更范围。
 
-> **Lightweight 任务**：通常只有 `prd.md`，Step 1 内的 Design / Implement 维度自动跳过
-> **Complex 任务**：三件套齐全，Step 1 对照矩阵覆盖三层（行为 / 契约 / 执行清单）
+如果确认范围内确实无变更，提示用户并终止。
 
----
+### 0.2 读取任务与规范
 
-## Step 1: 对照规划三件套检查实现
+读取当前任务：
 
-**重点**：三件套（PRD / Design / Implement）中的每条规划是否都正确实现了？有没有行为偏差、契约不一致、执行清单漏落地？
+- `prd.md`；没有时 Step 1 标记 `N/A`。
+- `design.md`（若存在）。
+- `implement.md`（若存在）。
+- `check.jsonl` 中列出的 spec/research 文件（若存在）。
+- 变更包对应的 `.trellis/spec/` 具体规范。
 
-### 1.1 核心原则（不可违反）
+不得只依赖 session 摘要推断规划内容，必须读取实际文件。
 
-1. **规划三件套都是验收依据** — PRD 的 Requirement / AC 是**行为基线**；Design（若存在）的 API 契约、数据模型、数据流、rollback 设计是**技术基线**；Implement（若存在）的有序步骤是**落地基线**。三层都要在代码中找到对应实现，找不到即为缺失
-2. **逐条追踪，不跳不漏** — 不能只看 happy path，PRD 中提到的边界条件、异常处理、空值场景都要追踪
-3. **读代码，不猜代码** — 必须实际读到实现代码，不能因为"应该写了"就标记通过
-4. **文案逐字比对** — PRD 中的 UI 文案（按钮、提示语、Toast、弹窗、表头、placeholder）必须与代码中的字面值**完全一致**
-5. **只报事实，不加发挥** — 报告中只陈述 PRD 要求 vs 代码实现的差异，不要加入 PRD 之外的建议
+### 0.3 选择快速路径或完整路径
 
-### 1.2 分解三件套为可验证条目
+**局部低风险路径**：文案、普通配置值、局部样式或单点条件修改，只追踪受影响的规划条目、直接引用点和必要回归路径。
 
-按优先级提取以下条目（design / implement 维度仅在对应文件存在时启用）：
+**完整适用范围路径**：存在以下任一条件时，对所有适用条目执行完整检查：
 
-**来自 `prd.md`（总是启用）**：
-1. **Acceptance Criteria** — 最直接的验证条目
-2. **Requirements** — 每条需求对应的行为
-3. **业务规则** — 条件判断、计算逻辑、状态流转
-4. **UI 文案** — 所有用户可见文字
-5. **边界/异常场景** — 空值处理、上限、错误提示等
+- API 契约或跨层数据流变化；
+- 数据模型、迁移或历史数据兼容变化；
+- 权限、鉴权、安全或资金相关变化；
+- 并发、时序、状态机或回滚机制变化；
+- 用户明确要求最终发布检查或完整审查。
 
-**来自 `design.md`（complex 任务启用）**：
+Step 2 各 Dimension 必须先判断 Trigger。未命中 Trigger 时标记 `N/A` 并立即跳过，不展开无关检查。
 
-6. **Design 契约** — API 路径 / 方法 / 入参 / 出参、数据模型字段名+类型+约束、数据流路径、关键 tradeoff 决策、rollout / rollback 设计
+---
 
-**来自 `implement.md`（complex 任务启用）**：
+## Step 1：对照规划三件套检查实现
 
-7. **Implement 执行清单** — 每个有序步骤是否落地、validation commands 的前置条件是否满足（**静态检查**；真跑命令归 Step 3 的 trellis-check 或用户执行）、review gates 是否到位、rollback points 是否实际可用
+### 1.1 验收依据
 
-每条记录格式：`[条目ID] <三件套原文摘要> — 来源：<prd / design / implement 中位置>`
+- PRD Requirement / Acceptance Criteria：行为基线。
+- Design API、数据模型、数据流、关键决策和 rollback：技术基线。
+- Implement 有序步骤、review gate 和 rollback point：落地基线。
 
-### 1.3 逐条追踪代码实现
+局部低风险路径只提取受影响条目；完整路径提取所有适用条目。每条记录来源位置，实际阅读对应代码后再判断。
 
-根据条目类型定位实现：
+### 1.2 必查类型
 
-| 条目类型 | 搜索方法 |
-|---------|---------|
-| API 接口行为 | Controller → Service → DAO，追踪完整链路 |
-| 前端交互行为 | 组件文件，事件处理、状态管理 |
-| 数据校验规则 | 前端 rules + 后端 validator/service，两端都查 |
-| UI 文案 | grep 关键字，前端代码精确匹配 |
-| 计算/转换逻辑 | service 层，读具体算法 |
-| 状态流转 | 状态枚举 + 转换条件代码 |
-| Design 契约（API / schema） | 实际 Controller / DTO / DB migration，对照路径、方法、字段名、类型、必填、默认值 |
-| Implement 执行步骤 | 代码 / 配置 / 迁移脚本是否处于 implement 步骤要求的状态（如：步骤说"加索引"则验证 migration 文件存在） |
+| 来源 | 可验证条目 |
+| --- | --- |
+| `prd.md` | AC、需求、业务规则、UI 文案、边界和异常场景 |
+| `design.md` | API 路径/方法/字段、数据模型、数据流、关键 tradeoff、rollout/rollback |
+| `implement.md` | 有序步骤是否落地、review gate 是否满足、rollback point 是否可用 |
 
-对每条标记状态：
+`implement.md` 中的 validation command 在本步骤只做静态前提核对；真实运行归 Step 3。
 
-| 状态 | 含义 |
-|------|------|
-| ✅ 已实现 | 代码正确实现了 PRD 要求（已读代码确认） |
-| ❌ 实现偏差 | 代码实现了，但行为与 PRD 描述不一致 |
-| 🔴 未实现 | 代码中找不到对应实现 |
-| ⚠️ 部分实现 | 核心逻辑有，但缺少边界/异常处理 |
-| 🟡 文案不一致 | UI 文案与 PRD 不逐字一致 |
+### 1.3 追踪方法
 
-### 1.4 重点检查场景（最容易漏）
+| 条目类型 | 追踪路径 |
+| --- | --- |
+| API 行为 | Controller/Handler -> Service -> DAO/Storage |
+| 前端交互 | 组件 -> 事件 -> 状态管理 -> API 调用 |
+| 数据校验 | 前端规则 + 后端 validator/service |
+| UI 文案 | 组件、i18n/locale 或其它有效文案来源 |
+| 计算转换 | 实际 service/utility 算法及边界值 |
+| 状态流转 | 状态定义 + 允许的转换条件 |
+| Schema | DTO/类型/迁移中的字段、类型、约束和默认值 |
+| Implement 步骤 | 对应代码、配置、迁移或资产是否存在且可用 |
 
-- **条件判断** — PRD 说"当 X 时做 Y"，if 条件是否完整？是否漏边界值？
-- **空值/零值** — PRD 提到的字段，代码在该字段为空时是否有处理？
-- **列表为空** — 列表展示是否有空状态/提示？
-- **并发/时序** — 多步操作是否处理了中间状态？
-- **权限控制** — PRD 提到的按钮/操作，是否加了权限判断？
-- **前后端一致** — 同一条规则前后端是否都实现了？
+文案要求逐字一致时，对照最终有效文案来源；不要强制要求文案必须直接写在组件字面量中。
 
-### 1.5 问题记录模板
+### 1.4 记录结果
 
-发现问题时按如下格式逐条记录（供最终汇总报告引用）：
+发现偏差、缺失、部分实现或文案不一致时，写入统一问题集合并继续。不要在此步骤询问“先修还是继续检查”。
 
-**❌ 实现偏差 / 🔴 未实现 / ⚠️ 部分实现**：
+---
 
-```markdown
-##### [条目ID] <三件套原文摘要> ｜ 来源：<prd / design / implement>
-- **规划要求**：<原文>
-- **实际实现**：<代码行为描述>
-- **代码位置**：<文件路径:行号>
-- **偏差/缺失说明**：<具体差异或缺失点>
-```
+## Step 2：实现假设验证
 
-**🟡 文案不一致**（用表格汇总）：
+根据实际变更选择适用 Dimension。每个适用 Dimension 都要确认源码或真实契约证据，不能凭记忆通过。
 
-| PRD 文案 | 代码文案 | 代码位置 |
-|---------|---------|---------|
+### Dimension A：API Contract
 
-> **如果发现 ❌ 实现偏差或 🔴 未实现，立即暂停**，展示问题并询问用户：
-> - 先修复再继续后续检查？
-> - 还是先跑完全部检查，最后统一修复？
+**Trigger**：新增或修改已有 API 调用、请求参数或响应解析。
 
----
+- 读取 Controller/Handler 和 DTO/Schema，确认实际请求、响应结构。
+- 找到项目内同 API 或同模式调用作为参考。
+- 确认参数名、类型、默认值、分页字段和起始页码。
+- 覆盖正常、空值、零值和错误响应。
 
-## Step 2: 实现假设验证
+### Dimension B：Component Context
 
-**重点**：API 响应结构、组件生命周期、历史数据兼容性等假设是否正确？大多数实现 bug 不是逻辑错误，而是前提假设错了。
+**Trigger**：在 Modal、Drawer、Tab 或条件渲染容器内修改有状态组件。
 
-根据变更类型选择适用的 Dimension 检查：
+- 确认容器关闭或切换时是否销毁子组件。
+- 确认受控值、初始化值和外部状态绑定。
+- 确认状态保持/重置行为符合规划。
+- 对照项目内相同容器的既有用法。
 
-### Dimension A: API Contract（调用了已有 API 时）
+### Dimension C：Data History
 
-**Trigger**：前端新增/修改了对后端 API 的调用
+**Trigger**：新增、修改或重新解释持久化字段。
 
-**Checklist**：
-- [ ] 读过 Controller/Handler 源码，确认实际响应结构？
-- [ ] 找到项目中已有的同 API 调用代码作为参考？
-- [ ] 请求参数名、类型、默认值从源码确认（非凭记忆）？
-- [ ] 分页接口：确认了分页字段名和起始页码？
+- 确认历史记录的新字段值和 null/零值行为。
+- 确认过滤、聚合和降级查询能处理历史数据。
+- 追踪新字段的写入来源和可靠性。
+- 无可用历史数据环境时标记 `部分验证` 或 `阻塞`，不得标记通过。
 
-**典型错误假设**：
+### Dimension D：Data Flow Trace
 
-| 错误假设 | 实际情况 |
-|---------|---------|
-| `res.data.data` 是数组 | 实际是 `{ items: [], total }` 分页结构 |
-| 参数名是 `page` | 实际是 `p`，且从 1 开始 |
-| 响应直接是业务数据 | 实际包了一层 `{ success, message, data }` |
+**Trigger**：变更跨越 UI、API、Service、Storage 中的两个或更多边界。
 
-### Dimension B: Component Context（在容器内使用组件时）
+- 模拟完整请求路径和返回路径。
+- 确认各层参数名、类型、嵌套层级一致。
+- 覆盖缺省、空值、零值、特殊字符和错误传播。
+- 分层代码分别正确不等于整条链路正确，必须连起来核对。
 
-**Trigger**：在 Modal / Drawer / Tab / 条件渲染块内使用有状态组件
+### Dimension E：Verification Tests
 
-**Checklist**：
-- [ ] 确认容器关闭/切换时是否销毁子组件？
-- [ ] 如需保持状态：是否用了 keepDOM / destroyOnClose={false} 等配置？
-- [ ] 受控组件的 value 与外部 state 是否正确绑定？
-- [ ] 找到项目中同容器内的组件用法作为参考？
+**Trigger**：Dimension A-D 任一适用。
 
-**典型错误假设**：
+- 检查关键假设是否已有可运行的自动化测试或明确手动验证。
+- 优先覆盖最脆弱的参数名、嵌套结构、历史数据和空值路径。
+- 测试存在时实际运行；未运行不能报告通过。
+- 缺少测试时记录问题，等待用户确认修复范围后再新增测试。
 
-| 错误假设 | 实际情况 |
-|---------|---------|
-| Modal 关闭后表单状态保留 | 默认销毁子组件，再开状态丢失 |
-| value 传了就是受控 | 某些组件需 initValue + value 配合 |
-| 组件在任何地方行为一致 | 容器上下文会影响挂载/卸载行为 |
+发现假设错误时写入统一问题集合并继续其它可执行检查。只有该错误让后续检查前提失效时，才按“真正阻塞”规则暂停。
 
-### Dimension C: Data History（修改了数据模型时）
+---
 
-**Trigger**：数据库表新增/修改了字段
+## Step 3：完整性、规范与项目验证
 
-**Checklist**：
-- [ ] 历史记录的新字段值是什么（空/零值/null）？
-- [ ] 用新字段过滤时，历史数据能否被正确查到？
-- [ ] 是否需要降级查询路径（如从其他表补查历史数据）？
-- [ ] 写入链路中新字段的值从哪来？来源是否可靠？
+读取 `.agents/skills/trellis-check/SKILL.md`（Claude-only 项目读取对应 `.claude` 副本），复用以下内容：
 
-**典型错误假设**：
+- 适用 spec 的读取方法；
+- lint、typecheck、测试等项目验证命令；
+- 测试覆盖、跨层数据流、复用、依赖和同层一致性检查；
+- debug logging、warning suppression 和类型安全绕过检查。
 
-| 错误假设 | 实际情况 |
-|---------|---------|
-| 加了字段就有数据 | 旧记录新字段全是零值/空值 |
-| 只查聚合表就够了 | 聚合表缺维度，需从明细表降级查询 |
-| 字段值肯定有 | 某些调用链路中该值可能为空 |
+### Audit-Only 覆盖规则
 
-### Dimension D: Data Flow Trace（跨层变更时）
+在 Check-All 内执行时，下列 `trellis-check` 指令一律失效：
 
-**Trigger**：变更涉及 前端 ↔ API ↔ 数据库 的数据传递
+- “Fix any failures before proceeding”；
+- “fix them directly”；
+- “Report and Fix”；
+- 任何要求检查 agent 直接编辑、补测试或反复修到通过的语句。
 
-**Checklist**：
-- [ ] 模拟一条完整请求路径：前端发什么 → 后端收什么 → 查出什么 → 返回什么 → 前端解析什么？
-- [ ] 前端参数名 === 后端 Query/Body 参数名？
-- [ ] 后端返回结构 === 前端解析结构？
-- [ ] 空值/零值场景：不填该字段时，每一层的行为是否正确？
+验证失败时记录命令、退出状态和关键错误到统一问题集合，继续其它独立验证。可能写业务数据或外部系统的验证不直接运行，按真正阻塞规则处理。
 
-**典型错误假设**：
+---
 
-| 错误假设 | 实际情况 |
-|---------|---------|
-| 代码看起来对就能跑 | 参数名差一个字母、嵌套差一层 |
-| 只检查非空路径 | 空值路径才是出 bug 最多的地方 |
-| 前后端分别看都没问题 | 放一起跑时数据对不上 |
+## 统一问题模型
 
-### Dimension E: Verification Tests（验证关键假设的测试）
+每个独立根因使用固定字段：
 
-**Trigger**：任何涉及 Dimension A-D 的变更
+| 字段 | 规则 |
+| --- | --- |
+| ID | 首次记录时依次分配 `CHK-001`、`CHK-002`；当前修复/重检循环中不重新编号 |
+| 严重度 | `P0` 数据破坏/安全事故/无法安全继续；`P1` 功能错误/需求违背/发布阻塞；`P2` 测试/规范/维护性/非阻塞风险 |
+| 标题 | 描述根因，不用症状堆叠 |
+| 来源 | prd/design/implement/spec/assumption/verification |
+| 证据 | `file:line`、实际契约或命令结果 |
+| 影响 | 用户、数据或工程影响 |
+| 建议 | 推荐修复方式，不在检查阶段执行 |
+| 位置 | 同一根因的全部受影响位置 |
+| 验证 | 修复后的命令或手动验证步骤 |
 
-光靠肉眼审查不够，关键假设必须有可运行的验证手段：
+同一根因的多个位置合并到一个问题。报告按严重度排序，但不得因此重排已经分配的 ID。新根因使用下一个 ID。
 
-- **API Contract 验证**：写请求测试验证实际响应结构与解析匹配，覆盖 happy + 空值/零值
-- **数据模型验证**：用真实数据（含历史旧记录）验证过滤/聚合结果
-- **跨层数据流验证**：端到端测试完整路径，覆盖空参数、特殊字符、零值
+---
 
-**验证原则**：
-- 不要求高覆盖率，但每个 Dimension 中发现的关键假设至少有一个测试保护
-- 优先写能暴露"想当然"问题的测试，而非走过场的 happy path
-- 如果无法写自动化测试，记录手动验证步骤和预期结果
+## 输出：统一检查报告
 
-**典型错误做法**：
+普通模式完成所有可继续检查后，严格按以下顺序输出：
 
-| 错误做法 | 正确做法 |
-|---------|---------|
-| 只写 happy path 测试 | 优先覆盖假设最脆弱的路径 |
-| 测试写了但没跑 | 测试必须实际运行并通过 |
-| "这个太简单不用测" | 越简单的假设越容易错（参数名、嵌套层级） |
+```markdown
+## Trellis Check-All 结果
 
-### Common Issues Quick Reference（假设类 bug 速查）
+[<通过/未通过/阻塞>] <N> 个维度 · <N> 个问题 · P0 <N> / P1 <N> / P2 <N> · 验证 <通过>/<总数>
 
-| Issue | Root Cause | Prevention |
-|-------|------------|------------|
-| API 调用返回 undefined | 响应结构假设错误 | 读 Controller 确认 |
-| 组件状态莫名丢失 | 容器销毁了子组件 | 检查容器生命周期 |
-| 筛选后数据为空 | 历史记录缺字段 | 验证旧数据查询路径 |
-| 参数传了但后端没收到 | 参数名不匹配 | 源码级确认参数名 |
-| 看着对但跑不通 | 只做了静态审查 | 模拟完整数据流 |
+任务：<任务名称或无活动任务>
+范围：<文件数与层级摘要>
+结论：<一句话结论>
 
-> **如果发现假设错误**，同样立即暂停询问用户（先修复 or 跑完再统一修）。
+### 维度结果
 
----
+| 维度 | 状态 | 问题 | 验证 |
+| --- | --- | ---: | --- |
+| 三件套实现 | <通过/未通过/部分验证/阻塞/N/A> | <N> | <摘要> |
+| 实现假设 | <通过/未通过/部分验证/阻塞/N/A> | <N> | <摘要> |
+| 完整性与规范 | <通过/未通过/部分验证/阻塞/N/A> | <N> | <摘要> |
 
-## Step 3: 跨层完整性与代码规范检查
+### 问题清单
 
-按 `.agents/skills/trellis-check/SKILL.md` 执行。
+- [ ] `CHK-001` `[P1]` <标题>
+  - 来源：<来源>
+  - 证据：<file:line / 契约 / 命令结果>
+  - 影响：<影响>
+  - 建议：<修复建议>
+  - 位置：<全部受影响位置>
+  - 验证：<验证命令或步骤>
 
-**重点**：变更涉及的所有层、所有引用点是否都同步更新了？代码是否符合项目 spec 中的编码规范？lint 和 typecheck 是否通过？
+### 未覆盖与风险
 
----
+- [<部分验证/阻塞/N/A>] <说明>
 
-## 输出：汇总报告
+### 修复批次
 
-所有检查完成后，输出一份汇总报告：
+批次 1：<问题 ID> · <修复目标>
+修复后：定向验证 -> Check-All 重检
 
-```markdown
-## Check All 汇总报告
+操作：`修复全部`、`修复 CHK-001,CHK-003`、`仅保留报告`
+```
 
-### 任务: <任务名称>
+展示规则：
+
+- 没有问题时省略“问题清单”“修复批次”和操作行，只报告通过结果、验证和剩余风险。
+- 有问题时只在报告末尾提供一次修复范围选择，不再逐项提问。
+- 独立问题不得因数量多而静默省略；先合并同根因重复项，再完整列出剩余问题。
+- 报告不得包含 commit message、拟提交/暂存文件、commit-only 决策或提交确认。
 
 ---
 
-### 各维度结果
+## 修复与重检
 
-| 维度 | 状态 | 问题数 | 关键问题 |
-|------|------|--------|---------|
-| 三件套实现 | ✅/❌ | N | <最严重的问题摘要 + 来源层> |
-| 假设验证 | ✅/❌ | N | <最严重的问题摘要> |
-| 跨层完整+规范 | ✅/❌ | N | <最严重的问题摘要> |
+用户选择修复范围后：
 
-### 问题清单（按优先级排序）
+1. 主会话复用当前任务已有的合法 implement route，批量修复选中的无歧义问题；不存在合法 implement route 时先进入 `trellis-route(target=implement)`，不得自行默认 inline/subagent。
+2. 修复过程中不对每个问题重复确认。
+3. 新增业务歧义、破坏性风险或范围扩张时才暂停，并一次性说明受影响问题。
+4. 完成定向验证后复用当前 check route 重新执行 Check-All。
+5. 原问题沿用 ID；新根因继续递增编号。
 
-#### P0 — 功能性 BUG（来自 Step 1 / Step 2）
-<PRD 实现偏差 / 🔴 未实现 / 假设错误>
+修复完成后输出：
 
-#### P1 — 完整性+规范问题（来自 Step 3）
-<跨层遗漏 / lint / typecheck / 规范违反>
+```markdown
+## Trellis Check-All 修复结果
 
-### 结论
-- <总体评价：整体完成度>
-- <建议修复顺序：P0 先修，P1 可视情况合并修>
-```
+[<完成/部分完成/失败>] 修复 <完成>/<计划> · 验证 <通过>/<总数> · 剩余问题 <N>
 
----
+| 问题 | 修复 | 验证 |
+| --- | --- | --- |
+| CHK-001 | <已修复/未修复/阻塞> | <通过/失败/未执行> |
 
-## Post-check 停止边界
+### 未修复与风险
 
-汇总报告输出后立即停止，等待用户继续。普通流程的本轮输出只允许包含：
+- <问题或风险；没有时写“无”>
 
-- 各检查维度的状态与问题数
-- 已执行的验证命令和结果
-- 未覆盖的环境验证或剩余风险
-- 总体结论
-- 下一步指向现有 Phase 3.3，再到 Phase 3.4 `trellis-push`
+结论：<重检结论与下一步>
+```
 
-本轮禁止出现 commit message、`Proposed commits`、拟提交/暂存文件、commit-only 决策或“回复 `ok` 执行提交”。这些内容属于后续 Phase 3.4，并且只能由 `trellis-push` 生成。运行中的 auto-loop 仍按 runner 的 `record` + `next` 规则继续，不受普通 post-check stop 影响。
+检查通过后才指向 Phase 3.3 `trellis-update-spec`，再到 Phase 3.4 `trellis-push`。仍有问题时停留在修复/重检循环。
 
 ---
 
-## 修复问题（需用户确认）
+## Auto-Loop 规则
 
-如果发现问题，**先展示报告，获得用户确认后再修复**。
+运行中的 auto-loop 复用相同的 audit-only 检查和问题模型，但不展示普通模式的修复选择：
 
-修复时遵循：
-- **按严重程度排序**：❌ 实现偏差 > 🔴 未实现 > ⚠️ 部分实现 > 🟡 文案不一致 > P1 完整性/规范
-- **每修一条标注 PRD 条目 ID 或问题位置**
-- **修复后重新验证该条目**
+- 有问题：向 runner `record --result failed`，摘要包含最高严重度、问题 ID、根因和受影响文件；随后由 runner 进入 `run_fix`。
+- 真正需要用户产品决策或越权：`record --result blocked`。
+- 无问题：`record --result ok`，继续 runner 返回的下一步。
+- 不修改 runner 的 fix/recheck 预算、commit-only 授权或队列行为。
 
 ---
 
-## 使用时机
-
-- **开发完成后、提交前** — 作为 `trellis-finish-work` 之前的全面检查
-- **Code Review 前** — 自查一遍再提交 MR
-- **不确定改动质量时** — 跑一遍全量检查心里有底
+## Post-Check 停止边界
 
----
+普通检查报告输出后立即停止并等待用户选择。允许输出的内容只有：
 
-## 注意事项
+- 各维度状态、问题数和问题清单；
+- 已执行验证及结果；
+- 未覆盖验证和剩余风险；
+- 总体结论；
+- 有问题时的一次修复范围选择，或通过时的 Phase 3.3 / Phase 3.4 下一步指向。
 
-- 每个维度独立输出报告，最后汇总
-- 如果某个维度发现严重问题（❌ / 🔴），会暂停询问是否先修复
-- 如果当前任务没有 PRD，自动跳过 Step 1，从 Step 2 开始
-- Step 1 对照矩阵随任务复杂度自动扩展：lightweight 仅查 prd 五类条目；complex 在场则追加 design 契约 + implement 执行清单两类条目
-- 只想快速检查某一维度：
-  - 只查规范/跨层：直接用 `trellis-check` skill
-  - 只查 PRD 或假设：在 prompt 里指定"只做 Step 1"或"只做 Step 2"
+禁止在本轮生成提交计划、commit message、拟提交文件或要求用户确认提交。
 
 ---
 
-## 反模式（避免）
-
-- ❌ 不读代码，凭"应该实现了"就标记通过
-- ❌ 只检查 happy path，忽略 PRD 提到的边界/异常场景
-- ❌ 文案只看"意思对"就通过（必须逐字一致）
-- ❌ 只查后端不查前端，或反之
-- ❌ 检查报告中加入三件套之外的改进建议（只对照规划，不发挥）
-- ❌ 发现问题直接改，不经用户确认
-- ❌ 委派给子 agent 跑各 Step（见执行模式段）
-- ❌ Complex 任务下只对照 PRD，忽略 `design.md` / `implement.md`（三层都要查）
-- ❌ 把 `implement.md` 的 validation commands 真跑算到 Step 1（Step 1 是静态对照；真跑归 Step 3 或用户执行）
-- ❌ 汇总报告后自行草拟 commit message / `Proposed commits` / 文件提交计划，或要求用户回复 `ok` 提交
+## 反模式
+
+- 发现一个普通问题就暂停询问一次。
+- 检查阶段直接修改代码、配置或测试。
+- 把 `trellis-check` 的自动修复指令带入 Check-All。
+- 未命中 Trigger 仍展开所有 Step 2 Dimension。
+- 无环境证据却把维度标记为通过。
+- 按检查步骤而不是实际影响划分严重度。
+- 同一根因拆成大量重复问题，或因问题多而静默省略。
+- subagent 自行选择修复范围或返回前修改工作区。
+- 报告后直接进入 commit/push。