create-yss-spec 2.1.3 → 2.1.5

package/template/.codex/skills/yss-api-integration/SKILL.md

@@ -18,10 +18,28 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 1. **契约状态已明确**：
    - 已有生成客户端：可以直接集成。
-   - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze，再进入生成和集成。
-   - 如果接口尚未冻结或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi`，不要手写临时路径、DTO 或响应结构。
-2. **API 已生成**：运行 `pnpm generate:api` 生成最新 API
-3. **了解 OpenAPI**：查看 `openapi/openapi.json` 了解接口定义
+   - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze。冻结的 OpenAPI YAML 是唯一权威，JSON 仅为它的受控派生物。
+   - 如果接口尚未冻结、JSON 派生记录缺失或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi-governance`，不要手写临时路径、DTO 或响应结构。
+2. **API 已生成**：在目标前端实现仓库中，按其既有的手动代码生成命令（例如 `pnpm generate:api`）刷新 API；本 Harness 不配置、不执行该命令，也不把它加入 CI。
+3. **了解 OpenAPI**：查看 Freeze 记录、JSON 派生记录和 `openapi/openapi.json` 了解接口定义；不得把 JSON 或生成 TypeScript 当成可手改的源文件。
+
+## 契约输入与生成链
+
+客户端重新生成只能走下列受控链路：
+
+```text
+冻结的 OpenAPI YAML
+  → 锁定的 redocly bundle 生成 openapi.json
+  → 原样物化到目标前端
+  → 既有前端代码生成流程（由目标项目手动执行）
+  → 类型检查与调用方验证
+```
+
+1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
+2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
+3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
+4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 不读取或修改目标前端的生成器配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
+5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 📁 API 文件结构
 
