sdd-flow-kit 1.3.15 → 1.3.18

package/dist/core/prdCoverage.js

@@ -15,6 +15,10 @@ const acMatrix_1 = require("./acMatrix");
 const fs_1 = require("./fs");
 const prdParse_1 = require("./prdParse");
 const prdSemanticDiff_1 = require("./prdSemanticDiff");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const e2eAssertionDepth_1 = require("./e2eAssertionDepth");
+const apiFieldContract_1 = require("./apiFieldContract");
+const demoImplementationCoverage_1 = require("./demoImplementationCoverage");
 const VALID_VERDICTS = ["一致", "不一致-按PRD修复", "待人工确认"];
 /** 禁止在证据/结论中出现的揣摩或兜底措辞 */
 const FORBIDDEN_SPECULATION = [
@@ -99,6 +103,22 @@ function hasForbiddenSpeculation(text) {
     }
     return null;
 }
+/** 08 报告中的无效/敷衍证据（如 index.vue:1、prd-atoms 注释覆盖） */
+function isWeakCodeEvidence(evidence) {
+    const e = evidence.trim();
+    if (!e)
+        return "空证据";
+    if (/:(1|2)\s*(\||$)/.test(e) && !/expect\(|getByText|getByRole|message\.|toast/.test(e)) {
+        return "证据仅指向文件首行，无具体交互/断言";
+    }
+    if (/prd-atoms-coverage|semantic-registry/i.test(e)) {
+        return "伪覆盖登记文件不能作为实现证据";
+    }
+    if (/index\.vue:1|index\.tsx:1/i.test(e) && e.split(/[;；]/).length < 2) {
+        return "禁止用列表页首行代替详情子模块证据";
+    }
+    return null;
+}
 async function writePrdAtomsManifest(outputRoot, atoms) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, ".prd-review-atoms.json"), `${JSON.stringify({ count: atoms.length, atoms }, null, 2)}\n`);
 }
