@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/presets/code-vibe/skills/frontend-design/references/design-standards/ux.md

@@ -0,0 +1,76 @@
+# UX（用户体验默认）
+
+> 社区锚点：ISO 9241-11、[Nielsen 10 Usability Heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/)。
+> **原则/启发式真源**（非 UI 施工入口）。有界面施工 → [LOAD-MAP.md](./LOAD-MAP.md)。
+> Verify 接线 → [`skills/testing/references/ux-standards.md`](../../../quality-review/references/ux-standards.md)。
+
+## 核心原则
+
+**合格体验 = 指定用户在真实情境下能有效、高效、满意地完成目标。**
+有控件 / Toast / API 200 / 空态文案 **单独均不算**达成。
+
+- 验证 / 设计都围绕用户 Job，不只围绕控件或接口；
+- 使用目标角色、真实入口和代表性数据心智；
+- 必须考虑系统反馈、错误恢复和完成感；
+- Shape 阶段就把失败与权限路径写进产品切片，再交给 Plan/Verify。
+
+## 可用性度量（ISO 9241）
+
+| 维度 | 含义 |
+|------|------|
+| Effectiveness | 能否真完成目标 |
+| Efficiency | 时间、步骤、认知成本 |
+| Satisfaction | 是否顺、是否愿意再来 |
+
+## 检查维度
+
+| 维度 | 最低问题 |
+|---|---|
+| 可发现 | 用户能找到正确入口吗？ |
+| 可理解 | 文案、状态和下一步是否明确？ |
+| 可控 | 用户能取消、返回或修正吗？ |
+| 反馈 | 操作后是否及时显示真实状态？ |
+| 错误恢复 | 失败是否说明原因和可行下一步？ |
+| 一致性 | 相同概念、动作和权限是否一致？ |
+| 可访问 | 键盘、焦点、对比度、语义（宿主 a11y + ai-tells） |
+| 完成感 | 用户能确认 Job 已完成且知道影响范围吗？ |
+
+## Nielsen 十条启发式（严重度 0–4）
+
+0 不是问题 · 1 妆容 · 2 小 · 3 重要 · **4 灾难（阻断核心 Job → Job Fail）**。
+
+| # | 启发式 | 评分时问什么 |
+|---|--------|--------------|
+| H1 | Visibility of system status | 是否知道自己在哪、系统在干什么？ |
+| H2 | Match system ↔ real world | 是否人话？顺序是否符合任务心智？ |
+| H3 | User control and freedom | 误操作能否撤销/退出？ |
+| H4 | Consistency and standards | 一词一义？符合平台/行业习惯？ |
+| H5 | Error prevention | 高代价错误是否被挡住？ |
+| H6 | Recognition rather than recall | 关键信息是否可见？是否逼人记 UUID？ |
+| H7 | Flexibility and efficiency | 新手可起步、熟手有捷径？ |
+| H8 | Aesthetic and minimalist | 无关信息是否淹没关键信息？ |
+| H9 | Help recover from errors | 错误是否人话并给下一步？ |
+| H10 | Help and documentation | 最好自解释；帮助是否任务向？ |
+
+## Shape / 产品包自检（有 UI 时）
+
+写或改 `01-experience` / `03-presentation` 时对照：
+
+- [ ] 主 Job 的成功、失败、权限拒绝路径都有可感结果
+- [ ] 反馈与完成感可观察（不只「点了按钮」）
+- [ ] 无逼用户记忆内部 ID / 技术术语（除非角色就是运维）
+- [ ] 与宿主已有导航、用词一致，或显式记录Breaking 变更
+
+## 反模式
+
+| 反模式 | 正确做法 |
+|--------|----------|
+| Toast / 「已安装」文案 → 成功 | 用户是否达成 Job？ |
+| API 200 → 成功 | 发现面用户是否认得出变化？ |
+| 旁路脚本顶替主通道 | 目标产品路径是否真走通？ |
+| 仅用启发式 Pass 数关版 | Jobs 有效性 + 无开放严重度 4 |
+| Shape 只画快乐路径 | 失败与权限必须进切片 |
+
+## 不适用
+
+纯后端无 UI、纯文档、纯 CI：`run.md` 写 `UX: N/A` + 理由；Shape 可跳过本册详细自检。

package/presets/code-vibe/skills/frontend-design/references/design-standards/visual.md

