sdd-flow-kit 1.3.18 → 1.3.22

package/dist/core/visualRegression.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVisualAcRequirements = parseVisualAcRequirements;
+exports.listPrdSourceImages = listPrdSourceImages;
+exports.resolveBaselinePath = resolveBaselinePath;
+exports.checkVisualRegression = checkVisualRegression;
+/**
+ * L4 视觉回归门禁：05 visual AC + 基线图存在 + E2E toHaveScreenshot 绑定。
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const e2eAssertionDepth_1 = require("./e2eAssertionDepth");
+const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const IMAGE_REF_RE = /(?:source\/[\w/.-]+\.(?:png|jpe?g|webp)|visual-baseline\/[\w/.-]+\.(?:png|jpe?g|webp)|image_\d+\.(?:png|jpe?g|webp))/gi;
+const DIFF_PERCENT_RE = /diff\s*[≤<=]\s*(\d+(?:\.\d+)?)\s*%/i;
+const TO_HAVE_SCREENSHOT_RE = /\btoHaveScreenshot\s*\(/;
+const PAGE_SCREENSHOT_ONLY_RE = /\bpage\.screenshot\s*\(/;
+const UI_SCENARIO_KEYWORDS = /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|编辑|导出|筛选|输入框|对话框|导航|toast|截图|布局/i;
+/**
+ * 从验收标准提取基线图路径与 diff 阈值（如 diff≤2%）。
+ */
+function parseVisualAcRequirements(items) {
+    var _a, _b, _c;
+    const out = [];
+    for (const item of items) {
+        if (!/visual/i.test((_a = item.testType) !== null && _a !== void 0 ? _a : ""))
+            continue;
+        const criterion = (_b = item.criterion) !== null && _b !== void 0 ? _b : "";
+        const baselineRefs = [...new Set(((_c = criterion.match(IMAGE_REF_RE)) !== null && _c !== void 0 ? _c : []).map((s) => s.trim()))];
+        const diffMatch = criterion.match(DIFF_PERCENT_RE);
+        const maxDiffPercent = diffMatch ? Number(diffMatch[1]) : null;
+        out.push({
+            acId: item.id,
+            criterion,
+            baselineRefs,
+            maxDiffPercent,
+        });
+    }
+    return out;
+}
+async function walkImages(dir, out) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        const full = path_1.default.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await walkImages(full, out);
+        }
+        else if (/\.(png|jpe?g|webp)$/i.test(ent.name)) {
+            out.push(full);
+        }
+    }
+}
+/** PRD run 的 source/ 下是否存在原型截图 */
+async function listPrdSourceImages(outputRoot) {
+    const sourceDir = path_1.default.join(outputRoot, "source");
+    const images = [];
+    await walkImages(sourceDir, images);
+    return images;
+}
+/**
+ * 将验收标准中的基线引用解析为磁盘绝对路径。
+ */
+async function resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages) {
+    const normalized = ref.replace(/\\/g, "/");
+    const candidates = [];
+    if (outputRoot) {
+        candidates.push(path_1.default.join(outputRoot, normalized));
+        candidates.push(path_1.default.join(outputRoot, "visual-baseline", path_1.default.basename(normalized)));
+    }
+    candidates.push(path_1.default.join(pkgRoot, normalized));
+    candidates.push(path_1.default.join(pkgRoot, "visual-baseline", path_1.default.basename(normalized)));
+    for (const c of candidates) {
+        const content = await (0, fs_1.readFileIfExists)(c);
+        if (content !== null)
+            return c;
+    }
+    if (/^image_\d+\./i.test(normalized)) {
+        const hit = prdImages.find((p) => path_1.default.basename(p) === path_1.default.basename(normalized));
+        if (hit)
+            return hit;
+    }
+    const byBase = prdImages.find((p) => p.endsWith(`/${path_1.default.basename(normalized)}`));
+    return byBase !== null && byBase !== void 0 ? byBase : null;
+}
+function e2eBlockHasVisualAssertion(blockBody) {
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    return TO_HAVE_SCREENSHOT_RE.test(body);
+}
+function e2eReferencesBaseline(blockBody, baselineRefs) {
+    if (baselineRefs.length === 0)
+        return TO_HAVE_SCREENSHOT_RE.test((0, testAssertionAnalysis_1.stripComments)(blockBody));
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    return baselineRefs.some((ref) => {
+        const base = path_1.default.basename(ref).replace(/\.(png|jpe?g|webp)$/i, "");
+        return body.includes(ref) || body.includes(base) || body.includes(`'${base}'`) || body.includes(`"${base}"`);
+    });
+}
+async function changeHasUiScenarios(pkgRoot, changeName) {
+    const specsDir = path_1.default.join(pkgRoot, "openspec/changes", changeName, "specs");
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(specsDir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const cap of entries) {
+        if (!cap.isDirectory())
+            continue;
+        const specPath = path_1.default.join(specsDir, cap.name, "spec.md");
+        const content = await (0, fs_1.readFileIfExists)(specPath);
+        if (!content)
+            continue;
+        const blocks = content.split(/^####\s+Scenario:/m);
+        for (let i = 1; i < blocks.length; i += 1) {
+            if (UI_SCENARIO_KEYWORDS.test(blocks[i]))
+                return true;
+        }
+    }
+    return false;
+}
+function hasVisualExempt(tasksContent) {
+    return /^VISUAL_REGRESSION_EXEMPT:/m.test(tasksContent);
+}
+/**
+ * 视觉回归静态门禁（deliver 前）：基线图 + toHaveScreenshot 与 visual AC 绑定。
+ */
+async function checkVisualRegression(pkgRoot, outputRoot, changeName, acItems) {
+    var _a, _b;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_VISUAL_REGRESSION === "1" ||
+        process.env.OPSX_SKIP_VISUAL_REGRESSION === "1";
+    if (skip) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_VISUAL_REGRESSION=1",
+        });
+        return checks;
+    }
+    const tasksContent = (_a = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, "openspec/changes", changeName, "tasks.md")))) !== null && _a !== void 0 ? _a : "";
+    if (hasVisualExempt(tasksContent)) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "VISUAL_REGRESSION_EXEMPT 已声明，跳过视觉回归门禁",
+        });
+        return checks;
+    }
+    const visualReqs = parseVisualAcRequirements(acItems);
+    const prdImages = outputRoot ? await listPrdSourceImages(outputRoot) : [];
+    const requiresUi = await changeHasUiScenarios(pkgRoot, changeName);
+    const specPaths = await (0, e2eAssertionDepth_1.collectChangeE2eSpecs)(pkgRoot, changeName);
+    if (prdImages.length > 0 && requiresUi && visualReqs.length === 0) {
+        checks.push({
+            name: "visual-ac-required",
+            ok: false,
+            detail: `PRD source 含 ${prdImages.length} 张原型图，但 05 无 visual 类型 AC；请补充基线对比验收项（如 AC-xx-v | visual | 基线 image_3.png）`,
+        });
+        return checks;
+    }
+    if (visualReqs.length === 0) {
+        checks.push({
+            name: "visual-regression",
+            ok: true,
+            detail: "无 visual 类型 AC，跳过视觉回归门禁",
+        });
+        return checks;
+    }
+    const failures = [];
+    let e2eBlob = "";
+    const e2eBlocks = [];
+    for (const rel of specPaths) {
+        const content = (_b = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, rel)))) !== null && _b !== void 0 ? _b : "";
+        e2eBlob += content;
+        for (const block of (0, testAssertionAnalysis_1.parseTestBlocks)(content)) {
+            e2eBlocks.push({ spec: rel, title: block.title, body: block.body });
+        }
+    }
+    if (specPaths.length === 0) {
+        failures.push("含 visual AC 但未绑定 e2e spec");
+    }
+    else if (!TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+        failures.push("e2e spec 须使用 toHaveScreenshot 做基线对比（禁止仅 page.screenshot 留证）");
+    }
+    for (const req of visualReqs) {
+        if (req.baselineRefs.length === 0) {
+            failures.push(`${req.acId}: visual AC 验收标准须写明基线路径（source/...png 或 visual-baseline/...png）`);
+            continue;
+        }
+        for (const ref of req.baselineRefs) {
+            const abs = await resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages);
+            if (!abs) {
+                failures.push(`${req.acId}: 基线图不存在 ${ref}（请在 PRD run visual-baseline/ 或 source/ 放置）`);
+            }
+        }
+        const boundBlocks = e2eBlocks.filter((b) => (0, testAssertionAnalysis_1.testBlockReferencesAc)({ title: b.title, body: b.body, index: 0 }, req.acId) && e2eBlockHasVisualAssertion(b.body));
+        if (boundBlocks.length === 0) {
+            failures.push(`${req.acId}: 须在 e2e test 块内含 [${req.acId}] 且调用 toHaveScreenshot（建议 maxDiffPixelRatio≤${req.maxDiffPercent != null ? (req.maxDiffPercent / 100).toFixed(2) : "0.02"}）`);
+            continue;
+        }
+        const baselineBound = boundBlocks.some((b) => e2eReferencesBaseline(b.body, req.baselineRefs));
+        if (!baselineBound && req.baselineRefs.length > 0) {
+            failures.push(`${req.acId}: toHaveScreenshot 须引用基线名 ${req.baselineRefs.map((r) => path_1.default.basename(r)).join("、")}`);
+        }
+        if (req.maxDiffPercent != null) {
+            const ratio = req.maxDiffPercent / 100;
+            const hasRatio = boundBlocks.some((b) => {
+                const body = (0, testAssertionAnalysis_1.stripComments)(b.body);
+                if (new RegExp(`maxDiffPixelRatio:\\s*${ratio}`).test(body))
+                    return true;
+                if (ratio <= 0.02 && /maxDiffPixelRatio:\s*0\.0[12]/.test(body))
+                    return true;
+                return false;
+            });
+            if (!hasRatio) {
+                failures.push(`${req.acId}: 建议 toHaveScreenshot 配置 maxDiffPixelRatio: ${ratio}（与验收标准 diff≤${req.maxDiffPercent}% 一致）`);
+            }
+        }
+    }
+    const screenshotOnlyNoCompare = PAGE_SCREENSHOT_ONLY_RE.test(e2eBlob) && !TO_HAVE_SCREENSHOT_RE.test(e2eBlob);
+    if (screenshotOnlyNoCompare) {
+        failures.push("存在 page.screenshot 但无 toHaveScreenshot，不能算作视觉回归");
+    }
+    checks.push({
+        name: "visual-regression",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `视觉回归绑定通过（${visualReqs.length} 条 visual AC，spec: ${specPaths.join(", ") || "无"}）`
+            : failures.join(" | "),
+    });
+    return checks;
+}