@@ -118,18 +138,16 @@ async function loadPrdAtomsFromManifest(outputRoot) {
 function checkAcTestMapping(items, testContents) {
     var _a;
     const checks = [];
-    // P0 全量 + 所有声明 e2e 的 AC（含 P1/P2 边缘场景）
     const mustCover = items.filter((i) => { var _a; return /^P0$/i.test(i.priority.trim()) || /e2e/i.test((_a = i.testType) !== null && _a !== void 0 ? _a : ""); });
     for (const ac of mustCover) {
-        const bracket = `[${ac.id}]`;
-        const hits = testContents.filter((t) => t.content.includes(bracket) || t.content.includes(ac.id));
         const e2eRequired = /e2e/i.test((_a = ac.testType) !== null && _a !== void 0 ? _a : "");
-        const e2eHits = hits.filter((h) => E2E_DIR_RE.test(h.file.replace(/\\/g, "/")));
+        const hits = testContents.filter((t) => (0, testAssertionAnalysis_1.hasMeaningfulAcCoverageInFile)(t.rel, t.content, ac.id).covered);
+        const e2eHits = hits.filter((h) => E2E_DIR_RE.test(h.rel));
         if (hits.length === 0) {
             checks.push({
                 name: `ac-test-${ac.id}`,
                 ok: false,
-                detail: `${ac.id}(${ac.priority}) 未在测试文件中找到 [${ac.id}] 映射`,
+                detail: `${ac.id}(${ac.priority}) 未在有效 test/it 块中找到 [${ac.id}] + expect 映射（注释登记不计入）`,
             });
             continue;
         }
@@ -137,7 +155,7 @@ function checkAcTestMapping(items, testContents) {
             checks.push({
                 name: `ac-e2e-${ac.id}`,
                 ok: false,
-                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 或 playwright/ 下无对应测试`,
+                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 或 playwright/ 下无含 expect 的对应测试`,
             });
             continue;
         }
@@ -145,8 +163,8 @@ function checkAcTestMapping(items, testContents) {
             name: `ac-test-${ac.id}`,
             ok: true,
             detail: e2eRequired
-                ? `${ac.id} 已映射（含 e2e: ${e2eHits.map((h) => path_1.default.basename(h.file)).join(", ")})`
-                : `${ac.id} 已映射: ${hits.map((h) => path_1.default.basename(h.file)).join(", ")}`,
+                ? `${ac.id} 已映射（含 e2e: ${e2eHits.map((h) => path_1.default.basename(h.rel)).join(", ")})`
+                : `${ac.id} 已映射: ${hits.map((h) => path_1.default.basename(h.rel)).join(", ")}`,
         });
     }
     return checks;
@@ -246,7 +264,7 @@ function checkSemanticDiffItems(semantic) {
 /**
  * gate prd-coverage：PRD 最细粒度条目全覆盖 + 08 复查报告合规 + P0 AC 测试映射。
  */
-async function checkPrdCoverage(outputRoot, pkgRoot) {
+async function checkPrdCoverage(outputRoot, pkgRoot, options) {
     const checks = [];
     const prdContent = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "source", "PRD.md"));
     if (!prdContent) {
@@ -314,6 +332,7 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
     const needHuman = [];
     const speculationHits = [];
     const emptyEvidence = [];
+    const weakEvidence = [];
     for (const atom of atoms) {
         const row = rowById.get(atom.id);
         if (!row)
@@ -329,6 +348,11 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
         if (!evidence || evidence.length < 8 || /（填写）|待填写|TBD/i.test(evidence)) {
             emptyEvidence.push(atom.id);
         }
+        if (row.verdict === "一致") {
+            const weak = isWeakCodeEvidence(evidence);
+            if (weak)
+                weakEvidence.push(`${atom.id}(${weak})`);
+        }
         const combined = `${row.codeEvidence} ${row.note} ${row.verdict}`;
         const forbidden = hasForbiddenSpeculation(combined);
         if (forbidden)
@@ -355,6 +379,13 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
             ? "每条均有可核对代码证据（文件路径+行号/选择器/断言）"
             : `缺少代码证据: ${emptyEvidence.slice(0, 8).join(", ")}`,
     });
+    checks.push({
+        name: "code-evidence-quality",
+        ok: weakEvidence.length === 0,
+        detail: weakEvidence.length === 0
+            ? "未发现敷衍证据（index.vue:1 / prd-atoms 登记等）"
+            : `证据质量不足: ${weakEvidence.slice(0, 8).join(", ")}`,
+    });
     checks.push({
         name: "no-prd-mismatch-open",
         ok: needFix.length === 0,
@@ -385,11 +416,17 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
             var _a;
             return ({
                 file: f,
+                rel: path_1.default.relative(pkgRoot, f).replace(/\\/g, "/"),
                 content: (_a = (await (0, fs_1.readFileIfExists)(f))) !== null && _a !== void 0 ? _a : "",
             });
         }));
         checks.push(...checkAcTestMapping(acParsed.items, testContents));
     }
+    if (options === null || options === void 0 ? void 0 : options.changeName) {
+        checks.push(...(await (0, e2eAssertionDepth_1.checkE2eAssertionDepth)(pkgRoot, outputRoot, options.changeName)));
+        checks.push(...(await (0, apiFieldContract_1.checkApiFieldContract)(pkgRoot, options.changeName)));
+        checks.push(...(await (0, demoImplementationCoverage_1.checkDemoImplementationCoverage)(pkgRoot, options.changeName)));
+    }
     const ok = checks.every((c) => c.ok);
     return { ok, checks };
 }

package/dist/core/prdSemanticDiff.js

@@ -18,6 +18,7 @@ exports.writeSemanticDiffArtifacts = writeSemanticDiffArtifacts;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
 const SOURCE_EXT = /\.(vue|tsx?|jsx?|json|css|less|scss)$/i;
 const TEST_EXT = /\.(spec|test)\.(t|j)sx?$/i;
 const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
@@ -170,15 +171,17 @@ async function verifyEvidenceRefs(pkgRoot, evidence, signals) {
     }
     return { ok: true, detail: "证据路径与字面量可核对" };
 }
