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

package/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: ep-stage-skill-package
+description: 使用时机：当需要维护 @epoint/ep-stage-skill 包源码、CLI 提取器、CRUD 契约生成器，或面向 Codex 的 ep-stage skill 资产时使用。
+---
+
+# @epoint/ep-stage-skill 包
+
+本包负责面向 Codex 的 `ep-stage` skill 背后的确定性工具链：
+
+- 将上游 CRUD 物料提取为 `crud-business-module/v1`
+- 在 `ModuleHints` 中隔离测试人员策略
+- 使用 `CrudFlowSlots` 将契约渲染为 glue 模式的 Playwright spec
+
+Codex skill 范围位于：
+
+```text
+packages/ep-stage-skill/codex-skill/ep-stage/
+```
+
+为便于 Agent 发现，本仓库通过双目录暴露 skill（Claude Code 扫描 `.claude/skills/`，Codex 扫描 `.agents/skills/`），二者均以 symlink 指向包源码：
+
+```text
+.claude/skills/<skill>  ->  packages/ep-stage-skill/codex-skill/ep-stage/<skill>
+.agents/skills/<skill>  ->  packages/ep-stage-skill/codex-skill/ep-stage/<skill>
+```
+
+对于面向用户的行为，编辑 `codex-skill/ep-stage/*/SKILL.md`。

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

@@ -0,0 +1,59 @@
+---
+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

@@ -0,0 +1,258 @@
+---
+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 负责审阅。

package/codex-skill/ep-stage/glue-test/references/crud-pipeline.md

