sdd-flow-kit 1.3.14 → 1.3.18

package/dist/steps/setupProject.js

@@ -134,6 +134,7 @@ async function installAgentSkill(projectRoot, projectKind) {
         return;
     const template = await (0, templates_1.loadTemplateText)("artifacts/06-agent-skill.template.md");
     const layered = await (0, templates_1.loadTemplateText)("skills/layered-testing-strategy.md");
+    const demoRef = await (0, templates_1.loadTemplateText)("skills/demo-reference-mandatory-workflow.md");
     for (const target of targets) {
         const agentName = target.includes("/.cursor/")
             ? "cursor"
@@ -150,6 +151,30 @@ async function installAgentSkill(projectRoot, projectKind) {
         await (0, fs_1.writeTextFileEnsuredDir)(target, content);
         const layeredPath = path_1.default.join(path_1.default.dirname(target), "LAYERED-TESTING.md");
         await (0, fs_1.writeTextFileEnsuredDir)(layeredPath, layered);
+        const demoRefPath = path_1.default.join(path_1.default.dirname(target), "DEMO-REFERENCE-WORKFLOW.md");
+        await (0, fs_1.writeTextFileEnsuredDir)(demoRefPath, demoRef);
+    }
+}
+async function installSddVersionTriggerRule(projectRoot, agent) {
+    const template = await (0, templates_1.loadTemplateText)("rules/sdd-version-trigger.mdc.template");
+    const content = renderVars(template, {
+        AGENT_NAME: agent,
+    });
+    if (agent === "cursor" || agent === "custom") {
+        const rulePath = path_1.default.join(projectRoot, ".cursor", "rules", "00-sdd-flow-kit-version-trigger.mdc");
+        await (0, fs_1.writeTextFileEnsuredDir)(rulePath, content);
+    }
+}
+async function installSddVersionTriggerSkills(projectRoot) {
+    const template = await (0, templates_1.loadTemplateText)("skills/version-trigger.SKILL.md.template");
+    const targets = [
+        { agent: "cursor", relPath: ".cursor/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "claude-code", relPath: ".claude/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "codex", relPath: ".codex/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "openclaw", relPath: ".openclaw/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+    ];
+    for (const target of targets) {
+        await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(projectRoot, target.relPath), renderVars(template, { AGENT_NAME: target.agent }));
     }
 }
 async function installSddCursorRule(projectRoot) {
@@ -343,6 +368,8 @@ async function setupProject(options) {
         const { dir } = docSkillDirName(selectedKind);
         plannedActions.push(`would install docs skill: ${path_1.default.join(installRoot, "docs", dir)}`);
         plannedActions.push(`would install opsx config: ${path_1.default.join(installRoot, ".opsx", "config.json")}`);
+        plannedActions.push(`would install highest-priority version trigger rule: ${path_1.default.join(installRoot, ".cursor", "rules", "00-sdd-flow-kit-version-trigger.mdc")}`);
+        plannedActions.push("would install cross-agent version trigger skills: cursor/claude-code/codex/openclaw");
         plannedActions.push(`would install cursor rule: ${path_1.default.join(installRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc")}`);
     }
     else {
@@ -352,6 +379,10 @@ async function setupProject(options) {
             plannedActions.push("added pnpm.onlyBuiltDependencies: sdd-flow-kit");
         }
         await installAgentSkill(installRoot, selectedKind);
+        await installSddVersionTriggerRule(installRoot, selectedAgent);
+        await installSddVersionTriggerSkills(installRoot);
+        plannedActions.push("installed highest-priority version trigger rule (.cursor/rules/00-sdd-flow-kit-version-trigger.mdc)");
+        plannedActions.push("installed cross-agent version trigger skills (cursor/claude-code/codex/openclaw)");
         await installSddCursorRule(installRoot);
         skillInstalled = true;
         await installDocsSkill(installRoot, selectedKind);

package/dist/steps/startFlow.js

@@ -10,6 +10,7 @@ const utils_1 = require("../core/utils");
 const fs_1 = require("../core/fs");
 const templates_1 = require("../core/templates");
 const inferProject_1 = require("../core/inferProject");
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
 const sessionState_1 = require("../core/sessionState");
 const projectRoots_1 = require("../core/projectRoots");
 const writeNext_1 = require("../core/writeNext");
@@ -30,12 +31,14 @@ async function startFlowScaffold(options) {
     // 1) Step1: doc-skill 指引（按产品解析脚本路径，支持 monorepo frontend）
     const kind = (0, inferProject_1.productToKind)(options.product);
     const docSkill = await (0, inferProject_1.resolveDocSkillDir)(options.projectRoot, kind);
+    const syncSourceDirRel = await (0, syncSourcePrd_1.resolveSyncSourceDirRel)(options.projectRoot, sourceDir, options.product);
     const step1Template = await (0, templates_1.loadTemplateText)("artifacts/01-adi-doc-skill-指引.template.md");
     const step1 = renderTemplate(step1Template, {
         PRODUCT: options.product,
         PRODUCT_PREFIX: inferProject_1.PRODUCT_PREFIX_BY_KIND[kind],
         DOC_SKILL_REL: docSkill.relFromRoot.replace(/\\/g, "/"),
         VERSION_EXAMPLE: options.version,
+        SYNC_SOURCE_DIR_REL: syncSourceDirRel,
     });
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "01-获取需求文档指引.md"), step1);
     // source 占位：让第 2 步提示词在任何工具里都能直接读
@@ -74,9 +77,11 @@ async function startFlowScaffold(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "02-改动点清单.md"), file02Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "03-待确认问题清单.md"), file03Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "05-验收清单.md"), file05Template);
-    // 4) Step4 技术文档入口（草稿）
+    // 4) Step4 技术文档入口（完整模板 + 填写指引）
     const techDocTemplate = await (0, templates_1.loadTemplateText)("artifacts/04-技术文档.template.md");
     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);
     // 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);
