@captain_z/zsk-skills 1.0.2 → 1.1.0

package/README.md

@@ -1,31 +1,21 @@
 # @captain_z/zsk-skills
 
-ZNorth Standard Kit 的内容包：**46 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
+ZNorth Standard Kit 的内容包：**47 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 46/46 | 结构化 lint 通过                                      |
-| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 46/46 | 命名空间统一                                          |
-| `description` 以 `Use when…` 开头（trigger-optimized）                                   | ✓ 46/46 | 触发匹配句式                                          |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 46/46 | stage/workflow/standard/resource/meta · core/optional |
-| `triggers` 数组非空                                                                      | ✓ 46/46 | 每颗至少 4 个关键词                                   |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 47/47 | 结构化 lint 通过                                      |
+| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 47/47 | 命名空间统一                                          |
+| `description` 使用直接陈述风格，触发词放入 `triggers`                                   | ✓ 47/47 | 触发语义由 description + triggers 共同承担            |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 47/47 | stage/workflow/standard/resource/meta · core/optional |
+| `triggers` 数组非空                                                                      | ✓ 47/47 | 每颗至少 4 个关键词                                   |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法（build 已重写）                                                  | ✓       | 无孤儿引用                                            |
-| 单文件 ≤ 300 行                                                                          | ⚠ 41/46 | 5 个 frontend skill 超标（见技术债）                  |
+| 单文件 ≤ 300 行                                                                          | ✓ 47/47 | `lint-frontmatter` 作为 error 强制                    |
 
-**技术债**（不阻塞 CI，`tools/lint-frontmatter.ts` 当前降级 warn）：
-
-| 文件                                | 行数 |
-| ----------------------------------- | ---- |
-| `frontend/a11y-web/SKILL.md`        | 370  |
-| `frontend/testing-web/SKILL.md`     | 351  |
-| `frontend/nfr-web/SKILL.md`         | 352  |
-| `frontend/security-web/SKILL.md`    | 311  |
-| `frontend/performance-web/SKILL.md` | 305  |
-
-清理手法见 `memory/project_tech_debts_lint_frontmatter.md`；完成后把 `max-lines` 从 `warn` 升回 `error`。
+当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
 ## 使用方法通则
 
@@ -46,13 +36,13 @@ zsk skill 是 LLM **按需自动触发**的资产：
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `sdlc/`           | 17       | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
+| `sdlc/`           | 18       | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
 | `frontend/`       | 16       | React + Web 层实现规范                     |
 | `quality/`        | 5        | 跨栈质量原则                               |
 | `design-handoff/` | 2        | 设计交付方法论                             |
 | `system/`         | 5        | 工程宪法级资源                             |
 | `meta/`           | 1        | 元信息                                     |
-| **总计**          | **46**   |                                            |
+| **总计**          | **47**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
@@ -63,26 +53,6 @@ zsk skill 是 LLM **按需自动触发**的资产：
 | `frontend-with-design-handoff` | 31     | frontend-project + Figma 交付 2               |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
-
 <!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
 
 ## Skill 清单（按领域）
@@ -108,7 +78,7 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`implementing design` · `task by task delivery` · `local quality gates` · `smallest viable change`
 
 - **`zsk:reviewing`** *[stage 5 · stage · core]*
-  PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、置信度评估、多阶段审查（Two-Pass）、测试执行流分析以及基于红黄绿灯的判定协议。
+  PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、多视角 Sub-Agent 审查、测试执行流分析、代码整洁/重构纪律、置信度校准以及按严重性排序的判定协议。
   触发：`code review` · `PR review` · `审查合并请求` · `review this PR`
 
 - **`zsk:verify`** *[stage 6 · stage · core]*
@@ -124,7 +94,7 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`bugfix task template` · `TDD bug fix` · `red green regression` · `bug confidence questions`
 
 - **`zsk:dor-dod`** *[core]*
-  DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in frontend:dor-dod-frontend.
+  DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in zsk:dor-dod-frontend.
   触发：`definition of ready` · `definition of done` · `DoR DoD` · `task gate`
 
 - **`zsk:refactor-tasks`** *[core]*
@@ -280,7 +250,7 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`NFR baseline` · `non functional requirements` · `quality attributes` · `ISO 25010`
 
 - **`zsk:project-constraints-template`** *[optional]*
-  Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.yaml (mechanical values).
+  Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.md (mechanical values).
   触发：`project constraints` · `SYSTEM-SPEC` · `import origins` · `forbidden packages`
 
 ### `meta/` — Meta · 元信息 (1)

package/frontend/design-frontend/SKILL.md

@@ -32,10 +32,23 @@ triggers:
 # Stage 3: Design · Frontend 补丁
 
 > **用途**：当模块是**前端组件 / 页面**时，在 [`zsk:design`](../../sdlc/design/SKILL.md) 通用骨架上追加的实现映射
-> **范围**：Props 映射、UE 状态 → 结构、Figma → 实现、性能预算 (CWV)、ErrorBoundary
+> **范围**：Props 映射、UE 状态 → 结构、Figma → 实现、前端分层/抽离、性能预算 (CWV)、ErrorBoundary
 
 ## 追加章节
 
+### 0. 前端分层与抽离约束
+
+在通用 [`zsk:design`](../../sdlc/design/SKILL.md) 的代码组织表上，前端模块还要明确：
+
+- 页面 / 容器只做组合、路由参数适配和数据装配
+- 纯 UI 组件不直接请求接口，不持有跨页面业务状态
+- 复杂状态、异步流程、事件编排优先抽到 hooks / composables
+- 数据归一化、过滤、排序、权限判断等可测试逻辑优先抽到 utils / services / models
+- 样式与布局遵循项目样式系统，不把业务判断散落在 class 拼接里
+- 预计变长的列表、树、表单、权限矩阵等必须预先设计子组件和测试边界
+- 目录保持浅层：页面/容器、components、hooks/composables、services、utils/models 足够表达时，不继续嵌套
+- 子组件拆分以“可命名职责 + 可独立测试/复用/替换”为准，不按视觉小块机械拆分
+
 ### A. Props / 状态 / 事件实现映射
 
 Spec 的每个公开 Props 必须说明：
@@ -153,6 +166,8 @@ Spec 的每个 UE 状态必须说明**由哪个容器 / class / 分支渲染**
 
 ## 质量门禁（前端补丁）
 
+- [ ] 页面 / 容器 / UI / hooks / services / utils 职责边界明确
+- [ ] 目录层级扁平，子组件拆分不过碎
 - [ ] Props / UE 状态全部映射到文件
 - [ ] Figma → 实现映射表与 `ue-mcp.md` 一致
 - [ ] 性能预算量化（LCP / INP / CLS / bundle）

package/meta/philosophy/SKILL.md

@@ -24,7 +24,7 @@ triggers:
 
 - **通用**：不绑定任何具体项目、技术栈、组件库
 - **LLM 友好**：frontmatter + 小文件 + 交叉引用
-- **可适配**：项目通过 `PROJECT-CONFIG.yaml` 挂接，不 fork skills
+- **可适配**：项目通过 `zsk.config.yaml` + `project-config.md` 挂接，不 fork skills
 - **有纪律**：Superpowers 硬原则（证据先于断言、TDD、置信度质疑）
 
 ## 四股思想的贡献
@@ -94,28 +94,30 @@ Karpathy 原文是**"LLM 持续自维护的活知识库"**；本 skill set 是**
 | Reflect | `zsk:design` | 怎么做（设计 / ADR） |
 | Engage | `zsk:coding` → `zsk:reviewing` → `zsk:verify` → `zsk:archive` | 动手执行 + 审代码 + 验收 + 沉淀 |
 
-### 4. 项目 SYSTEM-SPEC — 适配层
+### 4. 项目适配层
 
 项目总有定制需求（路径 / 技术栈 / 命名 / 环境）。适配层保证：
 
-- **占位符系统**：`{{config.*}}` 在 skill 内作为抽象变量
+- **资源配置**：`zsk.config.yaml` 描述 `.raws`、模块、工具和同步来源
+- **占位符系统**：`project-config.md` frontmatter 提供 `{{config.*}}`
 - **优先级层级**：项目覆写 > 通用 skill
 - **不 fork**：通过配置文件覆盖，而非修改 skill 本体
 