@@ -0,0 +1,52 @@
+# Visual（原则索引）
+
+> **非施工入口。** 有 UI → 先 [LOAD-MAP.md](./LOAD-MAP.md)。
+> 具体册：tokens · pages · components · copy · anchor · audit · exemplars
+
+## 0. 先定表面与锚点
+
+`surface` + `page_kind`/`motif` +（Build 前）`anchor`/`diverge` → 再按 LOAD-MAP 读册。强度见 LOAD-MAP 字段表。
+
+## 1. 一屏一主任务
+
+唯一主行动/主信息；次要降级；growth 首屏预算写进合同 motif。
+
+## 2. 先灰度，后上色
+
+色角色与禁令 → [tokens/color-roles.md](./tokens/color-roles.md)。模板脸禁令真源 → [audit/ai-tells.md](./audit/ai-tells.md)。
+
+## 3. 封闭尺度
+
+→ [tokens/scale.md](./tokens/scale.md)。有宿主 DS → 用宿主。
+
+## 4. 组件与页面
+
+按 LOAD-MAP 读 pages + components。
+
+## 5. 状态
+
+空（first-run）/ 筛选零 / 载 / 错 / 成功 / 无权限 — 见 forms-states + copy。
+
+## 6. 动效
+
+→ [tokens/motion.md](./tokens/motion.md)。
+
+## 7. AI 默认味
+
+输出前扫 [audit/ai-tells.md](./audit/ai-tells.md)。
+
+## 8. a11y
+
+WCAG 子集 + 宿主 a11y 约定；输出前扫 ai-tells。
+
+## 9. 自检
+
+- [ ] LOAD-MAP 已执行（或豁免适用）
+- [ ] surface / page_kind|motif /（Build）anchor
+- [ ] 尺度与色合规；overlays/copy 正确
+- [ ] 未平行第二套 DS
+
+## 10. Verify
+
+视觉 alone 不关版失败，除非 Job 失败 / 严重度 4 / 违反已写入合同。
+发现分级映射：Nielsen **4 ↔ P0**，**3 ↔ P1**，**1–2 ↔ P2**（走查用语见 testing）。

package/presets/code-vibe/skills/frontend-design/references/perceptible-path.md

@@ -0,0 +1,27 @@
+# 可感主路径卡（全流程唯一必需对象）
+
+> 同一对象被引用三次，不是三个产物。
+> 反模式：[`scheme-antipatterns.md`](./scheme-antipatterns.md)。
+
+## 五字段
+
+| 字段 | 写什么 |
+|------|--------|
+| **谁** | 目标用户 / 角色 |
+| **什么触发** | 进入场景的入口与动机 |
+| **第一次成功看到/得到什么** | 可观察的用户结果（非内部状态） |
+| **怎么观察到** | 人点验步骤或可机跑断言 |
+| **非目标** | 本切片明确不做 |
+
+## 落盘位置
+
+| 阶段 | 落点 |
+|------|------|
+| Shape | 产品方案脊骨（可写在 demand / module README / 方案卡） |
+| Spec | `tests.md` 的 **T-001**（或索引中第一个 success 主路径）Then = 「怎么观察到」 |
+| Verify | 人类验收包第 1 步 = 同一主路径 |
+
+## 闸
+
+- 「怎么观察到」若命中 [`scheme-antipatterns`](./scheme-antipatterns.md) → **不得**请确认方案；`check_spec` 对 T-001 Fail。
+- 增长 / 激活 / 教育类：可感主路径优先于检查点账本；Checklist 最多附录。

package/presets/code-vibe/skills/frontend-design/references/product-package.md

