sdd-flow-kit 1.3.15 → 1.3.21

package/scripts/assess-demo-implementation-coverage.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * 演示代码 → 生产实现 覆盖门禁（通用：演示可为 Vue/React）。
+ *
+ * 用法: node scripts/assess-demo-implementation-coverage.mjs --change <change-name>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const DEMO_SECTION_RE = /^##\s*(演示代码参照|Demo Reference)\s*$/im;
+const DEMO_EXEMPT_RE = /^DEMO_REFERENCE_EXEMPT:\s*(.+)$/m;
+const MAPPING_HEADER_RE = /演示模块|Demo Module/i;
+const UI_SCENARIO_KEYWORDS =
+  /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|编辑|导出|筛选|输入框|对话框|导航|toast|保存|删除|添加/i;
+
+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 stripComments(content) {
+  let out = "";
+  let i = 0;
+  while (i < content.length) {
+    if (content[i] === "/" && content[i + 1] === "/") {
+      while (i < content.length && content[i] !== "\n") i += 1;
+      continue;
+    }
+    if (content[i] === "/" && content[i + 1] === "*") {
+      i += 2;
+      while (i < content.length && !(content[i] === "*" && content[i + 1] === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    out += content[i];
+    i += 1;
+  }
+  return out;
+}
+
+function parseDemoReferenceSection(content) {
+  const exemptMatch = content.match(DEMO_EXEMPT_RE);
+  const exempt = exemptMatch?.[1]?.trim() || null;
+  const sectionMatch = content.match(DEMO_SECTION_RE);
+  if (!sectionMatch || sectionMatch.index === undefined) {
+    return { hasSection: false, exempt, mappings: [] };
+  }
+  const sectionBody = content.slice(sectionMatch.index);
+  const mappings = [];
+  const lines = sectionBody.split("\n");
+  let inTable = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("|") && MAPPING_HEADER_RE.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable || !trimmed.startsWith("|")) continue;
+    if (/^\|\s*[-:]+/.test(trimmed)) continue;
+    const cells = trimmed
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+    if (cells.length < 4) continue;
+    if (/演示模块|Demo Module/i.test(cells[0])) continue;
+    const signals = (cells[3] ?? "")
+      .split(/[、,，|；;]/)
+      .map((s) => s.trim())
+      .filter((s) => s.length >= 2);
+    mappings.push({
+      moduleName: cells[0],
+      productionPath: cells[2].replace(/\\/g, "/"),
+      interactionSignals: signals,
+    });
+  }
+  return { hasSection: true, exempt, mappings };
+}
+
+function changeHasUiScenarios(changeDir) {
+  const specsDir = path.join(changeDir, "specs");
+  if (!fs.existsSync(specsDir)) return false;
+  for (const cap of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (!cap.isDirectory()) continue;
+    const specPath = path.join(specsDir, cap.name, "spec.md");
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    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 fail(messages) {
+  console.error("[assess-demo-implementation-coverage] FAIL");
+  for (const msg of messages) console.error(`  - ${msg}`);
+  console.error(
+    "  修复: 在 design.md 填写 ## 演示代码参照 映射表；按演示拆生产组件；tasks 增加「演示模块迁移」",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_DEMO_REFERENCE ||
+    process.env.OPSX_SKIP_DEMO_REFERENCE;
+  if (skip === "1") {
+    console.warn("[assess-demo-implementation-coverage] SKIP");
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-demo-implementation-coverage] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-demo-implementation-coverage] change 不存在: ${change}`);
+    process.exit(2);
+  }
+
+  const designPath = path.join(changeDir, "design.md");
+  if (!fs.existsSync(designPath)) {
+    if (!changeHasUiScenarios(changeDir)) {
+      console.log("[assess-demo-implementation-coverage] PASS（无 UI）");
+      process.exit(0);
+    }
+    fail(["缺少 design.md"]);
+  }
+
+  const design = fs.readFileSync(designPath, "utf8");
+  const parsed = parseDemoReferenceSection(design);
+  if (parsed.exempt) {
+    console.log(`[assess-demo-implementation-coverage] PASS（豁免） ${parsed.exempt}`);
+    process.exit(0);
+  }
+
+  if (!changeHasUiScenarios(changeDir)) {
+    console.log("[assess-demo-implementation-coverage] PASS（无 UI Scenario）");
+    process.exit(0);
+  }
+
+  const errors = [];
+  if (!parsed.hasSection) errors.push("design.md 缺少 ## 演示代码参照");
+  if (parsed.mappings.length === 0) errors.push("演示模块映射表为空");
+
+  const tasksPath = path.join(changeDir, "tasks.md");
+  const tasks = fs.existsSync(tasksPath) ? fs.readFileSync(tasksPath, "utf8") : "";
+  if (!/演示模块迁移/.test(tasks)) {
+    errors.push("tasks.md 缺少「演示模块迁移」段");
+  }
+
+  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 code = stripComments(fs.readFileSync(abs, "utf8"));
+    const missing = m.interactionSignals.filter((s) => !code.includes(s));
+    if (m.interactionSignals.length > 0 && missing.length === m.interactionSignals.length) {
+      errors.push(
+        `${m.moduleName}: ${rel} 未实现演示中的关键交互（${m.interactionSignals.join("、")}）`,
+      );
+    } else if (missing.length > 0) {
+      errors.push(`${m.moduleName}: ${rel} 缺少: ${missing.join("、")}`);
+    }
+  }
+
+  if (errors.length > 0) fail(errors);
+  console.log(
+    `[assess-demo-implementation-coverage] PASS change=${change} modules=${parsed.mappings.length}`,
+  );
+}
+
+main();

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

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * E2E 断言深度门禁：change 级 spec 须含 page.goto + 数据/交互断言；拒绝 prd-atoms 伪覆盖。
+ *
+ * 用法: node scripts/assess-e2e-assertion-depth.mjs --change <change-name>
+ */
+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");
+const UI_SCENARIO_KEYWORDS =
+  /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|导出|筛选|输入框|对话框|导航|toast|截图/i;
+const E2E_SPEC_RE = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+
+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 readChangeArtifacts(changeDir) {
+  const parts = {};
+  let blob = "";
+  for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    const content = fs.readFileSync(fp, "utf8");
+    parts[f] = content;
+    blob += `${content}\n`;
+  }
+  return { parts, blob };
+}
+
+function analyzeDeltaSpecs(changeDir) {
+  const specsDir = path.join(changeDir, "specs");
+  let uiScenarioCount = 0;
+  if (!fs.existsSync(specsDir)) return { uiScenarioCount };
+  for (const cap of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (!cap.isDirectory()) continue;
+    const specPath = path.join(specsDir, cap.name, "spec.md");
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    const blocks = content.split(/^####\s+Scenario:/m);
+    for (let i = 1; i < blocks.length; i += 1) {
+      if (UI_SCENARIO_KEYWORDS.test(blocks[i])) uiScenarioCount += 1;
+    }
+  }
+  return { uiScenarioCount };
+}
+
+function collectChangeE2eSpecs(changeName, changeDir) {
+  const specs = new Set();
+  const { blob } = readChangeArtifacts(changeDir);
+  let m;
+  const re = new RegExp(E2E_SPEC_RE.source, "g");
+  while ((m = re.exec(blob)) !== null) {
+    const rel = m[0];
+    if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+  }
+  if (fs.existsSync(CONFIG_PATH)) {
+    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    const overrides = config.changeNameToSpecs?.[changeName];
+    if (overrides) {
+      for (const raw of overrides) {
+        const rel = raw.startsWith("e2e/") ? raw : `e2e/${raw}`;
+        if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+      }
+    }
+  }
+  return [...specs].sort();
+}
+
+function fail(messages) {
+  console.error("[assess-e2e-assertion-depth] FAIL");
+  for (const msg of messages) console.error(`  - ${msg}`);
+  console.error(
+    "  修复: 在 change 级 e2e spec 中补充 page.goto、waitForResponse/getByRole(cell)/toContainText 或 click 等断言；",
+  );
+  console.error("  禁止用 prd-atoms-coverage 登记代替真实 E2E；纯后端 change 可 PLAYWRIGHT_E2E_EXEMPT");
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_E2E_ASSERTION_DEPTH ||
+    process.env.OPSX_SKIP_E2E_ASSERTION_DEPTH;
+  if (skip === "1") {
+    console.warn("[assess-e2e-assertion-depth] SKIP");
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-e2e-assertion-depth] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-e2e-assertion-depth] 活跃 change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  const { parts } = readChangeArtifacts(changeDir);
+  const tasksContent = parts["tasks.md"] || "";
+  if (/^PLAYWRIGHT_E2E_EXEMPT:/m.test(tasksContent)) {
+    console.log(`[assess-e2e-assertion-depth] PASS（豁免） change=${change}`);
+    process.exit(0);
+  }
+
+  const { uiScenarioCount } = analyzeDeltaSpecs(changeDir);
+  const specPaths = collectChangeE2eSpecs(change, changeDir);
+
+  if (uiScenarioCount === 0 && specPaths.length === 0) {
+    console.log(`[assess-e2e-assertion-depth] PASS（无 UI e2e 要求） change=${change}`);
+    process.exit(0);
+  }
+
+  const errors = [];
+  if (uiScenarioCount > 0 && specPaths.length === 0) {
+    errors.push(`含 ${uiScenarioCount} 个 UI Scenario 但未绑定 e2e/*.spec.ts`);
+  }
+
+  for (const rel of specPaths) {
+    const content = fs.readFileSync(path.join(ROOT, rel), "utf8");
+    const depth = analyzeE2eSpecDepth(rel, content);
+    if (!depth.ok) {
+      errors.push(`${rel}: ${depth.issues.join("; ")}`);
+    }
+  }
+
+  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(
+    `[assess-e2e-assertion-depth] PASS change=${change} specs=${specPaths.join(" ")}`,
+  );
+}
+
+main();

package/scripts/assess-playwright-e2e-coverage.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * 校验 OpenSpec change 的 Playwright E2E 覆盖是否足以验收本 change（防 module 回退钻漏洞）。
+ *
+ * 规则摘要：
+ * - delta specs 含 UI 类 Scenario 时，tasks/proposal/design 或 changeNameToSpecs 必须声明可执行的 e2e/*.spec.ts
+ * - scope=change 将回退 module 且存在 UI Scenario 时，默认 FAIL（须显式 POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK=1 豁免）
+ *
+ * 用法: node scripts/assess-playwright-e2e-coverage.mjs --change <change-name>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG_PATH = path.join(ROOT, "e2e/e2e-scope.config.json");
+
+/** UI / 浏览器交互类关键词（出现在 delta Scenario 时强制要求 change 级 e2e spec） */
+const UI_SCENARIO_KEYWORDS =
+  /上传|点击|页面|按钮|弹窗|拖拽|选择文件|附件|输入框|对话框|导航|展示|卡片|加载|选文件|文件选择|工作台|Composer|toast|截图/i;
+
+/** tasks 中「单测代替集成」的典型反模式 */
+const MOCK_COVERS_INTEGRATION_RE =
+  /单测.*覆盖|mock.*覆盖|组件单测.*集成|子组件单测|仅靠.*单测/i;
+
+function loadConfig() {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+}
+
+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 findChangeDir(changeName) {
+  const active = path.join(ROOT, "openspec/changes", changeName);
+  if (fs.existsSync(active)) return active;
+  return null;
+}
+
+function readChangeArtifacts(changeDir) {
+  const files = ["tasks.md", "proposal.md", "design.md"];
+  const parts = {};
+  let blob = "";
+  for (const f of files) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    const content = fs.readFileSync(fp, "utf8");
+    parts[f] = content;
+    blob += `${content}\n`;
+  }
+  return { parts, blob };
+}
+
+/** 统计 delta specs 中的 Scenario 数量，并检测是否含 UI 交互描述 */
+function analyzeDeltaSpecs(changeDir) {
+  const specsDir = path.join(changeDir, "specs");
+  let scenarioCount = 0;
+  let uiScenarioCount = 0;
+  let deltaBlob = "";
+
+  if (!fs.existsSync(specsDir)) {
+    return { scenarioCount, uiScenarioCount, deltaBlob };
+  }
+
+  for (const cap of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (!cap.isDirectory()) continue;
+    const specPath = path.join(specsDir, cap.name, "spec.md");
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    deltaBlob += `${content}\n`;
+    const blocks = content.split(/^####\s+Scenario:/m);
+    for (let i = 1; i < blocks.length; i += 1) {
+      scenarioCount += 1;
+      if (UI_SCENARIO_KEYWORDS.test(blocks[i])) {
+        uiScenarioCount += 1;
+      }
+    }
+  }
+  return { scenarioCount, uiScenarioCount, deltaBlob };
+}
+
+/** 从 change 文档与配置收集本 change 绑定的 e2e spec 路径（须文件存在） */
+function collectChangeE2eSpecs(changeName, changeDir, config) {
+  const specs = new Set();
+  const specRe = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+
+  if (changeDir) {
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+      const fp = path.join(changeDir, f);
+      if (!fs.existsSync(fp)) continue;
+      const content = fs.readFileSync(fp, "utf8");
+      let m;
+      while ((m = specRe.exec(content)) !== null) {
+        const rel = m[0];
+        if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+      }
+    }
+  }
+
+  const overrides = config.changeNameToSpecs?.[changeName];
+  if (overrides) {
+    for (const raw of overrides) {
+      const rel = raw.startsWith("e2e/") ? raw : `e2e/${raw}`;
+      if (fs.existsSync(path.join(ROOT, rel))) specs.add(rel);
+    }
+  }
+  return [...specs].sort();
+}
+
+function hasExempt(tasksContent) {
+  if (!tasksContent) return { tdd: false, playwright: false };
+  const tdd = /^TDD_EXEMPT:/m.test(tasksContent);
+  const playwright = /^PLAYWRIGHT_E2E_EXEMPT:/m.test(tasksContent);
+  return { tdd, playwright };
+}
+
+function wouldModuleFallback(changeName, specPaths, config) {
+  if (specPaths.length > 0) return false;
+  const fallback = config.changeScopeFallback ?? "module";
+  return fallback === "module";
+}
+
+function fail(messages) {
+  console.error("[assess-playwright-e2e-coverage] FAIL");
+  for (const msg of messages) {
+    console.error(`  - ${msg}`);
+  }
+  console.error(
+    "  修复: 在 tasks.md 增加 E.1/E.2（写明 e2e/*.spec.ts 路径），或 e2e-scope.config.json → changeNameToSpecs；",
+  );
+  console.error(
+    "  纯无 UI 交互可声明 PLAYWRIGHT_E2E_EXEMPT: <原因>；module 回退须 POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK=1",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_PLAYWRIGHT_CHANGE_COVERAGE ||
+    process.env.OPSX_SKIP_PLAYWRIGHT_CHANGE_COVERAGE;
+  if (skip === "1") {
+    console.warn(
+      "[assess-playwright-e2e-coverage] SKIP: POQUAN_SKIP_PLAYWRIGHT_CHANGE_COVERAGE=1",
+    );
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-playwright-e2e-coverage] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = findChangeDir(change);
+  if (!changeDir) {
+    console.error(
+      `[assess-playwright-e2e-coverage] 活跃 change 不存在: openspec/changes/${change}`,
+    );
+    process.exit(2);
+  }
+
+  const config = loadConfig();
+  const { parts, blob: artifactBlob } = readChangeArtifacts(changeDir);
+  const { scenarioCount, uiScenarioCount, deltaBlob } = analyzeDeltaSpecs(changeDir);
+  const exempt = hasExempt(parts["tasks.md"]);
+  const specPaths = collectChangeE2eSpecs(change, changeDir, config);
+  const moduleFallback = wouldModuleFallback(change, specPaths, config);
+  const allowFallback =
+    process.env.POQUAN_ALLOW_PLAYWRIGHT_MODULE_FALLBACK === "1" ||
+    process.env.OPSX_ALLOW_PLAYWRIGHT_MODULE_FALLBACK === "1";
+
+  if (exempt.tdd || exempt.playwright) {
+    console.log(
+      `[assess-playwright-e2e-coverage] PASS（豁免） change=${change} ` +
+        `TDD_EXEMPT=${exempt.tdd} PLAYWRIGHT_E2E_EXEMPT=${exempt.playwright}`,
+    );
+    process.exit(0);
+  }
+
+  const errors = [];
+  const requiresChangeE2e = uiScenarioCount > 0;
+
+  if (requiresChangeE2e && specPaths.length === 0) {
+    errors.push(
+      `delta 含 ${uiScenarioCount} 个 UI/浏览器交互 Scenario，但未在 tasks/proposal/design 或 changeNameToSpecs 中绑定 e2e/*.spec.ts`,
+    );
+  }
+
+  if (requiresChangeE2e && moduleFallback && !allowFallback) {
+    errors.push(
+      `scope=change 将回退 module 目录（changeScopeFallback=module），无法验收本 change 的 UI Scenario；禁止用模块 smoke 代替 change 验收`,
+    );
+  }
+
+  const tasksContent = parts["tasks.md"] || "";
+  if (
+    requiresChangeE2e &&
+    MOCK_COVERS_INTEGRATION_RE.test(tasksContent) &&
+    !/\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/.test(tasksContent)
+  ) {
+    errors.push(
+      "tasks.md 声称「单测/mock 覆盖集成」但未写明 e2e/*.spec.ts；DOM/Network 交互类功能禁止仅用 mock 单测宣布验收",
+    );
+  }
+
+  if (requiresChangeE2e && specPaths.length > 0) {
+    const hasE2eTask =
+      /E\.1|E2E|playwright test|e2e\/[\w/.-]+\.spec/.test(tasksContent);
+    if (!hasE2eTask) {
+      errors.push(
+        `已配置 e2e spec（${specPaths.join(", ")}），但 tasks.md 缺少 E.1/E.2 Playwright 验收项`,
+      );
+    }
+  }
+
+  if (scenarioCount > 0 && uiScenarioCount === 0 && specPaths.length === 0 && moduleFallback) {
+    console.warn(
+      `[assess-playwright-e2e-coverage] WARN change=${change}: ` +
+        `${scenarioCount} 个 Scenario 未命中 UI 关键词，将允许 module 回退；若含隐式 UI 行为请补 e2e spec`,
+    );
+  }
+
+  if (errors.length > 0) {
+    fail(errors);
+  }
+
+  console.log(
+    `[assess-playwright-e2e-coverage] PASS change=${change} ` +
+      `scenarios=${scenarioCount} uiScenarios=${uiScenarioCount} ` +
+      `e2eSpecs=${specPaths.length > 0 ? specPaths.join(" ") : "(none)"} ` +
+      `moduleFallback=${moduleFallback}`,
+  );
+}
+
+main();

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

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * 校验 04-技术文档草稿.md 是否符合模板结构（gate docs-closed 同款规则）。
+ *
+ * 用法: node scripts/assess-tech-doc-quality.mjs --run-dir <openspec/PRD/runId>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const REQUIRED = [
+  { label: "文档元信息", re: /##\s*文档元信息/m },
+  { label: "1. 改造范围", re: /##\s*1\.\s*改造范围/m },
+  { label: "2. 页面与交互设计", re: /##\s*2\.\s*页面与交互设计/m },
+  { label: "2.4 演示代码参照", re: /###\s*2\.4\s*演示代码参照/m },
+  { label: "3. 前端状态与数据模型设计", re: /##\s*3\.\s*前端状态与数据模型设计/m },
+  { label: "4. 接口与数据交互设计", re: /##\s*4\.\s*接口与数据交互设计/m },
+  { label: "5. 表单与校验设计", re: /##\s*5\.\s*表单与校验设计/m },
+  { label: "6. 异常、边界与降级方案", re: /##\s*6\.\s*异常、边界与降级方案/m },
+  { label: "7. 改造清单", re: /##\s*7\.\s*改造清单/m },
+  { label: "8. 风险点与应对策略", re: /##\s*8\.\s*风险点与应对策略/m },
+  { label: "9. 发布、灰度与回滚", re: /##\s*9\.\s*发布、灰度与回滚/m },
+  { label: "10. 测试与验收要点", re: /##\s*10\.\s*测试与验收要点/m },
+  { label: "11. 待确认事项", re: /##\s*11\.\s*待确认事项/m },
+];
+
+const MIN_LINES = 150;
+
+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-tech-doc-quality] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error("  修复: 在现有 04-技术文档草稿.md 模板上逐节填写，见 04-技术文档生成指引.md");
+  process.exit(1);
+}
+
+function main() {
+  const skip = process.env.OPSX_SKIP_TECH_DOC_QUALITY;
+  if (skip === "1") {
+    console.warn("[assess-tech-doc-quality] SKIP");
+    process.exit(0);
+  }
+
+  const { runDir } = parseArgs(process.argv);
+  if (!runDir) {
+    console.error("[assess-tech-doc-quality] 缺少 --run-dir <openspec/PRD/runId>");
+    process.exit(2);
+  }
+
+  const absRun = path.isAbsolute(runDir) ? runDir : path.join(ROOT, runDir);
+  const docPath = path.join(absRun, "04-技术文档草稿.md");
+  if (!fs.existsSync(docPath)) {
+    fail(["04-技术文档草稿.md 不存在"]);
+  }
+
+  const content = fs.readFileSync(docPath, "utf8");
+  const lines = content.split("\n");
+  const errors = [];
+
+  if (lines.length < MIN_LINES) {
+    errors.push(`行数 ${lines.length} < ${MIN_LINES}，疑似摘要版而非完整技术文档`);
+  }
+
+  for (const sec of REQUIRED) {
+    if (!sec.re.test(content)) errors.push(`缺少章节: ${sec.label}`);
+  }
+
+  if (!/\|\s*接口\s*\|\s*Method\s*\|/m.test(content)) {
+    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 演示模块映射表格");
+  }
+
+  if (errors.length > 0) fail(errors);
+  console.log(`[assess-tech-doc-quality] PASS lines=${lines.length} path=${docPath}`);
+}
+
+main();