@qilitt-mickey/vue3-temp-skill 1.1.30 → 1.1.32

package/README.md

@@ -44,6 +44,27 @@ Node.js >= 22.12.0
 npx @qilitt-mickey/vue3-temp-skill@latest install all
 ```
 
+### 设计落地管控（在业务项目根目录）
+
+业务项目内写入 `.handoff/handoff.json` 后：
+
+```bash
+# 初始化 session（记录 git baseline）
+npx @qilitt-mickey/vue3-temp-skill handoff init --project ./my-vue-app --file .handoff/handoff.json
+
+# 落地完成后机器闸门（步骤 + JSON 规格）
+npx @qilitt-mickey/vue3-temp-skill handoff check --project ./my-vue-app --require-session
+```
+
+源码开发时可直接：
+
+```bash
+node scripts/handoff-session-init.mjs --project <业务项目> --file .handoff/handoff.json
+node scripts/handoff-governance.mjs --project <业务项目> --require-session
+```
+
+详见 `references/handoff-governance.md`。
+
 | 目标 | 说明 |
 |------|------|
 | 个人 Skill 目录 | 安装器写入当前 AI 环境支持的 Skill 目录 |

package/SKILL.md

@@ -17,7 +17,10 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 |------|------|
 | `python scripts/match.py "<需求>"` | **运行时匹配器**（AI 调用）：输出命中模块、同批加载、闸门项、文件清单 |
 | `python scripts/match.py --batch` | 批量测试 15 个典型场景 |
-| `npm run check` | **发布前全量检查**（5 项任一失败即中断） |
+| `npm run check` | **发布前全量检查**（skill 包结构，5 项） |
+| `node scripts/handoff-governance.mjs --project <业务项目>` | **设计落地管控闸门**（步骤 + JSON 规格） |
+| `vue3-temp-skill handoff init --project <业务项目> --file .handoff/handoff.json` | 初始化 `.handoff/session.json`（npm/npx 入口） |
+| `vue3-temp-skill handoff check --project <业务项目> --require-session` | 设计落地完成前必跑 |
 | `npm run validate` | 结构校验：frontmatter、路由表一致性、孤立模块、交叉引用 |
 | `npm run audit` | 命中精度审计：关键词重叠、盲区、模块评分、边界冲突 |
 | `npm run content` | 内容可用性审计：样板完整性、Must-do 清单 |
@@ -77,7 +80,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 ## 设计落地（handoff）
 
-设计技能每次产出时**始终自动附加 `design-handoff/v1` JSON**。本技能检测到 JSON 后**强制加载** `references/design-handoff.md`，按 C/T/F/Co/S/P 六步全流程执行（配置→令牌→框架→共享组件→样式→页面），**任一步跳过 = 硬失败**。执行完毕后**强制加载** `references/design-verify.md` 逐项验证还原度（区域级 + 逐属性 CSS 校验）。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。用户无需提及「JSON」或「handoff」——这是两技能间的自动协议。完整规则与逐项清单见 `design-handoff.md`，验证流程见 `design-verify.md`。
+设计技能每次产出时**始终自动附加 `design-handoff/v1` JSON**（含 **`structureRequirements` + `interactionSpecs`**）。本技能检测到 JSON 后**强制加载** `design-handoff.md` + `handoff-governance.md`，按 C/T/F/Co/S/P 执行。完成后执行 design-verify，并运行 **`vue3-temp-skill handoff check --project <业务项目> --require-session`**（或 `node scripts/handoff-governance.mjs --project <业务项目> --require-session`）。**lint 通过 ≠ 设计落地完成**。
 
 ### 项目级模式 vs 单页模式
 
@@ -123,7 +126,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
 | **启用精简模板已删的 addon（装包 + 改配置）** | `references/addon-enable.md`（与功能模块同读） |
 | 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（逐文件修改清单）+ `design-verify.md`（还原度验证）+ `design-system.md`（项目设计系统说明） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md` + `references/handoff-governance.md` + `design-verify.md` + `design-system.md` |
 | **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-handoff.md` 1:1 还原要求（F1-F14 / P1-P7） |
 
 ### 标准业务面
@@ -223,8 +226,9 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 ## 工作流
 
 1. **需求分析**：列出功能模块 ID（不含 `code-quality`）
-2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；**检测 design-handoff/v1 JSON 是否存在** — 若存在，强制加载 `design-handoff`（逐文件修改清单，含 C/T/F/Co/S/P 全流程 + 共享组件映射 + 项目级模式）+ `design-verify`（还原度验证）+ `design-system.md`，并按设计产出优先级执行
-3. **模式判断**：有 handoff JSON 时，读取 `meta.transformScope`：
+2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；**检测 design-handoff/v1 JSON** — 若存在，强制加载 `design-handoff` + **`handoff-governance`** + `design-verify` + `design-system.md`
+3. **handoff 初始化**：有 JSON 时 → `vue3-temp-skill handoff init --project <业务项目>` → 输出规范识别回执
+4. **模式判断**：有 handoff JSON 时，读取 `meta.transformScope`：
    - `project` → 进入**项目级模式**：先扫描 `src/router/modules/` 构建页面清单，输出「待改造页面清单」供用户确认
    - `single-page` 或未设置 → 单页模式，仅处理当前页面
 4. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
@@ -233,10 +237,11 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 单页模式：C/T/F/Co/S + 当前页面 P 步骤
    - 项目级模式：C/T/F/Co/S（全局一次） + 逐页面执行 P 步骤，标记完成状态
    - **有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
-7. **设计还原度验证**：有 handoff JSON 时必须执行，加载 `design-verify.md` 按其流程逐区域逐元素对照设计规范验证（10.1-10.7 区域级 + 10.8 逐属性 CSS 校验），输出「设计还原度验证报告」+「逐属性 CSS 校验报告」，未通过项必须修正
-8. **功能完整性核查**：有 handoff JSON 时必须执行，按 `design-handoff.md` 第十一章逐项核查功能是否正常（框架/共享组件/页面），样式改造不得破坏原有功能，发现问题立即修正
-9. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（项目级模式需校验全页面完成度 + 共享组件修改 + 设计还原度 + 功能完整性）
-10. **输出**：变更说明（含已改配置文件列表）+ 设计还原度验证报告 + 逐属性 CSS 校验报告 + 功能完整性核查报告 + 待确认项；**项目级模式未全部完成时，输出进度 + 待改造页面清单 + 「继续」指令提示**
+7. **设计还原度验证**：有 handoff 时必须执行 design-verify，落盘 `.handoff/verify-report.json`
+8. **handoff 管控闸门**：`vue3-temp-skill handoff check --project <业务项目> --require-session` **必须 exit 0**
+9. **功能完整性核查**：有 handoff 时按 design-handoff 第十一章
+10. **code-quality**：lint + type-check + 硬失败表
+11. **输出**：变更说明 + verify 报告 + **handoff 管控结果**
 
 ### 最终回复结构
 
@@ -248,8 +253,9 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 - 闸门：已执行 code-quality（生成后）
 - 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表→详情(如适用) / 列表布局(如适用) / 风格 / addon启用(如适用) → 通过 | 已修正：…
 - 硬失败：无 | 已拦截并修正：…
-- handoff 落地（如有 JSON）：C/T/F/Co/S/P 全流程已执行 → 通过 | 未完成项：…（硬失败）
-- 还原度验证（如有 JSON）：design-verify.md 区域级 + 逐属性校验已执行 → 通过 | 偏差项：…（已修正 / 待确认）
+- handoff 落地（如有 JSON）：C/T/F/Co/S/P 全流程 → 通过 | 未完成项：…
+- handoff 管控：`vue3-temp-skill handoff check` → 通过 | 失败：…
+- 还原度验证（如有 JSON）：design-verify + verify-report.json → 通过 | 偏差项：…
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
 

package/bin/cli.js

@@ -251,6 +251,11 @@ function installSkills(targetKey, projectDir) {
     copyDir(refsSrc, path.join(dest, "references"));
   }
 
+  const scriptsSrc = path.join(SKILL_DIR, "scripts");
+  if (fs.existsSync(scriptsSrc)) {
+    copyDir(scriptsSrc, path.join(dest, "scripts"));
+  }
+
   // Cursor：清理旧版 rules/*.mdc，避免与 skills 重复
   if (cfg.legacyRulesFile) {
     const legacy = cfg.legacyRulesFile(projectDir);
@@ -337,6 +342,8 @@ ${bold("命令:")}
   update [target]     更新已安装的技能（默认更新全部已安装目标）
   uninstall [target]  卸载技能（默认卸载全部已安装目标）
   list                查看已安装的目标和版本
+  handoff init        初始化业务项目 .handoff/session.json
+  handoff check       设计落地管控闸门（步骤 + JSON 规格）
 
 ${bold("目标 (target):")}
   cursor       → Cursor          ~/.cursor/skills/
@@ -370,8 +377,9 @@ ${bold("示例:")}
   ${dim("# 查看已安装情况")}
   npx @qilitt-mickey/vue3-temp-skill list
 
-  ${dim("# 卸载")}
-  npx @qilitt-mickey/vue3-temp-skill uninstall cursor
+  ${dim("# 设计落地管控（在业务项目根目录执行）")}
+  npx @qilitt-mickey/vue3-temp-skill handoff init --project ./my-app --file .handoff/handoff.json
+  npx @qilitt-mickey/vue3-temp-skill handoff check --project ./my-app --require-session
 `);
 }
 