-## 合成：5 条设计原则
+## 合成：6 条设计原则
 
 ### 原则 1：通用方法 × 项目配置
 
 ```text
  方法论（WHAT / HOW 抽象）      配置（WHERE / WHICH 具体）
         ↓                            ↓
-    .best-practices/      ×     PROJECT-CONFIG.yaml
+    .best-practices/      ×   zsk.config.yaml + project-config.md
         ↘                        ↙
           运行时解析 → 具体产物（模块 proposal.md / spec.md 等）
 ```
 
 - **方法论** → zsk skills（跨项目通用，npm 包）
-- **路径 / 工具 / 命名** → `PROJECT-CONFIG.yaml`（项目本地）
+- **资源 / 模块 / 同步** → `zsk.config.yaml`（项目本地）
+- **技术栈 / 脚本 / 阈值 / 命名** → `project-config.md`（项目本地）
 
 ### 原则 2：LLM 优先的组织
 
@@ -138,6 +140,8 @@ Karpathy 原文是**"LLM 持续自维护的活知识库"**；本 skill set 是**
 - TDD 是 Bugfix / Refactor 默认；Feature 视复杂度
 - 修 bug 前必问三问（Superpowers 置信度质疑）
 - Review 分歧时先验证技术，再讨论情感
+- Issue / Bug 先读日志与复现事实，确认根因后再改代码
+- 多 Agent 只按独立问题域拆分，输入必须自包含，结论必须由主 Agent 复核
 
 ### 原则 5：编号化交叉引用
 
@@ -167,23 +171,33 @@ Archive   Postmortem / ADR 引用原编号保留追溯
 - Bugfix 的"受影响契约项"、Refactor 的"行为不变"都用同一套编号
 - DoR/DoD/质量门禁把编号完整性作为硬性门禁
 
+### 原则 6：项目约束优先，最佳实践按需选择
+
+通用 skill 不预设任何项目一定使用某个语言、框架、目录名或工具。执行时按此顺序落地：
+
+1. 读用户目标和模块事实源
+2. 读 `zsk.config.yaml` 找资源、模块、工具入口
+3. 读 `SYSTEM-SPEC.md`、`project-config.md`、`docs/system/*` 找项目约束
+4. 再选择适用的最佳实践：TDD、Clean Code、重构之道、SOLID、安全、性能、a11y、领域专项
+
+不适用的最佳实践不强行套；适用但项目约束未定义时，先用通用原则提出建议或向用户确认。
+
 ## 优先级层级（冲突时上位胜出）
 
 1. **用户显式指令**（CLAUDE.md / 会话中的直接请求）
-2. **项目 PROJECT-CONFIG.yaml**（本项目的配置覆写）
-3. **项目 SYSTEM-SPEC.md**（本项目的系统规约）
-4. **项目 docs/system/\***（本项目 ADR / architecture / NFR）
-5. **zsk skills**（通用方法论，本目录）
-6. **`~/.claude/skills/*` 平台级 skill**（如 Superpowers）
-7. **工具默认行为**
+2. **项目 `zsk.config.yaml`**（资源、模块、工具和同步入口）
+3. **项目 `project-config.md`**（技术栈、脚本、阈值、命名等占位符配置）
+4. **项目 SYSTEM-SPEC.md**（本项目的系统规约）
+5. **项目 docs/system/\***（本项目 ADR / architecture / NFR）
+6. **zsk skills**（通用方法论，本目录）
+7. **`~/.codex/skills/*` / 平台级 skill**（如 Superpowers）
+8. **工具默认行为**
 
 ## 占位符系统
 
-Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，由 `project-config.yaml`（CLI `zsk project-init` 产出）填充：
+Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，由 `project-config.md` 填充；资源入口与同步方式由 `zsk.config.yaml` 填充：
 
 ```text
-{{config.paths.srs}}             原始需求文档
-{{config.paths.figma_index}}     设计索引（如有）
 {{config.stack.ui_lib}}          UI 库
 {{config.stack.state_async}}     异步状态库
 {{config.stack.state_shared}}    共享状态
@@ -203,19 +217,20 @@ Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，
 以下情况立即停止并修正：
 
 1. Skill 里出现硬编码项目路径（如 `.raws/SRS.md`）→ 必须改为 `{{config.*}}`
-2. Skill 里推荐特定 UI 库名 → 改为 `{{config.stack.ui_lib}}`
-3. 同一份 skill 做 3+ 件事 → 拆分
-4. 单文件 > 300 行 → 拆分或精简
-5. 文档没 frontmatter → 补齐
-6. `description` 以 "Use when…" 开头 → 重写为直接陈述风格（主题名词短语 — 关键要点）
-7. 引用其他 skill 但没写在 `related:` → 补齐
-8. 模板用了未在 `project-config.yaml` 声明的变量 → 补齐配置模板
+2. Skill 里硬编码资源路径 → 改为读取 `zsk.config.yaml.sources.*`
+3. Skill 里推荐特定 UI 库名 → 改为 `{{config.stack.ui_lib}}`
+4. 同一份 skill 做 3+ 件事 → 拆分
+5. 单文件 > 300 行 → 拆分或精简
+6. 文档没 frontmatter → 补齐
+7. `description` 以 "Use when…" 开头 → 重写为直接陈述风格（主题名词短语 — 关键要点）
+8. 引用其他 skill 但没写在 `related:` → 补齐
+9. 模板用了未在 `project-config.md` 声明的变量 → 补齐配置模板
 
 ## 输出承诺
 
 最终的 skill set 通过 `@captain_z/zsk` CLI 发布，允许：
 
 - ✅ 任意新项目通过 `npx @captain_z/zsk project-init` 接入
-- ✅ 不需要修改 skill 内容，只改 `project-config.yaml`
+- ✅ 不需要修改 skill 内容，只改 `project-config.md` 或 `zsk.config.yaml`
 - ✅ 允许项目通过 `SYSTEM-SPEC.md` 本地覆写个别规则
 - ✅ 上游 skill 更新不破坏项目（版本化 + config 向后兼容）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captain_z/zsk-skills",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "ZNorth Standard Kit — skill content package (SDLC + frontend + quality + design-handoff + system + meta)",
   "license": "MIT",
   "files": [

package/quality/code-hygiene/SKILL.md

@@ -112,6 +112,16 @@ triggers:
 - **文件长度**：超阈值必拆（推荐 300-500 行按语言）
 - **深度嵌套**：推荐 ≤ 3-4 层
 
+## 组织与抽离原则
+
+- **相关性优先**：目录按业务能力和变化原因组织，不按随手创建的技术桶无限堆叠。
+- **边界先于复用**：抽离首先为了清晰边界和可测试，其次才是减少行数。
+- **单文件单主责**：一个文件同时承担入口编排、UI、业务规则、数据访问、工具函数时，必须拆。
+- **抽离形式适配项目**：纯计算用 util，状态/副作用用 hook/composable，外部 IO 用 service/repository，复杂领域规则用 domain object/class/service。
+- **扁平优先**：目录深度默认保持浅层；只有职责边界、权限边界、发布边界或复用边界明确时才加一层。
+- **不过度碎片化**：拆分后如果调用链更难追踪、文件名无法表达稳定职责、测试收益很低，应合并回邻近模块。
+- **避免过早抽象**：只被一个地方使用且很小的逻辑可以留在局部，但要保持命名清楚、测试可达。
+
 具体到栈：
 - TypeScript 红线：见 [`frontend/typescript`](../../frontend/typescript/SKILL.md)
 - React 命名规范：见 [`frontend/react-naming`](../../frontend/react-naming/SKILL.md)

package/quality/testing-pyramid/SKILL.md

@@ -74,6 +74,17 @@ Bugfix 与 Refactor 默认使用 TDD；Feature 视情况（复杂逻辑建议 TD
 
 ## 测试用例设计
 
+### 事实源匹配
+
+测试用例必须能追溯到原始资源和设计约束：
+
+- 原始测试资产：`.raws/testing`、SRS、提测用例、历史缺陷
+- 行为契约：`spec.md` 的 FR / NFR / AC / 场景
+- 设计约束：`design.md` 的关键流程、状态机、数据流、错误处理、回滚策略
+- 模块映射：`docs/{module}/module.yaml` 的 `tests.raw_cases` / `derived_cases` / `automated`
+
+缺少追溯来源的测试可作为补充，但不能替代契约测试。
+
 ### 结构：AAA 或 GWT（语言无关）
 
 ```text