@@ -0,0 +1,80 @@
+# 产品包章节合同与剪枝
+
+> 统一 `docs/product/modules/<slug>/` 层内写法。建包 → skill `design`。
+> 旧包不强制回填；新写/大改某层时对齐本合同。
+> 宿主模板不复制本文；仅 skills 为真源。
+
+## 1. 骨架
+
+```text
+docs/product/modules/<slug>/
+├── README.md
+├── 01-experience.md
+├── 02-product-model.md
+├── 03-presentation.md   # 可同号改名
+├── 04-runtime.md        # 薄：产品级约束
+├── 05-delivery.md
+└── 06-acceptance-matrix.md  # 可选：系列 Version Acceptance
+```
+
+读序钉死：体验 → 模型 → 呈现 → 运行时意图 → 交付。
+语言后缀随宿主约定（默认无后缀）。域特化只许同号改名。
+
+## 2. modules ↔ specs（真源）
+
+| 真源 | 写什么 | 本层边界外 |
+|------|--------|----------|
+| `modules/<slug>/` | 产品决策（可超前） | 本版实现细节、关版 Test 全文 |
+| `specs/<id>/` | 本版实施 + `tests.md` 阅卷 | 只改 Spec 不改产品语义 |
+| system-map + 代码 | as-built | 愿景蓝图 |
+
+**05** 索引 Spec `T-xxx`；Test / Oracle 正文只在 Spec `tests.md`。
+
+## 3. 全集章节（适用则写；否则 N/A+理由或省略整层）
+
+### README
+一句话 + 状态/Gap/Spec · 读序地图 · 已拍板决策**索引** · 真源边界
+
+### 01 体验
+设计立场 · 角色/画像 · 操控面 · 用户旅程 · 可感配置/屏幕 · 体验非目标
+（有 UI 时按 [`LOAD-MAP`](./design-standards/LOAD-MAP.md) 场景自检；启发式见 [`ux.md`](./design-standards/ux.md)）
+
+### 02 产品模型
+能力表 · 概念术语 · 核心对象与状态 · 权限/触发 · 冻结项 · 非目标
+
+### 03 呈现
+IA · 文案/视觉语义 · 组件/表面规格（无 UI → 整篇省略）
+（有 UI → [`LOAD-MAP`](./design-standards/LOAD-MAP.md)；原则索引 [`visual.md`](./design-standards/visual.md)；品牌/DS 例外在 AGENTS）
+
+### 04 运行时意图（薄）
+进程/边界意图 · 关键路径语义 · 安全/观测约束
+表结构、长锚点、API 字段全集 → Spec `plan.md`
+
+### 05 交付
+分期 · 配置/环境 · 联调检查 · 风险 · 关版 Test **索引**（正文在 Spec `tests.md`）
+
+### 06 验收矩阵（可选 · 大模块）
+
+多角色 × 多表面 / 多 Spec 系列的 **Version Acceptance 唯一 Oracle**（全角色全场景或等价浏览器剧本）。
+写法通则：testing [`version-acceptance-matrix.md`](../../quality-review/references/version-acceptance-matrix.md)。
+未触发系列验收时可省略；触发后 **不得**用单 Spec Build Pass 冒充本矩阵 Pass。
+
+## 4. 剪枝表
+
+| 类型 | 剪枝 |
+|------|------|
+| 纯后端 / 无 UI | 省略 03 |
+| 纯体验愿景 | 可省略 04（README 声明） |
+| 单层 ≤~80 行 | 单文件豁免 |
+| 域特化呈现 | `03-cards` / `03-authoring` 等同号 |
+| 调研附录 | `05-research` / `07-*` 等不占 01–05 合同位；**06 验收矩阵**占用可选合同位（见上） |
+
+**硬门：** 04 概念保留在 04；交付不改号接到 03；关版以 Spec 验收为准（设计稿单独不构成关版）。
+
+## 5. 新包自检（换靶：可感主路径，非齐套）
+
+- [ ] **可感主路径卡**在（谁 / 触发 / 第一次成功结果 / 怎么观察到）——见 [`perceptible-path.md`](./perceptible-path.md)
+- [ ] 「怎么观察到」**未**命中 [`scheme-antipatterns.md`](./scheme-antipatterns.md)
+- [ ] 空层已省略（不为齐套建空文件）；简单诉求可用单页 / demand，不强制五层
+
+~~章节齐全勾选表已删除（齐套 ≠ 质量）。~~

package/presets/code-vibe/skills/frontend-design/references/scheme-antipatterns.md

@@ -0,0 +1,21 @@
+# Scheme antipatterns（≤12 · 只增须替换）
+
+> Shape / Spec / Verify 共用。命中 → 不得请人确认方案；不得把该 Oracle 当 T-001 成功。
+> 可感主路径卡：[`perceptible-path.md`](./perceptible-path.md)。
+
+| # | 反模式 | 失败信号（观察方式若仅此则 Fail） |
+|---|--------|----------------------------------|
+| 1 | **Tour / 引导遮罩当教育** | 播完 Tour / 点完「下一步」即算学会 |
+| 2 | **纯 Checklist 教育** | 勾完 lesson / checklist / 完成率 = 成功 |
+| 3 | **假沙箱** | 沙箱无真实后果，出沙箱即「已掌握」 |
+| 4 | **状态机冒充教学** | 状态位翻转 / flag 置位 = 学会 |
+| 5 | **深链 = focus textarea** | 打开抽屉 / focus 输入框 / 点击 CTA 单独当教育成功 |
+| 6 | **使命膨胀** | 常青账本 / 增长使命写进方案却无首日可感表面 |
+| 7 | **齐套灌水 / 文档对齐冒充设计** | 五层产品包或 docs 章节齐套但无代码锚点、无可证伪断言、无机制/主路径提案 |
+| 8 | **软回退关「学会」** | 出错软退回仍标教育完成 |
+| 9 | **residual 装过** | live-deferred / residual 冒充主路径已证 |
+| 10 | **形式走查** | UX 走查只对 rule ID，无对可感主路径 |
+| 11 | **懒 Done when** | Done when 仅「打开 X / 点到 Y」无用户结果 |
+| 12 | **把人当 CI** | 把「Codex 行不行 / 再跑一遍脚本」甩回用户当主验收 |
+
+**硬上限 12 条。** 新增须替换一行并说明替换理由。

