@ibotor/smart-trellis 0.5.22 → 0.5.24

package/dist/templates/common/bundled-skills/trellis-quality-review/docs/overview.md

@@ -0,0 +1,331 @@
+# Trellis Quality Review 介绍
+
+## 目的
+
+`trellis-quality-review` 是一个用于前端实现或重构完成后的结构化 review skill。它的目标是让 agent 像资深前端工程师一样审查当前前端 diff：保护需求范围、防止 scope creep、识别当前改动引入的质量问题、避免无关清理、选择合适的验证方式，并输出有证据支撑的交付报告。
+
+这个 skill 的设计是克制的。它不是为了把整个代码库变得更干净，而是为了让**当前这一次前端改动**变得安全、聚焦、可维护、可验证。
+
+## 两个核心思想
+
+### 1. 克制感：当前需求边界 > 代码洁癖
+
+这是这个 skill 最重要的设计取向。
+
+很多 review 流程的问题是：一旦发现旧代码不优雅、组件太大、命名不统一、历史 lint 不干净，就会顺手扩大修改范围。`trellis-quality-review` 反过来要求 agent 先判断问题是否属于当前 diff：
+
+- 当前 diff 引入的问题，可以按严重程度处理。
+- 为当前需求正确性所必需的相邻问题，可以作为 necessary adjacent 处理。
+- 历史问题、未触碰代码、来源不明的用户改动，默认只记录为 Note Only。
+- 即使代码可以更优雅，也不能为了“代码洁癖”扩大本次 diff。
+
+因此它的默认心智模型是：**发现问题不等于立刻修复；先判断边界，再决定行动。**
+
+### 2. 封装思想：合理拆分，不制造抽象噪音
+
+这个 skill 支持组件拆分、composable/hook 抽取、helper 移动和类型边界整理，但它反对“为了拆而拆”。
+
+它判断封装是否合理时，会优先看职责是否清晰、边界是否由当前需求触发、抽取后接口是否更小：
+
+- page / route / container 应主要负责路由、数据加载和页面编排。
+- component 应负责一个可命名的 UI 区块。
+- composable / hook 应承载状态、副作用、异步流程和派生状态。
+- helper 应承载纯格式化、映射、校验和计算逻辑。
+- api / types 应表达外部接口和共享契约边界。
+
+安全封装的判断不是“文件大不大”，而是：当前 diff 是否让某个职责变得独立、可命名、可验证。如果抽取会带来大量 props 透传、移动未触碰代码、改变 copy/layout/event timing，或者只是制造 `Common`、`Base`、`Utils` 这类模糊抽象，就应该停止，并把它记录为后续建议。
+
+一句话总结：**该拆时拆出清晰职责，不该拆时保持局部，避免把扎堆变成过度工程。**
+
+## 什么时候使用
+
+当前端工作已经实现或重构完成后，可以使用这个 skill，尤其是 diff 涉及：
+
+- Vue、React、Next.js、组件、路由、store、composable、hook 或 UI 状态
+- 表单、表格、弹窗、抽屉、上传流程、校验逻辑、API payload 映射
+- 用户可见文案、label、placeholder、选项顺序、helper text、提示信息
+- 容易混入无关格式化变更的文件
+- 交付前需要说明 lint、typecheck、测试或 build 状态的改动
+
+纯后端改动不适合使用这个 skill。对于非常小的前端改动，它内置了“微改快速通道”，在合适时只做 diff inspection，不进入完整 review。
+
+## 设计原则
+
+下面的设计原则是对上面两个核心思想的展开：先保持克制，再做安全封装。
+
+### 1. 需求范围优先
+
+skill 会先复述当前需求，并把需求和当前 diff 对比。每个变更块都应该被分类为：
+
+- **In requirement**：直接实现或验证用户要求的改动
+- **Necessary adjacent**：为了让当前改动正确、类型通过、lint 通过或可构建而必要的相邻改动
+- **Out of scope**：无关格式化、文案润色、宽泛重构、历史清理、重命名抽象、非必要行为变更
+
+这可以避免常见的 review 失败模式：agent 顺手优化无关代码，导致 diff 被扩大。
+
+### 2. 当前 diff 边界
+
+默认 review 边界是当前未提交 diff：`git diff HEAD`，包含 staged 和 unstaged 改动。
+
+如果用户要求只 review staged 内容，边界变成 `git diff --cached`。如果用户要求按分支或 PR 风格 review，边界可以是指定 base ref，例如 `main`。
+
+历史问题和未触碰文件通常归为 **Note Only**。除非它们阻塞当前需求，否则不应在本次 review 中修复。
+
+### 3. 文案和格式化都很敏感
+
+用户可见文案和选项顺序是产品行为，不是无害字符串。格式化-only diff 也是代码变更，因为它会增加 review 难度，并可能掩盖逻辑变化。
+
+因此这个 skill 把 copy fidelity 和 formatting fidelity 从普通代码质量检查中单独拆出来，避免 agent 无意中保留无关 churn。
+
+### 4. 安全重构，而不是过度重构
+
+这个 skill 支持组件拆分和逻辑抽取，但只在当前 diff 形成明确职责边界时进行。文件大本身不是拆分理由。
+
+一个安全的 refactor 至少需要满足：被抽出的职责由当前需求触碰；边界可以清楚命名；新接口比隐藏的复杂度更小；行为、文案、布局和公开契约保持不变。
+
+### 5. 先分级，再修复
+
+发现问题后先分级，再决定是否修复：
+
+- **Blocker**：交付前必须修
+- **Must Fix Before Handoff**：当前 diff 引入、不能带入交付的问题
+- **Should Fix If In Scope**：真实问题，但只有在范围内且改动小才修
+- **Note Only**：历史、未触碰、来源不明或超出范围的问题
+
+这能让 review 更像资深工程师：真正重要的问题不会被淹没，历史问题也不会劫持当前任务。
+
+### 6. 验证方式匹配风险
+
+这个 skill 避免两个极端：既不盲目跑所有命令，也不会对有意义的逻辑改动跳过验证。
+
+验证方式应根据当前 diff 的风险选择：
+
+- 细小 UI / copy / style / config 改动：diff inspection 可能足够
+- 类型、model、payload 改动：优先 typecheck 和相关测试
+- Vue SFC 改动：优先 lint 和 Vue/typecheck 脚本
+- React/Next route 或 server/client 边界改动：lint/typecheck，必要时 build
+- 历史失败：单独报告，不要声称全部通过
+
+## 目录结构
+
+```text
+trellis-quality-review/
+├── SKILL.md
+├── docs/
+│   └── overview.md
+├── references/
+│   ├── decision-tree.md
+│   ├── small-change-fast-path.md
+│   ├── scope-control.md
+│   ├── formatting-fidelity.md
+│   ├── copy-fidelity.md
+│   ├── framework-rules.md
+│   ├── safe-refactor-boundaries.md
+│   ├── severity.md
+│   ├── verification-selection.md
+│   └── report-format.md
+├── scripts/
+│   └── diff_scans.sh
+└── evals/
+    └── evals.json
+```
+
+## 文件职责
+
+### `SKILL.md`
+
+入口文件。它定义 skill 的使用场景、依赖的子 skill、reference 路由模型、整体 workflow 和操作原则。
+
+它应该保持简短。详细规则应放在 `references/` 中。
+
+### `docs/overview.md`
+
+给人看的说明文档。它解释这个 skill 的架构、设计意图、执行流程和维护方式。它适合用于分享、交接和理解整体设计，不是每次运行时都必须读取的执行规则。
+
+### `references/decision-tree.md`
+
+执行路由器。它根据 diff 中的信号决定 agent 应该继续读取哪些更细的 reference，例如：
+
+- 是否是微改
+- 是否涉及 Vue / React / Next
+- 是否有组件边界问题
+- 是否有格式化 churn
+- 是否有文案变化
+- 是否有可疑前端模式
+- 是否需要 severity 分级
+- 是否需要选择验证命令和最终报告格式
+
+这个文件的作用是减少漏检查。
+
+### `references/small-change-fast-path.md`
+
+定义什么时候前端改动足够小，可以不进入完整 review，也不默认跑 broad lint/typecheck/test/build。
+
+典型例子包括单行间距、宽度、颜色、明确要求的文案、小范围样式改动，并且不能涉及 API、状态流、类型、校验或数据转换。
+
+使用该路径时，最终报告必须说明为什么只做了有限验证。
+
+### `references/scope-control.md`
+
+定义需求边界和变更块分类方式。它是防止 scope creep 的核心护栏。
+
+### `references/formatting-fidelity.md`
+
+说明如何识别和处理 formatting-only churn，例如对比普通 diff 和忽略空白 diff：
+
+```bash
+git diff HEAD -- path/to/file
+git diff -w HEAD -- path/to/file
+```
+
+### `references/copy-fidelity.md`
+
+说明如何 review 用户可见文案和选项顺序。覆盖 label、placeholder、helper text、button text、validation message、modal title、table column title、本地化字符串等。
+
+### `references/framework-rules.md`
+
+提供 Vue、React、Next.js、样式、路由、store、composable、hook 和组件边界相关的前端 review 规则。
+
+它不会复制完整框架最佳实践，而是把更深入的 Vue 和 React/Next 细节交给专门的 `vue-best-practices` 和 `vercel-react-best-practices` skill。
+
+### `references/safe-refactor-boundaries.md`
+
+定义什么时候可以安全拆组件、抽 composable/hook、移动 helper 或改变 ownership。它同时防止“职责扎堆”和“过度封装”。
+
+### `references/severity.md`
+
+定义 review 严重程度模型：
+
+- Blocker
+- Must Fix Before Handoff
+- Should Fix If In Scope
+- Note Only
+
+它帮助 agent 判断哪些问题现在必须修，哪些应该延后，哪些只需要记录。
+
+### `references/verification-selection.md`
+
+定义如何根据 diff 风险选择验证命令。它说明如何发现 package scripts，如何选择 lint/typecheck/test/build，如何处理命令不存在，以及如何报告历史失败。
+
+### `references/report-format.md`
+
+定义最终交付报告格式：
+
+- Scope Check
+- Severity
+- Formatting Fidelity
+- Copy Fidelity
+- Changed
+- Removed
+- Verified
+- Notes
+
+### `scripts/diff_scans.sh`
+
+高信号 diff 扫描脚本。支持：
+
+```bash
+scripts/diff_scans.sh
+scripts/diff_scans.sh --files
+scripts/diff_scans.sh --cached
+scripts/diff_scans.sh --base main
+scripts/diff_scans.sh --json
+```
+
+它会扫描前端变更文件、调试代码、TypeScript 风险、Vue 风险、React/Next 浏览器边界风险，以及潜在 copy/accessibility 变化。
+
+扫描命中只是信号，不是自动缺陷。agent 必须结合上下文再决定是否修复。
+
+### `evals/evals.json`
+
+skill 的评估场景。覆盖 scope control、copy/formatting fidelity、small-change fast path、staged-only review、severity classification、verification selection、diff scans 和 safe refactor boundaries。
+
+## 典型 review 流程
+
+一次正常 review 通常按这个顺序进行：
+
+1. 复述当前需求。
+2. 检查当前 review 边界，通常是 `git status` 和 `git diff HEAD`。
+3. 读取 `decision-tree.md`，决定后续需要哪些检查。
+4. 如果 diff 符合微改条件，走 small-change fast path。
+5. 否则进入 scope control。
+6. 运行或手动复现 `diff_scans.sh`。
+7. 如果触发，执行 formatting fidelity 和 copy fidelity 检查。
+8. 如果涉及结构性 review，应用 framework rules 和 safe refactor boundaries。
+9. 对发现的问题做 severity 分级。
+10. 只修复当前范围内的问题。
+11. 选择并运行合适的验证命令。
+12. 按规定格式输出最终报告。
+
+## 示例场景
+
+### 细小 UI 改动
+
+表格列宽从 `120` 改为 `140`。
+
+期望行为：
+
+- 使用 small-change fast path
+- 只检查局部 diff
+- 默认跳过 broad lint/typecheck/test/build
+- 报告本次只使用 diff inspection 作为有限验证
+
+### 逻辑改动中混入文案 churn
+
+需求是增加一个必填 domain 字段，但 diff 同时改写了 radio helper text 并调整了选项顺序。
+
+期望行为：
+
+- 保留 domain 字段相关改动
+- 在安全时恢复无关 helper text 和选项顺序
+- 将 out-of-scope copy change 分类为 Must Fix Before Handoff
+- 报告 copy fidelity 检查结果
+
+### 安全抽取弹窗
+
+一个 Vue 页面改动新增了 edit modal，里面包含字段、校验、提交处理、loading 状态和 API mapping，并且这些逻辑都塞进了一个已经很大的页面。
+
+期望行为：
+
+- 识别 modal 是当前 diff 引入的、可命名的独立职责
+- 只考虑抽取 modal 边界
+- 不重构未触碰的 table/search 区域
+- 报告为什么这个抽取是安全的
+
+### 历史类型错误
+
+当前 diff 新增了一个 `console.log`，改了一个与需求无关的 placeholder，同时项目原本就在未触碰的 legacy 文件里有 `vue-tsc` 错误。
+
+期望行为：
+
+- 移除当前 diff 新增的 `console.log`
+- 恢复无关 placeholder
+- 将历史 `vue-tsc` 错误分类为 Note Only
+- 不修改 legacy 文件
+
+## 与 hooks 的关系
+
+这个 skill 不依赖 hooks。它是一个给 agent 使用的判断型 workflow。
+
+hooks 可以作为补充，用来自动扫描或强制简单规则，例如：
+
+- commit 前运行 `diff_scans.sh --cached`
+- 阻止 staged diff 中出现 `console.log` 或 `debugger`
+- 当前端文件发生变化但没有 review 时给出提醒
+- 输出 JSON 扫描结果给自动化流程使用
+
+hooks 通常应该负责检测和提示，不应该自动执行结构性重构或文案修改。
+
+## 维护建议
+
+保持这个 skill 模块化：
+
+- 运行时执行规则放到 `references/`
+- 给人看的说明放到 `docs/`
+- 确定性的辅助工具放到 `scripts/`
+- 评估场景放到 `evals/`
+- `SKILL.md` 保持为简短路由器
+
+不要把宽泛的前端最佳实践百科塞进这里。更深入的框架规则应该交给专门 skill，例如 `vue-best-practices` 和 `vercel-react-best-practices`。
+
+扩展这个 skill 时，优先添加一个聚焦规则，并配套一个 eval 场景；不要添加没有测试覆盖的大型 checklist。