@@ -591,6 +599,45 @@ function cmdList() {
   }
 }
 
+function cmdHandoff(sub, args, projectDir) {
+  const proj = projectDir || process.cwd();
+  const fileIdx = args.indexOf("--file");
+  const handoffFile =
+    fileIdx !== -1 ? path.resolve(proj, args[fileIdx + 1]) : path.join(proj, ".handoff", "handoff.json");
+  const requireSession = args.includes("--require-session");
+  const scriptDir = path.join(SKILL_DIR, "scripts");
+
+  if (sub === "init") {
+    const script = path.join(scriptDir, "handoff-session-init.mjs");
+    try {
+      execSync(`"${process.execPath}" "${script}" --project "${proj}" --file "${handoffFile}"`, {
+        stdio: "inherit",
+      });
+    } catch (e) {
+      process.exit(e.status ?? 1);
+    }
+    return;
+  }
+
+  if (sub === "check") {
+    const script = path.join(scriptDir, "handoff-governance.mjs");
+    const extra = requireSession ? " --require-session" : "";
+    try {
+      execSync(`"${process.execPath}" "${script}" --project "${proj}"${extra}`, {
+        stdio: "inherit",
+      });
+    } catch (e) {
+      process.exit(e.status ?? 1);
+    }
+    return;
+  }
+
+  console.error(red("✗ handoff 子命令: init | check"));
+  console.error(dim("  handoff init  --project <dir> [--file .handoff/handoff.json]"));
+  console.error(dim("  handoff check --project <dir> [--require-session]"));
+  process.exit(1);
+}
+
 // ============================================================
 // 入口
 // ============================================================