package/dist/steps/startFlow.js

@@ -82,6 +82,8 @@ async function startFlowScaffold(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "04-技术文档草稿.md"), techDocTemplate);
     const techDocFillGuide = await (0, templates_1.loadTemplateText)("prompts/04-tech-doc-fill-prompt.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "04-技术文档生成指引.md"), techDocFillGuide);
+    const visualBaselineReadme = await (0, templates_1.loadTemplateText)("artifacts/visual-baseline-readme.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "visual-baseline/README.md"), visualBaselineReadme);
     // 5) Step5 openspec 提案入口（草稿）
     const openspecEntryTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-openspec-提案草稿.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-openspec-提案草稿.md"), openspecEntryTemplate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.3.18",
+  "version": "1.3.22",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

package/scripts/assess-ac-assertion-binding.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * AC 断言绑定门禁：P0/e2e AC 的验收标准字面量须出现在 test 块 expect 中。
+ *
+ * 用法:
+ *   node scripts/assess-ac-assertion-binding.mjs --run-dir openspec/PRD/<runId>
+ *   node scripts/assess-ac-assertion-binding.mjs --run-dir <path> --change <name>（可选）
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  checkAcAssertionBinding,
+  parseAcMatrixFrom05,
+} from "./lib/ac-assertion-binding.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const TEST_FILE_RE = /\.(spec|test)\.(t|j)sx?$/i;
+
+function parseArgs(argv) {
+  let runDir = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--run-dir" && argv[i + 1]) runDir = argv[++i];
+    else if (!a.startsWith("-") && !runDir) runDir = a;
+  }
+  return { runDir };
+}
+
+function fail(messages) {
+  console.error("[assess-ac-assertion-binding] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error(
+    "  修复: Red 阶段从 05「验收标准」复制完整文案到 expect；禁止 toContain('成功') 等模糊断言",
+  );
+  process.exit(1);
+}
+
+function walkTests(dir, out, relPrefix = "") {
+  if (!fs.existsSync(dir)) return;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === "node_modules" || ent.name === ".git" || ent.name === "dist") continue;
+    const full = path.join(dir, ent.name);
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) walkTests(full, out, rel);
+    else if (TEST_FILE_RE.test(ent.name)) {
+      out.push({ rel, content: fs.readFileSync(full, "utf8") });
+    }
+  }
+}
+
+function collectTestFiles() {
+  const files = [];
+  for (const r of ["e2e", "tests", "test", "__tests__", "playwright", "src"]) {
+    walkTests(path.join(ROOT, r), files, r);
+  }
+  return files;
+}
+
+function resolveRunDir(arg) {
+  if (!arg) return "";
+  if (path.isAbsolute(arg)) return arg;
+  const candidates = [
+    path.join(ROOT, arg),
+    path.join(ROOT, "openspec/PRD", arg),
+    path.join(ROOT, "frontend/openspec/PRD", arg),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "05-验收清单.md"))) return c;
+  }
+  return path.join(ROOT, arg);
+}
+
+function main() {
+  const skip = process.env.OPSX_SKIP_AC_ASSERTION_BINDING;
+  if (skip === "1") {
+    console.warn("[assess-ac-assertion-binding] SKIP");
+    process.exit(0);
+  }
+
+  const { runDir: runDirArg } = parseArgs(process.argv);
+  const runDir = resolveRunDir(runDirArg);
+  const ac05Path = path.join(runDir, "05-验收清单.md");
+  if (!fs.existsSync(ac05Path)) {
+    console.error("[assess-ac-assertion-binding] 缺少 --run-dir（须含 05-验收清单.md）");
+    process.exit(2);
+  }
+
+  const items = parseAcMatrixFrom05(fs.readFileSync(ac05Path, "utf8"));
+  if (items.length === 0) {
+    console.error("[assess-ac-assertion-binding] 05 未解析到 AC 行");
+    process.exit(2);
+  }
+
+  const testFiles = collectTestFiles();
+  const errors = checkAcAssertionBinding(items, testFiles);
+  if (errors.length > 0) fail(errors);
+
+  console.log(
+    `[assess-ac-assertion-binding] PASS run=${path.basename(runDir)} ac=${items.length} tests=${testFiles.length}`,
+  );
+}
+
+main();