@@ -0,0 +1,139 @@
+# CRUD Pipeline 参考（CRUD Pipeline Reference）
+
+## 输入参数（Inputs）
+
+使用显式输入。当用户已经明确给出路径时，不要大范围搜索。
+
+| 输入 | 用途 | 说明 |
+| --- | --- | --- |
+| `--module-id` | 契约标识 | 稳定的技术标识，例如 `zwplace`。 |
+| `--docs` | 需求/规格目录 | 当存在 `spec.yaml` 时优先使用；当前 CLI 可回退到 `code_list.md` 的模块标签。 |
+| `--code-list` | 模块清单 | 通常为 `<knowledge-project>/_docs/code_list.md`。 |
+| `--webapp` | 生成的 HTML 页面 | 包含 list/add/edit/detail HTML 文件的目录。 |
+| `--java-actions` | Java Action 源码 | 包含 `*Action.java` 文件的目录，用于后端消息/规则。 |
+| `--hints` | 策略决策 | 数据主键、搜索条件、按钮别名、自动填充覆盖、删除策略、断言。 |
+| `--out` | 契约 JSON | 除非用户另有指定，否则输出保持在 `packages/ep-stage-skill/output/` 下。 |
+
+## ModuleHints 指引（ModuleHints Guidance）
+
+`ModuleHints` 是"已提取事实"与"测试人员策略"之间的边界。
+
+以下内容应放入 hints，而不是由 Agent 自行推断：
+
+- `dataKey.selectedField` 和 `dataKey.generationStrategy`
+- `searchConditions[]`，尤其是 listbox 的 `value`
+- `buttonAliases`
+- `autofill.overrideFields`
+- `deletePolicy`
+- 断言策略覆盖
+
+对于多条件 CRUD 冒烟测试，推荐：
+
+```json
+{
+  "dataKey": {
+    "selectedField": "placename",
+    "generationStrategy": "timestamp_prefix"
+  },
+  "searchConditions": [
+    {
+      "field": "placename",
+      "component": "input",
+      "seedValue": "自动化测试名称",
+      "strategy": "timestamp_prefix",
+      "updatePrefix": "修改"
+    },
+    {
+      "field": "placecategory",
+      "component": "listbox",
+      "value": "条线大厅",
+      "createSelections": [
+        { "field": "placecategory", "value": "条线大厅" }
+      ]
+    }
+  ]
+}
+```
+
+`searchConditions` 驱动生成的 `CrudFlowSlots`。`dataKey` 仍作为兼容性和策略锚点保留，但不应与独立的 `searchField` 概念重复。
+
+## 生成契约（Generate Contract）
+
+从仓库根目录执行：
+
+```bash
+pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
+  --module-id <module-id> \
+  --docs <absolute-upstream-docs-dir> \
+  --code-list <absolute-code-list-md> \
+  --webapp <absolute-webapp-html-dir> \
+  --java-actions <absolute-java-action-dir> \
+  --hints examples/<module>.module-hints.json \
+  --out output/<module>.crud.contract.json
+```
+
+由于 `pnpm --filter` 会在包目录内执行，上游路径通常应使用绝对路径。
+
+## 检查契约闸门（Inspect Contract Gate）
+
+```bash
+node --input-type=module -e "
+import fs from 'node:fs';
+const c = JSON.parse(fs.readFileSync('packages/ep-stage-skill/output/<module>.crud.contract.json', 'utf8'));
+console.log(JSON.stringify({
+  contractVersion: c.contractVersion,
+  module: c.module,
+  searchConditions: c.searchConditions?.map(({ field, label, component, value }) => ({ field, label, component, value })),
+  unresolvedSlots: c.unresolvedSlots?.map(({ slotId, reason }) => ({ slotId, reason }))
+}, null, 2));
+if (c.unresolvedSlots?.length) process.exit(2);
+"
+```
+
+若退出码为 `2`，请更新 `ModuleHints` 并重新生成。不要从存在未解析槽位（unresolved slots）的契约生成最终 spec。
+
+## 生成 Spec（Generate Spec）
+
+```bash
+pnpm --filter @epoint/ep-stage-skill generate:playwright-tests -- \
+  --contract output/<module>.crud.contract.json \
+  --out <absolute-glue-project>/src/tests/<name>.spec.ts \
+  --menu "<menu-path>"
+```
+
+生成的 spec 应当：
+
+- 从 `../skeletons` 导入 `CrudPage`、`LoginPage`、`MenuPage` 以及 `type CrudFlowSlots`
+- 定义 `const crudSlots: CrudFlowSlots`
+- 调用 `await crudPage.runCrudFlow()`
+- 避免内联 Playwright 操作流程
+
+## 在消费方 glue 项目中验证（Verify In Consuming Glue Project）
+
+```bash
+cd <glue-project>
+pnpm --ignore-workspace exec tsc --noEmit
+```
+
+运行时验证需要 `.env` 配置：
+
+```text
+LOGIN_SYSTEM_URL=...
+LOGIN_USERNAME=...
+LOGIN_PASSWORD=...
+HEADLESS=false
+```
+
+仅当业务系统可达时才执行：
+
+```bash
+pnpm --ignore-workspace exec playwright test src/tests/<name>.spec.ts --project=chromium --headed --workers=1
+```
+
+若运行时失败，将失败原因归类为：
+
+- 系统可达性或登录配置
+- 上游物料不匹配
+- `ModuleHints` 缺失或错误
+- 骨架/组件行为
+- 包生成器缺陷

package/codex-skill/ep-stage/glue-test/references/gap-review-protocol.md