@@ -626,6 +673,9 @@ function main() {
     case "list":
       cmdList();
       break;
+    case "handoff":
+      cmdHandoff(target, args.slice(2), projectDir);
+      break;
     default:
       // 兼容旧用法：直接传 target 名当作 install
       if (TARGETS[command] || command === "all") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.30",
+  "version": "1.1.32",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"
@@ -36,6 +36,8 @@
     "gen:index": "node scripts/generate-index.mjs",
     "gen:index:write": "node scripts/generate-index.mjs --write",
     "scaffold": "node scripts/scaffold-module.mjs",
+    "handoff:init": "node scripts/handoff-session-init.mjs",
+    "handoff:check": "node scripts/handoff-governance.mjs",
     "postpublish": "echo 'Published @qilitt-mickey/vue3-temp-skill to npmjs.org'"
   },
   "keywords": [

package/references/code-quality.md

@@ -13,9 +13,10 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 
 1. 重读本文件
 2. 列出本轮改动路径，对照下方清单；**硬失败表命中则先改代码再继续**
-3. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`（无脚本则 `pnpm lint` / `pnpm exec eslint . --fix`；`pnpm exec vue-tsc --noEmit`）
-4. 失败则修代码并重跑，直至通过或写明阻塞
-5. 最终回复追加：
+3. **有 handoff session 时**（`.handoff/session.json` 存在）：必跑 `vue3-temp-skill handoff check --project <业务项目> --require-session` → **exit 0 才能声称设计落地完成**（见 `handoff-governance.md`）
+4. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`
+5. 失败则修代码并重跑，直至通过或写明阻塞
+6. 最终回复追加：
 
 ```markdown
 ## 代码质量审查
@@ -23,6 +24,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - 改动文件：`path/a`、`path/b`、…
 - 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表→详情 ✅或N/A / 列表布局 ✅或N/A / 风格 ✅
 - 硬失败：无 | 已拦截并修正：…
+- handoff 管控（如有 session）：`vue3-temp-skill handoff check` → 通过 | 失败项：…
 - 已修正：…（无则写「无」）
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
@@ -128,6 +130,17 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 - [ ] 无遗漏页面（对照路由清单逐一核对）
 - [ ] 所有页面的多余元素（「展示列表」「左侧按钮...」等）均已清除
 
+#### 设计落地管控（有 `.handoff/session.json` 时必须执行）
+
+> 详见 `references/handoff-governance.md`。lint/type-check **不能**代替本段。
+
+- [ ] 动手前已 `handoff-session-init`，`.handoff/session.json` 含完整 handoff + baseline
+- [ ] handoff JSON 含 `structureRequirements` + `interactionSpecs`
+- [ ] C/T/F/Co/S/P 全流程已执行（`handoff-step-check` 通过）
+- [ ] 代码与当次 JSON 一致（`handoff-spec-check` 通过）
+- [ ] 已落盘 `.handoff/verify-report.json`（`overallPass: true`）
+- [ ] **`vue3-temp-skill handoff check --project <业务项目> --require-session` → exit 0**
+
 #### 设计还原度验证（有 handoff JSON 时必须执行）
 
 > 验证依据：设计 skill 的规范文件（design-tokens.md / unified-framework.md / list-page.md / component-spec.md）
@@ -141,8 +154,10 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 - [ ] **细节项还原度**：图标大小 16px、分隔线 #F0F0F0、hover 文字加深不变浅、行高正确、字重正确、圆角统一、阴影自然、更多按钮有箭头、操作列有竖分隔线、页签下划线居中、操作列 sticky、选择列 48px、状态标签颜色对应、卡片有阴影，共 15 项已逐项检查
 - [ ] **令牌溯源检查**：颜色/尺寸/间距均通过 CSS 变量传递，变量值与 design-tokens.md 一致，无裸 hex/px 值
 - [ ] **元素清理检查**：设置按钮、展示列表标题、示例按钮、操作列多余图标等已全部移除
-- [ ] **已输出「设计还原度验证报告」**（格式见 `design-verify.md` 10.7），包含整体还原度、各层通过率、偏差项及修正方案
-- [ ] **逐属性 CSS 校验已执行**（`design-verify.md` 10.8）：从设计源文件提取 CSS 属性清单，逐条比对项目代码，不一致项已修正并回读校验通过
+- [ ] **已输出「设计还原度验证报告」**（格式见 `design-verify.md` 10.7），包含整体还原度、各层通过率、偏差项及修正方案
+- [ ] **CSS 冲突检测已执行**（`design-verify.md` 10.7.5）：选择器重复扫描完成，无意冲突已消除，导入顺序已验证，新增 CSS 文件已注册
+- [ ] **已输出「CSS 冲突检测报告」**（格式见 `design-verify.md` 10.7.5.5），包含扫描范围、重复选择器明细、导入顺序验证结果
+- [ ] **逐属性 CSS 校验已执行**（`design-verify.md` 10.8）：从设计源文件提取 CSS 属性清单，逐条比对项目代码，不一致项已修正并回读校验通过
 - [ ] **已输出「逐属性 CSS 校验报告」**（格式见 `design-verify.md` 10.8.5），包含校验范围、偏差明细、待确认项
 - [ ] **设计落盘范围**：设计产出 HTML 未写入项目文件，设计规范未另存到非业务目录，所有修改只在 src/ 等业务代码中
 - [ ] **功能完整性核查**：样式改造后原有功能全部正常（框架层/共享组件层/页面层均已逐项核查，无按钮失效、事件丢失、数据绑定断裂等功能回归问题）

package/references/design-handoff.md

@@ -82,6 +82,8 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ## 规范识别回执（动手前必出）
 
+> 动手前须 `handoff-session-init` 写入 `.handoff/session.json`（见 `handoff-governance.md`）。
+
 ```markdown
 ## 规范识别回执
 - 来源形态：design-handoff/v1 JSON
@@ -90,9 +92,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 - 几何：header {n} / tabs {n} / margin {n}
 - 主色阶：完整 10 级
 - 侧栏：{shell.sidebar}
-- 结构要求：{structureRequirements.frameworkShell.header.length} 项
-- 交互要求：{Object.keys(interactionSpecs).length} 类
-- 将改文件：platform-config.json / design-tokens.scss / navbar / sidebar / tabs / app-main / element-plus.scss / dark.scss / 业务页面
+- 顶栏元素（JSON）：{structureRequirements.frameworkShell.header 逐项列出}
+- 交互规格（JSON）：tabsActive.underline / tableOperate.showIcon / menuActive.fullWidth 等
+- 将改文件：platform-config.json / design-tokens.scss / navbar / sidebar / tabs / ReTableBar / ReTableOperate / element-plus.scss / 业务页面
 ```
 
 ---
@@ -286,16 +288,16 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 | **修改内容** | 1. 分页布局：左右两段式（左侧总数 + 每页条数选择；右侧页码 + 跳转）<br>2. 默认每页条数：10<br>3. 可选条数：10/20/50<br>4. 跳转输入框宽度 48px<br>5. 激活页按钮：品牌色背景 + 白色文字 |
 | **验证** | 分页样式与设计规范一致 |
 
-### Co.9 侧栏菜单激活态 — 实色底修正
+### Co.9 侧栏菜单激活态
 
 | 项 | 说明 |
 |----|------|
 | **文件** | `src/styles/sidebar.scss` |
-| **设计规范** | unified-framework.md §2 Sider：激活项为实色品牌底 + 左侧 3px 指示条 + 白色文字 |
-| **修改内容** | 1. 激活态背景：`var(--sidebar-menu-active-bg, var(--brand-primary))`（实色，非 8% 透明）<br>2. 左侧指示条：`::before` 伪元素，width 3px，height 100%，背景 `var(--sidebar-active-indicator, var(--brand-primary))`<br>3. 激活态文字颜色：`var(--sidebar-menu-active-text, #fff)`（白色）<br>4. 确保 `--sidebar-menu-active-bg` 令牌值为实色，而非 `color-mix(... 8%, transparent)` |
-| **验证** | 侧栏激活菜单项为实色品牌底 + 左侧 3px 指示条 + 白色文字 |
+| **JSON 来源** | `interactionSpecs.menuActive` |
+| **修改内容** | 按 JSON 实现：`fullWidth` / `marginX` / `radius` / `background` / `indicator` / `textColor` |
+| **验证** | sidebar 激活态与 JSON 一致 |
 
-> ⚠️ 注意：当前模板 `sidebar.scss` 中激活态背景是 `color-mix(in srgb, var(--brand-primary) 8%, transparent)`，这与设计规范的「实色底」不符。Co9 步骤必须将其修正为实色。
+> ⚠️ **以当次 JSON 为准**：本规范默认 `fullWidth:false` + `marginX:8` + `radius:6` + `solid-brand` + `left-before`（见 unified-framework §6.13–6.16）。若 JSON 不同，按 JSON 实现，不得硬套「通栏实色底」。
 
 ### Co.10 navbar — 折叠按钮垂直居中
 
@@ -498,49 +500,58 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ## 八、硬失败（任一项命中 = 落地失败，必须修正）
 
+> **硬失败分两类**（详见 `handoff-governance.md`）：
+> - **流程类**：步骤跳过、无 session、无 verify 报告、lint 代替管控 — **与设计无关，永远检查**
+> - **规格类**：代码与**当次** handoff JSON 的 `structureRequirements` / `interactionSpecs` 不一致 — **随设计变，不写死在本表**
+
+### 8.1 流程硬失败（机器可拦）
+
+| 类别 | 条件 | 处理 |
+|------|------|------|
+| 管控 | 有 handoff 但未 `handoff-session-init` | 硬失败：先写 `.handoff/session.json` |
+| 管控 | `handoff-step-check` 任一步（C/T/F/Co/S）文件无 diff | 硬失败：补全该步骤，禁止跳过 Co |
+| 管控 | 只改 C/T 未改 Co 共享组件即声称完成 | 硬失败：执行 Co1-Co12 |
+| 管控 | 未执行 `vue3-temp-skill handoff check --require-session` | 硬失败：机器闸门 exit 0 后才能完成 |
+| 管控 | 以 `lint:fix` / `type-check` 通过代替 handoff 管控 | 硬失败：二者是必要非充分条件 |
+| 管控 | 有 handoff 但未落盘 `.handoff/verify-report.json` | 硬失败：design-verify 报告必须落盘 |
+| 项目级 | 项目级模式下未扫描全部路由即开始改造 | 硬失败：先完成 Step 0 页面清单初始化 |
+| 项目级 | 项目级模式下未完成全部页面即声称完成 | 硬失败：必须告知进度和剩余页面 |
+| 设计落地 | 设计 HTML / 规范文档被写入项目非业务目录 | 硬失败：撤销，设计修改只落在 src/ 等业务代码 |
+| 功能回归 | 样式改造后原有功能被破坏 | 硬失败：修复后重新验证 |
+| 逐属性校验 | 10.8 发现不一致且未修复 | 硬失败：零差异后才能声明完成 |
+| CSS 冲突 | 10.7.5 未执行就进 10.8 | 硬失败：先冲突检测 |
+
+### 8.2 规格硬失败（读当次 JSON + spec-check）
+
+| 类别 | 条件 | 处理 |
+|------|------|------|
+| JSON | handoff 缺少 `structureRequirements` 或 `interactionSpecs` | 硬失败：要求设计 skill 补全 JSON |
+| 框架-顶栏 | 顶栏元素与 `structureRequirements.frameworkShell.header` 不一致 | 硬失败：按 JSON 逐项对齐 |
+| 框架-顶栏 | `interactionSpecs.languageSwitch.mode=inline-text` 但仍是下拉框 | 硬失败：改内联文字 |
+| 框架-侧栏 | 与 `interactionSpecs.menuActive` 不一致（fullWidth/radius/background） | 硬失败：按 JSON 修正 |
+| 框架-页签 | 与 `interactionSpecs.tabsActive` 不一致（underline/fontWeight 等） | 硬失败：按 JSON 修正 |
+| 共享组件 | 与 `interactionSpecs.tableOperate` 不一致 | 硬失败：按 JSON 修正 ReTableOperate |
+| 共享组件 | 与 `interactionSpecs.tableToolbar` 不一致 | 硬失败：按 JSON 修正 ReTableBar |
+| 页面 | 与 `structureRequirements.moduleComposition` 不一致 | 硬失败：补全区域结构 |
+| 页面 | `structureRequirements.elementHideList` 项仍在代码中 | 硬失败：隐藏/删除 |
+| 页面 | 状态 Tag 与 `interactionSpecs.statusTag` 不一致 | 硬失败：按 JSON 修正 |
+| 页面 | `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 F1-F27 / P1-P7 + JSON 补充 |
+
+### 8.3 配置 / 令牌 / 样式硬失败（与 JSON 字段对照）
+
 | 类别 | 条件 | 处理 |
 |------|------|------|
 | 配置 | 只改主色/tokens，未改 Theme / Version | 硬失败：补全 C1-C8 |
 | 配置 | 设计 `sidebar=dark-gradient` 但 `Theme` 仍为 `light` | 硬失败：改为 `default` 并 `Version++` |
 | 配置 | 未写入 `shell.showModel` | 硬失败：按 JSON 补写 |
 | 配置 | `primaryScale` 未写入 `--primary-0..9` | 硬失败：补全 10 级色阶 |
-| 令牌 | 用 EP 默认错误色 `#F56C6C` 而非令牌引用 | 硬失败：改为 `var(--error-color)` 或对应令牌值 |
+| 令牌 | 用 EP 默认错误色 `#F56C6C` 而非令牌引用 | 硬失败：改为 `var(--error-color)` |
 | 令牌 | 壳层/弹窗写死 px | 硬失败：改 `var(--…)` |
 | 令牌 | 改了 margin 后列表仍用 `100vh` 减顶栏 | 硬失败：迁 flex / `vts-page-card` |
-| 框架-顶栏 | 顶栏元素与设计不一致（多了或少了） | 硬失败：按 `frameworkShell.header` 逐项对齐 |
-| 框架-顶栏 | 语言切换为下拉框（非内联文字） | 硬失败：改为内联文字 |
-| 框架-顶栏 | 设置按钮设计无但代码中还在 | 硬失败：删除或 `display:none` |
-| 框架-侧栏 | 侧栏底部折叠按钮设计无但还在 | 硬失败：隐藏，折叠按钮移至顶部 |
-| 框架-侧栏 | 菜单 hover 出现折叠功能设计无但还在 | 硬失败：禁用该功能 |
-| 框架-侧栏 | 菜单激活态无品牌色底+强调条 | 硬失败：按 `interactionSpecs.menuActive` 补充 |
-| 框架-页签 | 页签横线不居中 | 硬失败：调整下划线位置，确保与文字等宽居中 |
-| 框架-页签 | 首页页签可关闭 | 硬失败：设为不可关闭 |
-| 样式 | 展开收起按钮 hover 文字变浅 | 硬失败：hover 文字色加深或变色，**禁止变淡** |
-| 样式 | 表格行 hover 无品牌色底 | 硬失败：补充 hover 背景色 |
-| 样式 | 卡片/按钮 hover 无浮起效果 | 硬失败：补充 transform + shadow |
-| 样式 | 输入框聚焦无光环 | 硬失败：补充 focus 阴影 |
-| 页面 | 页面无标题区 / 筛选区无容器感 | 硬失败：按 `moduleComposition` 补充 |
-| 页面 | 状态标签样式与设计规范不一致 | 硬失败：按 `component-spec.md` Tag 规范修正 |
-| 页面 | 操作列按钮样式混乱（混用 button/文字链接） | 硬失败：统一为文字链接 + "更多"下拉 |
-| 页面 | 设计中未体现的元素未隐藏 | 硬失败：按元素自查隐藏清单逐项处理 |
-| 页面 | `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 F1-F27 / P1-P7 补充 |
-| 共享组件 | ReTableBar 工具栏按钮样式与设计规范不一致（刷新/密度/列设置尺寸、间距、分隔线） | 硬失败：按 Co2 修正 |
-| 共享组件 | ReTableOperate 操作列按钮有图标（设计规范为纯文字链接） | 硬失败：按 Co5 移除图标，添加竖分隔线 |
-| 共享组件 | 「更多」按钮无下拉箭头（设计规范必须有） | 硬失败：按 Co6 添加下拉箭头 |
-| 共享组件 | 侧栏菜单激活态为 8% 透明底（设计规范为实色底） | 硬失败：按 Co9 修正为实色底 |
-| 共享组件 | 顶栏设置按钮设计无但代码中还在 | 硬失败：按 Co11 删除或 `v-if="false"` |
-| 共享组件 | 折叠按钮未垂直居中 | 硬失败：按 Co10 修正 |
-| 共享组件 | 模块分割线间距与设计规范不一致 | 硬失败：按 Co12 修正各区域 padding 和分割线位置 |
-| 页面清理 | 列表页仍有「展示列表」等多余标题文字 | 硬失败：按 4.4 清单从模板中删除 |
-| 页面清理 | 列表页仍有「左侧按钮可以增加多个」等示例按钮 | 硬失败：按 4.4 清单从模板中删除 |
-| 项目级 | 项目级模式下未扫描全部路由即开始改造 | 硬失败：先完成 Step 0 页面清单初始化 |
-| 项目级 | 项目级模式下未完成全部页面即声称完成 | 硬失败：必须告知进度和剩余页面 |
-| 项目级 | 项目级模式下共享组件未按 Co 步骤修改 | 硬失败：按 Co1-Co12 逐一修正 |
-| 设计落地 | 设计 HTML / 规范文档被写入项目非业务目录 | 硬失败：撤销，设计修改只落在 src/ 等业务代码 |
-| 功能回归 | 样式改造后原有功能被破坏（按钮不能点、分页不工作、搜索失效等） | 硬失败：样式归样式功能归功能，改样式不得破坏原有功能，必须修复后重新验证 |
-| 逐属性校验 | 10.8 逐属性 CSS 校验发现设计值与项目实际值不一致且未修复 | 硬失败：逐条修改至零差异，回读校验通过后才能声明完成 |
-| 逐属性校验 | 设计源文件回读校验有未通过项（修改后未重新回读验证） | 硬失败：重新修复并回读，直到零差异 |
-| 逐属性校验 | 设计变更同步后未执行全量回读校验（只验变更项未验全量） | 硬失败：必须全量回读，防止变更项误改未变项 |
+| 样式 | `interactionSpecs.collapseBtnHover.textFade=true` 违反时 hover 变浅 | 硬失败：hover 加深 |
+| 页面清理 | 列表页仍有「展示列表」等 demo 文案 | 硬失败：按 elementHideList / 4.4 删除 |
+
+> ⚠️ **静态默认值冲突**：F/Co 步骤正文若与当次 JSON / 设计 HTML 矛盾，**以 JSON + 设计 HTML 为准**。
 
 ---
 
@@ -787,9 +798,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 5. **元素自查隐藏**（第四章）
 6. **样式修改**（S1）
 7. **页面代码生成**（P1-P7）
-8. **设计还原度验证** — 加载 `design-verify.md`，执行 10.1-10.7 区域级验证 + 10.8 逐属性 CSS 校验 + 10.9 设计变更同步（如有）
+8. **设计还原度验证** — 加载 `design-verify.md`，执行 10.1-10.7 区域级验证 + 10.7.5 CSS 冲突检测 + 10.8 逐属性 CSS 校验 + 10.9 设计变更同步（如有）
 9. **功能完整性核查**（第十一章）—— 检查功能坏没坏
 10. **code-quality 闸门**
-11. **输出报告**（设计还原度验证报告 + 逐属性校验报告 + 功能完整性核查报告）
+11. **输出报告**（设计还原度验证报告 + CSS 冲突检测报告 + 逐属性校验报告 + 功能完整性核查报告）
 
-> ⚠️ **三条腿走路**：区域级还原度（10.1-10.7）+ 属性级逐条校验（10.8-10.9）+ 功能完整性（第十一章）缺一不可。只改对样式但功能坏了 = 失败；功能正常但样式有偏差 = 也失败；区域级通过但属性级有遗漏 = 同样失败。三者全部通过才算完成。
+> ⚠️ **四条腿走路**：区域级还原度（10.1-10.7）+ CSS 结构级冲突检测（10.7.5）+ 属性级逐条校验（10.8-10.9）+ 功能完整性（第十一章）缺一不可。只改对样式但功能坏了 = 失败；功能正常但样式有偏差 = 也失败；区域级通过但属性级有遗漏 = 同样失败；属性级通过但 CSS 冲突导致生效值不确定 = 同样失败。四者全部通过才算完成。

package/references/design-verify.md

@@ -24,6 +24,8 @@ tags: [handoff, verify, css-audit, design-sync, hard-fail]
     ↓
 10.6-10.7  验证方法 + 区域级验证报告输出
     ↓
+10.7.5     CSS 冲突检测（选择器重复扫描 + 导入顺序验证 + 冲突修复）
+    ↓
 10.8       逐属性 CSS 校验（从设计源文件提取属性 → 逐条比对项目代码 → 回读校验）
     ↓
 10.9       设计变更增量同步（仅设计变更时执行）
@@ -31,6 +33,35 @@ tags: [handoff, verify, css-audit, design-sync, hard-fail]
 
 ---
 
+## 10.0 JSON 驱动验证（优先于静态条文）
+
+> **验证真相源顺序**：当次 handoff JSON（`structureRequirements` + `interactionSpecs`）> 设计 HTML > 设计 skill references > 模板出厂默认值。
+
+1. 读取 `.handoff/session.json` 或会话中的 handoff JSON
+2. 从 JSON 展开**本次验证清单**（非 skill 静态表）：
+   - `frameworkShell.header` → 顶栏元素逐项
+   - `interactionSpecs.tabsActive.underline` → 决定是否检查下划线
+   - `interactionSpecs.tableOperate.showIcon` → 决定是否禁止 icon
+   - `interactionSpecs.menuActive.*` → 侧栏激活 inset/通栏/圆角
+3. 执行 `vue3-temp-skill handoff check --project <业务项目> --require-session`（内含 step-check + spec-check）作为机器预检
+4. 人工/AI 区域验证（10.2–10.5）对照 JSON 展开项，**禁止**用上一版设计的静态预期
+
+### 10.0.1 verify-report 落盘
+
+design-verify 完成后必须写入项目 `.handoff/verify-report.json`：
+
+```json
+{
+  "generatedAt": "<ISO>",
+  "overallPass": true,
+  "specSource": "session.handoff",
+  "layers": { "framework": { "pass": 10, "total": 10 } },
+  "deviations": []
+}
+```
+
+---
+
 ## 10.1 验证原则
 
 1. **对照设计规范，不凭感觉**：每一项都有对应的设计规范来源（unified-framework.md / list-page.md / component-spec.md / design-tokens.md），禁止「大概差不多」
@@ -47,9 +78,9 @@ tags: [handoff, verify, css-audit, design-sync, hard-fail]
 | 折叠按钮位置 | unified-framework.md §3 | 检查折叠按钮是否垂直居中，尺寸是否 40×40px | 垂直居中，40×40px |
 | 侧栏宽度 | unified-framework.md §2 | 检查 `--sidebar-width` / `--sidebar-collapsed-width` | 展开 208px / 折叠 64px |
 | 侧栏背景色 | unified-framework.md §2 | 检查侧栏背景色令牌值 | 深色 #001529 |
-| 侧栏激活态 | unified-framework.md §2 + list-page.md §12 | 检查激活菜单项的背景、文字、指示条 | 实色品牌底 + 白色文字 + 左侧 3px 指示条 |
+| 侧栏激活态 | unified-framework.md §2 + **JSON `interactionSpecs.menuActive`** | 按 JSON fullWidth/radius/background/indicator 检查 |
 | 页签高度 | unified-framework.md §4 | 检查 `--tabs-height` + tabs 实际高度 | 40px |
-| 页签激活态 | unified-framework.md §4 + component-spec.md §5 | line 模式下检查激活页签样式 | 文字品牌色 + font-weight 500 + 底部 2px 强调线，无背景变化 |
+| 页签激活态 | unified-framework.md §4 + **JSON `interactionSpecs.tabsActive`** | 按 JSON：underline=false 则无底线；underline=true 则检查居中 |
 | 内容区背景色 | unified-framework.md §5 | 检查内容区背景色 | #F5F5F5（灰底） |
 | 内容区内边距 | unified-framework.md §5 | 检查 `--layout-content-padding` | 24px |
 
@@ -168,11 +199,110 @@ AI 在执行设计还原度验证时，按以下步骤操作：
 
 ---
 
+## 10.7.5 CSS 冲突检测（逐属性校验前置闸门 — 硬失败）
+
+> 10.8 逐属性校验依赖「项目代码中每个选择器的实际生效值」。如果同一选择器在多个文件重复定义、导入顺序错乱、或特异性冲突，实际生效值不可预测，10.8 比对结果不可靠。
+> **本节必须在 10.8 之前执行，未通过则不允许进入 10.8。**
+
+### 10.7.5.1 选择器重复扫描
+
+扫描项目全部 `src/**/*.scss`、`src/**/*.css`、`src/**/*.vue`（含 `<style>` 块）文件，检测同一选择器在多个文件或同一文件内多次出现的情况。
+
+**检测规则**：
+
+1. 提取每个文件中的全部 CSS 选择器（去掉伪类/伪元素后比对基础选择器）
+2. 按**选择器文本完全匹配**分组
+3. 跨文件出现 ≥2 次 = 重复选择器
+4. 同一文件内出现 ≥2 次 = 文件内重复
+
+**输出重复清单**：
+
+| 选择器 | 出现次数 | 文件列表 | 行号 | 重复类型 |
+|--------|---------|---------|------|---------|
+| .el-menu-item.is-active | 2 | element-plus.scss:573, sidebar.scss:104 | 573, 104 | 跨文件 |
+| .el-table thead th | 2 | element-plus.scss:342, element-plus.scss:566 | 342, 566 | 文件内 |
+
+### 10.7.5.2 重复选择器分类裁定
+
+对每个重复选择器，判定属于以下哪类：
+
+| 类型 | 判定条件 | 处理 |
+|------|---------|------|
+| **有意覆盖** | 后导入文件的选择器特异性 ≥ 前文件，且值确实需要覆盖前者 | ✅ 保留，但必须在选择器上方加注释 `// override: 覆盖 {文件名} 的 {原因}` |
+| **无意冲突** | 两个定义的值矛盾，且覆盖关系不确定 | ❌ 硬失败 — 必须合并为一个定义或删除冗余 |
+| **无害重复** | 两个定义的值完全一致 | ⚠️ 警告 — 删除冗余定义，只保留一个 |
+
+**裁定方法**：
+1. 根据 `index.scss` 的 `@use` 导入顺序确定文件优先级（后导入 = 高优先级）
+2. 对比特异性（ID > class > tag，`!important` 最高）
+3. 若优先级+特异性可以确定唯一胜出者 → 检查胜出值是否与设计规范一致
+4. 若无法确定唯一胜出者 → 硬失败
+
+### 10.7.5.3 导入顺序验证
+
+读取项目全局样式入口文件（通常为 `src/styles/index.scss`），验证 `@use` 导入顺序符合分层约定：
+
+```
+预期顺序（从先到后）：
+1. design-tokens  — 令牌定义（最底层）
+2. theme          — 主题变量
+3. transition     — 过渡动画
+4. button         — 按钮装饰类
+5. element-plus   — EP 组件覆盖（通用层）
+6. sidebar        — 侧栏专属覆盖（高优先级）
+7. dark           — 暗色模式覆盖
+8. vant           — Vant 组件覆盖
+```
+
+**验证规则**：
+1. 实际 `@use` 顺序与预期顺序对比 — 顺序不一致 = 硬失败
+2. 设计落地执行时新增的 CSS 文件是否已注册到 `index.scss` — 未注册 = 硬失败
+3. 新增文件应插入到正确层级位置（通用覆盖在 `element-plus` 附近，专属覆盖在 `sidebar` 附近）— 位置错误 = 硬失败
+
+### 10.7.5.4 冲突修复
+
+检测到硬失败项时，按以下优先级修复：
+
+1. **消除冗余**：同一选择器只在唯一文件中定义，删除其他文件中的重复
+2. **合并定义**：将分散在多文件的同一选择器属性合并到一个文件中
+3. **调整导入顺序**：若覆盖关系需要保留，确保导入顺序正确且添加 override 注释
+4. **提升特异性**：若需覆盖 EP 默认样式，使用更高特异性选择器（如 `.sidebar-container .el-menu-item`）而非 `!important`
+
+**修复后必须重新执行 10.7.5.1-10.7.5.3 确认零冲突。**
+
+### 10.7.5.5 冲突检测报告（输出格式）
+
+```markdown
+## CSS 冲突检测报告
+
+### 扫描范围
+- 文件数：{N}
+- 选择器总数：{total}
+- 重复选择器：{duplicates} 个
+
+### 导入顺序验证
+- index.scss @use 顺序：✅ 正确 / ❌ 错误（{详情}）
+- 新增文件注册：✅ 已注册 / ❌ 未注册（{文件名}）
+
+### 重复选择器明细
+| 选择器 | 类型 | 文件 | 胜出值 | 与设计一致 | 处理 |
+|--------|------|------|--------|-----------|------|
+| .el-menu-item.is-active | 有意覆盖 | element-plus.scss:573, sidebar.scss:104 | sidebar 值 | ✅ | 保留+加注释 |
+| .el-table thead th | 无害重复 | element-plus.scss:342, :566 | — | — | 删除冗余 |
+| .new-selector | 无意冲突 | a.scss:10, b.scss:20 | 不确定 | ❌ | 硬失败→已合并 |
+
+### 硬失败项
+- {如有，列出并说明已修复情况}
+```
+
+---
+
 ## 10.8 逐属性 CSS 校验（设计源文件回读 — 硬失败闸门）
 
 > 10.2-10.7 是「区域级」验证（检查"顶栏高度对不对""筛选区有没有"）。
+> 10.7.5 是「结构级」验证——确保 CSS 无冲突、导入顺序正确、每个选择器有唯一生效值。
 > 本节是「属性级」验证——从设计 reference 源文件中逐行提取每个 CSS 属性，与项目代码逐条比对。
-> **这是消除精度偏差的核心闸门，10.1-10.7 验证通过后必须执行本节，不可跳过。**
+> **这是消除精度偏差的核心闸门，10.1-10.7.5 验证通过后必须执行本节，不可跳过。**
 
 ### 10.8.1 动态发现设计源文件
 

package/references/handoff-governance.md

@@ -0,0 +1,74 @@
+---
+skill: handoff-governance
+description: 设计落地管控 — 流程闸门（步骤不可跳过）+ JSON 规格闸门（当次设计可变）。配合 scripts/handoff-*.mjs 机器执行。
+scope: project
+tags: [handoff, governance, gate, process, spec-check]
+---
+
+# 设计落地管控（handoff-governance）
+
+> **根本原则**：project skill 只规定**固定流水线 + 验收方法**；具体「有没有下划线、有没有设置按钮」写在**当次 handoff JSON** 的 `structureRequirements` / `interactionSpecs` 里，**不写死**在 skill 条文中。
+
+## 三层架构
+
+| 层 | 职责 | 会不会随设计变 |
+|----|------|--------------|
+| **设计 skill** | HTML + handoff JSON（含 structureRequirements / interactionSpecs） | ✅ 每次不同 |
+| **工程 skill** | C/T/F/Co/S/P 固定流程 + F/P/Co 映射 + design-verify 方法 | ❌ 流程不变 |
+| **机器闸门** | `handoff-step-check` + `handoff-spec-check` + verify-report | ❌ 逻辑不变，读当次 JSON |
+
+## 会话文件（项目内）
+
+设计落地**动手前**，AI 必须执行（在**业务项目根目录**）：
+
+```bash
+vue3-temp-skill handoff init --project <业务项目> --file .handoff/handoff.json
+# 或源码开发：
+node <skill>/scripts/handoff-session-init.mjs --project <业务项目> --file .handoff/handoff.json
+```
+
+完成后：
+
+```bash
+vue3-temp-skill handoff check --project <业务项目> --require-session
+```
+
+业务项目内产出（`.handoff/` 目录在**业务仓库**，脚本在 **skill 包**）：
+
+```
+<业务项目>/.handoff/
+  handoff.json       # 设计 JSON 副本
+  session.json       # init 生成
+  verify-report.json # verify 完成后落盘
+```
+
+## 固定流水线
+
+```
+0. handoff init
+1. C → T → F → Co → S → P
+2. design-verify + verify-report.json
+3. handoff check --require-session
+4. lint + type-check
+```
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `vue3-temp-skill handoff init --project <dir> [--file .handoff/handoff.json]` | 初始化 session |
+| `vue3-temp-skill handoff check --project <dir> [--require-session]` | 汇总闸门 |
+| `node scripts/handoff-step-check.mjs --project <dir>` | 仅步骤检查 |
+| `node scripts/handoff-spec-check.mjs --project <dir>` | 仅 JSON 规格检查 |
+
+## verify-report.json 最小形状
+
+```json
+{
+  "generatedAt": "2026-08-27T...",
+  "overallPass": true,
+  "layers": { "framework": { "pass": 10, "total": 10 } },
+  "deviations": [],
+  "specSource": "session.handoff"
+}
+```

package/scripts/cli.mjs

@@ -71,6 +71,16 @@ const commands = {
     file: "scaffold-module.mjs",
     args: "pass",
   },
+  "handoff-init": {
+    desc: "设计落地：初始化业务项目 .handoff/session.json",
+    file: "handoff-session-init.mjs",
+    args: "pass",
+  },
+  "handoff-check": {
+    desc: "设计落地：管控闸门（步骤 + JSON 规格）",
+    file: "handoff-governance.mjs",
+    args: "pass",
+  },
 };
 
 function run(cmd, extraArgs = []) {

package/scripts/handoff-governance.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Handoff governance gate — step check + spec check + optional verify report.
+ *
+ * Usage:
+ *   node scripts/handoff-governance.mjs --project <path>
+ *   node scripts/handoff-governance.mjs --project <path> --require-session
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { parseArgs, readSession, REPORT_FILE } from "./handoff-lib.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const NODE = process.execPath;
+const args = parseArgs(process.argv);
+
+function runScript(name) {
+  const extra = args.skipIfNoSession ? [] : ["--require-session"];
+  return execFileSync(NODE, [path.join(__dirname, name), "--project", args.project, ...extra], {
+    encoding: "utf-8",
+    stdio: "pipe",
+  });
+}
+
+console.log("Handoff 管控闸门\n" + "=".repeat(40));
+
+const session = readSession(args.sessionPath);
+if (!session && !args.skipIfNoSession) {
+  console.error("✗ 无 handoff session，请先 handoff-session-init");
+  process.exit(1);
+}
+
+if (!session) {
+  console.log("无活跃 handoff session — 跳过管控（非设计落地任务）\n");
+  process.exit(0);
+}
+
+const failures = [];
+
+try {
+  console.log(runScript("handoff-step-check.mjs"));
+} catch (e) {
+  failures.push("step-check");
+  if (e.stdout) console.error(e.stdout);
+  if (e.stderr) console.error(e.stderr);
+}
+
+try {
+  console.log(runScript("handoff-spec-check.mjs"));
+} catch (e) {
+  failures.push("spec-check");
+  if (e.stdout) console.error(e.stdout);
+  if (e.stderr) console.error(e.stderr);
+}
+
+const reportPath = path.join(args.project, ".handoff", REPORT_FILE);
+if (!existsSync(reportPath)) {
+  console.warn(
+    "\n⚠ 警告: 未找到 .handoff/verify-report.json（AI 须按 design-verify.md 输出并落盘）"
+  );
+  if (args.strict) failures.push("verify-report");
+} else {
+  console.log("✓ 已找到 verify-report.json");
+}
+
+console.log("\n" + "=".repeat(40));
+if (failures.length > 0) {
+  console.error(`✗ Handoff 管控失败: ${failures.join(", ")}`);
+  console.error("禁止声称设计落地完成，请补全步骤并重新执行 handoff check\n");
+  process.exit(1);
+}
+
+console.log("✓ Handoff 管控全部通过\n");
+process.exit(0);

package/scripts/handoff-lib.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Shared utilities for handoff governance scripts.
+ */
+
+import { execSync } from "child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import path from "path";
+
+export const SESSION_FILE = "session.json";
+export const REPORT_FILE = "verify-report.json";
+
+/** C/T/F/Co/S step → required project-relative paths (glob suffix * = directory) */
+export const STEP_MANIFEST = {
+  C: ["public/platform-config.json"],
+  T: ["src/styles/design-tokens.scss"],
+  F: [
+    "src/layout/components/lay-navbar/index.vue",
+    "src/layout/components/lay-sidebar/NavVertical.vue",
+    "src/layout/components/lay-tag/index.vue",
+    "src/styles/sidebar.scss",
+  ],
+  Co: [
+    "src/components/ReTableBar/src/bar.vue",
+    "src/components/ReTableOperate/src/index.vue",
+    "src/components/RePagination",
+  ],
+  S: ["src/styles/element-plus.scss"],
+};
+
+export function parseArgs(argv) {
+  const args = { project: process.cwd(), session: null, strict: false, skipIfNoSession: true };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project" && argv[i + 1]) args.project = path.resolve(argv[++i]);
+    else if (a === "--session" && argv[i + 1]) args.session = path.resolve(argv[++i]);
+    else if (a === "--strict") args.strict = true;
+    else if (a === "--require-session") args.skipIfNoSession = false;
+  }
+  args.sessionPath =
+    args.session || path.join(args.project, ".handoff", SESSION_FILE);
+  return args;
+}
+
+export function readSession(sessionPath) {
+  if (!existsSync(sessionPath)) return null;
+  try {
+    return JSON.parse(readFileSync(sessionPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function readProjectFile(projectRoot, relPath) {
+  const full = path.join(projectRoot, relPath);
+  if (!existsSync(full)) return null;
+  return readFileSync(full, "utf-8");
+}
+
+export function fileExists(projectRoot, relPath) {
+  return existsSync(path.join(projectRoot, relPath));
+}
+
+export function gitBaseline(projectRoot) {
+  try {
+    return execSync("git rev-parse HEAD", {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function gitChangedFiles(projectRoot, baseline) {
+  if (!baseline) return null;
+  try {
+    const out = execSync(`git diff --name-only ${baseline}`, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return out
+      .split(/\r?\n/)
+      .map(s => s.trim().replace(/\\/g, "/"))
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+export function expandStepPaths(relPaths) {
+  return relPaths.flatMap(p => (p.endsWith("*") ? [p.slice(0, -1)] : [p]));
+}
+
+export function pathMatchesChanged(changedSet, relPath) {
+  const norm = relPath.replace(/\\/g, "/");
+  if (changedSet.has(norm)) return true;
+  // directory: any file under prefix
+  for (const f of changedSet) {
+    if (f.startsWith(norm.endsWith("/") ? norm : `${norm}/`)) return true;
+  }
+  return false;
+}
+
+export function collectFilesUnder(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = path.join(dir, name);
+    if (statSync(full).isDirectory()) out.push(...collectFilesUnder(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+export function getHandoff(session) {
+  return session?.handoff || session;
+}
+
+export function headerElements(handoff) {
+  return handoff?.structureRequirements?.frameworkShell?.header ?? [];
+}
+
+export function interaction(handoff) {
+  return handoff?.interactionSpecs ?? {};
+}

package/scripts/handoff-session-init.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Initialize handoff session — write .handoff/session.json with baseline git commit.
+ *
+ * Usage:
+ *   node scripts/handoff-session-init.mjs --project <path> --file handoff.json
+ *   cat handoff.json | node scripts/handoff-session-init.mjs --project <path>
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+import { gitBaseline, parseArgs, SESSION_FILE } from "./handoff-lib.mjs";
+
+const args = parseArgs(process.argv);
+let handoffJson = null;
+
+const fileIdx = process.argv.indexOf("--file");
+if (fileIdx !== -1 && process.argv[fileIdx + 1]) {
+  handoffJson = JSON.parse(readFileSync(path.resolve(process.argv[fileIdx + 1]), "utf-8"));
+} else if (!process.stdin.isTTY) {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (raw) handoffJson = JSON.parse(raw);
+}
+
+if (!handoffJson) {
+  console.error("用法: handoff-session-init.mjs --project <path> --file <handoff.json>");
+  process.exit(1);
+}
+
+if (handoffJson.$schema !== "design-handoff/v1") {
+  console.error("handoff-session-init: 需要 $schema: design-handoff/v1");
+  process.exit(1);
+}
+
+if (!handoffJson.structureRequirements || !handoffJson.interactionSpecs) {
+  console.error(
+    "handoff-session-init: handoff 缺少 structureRequirements 或 interactionSpecs，请使用新版设计 skill 产出"
+  );
+  process.exit(1);
+}
+
+const handoffDir = path.join(args.project, ".handoff");
+mkdirSync(handoffDir, { recursive: true });
+
+const baseline = gitBaseline(args.project);
+const session = {
+  manifestVersion: 1,
+  startedAt: new Date().toISOString(),
+  baseline,
+  handoff: handoffJson,
+  steps: {
+    C: { status: "pending" },
+    T: { status: "pending" },
+    F: { status: "pending" },
+    Co: { status: "pending" },
+    S: { status: "pending" },
+    P: { status: "pending" },
+  },
+};
+
+const outPath = path.join(handoffDir, SESSION_FILE);
+writeFileSync(outPath, JSON.stringify(session, null, 2), "utf-8");
+
+console.log(`✓ 已写入 ${outPath}`);
+console.log(`  baseline: ${baseline || "(非 git 仓库)"}`);
+console.log(`  theme: ${handoffJson.meta?.themeName || handoffJson.meta?.themeId || "?"}`);
+console.log(`  header: ${(handoffJson.structureRequirements?.frameworkShell?.header || []).join(", ")}`);
+console.log(`  tabsActive.underline: ${handoffJson.interactionSpecs?.tabsActive?.underline}`);
+console.log(`  tableOperate.showIcon: ${handoffJson.interactionSpecs?.tableOperate?.showIcon}`);

package/scripts/handoff-spec-check.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Handoff spec gate — JSON-driven checks (structureRequirements + interactionSpecs).
+ *
+ * Usage:
+ *   node scripts/handoff-spec-check.mjs --project <path> [--require-session]
+ */
+
+import path from "path";
+import {
+  fileExists,
+  getHandoff,
+  headerElements,
+  interaction,
+  parseArgs,
+  readProjectFile,
+  readSession,
+} from "./handoff-lib.mjs";
+
+const args = parseArgs(process.argv);
+const session = readSession(args.sessionPath);
+
+if (!session) {
+  if (args.skipIfNoSession) {
+    console.log("handoff-spec-check: 无 .handoff/session.json，跳过规格检查");
+    process.exit(0);
+  }
+  console.error("handoff-spec-check: 缺少 .handoff/session.json");
+  process.exit(1);
+}
+
+const handoff = getHandoff(session);
+if (!handoff?.structureRequirements || !handoff?.interactionSpecs) {
+  console.error(
+    "handoff-spec-check: handoff JSON 缺少 structureRequirements 或 interactionSpecs（设计 skill 必产出段）"
+  );
+  process.exit(1);
+}
+
+const project = args.project;
+const specs = interaction(handoff);
+const header = headerElements(handoff);
+const failures = [];
+const passes = [];
+
+function fail(id, message) {
+  failures.push({ id, message });
+}
+
+function pass(id, message) {
+  passes.push({ id, message });
+}
+
+// --- structureRequirements: header elements ---
+const navbarPath = "src/layout/components/lay-navbar/index.vue";
+const navbar = readProjectFile(project, navbarPath);
+
+if (!navbar) {
+  fail("navbar-exists", `缺少 ${navbarPath}`);
+} else {
+  const headerChecks = [
+    { id: "settings", patterns: [/lay-setting|LaySetting|set-icon|settings/i], inHeader: header.includes("settings") },
+    { id: "breadcrumb", patterns: [/breadcrumb|LayBreadcrumb/i], inHeader: header.includes("breadcrumb") },
+    { id: "collapse", patterns: [/collapse|fold|unfold|iconify.*menu/i], inHeader: header.includes("collapse") },
+    { id: "langSwitch", patterns: [/ReLanguageSwitch|language-switch|lang-switch/i], inHeader: header.includes("langSwitch") },
+    { id: "fullscreen", patterns: [/fullscreen|FullScreen|screenfull/i], inHeader: header.includes("fullscreen") },
+  ];
+
+  for (const { id, patterns, inHeader } of headerChecks) {
+    const found = patterns.some(p => p.test(navbar));
+    if (inHeader && !found) fail(`header-missing-${id}`, `JSON header 含 "${id}" 但 ${navbarPath} 未找到对应实现`);
+    else if (!inHeader && found) fail(`header-forbidden-${id}`, `JSON header 不含 "${id}" 但 ${navbarPath} 仍存在该元素`);
+    else pass(`header-${id}`, `顶栏元素 ${id}: 与 JSON 一致`);
+  }
+}
+
+// --- interactionSpecs: languageSwitch ---
+if (specs.languageSwitch?.mode === "inline-text") {
+  const langFile =
+    readProjectFile(project, "src/components/ReLanguageSwitch/src/index.vue") ||
+    readProjectFile(project, "src/components/ReLanguageSwitch/index.vue");
+  if (langFile && /el-dropdown|ElDropdown/.test(langFile) && !/inline|中\s*[|｜/]\s*EN/i.test(langFile)) {
+    fail("lang-inline", "interactionSpecs.languageSwitch.mode=inline-text 但 ReLanguageSwitch 仍为下拉框");
+  } else if (langFile) {
+    pass("lang-inline", "语言切换为内联文字模式");
+  }
+}
+
+// --- interactionSpecs: tabsActive.underline ---
+if (specs.tabsActive?.underline === false) {
+  const tagVue = readProjectFile(project, "src/layout/components/lay-tag/index.vue") || "";
+  const epScss = readProjectFile(project, "src/styles/element-plus.scss") || "";
+  const combined = tagVue + epScss;
+  if (/schedule-active|active-bar|border-bottom.*primary|underline/i.test(combined) &&
+      !/underline:\s*none|display:\s*none.*active-bar|smart.*无下划线/i.test(combined)) {
+    // soft check — only fail on obvious underline patterns for smart/line
+    if (/\.schedule-active|active-bar|tabs.*border-bottom/i.test(combined)) {
+      fail(
+        "tabs-no-underline",
+        "interactionSpecs.tabsActive.underline=false 但 lay-tag/element-plus 仍含页签激活下划线样式"
+      );
+    }
+  } else {
+    pass("tabs-no-underline", "页签激活无下划线（符合 JSON）");
+  }
+}
+
+// --- interactionSpecs: menuActive ---
+const menu = specs.menuActive;
+if (menu) {
+  const sidebar = readProjectFile(project, "src/styles/sidebar.scss") || "";
+  if (menu.fullWidth === false) {
+    if (/width:\s*100%|margin:\s*0[^;]*;[^}]*active|通栏/i.test(sidebar) &&
+        !/margin:\s*0\s+8px|margin.*8px/i.test(sidebar)) {
+      fail("menu-not-fullwidth", "interactionSpecs.menuActive.fullWidth=false 但 sidebar 激活态疑似通栏");
+    } else {
+      pass("menu-not-fullwidth", "侧栏激活非通栏");
+    }
+  }
+  if (menu.radius === 6 && sidebar && !/border-radius:\s*6px|radius:\s*6/i.test(sidebar)) {
+    fail("menu-radius", "interactionSpecs.menuActive.radius=6 但 sidebar.scss 未找到 6px 圆角");
+  } else if (menu.radius) {
+    pass("menu-radius", "侧栏菜单圆角符合 JSON");
+  }
+}
+
+// --- interactionSpecs: tableOperate ---
+const tableOp = specs.tableOperate;
+if (tableOp?.showIcon === false) {
+  const operate =
+    readProjectFile(project, "src/components/ReTableOperate/src/index.vue") ||
+    readProjectFile(project, "src/components/ReTableOperate/index.vue");
+  if (operate && /:icon=|btn\.icon|icon:\s*/i.test(operate)) {
+    fail("operate-no-icon", "interactionSpecs.tableOperate.showIcon=false 但 ReTableOperate 仍绑定 icon");
+  } else if (operate) {
+    pass("operate-no-icon", "操作列无图标");
+  } else {
+    fail("operate-exists", "缺少 ReTableOperate 组件文件");
+  }
+}
+
+if (tableOp?.showDivider === true) {
+  const operate =
+    readProjectFile(project, "src/components/ReTableOperate/src/index.vue") ||
+    readProjectFile(project, "src/components/ReTableOperate/index.vue");
+  if (operate && !/divider|分隔|vts-table-action-divider|action-divider/i.test(operate)) {
+    fail("operate-divider", "interactionSpecs.tableOperate.showDivider=true 但 ReTableOperate 无分隔线");
+  } else if (operate) {
+    pass("operate-divider", "操作列有分隔线");
+  }
+}
+
+// --- interactionSpecs: tableToolbar ---
+const toolbar = specs.tableToolbar;
+if (toolbar?.showTextLabel === true) {
+  const bar =
+    readProjectFile(project, "src/components/ReTableBar/src/bar.vue") ||
+    readProjectFile(project, "src/components/ReTableBar/index.vue");
+  if (bar) {
+    const hasText = /刷新|密度|列设置|columns|density|refresh/i.test(bar);
+    if (!hasText) {
+      fail("toolbar-text-label", "interactionSpecs.tableToolbar.showTextLabel=true 但 ReTableBar 工具按钮无文字标签");
+    } else {
+      pass("toolbar-text-label", "工具栏按钮含文字标签");
+    }
+  }
+}
+
+// --- elementHideList ---
+const hideList = handoff.structureRequirements?.elementHideList ?? [];
+if (hideList.includes("navbar-settings") && navbar && /lay-setting|LaySetting|set-icon/i.test(navbar)) {
+  fail("hide-settings", "elementHideList 含 navbar-settings 但顶栏仍有设置按钮");
+}
+
+// --- Co files must exist ---
+for (const rel of [
+  "src/components/ReTableBar/src/bar.vue",
+  "src/components/ReTableOperate/src/index.vue",
+]) {
+  if (!fileExists(project, rel)) fail("co-file", `共享组件缺失: ${rel}`);
+}
+
+console.log("\n=== Handoff 规格检查（JSON 驱动）===");
+console.log(`  通过: ${passes.length}  失败: ${failures.length}`);
+
+if (failures.length > 0) {
+  console.error("\n✗ 规格检查失败:");
+  for (const f of failures) {
+    console.error(`  - [${f.id}] ${f.message}`);
+  }
+  process.exit(1);
+}
+
+console.log("\n✓ 规格检查全部通过\n");
+process.exit(0);

package/scripts/handoff-step-check.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Handoff step gate — verifies C/T/F/Co/S files were touched since session baseline.
+ *
+ * Usage:
+ *   node scripts/handoff-step-check.mjs --project <path> [--require-session]
+ */
+
+import path from "path";
+import {
+  STEP_MANIFEST,
+  expandStepPaths,
+  gitBaseline,
+  gitChangedFiles,
+  parseArgs,
+  pathMatchesChanged,
+  readSession,
+} from "./handoff-lib.mjs";
+
+const args = parseArgs(process.argv);
+const session = readSession(args.sessionPath);
+
+if (!session) {
+  if (args.skipIfNoSession) {
+    console.log("handoff-step-check: 无 .handoff/session.json，跳过步骤检查");
+    process.exit(0);
+  }
+  console.error("handoff-step-check: 缺少 .handoff/session.json，请先执行 handoff-session-init");
+  process.exit(1);
+}
+
+const baseline = session.baseline || gitBaseline(args.project);
+const changedList = gitChangedFiles(args.project, baseline);
+
+if (!changedList) {
+  console.error(
+    "handoff-step-check: 无法获取 git diff（非 git 仓库或无 baseline）。请先 handoff-session-init 或提交 baseline。"
+  );
+  process.exit(1);
+}
+
+const changedSet = new Set(changedList);
+const failures = [];
+const results = {};
+
+for (const [step, files] of Object.entries(STEP_MANIFEST)) {
+  const expanded = expandStepPaths(files);
+  const missing = [];
+  const touched = [];
+
+  for (const rel of expanded) {
+    const hit = pathMatchesChanged(changedSet, rel);
+    if (hit) touched.push(rel);
+    else missing.push(rel);
+  }
+
+  results[step] = { touched, missing, ok: missing.length === 0 };
+  if (missing.length > 0) {
+    failures.push({
+      step,
+      message: `步骤 ${step} 未修改: ${missing.join(", ")}`,
+      missing,
+    });
+  }
+}
+
+console.log("\n=== Handoff 步骤检查 ===");
+for (const [step, r] of Object.entries(results)) {
+  console.log(`  ${step}: ${r.ok ? "✓" : "✗"} (${r.touched.length}/${expandStepPaths(STEP_MANIFEST[step]).length} 文件已变更)`);
+}
+
+if (failures.length > 0) {
+  console.error("\n✗ 步骤检查失败（流程硬失败 — 可能跳过了 Co/F 等步骤）:");
+  for (const f of failures) {
+    console.error(`  - [${f.step}] ${f.message}`);
+  }
+  process.exit(1);
+}
+
+console.log("\n✓ 全部步骤（C/T/F/Co/S）对应文件均已变更\n");
+process.exit(0);