package/presets/code-vibe/skills/quality-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: quality-review
+description: 验收/UX 走查/体验审计专项：先证伪再 Pass、人类验收包、多视口截图证据、版本验收矩阵；Use when 验收、UX 走查、体验审计、walkthrough、wish-programming 阶段 4/5 或用户说「走查/验收/看看效果」时加载；只读不改实现。
+---
+
+# Quality Review（验收/UX 走查专项）
+
+> 从 SDD 体系（sdd-vibe-coding，MIT）移植的 Verify 专项：证伪优先、证据契约、人类验收包。
+> 与 wish-programming 阶段 4（机械验收）和阶段 5（用户 judge）联动；**maker ≠ grader**——验收用独立视角，不信任实现者自述。
+
+## 加载即执行的硬门
+
+1. **证伪先于结案**：适用项标 Pass 前，先执行「怎么证伪」步骤（`references/falsify-checklist.md` 默认证伪刀：翻页/无界滚动/表单校验等至少一刀，失败 = Fail，不许 smoke 覆盖）。
+2. **先读再走查**（UX 走查变体）：`references/ux-standards.md` → `references/ux-walkthrough.md`；未完成必读名单 → 禁止宣称已按 design-standards 走查。
+3. **floor ≠ 关版**：最低证据线不是验收通过线；`references/verification-loop.md` 的「结束信号」是关版前必须复核的清单。
+4. **同会话 Build→Verify 禁止誊抄**：Build 期间的 window-smoke/health 结果不得原样当 Verify Pass；须重跑证伪或等价命令并记新证据。
+5. **人类验收包**：有 UI 的愿望交付前产出 `references/human-acceptance-pack.md` 格式的验收包；多角色/多表面系列 → `references/version-acceptance-matrix.md`，禁止单 Spec Pass 冒充系列 Pass。
+6. **证据契约**：Evidence Kind 以 `references/evidence-contract.md` 为准；Browser 证据 → `references/browser-verify.md`（真实通道、多视口截图落 `.sdd/acceptance/<id>/shots/`）。
+
+## 册导航（references/ 内）
+
+| 场景 | 读什么 |
+|---|---|
+| 证伪优先清单（先读） | `falsify-checklist.md` |
+| 证据分层与表述 | `evidence-contract.md` |
+| 结束信号 / Floor≠关版 | `verification-loop.md` |
+| UX 走查（变体） | `ux-standards.md` → `ux-walkthrough.md` |
+| 人类验收包模板 | `human-acceptance-pack.md` |
+| 版本验收矩阵（系列） | `version-acceptance-matrix.md` |
+| 浏览器真实通道 | `browser-verify.md` |
+| 有界验收 / 回归 / 验证报告 | `bounded-verify.md` · `product-regression.md` · `validation-report.md` |
+| 设计标准对照（走查引用） | `../frontend-design/references/design-standards/`（LOAD-MAP / product-judgment / change-control / ai-tells） |
+
+## 证据落点对接（Evidence Kind ↔ coverage.tsv / shots/）
+
+> 本 skill 的 evidence-contract 定义证据**类型**；wish-programming 阶段 4 的 coverage.tsv 定义证据**落点**。两者是同一证据的两个维度，对照本表填写。
+
+| evidence-contract Evidence Kind | code-vibe 落点 |
+|---|---|
+| screenshot（多视口渲染） | `.sdd/acceptance/<id>/shots/`（1280/1440/窄分栏） |
+| api-diff / network-har（分页/请求对照） | 证据文件与该条 O/N 一起，路径填入 coverage.tsv 证据列 |
+| command-run（重跑输出） | coverage.tsv 证据列指向重跑输出文件，或 `.sdd/acceptance/<id>/runs/` |
+| human-acceptance（人类验收包） | `.sdd/acceptance/<id>/human-acceptance-pack.md`（阶段 5 交付前） |
+
+规则：coverage.tsv 的每个证据路径必须指向**真实存在的文件**（coverage_check.py 校验）；证据文件的内容满足本 skill 的 Evidence Kind 约束（如「分页」至少是 api-diff 或 network-har，不许首屏截图冒充）。
+
+## 与 wish-programming 的分工
+
+- 阶段 4 机械验收（独立 deny-write subagent 对照 requirements/存量清单）——本 skill 提供**证伪与证据标准**，不替代 journey/verify.sh/coverage_check。
+- 阶段 5 用户 judge（真实渲染迭代）——本 skill 提供**验收包与走查姿势**，帮助用户在截图前自查。
+- 只读评审：不修改实现；发现问题走 wish-programming 的切片修复。
+
+## 边界
+
+- 不替代 `dsh-ci-test-reliability`（测试级确定性/flake）；本 skill 管产品级验收（人可见的证据）。
+- 不替代 `frontend-design`（设计产出）；本 skill 管验收侧。
+- 设计类愿望的验收必须先过 `frontend-design` 的字段门（Job Brief/白名单），否则验收无对照。

