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

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ep-stage-skill-package
-description: 使用时机：当需要维护 @epoint/ep-stage-skill 包源码、CLI 提取器、CRUD 契约生成器，或面向 Codex 的 ep-stage skill 资产时使用。
+description: 使用时机：当需要维护 @epoint-testtech/ep-stage-skill 包源码、CLI 提取器、CRUD 契约生成器，或面向 Codex 的 ep-stage skill 资产时使用。
 ---
 
-# @epoint/ep-stage-skill 包
+# @epoint-testtech/ep-stage-skill 包
 
 本包负责面向 Codex 的 `ep-stage` skill 背后的确定性工具链：
 

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

@@ -0,0 +1,186 @@
+---
+name: glue-create-project
+description: 使用时机：当用户表达「创建胶水项目 / 测试脚手架 / 新建 glue 项目」或显式触发 `/glue-create-project [名称或路径]` 时使用。本 skill 只创建胶水模式（glue）Playwright 测试脚手架，不收集登录信息，不写 .env / stage-context.md。
+version: 2026-06-25+562b629
+argument-hint: "<脚手架项目名或脚手架项目路径>"
+---
+
+# ep-stage: glue-create-project
+
+本 skill 引导 Agent **包装** `@epoint-testtech/stage-create` CLI 的 glue 模式，不重新实现脚手架。用户视角全中文，不暴露 CLI 名称。
+
+> CLI 自 0.0.4-alpha.0 起已中性化：不再收集业务系统登录信息，不再写 `<projectDir>/.env`，也不再写 `<projectDir>/stage-context.md`。项目元信息全部沉到 `~/.ep-stage/projects.index.json5`（含 `stageCreateVersion`）。登录凭据由下游 `glue-generate-testcase` / `glue-run-test` 在需求级 `credentials.json5` 中收集。
+
+## 1. 自然语言映射规则
+
+用户在 Claude Code / Codex 里触发 skill 的典型形式：
+
+```text
+/glue-create-project my-project              # 裸名 → 落 <pwd>/e2e-test/my-project
+/glue-create-project path/my-project         # 含 / → 原样落点
+/glue-create-project /abs/path/my-project    # 绝对路径 → 原样落点
+/glue-create-project                         # 无参数 → 问项目名
+```
+
+### 1.1 目标位置与项目名（路径解析三段式）
+
+CLI 接收 `[project-name]` 参数，内部用 `path.basename` 取项目名、`path.resolve` 取输出目录（基于 Agent cwd）：
+
+| 用户输入                                    | skill 传给 CLI 的值                         | 最终落点                                |
+|---------------------------------------------|---------------------------------------------|-----------------------------------------|
+| 含 `/` 或绝对路径                           | 原样透传                                    | `<cwd>/...` 或绝对路径；项目名取 basename |
+| 裸名（无 `/`）                              | 拼成 `e2e-test/<name>`                      | `<cwd>/e2e-test/<name>`                 |
+| 无参数                                      | 先问 `<name>`，再拼 `e2e-test/<name>`        | `<cwd>/e2e-test/<name>`                 |
+
+**逃生口**：想在当前 cwd 根直接建裸名（不进 `e2e-test/`），用 `./my-project`（含 `/`）。
+
+中文目录名 macOS/Linux 能建，但 npm scope 校验和跨平台兼容差。Agent 收到中文名时，AskUserQuestion 二选一：保留中文 / 换 kebab-case 建议（如 `我的项目` → `my-project`）。
+
+### 1.2 模式 — 固定 glue
+
+本 skill 只创建 glue 项目，固定传 `--mode glue`，不暴露 default 模式入口。
+
+### 1.3 工作目录 (cwd) 确认
+
+Agent 在调用 CLI 前必须：跑 `pwd` → 按 §1.1 算最终落点 → 中文复述"将在 `<最终落点>` 下创建项目，确认吗？" → 用户否认 → 让用户给绝对路径或先 `cd` 切换。
+
+典型陷阱：cwd 是 git 仓库根（存在 `.git/`）时必须额外二次确认，避免污染该仓库工作树。
+
+## 2. Agent 执行剧本（7 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：
+
+- 加载 skill 后**立即**打印初始任务清单（Step 0）。
+- 每完成一步，输出单行状态更新 `✅ 第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`（不重写完整清单）。
+- Step 7 输出全勾选终态清单 + 完成摘要。
+
+### Step 0 — 打印任务清单
+
+```markdown
+📋 **创建胶水测试项目任务清单**
+
+- [ ] 第 1 步 — 抽取项目名与落点
+- [ ] 第 2 步 — 补齐核心参数（含 cwd 确认）
+- [ ] 第 3 步 — 调用脚手架 CLI
+- [ ] 第 4 步 — 验证脚手架产物
+- [ ] 第 5 步 — 安装依赖
+- [ ] 第 6 步 — 写入项目索引
+- [ ] 第 7 步 — 输出摘要
+```
+
+### Step 1 — 抽取项目名与落点
+
+从用户原始消息 / args 抽取目标路径/项目名（规则见 §1）。模式固定 glue。中文复述识别结果：
+
+> 已识别：项目名 = `xxx`，模式 = `胶水模式 (glue)`，落点 = `<pwd>/e2e-test/xxx`。
+
+识别失败/不确定 → Step 2 补齐。
+
+### Step 2 — 补齐核心参数（含 cwd 确认）
+
+只在缺失/有疑时触发，全中文：
+
+- 缺 `projectName`（无参数）→ free text 询问"请告诉我新项目的名称"，按 §1.1 拼 `e2e-test/<name>`。
+- 中文项目名 → AskUserQuestion 二选一：保留中文 / 换 `<kebab-case 建议>`。
+- cwd 是 git 仓库根 → AskUserQuestion 二选一：在此 cwd 创建 / 取消并手动 cd。
+
+> 本 skill 固定 glue 模式，不再收集登录信息，无需就模式或登录配置询问。
+
+### Step 3 — 调用脚手架 CLI
+
+固定命令形式（不 which、不扫 monorepo、不 cd 进项目、**不喂 stdin**）。`<targetPath>` 由 §1.1 算出：
+
+```bash
+npx -y @epoint-testtech/stage-create@latest "<targetPath>" --mode glue
+```
+
+CLI 中性化后**不读 stdin**，不询问登录 URL / 用户名 / 密码 / 知识库根。
+
+### Step 4 — 验证脚手架产物
+
+按 §4 验证产物。验证失败 → §3 错误处理报告，不发完成提示。
+
+### Step 5 — 安装依赖
+
+1. 先 `pnpm ping` 检测 registry 连通性：
+   - 连不上（超时/报错）→ 跳过自动安装，提示 `网络不通，依赖未自动安装，请手动执行: pnpm install --dir <projectDir>`。
+   - 连通 → 进入下一步。
+2. `pnpm install --dir "<projectDir>"`（**禁用 `cd`** 进入项目目录，必须用 `--dir`）。若 `<projectDir>` 位于某个 pnpm workspace 内（向上能找到 `pnpm-workspace.yaml`），改用 `pnpm install --dir "<projectDir>" --ignore-workspace` 做独立安装。
+3. **必须实时透传 pnpm 输出**（进度条、日志），不得静默执行。安装失败 → 如实报告 stderr，不谎报成功；骨架已生成，用户可手动重跑。
+
+### Step 6 — 写入项目索引
+
+CLI 0.0.4-alpha.0 已在 `~/.ep-stage/projects.index.json5` 的 `projects[]` 数组末尾追加本项目条目（字段精简，含 `stageCreateVersion`，**不含** `envPath/stageContextPath/knowledgeRoot/codeListPaths`）。Agent 校验：
+
+- 文件存在
+- 末尾条目 `projectDir` 与本次创建一致
+- 字段含 `projectName / projectDir / mode='glue' / createdAt / stageCreateVersion / requirements=[]`
+
+JSON5 项目条目范例（CLI 自动写）：
+
+```json5
+// ~/.ep-stage/projects.index.json5 项目条目范例（CLI 自动写，无 stageContextPath/envPath/knowledgeRoot）
+{
+  projectName: '<projectName>',
+  projectDir: '<绝对路径>',
+  mode: 'glue',
+  createdAt: '2026-06-25T...',
+  stageCreateVersion: '0.0.4-alpha.0',
+  requirements: [],
+}
+```
+
+条目缺失 → 提示"索引文件未登记本项目，后续 ep-stage skills/CLI 无法发现，请检查 stage-create CLI 版本（应 ≥ 0.0.4-alpha.0）"。
+
+### Step 7 — 输出摘要
+
+打印全勾选终态清单 + §5 完成提示。
+
+## 3. 错误处理
+
+| CLI 错误（原文）                  | 触发时机    | Agent 中文呈现 + 建议                                                                                                |
+|-----------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------|
+| `目录已存在: <path>` (exit 1)     | Step 3 前置 | "目录 `<path>` 已存在。我不会主动删除任何已存在目录。" → AskUserQuestion 三选一：换名重来 / 改 cwd / 取消              |
+| npm `404 / ENOTFOUND / ETIMEDOUT` | npx 拉包失败 | "无法从 npm 拉取 @epoint-testtech/stage-create" → 建议 ① 检查网络 ② `npm config get registry` ③ `npm i -g` 预装        |
+| 其他 exit !== 0                   | CLI 崩溃    | 把 stderr 原文中文转述并贴出，建议复制错误私聊开发                                                                   |
+
+**半成品回滚**：CLI 在校验失败时（目录已存在）在 `mkdirSync` 之前退出，无副作用。若 CLI 已 `mkdirSync` 后中途崩，Agent **不主动 `rm`**，提示用户手动检查 `<path>` 后决定是否 `rm -rf` 重试。理由：cwd 不一定可信，盲删可能误伤。
+
+**用户中途取消**：AskUserQuestion 阶段等待不超时；自然对话阶段说「算了/取消/stop」立即终止不调 CLI；已调 CLI 后用户取消 → CLI 无中途取消信号，等 CLI 退出后再复述结果。
+
+## 4. 验证清单
+
+CLI 退出后必须用 `ls` / `Read` 校验产物。验证失败视为整体失败，不要谎报成功。
+
+| 路径                                | 说明                          |
+|-------------------------------------|-------------------------------|
+| `<projectDir>/package.json`         | 模板渲染产出                  |
+| `<projectDir>/playwright.config.ts` | Playwright 基础配置           |
+| `<projectDir>/tsconfig.json`        | TS 配置                       |
+| `<projectDir>/src/skeletons/`       | 业务骨架目录（非空）          |
+| `<projectDir>/src/web/component/`   | 页面组件目录                  |
+| `<projectDir>/src/report/`          | 报告辅助目录                  |
+| `~/.ep-stage/projects.index.json5`  | 用户级索引，应新增本项目条目  |
+
+> **不再校验** `<projectDir>/.env`（CLI 不再写）和 `<projectDir>/stage-context.md`（CLI 不再写，元信息已沉到 projects.index.json5）。
+
+**不验证什么**：模板占位符 `{{projectName}}` 是否替换（已由 stage-create prepublish 校验）；业务系统登录配置（中性化后不再涉及）。
+
+## 5. 完成提示
+
+Step 7 验证与依赖安装都通过后，按以下中文格式呈现结果。不要用英文 success/done/created：
+
+> ✅ 项目创建完成，依赖已安装
+>
+> 路径：`<projectDir 绝对路径>`
+> 模式：胶水模式 (glue)
+> 索引登记：`~/.ep-stage/projects.index.json5`（含 stageCreateVersion）
+> 依赖：已 `pnpm install` 完成
+> 下一步：对某需求跑 `/glue-generate-testcase <需求目录路径>` 生成用例
+
+**失败时不要发完成提示**：第 4 节任一验证项失败或依赖安装失败 → 按 §3 报告，不允许在失败信息里混合"项目创建完成"字样。
+
+## 6. 引导场景
+
+- **A（缺脚手架）**：N/A — 本 skill 本身即建脚手架的入口，不存在"缺脚手架"前置。
+- **其他**：cwd 是 git 仓库根 → Step 2 二次确认；中文目录名 → Step 2 建议改 kebab-case。

