sdd-flow-kit 1.3.15 → 1.3.21

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,8 @@ 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) {

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,13 @@ 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);
+    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);
@@ -118,7 +125,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.15",
+  "version": "1.3.21",
   "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-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

@@ -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$/, "").replace(/\/$/, ""));
+  }
+
+  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-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();