package/presets/code-vibe/skills/quality-review/references/bounded-verify.md

@@ -0,0 +1,37 @@
+# Bounded Verify（有界验收轮次）
+
+> 蒸馏：Impeccable Core principles、visual-qa-testing。防止 open-ended 自扫烧钱。
+> 证伪步骤与禁烟规则见 [falsify-checklist.md](./falsify-checklist.md)。
+
+## 轮次硬停
+
+1. **一批** 证伪 + 证据：按 `tests.md` 适用用例跑完（含约定 desktop + 关键 mobile 截图）；数据面先两态对比。
+2. **一批** 修复：只修本批 Fail / P0–P1（Verify **不改码**；Repair 回 Build）。
+3. **最多再一轮** confirm 扫描。
+4. **停止** — 剩余 P2 记限制；禁止无期限「再扫一轮」。
+
+## Visual QA 三态报告（有 UI 的浏览器通道）
+
+在 [browser-verify.md](./browser-verify.md) V2 之上，UI 变更须记录：
+
+| 态 | 查什么 | 写入 |
+|----|--------|------|
+| **视觉** | 主 Job 屏截图；对照 page_kind 自检 + ai-tells 抽检 | `run.md` Evidence |
+| **控制台** | 无 fatal / 未处理 rejection（与 Job 相关） | 有则 Fail 或限制 |
+| **网络** | 主路径无意外 4xx/5xx；**数据面另查**请求参数与分页进度 | 有则归因 |
+
+不必每轮全站爬虫；覆盖**本切片声明的 page_kind 主 Job**即可。
+
+## 数据面（list / dashboard / 分页·排序·筛选）
+
+Visual QA **不替代**证伪。至少记录：
+
+- 两页或两 offset 响应可区分；或
+- 排序/筛选请求参数与结果序；
+
+Evidence Kind 须为 `api-diff` / `network-har`（旁挂 smoke 不算）。真源 [`evidence-contract.md`](./evidence-contract.md)。
+
+## 与走查
+
+UX 走查变体仍用 [ux-walkthrough.md](./ux-walkthrough.md)；发现分级用 [critique-format](../../frontend-design/references/critique-format.md) 或 O→I→S。
+严重度 4 → Job Fail（ux.md）。

package/presets/code-vibe/skills/quality-review/references/browser-verify.md