@@ -101,6 +112,13 @@ GWT（Given - When - Then）
 4. **契约边界**：公开接口的每个参数组合
 5. （若涉及）并发 / 幂等 / 重入
 
+## 场景覆盖目标
+
+- **目标：100% 场景覆盖**。`spec.md` 中每个 Scenario / AC、`.raws/testing` 中每个原始用例、`design.md` 中每条关键流程分支都应映射到测试或人工验证证据。
+- 无法 100% 覆盖时，必须在 `verification.md` 记录缺口、风险、原因、补测计划和用户/负责人豁免。
+- 覆盖率按“场景与分支”计算，不只看语句覆盖率。语句 100% 但缺失业务场景，仍视为测试缺口。
+- P0/P1 业务路径、权限路径、数据一致性路径和历史缺陷回归不得豁免。
+
 ### 独立性与确定性
 
 - **不共享状态**：每个 test 独立 setup / teardown
@@ -134,6 +152,8 @@ GWT（Given - When - Then）
 - [ ] 代码合并到主干
 - [ ] 单元测试通过，覆盖关键分支
 - [ ] 集成 / E2E 测试通过（如适用）
+- [ ] 原始测试资产、Spec 场景、Design 分支均已映射
+- [ ] 场景覆盖目标为 100%；不足项有风险和豁免记录
 - [ ] `lint` / `type-check` / `build` 零 error
 - [ ] PR 自检清单全部勾选
 

package/sdlc/bugfix/SKILL.md

@@ -59,7 +59,7 @@ Bug报告         复现+期望        5 Whys        Red→Green       相邻回
 **Addendum**:
 - 按 [`zsk:proposal`](../proposal/SKILL.md) 的 Bugfix 型模板
 - 严重度 P0–P3 明确
-- 是否 Hotfix 决策在此做出（见 [`quality:release`](../../quality/release/SKILL.md)）
+- 是否 Hotfix 决策在此做出（见 [`zsk:release`](../../quality/release/SKILL.md)）
 
 **Exit**: 严重度 / 影响范围 / 复现步骤明确 · 证据完整（截图 / 录屏 / 日志 / trace）
 
@@ -139,7 +139,7 @@ Bug报告         复现+期望        5 Whys        Red→Green       相邻回
 - 边界条件测试
 - 相关质量维度核对（前端：a11y / i18n / 性能；后端：幂等 / 并发 / 权限）
 - **证据归档**：log 前后对照、测试报告、复现步骤回归
-- **P0 / P1 → Hotfix 流程**（见 [`quality:release`](../../quality/release/SKILL.md)）
+- **P0 / P1 → Hotfix 流程**（见 [`zsk:release`](../../quality/release/SKILL.md)）
 - **P2 / P3 → 常规发布**
 
 **Output**: 修复代码 + 回归测试 · 证据链（前后对照截图 / 报告）

package/sdlc/coding/SKILL.md

@@ -37,7 +37,7 @@ triggers:
 > **阶段定位**：实施 / Execution
 > **回答的问题**：按什么顺序实现、如何控制改动、何时可以提交评审
 > **不回答的问题**：需求边界是否成立（看 `spec`）、方案是否合理（看 `design`）、是否满足契约（看 `verify`）
-> **项目/框架约束放哪里**：仓库结构、提交规范、分支规则、必用封装、禁用模式都来自 `SYSTEM-SPEC.md`、`project-config.yaml` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)
+> **项目/框架约束放哪里**：仓库结构、提交规范、分支规则、必用封装、禁用模式都来自 `SYSTEM-SPEC.md`、`project-config.md` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)
 
 ## 阶段职责
 

package/sdlc/design/SKILL.md

@@ -34,7 +34,7 @@ triggers:
 > **阶段定位**：方案设计 / Solution Design
 > **回答的问题**：在当前系统约束下，如何把 Spec 落成可执行方案
 > **不回答的问题**：新增未在 Spec 声明的公开行为；写实现代码
-> **项目/框架约束放哪里**：团队、语言、框架、仓库规则来自 `SYSTEM-SPEC.md`、`project-config.yaml` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Design 只引用并落实
+> **项目/框架约束放哪里**：团队、语言、框架、仓库规则来自 `SYSTEM-SPEC.md`、`project-config.md` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Design 只引用并落实
 
 ## 核心输入
 
@@ -49,10 +49,11 @@ Design 应沉淀以下内容：
 1. 当前状态与约束
 2. 关键决策与理由
 3. 目标结构 / 流程 / 数据或交互流
-4. FR / NFR 到实现的映射
-5. 错误处理、降级、兼容、迁移与回滚
-6. 可观测性与验证策略
-7. 交付切片 / 依赖顺序
+4. 代码组织、分层与抽离策略
+5. FR / NFR 到实现的映射
+6. 错误处理、降级、兼容、迁移与回滚
+7. 可观测性与验证策略
+8. 交付切片 / 依赖顺序
 
 ## 变更类型差异
 
@@ -108,19 +109,33 @@ Design 可以决定实现方式，不能追加新的对外契约。发现 Spec
 - 失败时如何止损
 - 是否需要兼容期或双跑期
 
+### 6. 代码组织必须先设计后实现
+
+Design 必须说明代码如何组织，避免 coding 阶段自然长成“单文件堆积”：
+
+- **按相关性聚合**：同一业务能力放在同一模块边界内；不同业务能力不要混放。
+- **目录尽量扁平**：优先 2-3 层可读结构；没有明确职责收益时，不新增深层目录。
+- **分层清晰**：入口 / UI 或接口适配 / 业务逻辑 / 数据访问 / 工具函数边界明确。
+- **逻辑与表现分离**：可复用业务规则、状态推导、数据转换不要埋在 UI、controller 或路由入口里。
+- **按稳定职责抽离**：跨入口复用或可独立测试的逻辑抽为 `utils` / `hooks` / `services` / `models` / class / domain service 等项目适配形式。
+- **模块化但不过碎**：拆分围绕业务相关性、复用边界、测试边界和变更原因；不要把只服务一个小分支的微逻辑拆成难追踪文件。
+- **控制文件体量**：预计超过项目阈值、出现多个职责或深层嵌套时，设计阶段就给出拆分方案。
+- **依赖方向单向**：底层逻辑不反向依赖 UI / 入口层；共享层不依赖具体业务页面。
+
 ## 推荐结构
 
 1. 模块映射与事实源
 2. 当前状态与关键约束
 3. 目标结构 / 关键流程
 4. 决策记录（ADR 级或局部设计决策）
-5. FR 实现映射
+5. 代码组织 / 分层 / 抽离策略
+6. FR 实现映射
 > **核心映射原则**：方案产出必须呈现一张明确的矩阵（FR编号 -> 代码模块），此为设计与现实实现的锚点。
-6. NFR 落地策略
-7. 错误处理 / 降级 / 安全边界
-8. 迁移 / 回滚 / 发布策略
-9. 可观测性 / 测试策略
-10. 交付切片与依赖
+7. NFR 落地策略
+8. 错误处理 / 降级 / 安全边界
+9. 迁移 / 回滚 / 发布策略
+10. 可观测性 / 测试策略
+11. 交付切片与依赖
 
 ## Feature 型模板
 
@@ -140,6 +155,25 @@ Design 可以决定实现方式，不能追加新的对外契约。发现 Spec
 - 目标结构：
 - 关键流程：
 