package/scripts/assess-api-field-contract.mjs

@@ -81,7 +81,7 @@ function main() {
   const modRe = /config\/api\/modules\/([\w/-]+)/g;
   let m;
   while ((m = modRe.exec(blob)) !== null) {
-    moduleRefs.add(m[1].replace(/\/index$/, ""));
+    moduleRefs.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
   }
 
   if (moduleRefs.size === 0) {

package/scripts/assess-api-field-coverage.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * API 字段级覆盖门禁（v1.3.20）：fixture 样例 + 04 字段映射表 + 源码消费点。
+ *
+ * 用法:
+ *   node scripts/assess-api-field-coverage.mjs --change <change-name> [--run-dir openspec/PRD/runId]
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { assessApiFieldCoverage } from "./lib/api-field-coverage.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  let change = "";
+  let runDir = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) change = argv[++i];
+    else if (a === "--run-dir" && argv[i + 1]) runDir = argv[++i];
+    else if (!a.startsWith("-") && !change) change = a;
+  }
+  return { change, runDir };
+}
+
+function resolveRunDir(arg) {
+  if (!arg) return "";
+  const candidates = [
+    path.isAbsolute(arg) ? arg : path.join(ROOT, arg),
+    path.join(ROOT, "openspec/PRD", arg),
+    path.join(ROOT, "frontend/openspec/PRD", arg),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "04-技术文档草稿.md"))) return c;
+  }
+  return candidates[0];
+}
+
+function fail(messages) {
+  console.error("[assess-api-field-coverage] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error(
+    "  修复: 1) 04 §4.3.1 补字段映射表 2) tests/fixtures/<module>/*.json 联调样例 3) caseTransform 单测加载 fixture",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_API_FIELD_COVERAGE ||
+    process.env.OPSX_SKIP_API_FIELD_COVERAGE;
+  if (skip === "1") {
+    console.warn("[assess-api-field-coverage] SKIP");
+    process.exit(0);
+  }
+
+  const { change, runDir: runDirArg } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-api-field-coverage] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-api-field-coverage] change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  let fieldDoc = "";
+  const runDir = resolveRunDir(runDirArg);
+  if (runDir && fs.existsSync(path.join(runDir, "04-技术文档草稿.md"))) {
+    fieldDoc += fs.readFileSync(path.join(runDir, "04-技术文档草稿.md"), "utf8");
+  }
+  const designPath = path.join(changeDir, "design.md");
+  if (fs.existsSync(designPath)) {
+    fieldDoc += fs.readFileSync(designPath, "utf8");
+  }
+
+  const { errors, passed } = assessApiFieldCoverage(ROOT, change, fieldDoc);
+  if (errors.length > 0) fail(errors);
+
+  console.log(
+    `[assess-api-field-coverage] PASS change=${change} ${passed.join("; ")}`,
+  );
+}
+
+main();