+/** PRD 原子须有 test/it 块内 expect 断言；禁止注释或 prd-atoms 登记类伪覆盖 */
 function hasTestCoverageForAtom(atomId, signals, testCorpus) {
     let hasTest = false;
     let hasE2e = false;
     for (const entry of testCorpus) {
-        const hasId = entry.content.includes(atomId) || entry.content.includes(`[${atomId}]`);
-        const hasSignal = signals.some((s) => s.length >= 4 && entry.content.includes(s));
-        if (hasId || hasSignal) {
+        if (!entry.isTest)
+            continue;
+        const { covered, hasE2e: fileE2e } = (0, testAssertionAnalysis_1.hasMeaningfulAtomCoverageInFile)(entry.rel, entry.content, atomId, signals);
+        if (covered) {
             hasTest = true;
-            if (entry.isE2e)
+            if (fileE2e)
                 hasE2e = true;
         }
     }

package/dist/core/syncSourcePrd.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVersionSlug = buildVersionSlug;
+exports.resolveDocsVersionDir = resolveDocsVersionDir;
+exports.findMainPrdMarkdown = findMainPrdMarkdown;
+exports.ensurePrdImageDirMetadata = ensurePrdImageDirMetadata;
+exports.syncSourcePrdFromDocs = syncSourcePrdFromDocs;
+exports.tryAutoSyncSourcePrd = tryAutoSyncSourcePrd;
+exports.resolveSyncSourceDirRel = resolveSyncSourceDirRel;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const inferProject_1 = require("./inferProject");
+const IMAGE_SUBDIR = "image";
+const PRD_PLACEHOLDER_MARKERS = ["请把《PRD》", "占位", "placeholder"];
+/**
+ * 与 confluence-doc.py 的 version_slug 保持一致：1.2.3 → adi-v123。
+ */
+function buildVersionSlug(productPrefix, version) {
+    const normalized = version
+        .trim()
+        .replace(/^[A-Z]+[-_]?V?/i, "")
+        .replace(/^V/i, "");
+    return `${productPrefix.toLowerCase()}-v${normalized.replace(/\./g, "")}`;
+}
+/**
+ * 解析 docs 下当前版本的 PRD 目录（含主文档与 image/）。
+ */
+async function resolveDocsVersionDir(projectRoot, product, version) {
+    const kind = (0, inferProject_1.productToKind)(product);
+    const prefix = inferProject_1.PRODUCT_PREFIX_BY_KIND[kind];
+    const slug = buildVersionSlug(prefix, version);
+    const docSkill = await (0, inferProject_1.resolveDocSkillDir)(projectRoot, kind);
+    const docsRoot = path_1.default.dirname(docSkill.absPath);
+    const versionDir = path_1.default.join(docsRoot, slug);
+    try {
+        const st = await promises_1.default.stat(versionDir);
+        if (!st.isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { docsRoot, versionDir, slug };
+}
+/**
+ * 在版本目录根下选取体积最大的 .md 作为主 PRD（排除子目录）。
+ */
+async function findMainPrdMarkdown(versionDir) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(versionDir);
+    }
+    catch {
+        return null;
+    }
+    const mdFiles = entries.filter((name) => name.toLowerCase().endsWith(".md"));
+    if (mdFiles.length === 0)
+        return null;
+    let best = null;
+    for (const name of mdFiles) {
+        const full = path_1.default.join(versionDir, name);
+        const st = await promises_1.default.stat(full);
+        if (!st.isFile())
+            continue;
+        if (!best || st.size > best.size) {
+            best = { name, size: st.size };
+        }
+    }
+    return best ? path_1.default.join(versionDir, best.name) : null;
+}
+/**
+ * 在 PRD 头部补充原型图片相对路径，供 OPSX UI 解析使用。
+ */
+function ensurePrdImageDirMetadata(content) {
+    if (/原型图片目录/.test(content)) {
+        return content;
+    }
+    const lines = content.split("\n");
+    const titleIdx = lines.findIndex((line) => line.trim().startsWith("# "));
+    const insertAt = titleIdx >= 0 ? titleIdx + 1 : 0;
+    const meta = `> 原型图片目录: ${IMAGE_SUBDIR}/`;
+    lines.splice(insertAt, 0, "", meta);
+    return lines.join("\n");
+}
+async function copyDirRecursive(srcDir, destDir) {
+    await promises_1.default.mkdir(destDir, { recursive: true });
+    const entries = await promises_1.default.readdir(srcDir, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        const srcPath = path_1.default.join(srcDir, entry.name);
+        const destPath = path_1.default.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            count += await copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            await promises_1.default.copyFile(srcPath, destPath);
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * 将 docs/<版本目录> 下的 PRD 主文档与 image/ 同步到 openspec run 的 source/。
+ */
+async function syncSourcePrdFromDocs(options) {
+    const resolved = await resolveDocsVersionDir(options.projectRoot, options.product, options.version);
+    if (!resolved) {
+        const slug = buildVersionSlug(inferProject_1.PRODUCT_PREFIX_BY_KIND[(0, inferProject_1.productToKind)(options.product)], options.version);
+        return {
+            ok: false,
+            attempted: true,
+            detail: `未找到 docs 版本目录（期望 docs/${slug}/，请先执行 confluence-doc.py）`,
+        };
+    }
+    const mainMd = await findMainPrdMarkdown(resolved.versionDir);
+    if (!mainMd) {
+        return {
+            ok: false,
+            attempted: true,
+            detail: `docs/${resolved.slug}/ 下无 PRD 主文档（*.md）`,
+        };
+    }
+    const sourceDir = path_1.default.join(options.outputRoot, "source");
+    const destPrd = path_1.default.join(sourceDir, "PRD.md");
+    const raw = await promises_1.default.readFile(mainMd, "utf8");
+    if (raw.trim().length < 80) {
+        return {
+            ok: false,
+            attempted: true,
+            detail: `docs 主文档过短: ${path_1.default.basename(mainMd)}`,
+        };
+    }
+    const content = ensurePrdImageDirMetadata(raw);
+    await (0, fs_1.writeTextFileEnsuredDir)(destPrd, content);
+    const srcImageDir = path_1.default.join(resolved.versionDir, IMAGE_SUBDIR);
+    const destImageDir = path_1.default.join(sourceDir, IMAGE_SUBDIR);
+    let imageCount = 0;
+    try {
+        const st = await promises_1.default.stat(srcImageDir);
+        if (st.isDirectory()) {
+            await promises_1.default.rm(destImageDir, { recursive: true, force: true });
+            imageCount = await copyDirRecursive(srcImageDir, destImageDir);
+        }
+    }
+    catch {
+        // 无图片目录不阻断同步
+    }
+    return {
+        ok: true,
+        attempted: true,
+        detail: `已同步 ${path_1.default.basename(mainMd)} → source/PRD.md${imageCount > 0 ? `，${imageCount} 张图片 → source/${IMAGE_SUBDIR}/` : "（无图片）"}`,
+        sourcePrdPath: destPrd,
+        imageCount,
+    };
+}
+/**
+ * gate 前自动同步：source/PRD.md 仍为占位且 docs 版本目录已存在时尝试回填。
+ */
+async function tryAutoSyncSourcePrd(options) {
+    const existing = await (0, fs_1.readFileIfExists)(path_1.default.join(options.outputRoot, "source", "PRD.md"));
+    if (existing && !PRD_PLACEHOLDER_MARKERS.some((m) => existing.includes(m)) && existing.trim().length >= 80) {
+        return { ok: true, attempted: false, detail: "source/PRD.md 已回填，跳过同步" };
+    }
+    return syncSourcePrdFromDocs(options);
+}
+/**
+ * 从 run 目录相对 doc-skill 脚本目录的 source 路径（供 confluence-doc.py 环境变量）。
+ */
+async function resolveSyncSourceDirRel(projectRoot, sourceDir, product) {
+    const kind = (0, inferProject_1.productToKind)(product);
+    const docSkill = await (0, inferProject_1.resolveDocSkillDir)(projectRoot, kind);
+    const rel = path_1.default.relative(docSkill.absPath, sourceDir).replace(/\\/g, "/");
+    if (!rel || rel.startsWith("..")) {
+        return rel;
+    }
+    return `./${rel}`;
+}

package/dist/core/techDocQuality.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * 04-技术文档草稿 结构质量门禁：与 artifacts/04-技术文档.template.md 对齐，禁止摘要版替换完整模板。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_TECH_DOC_SECTIONS = void 0;
+exports.checkTechDocStructure = checkTechDocStructure;
+/** 与模板一致的必备二级章节（允许「## 1. 改造范围」类带后缀标题） */
+exports.REQUIRED_TECH_DOC_SECTIONS = [
+    { id: "meta", pattern: /##\s*文档元信息/m, label: "文档元信息" },
+    { id: "scope", pattern: /##\s*1\.\s*改造范围/m, label: "1. 改造范围" },
+    { id: "ui", pattern: /##\s*2\.\s*页面与交互设计/m, label: "2. 页面与交互设计" },
+    { id: "demo", pattern: /###\s*2\.4\s*演示代码参照/m, label: "2.4 演示代码参照" },
+    { id: "state", pattern: /##\s*3\.\s*前端状态与数据模型设计/m, label: "3. 前端状态与数据模型设计" },
+    { id: "api", pattern: /##\s*4\.\s*接口与数据交互设计/m, label: "4. 接口与数据交互设计" },
+    { id: "form", pattern: /##\s*5\.\s*表单与校验设计/m, label: "5. 表单与校验设计" },
+    { id: "edge", pattern: /##\s*6\.\s*异常、边界与降级方案/m, label: "6. 异常、边界与降级方案" },
+    { id: "files", pattern: /##\s*7\.\s*改造清单/m, label: "7. 改造清单" },
+    { id: "risk", pattern: /##\s*8\.\s*风险点与应对策略/m, label: "8. 风险点与应对策略" },
+    { id: "release", pattern: /##\s*9\.\s*发布、灰度与回滚/m, label: "9. 发布、灰度与回滚" },
+    { id: "test", pattern: /##\s*10\.\s*测试与验收要点/m, label: "10. 测试与验收要点" },
+    { id: "pending", pattern: /##\s*11\.\s*待确认事项/m, label: "11. 待确认事项" },
+];
+const MIN_LINES = 150;
+const MIN_H3_UNDER_SCOPE = 2;
+const API_TABLE_RE = /\|\s*接口\s*\|\s*Method\s*\|/m;
+const DEMO_TABLE_RE = /\|\s*演示模块\s*\|\s*演示文件\/组件\s*\|/m;
+const AC_REF_RE = /\[AC-\d{2,}\]/g;
+/** 典型「摘要版」反模式：仅若干条顶层 [AC-xx]  bullet，无三级标题 */
+const SUMMARY_ANTIPATTERN_RE = /^#\s*04-技术文档草稿\s*\n+##\s*文档元信息[\s\S]{0,800}##\s*7\.\s*权限/m;
+/**
+ * 校验 04 技术文档是否按模板填满（非摘要替换版）。
+ */
+function checkTechDocStructure(content) {
+    var _a, _b, _c, _d;
+    const missingSections = [];
+    const warnings = [];
+    if (!content || content.trim().length < 80) {
+        return {
+            ok: false,
+            detail: "04-技术文档草稿.md 缺失或过短",
+            missingSections: exports.REQUIRED_TECH_DOC_SECTIONS.map((s) => s.label),
+            warnings: [],
+        };
+    }
+    const lines = content.split("\n");
+    if (lines.length < MIN_LINES) {
+        warnings.push(`行数 ${lines.length} < ${MIN_LINES}（模板级文档通常 ≥150 行）`);
+    }
+    for (const sec of exports.REQUIRED_TECH_DOC_SECTIONS) {
+        if (!sec.pattern.test(content)) {
+            missingSections.push(sec.label);
+        }
+    }
+    const h3InScope = ((_b = (_a = content.match(/##\s*1\.\s*改造范围[\s\S]*?(?=##\s*2\.)/m)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "").match(/^###\s+/gm);
+    if (!h3InScope || h3InScope.length < MIN_H3_UNDER_SCOPE) {
+        missingSections.push("1.x 改造目标/In Scope 等三级小节");
+    }
+    if (!API_TABLE_RE.test(content)) {
+        missingSections.push("4.1 接口清单表格（| 接口 | Method |）");
+    }
+    if (!DEMO_TABLE_RE.test(content)) {
+        missingSections.push("2.4 演示模块映射表格（| 演示模块 | 演示文件/组件 |）");
+    }
+    const acRefs = (_c = content.match(AC_REF_RE)) !== null && _c !== void 0 ? _c : [];
+    if (acRefs.length < 3) {
+        warnings.push("文中 [AC-XX] 引用过少（建议在各章节分散标注）");
+    }
+    if (SUMMARY_ANTIPATTERN_RE.test(content) && lines.length < 80) {
+        missingSections.push("禁止摘要版：须保留模板全部 11 章并逐节填写");
+    }
+    const placeholderHeavy = ((_d = content.match(/（填写）|待填写|TBD|示例：/g)) !== null && _d !== void 0 ? _d : []).length > 25 &&
+        lines.length < MIN_LINES;
+    if (placeholderHeavy) {
+        warnings.push("占位符过多且篇幅过短，疑似未按 PRD/接口/演示填充");
+    }
+    const ok = missingSections.length === 0 && lines.length >= MIN_LINES;
+    const detail = ok
+        ? `04 技术文档结构合格（${lines.length} 行，${exports.REQUIRED_TECH_DOC_SECTIONS.length} 章齐全）`
+        : `04 技术文档不符合模板: 缺 ${missingSections.join("、")}${warnings.length ? `；${warnings.join("；")}` : ""}`;
+    return {
+        ok,
+        detail,
+        missingSections,
+        warnings,
+    };
+}

package/dist/core/testAssertionAnalysis.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * 测试断言深度分析：用于 PRD 语义覆盖、AC 映射与 E2E 深度门禁。
+ * 禁止仅靠注释登记 PRD/AC；要求 test/it 块内存在 expect 等有效断言。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripComments = stripComments;
+exports.parseTestBlocks = parseTestBlocks;
+exports.isRegistryStubFile = isRegistryStubFile;
+exports.testBlockHasExpect = testBlockHasExpect;
+exports.testBlockReferencesAc = testBlockReferencesAc;
+exports.testBlockReferencesAtom = testBlockReferencesAtom;
+exports.hasMeaningfulAtomCoverageInFile = hasMeaningfulAtomCoverageInFile;
+exports.hasMeaningfulAcCoverageInFile = hasMeaningfulAcCoverageInFile;
+exports.testBlockIsPlaceholderOnly = testBlockIsPlaceholderOnly;
+exports.analyzeE2eSpecDepth = analyzeE2eSpecDepth;
+const TEST_TITLE_RE = /(?:^|\n)\s*(?:test|it)(?:\.(?:only|skip))?\s*\(\s*(?:async\s*)?[`'"]([^`'"]*)[`'"]/g;
+const EXPECT_RE = /\bexpect\s*\(/;
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+/** 仅用于登记 PRD 原子、无真实 UI 断言的伪覆盖文件 */
+const REGISTRY_STUB_FILE_RE = /prd-atoms-coverage|prd-atoms-registry|semantic-registry/i;
+/** 浅层 E2E：仅有占位符可见性断言 */
+const PLACEHOLDER_ONLY_RE = /getByPlaceholder|getByLabel|getByTestId/i;
+const DATA_ASSERTION_RE = /getByRole\s*\(\s*['"]cell|getByRole\s*\(\s*['"]row|toContainText|waitForResponse|\.n-data-table|data-table-tbody|data-table-body/i;
+const HOOK_TITLE_RE = /^(?:beforeEach|afterEach|beforeAll|afterAll)$/i;
+/** 移除行注释与块注释，避免注释中的 PRD 或 AC 标识误计为覆盖 */
+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;
+}
+/** 解析 test/it 块（标题 + 回调体近似区间） */
+function parseTestBlocks(content) {
+    var _a, _b, _c;
+    const stripped = stripComments(content);
+    const blocks = [];
+    const re = new RegExp(TEST_TITLE_RE.source, "g");
+    let m;
+    const indices = [];
+    let idx = 0;
+    while ((m = re.exec(stripped)) !== null) {
+        indices.push({ title: (_a = m[1]) !== null && _a !== void 0 ? _a : "", start: m.index, index: idx });
+        idx += 1;
+    }
+    for (let i = 0; i < indices.length; i += 1) {
+        const cur = indices[i];
+        const nextStart = (_c = (_b = indices[i + 1]) === null || _b === void 0 ? void 0 : _b.start) !== null && _c !== void 0 ? _c : stripped.length;
+        const slice = stripped.slice(cur.start, Math.min(cur.start + 4000, nextStart));
+        blocks.push({ title: cur.title, body: slice, index: cur.index });
+    }
+    return blocks;
+}
+/** 是否为 PRD 原子登记类伪覆盖文件 */
+function isRegistryStubFile(relPath, content) {
+    const norm = relPath.replace(/\\/g, "/");
+    if (REGISTRY_STUB_FILE_RE.test(norm))
+        return true;
+    if (!E2E_DIR_RE.test(norm))
+        return false;
+    const blocks = parseTestBlocks(content);
+    if (blocks.length === 0)
+        return false;
+    const allShallow = blocks.every((b) => {
+        const hasExpect = EXPECT_RE.test(b.body);
+        const onlyCount = /expect\s*\([^)]*\)\s*\.toBeGreaterThan\s*\(\s*0\s*\)/.test(b.body) &&
+            !DATA_ASSERTION_RE.test(b.body) &&
+            !/\bpage\.goto\b/.test(b.body);
+        return !hasExpect || onlyCount;
+    });
+    return allShallow && blocks.length >= 3;
+}
+function testBlockHasExpect(block) {
+    return EXPECT_RE.test(block.body);
+}
+/** test 块是否引用 AC（标题或块内显式标注） */
+function testBlockReferencesAc(block, acId) {
+    const bracket = `[${acId}]`;
+    const upper = acId.toUpperCase();
+    return (block.title.includes(bracket) ||
+        block.title.toUpperCase().includes(upper) ||
+        block.body.includes(bracket));
+}
+/** test 块是否引用 PRD 原子或可核对信号 */
+function testBlockReferencesAtom(block, atomId, signals) {
+    const hasId = block.title.includes(atomId) ||
+        block.title.includes(`[${atomId}]`) ||
+        block.body.includes(atomId);
+    if (hasId)
+        return true;
+    return signals.some((s) => s.length >= 4 && (block.title.includes(s) || block.body.includes(s)));
+}
+/**
+ * 判断单条测试文件是否对 PRD 原子有「有效」自动化覆盖（非注释、非 stub、含 expect）。
+ */
+function hasMeaningfulAtomCoverageInFile(relPath, content, atomId, signals) {
+    if (isRegistryStubFile(relPath, content)) {
+        return { covered: false, hasE2e: false };
+    }
+    const isE2e = E2E_DIR_RE.test(relPath);
+    const blocks = parseTestBlocks(content);
+    for (const block of blocks) {
+        if (!testBlockHasExpect(block))
+            continue;
+        if (!testBlockReferencesAtom(block, atomId, signals))
+            continue;
+        return { covered: true, hasE2e: isE2e };
+    }
+    return { covered: false, hasE2e: false };
+}
+/**
+ * 判断单条测试文件是否对 AC 有有效覆盖（test 块内 [AC-XX] + expect）。
+ */
+function hasMeaningfulAcCoverageInFile(relPath, content, acId) {
+    if (isRegistryStubFile(relPath, content)) {
+        return { covered: false, isE2e: false };
+    }
+    const isE2e = E2E_DIR_RE.test(relPath);
+    const blocks = parseTestBlocks(content);
+    for (const block of blocks) {
+        if (!testBlockReferencesAc(block, acId))
+            continue;
+        if (!testBlockHasExpect(block))
+            continue;
+        return { covered: true, isE2e };
+    }
+    return { covered: false, isE2e: false };
+}
+function testBlockIsPlaceholderOnly(block) {
+    if (HOOK_TITLE_RE.test(block.title.trim()))
+        return false;
+    if (!EXPECT_RE.test(block.body))
+        return false;
+    const hasPlaceholder = PLACEHOLDER_ONLY_RE.test(block.body);
+    const hasData = DATA_ASSERTION_RE.test(block.body);
+    const hasInteraction = /\b(?:click|dblclick|fill|press|selectOption)\b/.test(block.body);
+    return hasPlaceholder && !hasData && !hasInteraction;
+}
+/**
+ * 评估单个 E2E spec 的断言深度（L3 最低要求）。
+ * 每个非 hook 的 test 块不得仅断言 placeholder；至少一个 test 块须含数据或交互断言。
+ */
+function analyzeE2eSpecDepth(relPath, content) {
+    const issues = [];
+    if (isRegistryStubFile(relPath, content)) {
+        return {
+            ok: false,
+            issues: ["伪覆盖登记文件，不能作为 change 级 E2E 验收"],
+            stats: {
+                testCount: 0,
+                testsWithExpect: 0,
+                hasGoto: false,
+                hasDataAssertion: false,
+                hasInteraction: false,
+            },
+        };
+    }
+    const stripped = stripComments(content);
+    const blocks = parseTestBlocks(content);
+    const hookBlocks = blocks.filter((b) => HOOK_TITLE_RE.test(b.title.trim()));
+    const testBlocks = blocks.filter((b) => !HOOK_TITLE_RE.test(b.title.trim()));
+    const testsWithExpect = testBlocks.filter((b) => testBlockHasExpect(b)).length;
+    const hasGoto = /\bpage\.goto\b/.test(stripped);
+    const hasDataInTests = testBlocks.some((b) => DATA_ASSERTION_RE.test(b.body));
+    const hasInteractionInTests = testBlocks.some((b) => /\b(?:click|dblclick|fill|press|selectOption)\b/.test(b.body));
+    const placeholderOnlyTests = testBlocks.filter((b) => testBlockIsPlaceholderOnly(b));
+    if (testBlocks.length === 0) {
+        issues.push("未解析到 test/it 用例（不含 hook）");
+    }
+    if (testsWithExpect === 0) {
+        issues.push("无含 expect( 的 test/it 块");
+    }
+    if (!hasGoto && !hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) {
+        issues.push("缺少 page.goto（页面可达性未验证）");
+    }
+    if (placeholderOnlyTests.length > 0) {
+        issues.push(`以下用例仅断言 placeholder/label，缺少数据或交互: ${placeholderOnlyTests.map((t) => t.title).join(", ")}`);
+    }
+    if (!hasDataInTests && !hasInteractionInTests) {
+        issues.push("所有 test 块均缺少数据展示断言（cell/row/toContainText/waitForResponse）或交互操作");
+    }
+    const ok = testBlocks.length > 0 &&
+        testsWithExpect > 0 &&
+        (hasGoto || hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) &&
+        placeholderOnlyTests.length === 0 &&
+        (hasDataInTests || hasInteractionInTests);
+    return {
+        ok,
+        issues,
+        stats: {
+            testCount: testBlocks.length,
+            testsWithExpect,
+            hasGoto,
+            hasDataAssertion: hasDataInTests,
+            hasInteraction: hasInteractionInTests,
+        },
+    };
+}

package/dist/core/writeNext.js

@@ -35,7 +35,7 @@ async function writeInitialNext(outputRoot, projectRoot, runId) {
         "| `tasks.md` | AC 的可执行映射（`[AC-XX]`） |",
         "",
         "## 1. Step1 — 拉取 PRD",
-        "按 `01-获取需求文档指引.md` 执行 confluence 脚本；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
+        "按 `01-获取需求文档指引.md` 执行 confluence 脚本（设置 `SDD_SYNC_SOURCE_DIR` 后自动同步到 `source/PRD.md` + `source/image/`）；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
         "```bash",
         `npx sdd-flow-kit gate --project-root "${pr}" --run-id ${runId} --expect prd-fetched`,
         `npx sdd-flow-kit phase advance --project-root "${pr}" --run-id ${runId} --to after-prd`,