+## 代码组织 / 分层 / 抽离策略
+| 层 / 职责 | 文件或目录 | 放入内容 | 不放入内容 |
+| --- | --- | --- | --- |
+| 入口 / 组合 |  | 编排、依赖注入、路由/页面组装 | 复杂业务规则 |
+| UI / 表现 |  | 渲染、交互状态、样式适配 | 数据访问、跨模块业务规则 |
+| 业务逻辑 |  | 规则、状态推导、流程判断 | UI 细节 |
+| 数据 / 服务 |  | API、仓储、DTO 归一化 | 展示逻辑 |
+| 工具 / 共享 |  | 纯函数、格式化、通用转换 | 具体业务流程 |
+
+## 目录形态
+| 目录 | 层级 | 职责 | 保持/新增理由 |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## 抽离决策
+| 候选逻辑 | 抽离形式 | 理由 | 测试方式 |
+| --- | --- | --- | --- |
+|  | util / hook / service / class / component |  |  |
+
 ## 关键决策
 | 决策 | 选项 | 结论 | 理由 |
 | --- | --- | --- | --- |
@@ -230,6 +264,9 @@ Design 里不必写完整 `tasks.md`，但必须给出：
 - [ ] 已扫描当前状态与关键约束
 - [ ] 未新增 Spec 未声明的行为
 - [ ] 关键决策有理由，有主要替代方案对照
+- [ ] 代码组织、分层和抽离策略明确
+- [ ] 目录结构尽量扁平，没有无理由深层嵌套
+- [ ] 拆分粒度合理，既没有单文件堆积，也没有过度碎片化
 - [ ] FR / NFR 均有落地方式
 - [ ] 错误处理、回滚、验证策略明确
 - [ ] 高风险改动已说明兼容 / 迁移方案

package/sdlc/dor-dod/SKILL.md

@@ -2,7 +2,7 @@
 name: zsk:dor-dod
 description: DoR/DoD gates between SDLC stages — generic DoR/DoD for all change
   types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are
-  in frontend:dor-dod-frontend.
+  in zsk:dor-dod-frontend.
 category: resource
 domain: sdlc
 tier: core
@@ -27,7 +27,7 @@ triggers:
 # DoR & DoD — 任务启动与关闭门禁
 
 > **用途**：启动一个任务前跑 DoR；交付 / 关闭前跑 DoD
-> **通用版 + 变更类型专用**；前端项目的额外条款（UE / Figma / 三语 / a11y / 视觉回归）见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> **通用版 + 变更类型专用**；前端项目的额外条款（UE / Figma / 三语 / a11y / 视觉回归）见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ## Definition of Ready（DoR）— 启动前门禁
 
@@ -44,7 +44,7 @@ triggers:
 - [ ] NFR 六类（性能 / 可靠性 / 安全 / 国际化 / 兼容性 / 可观测性）全覆盖
 - [ ] 后端契约目录（若涉及接口）已对齐
 
-> 前端模块额外：UE 状态矩阵覆盖、`ue-mcp.md` 登记、Props / Event Contract 完整 — 见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> 前端模块额外：UE 状态矩阵覆盖、`ue-mcp.md` 登记、Props / Event Contract 完整 — 见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ### Bugfix 专用
 
@@ -75,7 +75,7 @@ triggers:
 - [ ] **FR 覆盖矩阵**所有 P0 FR 都有"覆盖任务 + 验收证据"（见 [`zsk:task-evidence`](../task-evidence/SKILL.md)）
 - [ ] **校验记录**每行有证据链接（证据先于断言）
 
-> 前端模块额外：视觉回归 / i18n 三语 / a11y / CWV — 见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> 前端模块额外：视觉回归 / i18n 三语 / a11y / CWV — 见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ### Feature 专用
 

package/sdlc/feature/SKILL.md

@@ -66,7 +66,7 @@ triggers:
 - User Stories 满足 INVEST
 - BDD Given/When/Then ≥ 1 Happy + 1 Edge
 - FR / NFR / US / AC 编号完整
-- **前端模块补** [`frontend:spec-frontend`](../../frontend/spec-frontend/SKILL.md)：Props / Event Contract / UE 状态矩阵 / Figma 引用
+- **前端模块补** [`zsk:spec-frontend`](../../frontend/spec-frontend/SKILL.md)：Props / Event Contract / UE 状态矩阵 / Figma 引用
 
 **Output**: `docs/{module}/spec.md`（+ 前端模块的 `ue-mcp.md` / `api-contract.md`）
 
@@ -82,7 +82,7 @@ triggers:
 - 按 [`zsk:design`](../design/SKILL.md) 的 Feature 型模板
 - 关键决策都走 ADR（模板 [`zsk:adr`](../../system/adr/SKILL.md)）
 - 上下文图 + 时序图（Mermaid 内联）
-- **前端模块补** [`frontend:design-frontend`](../../frontend/design-frontend/SKILL.md)：Props/UE 实现映射 + Figma → 实现 + 性能预算（CWV）
+- **前端模块补** [`zsk:design-frontend`](../../frontend/design-frontend/SKILL.md)：Props/UE 实现映射 + Figma → 实现 + 性能预算（CWV）
 - 错误 / 降级 / 回滚策略
 - 未新增 Spec 未声明的行为
 
@@ -97,9 +97,9 @@ triggers:
 **Primary Skill**: `superpowers:executing-plans` · `superpowers:test-driven-development` · `zsk:coding` · `superpowers:using-git-worktrees`（需隔离时）· `code-commit` · GSD: Engage
 
 **Addendum**:
-- 任务模板：通用用 [`zsk:task-structure`](../task-structure/SKILL.md)；组件/前端用 [`frontend:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md)（7 类强制任务）
+- 任务模板：通用用 [`zsk:task-structure`](../task-structure/SKILL.md)；组件/前端用 [`zsk:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md)（7 类强制任务）
 - 遵循 [`zsk:coding`](../coding/SKILL.md) 的分支 / commit / 依赖卫生
-- 遵循 [`quality:testing-pyramid`](../../quality/testing-pyramid/SKILL.md)
+- 遵循 [`zsk:testing-pyramid`](../../quality/testing-pyramid/SKILL.md)
 - 契约驱动：类型引自 Spec / 后端契约（`system/project-constraints-template`）
 
 **Exit**: 测试金字塔三层均有任务且绿 · 本地 lint / type-check / test 零 error · Commit 遵循 Conventional Commits
@@ -111,7 +111,7 @@ triggers:
 **Primary Skill**: `superpowers:requesting-code-review` · `superpowers:receiving-code-review` · `zsk:reviewing` / `review` / `merge-review` / `codex review`
 
 **Addendum**:
-- 自评清单（通用见 [`zsk:reviewing`](../reviewing/SKILL.md)；前端补 [`frontend:review-frontend`](../../frontend/review-frontend/SKILL.md)）全绿
+- 自评清单（通用见 [`zsk:reviewing`](../reviewing/SKILL.md)；前端补 [`zsk:review-frontend`](../../frontend/review-frontend/SKILL.md)）全绿
 - 至少 1 轮 Code Review 通过（高风险改动 ≥ 2 人）
 - Conventional Comments：`blocking:` / `issue:` / `suggestion:` / `nitpick:`
 - 分歧验证技术事实再决策
@@ -128,7 +128,7 @@ triggers:
 - DoD 全绿（见 [`zsk:dor-dod`](../dor-dod/SKILL.md)）
 - FR 覆盖矩阵完整（Spec 每条 P0 FR 都有任务 + 验收证据）
 - AC 逐条勾选，每条有证据链接
-- 校验记录全绿（通用 + 前端项目补 `frontend:nfr-web` 的视觉 / a11y / i18n / 性能 / 安全）
+- 校验记录全绿（通用 + 前端项目补 `zsk:nfr-web` 的视觉 / a11y / i18n / 性能 / 安全）
 
 **Output**: `docs/{module}/tasks.md`（全程更新）· 代码 + 测试 · PR / MR · Changelog 条目 · 证据链
 
@@ -144,7 +144,7 @@ triggers:
 - Changelog `Added` 条目引用 Spec FR 编号
 - 归档入 `SYSTEM-SPEC.md`（如有系统级约定）
 - 历史快照保存到 `docs/{module}/archive/{YYYY-MM-DD}-{需求名}/`
-- 遵循 [`quality:release`](../../quality/release/SKILL.md)（SemVer / Changelog / 回滚预案）
+- 遵循 [`zsk:release`](../../quality/release/SKILL.md)（SemVer / Changelog / 回滚预案）
 - 发布后 30 分钟 canary 观察（若适用）
 
 ## Skip 规则

package/sdlc/refactor/SKILL.md