@@ -0,0 +1,81 @@
+# 浏览器真实通道验证（V2）
+
+> 跨仓通则。宿主 URL、前端根、reload / E2E 命令以 `AGENTS.md` 为准；本文件不写死单仓路径。
+
+改用户可见前端后，在声称完成前做一次**真实浏览器通道**验证。输入是当前切片的用户
+Job、Test（`tests.md`）、Effective Channel 和 Oracle。
+
+## 探测（先读宿主）
+
+| 项 | 如何确定 |
+|----|----------|
+| 前端根 | 读 `AGENTS.md` 代码入口；再按仓内约定探测 |
+| Dev / 目标 URL | **先读** `AGENTS.md` 环境表；再扫 handoff / 近期 `run.md` |
+| 静态刷新 | `AGENTS.md` 或宿主 Makefile / 脚本中的 reload 目标 |
+| E2E / 无头冒烟 | 宿主约定的 VERIFY / e2e 命令；或仓内测试目录 |
+
+## 场景分流
+
+| 你在哪跑 | 浏览器手段 |
+|----------|------------|
+| **有 Browser MCP 的 IDE** | Browser MCP → 宿主声明的 Dev / 目标 URL |
+| **无 Browser MCP**（远程 worker、无头 CI、网页 Agent） | Playwright / 宿主 `AGENTS.md` 约定的等价命令 |
+| CI | 仓内 E2E / smoke 目标 |
+
+### 验证层次（UI / 全栈交付）
+
+| 层 | 验什么 | 单独算交付？ |
+|----|--------|--------------|
+| L1 接口 | HTTP 状态、JSON 结构、错误边界 | 否 |
+| L2 UI 交互 | 页面渲染、控件实际触发、数据联动、无 Console 致命错 | 否（须配合 Job） |
+| L3 用户旅程 | 目标角色走完 Job，Oracle 可观察 | **是（V2）** |
+
+### V2 通过条件
+
+- 打开宿主声明的产品 Dev / 目标 URL（正确主机）；
+- 经浏览器通道走完 Job 步骤（L3；关键控件须真实点击，不能只截静态首屏）；
+- Oracle 可观察结果 + 截图/日志落盘路径写入 `run.md`；
+- UI 切片另记 **Visual QA 三态**（视觉 / 控制台 / 网络）→ [bounded-verify.md](./bounded-verify.md)。
+
+**硬门：** 仅 API 冒烟、`curl /health`、首页 200、nginx 200 + SPA Not Found、仅单测绿、window-smoke JSON、或错误主机 loopback，不构成 V2 通过。
+数据面另遵 [falsify-checklist.md](./falsify-checklist.md)。
+
+## 回写（Demo / V2 Gate）
+
+回写至少包括：
+
+- 可体验入口、账号/角色与必要数据
+- 用户实际操作步骤
+- 结果是否满足 Oracle
+- 截图/日志等证据路径
+- 失败下一动作：按 [`evidence-contract.md`](./evidence-contract.md)
+  Fail 分类路由（`shape` / `plan` / Repair / `blocked` / `diagnose` 等）——没有独立的
+  `deliver` Rail
+
+产品专家看真实系统与证据；测试命令放技术详情。
+
+## 身份切换
+
+验收需要 Admin / 另一成员身份时：
+
+1. 确认登录页是否有**账号密码**（或宿主约定的可复用测试登录）路径；
+2. 有 → **自行**退出当前会话 → 用仓库 / 前次会话 / E2E 可复用凭据登录 → 继续走查；
+3. 仅当路径是扫码 / SSO / 用户个人 OAuth / 必须真人本人时，才登记等人。
+
+细则亦见 [`evidence-contract.md`](./evidence-contract.md) §6。
+
+## 证据落盘
+
+关键屏截图复制进宿主约定目录，路径写入 `run.md` 追踪矩阵 / 批次结果的 Evidence 列。
+**硬门：** 对话贴图或工具临时目录不算验完；正册在仓库约定路径。
+
+## 完成定义
+
+```text
+改前端 → 直接相关静态/单元检查 → 一次浏览器真实通道验证 → 才可汇报完成
+```
+
+发布、CI、全局合同或仓内明确门禁之外，不默认叠加全量单测与全量 E2E。
+稳定的新用户旅程可补 E2E；局部视觉、文案、布局调整按需决定是否加 E2E。
+
+若仓内启用验证 marker：真实验证完成后再写入 marker。

package/presets/code-vibe/skills/quality-review/references/evidence-contract.md

