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

package/dist/test/validation/projects-index.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { validateProjectsIndex } from '../../src/validation/projects-index.js';
+describe('validateProjectsIndex', () => {
+    it('通过合法结构（含 systems[] 与 stageCreateVersion）', () => {
+        const obj = {
+            projects: [
+                {
+                    projectName: 'demo',
+                    projectDir: '/abs/demo',
+                    mode: 'glue',
+                    createdAt: '2026-06-25T00:00:00Z',
+                    stageCreateVersion: '0.0.4-alpha.0',
+                    requirements: [],
+                },
+            ],
+            systems: [],
+        };
+        const result = validateProjectsIndex(obj);
+        expect(result.projects).toHaveLength(1);
+        expect(result.projects[0].stageCreateVersion).toBe('0.0.4-alpha.0');
+        expect(result.systems).toEqual([]);
+    });
+    it('缺 systems 字段时报结构化错误', () => {
+        expect(() => validateProjectsIndex({ projects: [] })).toThrow(/systems/);
+    });
+    it('项目条目缺 stageCreateVersion 报错（stage-context.md 砍掉后的元信息承接）', () => {
+        expect(() => validateProjectsIndex({
+            projects: [{ projectName: 'x', projectDir: '/x', mode: 'glue', requirements: [] }],
+            systems: [],
+        })).toThrow(/stageCreateVersion/);
+    });
+    it('不允许残留 stageContextPath / envPath / knowledgeRoot 字段', () => {
+        expect(() => validateProjectsIndex({
+            projects: [
+                {
+                    projectName: 'x',
+                    projectDir: '/x',
+                    mode: 'glue',
+                    createdAt: '2026-06-25T00:00:00Z',
+                    stageCreateVersion: '0.0.4-alpha.0',
+                    requirements: [],
+                    stageContextPath: '/x/stage-context.md', // 应被拒绝
+                },
+            ],
+            systems: [],
+        })).toThrow(/stageContextPath|removed/);
+    });
+});

package/dist/test/validation/testcase.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testcase.test.d.ts.map

package/dist/test/validation/testcase.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase.test.d.ts","sourceRoot":"","sources":["../../../test/validation/testcase.test.ts"],"names":[],"mappings":""}