@@ -172,7 +172,7 @@ triggers:
 **Addendum**:
 - 更新 `design.md` 中的 ADR（Proposed → Accepted）
 - Changelog 仅 **Changed** / **Removed** 章节（**不在** Added / Fixed）
-- 遵循 [`quality:release`](../../quality/release/SKILL.md)
+- 遵循 [`zsk:release`](../../quality/release/SKILL.md)
 - 大重构若用 feature flag，登记 flag 清理计划
 - 大重构归档到 `docs/{module}/archive/{YYYY-MM-DD}-refactor-{简述}/`
 

package/sdlc/reviewing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zsk:reviewing
-description: PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、置信度评估、多阶段审查（Two-Pass）、测试执行流分析以及基于红黄绿灯的判定协议。
+description: PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、多视角 Sub-Agent
+  审查、测试执行流分析、代码整洁/重构纪律、置信度校准以及按严重性排序的判定协议。
 category: stage
 domain: sdlc
 tier: core
@@ -28,75 +29,117 @@ triggers:
 > **阶段定位**：代码与架构审查（Code & Architecture Review）
 > **目标**：以高置信度的客观标准发现代码缺陷、架构偏移和需求蔓延，防止劣质代码合入主干。
 > **核心原则**：
-> - **事实先行**：审查不仅看代码语法，更要对照 `spec.md` 验证意图。
+> - **业务正确性优先**：先判断业务逻辑、交付范围、完成质量和验收条件是否满足，再谈代码风格。
+> - **事实先行**：审查不仅看代码语法，更要对照 `proposal.md` / `spec.md` / `design.md` / `tasks.md` 验证意图。
 > - **置信度校准**：宁缺毋滥。高确定性问题亮红灯，猜测性建议必须降级。
 > - **全链路视角**：不放过任何一个未处理的错误流分支。
 
-## 🤖 AI 代码审查标准流 (AI Code Review Flow)
+## AI 代码审查标准流 (AI Code Review Flow)
 
-当 Agent（或 Sub-Agent）被召唤进行代码审查时，必须**严格按顺序执行以下四个阶段**。不得跳过。
+当 Agent 被召唤进行代码审查时，必须**严格按顺序执行以下五个阶段**。主 Agent 负责整合结论；Sub-Agent 只负责专业视角，不直接给最终放行。
 
 ### 阶段 1：Scope Drift Detection (需求偏移检测)
 
 **核心目标**：检查“写的是不是要求的东西”——不夹带私货，不漏掉功能。
 
-1. 读取 `spec.md` 和 `tasks.md`，提取出所有的目标项。
+1. 按顺序读取 `proposal.md`、`spec.md`、`design.md`、`tasks.md`，提取业务目标、FR/NFR、AC、设计决策、任务完成状态。
 2. 运行 `git diff` 对比变更。
-   - **重要约束**：必须优先读取 `project-config.md` 中的 `defaultBranch` 字段作为 base 分支。如果未配置，默认使用 `origin/main` 作为比对基础。
-3. 产出一份 **Scope Check 报告**：
+   - **重要约束**：优先读取 `project-config.md` frontmatter 中的 `git.main_branch` / `{{config.git.main_branch}}` 作为 base 分支。
+   - 未配置时，先用仓库默认上游（如 `origin/HEAD` 或当前分支 merge-base）探测；仍无法确定时，明确说明假设，才退回 `origin/main`。
+3. 产出一份 **Completion Check 报告**：
+   - `[BUSINESS OK]`：核心业务路径与业务规则成立。
    - `[DONE]`：代码与目标严格匹配。
    - `[NOT DONE]`：Spec 中要求的但在 diff 中找不到证据（Missing Requirements）。
+   - `[DESIGN GAP]`：实现没有遵循已确认的 design，或 design 未覆盖实际高风险变更。
+   - `[TASK GAP]`：tasks 标记完成但代码/测试/证据不支持。
    - `[CREEP]`：diff 中出现了 Spec/Task 中根本没提到的重构或新功能（Scope Creep）。
    - *（注意：Scope Creep 需要特别指明，由用户判断是正向的补充还是危险的蔓延）*
 
-### 阶段 2：Two-Pass Multi-Agent 审查 (两遍核心检查)
+### 阶段 2：Sub-Agent Review Plan (多视角审查计划)
 
-将审查分为两个独立视角（Agent 应分饰多角依次进行）。
+满足任一条件时，主 Agent 应拆分 Sub-Agent 并行审查，减少主上下文负担并提高专业性：
 
-**Pass 1: Critical (致命问题审查 - P1级别)**
-- **SQL / 数据安全**：检查是否存在注入、数据越权、无 WHERE 条件的全表更新。
-- **并发与竞态**：检查是否存在共享可变状态、缺乏事务锁的资金/库存操作。
-- **契约破坏**：是否悄悄改变了对外公开 API 的出入参结构。
-- **红线违规**：是否引入了 `SYSTEM-SPEC.md` 中禁用的依赖或违背了 Import 起源规则。
+- diff 跨 5 个以上文件、多个模块或多种技术栈
+- 涉及权限、资金、数据一致性、安全、迁移、公共 API、性能关键路径
+- 需求、设计、测试资产、代码之间存在不一致
+- Review 需要同时覆盖前端视觉/交互、后端契约、测试、重构等不同专业视角
 
-**Pass 2: Compliance & Best Practices (合规与架构审查 - P2/P3级别)**
-- **代码结构**：是否存在魔法数字、强耦合、废弃代码未删。
-- **错误降级**：所有异常捕获是否有合理的降级策略（Fallback），网络错误对用户是否可见。
-- **特定领域检查**：对于前端代码，必须引用并符合 `frontend/review-frontend.md`。
+默认视角：
 
-### 阶段 3：Test Coverage Tracking (测试死角追踪)
+| 视角 | 关注点 | 输出 |
+| --- | --- | --- |
+| Business / Completion | 业务逻辑、`proposal.md` 目标、`spec.md` FR/AC、`design.md` 决策、`tasks.md` 完成度是否被实现证据支撑 | `[BUSINESS BUG]` / `[NOT DONE]` / `[DESIGN GAP]` / `[TASK GAP]` |
+| Completion Quality | 已完成内容的质量是否达到可合并标准：证据闭环、边界清晰、异常/回归覆盖、实现复杂度可接受、无明显维护债 | `[QUALITY GAP]` / 返工建议 / 豁免条件 |
+| Scope / Contract | API 契约、`SYSTEM-SPEC.md`、模块边界、数据模型是否与 diff 一致 | `[CREEP]` / 契约破坏 / 系统约束违规 |
+| Correctness / Risk | 数据流、状态机、边界值、并发、权限、安全、错误流 | 可复现 bug 和高风险路径 |
+| Test / TDD | `.raws/testing`、派生用例、单元/集成/E2E 覆盖与 Red-Green 证据 | `[TESTING GAP]` 与缺失用例 |
+| Project Best Practices | 结合项目技术栈与约束选择 Clean Code、重构之道、SOLID、性能、安全、a11y、i18n、前端/后端专项等检查 | 可维护性、可演进性和专项质量问题 |
+
+Sub-Agent 使用原则：
+
+- 每个 Sub-Agent 只拿必要上下文：目标、base/head、相关文件、对应检查清单。
+- Sub-Agent 输出必须包含 `severity`、`confidence`、`file:line`、证据和建议修复方向。
+- 主 Agent 必须复核高严重性问题，不得把 Sub-Agent 报告原样当最终事实。
+- 没有工具能力开 Sub-Agent 时，主 Agent 也要按同样视角顺序自查，并说明未并行的原因。
+
+### 阶段 3：Two-Pass Core Review (两遍核心检查)
+
+**Pass 1: Critical / Blocking**
+
+- **数据与安全**：注入、越权、敏感信息泄露、无 WHERE 更新、危险动态执行。
+- **并发与一致性**：竞态、事务边界、幂等性、重复提交、缓存不一致。
+- **契约破坏**：公开 API、事件、类型、数据结构、持久化格式是否悄悄变化。
+- **系统红线**：是否违反 `SYSTEM-SPEC.md`、导入边界、禁用依赖、许可证/安全基线。
+
+**Pass 2: Compliance / Maintainability**
+
+- **项目最佳实践选择**：根据 `SYSTEM-SPEC.md`、`project-config.md`、技术栈和变更类型选择合适的最佳实践，而不是机械套固定清单。
+- **Clean Code / 代码整洁之道**：命名表达意图、函数单一职责、无重复、无无效注释、无魔法常量。
+- **重构之道**：重构必须行为不变、独立于 feature/bugfix；需要 Characterization Test 时不能跳过。
+- **SOLID / 架构边界**：仅在当前语言/架构适用时检查依赖方向、抽象稳定性、职责分离。
+- **错误处理**：异常是否可恢复、可观测、对用户可理解；失败路径是否有降级。
+- **领域专项**：前端代码必须引用并符合 [`zsk:review-frontend`](../../frontend/review-frontend/SKILL.md)。
+
+### 阶段 4：Test Coverage Tracking (测试死角追踪)
 
 1. **画出执行流 (Mental Model)**：对于被改变的每一个核心函数，不仅要看正常流程，必须分析其“异常分支”（if-else, try-catch, 边界值）。