package/dist/templates/common/bundled-skills/trellis-quality-review/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "trellis-quality-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review my Vue form changes. The request was only to add a required domain field, but the diff also changed radio helper text, option order, and some line wrapping. Clean up only what belongs to the request and report verification.",
+      "expected_output": "The skill should identify out-of-scope copy and formatting changes, restore them when safe, keep the required domain field work, and report scope/copy/formatting checks."
+    },
+    {
+      "id": 2,
+      "prompt": "I finished a React settings page refactor. Please do a frontend quality review. Watch for unnecessary component splits, dead code from the current diff, and whether lint/typecheck should be run.",
+      "expected_output": "The skill should review component boundaries, remove current-work dead code only, avoid broad legacy cleanup, and provide exact verification commands and results."
+    },
+    {
+      "id": 3,
+      "prompt": "Check this frontend diff before handoff. It includes a new Vue table feature plus a couple of console.log and @ts-ignore lines added while debugging. Do not touch unrelated old warnings.",
+      "expected_output": "The skill should use diff-only scans, fix newly introduced suspicious lines, avoid unrelated legacy issues, and summarize skipped findings."
+    },
+    {
+      "id": 4,
+      "prompt": "Review a Next.js page change where the route component now owns data fetching, modal state, validation, and three UI sections. Decide if the current change needs component or hook extraction without over-abstracting.",
+      "expected_output": "The skill should apply framework rules, build a responsibility map, propose or perform targeted extraction only if it clarifies the current requirement, and verify behavior."
+    },
+    {
+      "id": 5,
+      "prompt": "This is a tiny Vue UI tweak: I only changed one table column width from 120 to 140. Please review it, but don't run the full lint/typecheck/build unless needed.",
+      "expected_output": "The skill should use the small-change fast path, inspect the localized diff, avoid full review and broad verification by default, and explicitly report limited diff-only verification."
+    },
+    {
+      "id": 6,
+      "prompt": "Review this Vue form validation change before handoff. It changes a required rule, a TypeScript form model, and one submit payload mapping. Pick the right verification commands without blindly running every script.",
+      "expected_output": "The skill should read verification-selection, choose typecheck plus relevant lint/tests when available, avoid unnecessary full build unless justified, and report exact commands, exit status, and any unrelated failures clearly."
+    },
+    {
+      "id": 7,
+      "prompt": "Review the staged frontend changes only. They include a Next.js TSX edit with a new use client directive, window access, an as any cast, and a label change. Use the diff scan helper if available and don't inspect unstaged work.",
+      "expected_output": "The skill should use diff_scans.sh --cached, treat scan hits as signals, inspect only staged current-work risks, route label changes to copy fidelity, and avoid touching unstaged or unrelated code."
+    },
+    {
+      "id": 8,
+      "prompt": "Review my current frontend diff. It adds one console.log, changes a placeholder unrelated to the request, and the project already has old vue-tsc errors in untouched legacy files. Classify what must be fixed versus what should only be noted.",
+      "expected_output": "The skill should read severity, classify added console.log and out-of-scope placeholder as Must Fix, classify unrelated historical vue-tsc errors as Note Only, avoid fixing legacy files, and report severity clearly."
+    },
+    {
+      "id": 9,
+      "prompt": "Review this Vue page diff. The current request added an edit modal with its own fields, validation, submit handler, loading state, and API mapping inside an already large page. Decide whether to extract it without touching the old table and search sections.",
+      "expected_output": "The skill should read safe-refactor-boundaries, identify the modal as a nameable current-diff responsibility, extract or recommend extracting only that boundary if safe, avoid refactoring untouched table/search code, and report why the boundary is safe."
+    }
+  ]
+}

