@epoint-testtech/ep-stage-skill 0.0.3-alpha.1

package/dist/src/cli/run-gap-pipeline.js

@@ -0,0 +1,1468 @@
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'url';
+import { extractCodeListSummary } from '../extractors/code-list.js';
+import { extractHtmlPage } from '../extractors/html-page.js';
+import { extractJavaAction } from '../extractors/java-action.js';
+import { extractSpecYaml } from '../extractors/spec-yaml.js';
+import { buildCrudBusinessModuleContract } from '../normalizers/crud-contract.js';
+import { collectActionCandidates } from '../gap-planner/action-candidates.js';
+import { createSkeletonCoverage } from '../gap-planner/skeleton-coverage.js';
+import { planAgentInferredWorkflows } from '../gap-planner/plan-agent-workflows.js';
+import { resolveStageContext } from '../context/stage-context.js';
+import { createTraceWriter } from '../trace/trace-writer.js';
+import { renderReviewSummary } from '../trace/review-summary.js';
+import { resolveMaterialInventory } from '../material/material-inventory.js';
+import { summarizePageStructure } from '../capability/page-structure.js';
+import { inferPageScenarios } from '../capability/scenario-inference.js';
+import { createCoverageDiff } from '../capability/coverage-diff.js';
+import { generateGlueTestcases } from '../testcase/testcase-generator.js';
+import { summarizeGeneralizationRun } from '../generalization/generalization-eval.js';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const repoRoot = path.resolve(packageRoot, '../..');
+const UNRESOLVED_MENU_PLACEHOLDER = '未确认菜单路径';
+const PROTECTED_KNOWLEDGE_PROJECT_ROOT = path.join(repoRoot, 'knowledge-project');
+export const runtimeSummaryMarker = '@@EP_STAGE_RUNTIME_SUMMARY@@';
+/**
+ * 把相对仓库根的路径解析为绝对路径。
+ *
+ * @param value - 可能相对的路径。
+ * @returns 绝对路径。
+ */
+function resolveFromRepo(value) {
+    return path.isAbsolute(value) ? value : path.resolve(repoRoot, value);
+}
+/**
+ * 解析可观测 pipeline 的命令行参数。
+ *
+ * 默认入口只需 --code-list；--scenario 为场景 gate 的人工确认值（缺省时停在 scenario gate）。
+ * 调试覆盖参数 --docs/--webapp/--java-actions/--hints 始终优先于 code_list 钻探。
+ *
+ * @param argv - process.argv.slice(2)。
+ * @returns 解析后的 ObservablePipelineArgs。
+ * @throws 缺少 --code-list 或参数对非法时抛错。
+ */
+export function parseObservablePipelineArgs(argv) {
+    const result = {};
+    const normalizedArgv = argv.filter((arg) => arg !== '--');
+    for (let index = 0; index < normalizedArgv.length; index += 2) {
+        const key = normalizedArgv[index];
+        const value = normalizedArgv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error(`无效的参数对，靠近 ${key ?? '<empty>'}`);
+        }
+        result[key.slice(2)] = value;
+    }
+    if (!result['code-list']) {
+        throw new Error('缺少 code_list.md 路径。默认入口：run:gap-pipeline -- --code-list <path/to/code_list.md>');
+    }
+    return {
+        codeList: resolveFromRepo(result['code-list']),
+        stageContext: result['stage-context'] ? resolveFromRepo(result['stage-context']) : undefined,
+        projectDir: result['project-dir'] ? resolveFromRepo(result['project-dir']) : undefined,
+        moduleId: result['module-id'],
+        menu: result.menu,
+        scenario: result.scenario,
+        confirmTestcases: result['confirm-testcases'] === 'true',
+        contractOut: result['contract-out'] ? resolveFromRepo(result['contract-out']) : undefined,
+        specOut: result['spec-out'] ? resolveFromRepo(result['spec-out']) : undefined,
+        playwrightProject: result.project ?? 'chromium',
+        headless: result.headless === 'true',
+        debugOverrides: {
+            docs: result.docs ? resolveFromRepo(result.docs) : undefined,
+            webapp: result.webapp ? resolveFromRepo(result.webapp) : undefined,
+            javaActions: result['java-actions'] ? resolveFromRepo(result['java-actions']) : undefined,
+            hints: result.hints ? resolveFromRepo(result.hints) : undefined,
+        },
+    };
+}
+/**
+ * 判断目标路径是否位于主仓 knowledge-project 受保护只读区。
+ *
+ * @param targetPath - 待写入路径。
+ * @returns true 表示该路径受主仓 knowledge-project 只读约束保护。
+ */
+export function isProtectedKnowledgeProjectPath(targetPath) {
+    const relativePath = path.relative(PROTECTED_KNOWLEDGE_PROJECT_ROOT, path.resolve(targetPath));
+    return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+/**
+ * 把路径统一渲染为 code_list.md 中更稳定的相对路径（POSIX 分隔符）。
+ *
+ * @param codeListPath - code_list.md 路径。
+ * @param targetPath - 目标物料路径。
+ * @returns 相对 code_list.md 的路径字符串。
+ */
+function renderRelativeCodeListPath(codeListPath, targetPath) {
+    return path.relative(path.dirname(codeListPath), targetPath).split(path.sep).join('/');
+}
+/**
+ * 将标量字段写回 code_list.md；已存在时覆盖，不存在时插入到正文前。
+ *
+ * @param content - 原始 code_list.md 内容。
+ * @param key - 字段名。
+ * @param value - 字段值。
+ * @returns 更新后的内容。
+ */
+function upsertCodeListScalar(content, key, value) {
+    const renderedLine = `${key}: ${JSON.stringify(value)}`;
+    const scalarPattern = new RegExp(`^\\s*${key}\\s*:\\s*.+$`, 'm');
+    if (scalarPattern.test(content)) {
+        return content.replace(scalarPattern, renderedLine);
+    }
+    const firstDivider = content.match(/^---\s*$/m);
+    if (firstDivider?.index !== undefined) {
+        return `${content.slice(0, firstDivider.index)}${renderedLine}\n${content.slice(firstDivider.index)}`;
+    }
+    const titleMatch = content.match(/^#.*(?:\r?\n|$)/);
+    if (titleMatch?.index === 0) {
+        const insertIndex = titleMatch[0].length;
+        return `${content.slice(0, insertIndex)}${renderedLine}\n\n${content.slice(insertIndex)}`;
+    }
+    return `${renderedLine}\n\n${content}`;
+}
+/**
+ * 将补齐后的字段和物料引用写回 code_list.md 内容。
+ *
+ * @param content - 原始 code_list.md 内容。
+ * @param input - 待写回字段。
+ * @returns 更新后的 code_list.md 内容。
+ */
+export function applyCodeListWriteBack(content, input) {
+    let nextContent = content;
+    if (input.knowledgeRoot) {
+        nextContent = upsertCodeListScalar(nextContent, 'knowledgeRoot', input.knowledgeRoot);
+    }
+    if (input.menu) {
+        nextContent = upsertCodeListScalar(nextContent, 'menu', input.menu);
+    }
+    const missingRefs = input.materialRefs.filter((materialRef) => !nextContent.includes(`\`${materialRef}\``));
+    if (missingRefs.length === 0) {
+        return nextContent;
+    }
+    return `${nextContent.trimEnd()}\n\n## 交互补齐物料\n\n${missingRefs
+        .map((materialRef) => `- \`${materialRef}\``)
+        .join('\n')}\n`;
+}
+/**
+ * 从用户提供的目录或文件路径中展开可写回的物料引用。
+ *
+ * HTML 目录会展开为全部 `.html` 文件；Java Action 目录会展开为全部 `*Action.java` 文件；
+ * 其余文件按单文件写回。
+ *
+ * @param codeListPath - code_list.md 路径。
+ * @param inputPath - 用户输入的文件或目录路径。
+ * @param kind - 物料类别。
+ * @returns 可写回 code_list.md 的相对路径列表。
+ */
+export function collectCodeListMaterialRefsFromPath(codeListPath, inputPath, kind) {
+    const resolvedPath = path.resolve(inputPath);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`交互补齐的路径不存在：${resolvedPath}`);
+    }
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+        return [renderRelativeCodeListPath(codeListPath, resolvedPath)];
+    }
+    const fileNames = fs.readdirSync(resolvedPath).sort();
+    const matchedFiles = fileNames.filter((fileName) => {
+        if (kind === 'html') {
+            return fileName.endsWith('.html');
+        }
+        if (kind === 'java_action') {
+            return fileName.endsWith('Action.java');
+        }
+        return true;
+    });
+    return matchedFiles.map((fileName) => renderRelativeCodeListPath(codeListPath, path.join(resolvedPath, fileName)));
+}
+/**
+ * 判断当前终端是否适合做交互补齐。
+ *
+ * @returns true 表示 stdin/stdout 都是 TTY，可安全提问。
+ */
+function canPromptInteractively() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * 校验路径存在（调试覆盖参数指向的路径）。
+ */
+function ensurePathExists(value, flag) {
+    if (!fs.existsSync(value)) {
+        throw new Error(`参数 ${flag} 指向的路径不存在：${value}`);
+    }
+}
+/**
+ * 逐项提问，读取用户输入；空输入视为跳过。
+ *
+ * @param promptText - 提示语。
+ * @param initialValue - 可选默认值。
+ * @returns 用户输入；空串返回 undefined。
+ */
+async function askOptionalQuestion(promptText, initialValue) {
+    const terminal = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const suffix = initialValue ? ` [默认: ${initialValue}]` : '';
+        const answer = (await terminal.question(`${promptText}${suffix}: `)).trim();
+        if (!answer) {
+            return initialValue?.trim() || undefined;
+        }
+        return answer;
+    }
+    finally {
+        terminal.close();
+    }
+}
+/**
+ * 在 material/menu 信息不全时，TTY 下交互补齐可写回的字段。
+ *
+ * 本轮只覆盖默认入口缺失最常见的 6 个入口字段：
+ * `knowledgeRoot`、`moduleId`、`webappDir`、`javaActionsDir`、`hintsPath`、`menu`。
+ *
+ * @param input - 当前 code_list、解析结果和 stage-context。
+ * @returns 补齐结果；若用户放弃或无新信息则返回空补充。
+ */
+async function promptInteractiveCodeListSupplements(input) {
+    const codeListDir = path.dirname(input.codeListPath);
+    const wantsSupplement = await askOptionalQuestion('检测到 code_list.md 信息不完整，是否现在补齐并继续？输入 y 继续，直接回车跳过', 'y');
+    if ((wantsSupplement ?? '').toLowerCase() !== 'y') {
+        return { supplements: {}, wroteBack: false };
+    }
+    const supplements = {};
+    if (!input.codeList.knowledgeRoot) {
+        supplements.knowledgeRoot = await askOptionalQuestion('请输入 knowledgeRoot（上游物料根目录，可留空跳过）');
+    }
+    if (input.materialResult.resolvedInputs.moduleId.status === 'missing') {
+        supplements.moduleId = await askOptionalQuestion('请输入 moduleId（如 zwplace）');
+    }
+    if (input.materialResult.resolvedInputs.webappDir.status !== 'resolved') {
+        supplements.webappDir = await askOptionalQuestion('请输入 webappDir（HTML 目录或单个 html 文件路径）');
+    }
+    if (input.materialResult.resolvedInputs.javaActionsDir.status !== 'resolved') {
+        supplements.javaActionsDir = await askOptionalQuestion('请输入 javaActionsDir（Action 目录或单个 Action.java 路径）');
+    }
+    if (input.materialResult.resolvedInputs.hintsPath.status !== 'resolved') {
+        supplements.hintsPath = await askOptionalQuestion('请输入 hintsPath（可选，ModuleHints 文件路径）');
+    }
+    if (input.materialResult.resolvedInputs.menu.status !== 'resolved') {
+        supplements.menu = await askOptionalQuestion('请输入菜单路径 menu（如 一级菜单>二级菜单）');
+    }
+    const hasSupplements = Object.values(supplements).some((value) => Boolean(value?.trim()));
+    if (!hasSupplements) {
+        return { supplements: {}, wroteBack: false };
+    }
+    if (isProtectedKnowledgeProjectPath(input.codeListPath)) {
+        return {
+            supplements,
+            wroteBack: false,
+            skippedWriteBackReason: `目标 code_list 位于主仓只读 knowledge-project，已仅对本次运行生效：${input.codeListPath}`,
+        };
+    }
+    const materialRefs = [
+        ...(supplements.webappDir
+            ? collectCodeListMaterialRefsFromPath(input.codeListPath, supplements.webappDir, 'html')
+            : []),
+        ...(supplements.javaActionsDir
+            ? collectCodeListMaterialRefsFromPath(input.codeListPath, supplements.javaActionsDir, 'java_action')
+            : []),
+        ...(supplements.hintsPath
+            ? collectCodeListMaterialRefsFromPath(input.codeListPath, supplements.hintsPath, 'module_hints')
+            : []),
+    ];
+    const nextContent = applyCodeListWriteBack(fs.readFileSync(input.codeListPath, 'utf8'), {
+        knowledgeRoot: supplements.knowledgeRoot
+            ? renderRelativeCodeListPath(input.codeListPath, path.resolve(supplements.knowledgeRoot))
+            : undefined,
+        menu: supplements.menu,
+        materialRefs,
+    });
+    fs.mkdirSync(codeListDir, { recursive: true });
+    fs.writeFileSync(input.codeListPath, nextContent, 'utf8');
+    return { supplements, wroteBack: true };
+}
+/**
+ * 在 menu gate 停下时交互确认菜单，并尽量写回 code_list.md。
+ *
+ * @param codeListPath - code_list.md 路径。
+ * @param menuResolution - 当前菜单解析结果。
+ * @returns 人工确认后的菜单；未输入时返回 undefined。
+ */
+async function promptMenuAtGate(codeListPath, menuResolution) {
+    const initialValue = menuResolution.status === 'candidate'
+        ? menuResolution.candidates[0]
+        : undefined;
+    const menu = await askOptionalQuestion(menuResolution.status === 'candidate'
+        ? `请输入菜单路径 menu（候选：${menuResolution.candidates.join(' | ')}）`
+        : '请输入菜单路径 menu', initialValue);
+    if (!menu) {
+        return { supplements: {}, wroteBack: false };
+    }
+    if (isProtectedKnowledgeProjectPath(codeListPath)) {
+        return {
+            supplements: { menu },
+            wroteBack: false,
+            skippedWriteBackReason: `目标 code_list 位于主仓只读 knowledge-project，menu 仅对本次运行生效：${codeListPath}`,
+        };
+    }
+    const nextContent = applyCodeListWriteBack(fs.readFileSync(codeListPath, 'utf8'), {
+        menu,
+        materialRefs: [],
+    });
+    fs.writeFileSync(codeListPath, nextContent, 'utf8');
+    return {
+        supplements: { menu },
+        wroteBack: true,
+    };
+}
+/**
+ * 读取契约 JSON（Task 9B spec assembly 复用）。
+ */
+function readContract(contractPath) {
+    return JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+}
+/**
+ * 读取 glue-report run-info（Task 9B 报告阶段复用）。
+ */
+function readRunInfo(projectDir) {
+    const filePath = path.join(projectDir, 'glue-report', 'run-info.json');
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+/**
+ * 列出目录下所有 .html 文件（按名排序）。
+ */
+function htmlFiles(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('.html'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 列出目录下所有 *Action.java 文件（按名排序）。
+ */
+function javaFiles(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('Action.java'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 解析 spec.yaml；缺失时回退为低置信 spec（保留 module id 与 code_list 标题）。
+ *
+ * @param docsDir - 文档目录。
+ * @param moduleId - 模块 id。
+ * @param codeListSummary - code_list 摘要（取 moduleLabel 作为 fallback label）。
+ * @returns ExtractedSpecYaml。
+ */
+function resolveSpec(docsDir, moduleId, codeListSummary) {
+    const specPath = path.join(docsDir, 'spec.yaml');
+    if (fs.existsSync(specPath)) {
+        return extractSpecYaml(specPath);
+    }
+    return {
+        path: specPath,
+        module: {
+            id: moduleId,
+            label: codeListSummary.moduleLabel,
+        },
+        fields: [],
+        businessRules: [],
+    };
+}
+/**
+ * 把 MaterialResolution 解析为路径；未 resolved 时抛错（不应进入下一阶段）。
+ */
+function resolvedPath(input, key) {
+    if (input.status !== 'resolved') {
+        throw new Error(`${key} 未解析，不能进入下一阶段`);
+    }
+    return input.path;
+}
+/**
+ * 把 ValueResolution 解析为值；未 resolved 时抛错。
+ */
+function resolvedValue(input, key) {
+    if (input.status !== 'resolved') {
+        throw new Error(`${key} 未解析，不能进入下一阶段`);
+    }
+    return input.value;
+}
+/**
+ * 解析本轮 pipeline 的菜单路由。
+ *
+ * 优先使用已确认的 menu；缺失时根据 contract 的模块名和列表页标题生成候选，
+ * 但候选仍需人工确认，不得直接进入可执行阶段。
+ *
+ * @param input - menu 槽位与 CRUD 契约。
+ * @returns 已确认菜单或候选菜单。
+ */
+export function resolveMenuRouteForPipeline(input) {
+    if (input.menu.status === 'resolved' || input.menu.status === 'candidate') {
+        return input.menu;
+    }
+    const moduleLabel = input.contract.module.label.trim();
+    const listPageTitle = input.contract.pages.list.title.trim();
+    const candidates = Array.from(new Set([
+        moduleLabel && listPageTitle ? `${moduleLabel}>${listPageTitle}` : undefined,
+        listPageTitle || undefined,
+    ].filter((item) => Boolean(item && item.trim().length > 0))));
+    if (candidates.length > 0) {
+        return {
+            status: 'candidate',
+            candidates,
+            evidence: 'menu 候选来自 contract.module.label 与 contract.pages.list.title',
+        };
+    }
+    return input.menu;
+}
+/**
+ * 写入单阶段 trace 并追加阶段摘要。
+ *
+ * @param writer - trace writer。
+ * @param stageSummaries - 阶段摘要累积列表。
+ * @param stage - 阶段名称。
+ * @param payload - 阶段 trace payload。
+ */
+function recordStage(writer, stageSummaries, stage, payload) {
+    writer.writeStage(stage, payload);
+    stageSummaries.push({
+        stage,
+        stageLabel: payload.stageLabel,
+        status: payload.gate.status,
+        conclusion: payload.reasoningSummary?.conclusion ?? `${payload.stageLabel}完成`,
+        needsHumanReview: payload.reasoningSummary?.needsHumanReview ?? false,
+    });
+}
+/**
+ * 能力候选阶段 trace 转换：动作候选 + 页面结构摘要。
+ */
+function capabilityCandidatesToTrace(input) {
+    return {
+        stage: 'capability-candidates',
+        stageLabel: '能力候选追踪',
+        inputs: [{ kind: 'material_inventory', path: 'material-inventory.json' }],
+        outputs: input.actionCandidates.map((candidate) => ({
+            kind: 'action_candidate',
+            path: candidate.actionId,
+            description: candidate.label,
+        })),
+        reasoningSummary: {
+            conclusion: `识别动作候选 ${input.actionCandidates.length} 个，页面结构摘要 ${input.pageStructures.length} 个。`,
+            evidenceChain: input.actionCandidates.flatMap((candidate) => candidate.evidence.map((evidence) => ({
+                source: 'html',
+                path: evidence.path,
+                text: evidence.evidenceText ?? candidate.label,
+            }))),
+            alternatives: [],
+            confidence: 'medium',
+            risks: [],
+            needsHumanReview: false,
+        },
+        candidateCount: input.actionCandidates.length,
+        unresolvedCount: 0,
+        gate: { status: 'confirmed', confirmedBy: 'policy', reason: '能力候选来自确定性 extractor' },
+    };
+}
+/**
+ * 骨架能力模型阶段 trace 转换。
+ */
+function skeletonCoverageToTrace(coverage) {
+    return {
+        stage: 'skeleton-capability-model',
+        stageLabel: '骨架能力模型追踪',
+        inputs: [{ kind: 'capability_candidates', path: 'capability-candidates.json' }],
+        outputs: coverage.coveredWorkflows.map((workflow) => ({ kind: 'skeleton_workflow', path: workflow })),
+        reasoningSummary: {
+            conclusion: `当前骨架覆盖 ${coverage.coveredWorkflows.join('、')}。`,
+            evidenceChain: [],
+            alternatives: [],
+            confidence: 'high',
+            risks: [],
+            needsHumanReview: false,
+        },
+        candidateCount: coverage.coveredWorkflows.length,
+        unresolvedCount: 0,
+        gate: { status: 'confirmed', confirmedBy: 'policy', reason: '骨架能力模型已生成' },
+    };
+}
+/**
+ * coverage diff 阶段 trace 转换。
+ */
+function coverageDiffToTrace(diff) {
+    return {
+        stage: 'coverage-diff',
+        stageLabel: '覆盖差异追踪',
+        inputs: [
+            { kind: 'skeleton_capability_model', path: 'skeleton-capability-model.json' },
+            { kind: 'baseline_gap_planner', path: 'baselineWorkflows' },
+        ],
+        outputs: [
+            ...diff.covered.map((item) => ({ kind: 'covered_action', path: item.actionId, description: item.label })),
+            ...diff.gapCandidates.map((item) => ({ kind: 'gap_candidate', path: item.actionId, description: item.label })),
+        ],
+        reasoningSummary: diff.reasoningSummary,
+        candidateCount: diff.covered.length + diff.gapCandidates.length + diff.nestedCrudCandidates.length,
+        unresolvedCount: diff.unresolved.length + diff.nestedCrudCandidates.length,
+        gate: diff.reasoningSummary.needsHumanReview
+            ? { status: 'needs_review', reason: 'coverage diff 存在 gap 或嵌套 CRUD 候选' }
+            : { status: 'confirmed', confirmedBy: 'policy', reason: 'coverage diff 无需人工确认' },
+    };
+}
+/**
+ * 用例生成阶段 trace 转换。
+ */
+function testcaseGenerationToTrace(testcases) {
+    const needsHumanReview = testcases.reasoningSummary.needsHumanReview ||
+        testcases.cases.some((item) => item.reviewStatus !== 'confirmed');
+    return {
+        stage: 'testcase-generation',
+        stageLabel: '用例生成追踪',
+        inputs: [{ kind: 'coverage_diff', path: 'coverage-diff.json' }],
+        outputs: testcases.cases.map((item) => ({ kind: 'glue_testcase', path: item.caseId, description: item.title })),
+        reasoningSummary: testcases.reasoningSummary,
+        candidateCount: testcases.cases.length,
+        unresolvedCount: needsHumanReview ? 1 : 0,
+        gate: needsHumanReview
+            ? { status: 'needs_review', reason: '存在未确认用例' }
+            : { status: 'confirmed', confirmedBy: 'policy', reason: '用例均已确认' },
+    };
+}
+/**
+ * 将 testcase gate 的人工确认结果写回结构化用例文档。
+ *
+ * @param testcases - 原始用例文档。
+ * @returns 所有 case 标记为 confirmed 的新文档。
+ */
+export function confirmGlueTestcaseDocument(testcases) {
+    return {
+        ...testcases,
+        cases: testcases.cases.map((item) => ({
+            ...item,
+            reviewStatus: 'confirmed',
+        })),
+        reasoningSummary: {
+            ...testcases.reasoningSummary,
+            conclusion: `${testcases.reasoningSummary.conclusion} 人工已通过 --confirm-testcases=true 确认 testcase gate。`,
+            evidenceChain: [
+                ...testcases.reasoningSummary.evidenceChain,
+                {
+                    source: 'human',
+                    path: 'cli --confirm-testcases',
+                    text: 'confirmed=true',
+                },
+            ],
+            needsHumanReview: false,
+        },
+    };
+}
+/**
+ * 回写 testcase markdown frontmatter 的 reviewStatus。
+ *
+ * @param markdown - 原始 testcase markdown。
+ * @param reviewStatus - 目标审阅状态。
+ * @returns 更新后的 markdown。
+ */
+export function applyTestcaseReviewStatusToMarkdown(markdown, reviewStatus) {
+    return markdown.replace(/^reviewStatus:\s*".*"$/m, `reviewStatus: "${reviewStatus}"`);
+}
+/**
+ * 把 runtime gap 推理摘要转换为可审阅 trace payload。
+ *
+ * Task 9B 接入 runtime 后写入 runtime-gap-inference.json。
+ * 运行时只能补定位和运行态证据，不允许修改业务意图和断言预期。
+ *
+ * @param runtime - runtime runner 产出的摘要。
+ * @returns runtime-gap-inference 阶段 trace payload。
+ */
+export function runtimeSummaryToTrace(runtime) {
+    const runtimeStatus = runtime.runtimeStatus ?? 'resolved';
+    const runtimeFailed = runtimeStatus !== 'resolved';
+    const needsHumanReview = runtime.needsReviewWorkflows.length > 0 || runtimeFailed;
+    const runtimeError = runtime.errorMessage ?? runtime.stderr ?? runtime.stdout;
+    const runtimeErrorPreview = runtimeError?.slice(0, 500);
+    const mismatchSelectors = (runtime.pageStructureSignals ?? [])
+        .filter((signal) => signal.runtimeMismatch)
+        .map((signal) => signal.selector);
+    const needsReviewReasonMap = new Map((runtime.needsReviewWorkflowReasons ?? []).map((item) => [item.workflowId, item.reason]));
+    const conclusion = runtimeFailed
+        ? `运行时推理未完成：${runtimeStatus}。`
+        : `运行时已解决 ${runtime.resolvedWorkflows.length} 个 workflow，${runtime.needsReviewWorkflows.length} 个仍需人工审阅。`;
+    return {
+        stage: 'runtime-gap-inference',
+        stageLabel: '运行时 gap 推理追踪',
+        inputs: [{ kind: 'playwright_spec', path: runtime.specPath }],
+        outputs: [
+            ...runtime.resolvedWorkflows.map((workflowId) => ({
+                kind: 'resolved_runtime_workflow',
+                path: workflowId,
+            })),
+            ...(runtime.pageStructureSignals ?? []).map((signal) => ({
+                kind: 'runtime_page_structure',
+                path: signal.selector,
+                description: signal.runtimeVisible ? 'visible' : 'not_visible',
+            })),
+        ],
+        reasoningSummary: {
+            conclusion,
+            evidenceChain: [
+                ...runtime.resolvedWorkflows.map((workflowId) => ({
+                    source: 'runtime',
+                    path: runtime.specPath,
+                    text: `resolved=${workflowId}`,
+                })),
+                ...runtime.needsReviewWorkflows.map((workflowId) => {
+                    const reason = needsReviewReasonMap.get(workflowId);
+                    return {
+                        source: 'runtime',
+                        path: runtime.specPath,
+                        text: reason ? `needs_review=${workflowId} reason=${reason}` : `needs_review=${workflowId}`,
+                    };
+                }),
+                ...(runtime.pageStructureSignals ?? []).map((signal) => ({
+                    source: 'runtime',
+                    path: runtime.specPath,
+                    text: signal.evidenceText,
+                })),
+                ...(runtimeErrorPreview
+                    ? [{
+                            source: 'runtime',
+                            path: runtime.specPath,
+                            text: runtimeErrorPreview,
+                        }]
+                    : []),
+            ],
+            alternatives: ['runtime locator resolve', 'manual review'],
+            confidence: runtimeFailed ? 'low' : needsHumanReview ? 'medium' : 'high',
+            risks: [
+                ...(runtimeErrorPreview ? [runtimeErrorPreview] : []),
+                ...runtime.needsReviewWorkflows.map((workflowId) => {
+                    const reason = needsReviewReasonMap.get(workflowId);
+                    return reason ? `${workflowId} 仍需人工审阅：${reason}` : `${workflowId} 仍需人工审阅`;
+                }),
+                ...mismatchSelectors.map((selector) => `${selector} 静态存在但运行时不可见`),
+            ],
+            needsHumanReview,
+        },
+        candidateCount: runtime.resolvedWorkflows.length + runtime.needsReviewWorkflows.length,
+        unresolvedCount: runtime.needsReviewWorkflows.length,
+        gate: needsHumanReview
+            ? { status: 'needs_review', reason: runtimeFailed ? `运行时推理未完成：${runtimeStatus}` : '存在运行时未确认 workflow' }
+            : { status: 'confirmed', confirmedBy: 'policy', reason: '运行时 workflow 已解决' },
+    };
+}
+/**
+ * 从结构化 glue-report JSON 中提取失败工作流与 gap finding 摘要。
+ *
+ * @param reportJsonPath - stage-glue report JSON 路径。
+ * @returns 可用于 trace 的失败摘要。
+ */
+function readGlueReportDetails(reportJsonPath) {
+    if (!reportJsonPath || !fs.existsSync(reportJsonPath)) {
+        return {};
+    }
+    const report = JSON.parse(fs.readFileSync(reportJsonPath, 'utf8'));
+    const failedWorkflows = (report.workflows ?? []).filter((workflow) => workflow.status === 'failed');
+    return {
+        failedWorkflowSummaries: failedWorkflows.map((workflow) => `${workflow.workflowId}${workflow.workflowName ? `(${workflow.workflowName})` : ''}: ${workflow.errorMessage ?? 'failed'}`),
+        gapFindingSummaries: failedWorkflows
+            .filter((workflow) => workflow.gapFinding?.kind)
+            .map((workflow) => `${workflow.workflowId}: ${workflow.gapFinding?.kind} - ${workflow.gapFinding?.summary ?? '无摘要'}${workflow.gapFinding?.observed ? `；observed=${workflow.gapFinding.observed}` : ''}`),
+    };
+}
+/**
+ * 从 `.env` 文件中提取登录 URL。
+ *
+ * @param envFilePath - `.env` 文件路径。
+ * @returns `LOGIN_SYSTEM_URL`；不存在时返回 undefined。
+ */
+export function extractLoginSystemUrlFromEnvFile(envFilePath) {
+    if (!fs.existsSync(envFilePath)) {
+        return undefined;
+    }
+    const content = fs.readFileSync(envFilePath, 'utf8');
+    const match = content.match(/^\s*LOGIN_SYSTEM_URL\s*=\s*(.+?)\s*$/m);
+    if (!match?.[1]) {
+        return undefined;
+    }
+    return match[1].trim().replace(/^["']|["']$/g, '');
+}
+/**
+ * 用轻量 HTTP 头请求补证当前登录环境是否可访问。
+ *
+ * @param loginUrl - 登录地址。
+ * @returns 简短环境证据文本。
+ */
+function probeLoginEnvironment(loginUrl) {
+    const result = spawnSync('curl', ['-I', '--max-time', '10', '-sS', loginUrl], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    const output = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+    if (result.status === 0) {
+        const firstLine = output.split(/\r?\n/).find((line) => line.trim().length > 0);
+        return firstLine ? `curl -I: ${firstLine}` : 'curl -I: success';
+    }
+    return output ? `curl -I: ${output}` : `curl -I exitCode=${result.status ?? 1}`;
+}
+/**
+ * 胶水测试组装阶段 trace 转换。
+ *
+ * @param summary - spec assembly 摘要。
+ * @returns glue-spec-assembly 阶段 trace payload。
+ */
+export function glueSpecAssemblyToTrace(summary) {
+    const assemblyError = summary.errorMessage ?? summary.stderr ?? summary.stdout;
+    const assemblyErrorPreview = assemblyError?.slice(0, 500);
+    return {
+        stage: 'glue-spec-assembly',
+        stageLabel: '胶水测试组装追踪',
+        inputs: [
+            { kind: 'crud_contract', path: summary.contractPath },
+            { kind: 'glue_testcase', path: summary.testcasePath },
+        ],
+        outputs: summary.generated ? [{ kind: 'playwright_spec', path: summary.specPath }] : [],
+        reasoningSummary: {
+            conclusion: summary.generated ? '已根据确认用例组装 Playwright spec。' : '未生成 Playwright spec。',
+            evidenceChain: [
+                { source: 'human', path: summary.testcasePath, text: `menu=${summary.menu}` },
+                ...(assemblyErrorPreview
+                    ? [{
+                            source: 'runtime',
+                            path: summary.specPath,
+                            text: assemblyErrorPreview,
+                        }]
+                    : []),
+            ],
+            alternatives: [],
+            confidence: summary.generated ? 'high' : 'low',
+            risks: summary.generated ? [] : [assemblyErrorPreview ?? 'spec assembly 未产出文件'],
+            needsHumanReview: !summary.generated,
+        },
+        candidateCount: 1,
+        unresolvedCount: summary.generated ? 0 : 1,
+        gate: summary.generated
+            ? { status: 'confirmed', confirmedBy: 'policy', reason: '已生成 Playwright spec' }
+            : { status: 'needs_review', reason: 'Playwright spec 未生成' },
+    };
+}
+/**
+ * Playwright 执行阶段 trace 转换。
+ *
+ * @param summary - Playwright 执行摘要。
+ * @returns playwright-execution 阶段 trace payload。
+ */
+export function playwrightExecutionToTrace(summary) {
+    const passed = summary.status === 'passed';
+    return {
+        stage: 'playwright-execution',
+        stageLabel: '测试执行追踪',
+        inputs: [{ kind: 'playwright_spec', path: summary.specPath }],
+        outputs: [{ kind: 'playwright_result', path: String(summary.exitCode), description: summary.status }],
+        reasoningSummary: {
+            conclusion: passed
+                ? 'Playwright 执行通过。'
+                : `Playwright 执行未通过：${summary.status}。`,
+            evidenceChain: [
+                ...(summary.stdout
+                    ? [{ source: 'runtime', path: summary.specPath, text: summary.stdout.slice(0, 500) }]
+                    : []),
+                ...(summary.stderr
+                    ? [{ source: 'runtime', path: summary.specPath, text: summary.stderr.slice(0, 500) }]
+                    : []),
+                ...(summary.loginUrl && summary.environmentEvidence
+                    ? [{
+                            source: 'runtime',
+                            path: summary.loginUrl,
+                            text: `环境预检：${summary.environmentEvidence}`,
+                        }]
+                    : []),
+            ],
+            alternatives: ['business failure', 'environment unavailable', 'test implementation failure'],
+            confidence: passed ? 'high' : 'medium',
+            risks: passed ? [] : [summary.stderr ?? summary.stdout ?? 'Playwright 执行失败'],
+            needsHumanReview: !passed,
+        },
+        gate: passed
+            ? { status: 'confirmed', confirmedBy: 'policy', reason: 'Playwright exitCode=0' }
+            : { status: 'needs_review', reason: `Playwright exitCode=${summary.exitCode}` },
+    };
+}
+/**
+ * glue-report 阶段 trace 转换。
+ *
+ * @param summary - glue-report 摘要。
+ * @returns glue-report 阶段 trace payload。
+ */
+export function glueReportToTrace(summary) {
+    const outputs = [
+        ...(summary.stageGlueReportJsonPath
+            ? [{ kind: 'glue_report_json', path: summary.stageGlueReportJsonPath }]
+            : []),
+        ...(summary.stageGlueReportHtmlPath
+            ? [{ kind: 'glue_report_html', path: summary.stageGlueReportHtmlPath }]
+            : []),
+        ...(summary.playwrightReportDirPath
+            ? [{ kind: 'playwright_report_dir', path: summary.playwrightReportDirPath }]
+            : []),
+    ];
+    return {
+        stage: 'glue-report',
+        stageLabel: '执行报告追踪',
+        inputs: [{ kind: 'project_dir', path: summary.projectDir }],
+        outputs,
+        reasoningSummary: {
+            conclusion: outputs.length > 0
+                ? summary.gapFindingSummaries?.length
+                    ? `已收集 glue-report 输出；报告识别到 ${summary.gapFindingSummaries.length} 个业务缺口。`
+                    : '已收集 glue-report 输出。'
+                : '未发现 glue-report 输出。',
+            evidenceChain: [
+                ...outputs.map((item) => ({ source: 'runtime', path: item.path, text: item.kind })),
+                ...(summary.failedWorkflowSummaries ?? []).map((text) => ({
+                    source: 'runtime',
+                    path: summary.stageGlueReportJsonPath ?? summary.projectDir,
+                    text,
+                })),
+                ...(summary.gapFindingSummaries ?? []).map((text) => ({
+                    source: 'runtime',
+                    path: summary.stageGlueReportJsonPath ?? summary.projectDir,
+                    text,
+                })),
+            ],
+            alternatives: [],
+            confidence: outputs.length > 0 ? 'high' : 'low',
+            risks: outputs.length > 0 ? (summary.gapFindingSummaries ?? []) : ['glue-report 输出缺失'],
+            needsHumanReview: outputs.length === 0,
+        },
+        gate: outputs.length > 0
+            ? { status: 'confirmed', confirmedBy: 'policy', reason: '报告路径已收集' }
+            : { status: 'needs_review', reason: '未发现报告路径' },
+    };
+}
+/**
+ * 解析 pipeline 输出路径（contract / spec / testcase），未显式指定时给默认值。
+ */
+function resolvePipelineOutputPaths(input) {
+    return {
+        contractOut: input.args.contractOut ??
+            resolveFromRepo(`packages/ep-stage-skill/output/${input.moduleId}.crud.contract.json`),
+        specOut: input.args.specOut ??
+            path.join(input.projectDir, 'src', 'tests', `generated-${input.moduleId}.gap.spec.ts`),
+        testcaseJsonPath: path.join(input.projectDir, 'testcases', `${input.moduleId}.glue-testcase.json`),
+    };
+}
+/**
+ * 捕获式运行 pnpm 子命令，返回 status/stdout/stderr（不 process.exit）。
+ *
+ * @param commandArgs - pnpm 参数。
+ * @param cwd - 工作目录，默认仓库根。
+ * @param env - 额外环境变量。
+ * @returns status / stdout / stderr。
+ */
+function runPnpmCapture(commandArgs, cwd = repoRoot, env) {
+    const result = spawnSync('pnpm', commandArgs, {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf8',
+        env: { ...process.env, ...env },
+    });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+/**
+ * 把契约写入 contractOut（供 generate:playwright-tests 消费）。
+ */
+function writeContractArtifact(contract, contractOut) {
+    fs.mkdirSync(path.dirname(contractOut), { recursive: true });
+    fs.writeFileSync(contractOut, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
+}
+/**
+ * 运行 generate:playwright-tests 组装 Playwright spec。
+ */
+function runSpecAssembly(input) {
+    fs.mkdirSync(path.dirname(input.specOut), { recursive: true });
+    const result = runPnpmCapture([
+        '--filter',
+        '@epoint-testtech/ep-stage-skill',
+        'generate:playwright-tests',
+        '--',
+        '--contract',
+        input.contractOut,
+        '--out',
+        input.specOut,
+        '--menu',
+        input.menu,
+        '--testcase',
+        input.testcasePath,
+    ]);
+    if (result.status !== 0) {
+        return {
+            contractPath: input.contractOut,
+            specPath: input.specOut,
+            menu: input.menu,
+            testcasePath: input.testcasePath,
+            generated: false,
+            exitCode: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            errorMessage: result.stderr || result.stdout || 'generate:playwright-tests failed',
+        };
+    }
+    return {
+        contractPath: input.contractOut,
+        specPath: input.specOut,
+        menu: input.menu,
+        testcasePath: input.testcasePath,
+        generated: fs.existsSync(input.specOut),
+    };
+}
+/**
+ * 判断 runtime 子进程失败是否更像环境不可达。
+ *
+ * @param text - stderr + stdout 文本。
+ * @returns 是否属于环境或登录态不可用。
+ */
+function isRuntimeEnvironmentUnavailable(text) {
+    return /ERR_EMPTY_RESPONSE|ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|net::ERR|登录失败|LOGIN_|login timeout|navigation timeout/i.test(text);
+}
+/**
+ * 解析 runtime runner 带哨兵的 JSON 输出。
+ *
+ * @param stdout - runtime runner stdout。
+ * @returns RuntimeSummary。
+ */
+export function parseRuntimeSummaryOutput(stdout) {
+    const markerIndex = stdout.lastIndexOf(runtimeSummaryMarker);
+    const payload = markerIndex >= 0
+        ? stdout.slice(markerIndex + runtimeSummaryMarker.length).trim()
+        : stdout.trim();
+    return JSON.parse(payload);
+}
+/**
+ * 将 runtime 子进程失败转成可观测摘要，避免吞掉实现错误。
+ *
+ * @param input - 子进程失败信息与计划 workflow。
+ * @returns RuntimeSummary。
+ */
+export function createRuntimeFailureSummary(input) {
+    const combinedOutput = [input.stderr, input.stdout].filter(Boolean).join('\n');
+    const environmentUnavailable = isRuntimeEnvironmentUnavailable(combinedOutput);
+    return {
+        resolvedWorkflows: [],
+        skippedWorkflows: input.plannedWorkflows,
+        needsReviewWorkflows: input.plannedWorkflows,
+        specPath: input.specPath,
+        runtimeStatus: environmentUnavailable ? 'environment_unavailable' : 'failed',
+        runtimePageStructureStatus: environmentUnavailable ? 'environment_unavailable' : 'failed',
+        pageStructureSignals: [],
+        exitCode: input.status,
+        stdout: input.stdout,
+        stderr: input.stderr,
+        errorMessage: combinedOutput || `runtime runner exited with ${input.status}`,
+    };
+}
+/**
+ * 运行 runtime gap resolve（node --import tsx runtime-runner.ts），返回 RuntimeSummary。
+ *
+ * 无 planned workflow 时返回空摘要；子命令失败（如内网不可达）标记 environment_unavailable，
+ * 全部 workflow 计入 needsReview，不抛错。
+ */
+function runRuntimeResolve(input) {
+    const contract = readContract(input.contractOut);
+    const plannedWorkflows = (contract.agentInferredWorkflows ?? [])
+        .filter((workflow) => workflow.status === 'planned')
+        .map((workflow) => workflow.workflowId);
+    if (plannedWorkflows.length === 0) {
+        return {
+            resolvedWorkflows: [],
+            skippedWorkflows: [],
+            needsReviewWorkflows: [],
+            specPath: input.specOut,
+            runtimeStatus: 'resolved',
+        };
+    }
+    const scriptPath = path.join(input.projectDir, 'src', 'gap-executor', 'runtime-runner.ts');
+    const result = runPnpmCapture([
+        '--filter',
+        '@epoint-testtech/ep-stage-skill',
+        'exec',
+        'node',
+        '--import',
+        'tsx',
+        scriptPath,
+        '--contract',
+        input.contractOut,
+        '--spec',
+        input.specOut,
+        '--project-dir',
+        input.projectDir,
+        '--menu',
+        input.menu,
+        '--module-id',
+        input.moduleId,
+        '--workflow-ids',
+        plannedWorkflows.join(','),
+        '--headless',
+        String(input.headless),
+    ]);
+    if (result.status !== 0) {
+        return createRuntimeFailureSummary({
+            plannedWorkflows,
+            specPath: input.specOut,
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        });
+    }
+    return {
+        ...parseRuntimeSummaryOutput(result.stdout),
+        runtimeStatus: 'resolved',
+    };
+}
+/**
+ * 运行 Playwright 执行目标 spec，返回执行摘要。
+ *
+ * 失败时按 stderr/stdout 判定 environment_unavailable 或 failed，不抛错。
+ */
+function runPlaywright(input) {
+    const loginUrl = extractLoginSystemUrlFromEnvFile(path.join(input.projectDir, '.env'));
+    const specArg = path.relative(input.projectDir, input.specOut);
+    const result = runPnpmCapture(['--dir', input.projectDir, 'exec', 'playwright', 'test', specArg, '--project', input.playwrightProject], repoRoot, { HEADLESS: String(input.headless) });
+    const status = result.status === 0
+        ? 'passed'
+        : /ERR_EMPTY_RESPONSE|ECONNREFUSED|net::ERR/i.test(result.stderr + result.stdout)
+            ? 'environment_unavailable'
+            : 'failed';
+    const environmentEvidence = status === 'environment_unavailable' && loginUrl ? probeLoginEnvironment(loginUrl) : undefined;
+    return {
+        specPath: input.specOut,
+        project: input.playwrightProject,
+        status,
+        exitCode: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        loginUrl,
+        environmentEvidence,
+    };
+}
+/**
+ * 可观测胶水链路完整入口。
+ *
+ * 数据流：context → material → evidence → capability → scenario(gate) →
+ * skeleton → coverage-diff → testcase(gate) → menu(gate) →
+ * spec assembly → runtime → playwright → glue-report。
+ *
+ * 任一 gate needs_review 时停止（退出码 2），不继续后续阶段。
+ * runtime/playwright 失败写入 trace，内网不可访问标记 environment_unavailable，不视为链路失败。
+ */
+async function main() {
+    const pipelineArgs = parseObservablePipelineArgs(process.argv.slice(2));
+    const contextResult = resolveStageContext({
+        cwd: process.cwd(),
+        codeListPath: pipelineArgs.codeList,
+        projectDir: pipelineArgs.projectDir,
+        stageContextPath: pipelineArgs.stageContext,
+    });
+    const writer = createTraceWriter({
+        projectDir: contextResult.context.projectDir,
+        codeListPath: pipelineArgs.codeList,
+    });
+    const stageSummaries = [];
+    recordStage(writer, stageSummaries, 'context-resolution', contextResult.trace);
+    if (contextResult.trace.gate.status === 'needs_review') {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '项目上下文需要确认',
+            reasoningSummary: contextResult.trace.reasoningSummary,
+            nextAction: '补齐项目 .env 登录配置，或通过 --stage-context / ~/.ep-stage/projects.index.json5 指向正确项目后重跑',
+        }));
+        process.exit(2);
+    }
+    let codeList = extractCodeListSummary(pipelineArgs.codeList, {
+        knowledgeRoot: contextResult.context.knowledgeRoot,
+    });
+    let effectiveOverrides = {
+        ...pipelineArgs.debugOverrides,
+        moduleId: pipelineArgs.moduleId,
+        menu: pipelineArgs.menu,
+    };
+    let materialResult = resolveMaterialInventory({
+        codeListPath: pipelineArgs.codeList,
+        codeList,
+        stageContext: contextResult.context,
+        debugOverrides: effectiveOverrides,
+    });
+    if (canPromptInteractively() &&
+        (materialResult.gate.status === 'needs_review' ||
+            materialResult.resolvedInputs.menu.status !== 'resolved' ||
+            materialResult.resolvedInputs.hintsPath.status !== 'resolved')) {
+        const supplementResult = await promptInteractiveCodeListSupplements({
+            codeListPath: pipelineArgs.codeList,
+            codeList,
+            materialResult,
+        });
+        if (supplementResult.skippedWriteBackReason) {
+            process.stdout.write(`${supplementResult.skippedWriteBackReason}\n`);
+        }
+        if (Object.keys(supplementResult.supplements).length > 0) {
+            effectiveOverrides = {
+                ...effectiveOverrides,
+                ...(supplementResult.supplements.moduleId ? { moduleId: supplementResult.supplements.moduleId } : {}),
+                ...(supplementResult.supplements.menu ? { menu: supplementResult.supplements.menu } : {}),
+                ...(supplementResult.supplements.webappDir ? { webapp: path.resolve(supplementResult.supplements.webappDir) } : {}),
+                ...(supplementResult.supplements.javaActionsDir
+                    ? { javaActions: path.resolve(supplementResult.supplements.javaActionsDir) }
+                    : {}),
+                ...(supplementResult.supplements.hintsPath ? { hints: path.resolve(supplementResult.supplements.hintsPath) } : {}),
+            };
+            codeList = extractCodeListSummary(pipelineArgs.codeList, {
+                knowledgeRoot: supplementResult.supplements.knowledgeRoot
+                    ? path.resolve(supplementResult.supplements.knowledgeRoot)
+                    : contextResult.context.knowledgeRoot,
+            });
+            materialResult = resolveMaterialInventory({
+                codeListPath: pipelineArgs.codeList,
+                codeList,
+                stageContext: contextResult.context,
+                debugOverrides: effectiveOverrides,
+            });
+            const baseReasoning = materialResult.trace.reasoningSummary ?? {
+                conclusion: '已完成交互补齐后的物料重解析。',
+                evidenceChain: [],
+                alternatives: [],
+                confidence: 'medium',
+                risks: [],
+                needsHumanReview: false,
+            };
+            materialResult.trace.reasoningSummary = {
+                ...baseReasoning,
+                conclusion: supplementResult.wroteBack
+                    ? `${baseReasoning.conclusion} 已将交互补齐结果写回 code_list.md。`
+                    : supplementResult.skippedWriteBackReason
+                        ? `${baseReasoning.conclusion} 交互补齐仅用于本次运行，未写回 code_list.md。`
+                        : baseReasoning.conclusion,
+                evidenceChain: [
+                    ...baseReasoning.evidenceChain,
+                    ...Object.entries(supplementResult.supplements)
+                        .filter(([, value]) => Boolean(value))
+                        .map(([key, value]) => ({
+                        source: 'human',
+                        path: pipelineArgs.codeList,
+                        text: `${key}=${value}`,
+                    })),
+                ],
+            };
+        }
+    }
+    recordStage(writer, stageSummaries, 'material-inventory', materialResult.trace);
+    if (materialResult.gate.status === 'needs_review') {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '物料清单需要确认',
+            reasoningSummary: materialResult.trace.reasoningSummary,
+            nextAction: '补充 --webapp / --java-actions / --module-id，或修正 stage-context.md 后重跑',
+        }));
+        process.exit(2);
+    }
+    const materialInputs = materialResult.resolvedInputs;
+    const moduleId = resolvedValue(materialInputs.moduleId, 'moduleId');
+    const docsDir = materialInputs.docsDir.status === 'resolved'
+        ? materialInputs.docsDir.path
+        : path.dirname(pipelineArgs.codeList);
+    const webappDir = resolvedPath(materialInputs.webappDir, 'webappDir');
+    const javaActionsDir = resolvedPath(materialInputs.javaActionsDir, 'javaActionsDir');
+    const hints = materialInputs.hintsPath.status === 'resolved'
+        ? JSON.parse(fs.readFileSync(materialInputs.hintsPath.path, 'utf8'))
+        : undefined;
+    const spec = resolveSpec(docsDir, moduleId, codeList);
+    const pages = htmlFiles(webappDir).map(extractHtmlPage);
+    const actions = javaFiles(javaActionsDir).map(extractJavaAction);
+    const pageStructures = pages.map(summarizePageStructure);
+    const evidenceTrace = {
+        stage: 'evidence-extraction',
+        stageLabel: '证据抽取追踪',
+        inputs: [
+            { kind: 'docs_dir', path: docsDir },
+            { kind: 'webapp_dir', path: webappDir },
+            { kind: 'java_actions_dir', path: javaActionsDir },
+        ],
+        outputs: [
+            { kind: 'html_pages', path: String(pages.length) },
+            { kind: 'java_actions', path: String(actions.length) },
+        ],
+        reasoningSummary: {
+            conclusion: `抽取 HTML 页面 ${pages.length} 个，Java Action ${actions.length} 个。`,
+            evidenceChain: pages.map((page) => ({
+                source: 'html',
+                path: page.path,
+                text: page.title || page.pageId,
+            })),
+            alternatives: [],
+            confidence: 'high',
+            risks: [],
+            needsHumanReview: false,
+        },
+        gate: { status: 'confirmed', confirmedBy: 'policy', reason: '确定性 extractor 已完成' },
+    };
+    recordStage(writer, stageSummaries, 'evidence-extraction', evidenceTrace);
+    const contract = buildCrudBusinessModuleContract({
+        moduleId,
+        spec,
+        codeList,
+        pages,
+        actions,
+        hints,
+    });
+    let menuResolution = resolveMenuRouteForPipeline({
+        menu: materialInputs.menu,
+        contract,
+    });
+    const skeletonCoverage = createSkeletonCoverage(contract, hints);
+    const actionCandidates = collectActionCandidates(contract);
+    const baselineWorkflows = planAgentInferredWorkflows({ contract, actions, hints });
+    recordStage(writer, stageSummaries, 'capability-candidates', capabilityCandidatesToTrace({ moduleId, actionCandidates, pageStructures }));
+    const scenarioTrace = inferPageScenarios({
+        moduleId,
+        pages: pageStructures,
+        skeletonCapabilities: skeletonCoverage.coveredWorkflows,
+    });
+    const scenarioCandidateIds = scenarioTrace.candidates.map((item) => item.scenario);
+    if (pipelineArgs.scenario && !scenarioCandidateIds.includes(pipelineArgs.scenario)) {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '场景确认值无效',
+            reasoningSummary: {
+                ...scenarioTrace.reasoningSummary,
+                risks: [
+                    ...scenarioTrace.reasoningSummary.risks,
+                    `--scenario=${pipelineArgs.scenario} 不在候选场景中；候选=${scenarioCandidateIds.join(', ')}`,
+                ],
+                needsHumanReview: true,
+            },
+            nextAction: '从候选场景中选择一个 --scenario 后重跑，或补充证据后重新推理',
+        }));
+        process.exit(2);
+    }
+    const confirmedScenarios = pipelineArgs.scenario ? [pipelineArgs.scenario] : [];
+    const scenarioPayload = {
+        stage: 'scenario-inference',
+        stageLabel: '场景推理追踪',
+        inputs: [{ kind: 'capability_candidates', path: 'capability-candidates.json' }],
+        outputs: [{ kind: 'scenario_candidates', path: 'scenario-inference.json' }],
+        reasoningSummary: pipelineArgs.scenario
+            ? {
+                ...scenarioTrace.reasoningSummary,
+                evidenceChain: [
+                    ...scenarioTrace.reasoningSummary.evidenceChain,
+                    { source: 'human', path: 'cli --scenario', text: `confirmed=${pipelineArgs.scenario}` },
+                ],
+                needsHumanReview: false,
+            }
+            : scenarioTrace.reasoningSummary,
+        candidateCount: scenarioTrace.candidates.length,
+        unresolvedCount: scenarioTrace.candidates.flatMap((item) => item.unresolved).length,
+        gate: pipelineArgs.scenario
+            ? { status: 'confirmed', confirmedBy: 'human', reason: `人工确认场景：${pipelineArgs.scenario}` }
+            : scenarioTrace.gate,
+    };
+    recordStage(writer, stageSummaries, 'scenario-inference', scenarioPayload);
+    // inferPageScenarios 的 gate 恒为 needs_review；默认入口在此停下（退出码 2），
+    // 人工审阅后用 --scenario <场景候选> 复跑表示已确认，方可继续到 skeleton/coverage-diff/testcase。
+    if (scenarioPayload.gate.status === 'needs_review') {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '场景推理需要确认',
+            reasoningSummary: scenarioTrace.reasoningSummary,
+            nextAction: '人工确认后用 --scenario <场景候选> 复跑以继续（confirm / correct / add-evidence / skip）',
+        }));
+        process.exit(2);
+    }
+    recordStage(writer, stageSummaries, 'skeleton-capability-model', skeletonCoverageToTrace(skeletonCoverage));
+    const coverageDiff = createCoverageDiff({
+        moduleId,
+        actionCandidates,
+        skeletonCoverage,
+        baselineWorkflows,
+        pageStructures,
+    });
+    recordStage(writer, stageSummaries, 'coverage-diff', coverageDiffToTrace(coverageDiff));
+    // 泛化指标快照（非 gating）：供 Phase 2 跨系统用 compareObservableRuns 对比，不参与阶段判定。
+    const generalizationMetrics = summarizeGeneralizationRun({
+        moduleId,
+        resolvedInputs: materialResult.resolvedInputs,
+        scenario: scenarioTrace,
+        coverageDiff,
+    });
+    fs.writeFileSync(path.join(writer.traceDir, 'generalization-evaluation.json'), `${JSON.stringify(generalizationMetrics, null, 2)}\n`, 'utf8');
+    const testcases = generateGlueTestcases({
+        contract,
+        menu: menuResolution.status === 'resolved' ? menuResolution.value : UNRESOLVED_MENU_PLACEHOLDER,
+        menuReviewHint: menuResolution.status === 'candidate'
+            ? `menu.candidate: ${menuResolution.candidates.join(' | ')}`
+            : undefined,
+        scenarios: scenarioTrace.candidates.map((item) => item.scenario),
+        confirmedScenarios,
+        coverageDiff,
+    });
+    let testcasesForGate = pipelineArgs.confirmTestcases
+        ? confirmGlueTestcaseDocument(testcases.json)
+        : testcases.json;
+    let testcaseMarkdownForGate = pipelineArgs.confirmTestcases
+        ? applyTestcaseReviewStatusToMarkdown(testcases.markdown, 'confirmed')
+        : testcases.markdown;
+    if (menuResolution.status === 'candidate') {
+        testcasesForGate.reasoningSummary = {
+            ...testcasesForGate.reasoningSummary,
+            evidenceChain: [
+                ...testcasesForGate.reasoningSummary.evidenceChain,
+                {
+                    source: 'human',
+                    path: 'menu-candidates',
+                    text: `menuCandidates=${menuResolution.candidates.join(' | ')}`,
+                },
+            ],
+            risks: [
+                ...testcasesForGate.reasoningSummary.risks,
+                `菜单候选待确认：${menuResolution.candidates.join(' | ')}`,
+            ],
+            needsHumanReview: true,
+        };
+    }
+    const testcaseDir = path.join(contextResult.context.projectDir, 'testcases');
+    fs.mkdirSync(testcaseDir, { recursive: true });
+    fs.writeFileSync(path.join(testcaseDir, `${moduleId}.glue-testcase.json`), `${JSON.stringify(testcasesForGate, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(path.join(testcaseDir, `${moduleId}.glue-testcase.md`), testcaseMarkdownForGate, 'utf8');
+    recordStage(writer, stageSummaries, 'testcase-generation', testcaseGenerationToTrace(testcasesForGate));
+    if (testcasesForGate.cases.some((item) => item.reviewStatus !== 'confirmed')) {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '用例生成需要确认',
+            reasoningSummary: testcasesForGate.reasoningSummary,
+            nextAction: '确认 testcase 中的 candidate / unresolved 后用 --confirm-testcases true 重跑 spec assembly',
+        }));
+        process.exit(2);
+    }
+    if (menuResolution.status !== 'resolved') {
+        if (canPromptInteractively()) {
+            const menuSupplement = await promptMenuAtGate(pipelineArgs.codeList, menuResolution);
+            if (menuSupplement.skippedWriteBackReason) {
+                process.stdout.write(`${menuSupplement.skippedWriteBackReason}\n`);
+            }
+            if (menuSupplement.supplements.menu) {
+                menuResolution = {
+                    status: 'resolved',
+                    value: menuSupplement.supplements.menu,
+                    evidence: menuSupplement.wroteBack
+                        ? 'menu 来自交互补齐并已写回 code_list.md'
+                        : 'menu 来自交互补齐，仅本次运行生效',
+                };
+            }
+        }
+    }
+    if (menuResolution.status !== 'resolved') {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '菜单路径需要确认',
+            reasoningSummary: testcasesForGate.reasoningSummary,
+            nextAction: '补充 code_list.md 的 menu，或用 --menu / stage-context.md 显式确认后重跑 spec assembly',
+        }));
+        process.exit(2);
+    }
+    const outputPaths = resolvePipelineOutputPaths({
+        args: pipelineArgs,
+        projectDir: contextResult.context.projectDir,
+        moduleId,
+    });
+    writeContractArtifact(contract, outputPaths.contractOut);
+    // 契约存在 unresolvedSlots 时停在 gate（与前半段 gate 风格一致），未解析槽位不得进入可执行 spec 组装。
+    if ((contract.unresolvedSlots?.length ?? 0) > 0) {
+        const unresolvedIds = contract.unresolvedSlots.map((slot) => slot.slotId);
+        const unresolvedGate = {
+            stage: 'glue-spec-assembly',
+            stageLabel: '胶水测试组装追踪',
+            inputs: [{ kind: 'crud_contract', path: outputPaths.contractOut }],
+            outputs: [],
+            reasoningSummary: {
+                conclusion: `契约仍有 ${unresolvedIds.length} 个 unresolvedSlots，未达可执行 spec 组装条件。`,
+                evidenceChain: unresolvedIds.map((slotId) => ({
+                    source: 'human',
+                    path: outputPaths.contractOut,
+                    text: `unresolved=${slotId}`,
+                })),
+                alternatives: [],
+                confidence: 'medium',
+                risks: unresolvedIds.map((slotId) => `${slotId} 需人工补充`),
+                needsHumanReview: true,
+            },
+            candidateCount: 0,
+            unresolvedCount: unresolvedIds.length,
+            gate: {
+                status: 'needs_review',
+                reason: `contract 存在 unresolvedSlots：${unresolvedIds.join(', ')}`,
+            },
+        };
+        recordStage(writer, stageSummaries, 'glue-spec-assembly', unresolvedGate);
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '契约存在未解析槽位（unresolvedSlots）',
+            reasoningSummary: unresolvedGate.reasoningSummary,
+            nextAction: '补充 ModuleHints/spec 解析这些槽位后重跑；未解析槽位不得进入可执行 spec',
+        }));
+        process.exit(2);
+    }
+    const specSummary = runSpecAssembly({
+        contractOut: outputPaths.contractOut,
+        specOut: outputPaths.specOut,
+        menu: resolvedValue(menuResolution, 'menu'),
+        testcasePath: outputPaths.testcaseJsonPath,
+    });
+    const specTrace = glueSpecAssemblyToTrace(specSummary);
+    recordStage(writer, stageSummaries, 'glue-spec-assembly', specTrace);
+    if (!specSummary.generated) {
+        writer.writeSummary(stageSummaries);
+        process.stdout.write(renderReviewSummary({
+            title: '胶水测试组装失败',
+            reasoningSummary: specTrace.reasoningSummary,
+            nextAction: '查看 glue-spec-assembly.json 中的 stderr/stdout，修复 generate:playwright-tests 输入后重跑',
+        }));
+        process.exit(2);
+    }
+    const runtimeSummary = runRuntimeResolve({
+        moduleId,
+        menu: resolvedValue(menuResolution, 'menu'),
+        contractOut: outputPaths.contractOut,
+        specOut: outputPaths.specOut,
+        projectDir: contextResult.context.projectDir,
+        headless: pipelineArgs.headless,
+    });
+    recordStage(writer, stageSummaries, 'runtime-gap-inference', runtimeSummaryToTrace(runtimeSummary));
+    const playwrightSummary = runPlaywright({
+        projectDir: contextResult.context.projectDir,
+        specOut: outputPaths.specOut,
+        playwrightProject: pipelineArgs.playwrightProject,
+        headless: pipelineArgs.headless,
+    });
+    recordStage(writer, stageSummaries, 'playwright-execution', playwrightExecutionToTrace(playwrightSummary));
+    const reportSummary = {
+        projectDir: contextResult.context.projectDir,
+        ...readRunInfo(contextResult.context.projectDir),
+    };
+    Object.assign(reportSummary, readGlueReportDetails(reportSummary.stageGlueReportJsonPath));
+    recordStage(writer, stageSummaries, 'glue-report', glueReportToTrace(reportSummary));
+    writer.writeSummary(stageSummaries);
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    void main();
+}