-2. **校验测试映射**：查找对应的测试代码，核对测试用例是否覆盖了步骤 1 中的异常分支。
+2. **校验测试资产映射**：先看 `.raws/testing` 与 `docs/{module}/module.yaml` 中的 raw/derived/automated 映射，再查对应测试代码。
 3. **输出 Gap (死角报告)**：如果某个条件分支（如服务端返回 500 时 UI 的处理）在 diff 中没有对应的单元测试/E2E测试覆盖，必须作为 `[TESTING GAP]` 显式列出。
+4. **TDD 校验**：Bugfix / Refactor / 高风险业务逻辑若没有先失败再变绿的证据，应作为 Important 以上问题。
 
-### 阶段 4：Confidence Calibration 与红绿灯定论输出
+### 阶段 5：Severity, Confidence 与红绿灯定论输出
 
-在给出最终的 Review 报告时，所有的发现（Findings）必须带上 **置信度评分 (Confidence: N/10)**。
+在给出最终 Review 报告时，所有 Findings 必须按严重性排序，并带上 **置信度评分 (Confidence: N/10)**。
+
+| Severity | 含义 | 处理规则 |
+| --- | --- | --- |
+| Critical | 会导致安全/数据/权限/生产事故，或明确阻塞需求交付 | 必须修复，不能合并 |
+| Important | 高概率 bug、契约偏移、关键测试缺失、违反 TDD/重构纪律 | 合并前修复或用户显式豁免 |
+| Minor | 可维护性、可读性、局部清理建议，不影响本次交付正确性 | 可排后续 |
+| Question | 信息不足，需要作者补证据或解释 | 不当成事实缺陷 |
 
 - **9-10 (确凿)**：通过阅读明确上下文确认的 Bug 或红线违背。
 - **7-8 (极大概率)**：高置信度模式匹配（如常见的性能泄漏点）。
 - **5-6 (存疑)**：可能是误报，需提示用户验证。
 - **< 5 (猜测)**：除非是 P0 级风险，否则不要在最终报告中扰民。
 
-**输出格式**：`[SEVERITY] (confidence: N/10) filename:line — description`
+**输出格式**：`[SEVERITY] (confidence: N/10) filename:line — description — evidence / suggested fix`
 
 #### 最终判定协议 (Verdict Protocol)
 
-Agent 在完成四步后，必须输出以下三种颜色的最终判定：
+Agent 在完成五步后，必须输出以下三种颜色的最终判定：
 
 - 🟢 **PASS (通过)**：仅有少量拼写错误、格式建议，无阻碍性问题。可以进入 `Verify`。
-- 🟡 **PASS_WITH_CONCERNS (带条件通过)**：存在 Scope Creep（但无害）、低置信度的架构建议、或遗漏的非致命测试。给出列表，请求用户定夺。
-- 🔴 **FAIL / BLOCKED (拒绝)**：发现 P1 级 Critical 问题、置信度极高的未捕获异常、或大面积未完成的 `[NOT DONE]` 需求。必须回退到 Coding 进行修复。
+- 🟡 **PASS_WITH_CONCERNS (带条件通过)**：存在 Important 但有明确豁免理由、低置信度架构建议、或遗漏的非致命测试。给出列表，请求用户定夺。
+- 🔴 **FAIL / BLOCKED (拒绝)**：发现 Critical、未完成的 `[NOT DONE]`、高置信度严重缺陷、或关键测试/TDD 证据缺失。必须回退到 Coding 进行修复。
 
 ---
 
-## 👩‍💻 人类评审规约 (Human Reviewer Guidelines)
+## 人类评审规约 (Human Reviewer Guidelines)
 
 ### 发起者自查清单 (Author Pre-PR Checklist)
-> 💡 强烈建议 Author 在提交 PR 交给 AI 或其他人审查之前，先行对照以下精简清单自查，以节约 Review 成本。
 
-- [ ] 是否在本地运行了 `pnpm typecheck` 和 `pnpm lint` 且 0 报错？
+- [ ] 是否在本地运行了 `{{config.scripts.type_check}}` 和 `{{config.scripts.lint}}` 且 0 报错？
 - [ ] 所有的改动是否都属于该 PR 的原始目标？(拒绝私带重构代码)
 - [ ] 核心 API 修改是否已经通知了潜在的调用方？
 - [ ] UI 变动是否已在明暗色、移动/桌面端自我验收？

package/sdlc/spec/SKILL.md

@@ -35,7 +35,7 @@ triggers:
 > **阶段定位**：行为规格 / Requirements Contract
 > **回答的问题**：做什么、在什么边界内做、什么算验收通过
 > **不回答的问题**：怎么实现、怎么分层、文件怎么改，这些属于 `zsk:design`
-> **项目/框架约束放哪里**：项目特定规则写进 `SYSTEM-SPEC.md`、`project-config.yaml` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Spec 只引用，不重写
+> **项目/框架约束放哪里**：项目特定规则写进 `SYSTEM-SPEC.md`、`project-config.md` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Spec 只引用，不重写
 
 ## 核心输入
 
@@ -53,7 +53,9 @@ Spec 必须沉淀以下内容：
 4. 编号化非功能需求（NFR）
 5. 场景化验收（BDD 或等价格式）
 6. 编号化验收标准（AC）
-7. 边界、异常、兼容与影响
+7. 测试场景覆盖要求
+8. 可维护性 / 代码组织约束（只写验收口径，不写实现方案）
+9. 边界、异常、兼容与影响
 
 ## 变更类型差异
 
@@ -118,6 +120,27 @@ Spec 必须沉淀以下内容：
 
 Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR 关系由 [`zsk:task-structure`](../task-structure/SKILL.md) 和 coding 阶段负责。
 
+### 7. 测试覆盖要求要可追溯
+
+Spec 必须把原始资源中的测试用例、业务场景和验收标准纳入同一张追溯网：
+
+- `.raws/testing` 中的原始用例必须映射到 FR / AC / Scenario
+- 每个 Scenario 至少有一种验证方式：自动化测试、人工验证、截图/录屏或日志证据
+- 场景覆盖目标默认 100%；不能覆盖时必须记录缺口和豁免条件
+- 设计阶段新增的关键分支必须回写到 Spec 或测试矩阵，避免“实现才知道”的隐藏场景
+
+### 8. 可维护性约束要可验收
+
+Spec 不设计目录，但可以声明完成质量的验收口径：
+
+- 业务逻辑与 UI / 表现层不得强耦合
+- 模块职责边界必须清晰，不能把无关能力堆进同一文件
+- 复杂流程、状态推导、数据转换必须可单独测试
+- 需要复用的逻辑不得复制粘贴到多个入口
+- 文件体量、复杂度、依赖方向遵守 `SYSTEM-SPEC.md` / `project-config.md` 的阈值
+
+这些约束应写成 NFR 或 AC，由 Design 决定具体分层、目录与抽离形式。
+
 ## 推荐结构
 
 1. 模块映射与事实源
@@ -126,10 +149,12 @@ Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR
 4. 用户故事 / 关键场景
 5. 功能需求（FR）
 6. 非功能需求（NFR）