package/dist/templates/common/bundled-skills/trellis-quality-review/references/copy-fidelity.md

@@ -0,0 +1,56 @@
+# Copy Fidelity
+
+User-visible copy is product behavior. Review it separately from code quality.
+
+## What Counts as Copy
+
+Check every added or modified:
+
+- label
+- title
+- placeholder
+- tooltip
+- helper text
+- description
+- radio/checkbox/select option
+- button text
+- validation message
+- empty state
+- modal title
+- table column title
+- confirmation text
+- option order
+
+## Classification
+
+For each changed copy or option-order line, classify it as:
+
+- **Exact requirement text:** the text/order appears in the user's requirement.
+- **Necessary adaptation:** minimal wording/order change required by the feature.
+- **Existing text preserved:** adjacent text appears in diff context but was not changed.
+- **Out-of-scope copy change:** copy/order was polished, rewritten, moved, or added without requirement support.
+
+## Rules
+
+1. Revert out-of-scope copy changes to the previous text/order when safe.
+2. When reordering options for a required default or required order, do not change child descriptions/helper text unless explicitly requested.
+3. Do not improve tone, punctuation, wording, examples, or explanatory text during review unless the requirement asks for it.
+4. Preserve helper descriptions, placeholders, and validation messages unless the requested feature cannot work without changing them.
+5. If copy ownership is unclear, ask before changing more text.
+
+## Diff Scan
+
+Use this scan as a starting point, then manually check each hit against the requirement:
+
+```bash
+git diff -U0 HEAD -- '*.vue' '*.ts' '*.tsx' | rg '^[+-][^+-].*(label|title|placeholder|help|message|Radio|Checkbox|Button|Tooltip|content|confirmText|cancelText|text-|请选择|请输入|验证|账户|服务商|域名|说明|提示)'
+```
+
+## Common Copy Mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Treating wording polish as harmless | Treat copy as behavior and verify it against the requirement |
+| Changing radio descriptions when only label/default changed | Preserve existing helper text |
+| Reordering options without requirement support | Restore order unless required |
+| Editing placeholder/help text for consistency | Leave it unchanged unless requested |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/decision-tree.md