@@ -0,0 +1,194 @@
+# Evidence Contract
+
+> 本文件是 Build Validation、Version Acceptance、Production Verification 和完成声明的唯一真源。
+
+## 1. 证据层
+
+| 层 | 证明 | 常见证据 |
+|---|---|---|
+| V0 | 静态合同成立 | diff、lint、类型、确定性检查 |
+| V1 | 实现逻辑正确 | 单元、集成、API、migration 测试 |
+| V2 | Test 在真实通道有效 | 浏览器、运行时 Job、目标环境、**跨用户越权拒绝** |
+| V3 | 全局消费者或发布稳定 | 全量回归、CI、生产检查 |
+
+按当前风险选择验证层组合。**Floor ≠ 关版**——最低条只是入场；关版条件见
+[`verification-loop.md`](./verification-loop.md)。系列 / 全角色验收见 testing
+[`version-acceptance-matrix.md`](./version-acceptance-matrix.md)。
+
+### 1.1 Evidence Kind（`run.md` Evidence 列）
+
+> 每种证据证明什么；**单独不足以支撑 Job Pass 的 Kind 不得标 Pass。**
+> 写法：`kind=<名> · <路径或命令摘要>`。机检见 `check_spec`；执行见 testing
+> [`falsify-checklist.md`](./falsify-checklist.md)。
+
+| Kind | 证明 | 可单独支撑 Job Pass？ |
+|---|---|---|
+| `api-diff` | 两次请求/参数下响应可区分（分页 offset、排序、筛选） | 是（数据面 Oracle） |
+| `network-har` | 真实通道抓到的请求参数与状态码 | 是（须对齐 Then） |
+| `browser-job` | 浏览器走完 Job，Oracle 可观察 + 截图/日志 | 是（UI / 人工 Test） |
+| `unit` / `integration` | 自动化断言绿 | 仅当该 Test 层声明为 V0/V1 且非 UI Job |
+| `window-smoke` | 窗口/脚本冒烟 JSON、首屏探活 | **否**（旁证） |
+| `health` | `/health`、进程 active、首页 200 | **否**（旁证；P5 过程信号） |
+
+**硬门：** Pass 行的 Evidence 不得只有 `window-smoke` / `health` / 裸 `*smoke*.json`。
+数据面（分页/排序/筛选/list|dashboard）的 success Pass 须含 `api-diff` 或 `network-har`（或 Then 已写明的等价证伪输出）。
+
+### 行为优先于文档自洽
+
+1. 权限正确、用户 Job 成功、`code-ready` 须有行为/通道证据；编号对齐、manifest 计数、checklist 只证明文档自洽。
+2. 权限 / 隔离类 Spec：每个 In-scope 入口具备可观察的成功路径 + 越权失败路径证据（测试、探针或真实通道），再宣称该入口完成。
+3. 代码或 Schema 与 Spec 冲突时：先修 Spec 或标缺陷，再继续。
+4. **证伪优先于冒烟**：适用 Test 标 Pass 前须满足 Then 的可打假断言；冒烟文件存在 ≠ Oracle 达成。
+
+## 2. 三个验证层次
+
+### Build Validation
+
+Build 先证明整个 Spec 的实现状态；完成实现后运行完整单元测试批次，测试期间冻结改码。
+**Build 轨不得宣称「可交付」/ `acceptance-passed`**（只可报实现完成 + 单测批次）；关版结论属 Version Acceptance。许愿路径见 [`human-acceptance-pack.md`](./human-acceptance-pack.md)（无 UI 机器关版 / 有 UI 人点验）。
+Repair 只在 Verify 汇总全部 Fail 并形成统一方案后开始：
+
+- 直接相关检查；
+- Spec `tests.md` 用例；
+- 用户可见变化的真实通道；
+- 单向门附加验证；
+- diff 与 Spec In / Out 自检。
+
+### Version Acceptance
+
+Verify 证明整份 Spec 集成后（**先证伪，再写 Pass**；见 falsify-checklist）：
+
+- 核心成功路径；
+- 关键失败和降级；
+- 角色与权限；
+- 跨入口 / 跨模块集成；
+- 用户真实通道；
+- 适用回归和 UX Job；
+- 数据面：分页/排序/筛选的两态可区分证据。
+
+### Production Verification
+
+证明目标版本在**目标环境**真实生效：版本、deploy、health（过程信号）、**产品冒烟**、数据一致性、监控和回滚点。
+
+发布全过程（证据 → 并列设计「怎么发 / 怎么证伪」→ 批准 → 执行 → 关版）见 Skill
+`deploy` 轨道（发布流程见 `journey --assert deploy`；生产须本回合真人授权，P0–P6）。本节只钉 **关版硬门**；执行步骤以 deploy Skill 为准。
+
+#### Delivery Target 闸门
+
+| Target | 含义 | 部署含义 |
+|---|---|---|
+| `code-ready` | 代码与合同就绪 | 不自动部署 |
+| `dev-effective` | 在开发/预览环境生效 | 默认只交付该环境；上生产须写清风险接受 + 加长版目标环境冒烟 |
+| `production-delivered` | 生产真实生效 | 正常生产发布入口；须 P6 目标环境冒烟通过 |
+
+完成标签对齐已声明 Target。`matrix-accounted` / `acceptance-passed` / `design-ready` / `production-restored`
+不是 Delivery Target；Delivery Target 的分层与条件以本节为准。
+
+#### 交付条件
+
+1. **产品冒烟（P6）**：有产品影响的发布在**目标环境**按事先写好的验证方案跑用户路径冒烟；完成声明带冒烟态（通过 / 未过 / Blocked+原因）。
+   **硬门：** `/health`、进程 active、首页 HTTP 200 单独不构成「部署成功」或生产交付（仅 P5 过程检查）。
+   **硬门：** P6 须 `探活执行者: agent`（或 `blocked-needs-auth`）；禁止在宣称通过后再派用户「打开/硬刷」当第一发现手段（见 [`verification-loop.md`](./verification-loop.md)）。
+2. **环境对齐**：生产 Target 的证据取自目标生产环境（数据、env、权限、预置）。
+   **硬门：** 开发/预览 E2E 或开发 URL 回归单独不构成生产验收（最多作 P1 旁证）。
+3. **定级有理由**：发布风险定级（L0/L1/L2）与冒烟范围由 Agent/人写明理由；脚本（路径变更、reload、环境清单）只作信号，不定级。
+4. **P2 + P3 先于执行**：生产发布须先贴 **发布方案（怎么发）** 与 **验证方案（怎么证伪）**，再经批准（P4）后才执行（P5）。
+   **硬门：** L1/L2 缺任一则禁止 deploy；L0 可极简但仍须触及面最小冒烟（Agent 跑关键路径，非仅 health）。
+   **硬门：** P6 未过禁止宣称 `production-delivered`；标签只能是 `prod-smoke 未过/Blocked`。
+5. **非代码面**：触及 migrate / 主机依赖 / 反向代理·进程模板 / 新 env 合同等时，方案须含采纳或明确延期（理由+跟踪）；配置类 MUST 含「模板↔live 同步」再 reload，禁止只写 reload。
+
+#### Deliver Gate 回写（`run.md`）
+
+生产或目标环境交付后，至少回写：
+
+```markdown
+声明目标：
+实际达到：
+环境 / 版本：
+定级 + 理由（若适用）：
+P2 发布方案（执行序 / sidecar 采纳或延期）：
+P3 验证方案（冒烟层勾选）：
+reload / deploy（P5）：
+migration / health（过程）：
+环境门禁 / 侧车检查：
+产品冒烟（目标环境 · P6）：通过 | 未过 | Blocked+原因
+探活执行者：agent | blocked-needs-auth
+产品冒烟证据：kind=… · <路径或命令>
+需要用户做什么：无需动作 | 批准… | 真人SSO/密钥…
+完成标签：[部署·L#·prod-smoke …]
+Open MUST（延期 sidecar，挂下次 P1）：
+回滚点：
+Observe 结果：
+```
+
+目标环境产品冒烟通过后，再推进生产 Observe。
+
+宿主具体命令、URL、检查清单以 `AGENTS.md`（及产品仓 deploy 适配器，若有）为准。
+
+## 3. 追踪链
+
+```text
+Requirement
+→ Test（tests.md）
+→ Implementation
+→ Build Evidence
+→ Version Evidence
+→ Production Evidence
+```
+
+适用节点齐备后再提高对应 Delivery Target。
+
+## 4. Test 终态
+
+- `Pass`：实际执行并达到 Oracle；
+- `Fail`：实际执行但未达到；
+- `Blocked`：无法执行，必须写原因。
+
+所有适用 Test 有终态 → 可声明 `matrix-accounted`。关版条件满足 → 可声明 `acceptance-passed`。
+
+## 5. Fail 分类
+
+| 类型 | 下一 Rail |
+|---|---|
+| implementation | 汇总全部实现 Fail，形成统一 Repair 方案后集中修复并回验 |
+| product / ux | Shape（回写 `docs/product/`，不另建 Spec 体验文件） |
+| plan | Plan |
+| test-oracle | 修订 `tests.md` 测试合同 |
+| environment / account / data | Blocked |
+| new-request | demand pool / Shape |
+| unknown-root-cause | Diagnose |
+
+全部适用测试结果齐备后，再创建统一 Repair 方案。
+
+## 6. UI 与用户体验
+
+用户 Job 通过须有真实通道证据（至少一次 V2）。截图应能让读者判断场景和结果。
+**硬门：** API 成功、控件存在、Toast、`/health`、window-smoke JSON 或脚本旁路单独不构成 Job 通过。
+**硬门：** 「页面能打开 / 列表有数据 / 可以滚动」无两态对比时，不构成数据面 Pass。
+
+浏览器通道选型、证据落盘与身份切换细则见 testing Skill 的
+[`browser-verify.md`](./browser-verify.md)。
+UX 判定标准见 [`ux-standards.md`](./ux-standards.md)。
+
+生产/测试环境需要登录时：宿主 `AGENTS.md` 或项目约定中**已有可复用测试凭据**的，Agent
+自行切换账号继续验收。仅当需要**用户个人账号**、OAuth 本人授权、或生产密钥时，记为
+`Blocked` / `needs-authorization`。
+
+**硬门：** 结论为通过 / `prod-smoke 通过` 时，`需要用户做什么` 默认 `无需动作`；禁止把
+「请打开页面 / 硬刷新确认是否正常」当作验收步骤（那是 Agent 探活义务）。
+**硬门（钉 1）：** 宣称 `可交付` / `acceptance-passed` / `prod-smoke 通过` 前须
+`make verify-deliver HOST=<repo> SPEC=<id>` exit 0（`check_spec --closing`；见 [`verification-loop.md`](./verification-loop.md)）。
+
+## 7. 完成声明
+
+完成报告须写：
+
+- Rail；
+- Spec / Test / 声明范围；
+- 实际 Delivery Target；
+- 真实运行的命令和步骤；
+- 证据路径；
+- 未覆盖项、Blocked 和限制；
+- Workspace / Branch / PR / 环境状态。
+
+测试绿证明对应 Correctness；用户价值、目标环境或生产交付另按本文件 Delivery Target 条件声明。