-7. 行为场景（BDD 或等价）
-8. 验收标准（AC）
-9. 异常 / 边界 / 兼容性
-10. 影响面
+7. 完成质量约束
+8. 测试覆盖矩阵要求
+9. 行为场景（BDD 或等价）
+10. 验收标准（AC）
+11. 异常 / 边界 / 兼容性
+12. 影响面
 
 ## Feature 型模板
 
@@ -163,6 +188,19 @@ Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR
 | 编号 | 类别 | 要求 | 验证方式 |
 | --- | --- | --- | --- |
 
+## 完成质量约束
+| 编号 | 约束 | 验收方式 |
+| --- | --- | --- |
+| AC-Q1 | 业务逻辑与 UI / 表现层边界清晰 | Design 中有分层映射；Review 无强耦合阻塞问题 |
+| AC-Q2 | 复杂逻辑可单独测试 | 有对应单元 / 集成测试映射 |
+
+## 测试覆盖矩阵要求
+| 来源 | 场景 / 用例 | 覆盖目标 | 验证方式 |
+| --- | --- | --- | --- |
+| `.raws/testing/...` |  | 100% | 自动化 / 人工证据 |
+| `Scenario` |  | 100% | 自动化 / 人工证据 |
+| `AC-*` |  | 100% | 自动化 / 人工证据 |
+
 ## 行为场景
 ### Scenario: {场景名}
 - Given ...
@@ -187,14 +225,8 @@ Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR
 ```md
 # Bugfix Spec: {问题名}
 
-> 变更类型：Bugfix
-> 关联 Proposal：`docs/{module}/proposal.md`
-> 日期：{YYYY-MM-DD}
-
 ## 受影响契约项
-- FR：
-- NFR：
-- AC：
+- FR / NFR / AC：
 
 ## Expected vs Actual
 | 场景 | 预期 | 实际 |
@@ -206,12 +238,6 @@ Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR
 - 必须继续成立：
 - 本次不处理：
 
-## 场景与验收
-### Scenario: {bug 场景}
-- Given ...
-- When ...
-- Then ...
-
 ## 验收标准（AC）
 - [ ] AC-1：原复现步骤不再触发
 - [ ] AC-2：相邻场景无回归
@@ -222,10 +248,6 @@ Spec 可以给出交付切片建议，但详细任务结构、估算、覆盖 FR
 ```md
 # Refactor Spec: {主题}
 
-> 变更类型：Refactor
-> 关联 Proposal：`docs/{module}/proposal.md`
-> 日期：{YYYY-MM-DD}
-
 ## 行为不变边界
 - 对外保持不变：
 - 本次不承诺：

package/sdlc/standard-dev-flow/SKILL.md

@@ -30,6 +30,7 @@ triggers:
 > **定位**：这是一套专为公司级开发或新项目设计的 **分节点交互式编排工作流 (Interactive Orchestrator Skill)**。遵循业界最佳实践，确保高内聚、低耦合以及严格的质量门禁。
 > **核心原则**：工作流分为 **9 个串行节点**。Agent **绝不允许跨节点越权执行**。在每个节点的任务完成后，Agent 必须停下来，询问用户是否可以进入下一个环节，并在得到明确肯定后方可继续。
 > **适用场景**：复杂功能的从头开发、需要高质量审查的重要迭代。
+> **职责边界**：本 skill 只做流程编排；每个节点的详细模板和门禁以对应 stage skill 为准，避免复制出第二套规范。
 
 ## Agent 执行铁律 (The Golden Rules)
 
@@ -45,13 +46,15 @@ triggers:
 
 ### Node 1: Prepare (准备与资源收集)
 - **目标**：准备开发资源，建立本次迭代的事实源（Source of Truth）。
-- **Agent 动作**：向用户索要初始输入，并将其统一整理保存到项目根目录的 `.raws/` 文件夹下。
-- **`.raws/` 命名规范**（必须遵守）：
-  - 需求文档 → `.raws/requirements.md`
-  - Figma 链接或导出 → `.raws/design-figma.json` 或 `.raws/design-figma.md`
-  - API 接口文档 → `.raws/api-spec.json` 或 `.raws/api-spec.md`
-  - 其他资料 → `.raws/<描述性名称>.<扩展名>`（使用小写 kebab-case，禁止空格）
-- **出口门禁**：所有必要的上下文资料已按规范落盘。向用户确认是否进入 `Proposal` 阶段。
+- **Agent 动作**：先读取 `zsk.config.yaml.sources.*`，确认每类资源从哪里来、写到哪里；配置缺失或不理解时必须向用户确认。
+- **`.raws/` 推荐命名**（与 `zsk.config.yaml` 模板一致）：
+  - SRS / 原始需求 → `.raws/SRS.md`
+  - Figma 索引 → `.raws/FIGMA-INDEX.md`
+  - API 契约 → `.raws/api-contracts/`
+  - 原始测试用例 / 提测测试包 → `.raws/testing/`
+  - 设计快照 → `.raws/design-assets/{module}/{snapshot}/`
+- **同步规则**：`kind: local` 只检查存在性；`kind: script` 由命令更新 `output`；`kind: skill` 由对应 AI skill / MCP / Computer Use 获取后写入 `output`，并更新 `.raws/manifest.json`。
+- **出口门禁**：必要资源已按 `zsk.config.yaml` 落盘或登记为待同步；`.raws/manifest.json` 已反映当前状态；向用户确认是否进入 `Proposal` 阶段。
 
 ### Node 2: Proposal (提案阶段)
 - **目标**：对齐业务意图和范围边界。
@@ -84,7 +87,7 @@ triggers:
 
 ### Node 7: Review (多视角审查)
 - **目标**：提高代码交付质量，排查隐患。
-- **Agent 动作**：参照 `zsk:reviewing` 技能的四阶段流程（Scope Drift → Two-Pass → Test Coverage → Confidence Verdict），扮演多视角 Sub-Agent 执行审查。
+- **Agent 动作**：参照 `zsk:reviewing` 技能的五阶段流程（Scope Drift → Sub-Agent Plan → Core Review → Test Coverage → Severity Verdict），按不同专业视角拆分 Sub-Agent 审查，并由主 Agent 汇总。
 - **输出产物**：最终给出以下三种评估之一：
   - 🟢 **绿灯 (Green)**：无阻碍性问题，进入 Node 8 Verify。
   - 🟡 **黄灯 (Yellow)**：存在建议项，列出清单，由用户决定是否修复后再 Review，或豁免放行。
@@ -95,7 +98,7 @@ triggers:
 - **目标**：以客观证据逐条验证 `spec.md` 中所有 AC 均已满足。
 - **Agent 动作**：
   1. 从 `spec.md` 提取所有 `AC-XXX` 编号，逐条核对，输出：`AC-XXX: [PASS / FAIL] — 证据：<命令输出 / 截图 / 日志片段>`
-  2. 运行 `SYSTEM-SPEC.md § NFR 基线` 中所有命令并展示 Exit code（如 `pnpm typecheck`、`pnpm lint`、`pnpm build`）。
+  2. 运行 `SYSTEM-SPEC.md § NFR 基线` / `project-config.md` 中声明的命令并展示 Exit code（如 `{{config.scripts.type_check}}`、`{{config.scripts.lint}}`、`{{config.scripts.build}}`）。
   3. 若环境允许，调用高级工具（如 `Figma MCP` 进行 UI 还原度比对，或 `Computer Use` 模拟浏览器验证用户流）。
 - **出口门禁**：所有 AC 状态为 `PASS` 且 NFR 命令 Exit code = 0。任一 AC 为 `FAIL`，禁止进入 Node 9，回退 Node 6 修复。
 

package/sdlc/task/SKILL.md

@@ -65,7 +65,7 @@ proposal → spec → design → coding → reviewing → verify → archive
 | 变更类型 | 用哪份模板 | 独特纪律 |
 | --- | --- | --- |
 | **Feature（通用）** | [`zsk:task-structure`](../task-structure/SKILL.md) + 自定义 | 两级结构 + FR 全覆盖 |