@@ -0,0 +1,43 @@
+# Gap 评审协议（Gap Review Protocol）
+
+本参考定义了 `review-gaps` 在第一阶段的 Agent 行为。
+
+`review-gaps` 在本期不是一个新的 CLI，而是介于"骨架覆盖"与"运行时推理"之间的一层用户确认窗口。
+
+## 输入（Inputs）
+
+- 由 `generate:crud-contract` 生成的契约 JSON。
+- 契约中的 `agentInferredWorkflows`。
+- 当存在时，`ModuleHints.customWorkflows`。
+- 当 `run:gap-pipeline` 已经生成过时，运行时 pipeline 的摘要。
+
+## 状态处理（Status Handling）
+
+| 状态 | 行为 |
+| --- | --- |
+| `planned` | 可进入运行时推理。运行前展示其意图、断言和证据。 |
+| `candidate` | 不得追加到 spec。询问是否在 `ModuleHints.customWorkflows` 中补充意图和断言。 |
+| `unresolved` | 不得追加到 spec。报告缺失的证据及所需的提供方。 |
+| `resolved` | 可作为运行时已支持的证据进行报告。 |
+| `needs_review` | 保留供人工评审，并报告确切原因。 |
+
+## 面向用户的摘要格式（User-Facing Summary Shape）
+
+在响应中使用如下格式：
+
+```text
+Gap: 同步窗口管理系统
+status: planned
+workflowId: zwplace.custom_da3d238e
+evidence: HTML button, Java Action method, ModuleHints.customWorkflows
+businessIntent: 同步窗口管理系统数据
+assertionExpectation: 同步完成
+recommendedAction: infer | supplement-hints | skip
+```
+
+## 约束（Constraints）
+
+- 不得虚构业务意图。
+- 不得虚构断言文案。
+- 在没有用户提供的 hints 之前，不得将 `candidate` 提升为 `planned`。
+- 不得通过修改骨架来让一个 gap 通过。

package/codex-skill/ep-stage/glue-test/references/harness-principles.md

@@ -0,0 +1,46 @@
+# Stage Glue 的治理原则（Harness Principles）
+
+本 skill 将治理工程（harness-engineering）应用为一条小巧、显式的流水线，而非一个庞大且无所不包的提示词。
+
+## 设计承诺（Design Commitments）
+
+1. **仓库即记录系统（Repository as record system）**
+   - 契约、hints、生成的 spec 以及验证命令都是本地文件。
+   - 不要仅依赖截图或对话记忆作为唯一事实来源。
+
+2. **渐进式披露（Progressive disclosure）**
+   - `SKILL.md` 承载路由和护栏。
+   - `references/crud-pipeline.md` 承载命令和闸门。
+   - 仅当确定性命令执行有用时才加载脚本。
+
+3. **规划器/生成器/评估器分离（Planner/generator/evaluator separation）**
+   - 规划器（Planner）：识别上游物料和缺失的策略槽位。
+   - 生成器（Generator）：运行提取器和骨架渲染器。
+   - 评估器（Evaluator）：检查 `unresolvedSlots`，汇总输出，并可选地运行 Playwright。
+
+4. **最小可行治理（Minimum viable harness）**
+   - 日常工作中直接使用包 CLI。
+   - 仅当重复处理路径或未解析槽位闸门容易出错时，才使用 `scripts/generate-crud-spec.mjs`。
+   - 除非模块或验证目标过大、单次确定性执行无法覆盖，否则不要引入多 Agent 循环。
+
+5. **反过拟合（Anti-overfitting）**
+   - `zwplace` 是回归 fixture 和示例。
+   - 可复用的抽象是：上游物料 -> `crud-business-module/v1` -> `CrudFlowSlots` -> glue 骨架。
+   - 模块特有的取值应放入 hints 和生成产物中，而不是 skill 指令里。
+
+## 质量闸门（Quality Gates）
+
+| 闸门 | 证据 |
+| --- | --- |
+| Skill 可发现性 | `name` 与目录名一致，且 `description` 以 `Use when` 开头。 |
+| 契约健康度 | `contractVersion`、模块标识、`searchConditions`，且 `unresolvedSlots` 为空。 |
+| 骨架兼容性 | 生成的 spec 导入骨架类型，并能在 glue 项目中编译通过。 |
+| 运行时冒烟 | Playwright 测试在可达的业务系统上通过。 |
+| 交接清晰度 | 最终响应列出已生成文件、已执行命令以及未解决的风险。 |
+
+## 失败处理（Failure Handling）
+
+- 若上游路径错误，先停下来修正路径，再编辑 hints。
+- 若 `unresolvedSlots` 非空，应更新 hints，而不是削弱生成器检查。
+- 若 listbox 取值不唯一，在 hints 中选择一个合法的冒烟测试取值；完整数据覆盖不在 CRUD 冒烟范围之内。
+- 若 Playwright 无法连通系统，应将环境/网络状态与生成正确性分开报告。