@@ -0,0 +1,102 @@
+# Decision Tree
+
+Use this routing tree after reading `SKILL.md` and before deeper review. Its purpose is to make reference loading deterministic so copy, formatting, framework, and reporting checks are not skipped.
+
+## Start Gate
+
+1. **Is there a frontend diff?**
+   - Check with `scripts/diff_scans.sh --files` when available, or manually run `git diff --name-only HEAD -- '*.vue' '*.ts' '*.tsx' '*.jsx' '*.js' '*.css' '*.scss'`.
+   - Use `scripts/diff_scans.sh --cached` for staged-only review or `scripts/diff_scans.sh --base main` for branch/PR-style review when appropriate.
+   - If no frontend files changed, do not continue with this skill unless the user explicitly requested frontend review planning.
+   - If frontend files changed, continue.
+
+2. **Can you restate the current requirement?**
+   - If yes, write the one-sentence requirement and continue.
+   - If no, inspect the conversation and diff.
+   - If still unclear and further edits depend on interpretation, ask the user before changing code.
+
+3. **Does the change qualify for the small-change fast path?**
+   Signals include a one-file or very localized UI/copy/style/config change with no API, state-flow, validation, routing, permissions, shared type, or data transformation impact.
+   - If yes, read `references/small-change-fast-path.md`, confirm the diff contains only the requested change, and skip full review unless inspection finds scope expansion.
+   - If no, continue with the normal review tree.
+
+4. **Load scope control for normal review.**
+   - Read `references/scope-control.md`.
+   - Classify changed blocks as in-requirement, necessary-adjacent, or out-of-scope before cleanup.
+
+## Framework Branch
+
+5. **Does the diff include Vue, Vite Vue, Pinia, Vue Router, or `.vue` files?**
+   - If yes, use `vue-best-practices` and read `references/framework-rules.md`.
+   - Run or reproduce the Vue added-line scan for `v-model:` when relevant.
+
+6. **Does the diff include React, Next.js, JSX/TSX, React hooks, or Next route/page files?**
+   - If yes, use `vercel-react-best-practices` and read `references/framework-rules.md`.
+   - Check server/client boundaries, hook placement, page/container responsibilities, and unnecessary memoization.
+
+7. **Does any changed file own multiple responsibilities touched by this requirement?**
+   - If yes, build the responsibility map from `scope-control.md` and `framework-rules.md`.
+   - Before splitting components, extracting composables/hooks, moving helpers, or changing ownership, read `references/safe-refactor-boundaries.md`.
+   - Split or extract only when the current requirement created unclear ownership or repeated logic and the safe-refactor checks pass.
+   - If no, avoid structural refactor.
+
+## Diff Fidelity Branch
+
+8. **Could modified existing files contain formatting-only churn?**
+   Signals include changed indentation, wrapping, import/object layout, blank lines, class ordering, or formatter output.
+   - If yes, read `references/formatting-fidelity.md`.
+   - Compare normal diff and whitespace-insensitive diff for affected files.
+   - Restore out-of-scope formatting when safe.
+
+9. **Could user-visible copy or option order have changed?**
+   Signals include changed `label`, `title`, `placeholder`, `help`, `message`, button text, validation text, modal/table text, radio/select options, or localized strings.
+   - If yes, read `references/copy-fidelity.md`.
+   - Classify each changed copy/order line against the requirement.
+   - Restore out-of-scope copy/order changes when safe.
+
+10. **Did the current diff add suspicious frontend patterns?**
+   Use `scripts/diff_scans.sh` when available. Signals include:
+   - debug or suppression lines: `console.log`, `debugger`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, `TODO`, `FIXME`
+   - TypeScript risk lines: `any`, `as any`, `as unknown as`, non-null assertions
+   - Vue risk lines: `v-model:`, deep watchers, direct prop mutation patterns
+   - React/Next/browser-boundary risk lines: `use client`, `dangerouslySetInnerHTML`, `window`, `document`, web storage access
+   - copy/accessibility text lines: labels, placeholders, messages, `aria-label`, `alt`
+   - If yes, inspect and fix only current-work instances unless adjacent legacy code blocks correctness.
+   - Treat scan hits as signals, not automatic defects.
+   - If ownership is unclear, mention it in Notes instead of expanding scope.
+
+## Severity, Verification, and Report Branch
+
+11. **Before fixing or deferring findings, has severity been classified?**
+    - Read `references/severity.md`.
+    - Classify findings as Blocker, Must Fix Before Handoff, Should Fix If In Scope, or Note Only.
+    - Fix Blocker findings when possible.
+    - Fix Must Fix findings when introduced by the current diff and ownership is clear.
+    - Fix Should Fix findings only when the edit is small and inside scope.
+    - Record Note Only findings without expanding the diff.
+
+12. **Before final response, has verification been selected and run or intentionally skipped?**
+    - If claiming completion or correctness, use `verification-before-completion`.
+    - Read `references/verification-selection.md` before choosing lint, typecheck, test, build, or diff-only verification.
+    - Choose the smallest relevant verification set from project scripts and docs.
+    - If verification is skipped, state why.
+
+13. **Before final response, load report format.**
+    - Read `references/report-format.md`.
+    - Include Scope Check, Formatting Fidelity, Copy Fidelity, Changed, Removed, Verified, and Notes.
+
+## Quick Routing Table
+
+| Signal | Required action |
+| --- | --- |
+| Tiny localized UI/copy/style/config change | Read `small-change-fast-path.md`; use diff inspection unless disqualified |
+| Any normal frontend diff | Read `scope-control.md` |
+| `.vue`, Pinia, Vue Router, Vite Vue | Use `vue-best-practices`; read `framework-rules.md` |
+| React, Next.js, `.tsx`, hooks | Use `vercel-react-best-practices`; read `framework-rules.md` |
+| Component split, hook/composable extraction, helper move, ownership change | Read `safe-refactor-boundaries.md` |
+| Formatting-only looking diff | Read `formatting-fidelity.md` |
+| Label/title/placeholder/message/options changed | Read `copy-fidelity.md` |
+| Added debug/type suppression lines | Classify severity, then fix current-work instances or explain why not |
+| Deciding fix vs defer | Read `severity.md` |
+| Choosing verification | Read `verification-selection.md` |
+| Final handoff | Use `verification-before-completion`; read `report-format.md` |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/formatting-fidelity.md