-| **Feature（组件/前端）** | [`frontend:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md) | 7 类强制任务 |
+| **Feature（组件/前端）** | [`zsk:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md) | 7 类强制任务 |
 | **Bugfix** | [`zsk:bugfix-tasks`](../bugfix-tasks/SKILL.md) | TDD 强制（Red-Green-Regression）+ 置信度三问 |
 | **Refactor** | [`zsk:refactor-tasks`](../refactor-tasks/SKILL.md) | 行为不变 + 小步原子 + Parallel Change（大） |
 | **Maintenance**（依赖升级 / CVE） | 复用 Bugfix 模板（DoR 豁免 TDD） | 升级范围 + 回归覆盖 |
@@ -101,7 +101,7 @@ proposal → spec → design → coding → reviewing → verify → archive
 | 位置 | 内容 |
 | --- | --- |
 | `SYSTEM-SPEC.md` | 项目宪法级规约 |
-| `project-config.yaml`（CLI init 产出） | 占位符配置 |
+| `project-config.md` | 技术栈、质量阈值、脚本命令等 `{{config.*}}` 占位符配置 |
 | `docs/system/adrs/` | 已决策的架构选择 |
 | `zsk:quality` / `zsk:frontend` 等 | 项目执行规范 |
 

package/sdlc/task-evidence/SKILL.md

@@ -48,7 +48,7 @@ triggers:
 - 未覆盖的 FR = DoD 未达 = 不可合并
 - 编号引自 `spec.md`，矩阵只复制不自造
 
-> 前端项目 NFR 常见基线（CWV / WCAG / 三语 / 浏览器矩阵）见 [`frontend:nfr-web`](../../frontend/nfr-web/SKILL.md)
+> 前端项目 NFR 常见基线（CWV / WCAG / 三语 / 浏览器矩阵）见 [`zsk:nfr-web`](../../frontend/nfr-web/SKILL.md)
 
 ## 2. AC 勾选（BDD 场景验证）
 
@@ -81,7 +81,27 @@ triggers:
 - ❌ "截图在飞书 / 微信"（链接会失效）
 - ❌ "大概这样"（无具体数据）
 
-## 3. 校验记录（门禁证据表）
+## 3. 测试资产追溯矩阵
+
+> 目标是证明测试用例与原始资源、设计文档匹配，而不是只证明“跑过测试”。
+
+```md
+## 测试资产追溯矩阵
+
+| 来源 | 原始编号 / 路径 | 覆盖的 FR/AC/Scenario | 派生用例 | 自动化 / 人工证据 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| `.raws/testing/...` |  |  |  |  | TODO |
+| `spec.md` | AC-1 |  |  |  | TODO |
+| `design.md` | 关键流程 / 分支 |  |  |  | TODO |
+```
+
+规则：
+
+- `.raws/testing` 中每个原始用例都必须有映射；未映射即缺口。
+- `design.md` 的状态机、错误流、权限流、数据流分支必须有测试或人工验证证据。
+- 场景覆盖目标为 100%；不足项必须写入风险与豁免。
+
+## 4. 校验记录（门禁证据表）
 
 > 每个门禁一行，**每行必须有证据链接**。
 
@@ -98,7 +118,7 @@ triggers:
 | 安全（依赖扫描） | ✅ | {audit 输出} |
 ```
 
-> 前端项目额外：视觉回归 / a11y / i18n / 性能（Lighthouse）/ 包体积（Bundle Analyzer）— 见 [`frontend:nfr-web`](../../frontend/nfr-web/SKILL.md)
+> 前端项目额外：视觉回归 / a11y / i18n / 性能（Lighthouse）/ 包体积（Bundle Analyzer）— 见 [`zsk:nfr-web`](../../frontend/nfr-web/SKILL.md)
 
 ### 门禁类别（按变更类型）
 
@@ -114,7 +134,7 @@ triggers:
 | 回归测试 | — | ✅（必须） | — |
 | Characterization | — | — | ✅（必须） |
 
-## 4. Refactor 专用：行为不变对照
+## 5. Refactor 专用：行为不变对照
 
 > Refactor 额外需要 before/after 对照证据。
 
@@ -131,7 +151,7 @@ triggers:
 | 公开接口 | {列} | {列} | 无新增 / 删除 |
 ```
 
-## 5. Bugfix 专用：复现对照
+## 6. Bugfix 专用：复现对照
 
 > Bugfix 额外需要 before（复现）/ after（修复）对照证据。
 
@@ -167,7 +187,7 @@ triggers:
 ## 何时填
 
 - 任务执行中：校验记录**随做随填**
-- 交付前：AC 勾选 + FR 覆盖矩阵**汇总填完**
+- 交付前：AC 勾选 + FR 覆盖矩阵 + 测试资产追溯矩阵**汇总填完**
 - 审计时：整份表作为 verify 阶段的输入
 
 ## 反模式（禁止）

package/sdlc/task-structure/SKILL.md

@@ -116,7 +116,7 @@ triggers:
 
 **通用变更**：按"事实源对齐 / 核心实现 / 测试 / 质量门禁准备"四类组织。
 
-**组件 / 前端**（强制 7 类）：见 [`frontend:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md) — 事实源对齐 / Props / UE-MCP / UE 状态 / 测试 / 视觉回归 / 质量门禁。
+**组件 / 前端**（强制 7 类）：见 [`zsk:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md) — 事实源对齐 / Props / UE-MCP / UE 状态 / 测试 / 视觉回归 / 质量门禁。
 
 **Bugfix**：TDD 四步（Red / Green / Regression / Evidence）— 见 [`zsk:bugfix-tasks`](../bugfix-tasks/SKILL.md)。
 

package/sdlc/verify/SKILL.md

@@ -73,8 +73,9 @@ Verify 阶段至少产出以下四类结果：
 
 1. FR / NFR 覆盖矩阵
 2. AC 逐条验收记录
-3. 门禁校验记录
-4. 最终结论：`PASS / PASS_WITH_CONCERNS / FAIL`
+3. 测试资产追溯与场景覆盖报告
+4. 门禁校验记录
+5. 最终结论：`PASS / PASS_WITH_CONCERNS / FAIL`
 
 ## 变更类型差异
 
@@ -103,7 +104,18 @@ Verify 阶段至少产出以下四类结果：
 - 手工录屏 / 截图
 - 报告 / 日志 / 业务记录
 
-### 3. 门禁记录
+### 3. 测试资产追溯与场景覆盖
+
+必须核对：
+
+- `.raws/testing` 原始用例是否全部映射到模块 `module.yaml`
+- 派生测试用例是否覆盖 `spec.md` 的 Scenario / AC
+- 自动化测试是否覆盖 `design.md` 的关键流程、错误路径、状态分支
+- 场景覆盖率是否达到 100%
+
+若未达到 100%，Verify 结论最高只能是 `PASS_WITH_CONCERNS`；P0/P1 场景缺失时必须 `FAIL`。
+
+### 4. 门禁记录
 
 至少覆盖与本次变更相关的门禁，例如：
 
@@ -113,7 +125,7 @@ Verify 阶段至少产出以下四类结果：
 - 构建 / 制品
 - 安全 / 性能 / 可访问性 / 合规
 
-### 4. 例外与风险
+### 5. 例外与风险
 
 不能通过的项必须明确：
 
@@ -153,6 +165,8 @@ Verify 阶段至少产出以下四类结果：
 - [ ] 完整性、正确性、一致性三维都已检查
 - [ ] FR / NFR 覆盖矩阵完整
 - [ ] AC 已逐条验收并附证据
+- [ ] 原始测试资产、派生用例、自动化测试与设计分支已追溯
+- [ ] 场景覆盖率达到 100%，或缺口/风险/豁免已记录
 - [ ] 相关门禁记录齐全
 - [ ] 结论与证据一致，无"口头通过"
 - [ ] 已知风险已单独列出

package/system/project-constraints-template/SKILL.md

@@ -4,7 +4,7 @@ description: Project constraints template for new-project bootstrap — captures
   import origins, forbidden libraries/patterns, required wrappers, naming
   conventions, quality gates, branch/release conventions in one SYSTEM-SPEC
   chapter. The project-side constitutional constraint table, complementary to
-  project-config.yaml (mechanical values).
+  project-config.md (mechanical values).
 category: resource
 domain: system
 tier: optional