package/scripts/assess-component-substance.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * 组件实质门禁：演示映射的生产组件须非空壳，子组件须被父组件引用。
+ *
+ * 用法: node scripts/assess-component-substance.mjs --change <change-name>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  analyzeComponentSubstance,
+  checkChildComponentsImported,
+} from "./lib/component-substance.mjs";
+import { parseDemoReferenceSection } from "./lib/demo-reference-parse.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  let change = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) change = argv[++i];
+    else if (!a.startsWith("-") && !change) change = a;
+  }
+  return { change };
+}
+
+function fail(messages) {
+  console.error("[assess-component-substance] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error(
+    "  修复: 按 design 映射实现真实子组件（template+API/emit），并在父 Drawer 中 import；禁止注释塞关键词",
+  );
+  process.exit(1);
+}
+
+async function main() {
+  const skip = process.env.OPSX_SKIP_COMPONENT_SUBSTANCE;
+  if (skip === "1") {
+    console.warn("[assess-component-substance] SKIP");
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-component-substance] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const designPath = path.join(ROOT, "openspec/changes", change, "design.md");
+  if (!fs.existsSync(designPath)) {
+    console.error(`[assess-component-substance] design.md 不存在: ${change}`);
+    process.exit(2);
+  }
+
+  const design = fs.readFileSync(designPath, "utf8");
+  const parsed = parseDemoReferenceSection(design);
+  if (parsed.exempt || parsed.mappings.length === 0) {
+    console.log("[assess-component-substance] PASS（无演示映射）");
+    process.exit(0);
+  }
+
+  const errors = [];
+  for (const m of parsed.mappings) {
+    const rel = m.productionPath.replace(/^\.\//, "");
+    const abs = path.join(ROOT, rel);
+    if (!fs.existsSync(abs)) {
+      errors.push(`${m.moduleName}: 文件不存在 ${rel}`);
+      continue;
+    }
+    const content = fs.readFileSync(abs, "utf8");
+    const result = analyzeComponentSubstance(rel, content, m.interactionSignals);
+    if (!result.ok) {
+      errors.push(`${m.moduleName}(${rel}): ${result.issues.join("; ")}`);
+    }
+  }
+
+  const importFailures = await checkChildComponentsImported(ROOT, parsed.mappings);
+  errors.push(...importFailures);
+
+  if (errors.length > 0) fail(errors);
+  console.log(
+    `[assess-component-substance] PASS change=${change} modules=${parsed.mappings.length}`,
+  );
+}
+
+main();

package/scripts/assess-e2e-assertion-depth.mjs

@@ -8,6 +8,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { analyzeE2eSpecDepth } from "./lib/test-assertion-analysis.mjs";
+import { checkE2eDemoSignalClicks } from "./lib/e2e-demo-signal-clicks.mjs";
+import { parseDemoReferenceSection } from "./lib/demo-reference-parse.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const CONFIG_PATH = path.join(ROOT, "e2e/e2e-scope.config.json");
@@ -136,6 +138,20 @@ function main() {
     }
   }
 