@@ -0,0 +1,37 @@
+# Formatting Fidelity
+
+Formatting-only diffs are code changes. Review them separately from logic and copy.
+
+## Default Rule
+
+Preserve existing formatting for existing code unless the user explicitly asked to format, or the touched new/changed code cannot pass required verification without a minimal formatting change.
+
+For every modified existing file, compare normal and whitespace-insensitive diffs:
+
+```bash
+git diff HEAD -- path/to/file
+git diff -w HEAD -- path/to/file
+```
+
+## Classification
+
+- **Necessary formatting:** layout required for newly added code or to satisfy a non-formatting correctness/lint issue in the touched block.
+- **Out-of-scope formatting:** single-line/multiline wrapping, indentation, blank-line, object/call layout, chain layout, or trailing whitespace changes that do not change behavior and were not required.
+- **Formatter conflict:** preserving original code style makes `prettier/prettier` complain, but changing it would reformat existing out-of-scope code.
+
+## Rules
+
+1. If normal diff shows a block but `git diff -w` makes it disappear, treat it as likely out-of-scope formatting until proven necessary.
+2. Do not run broad `eslint --fix` or prettier on existing files during scope review unless the user asked for formatting.
+3. Revert out-of-scope formatting to the previous layout when safe.
+4. If formatter rules conflict with scope preservation, prefer scope preservation for existing code.
+5. When needed, run scoped lint with formatting rules disabled and report the conflict instead of expanding the diff.
+6. New code should still be readable and locally consistent, but do not reflow surrounding old code just to match formatter output.
+
+## High-Signal Questions
+
+- Did this file change only because a formatter touched it?
+- Does `git diff -w` remove the entire block?
+- Did line wrapping change without behavior or type impact?
+- Did import/order/object layout change without necessity?
+- Would reverting formatting leave the requested behavior intact?