package/codex-skill/ep-stage/glue-generate-testcase/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: glue-generate-testcase
+description: 使用时机：当用户对某需求要「生成用例 / 准备测试场景 / 钻探上游需求生成胶水冒烟用例」或显式触发 `/glue-generate-testcase <需求目录>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，并负责自然语言映射、缺数据引导、Step 5 凭据交互确认。
+version: 2026-06-25+5179a92
+argument-hint: "<需求目录绝对/相对路径>"
+---
+
+# ep-stage: glue-generate-testcase
+
+本 skill 引导 Agent **包装** `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，不重新实现钻探与用例生成。CLI 内部完成物料解析 + contract 提取（内嵌）+ coverage 分析 + testcase v2 装配 + credentials.template 生成 + code_list.md 软链。skill 负责：路径解析、反查项目脚手架、缺数据引导、Step 5 平台对话确认凭据、审阅引导。用户视角全中文，不暴露 CLI 名称。
+
+> 钻探前置：v2 顶层（schemaVersion + scenario + menuPath + requiredSystems + requiredRoles + coveredActions + uncoveredCandidates）由 CLI 一次写入。scenario 3 档决策（REQ-SCENE-01）：①CLI `--scenario` ②ModuleHints 推断 ③默认 `crud`；scenario 作为**产物**（非输入）写入顶层。
+
+## 1. 自然语言映射
+
+```text
+/glue-generate-testcase /abs/path/.../014-测试需求10-20260622   # 绝对路径
+/glue-generate-testcase ../knowledge-project/.../014-测试需求10-20260622  # 相对路径
+/glue-generate-testcase                                          # 无参数 → 问需求目录
+```
+
+skill 把入参 `path.resolve` 绝对化，用 `path.basename` 取「需求名」作为 `<projectDir>/src/tests/<需求名>` 子目录。**projectDir 不接受参数**，全部从 `~/.ep-stage/projects.index.json5` 反查最新 `mode: 'glue'` 条目（多条 AskUserQuestion 让用户挑）；索引缺失走引导场景 A。
+
+## 2. Agent 执行剧本（8 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：load 后**立即**打印初始任务清单（Step 0）；每完成一步输出单行 `✅ 第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 8 输出全勾选终态清单 + 摘要。
+
+### Step 0 — 打印任务清单
+
+```markdown
+📋 **生成胶水测试用例任务清单**
+
+- [ ] 第 1 步 — 解析需求路径
+- [ ] 第 2 步 — 反查项目脚手架
+- [ ] 第 3 步 — 校验 code_list.md 输入
+- [ ] 第 4 步 — 调用钻探与用例生成 CLI
+- [ ] 第 5 步 — 与研发人员交互确认推断结果
+- [ ] 第 6 步 — 校验产物完整性
+- [ ] 第 7 步 — 写入需求条目到项目索引
+- [ ] 第 8 步 — 输出审阅引导摘要
+```
+
+### Step 1 — 解析需求路径
+
+从用户消息 / args 抽取需求目录路径，绝对化 + basename。中文复述识别结果："已识别：需求目录 = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我需求目录的绝对或相对路径"。
+
+### Step 2 — 反查项目脚手架（缺 → 引导 A）
+
+读 `~/.ep-stage/projects.index.json5`：文件不存在 / 无 glue 条目 → **引导场景 A**：中文提示"未发现胶水测试脚手架。请先跑 `/glue-create-project <项目名>` 创建脚手架后再回来"，退出不调 CLI。多条匹配 → AskUserQuestion 挑 projectDir。单条 → 直接拼 `--tests-dir` 根。
+
+### Step 3 — 校验 code_list.md 输入（缺 → 引导 D）
+
+校验 `<需求目录>/code_list.md` 是否存在。缺失 → **引导场景 D**，AskUserQuestion 三选一：
+
+1. **提供 code_list.md 路径**：让用户给绝对路径，skill 用跨平台 softlink fallback（symlink → hardlink → copy + 时间戳警示）建到需求目录。
+2. **读 PRD 草稿生成 code_list.md**：在需求目录找 PRD / spec.yaml，AI 推断 `knowledgeRoot` / `menu` / 文件清单写一份 code_list.md 草稿，提示"已生成草稿，请人审后再跑"，退出。
+3. **取消**：直接退出，不调 CLI。
+
+### Step 4 — 调用钻探与用例生成 CLI
+
+固定命令形式（不 which、不扫 monorepo、不 cd、**不喂 stdin**）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest testcase \
+  --code-list <需求目录>/code_list.md \
+  --tests-dir <projectDir>/src/tests/<需求名> \
+  --requirement-dir <需求目录> \
+  --project-dir <projectDir> \
+  [--scenario <值>] \
+  [--hints <module-hints.json 路径>]
+```
+
+CLI 内部：先按 scenario 3 档决策（①`--scenario` ②ModuleHints ③默认 `crud`），按 scenario 选 extractor → 物料解析 + contract 提取 + coverage 分析 → 装配 testcase v2（最终 scenario 写入 `testcase.json5` 顶层）→ 写 testcase.json5 / testcase.md（i18n 中文）/ credentials.template.json5 / `.ep-stage/contract.json` → 软链上游 code_list.md。CLI 非 0 退出 → 复述 stderr，不发完成提示，不进 Step 5。
+
+### Step 5 — 与研发人员交互确认推断结果（REQ-UX-02）
+
+Step 4 成功后，skill 读 testcase.json5 顶层 `requiredSystems[]` / `requiredRoles[]`，再读 `~/.ep-stage/projects.index.json5` 的 `systems[]` 算 `cachedSystemsHit`（url 命中的列表）。用**平台对话能力**（Claude Code 用 `AskUserQuestion` / Codex 用对应交互机制）跟用户对话：
+
+> 推断出 **N 个系统** + **M 个角色**（如 建设单位 / 施工单位 / 监理单位）。请选择：
+> 1. **现在交互输入**（推荐：≤3 角色场景）— 我逐个角色问 URL / 用户名 / 密码 / systemName，**直接写 `credentials.json5`**
+> 2. **仅生成 template，自己后续填** — 退出后请拷贝 `credentials.template.json5` → `credentials.json5` 并填值
+> 3. **跳过，使用全局 systems[] 缓存复用** — 自动从 `cachedSystemsHit` 命中缓存生成 `credentials.json5`（缺失角色 fallback 引导 C，留给 glue-run-test）
+
+三分支处理：
+
+- **选 1**：skill 顺序问每条角色的 URL/username/password/systemName（free text），直接写 `<需求名>/credentials.json5`（gitignore，非 template），**回写**全局 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`（按 url 归并，跨需求复用）。
+- **选 2**：保留 template；提示"请编辑 `credentials.json5` 后再跑 `/glue-run-test`"，进入 Step 6。
+- **选 3**：从 `systems[].credentialsCache` 拼出 credentials.json5，缺失角色用 template 占位符保留。
+
+### Step 6 — 校验产物完整性
+
+按 §3 验证清单 `ls` / `Read` 校验全部产物存在。缺任意一项视为整体失败，按 §4 报告。
+
+### Step 7 — 写入需求条目到项目索引
+
+CLI testcase 子命令已在 `~/.ep-stage/projects.index.json5` 对应 `projects[].requirements[]` 追加本需求条目（含 `name / requirementDir / testsDir / lastRunStatus: "never"`）。skill 校验：条目存在；`name` 与 Step 1 一致；`testsDir` 指向 `<projectDir>/src/tests/<需求名>`。缺时由 skill 补写。
+
+### Step 8 — 输出审阅引导摘要
+
+打印全勾选终态清单 + §5 完成提示（含审阅引导链：审 testcase.md → 编辑 testcase.json5 → 填 credentials.json5 → 跑 `/glue-run-test`）。
+
+## 3. 验证清单
+
+| 路径                                                  | 说明                          |
+|-------------------------------------------------------|-------------------------------|
+| `<projectDir>/src/tests/<需求名>/testcase.json5`      | v2 schema（含 scenario / menuPath / requiredSystems 等）|
+| `<projectDir>/src/tests/<需求名>/testcase.md`         | 中文人审视图（i18n 映射）     |
+| `<projectDir>/src/tests/<需求名>/credentials.template.json5` | 行数 = `requiredRoles.length` |
+| `<projectDir>/src/tests/<需求名>/code_list.md`        | 软链 / hardlink / copy 到上游 |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json` | 内部产物，机器专用，禁手编 |
+| `~/.ep-stage/projects.index.json5`                    | 已追加 `projects[].requirements[]` |
+
+## 4. 错误处理
+
+| 触发时机                  | Agent 中文呈现 + 建议 |
+|---------------------------|---------------------|
+| 引导 A（缺脚手架）        | 中文提示+退出，引导先跑 `/glue-create-project` |
+| 引导 D（缺 code_list.md） | AskUserQuestion 三选一：建软链 / 读 PRD 草稿 / 取消 |
+| CLI exit ≠ 0              | 复述 stderr 中文转述，不发完成提示，不进 Step 5 |
+| testcase.json5 缺 `schemaVersion: "v2"` | 报"产物 schema 校验失败，请重跑 `/glue-generate-testcase <需求路径>`" |
+| Step 5 选 1 用户中途取消  | 保留 template，提示"凭据未写入，请稍后拷贝 template 自填" |
+
+## 5. 完成提示
+
+Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/generated）：
+
+> ✅ 用例生成完成
+>
+> 需求：`<需求名>`
+> 项目：`<projectDir>`
+> 产物目录：`<projectDir>/src/tests/<需求名>/`（testcase.json5 v2 + testcase.md + credentials.template.json5 + credentials.json5（如选 1/3）+ code_list.md 软链）
+> 项目索引：`~/.ep-stage/projects.index.json5` 已追加需求条目
+>
+> 下一步审阅引导链：
+> 1. 打开 `testcase.md` 审阅推断结果与未确认项
+> 2. 如需调整，编辑 `testcase.json5`（JSON5 支持 `// 注释`，审阅意见可直接写注释）
+> 3. 检查 / 填好 `credentials.json5`（如未在 Step 5 选 1/3 写入）
+> 4. 跑 `/glue-run-test <需求目录路径>` 组装并执行 spec
+
+## 6. 引导场景
+
+- **A（缺脚手架）**：Step 2 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
+- **D（缺 code_list.md）**：Step 3 缺失 → AskUserQuestion 三选一（建软链 / 读 PRD 草稿 / 取消）。
+- **B / C**：由下游 `glue-run-test` 处理。
+
+## 7. 输入字段约定
+
+```markdown
+<!-- code_list.md 字段约定（REQ-FILE-02 / REQ-MENU-01） -->
+knowledgeRoot: /abs/path/to/knowledge-project/xxx
+menu: 一级菜单>二级菜单   <!-- 可选；缺时引导补，最终写入 testcase.json5.menuPath -->
+
+`_docs/.../spec.yaml`
+`src/main/webapp/.../*.html`
+`src/main/java/.../*Action.java`
+`_docs/.../*.module-hints.json`
+```
+
+## 8. 内嵌数据契约范例
+
+`<需求名>/testcase.json5` v2 顶层骨架（详见 references/testcase-schema.md）：
+
+```json5
+{
+  schemaVersion: "v2",
+  scenario: "crud",                            // 产物：CLI 3 档决策后写入
+  moduleId: "zwplace", moduleName: "场所窗口信息管理",
+  menuPath: "场所窗口信息管理>场所窗口信息列表",
+  requiredSystems: [{ url: "http://...", systemName: "主业务系统" }],
+  requiredRoles:   [{ role: "admin", hint: "默认操作员" }],
+  coveredActions:  [{ actionId: "zwplace.create", kind: "create", evidence: ["html=...", "java=..."] }],
+  uncoveredCandidates: [{ actionId: "zwplace.sync", status: "planned", requiredRole: "admin", businessIntent: "...", assertionExpectation: "...", evidence: ["..."] }],
+  cases: [{ caseId: "zwplace.create", title: "新增", scenario: "crud.single-page", reviewStatus: "confirmed", requiredRole: "admin", evidence: ["..."], steps: [], assertions: [], unresolved: [] }],
+  reasoningSummary: { conclusion: "...", evidenceChain: [], alternatives: [], confidence: "high", risks: [], needsHumanReview: false }
+}
+```
+
+`<需求名>/credentials.template.json5`（行数 = `requiredRoles.length`） + `~/.ep-stage/projects.index.json5` 需求条目（CLI 追加到 `projects[].requirements[]`）：
+
+```json5
+// credentials.template.json5
+[ { url: "<请填登录页 URL>", username: "<请填>", password: "<请填>", role: "admin", systemName: "主业务系统" } ]
+
+// projects.index.json5 → projects[].requirements[<i>]
+{ name: "014-测试需求10-20260622", requirementDir: "/abs/.../014-测试需求10-20260622", testsDir: "<projectDir>/src/tests/014-测试需求10-20260622", lastRunStatus: "never" }
+```
+
+## 9. 按需加载
+
+- 用例 schema 详解：`references/testcase-schema.md`（v2）
+- 既有工作流参考：`references/workflow.md`
+
+## 10. 关键约束
+
+- 顶层 `reviewStatus` 字段**永远不引入**（REQ-DATA-04）；审阅意见请直接在 `testcase.json5` 加 JSON5 `// 注释`。
+- `cases[].reviewStatus = needs_review` 的用例不得进入 spec 组装（run 阶段按 case 粒度阻断）。
+- 嵌套 CRUD 一期仅作为候选用例进入 testcase，不写入正式 CRUD 契约。
+- testcase.md 每次重跑完全覆盖，不保留人工编辑（事实源是 testcase.json5）。
+- 对话中展示可审阅推理摘要和证据链，不展示原始隐式思维链。

package/codex-skill/ep-stage/glue-generate-testcase/references/testcase-schema.md

@@ -0,0 +1,112 @@
+# glue-testcase schema (v2)
+
+`testcase.json5` 顶层 schema：
+
+```json5
+{
+  schemaVersion: "v2",
+  scenario: "crud",                  // ★ v2 新增（REQ-SCENE-01）：场景类型。**由 testcase 子命令运行时决定后写入此字段**（产物，非输入）。决策优先级：①--scenario CLI 参数 ②ModuleHints 推断 ③默认 "crud"
+  moduleId: "zwplace",
+  moduleName: "场所窗口信息管理",
+  menuPath: "场所窗口信息管理>场所窗口信息列表",  // ★ v2 新增（REQ-MENU-01）：从 code_list.md 搬到 testcase 扎口
+
+  // ★ v2 新增：上游推断的需求系统/角色集
+  requiredSystems: [
+    { url: "http://192.168.x.x:8100/.../login", systemName: "主业务系统" }
+  ],
+  requiredRoles: [
+    { role: "admin", hint: "默认操作员" }
+  ],
+
+  // ★ v2 新增：骨架命中清单（run 阶段直接组装）
+  // evidence 格式约定：<kind>=<ref>，kind ∈ {html, java, spec, contract, skeleton, hint}
+  coveredActions: [
+    {
+      actionId: "zwplace.create",
+      kind: "create",
+      evidence: [
+        "html=src/main/webapp/.../gxhzwplaceadd.html",
+        "java=src/main/java/.../ZwplaceAction.java"
+      ]
+    },
+    { actionId: "zwplace.read",   kind: "read",   evidence: ["html=src/main/webapp/.../gxhzwplacelist.html", "java=..."] },
+    { actionId: "zwplace.update", kind: "update", evidence: ["html=...", "java=..."] },
+    { actionId: "zwplace.delete", kind: "delete", evidence: ["html=...", "java=..."] }
+  ],
+
+  // ★ v2 新增：骨架未命中候选（run 阶段 AI 推理）
+  uncoveredCandidates: [
+    {
+      actionId: "zwplace.sync",
+      label: "同步窗口管理系统",
+      status: "planned",            // planned | candidate | unresolved | resolved
+      requiredRole: "admin",        // ★ v2 新增：AI 推理时知道用哪个角色操作
+      businessIntent: "同步窗口数据",
+      assertionExpectation: "同步完成提示",
+      evidence: ["html=...", "hint=ModuleHints.customWorkflows.zwplace.sync"]
+    }
+  ],
+
+  // 既有 v1 字段（cases 内部行为不变）
+  cases: [
+    {
+      caseId: "zwplace.create",
+      title: "新增场所窗口信息管理",
+      scenario: "crud.single-page",
+      reviewStatus: "confirmed",    // v1 字段保留：confirmed | needs_review | blocked
+      requiredRole: "admin",        // ★ v2 新增：该用例由哪个角色操作
+      evidence: ["skeleton=crud.skeleton-testcase/v1", "contract=crud-business-module/v1"],
+      steps: ["进入菜单", "点击新增", "填写并保存测试数据"],
+      assertions: ["新增后可查询到记录"],
+      unresolved: []
+    }
+  ],
+
+  reasoningSummary: {
+    conclusion: "生成 4 条 CRUD 胶水测试用例。",
+    evidenceChain: [],
+    alternatives: ["crud.single-page"],
+    confidence: "high",
+    risks: [],
+    needsHumanReview: false
+  }
+}
+```
+
+## v1 → v2 升级点
+
+- 顶层新增 `schemaVersion: "v2"`
+- 顶层新增 `scenario`（REQ-SCENE-01）
+- 顶层新增 `menuPath`（REQ-MENU-01 修订）
+- 顶层新增 `requiredSystems[]` / `requiredRoles[]`
+- 顶层新增 `coveredActions[]` / `uncoveredCandidates[]`（钻探产物前移）
+- `cases[]` 新增 `requiredRole`
+- `uncoveredCandidates[]` 新增 `requiredRole`
+- `evidence` 字段格式约定 `<kind>=<ref>`
+- **顶层不引入** `reviewStatus`（REQ-DATA-04）；仅 `cases[].reviewStatus` 保留
+
+## 字段说明（v2 新增字段）
+
+- `schemaVersion`：必为字符串 `"v2"`。Task 1.1 `validateTestcase` 强制校验；其他值或缺失会拒绝并提示重跑 `glue-generate-testcase`。
+- `scenario`：场景类型（**产物**，非输入）。由 testcase 子命令运行时按 3 档优先级决定：① CLI `--scenario` 显式参数 → ② 从 `ModuleHints` 推断 → ③ 默认 `"crud"`。本轮仅支持 `"crud"`；未来 `"statistic"` / `"approval"` 等场景扩展时不增加新 CLI 命令，仅扩展 testcase 内部分发（REQ-SCENE-01）。
+- `menuPath`：菜单路径，从 `code_list.md` 搬到 testcase 扎口（REQ-MENU-01 修订）。glue-run-test 的 spec 子命令从此读取，不再从 code_list 二次解析。
+- `requiredSystems[]`：上游钻探推断的需求涉及的系统集，每项 `{ url, systemName? }`。驱动 `credentials.template.json5` 生成 + 引导用户在 glue-generate-testcase 第 5 步交互确认（REQ-UX-02）。
+- `requiredRoles[]`：上游钻探推断的需求涉及的角色集，每项 `{ role, hint? }`。同上驱动 template + 确认。
+- `coveredActions[]`：骨架命中清单。run 阶段直接组装胶水部分 spec，按 `evidence` 引用源码与契约。
+- `uncoveredCandidates[]`：骨架未命中候选；`status` 取 `planned`（可进 AI 推理）/ `candidate`（不得进 spec，要求补 hints）/ `unresolved`（缺证据）/ `resolved`（已通过推理）。
+- `uncoveredCandidates[].requiredRole`：AI 推理时该动作由哪个角色操作（多角色场景必需）。
+- `cases[].requiredRole`：该用例由哪个角色操作。spec 子命令据此映射 credentials.json5 + cases 登录切换。
+- `evidence`：字符串数组，每项格式 `<kind>=<ref>`。`kind` ∈ `{html, java, spec, contract, skeleton, hint}`。
+
+## 既有 v1 字段说明（保留语义）
+
+- `cases[].reviewStatus`：`confirmed` / `needs_review` / `blocked`。`needs_review` 的用例不得进入 spec assembly（run 阶段按 case 粒度阻断）。
+- `caseId`：spec assembly 需要与生成脚本工作流粒度一致。CRUD 用例固定为 `<moduleId>.create` / `.read` / `.update` / `.delete`。
+- `unresolved`：未确认项（如嵌套 CRUD 子表保存后断言）。必须落盘，不能只在对话解释。
+- `reasoningSummary`：与 `.stage/trace/<run-id>/testcase-generation.json` 同构。
+
+## Schema 演化策略
+
+- 破坏性升级走 major 版本号（如 v2 → v3）
+- CLI 读取时校验 `schemaVersion`：不匹配抛结构化错误（含期望版本 + 修复建议「重跑 `glue-generate-testcase <需求路径>`」）
+- 顶层 `reviewStatus` 字段**永远不引入**（REQ-DATA-04）；审阅意见请直接在 `testcase.json5` 加 JSON5 `// 注释`