@@ -329,7 +347,7 @@ const handleSubmit = async (payload: SubmitCmd) => {
 request.post("/api/v1/todo/guess", payload as any);
 ```
 
-✅ **正确做法**：确认 OpenAPI Draft/Freeze 状态；冻结后用 `yss-openapi` 刷新生成客户端，再从 `@/api/generated/api` 和 `@/api/generated/model` 导入。
+✅ **正确做法**：确认 OpenAPI Draft/Freeze 状态；Freeze 后先由 `yss-openapi-governance` 从 YAML 生成并记录 JSON，再运行 `pnpm generate:api`，最后从 `@/api/generated/api` 和 `@/api/generated/model` 导入。
 
 ### ❌ 错误 3：缺少错误处理
 
@@ -386,7 +404,7 @@ const fetchData = async () => {
    pnpm generate:api
    ```
 
-   生成前应确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft 已完成设计审查并 Freeze；生成动作本身优先交给 `yss-openapi`。
+   生成前应确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft 已完成设计审查并 Freeze，且 `yss-openapi-governance` 已用锁定的 `redocly bundle` 留下对应 JSON 派生记录；随后才运行 `pnpm generate:api`。
 
 2. **封装业务逻辑到 Hook**：
    - 将 API 调用封装在 `hooks/use{Name}Api.ts`
@@ -404,6 +422,6 @@ const fetchData = async () => {
 
 ## 阶段 7 合同
 
-- 只消费已冻结的 OpenAPI 生成客户端和批准后的 `Slice Implementation Contract`；实现中的半成品 backend 不得作为稳定 source of truth。
+- 只消费冻结的 OpenAPI YAML 派生出的 JSON、生成客户端和批准后的 `Slice Implementation Contract`；实现中的半成品 backend 不得作为稳定 source of truth。
 - 客户端重新生成属于 `controlled-generation`；页面请求状态、错误处理、权限和用户交互属于 `behavior-tdd`。
 - 必须按统一 `YSS Skill Execution Result` 返回生成客户端引用、调用文件、组件/API 测试、实际 pnpm 验证结果、偏离和 `new_impacts`；发现缺失路径或 schema 变化时暂停并回生命周期。

package/template/.codex/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -26,7 +26,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 1. 确认项目名、基础包名、输出目录、数据库类型。
    Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
 2. 运行 `scripts/generate_scaffold.py` 生成骨架。
-3. 检查生成的模块名、POM、配置文件、Smart Doc 配置和包路径。
+3. 检查生成的模块名、POM、基础配置文件和包路径。
 4. 由生命周期受控工作单元在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；生成器打印的下一步命令不构成验证证据。
 5. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
 
@@ -57,7 +57,6 @@ python3 scripts/generate_scaffold.py \
 - `*-adapter`
 - `*-bootstrap`
 - 基础配置、机械模板、构建脚本
-- `bootstrap/src/main/resources/smart-doc.json` 基础配置
 
 ## 使用约束
 
@@ -70,8 +69,8 @@ python3 scripts/generate_scaffold.py \
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
-- 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行、OpenAPI 生成和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
-- 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper、Smart Doc 和机械模板，不是业务实现。
+- 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
+- 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation` 和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入非业务元数据清单 `.yss/scaffold-generation.json`，回勾合同 ID、版本、批准引用、生成输入、受控模式和固定验证命令；清单缺失时不得交给后续 Router。
@@ -81,19 +80,6 @@ python3 scripts/generate_scaffold.py \
 - `.mvn/settings.xml` 只能通过 `${env.MAVEN_REPO_USERNAME}` 和 `${env.MAVEN_REPO_PASSWORD}` 读取 Maven 仓库凭据；内部仓库构建前由 CI 或本地安全环境注入变量，禁止把 Maven 仓库用户名、明文密码或 Maven 加密密码写入 skill、模板或生成工程。
 - 涉及 API 契约时，先确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
 
-## Smart Doc 配置参考
-
-脚手架只生成不包含环境地址、Torna token 和业务项目名称的基础 `smart-doc.json`。参考真实项目配置时，仅提炼通用生成行为：
-
-- `allInOne: true`：生成单一 OpenAPI 文档。
-- `outPath: "target/openapi"`：生成文件输出到构建产物目录。
-- `packageFilters: "<base_package>.*"`：按 Smart Doc 的正则语义扫描当前服务的 Controller 包。
-- `componentType: "NORMAL"`：使用稳定的类名作为 schema 组件名。
-- `inlineEnum: true`、`recursionLimit: 7`：保持枚举展开和递归深度策略。
-- `requestExample`、`responseExample`、`createDebugPage` 默认关闭，避免把环境或示例数据带入契约产物。
-
-`serverUrl`、`debugEnvUrl`、`openUrl`、`appToken`、`revisionLogs` 属于具体环境或项目治理配置，必须在实现仓库中按实际契约补充，不能写入通用脚手架模板。
-
 ## 按需读取
 
 - 主脚本：`scripts/generate_scaffold.py`

package/template/.codex/skills/yss-ddd-scaffold-generator/assets/templates/pom/bootstrap-pom.xml.template

@@ -45,36 +45,6 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
-            <plugin>
-                <artifactId>smart-doc-maven-plugin</artifactId>
-                <version>yss-4.0.0</version>
-                <configuration>
-                    <configFile>src/main/resources/smart-doc.json</configFile>
-                    <includes>
-                        <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
-                        <include>com.yss.cloud:yss-component-dto</include>
-                        <include>com.yss.datamiddle:datamiddle-component-exception</include>
-                        <include>com.yss.datamiddle:datamiddle-component-cache-starter</include>
-                        <include>com.yss.datamiddle:valuation-outsourced-client</include>
-                        <include>com.yss.cloud:yss-component-dir-client</include>
-                        <include>com.yss.cloud:yss-component-dir</include>
-                        <include>com.yss.cloud:yss-component-dir-common</include>
-                        <include>com.yss.datamiddle:{{project_name}}-domain</include>
-                        <include>com.yss.datamiddle:{{project_name}}-infrastructure</include>
-                        <include>com.yss.datamiddle:{{project_name}}-domain</include>
-                    </includes>
-                    <projectName>${project.description}</projectName>
-                </configuration>
-                <groupId>com.github.shalousun</groupId>
-                <dependencies>
-                    <!-- 显式添加 commons-codec 依赖 -->
-                    <dependency>
-                        <groupId>commons-codec</groupId>
-                        <artifactId>commons-codec</artifactId>
-                        <version>1.15</version> <!-- 或与项目一致的版本 -->
-                    </dependency>
-                </dependencies>
-            </plugin>
         </plugins>
     </build>
 </project>

package/template/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -119,7 +119,7 @@ description: "YSS 服务的后端开发脚手架框架和技术指南。在开
 - Infrastructure 是否只实现 Gateway / Repository，并隔离 PO、Mapper、SQL、外部系统客户端。
 - Web / Adapter 是否只做协议适配、鉴权上下文、参数校验、DTO/VO 转换和响应包装。
 - Application 是否承载用例编排、事务边界和跨聚合协调，不把领域规则下沉到 Controller 或 Mapper。
-- OpenAPI Draft / Freeze、ADR、测试 seam 和安全红线是否已经明确。
+- OpenAPI Draft / Freeze、ADR、测试 seam 和已批准的架构约束是否已经明确。
 
 ## 5. 常用命令
 

package/template/.codex/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py

@@ -321,9 +321,6 @@ class ScaffoldGenerator:
         required_files = [
             self.project_root / "pom.xml",
             self.project_root / f"{self.project_name}-bootstrap" / "pom.xml",
-            self.project_root
-            / f"{self.project_name}-bootstrap"
-            / "src/main/resources/smart-doc.json",
             self.project_root / "mvnw",
             self.project_root / ".yss/scaffold-generation.json",
         ]
@@ -331,9 +328,7 @@ class ScaffoldGenerator:
         if missing:
             raise FileNotFoundError(f"生成产物缺失: {', '.join(missing)}")
 
-        smart_doc_path = required_files[2]
-        json.loads(smart_doc_path.read_text(encoding="utf-8"))
-        manifest = json.loads(required_files[4].read_text(encoding="utf-8"))
+        manifest = json.loads(required_files[3].read_text(encoding="utf-8"))
         if (
             manifest.get("contract_id") != self.contract_id
             or manifest.get("contract_version") != self.contract_version
@@ -343,14 +338,6 @@ class ScaffoldGenerator:
             != ["./mvnw validate", "./mvnw test", "./mvnw package"]
         ):
             raise ValueError("脚手架生成元数据清单与当前批准合同或固定验证命令不一致")
-        bootstrap_pom = required_files[1].read_text(encoding="utf-8")
-        plugin_versions = re.findall(
-            r"<artifactId>smart-doc-maven-plugin</artifactId>\s*<version>([^<]+)</version>",
-            bootstrap_pom,
-        )
-        if plugin_versions != ["yss-4.0.0"]:
-            raise ValueError("smart-doc-maven-plugin 必须且只能使用 yss-4.0.0")
-
         binary_suffixes = {".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"}
         for path in self.project_root.rglob("*"):
             if not path.is_file() or path.suffix in binary_suffixes:
@@ -452,17 +439,10 @@ class ScaffoldGenerator:
                 / f"{self.project_name}-bootstrap"
                 / "src/main/resources/logback-spring.xml",
             ),
-            (
-                self.config_template_dir / "smart-doc.json.template",
-                self.project_root
-                / f"{self.project_name}-bootstrap"
-                / "src/main/resources/smart-doc.json",
-            ),
         ]
         self._render_and_write_templates(config_templates)
         print("  ✓ application.yml")
         print("  ✓ logback-spring.xml")
-        print("  ✓ smart-doc.json")
 
     def _generate_database_scripts(self):
         """只保留数据库目录布局，不生成业务表或初始化数据。"""

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -13,6 +13,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 项目 token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`。
 - 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
 - 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
+- 原型阶段合同：`yss-prototype-stage`，用于统一跨 Agent 的原型资产、AntD 事实和浏览器验证证据。
 
 如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 token，必须读项目内 `docs/design/design.md`；若要执行评审或实现检查，再读 `references/design-system.md`。
 
@@ -21,7 +22,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
 2. 读取已有资产：`docs/design/design.md`、相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
-4. 若是产品设计阶段，配合 `product-design-prototype` 产出页面、流程、状态矩阵和 OpenAPI 反推清单。
+4. 若是产品设计阶段，先使用 `yss-prototype-stage`；Codex 以 `product-design:index` 为主入口，其他 Agent 必须交付等价合同资产和证据。
 5. 若是前端实现阶段，配合 `yss-ui`、`yss-components`、`yss-formily`、`yss-page-module-development`，但本技能负责风格与体验一致性门禁。
 6. 若发现现有设计系统文档不足，先更新 `docs/design/design.md`，再让实现或评审引用该文档。
 
@@ -76,15 +77,15 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 | 场景 | 配合技能 |
 | --- | --- |
-| Spec 后做页面 / 原型 / 交互说明 | `product-design-prototype` |
+| Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
-| 低保真评审通过后的高保真 HTML 原型 | `high-fidelity-html-prototype` |
-| 低保真线框或流程图 | `wireframe-prototype` / `excalidraw-diagram-generator` |
+| 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
+| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 / `excalidraw-diagram-generator` |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
 | Ant Design v6 组件 / token / demo 查询 | 官方 `@ant-design/cli` / `https://ant.design/docs/react/for-agents` |
-| API 契约 / 接入 | `api-integration` / `yss-openapi` |
+| API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
 
 ## 更新设计系统
 

package/template/.codex/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -21,7 +21,9 @@ branch: template
 - `app_name`：应用名。
 - `microapp_name`：微应用注册名。
 - `base_route`：基础路由。
-- `openapi_source`：OpenAPI 文件、URL 或 Harness spec 路径。
+- OpenAPI Freeze 记录：已批准的冻结 YAML 版本和引用。
+- OpenAPI JSON 派生记录：`docs/.scratch/<feature>/api/<feature>-json-export.md`，包含 YAML / JSON SHA-256、Redocly CLI 版本和 lockfile 引用。
+- 冻结 JSON 产物：`docs/.scratch/<feature>/api/<feature>.json`；这是唯一允许交给既有前端代码生成流程的上游产物。
 - `target_git_url` 或 `output_dir`：目标实现仓库或本地输出目录。
 - `package_manager`：默认 pnpm。
 - `init_git`：是否初始化 Git；默认必须用户明确确认。
@@ -33,9 +35,10 @@ branch: template
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
-6. 配置 OpenAPI source，并准备 Orval 生成命令。
-7. 记录验证命令：`pnpm install`、`pnpm lint:check`、`pnpm type-check`、`pnpm build`、`pnpm generate:api`。
-8. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
+6. 核验 OpenAPI Freeze 记录和 OpenAPI JSON 派生记录；通过批准的 Cross-repo 子合同或项目脚本，将记录中的 JSON 原样物化到 `<frontend>/openapi/openapi.json`，并再次核对 SHA-256。
+7. 保持模板既有的前端代码生成配置不变；本 Harness 只将 SHA-256 一致的 JSON 原样交给既有前端代码生成流程，不修改该配置、不在此仓库执行生成，也不设置生成 CI 门禁。目标前端项目在需要时手动运行其既有命令。
+8. 记录目标前端项目的 install / lint / type-check / build 命令，以及既有客户端生成命令（如有）；生成命令仅作为目标项目的手动验证项。
+9. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
 
 ## Expected Template Shape
 
@@ -55,7 +58,9 @@ packages/package.json
 
 - 不直接创建远端 Git 项目，除非用户明确要求。
 - 不推送、不创建 MR / PR，除非用户明确要求。
-- 不绕过 OpenAPI Draft / Freeze；API client 生成必须有可追溯 OpenAPI source。
+- 不绕过 OpenAPI Draft / Freeze；API client 只消费与 OpenAPI JSON 派生记录 SHA-256 一致的冻结 JSON。
+- 不接受任意 URL、未冻结 YAML、后端运行时输出或手工 JSON 作为既有前端代码生成流程的输入。
+- 不修改模板既有的代码生成配置，也不把客户端生成加入 CI。
 - 不得把 `apps/frontend/` 容器根登记为项目根；Harness 内每个前端项目必须有独立的 `apps/frontend/<project>/` 路径。
 - 不把模板示例页面当作业务功能交付。
 - 生成后仍需使用 `yss-page-module-development`、`yss-components`、`api-integration` 等专项 skill 实现业务页面。
@@ -65,6 +70,7 @@ packages/package.json
 - 前端工程生成位置或目标仓库信息。
 - 模板来源和 commit / branch 证据。
 - 替换参数清单。
-- install / lint / type-check / build / generate:api 命令。
+- install / lint / type-check / build 命令，以及目标前端项目既有的手动客户端生成命令（如有）。
+- OpenAPI Freeze 记录、OpenAPI JSON 派生记录、JSON SHA-256 和 `openapi/openapi.json` 物化证据。
 - Harness 实现仓库登记草案。
 - 未覆盖项和 `TODO-HUMAN-REVIEW`。

package/template/.codex/skills/yss-openapi-draft-review/SKILL.md

@@ -1,34 +1,33 @@
 ---
 name: yss-openapi-draft-review
-description: Use when reviewing a `docs/.scratch/<feature>/api/` OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/Spec Delta design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, permissions, pagination, optimistic locking, security red lines, and contract test seams.
+description: Use when reviewing a `docs/.scratch/<feature>/api/` OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/Spec Delta design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, pagination, optimistic locking, and contract test seams.
 ---
 
 # YSS OpenAPI Draft Review
 
-Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it is not the smart-doc / Orval generation workflow.
+Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
 
 ## Required Inputs
 
-- OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`.
+- OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
 - Calibrated Spec.
 - Interaction spec / prototype review when UI exists.
 - YSS engineering baseline rules, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
 
 ## Review Flow
 
-1. Consume fresh automated evidence for YAML parsing, `$ref`, path parameters, and lint. Generate it once with the Draft or when the Draft changes; do not manually repeat unchanged structural checks.
-2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests.
-3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes.
+1. Consume fresh automated evidence for YAML parsing, single-document OAS 3.1 shape, `$ref`, path parameters, and lint. Generate it once with the Draft or when the Draft changes; do not manually repeat unchanged structural checks.
+2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry.
+3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
 4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
 5. Check YSS API baseline: REST shape, `SingleResult<T>` for single objects, `MultiResult<T>` for non-page lists, `PageResult<T>` for pagination, and stable DTO/schema names.
-6. Check error and permission contracts: field-level errors, model-level errors, 403 no-data leakage, disabled reasons, gate failures, and conflict responses.
-7. Check security red lines: authentication/authorization, SQL/DDL draft boundaries, downloads, audit/logging, sensitive field handling, and human-review items.
-8. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+6. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
+7. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
 
 ## Automation Boundary
 
-- Automated checks own YAML syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
-- Human or independent semantic review owns P0 traceability, page-action coverage, permission and error behavior, concurrency/idempotency, security red lines, scope downgrades, and contract-test seams.
+- Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
+- Human or independent semantic review owns P0 traceability, page-action coverage, error behavior, concurrency/idempotency, scope downgrades, contract-test seams, and any explicitly specified authentication or authorization behavior.
 - Fresh passing automation evidence may be referenced by the semantic review; copying the same findings into a second checklist is unnecessary.
 - Re-run structural automation only when the Draft, ruleset, or referenced schema changes.
 
@@ -40,8 +39,8 @@ Block if any of these are true:
 - A UI action has no endpoint/non-goal mapping.
 - A configurable rule or gate lacks a source, owner, fixed/default decision, or API representation.
 - Pagination does not align with YSS `PageResult<T>` or documented exception.
-- Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, permission, and optimistic locking.
-- Security red lines are unmarked or the Draft exposes execution endpoints for SQL/DDL migration.
+- Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, and optimistic locking.
+- YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
 
 ## Output Contract
 
@@ -61,14 +60,11 @@ Block if any of these are true:
 ### YSS Baseline
 - <response wrappers, DDD boundary implications, implementation feasibility>
 
-### Security Review
-- <red lines and human-review items>
-
 ### Contract Test Checklist
 - <minimum contract tests before OpenAPI Freeze>
 
 ### Next Action
-- <return to OpenAPI Draft / enter Engineering Baseline / architecture design>
+- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
 ```
 
 Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

package/template/.codex/skills/yss-openapi-governance/SKILL.md

@@ -1,145 +1,120 @@
 ---
 name: yss-openapi-governance
-description: Use when Govern and lint YSS OpenAPI design-time contracts with Spectral or Redocly CLI before OpenAPI Freeze. Use when creating or maintaining organization-level OpenAPI style rules, validating `docs/.scratch/<feature>/api/<feature>.yaml`, defining API naming/error/pagination/permission conventions, adding contract-test checklist rules, or checking generated smart-doc output against YSS API governance. Do not use for smart-doc or Orval generation; use yss-openapi for that implementation workflow.
+description: Use when creating, governing, linting, freezing, or exporting YSS OpenAPI 3.1 design-time contracts. The frozen YAML is the only authority; this skill produces the reviewed JSON derivative consumed by frontend client generation.
 ---
 
 # YSS OpenAPI Governance
 
-Use this skill to make OpenAPI contracts consistent, lintable, and reviewable before implementation. This is the ruleset and governance layer for `docs/.scratch/<feature>/api/<feature>.yaml`; it is not the smart-doc / Orval generation workflow.
+本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
 
-## Boundary
+```text
+Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生物 → 下游既有前端代码生成流程
+```
 
-Use `yss-openapi-governance` for:
+`docs/.scratch/<feature>/api/<feature>.yaml` 是唯一权威的 OpenAPI 3.1 契约。JSON 只能由冻结后的 YAML 可复现地产生，用于前端代码生成或分发；不得手写、不得反向覆盖 YAML、不得把运行时代码当成设计契约来源。
 
-- Defining or applying reusable OpenAPI style rules.
-- Running Spectral or Redocly CLI against `docs/.scratch/<feature>/api/<feature>.yaml`.
-- Checking YSS response wrappers, error contracts, pagination, permissions, security red lines, and contract-test seams.
-- Comparing generated `openapi.json` against frozen design rules when backend code is already implemented.
-- Writing or updating governance notes under `docs/.scratch/<feature>/api/`, `docs/.scratch/<feature>/architecture/`, or the active Spec Delta design.
+## 边界与职责
 
-Use other skills for:
+使用 `yss-openapi-governance`：
 
-- `yss-openapi`: generate `target/openapi/openapi.json` from implemented controllers/DTOs and refresh Orval clients.
-- `yss-openapi-draft-review`: perform fail-closed semantic review against Spec, prototype, page actions, P0 coverage, and architecture readiness.
-- `docs/.scratch/<feature>/spec-delta/` and `to-tickets`: formalize behavior changes and implementation tickets after the contract is frozen.
+- 基于冻结前的 Spec、产品设计、架构约束创建或更新 `docs/.scratch/<feature>/api/<feature>.yaml`。
+- 保证 YAML 是单一 YAML document、根节点为 `openapi: 3.1.0`，且不把 `pipeline`、`stage`、`status`、`owner` 等生命周期元数据写入 OpenAPI 根节点。
+- 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
+- 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
+- 维护治理记录、Freeze 记录和 JSON 派生记录。
+- Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
 
-## Preferred Tooling
+不使用本 skill 来替代：
 
-Prefer Spectral when the repo needs a portable, custom OpenAPI ruleset:
+- `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
+- `api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
+- `to-tickets`：在 Freeze 后正式化垂直切片。
 
-```bash
-npx --yes @stoplight/spectral-cli lint -r .spectral.yaml docs/.scratch/<feature>/api/<feature>.yaml
-```
+## 受控工具链
 
-Prefer Redocly CLI when the repo already uses Redocly for lint, bundle, docs, or CI:
+在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
 
 ```bash
-npx --yes @redocly/cli lint docs/.scratch/<feature>/api/<feature>.yaml
+pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
+
+pnpm exec redocly bundle \
+  docs/.scratch/<feature>/api/<feature>.yaml \
+  --output docs/.scratch/<feature>/api/<feature>.json \
+  --ext json \
+  --component-renaming-conflicts-severity=error \
+  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
 ```
 
-If neither tool is configured, do not invent project policy silently. Create or propose a minimal config and mark it as draft until reviewed. Use Spectral as the default baseline for custom YSS rules because its YAML rulesets are easy to version and extend.
-
-## Governance Flow
-
-1. Locate contract inputs.
-   - Check `docs/.scratch/<feature>/api/<feature>.yaml` first.
-   - If only generated contracts exist, inspect `*/target/openapi/openapi.json` or frontend `openapi/openapi.json` as implemented evidence, not as design authority.
-   - Confirm whether the task is pre-freeze design governance or post-implementation conformance checking.
-
-2. Detect existing lint configuration.
-   - Look for `.spectral.yaml`, `.spectral.yml`, `redocly.yaml`, `redocly.yml`, `package.json` scripts, or CI jobs.
-   - Reuse the existing toolchain and scripts when present.
-   - If both Spectral and Redocly exist, run the repo's documented CI path first, then targeted local lint.
-
-3. Validate baseline OpenAPI correctness.
-   - Parse YAML/JSON successfully.
-   - Check OpenAPI version, `$ref` resolution, duplicate `operationId`, path parameter coverage, unused schemas, and invalid examples.
-   - Bundle or dereference only when needed for tooling; keep source files maintainable.
-
-4. Apply YSS API governance rules.
-   - Paths are versioned under `/api/v1/` unless a documented exception exists.
-   - Operations use stable `operationId` values suitable for Orval/client generation.
-   - Single-object responses use `SingleResult<T>`.
-   - Non-page list responses use `MultiResult<T>`.
-   - Page responses use `PageResult<T>` and expose the project's standard page request/response fields.
-   - Error responses include a consistent envelope, machine-readable code, human-readable message, and field/model-level validation shape where applicable.
-   - Permission failures avoid data leakage; 403/disabled-action behavior is explicit.
-   - Mutating operations define idempotency, optimistic locking, or conflict semantics when repeated submission or concurrent edits are possible.
-   - Download, upload, export, import, audit, sensitive data, SQL, DDL, authentication, authorization, and encryption surfaces are marked for human/security review when they touch AGENTS.md safety red lines.
-   - Contract-test seams are named for each P0 workflow and critical error path.
-
-5. Produce governance output.
-   - For quick checks, report lint command, pass/fail result, and blocking findings with file paths.
-   - For durable decisions, write or update a Chinese governance artifact under `docs/.scratch/<feature>/api/` or `docs/.scratch/<feature>/architecture/`.
-   - For active Spec Delta work, reference `docs/.scratch/<feature>/spec-delta/` and keep rules aligned with the related design, task, and spec artifacts.
-
-## Minimal Spectral Baseline
-
-When the repo lacks a ruleset and the user asks to add one, start with a small `.spectral.yaml` that extends the OpenAPI baseline and encodes only stable YSS rules. Keep controversial product semantics in review checklists until the team agrees.
-
-```yaml
-extends:
-  - spectral:oas
-
-rules:
-  yss-paths-versioned:
-    description: YSS API paths should be versioned under /api/v1.
-    message: "Path '{{property}}' should start with /api/v1/ or document an exception."
-    severity: warn
-    given: "$.paths[*]~"
-    then:
-      function: pattern
-      functionOptions:
-        match: "^/api/v1/"
-
-  yss-operation-id-required:
-    description: Operation IDs must be stable for generated clients and contract tests.
-    severity: error
-    given: "$.paths[*][*]"
-    then:
-      field: operationId
-      function: truthy
-
-  yss-tags-required:
-    description: Operations should be grouped by bounded context or module.
-    severity: warn
-    given: "$.paths[*][*]"
-    then:
-      field: tags
-      function: truthy
-```
+默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
 
-Do not overfit Spectral rules when human review is better. For example, "uses `SingleResult<T>` correctly" may require schema convention inspection and YSS context; encode it only if the repo has stable wrapper schema names.
+`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
 
-## Blocking Rules
+## 治理流程
 
-Block OpenAPI Freeze if any of these are true:
+1. **建立或读取 YAML Draft**
+   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
+   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
+   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
 
-- The contract cannot be parsed or linted with the repo's configured tool.
-- A public operation lacks `operationId`, response schema, or error contract.
-- Pagination, list, or single-object response wrappers contradict YSS baseline without a documented exception.
-- Permission, validation, conflict, import/export, upload/download, or sensitive-data behavior is ambiguous.
-- A safety-red-line area is implemented as final contract without `TODO-HUMAN-REVIEW` or equivalent review record.
-- Contract tests cannot be identified for P0 flows and critical error paths.
+2. **运行结构与治理校验**
+   - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
+   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
+   - 检查 `/api/v1/` 版本策略（或记录例外）、`SingleResult<T>` / `MultiResult<T>` / `PageResult<T>`、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
 
-## Output Contract
+3. **独立 Draft Review 与 Freeze**
+   - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
+   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
 
-```markdown
-### Governance Result
-<Pass / Blocked / Draft Rules Proposed>
+4. **从冻结 YAML 派生 JSON**
+   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
+   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
+   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `docs/api/templates/openapi-json-export-record-template.md` 创建。
+   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
+
+5. **交给下游前端**
+   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `api-integration` 与目标前端实现仓库。
+   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
+   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
+   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
 
-### Tooling
-- <Spectral/Redocly command used or proposed>
+## 阻断规则
 
-### Blocking Findings
-- <file:line grounded finding>
+阻断 OpenAPI Freeze 或 JSON 导出，若：
 
-### Rule Changes
-- <ruleset/config changes made or proposed>
+- YAML 不是单一 OAS 3.1 document，或其根节点混入生命周期元数据。
+- YAML / `$ref` / lint 不通过，operationId 不稳定或不唯一，或路径参数、schema、examples 无法解析。
+- P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
+- `$ref` 超出允许范围，或转换器版本、lockfile、命令、输入 YAML 无法识别。
+- Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
+- JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。
 
-### YSS Contract Checks
-- <response wrappers, errors, pagination, permissions, security red lines, contract tests>
+## 输出契约
 
-### Next Action
-- <fix draft / run yss-openapi-draft-review / enter OpenAPI Freeze / compare generated contract>
+```markdown
+### Governance Result
+<Draft / Approved for Freeze / Blocked / JSON Exported>
+
+### YAML Authority
+- YAML: <docs/.scratch/<feature>/api/<feature>.yaml>
+- OAS: 3.1.0
+- YAML SHA-256: <sha256>
+- Freeze record: <path / ref>
+
+### Validation
+- Lint command and result: <locked pnpm command / result>
+- `$ref` policy / approved exceptions: <details>
+- Blocking findings: <file:line grounded finding>
+
+### JSON Derivative
+- JSON: <docs/.scratch/<feature>/api/<feature>.json>
+- JSON SHA-256: <sha256>
+- Redocly CLI / lockfile: <version and lock reference>
+- Bundle command and metafile: <command / path>
+- JSON validation result: <pass / blocked>
+
+### Downstream Handoff
+- Canonical JSON / frontend materialization SHA-256: <same sha / blocked>
+- Frontend materialization path: <frontend/openapi/openapi.json / blocked>
+- Existing frontend code generation: <manual command in target repository / blocked reason>
+- Template boundary: <no frontend configuration, code-generation execution, or CI change>
 ```