package/dist/templates/common/bundled-skills/trellis-quality-review/references/framework-rules.md

@@ -0,0 +1,59 @@
+# Framework Rules
+
+Use this reference when the review touches Vue, React, Next.js, routes, stores, components, composables, hooks, or styling conventions.
+
+## Shared Frontend Rules
+
+- Keep page/container files focused on orchestration.
+- Keep presentational components focused on one UI section.
+- Keep stateful side effects in composables/hooks.
+- Keep pure feature-local logic in local helpers.
+- Avoid magic strings when a small typed union or constant improves clarity.
+- Avoid adding comments unless they explain business rules, side effects, temporary mock behavior, or non-obvious constraints.
+- Do not create broad shared abstractions for logic used only once.
+- Before structural refactors, use `safe-refactor-boundaries.md` to decide whether the split is safer than keeping code local.
+
+## Vue / Vite / Pinia
+
+Load `vue-best-practices` before editing Vue code.
+
+Check current-work code for:
+
+- Composition API and `<script setup>` usage where the project uses it.
+- typed `defineProps`, `defineEmits`, and `defineModel` usage.
+- section-local state staying near the owning component.
+- composables owning stateful logic and side effects, not presentational markup.
+- Pinia stores used for shared application state, not one-off local UI state.
+- route/page components doing orchestration rather than owning multiple unrelated UI sections.
+- newly introduced `v-model:` usage if the project lint rule disallows arguments.
+
+Diff-only scan for Vue projects with `vue/no-v-model-argument`:
+
+```bash
+git diff -U0 HEAD -- '*.vue' | rg '^\+[^+].*v-model:'
+```
+
+If an added line contains `v-model:value="..."` and the project uses `vue/no-v-model-argument`, rewrite the touched code to the project-approved binding/event style instead of editing unrelated old occurrences.
+
+## React / Next.js
+
+Load `vercel-react-best-practices` before editing React or Next.js code.
+
+Check current-work code for:
+
+- server/client component boundary correctness in Next.js.
+- unnecessary client components or broad `use client` placement.
+- hooks used only in valid component/hook contexts.
+- derived state that can be computed instead of stored.
+- callback/prop contracts that are typed and stable enough for the feature.
+- expensive render work introduced by the current change.
+- route/page files doing orchestration rather than owning large reusable UI sections.
+
+Do not add memoization by default. Add it only when there is a clear render-cost or identity-stability reason related to the current change.
+
+## Styling
+
+- Preserve layout unless the requirement asks for visual changes.
+- Do not normalize class ordering, spacing, or style object layout unless required by touched code or lint.
+- Avoid moving styles across files just for preference.
+- If design tokens exist, use project conventions already present in nearby code.