@@ -118,7 +123,7 @@ async function startFlowScaffold(options) {
         "用户确认后产出（顺序重要）：",
         "- `03-待确认问题清单.md`（已闭合）",
         "- `05-验收清单.md`（从 `source/PRD.md` 逐条抽取 AC，标注「定义状态：已定义」）",
-        "- `04-技术文档草稿.md`（引用 AC-ID）",
+        "- `04-技术文档草稿.md`（**在脚手架模板原文件上逐节填写**，见 `04-技术文档生成指引.md`；禁止摘要替换）",
         "- `01-需求分析报告.md`（业务概述，非验收 SSOT）",
         "- `02-改动点清单.md`",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.3.14",
+  "version": "1.3.18",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",
@@ -12,6 +12,7 @@
   "files": [
     "dist",
     "src/templates",
+    "scripts",
     "README.md"
   ],
   "bin": {

package/scripts/assert-active-openspec-change.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# 校验：改动 src/ 或 e2e/ 时必须绑定活跃 OpenSpec change（见 AGENTS.md）
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+WATCH_PATHS=('src/' 'e2e/')
+CHANGE_DIR_PREFIX="openspec/changes"
+ACTIVE_CHANGE_FILES=('.opsx-active-change' '.poquan-active-change')
+
+log() { printf '[opsx:gate] %s\n' "$*"; }
+die() { log "ERROR: $*"; exit 1; }
+
+path_is_watched() {
+  local path="$1"
+  local prefix
+  for prefix in "${WATCH_PATHS[@]}"; do
+    if [[ "$path" == "$prefix"* ]] || [[ "$path" == */"$prefix"* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+collect_candidate_files() {
+  CANDIDATE_FILES=()
+  if [[ "${1:-}" == "--ci" ]]; then
+    local base="${GITHUB_BASE_REF:-main}"
+    base="${base#origin/}"
+    git fetch origin "$base" --depth=1 2>/dev/null || true
+    local merge_base
+    merge_base="$(git merge-base "origin/${base}" HEAD 2>/dev/null || git merge-base "${base}" HEAD 2>/dev/null || echo "")"
+    [[ -n "$merge_base" ]] || merge_base="HEAD~1"
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+    done < <(git diff --name-only "$merge_base"...HEAD 2>/dev/null || git diff --name-only HEAD~1 HEAD)
+  else
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+    done < <(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+    if [[ ${#CANDIDATE_FILES[@]} -eq 0 ]]; then
+      while IFS= read -r line; do
+        [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+      done < <(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null || true)
+    fi
+  fi
+}
+
+has_watched_changes() {
+  local file
+  for file in "${CANDIDATE_FILES[@]}"; do
+    if path_is_watched "$file"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+resolve_change_name() {
+  if [[ -n "${OPSX_ACTIVE_CHANGE:-}" ]]; then
+    echo "$OPSX_ACTIVE_CHANGE"
+    return 0
+  fi
+  if [[ -n "${POQUAN_ACTIVE_CHANGE:-}" ]]; then
+    echo "$POQUAN_ACTIVE_CHANGE"
+    return 0
+  fi
+  local file name
+  for file in "${ACTIVE_CHANGE_FILES[@]}"; do
+    if [[ -f "$file" ]]; then
+      name="$(tr -d '[:space:]' <"$file")"
+      [[ -n "$name" ]] && { echo "$name"; return 0; }
+    fi
+  done
+  local branch
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+  if [[ "$branch" =~ ^change/([^/]+) ]]; then
+    echo "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+validate_change_dir() {
+  local name="$1"
+  local dir="${CHANGE_DIR_PREFIX}/${name}"
+  [[ -d "$dir" ]] || die "change 目录不存在: ${dir}（请先 Propose 或设置 OPSX_ACTIVE_CHANGE）"
+  [[ "$dir" != *"/archive/"* ]] || die "change 已归档，请新建 change: ${name}"
+  if [[ -f "${dir}/tasks.md" ]] && grep -q '^- \[ \]' "${dir}/tasks.md" 2>/dev/null; then
+    log "WARN: tasks.md 仍有未完成项；合码前建议全部勾选并跑 delivery-pipeline"
+  fi
+}
+
+main() {
+  if [[ "${OPSX_SKIP_OPSX:-}" == "1" ]] || [[ "${POQUAN_SKIP_OPSX:-}" == "1" ]]; then
+    log "已跳过（OPSX_SKIP_OPSX 或 POQUAN_SKIP_OPSX=1）"
+    exit 0
+  fi
+
+  collect_candidate_files "${1:-}"
+  if ! has_watched_changes; then
+    log "无 src/ 或 e2e/ 改动，跳过"
+    exit 0
+  fi
+
+  local change_name
+  change_name="$(resolve_change_name)" || die "改动 src/e2e 但未绑定 OpenSpec change。请先 Propose，或设置 OPSX_ACTIVE_CHANGE / .opsx-active-change / 分支 change/<name>。详见 AGENTS.md"
+
+  validate_change_dir "$change_name"
+  log "OK — 活跃 change: ${change_name}"
+}
+
+main "$@"

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * API 字段契约门禁：change 引用的 config/api/modules 须含 snake/camel normalize（防 SNAKE_CASE 漏映射）。
+ *
+ * 用法: node scripts/assess-api-field-contract.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 NORMALIZE_MARKERS =
+  /snakeToCamel|camelToSnake|normalizeFinanceApiResult|normalize\w*Api|caseTransform|toCamelCase|toSnakeCase/i;
+const API_CLIENT_CALL_RE = /\b(?:apiClient|request|post|get)\s*[.(]/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 readChangeBlob(changeDir) {
+  let blob = "";
+  for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    blob += fs.readFileSync(fp, "utf8");
+  }
+  return blob;
+}
+
+function resolveModuleFile(mod) {
+  const candidates = [
+    path.join(ROOT, "src/config/api/modules", mod, "index.ts"),
+    path.join(ROOT, "frontend/src/config/api/modules", mod, "index.ts"),
+    path.join(ROOT, "src/config/api/modules", `${mod}.ts`),
+    path.join(ROOT, "frontend/src/config/api/modules", `${mod}.ts`),
+  ];
+  for (const fp of candidates) {
+    if (fs.existsSync(fp)) return fp;
+  }
+  return null;
+}
+
+function fail(messages) {
+  console.error("[assess-api-field-contract] FAIL");
+  for (const msg of messages) console.error(`  - ${msg}`);
+  console.error(
+    "  修复: 在 config/api/modules/<domain> 对请求体 camelToSnake、响应 data snakeToCamel；参考 finance/caseTransform.ts",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_API_FIELD_CONTRACT ||
+    process.env.OPSX_SKIP_API_FIELD_CONTRACT;
+  if (skip === "1") {
+    console.warn("[assess-api-field-contract] SKIP");
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-api-field-contract] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-api-field-contract] change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  const blob = readChangeBlob(changeDir);
+  const moduleRefs = new Set();
+  const modRe = /config\/api\/modules\/([\w/-]+)/g;
+  let m;
+  while ((m = modRe.exec(blob)) !== null) {
+    moduleRefs.add(m[1].replace(/\/index$/, ""));
+  }
+
+  if (moduleRefs.size === 0) {
+    console.log(`[assess-api-field-contract] PASS（无 API 模块引用） change=${change}`);
+    process.exit(0);
+  }
+
+  const errors = [];
+  const passed = [];
+  for (const mod of moduleRefs) {
+    const fp = resolveModuleFile(mod);
+    if (!fp) {
+      errors.push(`config/api/modules/${mod} 引用但文件不存在`);
+      continue;
+    }
+    const rel = path.relative(ROOT, fp).replace(/\\/g, "/");
+    const content = fs.readFileSync(fp, "utf8");
+    if (!API_CLIENT_CALL_RE.test(content)) {
+      passed.push(`${rel}（无 HTTP 调用）`);
+      continue;
+    }
+    if (!NORMALIZE_MARKERS.test(content)) {
+      errors.push(`${rel} 含 API 调用但未发现字段 normalize`);
+    } else {
+      passed.push(rel);
+    }
+  }
+
+  if (errors.length > 0) fail(errors);
+  console.log(
+    `[assess-api-field-contract] PASS change=${change} modules=${passed.join(", ")}`,
+  );
+}
+
+main();

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,146 @@
+#!/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";
+
+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("; ")}`);
+    }
+  }
+
+  if (errors.length > 0) fail(errors);
+
+  console.log(
+    `[assess-e2e-assertion-depth] PASS change=${change} specs=${specPaths.join(" ")}`,
+  );
+}
+
+main();