package/dist/test/validation/testcase.test.js

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { validateTestcase } from '../../src/validation/testcase.js';
+/**
+ * 构造一份满足 v2 schema 的最小合法 testcase（REQ-DATA-02）。
+ *
+ * @returns 合法 testcase v2 对象。
+ */
+function makeValidTestcase() {
+    return {
+        schemaVersion: 'v2',
+        scenario: '组织管理 CRUD 主流程',
+        moduleId: 'org-management',
+        moduleName: '组织管理',
+        menuPath: '系统管理 > 组织管理',
+        requiredSystems: [{ url: 'http://example.test', systemName: '基础平台' }],
+        requiredRoles: [{ role: '系统管理员', hint: '可访问组织管理菜单' }],
+        coveredActions: [
+            { actionId: 'create', kind: 'create', evidence: ['html=org-list.html#btn-add'] },
+        ],
+        uncoveredCandidates: [
+            {
+                actionId: 'export',
+                label: '导出',
+                status: 'planned',
+                requiredRole: '系统管理员',
+                businessIntent: '导出当前查询结果',
+                assertionExpectation: '断言下载文件存在',
+                evidence: ['hint=ModuleHints.export'],
+            },
+        ],
+        cases: [
+            {
+                caseId: 'CASE-001',
+                title: '管理员新增组织',
+                scenario: '组织管理 CRUD 主流程',
+                reviewStatus: 'confirmed',
+                requiredRole: '系统管理员',
+                evidence: ['spec=org-management.spec.yaml#create'],
+                steps: ['打开菜单', '点击新增'],
+                assertions: ['列表出现新组织'],
+                unresolved: [],
+            },
+        ],
+        reasoningSummary: {
+            conclusion: '主流程覆盖增删改查',
+            evidenceChain: ['html=org-list.html'],
+            alternatives: [],
+            confidence: 'high',
+            risks: [],
+            needsHumanReview: false,
+        },
+    };
+}
+describe('validateTestcase', () => {
+    it('合法 v2 testcase 通过', () => {
+        const result = validateTestcase(makeValidTestcase());
+        expect(result.schemaVersion).toBe('v2');
+        expect(result.cases).toHaveLength(1);
+    });
+    it('缺 schemaVersion 报版本错误引导重跑（v1 升级路径）', () => {
+        const tc = makeValidTestcase();
+        delete tc.schemaVersion;
+        expect(() => validateTestcase(tc)).toThrow(/schemaVersion|v2|重跑/);
+    });
+    it('schemaVersion 非 v2（视作 v1）也走版本错误引导重跑', () => {
+        const tc = { ...makeValidTestcase(), schemaVersion: 'v1' };
+        expect(() => validateTestcase(tc)).toThrow(/schemaVersion|v2|重跑/);
+    });
+    it('缺 scenario 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.scenario;
+        expect(() => validateTestcase(tc)).toThrow(/scenario/);
+    });
+    it('缺 menuPath 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.menuPath;
+        expect(() => validateTestcase(tc)).toThrow(/menuPath/);
+    });
+    it('缺 requiredSystems[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.requiredSystems;
+        expect(() => validateTestcase(tc)).toThrow(/requiredSystems/);
+    });
+    it('缺 requiredRoles[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.requiredRoles;
+        expect(() => validateTestcase(tc)).toThrow(/requiredRoles/);
+    });
+    it('缺 coveredActions[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.coveredActions;
+        expect(() => validateTestcase(tc)).toThrow(/coveredActions/);
+    });
+    it('缺 uncoveredCandidates[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.uncoveredCandidates;
+        expect(() => validateTestcase(tc)).toThrow(/uncoveredCandidates/);
+    });
+    it('uncoveredCandidates[].requiredRole 缺失报错', () => {
+        const tc = makeValidTestcase();
+        const uncovered = tc.uncoveredCandidates;
+        delete uncovered[0].requiredRole;
+        expect(() => validateTestcase(tc)).toThrow(/uncoveredCandidates.*requiredRole/);
+    });
+    it('coveredActions[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const covered = tc.coveredActions;
+        covered[0].evidence = ['某条非法 evidence 字符串'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('uncoveredCandidates[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const uncovered = tc.uncoveredCandidates;
+        uncovered[0].evidence = ['plainstring'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('cases[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const cases = tc.cases;
+        cases[0].evidence = ['noequalsign'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('evidence kind 必须在 html/java/spec/contract/skeleton/hint 范围内', () => {
+        const tc = makeValidTestcase();
+        const covered = tc.coveredActions;
+        covered[0].evidence = ['unknownkind=foo.html'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+});

package/docs/README.md

@@ -1,4 +1,4 @@
-# @epoint/ep-stage-skill
+# @epoint-testtech/ep-stage-skill
 
 > 胶水编码链路 Agent Skill — 解析上游物料，按契约生成可执行测试脚本
 
@@ -11,8 +11,8 @@
 AI Agent 可发现的 Skill 入口（Claude Code 扫 `.claude/skills/`、Codex 扫 `.agents/skills/`，均 symlink 到包内源）：
 
 ```text
-.claude/skills/{glue-test, create-project, recording-to-glue}
-.agents/skills/{glue-test, create-project, recording-to-glue}
+.claude/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
+.agents/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
   → packages/ep-stage-skill/codex-skill/ep-stage/<skill>/
 ```
 
@@ -31,11 +31,11 @@ AI Agent 可发现的 Skill 入口（Claude Code 扫 `.claude/skills/`、Codex
 
 ```bash
 # 可观测默认入口（推荐）
-pnpm --filter @epoint/ep-stage-skill run:gap-pipeline -- \
+pnpm --filter @epoint-testtech/ep-stage-skill run:gap-pipeline -- \
   --code-list <code_list.md>
 
 # 生成契约
-pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
+pnpm --filter @epoint-testtech/ep-stage-skill generate:crud-contract -- \
   --module-id <模块ID> \
   --docs <上游文档目录> \
   --code-list <code_list.md> \
@@ -45,7 +45,7 @@ pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
   --out output/<module>.crud.contract.json
 
 # 生成测试脚本
-pnpm --filter @epoint/ep-stage-skill generate:playwright-tests -- \
+pnpm --filter @epoint-testtech/ep-stage-skill generate:playwright-tests -- \
   --contract output/<module>.crud.contract.json \
   --out <glue项目>/src/tests/<name>.spec.ts \
   --menu "一级菜单>二级菜单" \

package/docs/mvp-usage-guide.md

@@ -1,8 +1,8 @@
-# glue-test CRUD 契约生成器 — MVP 使用手册
+# glue-run-test CRUD 契约生成器 — MVP 使用手册
 
 ## 概述
 
-`glue-test` 是一个 TypeScript agent skill，用于从上游业务模块物料中提取结构化信息，归一化为 `crud-business-module/v1` 契约 JSON。该契约作为 AI Agent 生成 Playwright 测试脚本的地基，确保 Agent 不需要自己编造 selector、按钮文本或业务预期。
+`glue-run-test` 是一个 TypeScript agent skill，用于从上游业务模块物料中提取结构化信息，归一化为 `crud-business-module/v1` 契约 JSON。该契约作为 AI Agent 生成 Playwright 测试脚本的地基，确保 Agent 不需要自己编造 selector、按钮文本或业务预期。
 
 当前 MVP 只面向公司自研 `zwplace` CRUD 场景，负责：
 
@@ -14,7 +14,7 @@
 ## 数据流
 
 ```
-上游物料                          glue-test                        输出
+上游物料                          glue-run-test                        输出
 ┌──────────────┐               ┌──────────────┐               ┌──────────────┐
 │ HTML 页面    │──extractor──→ │              │               │              │
 │ spec.yaml    │──extractor──→ │  normalizer  │──CLI 输出──→  │ 契约 JSON    │

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@epoint-testtech/ep-stage-skill",
-  "version": "0.0.3-alpha.2",
+  "version": "0.0.4-alpha.1",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "bin": {
+    "ep-stage-skill": "./dist/src/cli/index.js"
+  },
   "files": [
     "dist",
     "codex-skill",
@@ -31,8 +34,10 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "build": "tsc",
-    "generate:crud-contract": "node --import tsx src/cli/generate-crud-contract.ts",
-    "generate:playwright-tests": "node --import tsx src/cli/generate-playwright-tests.ts",
-    "run:gap-pipeline": "node --import tsx src/cli/run-gap-pipeline.ts"
+    "generate:crud-contract": "node --import tsx src/cli/dev/extract-contract.ts",
+    "generate:playwright-tests": "node --import tsx src/cli/index.ts spec",
+    "run:gap-pipeline": "node --import tsx src/cli/run-gap-pipeline.ts",
+    "cli": "node --import tsx src/cli/index.ts",
+    "generate:testcase": "node --import tsx src/cli/index.ts testcase"
   }
 }

package/codex-skill/ep-stage/create-project/SKILL.md

@@ -1,59 +0,0 @@
----
-name: create-project
-description: 使用时机：当用户需要通过现有 stage-create CLI 创建 ep-stage Playwright 项目（尤其是 default 或 glue 模式项目）时使用。
----
-
-# ep-stage: create-project
-
-当用户需要创建 ep-stage 项目，或要求生成 glue 模式（glue-mode）Playwright 脚手架时，使用本 skill。
-
-## 行为契约（Behavior Contract）
-
-本 skill 引导 Agent 调用现有 `@epoint/stage-create` CLI，不重新实现脚手架逻辑。
-
-当前命令示例：
-
-```bash
-stage-create my-glue-project --mode glue
-stage-create my-default-project --mode default
-```
-
-## 必填输入
-
-- 项目名称（project name）：必填，缺失时必须向用户询问。
-- 模式（mode）：`glue` 或 `default`，缺失时必须向用户询问。
-
-不要自行猜测项目名称。不要发明名为 `ep-stage: create-project` 的命令——那是 skill 名称，不是 shell 命令。
-
-## 模式选择指引
-
-- 当项目需要包含胶水骨架（glue skeletons）、页面组件（page components）、报告辅助（report helpers）以及物料驱动的测试生成时，使用 `glue` 模式。
-- 当项目只需要标准 Playwright 基线时，使用 `default` 模式。
-
-## 验证
-
-创建项目后，验证输出目录存在且包含：
-
-```text
-package.json
-playwright.config.ts
-tsconfig.json
-```
-
-对于 `glue` 模式，还需验证：
-
-```text
-src/skeletons/
-src/web/component/
-src/report/
-```
-
-## glue 项目上下文
-
-创建 glue 项目后必须生成（由 stage-create CLI 交互写入）：
-
-- `<project>/stage-context.md`
-- `<project>/.env`
-- `~/.ep-stage/projects.index.json5`
-
-这些文件供后续 `glue-testcase` 和 `glue-test` 内置读取，不依赖用户项目存在 `AGENTS.md`。

package/codex-skill/ep-stage/glue-test/SKILL.md

@@ -1,258 +0,0 @@
----
-name: glue-test
-description: 使用时机：当需要从上游需求文档、code_list.md、生成的 HTML 页面、Java Action 源码、ModuleHints 或 CrudFlowSlots 组装 ep-stage 项目的 Playwright CRUD 胶水测试（glue-code tests），或运行端到端 gap 推理工作流时使用。
-compatibility: 需要 Codex workspace 环境，配备 pnpm、Node.js、packages/ep-stage-skill，以及由 stage-create 生成的 glue 模式 Playwright 项目。
-metadata:
-  source-package: "@epoint/ep-stage-skill"
-  contract: "crud-business-module/v1"
----
-
-# ep-stage: glue-test
-
-ep-stage 项目中的胶水编码工作流使用本 skill。
-
-## 概览（Overview）
-
-本 skill 通过确定性提取器（deterministic extractors）、显式的 `ModuleHints` 策略文件、glue 模式 CRUD 骨架以及 gap runtime pipeline，将上游业务物料转换为可执行的 Playwright 胶水测试。
-
-核心原则：Agent 负责组装并核实证据，不自行发明选择器（selector）、iframe 关键字、按钮文案、listbox 取值、数据唯一性规则或业务断言。
-
-**默认入口**：当用户要求端到端验证、运行时 gap 推理，或"静态组装 + 动态推理 + 落袋合并"时，优先使用一键 pipeline `run:gap-pipeline`。仅当用户明确希望在不执行真实页面的情况下生成 contract/spec 时，才回退到旧的两步离线流程。
-
-## 当前后端（Current Backend）
-
-当前运行时后端是 `@epoint/ep-stage-skill` 中现有的 CRUD + Export + gap pipeline。
-
-本期只承载 skill 入口与工作流描述，不改变 `crud-business-module/v1`，不引入 `skeleton-registry`。当前已支持**默认入口所需字段**的轻量交互补齐：当 `run:gap-pipeline` 在 `material-inventory` 或 `menu` gate 发现 `code_list.md` 缺少 `knowledgeRoot`、`menu`、HTML、Java Action、`ModuleHints` 等关键入口信息时，TTY 环境下会提示用户补齐，并优先写回**可写的** `code_list.md`。当前仓内的真实业务验收主线是 `zwplace`，其唯一上游扎口是 `knowledge-project/epoint-web-v9.5.2/_docs/code_list.md`；仓内 `packages/ep-stage-skill/examples/zwplace.observable.code_list.md` 只是该只读物料的可写镜像。骨架项目或脚手架里顺带出现的说明信息不应替代 `code_list.md` 成为本源。非 CRUD 工作流泛化、`skeleton-registry`、交互式 `review-gaps` CLI 属于第二期源码级改造范围。
-
-若后续要验证“不同系统的普通 CRUD 泛化”，应由用户补充第二个真实业务样本的 `code_list.md`；不要在当前链路中用脚手架说明信息、运行产物或旁证文档反推出第二个模块充当本源。
-
-**真实系统 E2E 运行约束：**
-
-- 禁止用 `--headless true` 跑真实业务系统 E2E。
-- 真实系统验证必须通过 `packages/ep-stage-skill/codex-skill/ep-stage` 这套 skill / `run:gap-pipeline` 入口，以 `--headless false` 运行。
-- 运行过程中必须有人在场观察页面行为、弹窗、登录状态和业务副作用；无人工观察的无头回放不算当前阶段验收证据。
-- `--headless true` 仅允许用于本地调试、结构验证或历史对比，不作为真实系统验收方式。
-
-## 工作流（Workflow）
-
-完整链路按步骤解耦如下：
-
-```text
-explore-materials
-  -> generate-contract
-  -> match-skeleton
-  -> review-gaps
-  -> generate-spec
-  -> infer-gaps
-  -> run-tests
-  -> generate-report
-```
-
-每个步骤既可端到端串联调用，也可单步独立调用（便于排查链路中某一步的问题、迭代局部产出、对中间产物有干预窗口）。
-
-## 适用场景（Use This For）
-
-- 从需求文档、`code_list.md`、生成的 HTML 和 Java Action 文件生成 `crud-business-module/v1` 契约。
-- 生成调用 `LoginPage`、`MenuPage` 和 `CrudPage` 并使用 `CrudFlowSlots` 的 `.spec.ts` 文件。
-- 运行一键胶水 E2E 验证：静态组装 -> 运行时 gap 解决 -> 追加 `Custom` 测试 -> 执行 Playwright -> 产出 glue-report。
-- 当数据主键、搜索条件、listbox 取值、按钮别名、自动填充覆盖或删除策略属于策略决策时，更新 `ModuleHints`。
-- 模拟胶水编码链路：上游物料 -> 契约 -> 动态槽位 -> CRUD 骨架 -> Playwright 脚本 -> 编译/运行时验证。
-- 识别 CRUD + Export 骨架未覆盖的业务动作，并输出 `agentInferredWorkflows`。
-- 使用 `ModuleHints.customWorkflows` 约束自定义工作流的业务意图和断言预期。
-
-不要将本 skill 用于绕过骨架的自由式 Playwright 编写，或用于 `stage-core` 核心运行时改动。
-
-## 必须遵循的工作流（Required Workflow）
-
-### 优先路径：一键 gap pipeline
-
-1. 定位当前仓库根目录，确认 `packages/ep-stage-skill/package.json` 存在。
-2. 运行前检查上游物料：
-   - docs 目录，通常包含 `spec.yaml` 或模块文档
-   - `code_list.md`
-   - 生成的网页 HTML 目录
-   - Java Action 源码目录
-   - `ModuleHints` JSON
-3. 运行 `run:gap-pipeline`。
-4. 检查生成的摘要：
-   - `contractPath`
-   - `specPath`
-   - `runTimestamp`
-   - `stageGlueReportHtmlPath`
-   - `playwrightReportDirPath`
-   - `resolvedWorkflows` / `needsReviewWorkflows`
-5. 若运行时 gap 解决失败，报告失败发生在：
-   - 上游提取
-   - 契约生成
-   - spec 生成
-   - 运行时解决
-   - Playwright 执行
-
-### 回退路径：离线两步生成
-
-1. 定位当前仓库根目录，确认 `packages/ep-stage-skill/package.json` 存在。
-2. 生成前检查上游物料：
-   - docs 目录，通常包含 `spec.yaml` 或模块文档
-   - `code_list.md`
-   - 生成的网页 HTML 目录
-   - Java Action 源码目录
-   - `ModuleHints` JSON
-3. 使用 `packages/ep-stage-skill` 生成契约。
-4. 检查生成的契约：
-   - `contractVersion` 为 `crud-business-module/v1`
-   - `module.id` 和 `module.label` 与上游模块一致
-   - `searchConditions` 包含预期的 CRUD 搜索条件
-   - 在生成最终 spec 前 `unresolvedSlots` 为空
-5. 将 Playwright spec 生成到 glue 模式项目中。
-6. 验证生成的 spec 在消费方 glue 项目中能编译通过。
-7. 仅当所需环境与业务系统可用时才运行 Playwright。
-
-详细命令模式见 `references/crud-pipeline.md`。
-
-## Gap 评审协议（Gap Review Protocol）
-
-在运行时推理之前，尽可能向用户呈现 gap 清单：
-
-- `planned` 状态的 gap 可以进入运行时推理。
-- `candidate` 和 `unresolved` 状态的 gap 不得盲目追加到 spec。
-- 若某个 gap 缺少业务意图或断言预期，应询问用户是补充 `ModuleHints.customWorkflows`、本轮跳过，还是留待后续处理。
-
-详细的第一期行为契约见 `references/gap-review-protocol.md`。
-
-## 治理规则（Harness Rules）
-
-在保证可靠性的前提下，使用最轻量的治理方式：
-
-| 治理关注点 | glue-test 规则 |
-| --- | --- |
-| 上下文交接（Context handoff） | 将契约 JSON 和生成的 spec 作为版本化产物保留。 |
-| 渐进式披露（Progressive disclosure） | 先加载本文件；仅按需打开 references。 |
-| 确定性（Determinism） | 优先使用提取器和 CLI 输出，而非 Agent 猜测。 |
-| 策略隔离（Strategy isolation） | 将人工/测试人员的决策放入 `ModuleHints`，而非提取器代码。 |
-| 评估（Evaluation） | 检查契约结构、编译输出，以及（可选）真实 Playwright 行为。 |
-| 反过拟合（Anti-overfit） | 将 `zwplace` 视为示例 fixture，而非唯一支持的模块。 |
-
-治理原则的完整说明见 `references/harness-principles.md`。
-
-## 快速命令格式（Quick Command Shape）
-
-### 优先：一键 gap pipeline
-
-```bash
-pnpm --filter @epoint/ep-stage-skill run:gap-pipeline -- \
-  --module-id <module-id> \
-  --docs <upstream-docs-dir> \
-  --code-list <upstream-code-list-md> \
-  --webapp <upstream-html-dir> \
-  --java-actions <upstream-java-action-dir> \
-  --hints <module-hints-json> \
-  --menu "<menu-path>" \
-  --project-dir <glue-project-dir> \
-  --headless false
-```
-
-当用户要求以下场景时使用：
-
-- 真实端到端验证
-- 运行时 gap 推理
-- 真实页面补证据
-- 自动把 `Custom` test 追加到现有 suite
-
-### 回退：仅离线生成
-
-```bash
-pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
-  --module-id <module-id> \
-  --docs <upstream-docs-dir> \
-  --code-list <upstream-code-list-md> \
-  --webapp <upstream-html-dir> \
-  --java-actions <upstream-java-action-dir> \
-  --hints <module-hints-json> \
-  --out output/<module-id>.crud.contract.json
-
-pnpm --filter @epoint/ep-stage-skill generate:playwright-tests -- \
-  --contract output/<module-id>.crud.contract.json \
-  --out <glue-project>/src/tests/<name>.spec.ts \
-  --menu "<menu-path>"
-```
-
-通过 `pnpm --filter` 传路径时，上游文件和输出 spec 建议使用绝对路径。相对路径从 `packages/ep-stage-skill` 解析。
-
-真实系统 E2E 请固定使用：
-
-```bash
-pnpm --filter @epoint/ep-stage-skill run:gap-pipeline -- \
-  --code-list <code_list.md> \
-  --project-dir <glue-project-dir> \
-  --scenario <confirmed-scenario> \
-  --headless false
-```
-
-## 常见错误（Common Mistakes）
-
-- 用户明确要 E2E 验证时，仍然只跑 `generate:crud-contract` + `generate:playwright-tests`，没有进入 `run:gap-pipeline`。
-- 在 `unresolvedSlots` 非空时使用生成的 `.spec.ts`。
-- 从截图猜测 listbox 取值，而不是将冒烟测试值放入 `ModuleHints.searchConditions`。
-- 把 `dataKey` 和 `searchConditions` 当作互相竞争的独立策略。当前 glue CRUD 流程由 `searchConditions` 驱动。
-- 在生成的 spec 中内联 `page.fill()` 或 `page.click()` 流程，而不是调用骨架。
-- 当真实系统、登录环境或内网不可用时，仍假设业务 Playwright 运行失败是代码问题。
-- 只凭按钮文本生成 Custom test。
-- 把 `candidate` 或 `unresolved` 的 gap workflow 直接追加到 spec。
-- 在 runtime gap resolve 阶段修改 `businessIntent` 或 `assertionExpectation`。
-- 在 gap 代码中修改 `src/skeletons/*.ts`。
-
-## 边界（Boundaries）
-
-不要声称本期已实现非 CRUD 工作流的生成。若用户要求审批流、流程发起或表单提交等超出当前后端能力的工作流，应说明这些属于第二期源码级泛化范围。
-
-处理运行时 gap 推理时，不要修改 `src/skeletons/*.ts`。
-
-## 参考文档（References）
-
-- `references/crud-pipeline.md`：通用 CRUD 组装 pipeline 与验证命令。
-- `references/harness-principles.md`：本 skill 如何在不发生过拟合（不绑定单一模块或模型）的前提下应用 harness 工程。
-- `references/gap-review-protocol.md`：`review-gaps` 步骤的第一期 Agent 行为协议。
-- `scripts/generate-crud-spec.mjs --help`：两个包 CLI 的确定性封装。
-
-## 可观测默认入口
-
-默认只要求用户提供 `code_list.md`（`run:gap-pipeline -- --code-list <path>`）。`code_list.md` 是上游物料统一输入扎口：端到端链路需要的 `knowledgeRoot`、`menu` / `menuPath`、HTML、Java Action、spec、ModuleHints 等上游路径信息应优先写入该文件。当前 repo 的真实验收口径下，应优先把 `knowledge-project/epoint-web-v9.5.2/_docs/code_list.md` 视为真相源；若因主仓只读无法直接回写，再退到它的可写镜像 `packages/ep-stage-skill/examples/zwplace.observable.code_list.md`。若缺失入口字段：
-
-- `material-inventory` gate 会在 TTY 环境下提示补齐 `knowledgeRoot` / `moduleId` / `webappDir` / `javaActionsDir` / `hintsPath` / `menu`。
-- `menu` gate 会在 TTY 环境下再次提示确认菜单路径。
-- 若目标 `code_list.md` 位于**主仓只读** `knowledge-project/...`，补齐结果只对本次运行生效，不会写回受保护物料；若目标是外置可写 `code_list.md`，则会按当前格式回写。
-
-调试时可继续传 `--docs`、`--webapp`、`--java-actions`、`--hints`、`--project-dir`、`--menu` 做覆盖；覆盖参数只用于开发观测，不作为默认业务输入方式。场景推理后用 `--scenario <候选>` 人工确认继续。
-
-若目标是**真实系统验收**，除场景确认外还必须满足：
-
-- 以 `--headless false` 有头模式运行；
-- 运行时有人观察页面实际行为；
-- 将观察结论与 `.stage/trace/<run-id>/summary.md`、`playwright-execution.json`、`glue-report` 交叉核对后，才可作为验收证据。
-
-当前一期对“普通 CRUD，不考虑嵌套 CRUD”的处理口径是：
-
-- 若人工确认场景为 `crud.single-page`，`nestedCrudCandidates` 仍保留在 coverage / reasoning 证据中；
-- 但它们不再阻断 testcase gate，不需要再额外 `--confirm-testcases` 才能继续普通 CRUD 主链路；
-- 真正的业务失败应由后续 runtime / playwright / glue-report 给出结构化结论。
-
-链路顺序（每阶段写 `.stage/trace/<run-id>/*.json` + `summary.md`）：
-
-```text
-code_list.md
-  -> context-resolution
-  -> material-inventory (gate)
-  -> evidence-extraction
-  -> capability-candidates
-  -> scenario-inference (gate, --scenario 确认)
-  -> skeleton-capability-model
-  -> coverage-diff
-  -> glue-testcase (gate)
-  -> glue spec assembly (unresolvedSlots gate)
-  -> runtime gap inference
-  -> Playwright execution
-  -> glue-report
-```
-
-任一 gate `needs_review` 时停止（退出码 2），不继续后续阶段。用例中间产物由 `glue-testcase` skill 负责审阅。