+  const designPath = path.join(changeDir, "design.md");
+  if (fs.existsSync(designPath) && specPaths.length > 0) {
+    const design = fs.readFileSync(designPath, "utf8");
+    const parsed = parseDemoReferenceSection(design);
+    if (!parsed.exempt && parsed.mappings.length > 0) {
+      let e2eBlob = "";
+      for (const rel of specPaths) {
+        e2eBlob += fs.readFileSync(path.join(ROOT, rel), "utf8");
+      }
+      const clickFailures = checkE2eDemoSignalClicks(design, e2eBlob);
+      for (const f of clickFailures) errors.push(f);
+    }
+  }
+
   if (errors.length > 0) fail(errors);
 
   console.log(

package/scripts/assess-tech-doc-quality.mjs

@@ -80,6 +80,13 @@ function main() {
     errors.push("缺少 §4.1 接口清单表格");
   }
 
+  if (
+    /\|\s*接口\s*\|\s*Method\s*\|/m.test(content) &&
+    !/\|\s*后端字段\s*\|\s*前端字段\s*\|/m.test(content)
+  ) {
+    errors.push("缺少 §4.3.1 响应字段映射表（| 后端字段 | 前端字段 |）");
+  }
+
   if (!/\|\s*演示模块\s*\|\s*演示文件\/组件\s*\|/m.test(content)) {
     errors.push("缺少 §2.4 演示模块映射表格");
   }

package/scripts/assess-visual-regression.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * L4 视觉回归门禁：05 visual AC + 基线图 + E2E toHaveScreenshot。
+ *
+ * 用法:
+ *   node scripts/assess-visual-regression.mjs --change <name> --run-dir openspec/PRD/<runId>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  assessVisualRegression,
+  parseAcMatrixFrom05,
+} from "./lib/visual-regression.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  let change = "";
+  let runDir = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) change = argv[++i];
+    else if (a === "--run-dir" && argv[i + 1]) runDir = argv[++i];
+    else if (!a.startsWith("-") && !change) change = a;
+  }
+  return { change, runDir };
+}
+
+function resolveRunDir(arg) {
+  if (!arg) return "";
+  const candidates = [
+    path.isAbsolute(arg) ? arg : path.join(ROOT, arg),
+    path.join(ROOT, "openspec/PRD", arg),
+    path.join(ROOT, "frontend/openspec/PRD", arg),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "05-验收清单.md"))) return c;
+  }
+  return "";
+}
+
+function fail(messages) {
+  console.error("[assess-visual-regression] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error(
+    "  修复: 05 增加 visual AC（含基线路径 + diff≤N%）；e2e 使用 toHaveScreenshot；基线图放 source/ 或 visual-baseline/",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip = process.env.OPSX_SKIP_VISUAL_REGRESSION;
+  if (skip === "1") {
+    console.warn("[assess-visual-regression] SKIP");
+    process.exit(0);
+  }
+
+  const { change, runDir: runDirArg } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-visual-regression] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-visual-regression] change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  const runDir = resolveRunDir(runDirArg);
+  if (!runDir) {
+    console.error("[assess-visual-regression] 缺少 --run-dir（须含 05-验收清单.md）");
+    process.exit(2);
+  }
+
+  const acItems = parseAcMatrixFrom05(fs.readFileSync(path.join(runDir, "05-验收清单.md"), "utf8"));
+  const { errors, visualReqs, exempt } = assessVisualRegression(ROOT, runDir, change, acItems);
+
+  if (exempt) {
+    console.log("[assess-visual-regression] PASS（豁免）");
+    process.exit(0);
+  }
+
+  if (errors.length > 0) fail(errors);
+
+  console.log(
+    `[assess-visual-regression] PASS change=${change} visualAc=${visualReqs.length}`,
+  );
+}
+
+main();