package/dist/templates/common/bundled-skills/trellis-quality-review/references/report-format.md

@@ -0,0 +1,23 @@
+# Report Format
+
+Keep the final report concise and evidence-based.
+
+Use this structure:
+
+- **Scope Check:** whether the diff stayed within the requested requirement, plus any out-of-scope code intentionally left unchanged.
+- **Severity:** Blocker, Must Fix, Should Fix, and Note Only summary for current-diff findings.
+- **Formatting Fidelity:** whether normal diff vs `git diff -w` was checked, what formatting-only changes were restored, and any remaining formatter conflicts.
+- **Copy Fidelity:** whether changed user-visible text/order was checked against the requirement, what was restored, and any remaining necessary copy changes.
+- **Changed:** cleanup, refactor, comment, or boundary changes made during review.
+- **Removed:** dead code blocks, unused imports, unused state, or files removed.
+- **Verified:** exact commands and exit status.
+- **Notes:** skipped findings, historical issues, or remaining risks with reasons.
+
+## Reporting Rules
+
+- Do not claim checks passed unless command output was read and exit status was successful.
+- If verification fails due to historical or unrelated issues, say so explicitly and explain whether the current change appears related.
+- If you skipped lint/typecheck/test/build, explain why.
+- Avoid long narrative. Prefer short bullets with concrete evidence.
+- Mention out-of-scope issues without fixing them unless they block the current requirement.
+- Keep Severity concise; do not list every Note Only issue when one representative summary is enough.