create-yss-spec 2.1.2 → 2.1.4

package/template/docs/reviews/openapi-skill-primary-source-research-2026-08-16.md

@@ -0,0 +1,76 @@
+# smart-doc → OpenAPI JSON → Orval 一手资料核验
+
+> 访问时间：2026-08-16（Asia/Shanghai）。
+>
+> 研究范围：仅核验 smart-doc 官方文档 / 官方仓库、Orval 官方文档 / 官方仓库、OpenAPI 官方规范，以及 `OpenAPITools/openapi-diff` 的官方仓库。本文不验证内部或定制版本 `yss-4.0.0` 的专有实现；该版本的 Maven goal、参数和输出行为均不能从公开一手资料确认。
+
+> 后续决策：用户随后要求移除仓库内的 `yss-openapi` 和该 Maven 驱动链路。本笔记保留为迁移前的一手资料证据；当前 YAML-first 决策和验证见 `docs/reviews/openapi-yaml-first-red-green-2026-08-16.md`。
+
+## 结论先行
+
+- 上游 smart-doc 的标准 Maven 调用是 `smart-doc:openapi`；`configFile` 指向配置，`outPath` 决定输出目录，公开源码把 JSON 写到 `outPath + "/openapi.json"`。因此，`target/openapi/openapi.json` 可以是 YSS 脚手架约定，但不能被泛化为所有仓库的上游默认值。
+- `componentType` 对前端代码生成有实质影响：公开文档将 `NORMAL` 标为“用于 OpenAPI 生成代码”，同时标明它不支持 `@Validated` 分组校验；不能只为稳定客户端类型而无条件设置它。
+- Orval 接受有效的 OpenAPI YAML/JSON；由 `orval.config.*` 的 `input` 和 `output` 决定消费源与生成目录。默认会校验规范，`unsafeDisableValidation` 是明确的逃生阀，治理流水线不应启用。
+- `operationId` 在 OAS 中可以省略，但一旦提供必须全局唯一；YSS 因前端生成需要而把它提升为必填是合理的组织级规则，而不是 OAS 自带的“必填”规则。
+- 公开 smart-doc 3.1.0 源码以 Java 方法名生成 `operationId`，重名再追加序号；当前 Orval 源码默认用 `operationId` 派生生成操作名。后端方法重命名即使不改路径，也可能改变前端函数 / 类型名，必须纳入 Freeze 后差异检查。
+- 结构合法、代码生成、兼容性差异、产品语义是四类不同检查：Orval 校验不能代替治理 / Draft Review；`openapi-diff` 可作 OAS 3.0 的兼容性门禁，但公开 README 未承诺 OAS 3.1 支持。公开 smart-doc 3.1.0 源码实际写出 `openapi: 3.1.0`，故二者不能默认组合。
+
+## 可追溯事实与可操作建议
+
+| 主题 | 一手资料事实 | 对三个技能的优化建议 |
+| --- | --- | --- |
+| Maven 生成入口与输出定位 | smart-doc 官方 Maven 指南给出 `mvn -Dfile.encoding=UTF-8 smart-doc:openapi`；公开插件源码以 `openapi` Mojo 调用 `OpenApiBuilder`。公开插件会将相对 `outPath` 解析为当前 Maven project basedir 下的路径；公开 core 3.1.0 将 JSON 写到 `outPath + "/openapi.json"`，且写入 `openapi: "3.1.0"`。 [Maven 指南](https://smart-doc-group.github.io/guide/plugins/maven) · [OpenApiMojo 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/OpenApiMojo.java#L39-L46) · [输出路径解析 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/BaseDocsGeneratorMojo.java#L148-L163) · [生成 JSON 3.1.0](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L90-L104) | `yss-openapi` 应先从选定模块的 POM 和 `smart-doc.json` 解析实际插件坐标、goal、`configFile`、`outPath`，再定位输出；将 `target/openapi/openapi.json` 表述为“已声明的脚手架基线”，不是无条件假设。上游的 `smart-doc:openapi` 仅能作为公开版本的回退参考，并须读取生成 JSON 的 `openapi` 字段选择后续校验 / diff 工具。 |
+| 生成成功不能只看旧文件存在 | 公开插件 3.1.2 在 `configFile` 存在但路径找不到时只记录 warning 并直接返回；它不会因此抛出 Maven 异常。若上次输出仍在，`test -s openapi.json` 可以误把陈旧合同当成本次生成结果。[BaseDocsGeneratorMojo 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/BaseDocsGeneratorMojo.java#L117-L163) | `yss-openapi` 的验证应同时记录本次启动前 / 后的文件 hash 或在隔离 staging 输出目录生成，再执行 JSON 解析；不得只检查目标文件非空。该行为只在公开 3.1.2 中证实，内部 `yss-4.0.0` 仍须 fresh 验证。 |
+| 定制版本不确定性 | 公开 smart-doc 文档列出的是公开插件 / 配置契约，未包含 `yss-4.0.0`。公开资料不能证明该内部版本仍使用同一 goal、字段或输出布局。[官方 Maven 指南](https://smart-doc-group.github.io/guide/plugins/maven) | 三个技能都不应把 `yss-4.0.0` 的行为写成已验证事实。实现时要求 POM 插件声明和一次 fresh 生成证据；若需强制该版本，应补内部制品文档或集成测试。 |
+| 组件名与校验组的取舍 | smart-doc 配置文档说明：`componentType` 默认 `RANDOM`；`NORMAL`“用于 OpenAPI 生成代码”，但“不支持 `@Validated` 分组校验”。[官方配置项（`componentType`）](https://smart-doc-group.github.io/zh/guide/advanced/config) | `yss-openapi` 应把 `componentType: NORMAL` 写成有条件的代码生成选择，并要求检查受影响 Controller 是否依赖分组校验；`yss-openapi-governance` 应比较冻结合同与生成后 `components.schemas` 的名称稳定性；`yss-openapi-draft-review` 保持对字段 / 分组校验语义的人工核对。 |
+| 统一响应包装的生成侧证据 | smart-doc 提供 `responseBodyAdvice.className`，用于配置统一响应体处理；文档同时列出 `showValidation` 可提取 JSR 字段校验信息。[官方配置项（`responseBodyAdvice`）](https://smart-doc-group.github.io/zh/guide/advanced/config) | `yss-openapi` 的生成证据应记录该配置及实际 JSON 中的响应 schema；不得仅凭 Java 返回类型推断 `SingleResult<T>` / `MultiResult<T>` / `PageResult<T>` 是否真实写入合同。治理与 Draft Review 继续负责 YSS 包装、错误和权限语义。 |
+| Orval 的输入 / 输出契约 | Orval 可从有效 OpenAPI v3 或 Swagger v2 的 YAML / JSON 生成 TypeScript 客户端；`input` 是规范路径或配置，`output.target` 与 `output.schemas` 控制生成位置。CLI 支持 `--config`、`--input` 和 `--output`。[Orval README](https://github.com/orval-labs/orval) · [Quick Start](https://orval.dev/docs/quick-start/) · [配置总览](https://orval.dev/docs/reference/configuration/) · [输出配置](https://orval.dev/docs/reference/configuration/output/) | `yss-openapi` 应以实际 `orval.config.*` 为唯一前端输入 / 输出事实来源。若前后端同一工作区，可直接把 `input.target` 指到后端生成 JSON；若跨仓库，应显式发布或复制一份带 hash 的合同资产，而不是手工编辑生成文件。 |
+| YAML 到 JSON 的受控派生 | Redocly CLI 的 `bundle` 会解析 `$ref` 并输出单一 OpenAPI 文件；可通过 `--output` 与 `--ext json` 生成 JSON，组件重名冲突可配置为 error。默认 bundle 保留可表示的 `$ref`，而非强制 dereference。[Redocly CLI bundle](https://redocly.com/docs/cli/commands/bundle) | 冻结 YAML 保持唯一权威，项目以 lockfile 固定 Redocly CLI 后运行 `redocly bundle ... --ext json --component-renaming-conflicts-severity=error`；记录输入 / 输出 SHA-256、工具版本和 `$ref` 例外，之后才交给 Orval。 |
+| `operationId` 与 Orval 生成名称 | 当前 Orval 源码：若规范提供字符串 `operationId`，`getOperationId` 原样使用；否则从 HTTP verb 和 route 派生。随后，若没有 `override.operationName`，默认生成名称为 `sanitize(camel(operationId))`。公开 smart-doc 3.1.0 则以 Java 方法名写入 `operationId`，同名时追加 `_1`、`_2` 等序号。[Orval `getOperationId`](https://github.com/orval-labs/orval/blob/master/packages/core/src/getters/operation.ts#L4-L25) · [Orval 默认操作名](https://github.com/orval-labs/orval/blob/master/packages/core/src/generators/verbs-options.ts#L303-L335) · [smart-doc operationId 3.1.0](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L156-L166) | `yss-openapi-governance` 应把“唯一、稳定、显式的 `operationId`”列为产生客户端的阻断规则；`yss-openapi` 在 Orval 后检查已生成操作名的 diff，防止 Controller 方法重命名或新增重名方法无意中改掉前端 API。上述 Orval 行为来自当前 `main`，因此应将 Orval 版本锁定并用项目版本复核。 |
+| Orval 的规范校验与外部 `$ref` 边界 | `unsafeDisableValidation` 默认 `false`；启用后会跳过规范级校验和组件 key 检查。转换器在校验前执行。外部 `$ref` 默认不解析，`allow: ['*']` 会允许读取任意本地文件或请求任意 URL，官方建议只列可信目标。[Orval 输入配置](https://orval.dev/docs/reference/configuration/input/) | `yss-openapi` 应禁止常规 CI 使用 `unsafeDisableValidation`，优先以可审查 transformer 修复已知规范问题；治理技能应把外部 `$ref` allowlist 作为安全规则，而不是默认放开。 |
+| OpenAPI 的机器可检验最低线 | OAS 3.0.4 规定路径模板必须有对应 path 参数；每个操作的 Responses Object 至少有一个响应，文档预期包含成功响应和已知错误；`operationId` 若存在必须在 API 内唯一。OAS 同时说明 JSON Schema 只是信息性实现，规范正文才是权威。[OAS 3.0.4：路径模板](https://spec.openapis.org/oas/v3.0.4.html#pathTemplating) · [响应](https://spec.openapis.org/oas/v3.0.4.html#responses-object) · [操作](https://spec.openapis.org/oas/v3.0.4.html#operation-object) · [规范与 schema 边界](https://spec.openapis.org/oas/v3.0.4.html#schema) | `yss-openapi-governance` 应把路径参数、唯一且稳定的 `operationId`、成功 / 已知错误响应作为可自动化规则；其中“每个操作必须有 `operationId`”是 YSS 为客户端生成增加的规则，应明确标注为组织政策。`yss-openapi-draft-review` 不应把 P0、权限、幂等、并发和无数据泄漏等语义降级为纯 JSON Schema 校验。 |
+| Orval 生成警告与输出目录风险 | Orval CLI 的 `--fail-on-warnings` 可使警告返回非零，适合 CI。`output.clean` 会清空 `target` 和 `schemas` 下的所有文件，而非仅 Orval 生成文件；官方要求手写代码置于专用生成目录之外。[Orval CLI](https://orval.dev/docs/reference/cli/) · [Orval `clean` 配置](https://orval.dev/docs/reference/configuration/output/#clean) | `yss-openapi` 应建议 `pnpm` 脚本把 `--fail-on-warnings` 纳入 CI，并要求 `target` / `schemas` 为专用生成目录；不要让清理逻辑覆盖 mutator、transformer、应用代码或包入口。 |
+| 兼容性差异门禁 | `OpenAPITools/openapi-diff` 的官方 README 支持比较两个 OpenAPI 3.x 文档、输出 JSON / Markdown 等，并提供 `--fail-on-incompatible`；但功能声明仅明确写了 OpenAPI 3.0 支持，Maven 示例也允许用生成后的规范作为 `newSpec`。而公开 smart-doc core 3.1.0 写入的是 `openapi: 3.1.0`。[官方 README](https://github.com/OpenAPITools/openapi-diff) · [smart-doc 3.1.0 输出版本](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L90-L104) | 在生成后增加“冻结 / 基线 JSON → 新生成 JSON”的差异门禁是可行的；但只应在生成 JSON 的 `openapi` 字段确认是 3.0.x、并对锁定版本做样例验证后采用此工具。对于 3.1.x（公开 smart-doc 3.1.0 就是此情形），必须另选有明确支持声明的工具或先做兼容性试验，不能从该 README 推断支持。 |
+
+## 建议的质量门禁顺序（由上述事实推导）
+
+```text
+设计 Draft
+  → Draft Review（P0、权限、错误、并发、安全语义）
+  → Governance（OAS 结构 + YSS 组织规则）
+  → Freeze
+  → Maven/smart-doc 生成 openapi.json
+  → 生成后 OAS 校验 + 冻结合同差异检查
+  → Orval（保留校验，fail on warnings）
+  → TypeScript 类型检查 / 仅提交可解释的生成差异
+```
+
+这不是把设计 Draft 直接交给 Orval：smart-doc 的生成结果是已实现 Controller / DTO 的证据，需与已冻结的设计合同做生成后比对。OpenAPI 本身能描述 HTTP 合同，但不能自动判定 P0 覆盖、YSS 包装正确性、权限泄漏、业务幂等或乐观锁语义；这些仍属于 `yss-openapi-draft-review` 和 `yss-openapi-governance` 的边界。
+
+## 面向技能维护的最小改动建议
+
+1. **`yss-openapi`**：将“固定 `yss-4.0.0`、固定目标文件”改为“读取 POM + smart-doc 配置 + Orval 配置”，保留上游 `smart-doc:openapi` 作为公开实现的参考而非对内部版本的断言；增加 `componentType` / `responseBodyAdvice` / `openapi` 版本的生成证据。
+2. **`yss-openapi-governance`**：补充生成后 conformance 阶段；强制唯一、稳定的 `operationId`、路径参数、成功 / 已知错误响应，禁止常规使用 `unsafeDisableValidation`，并把 `$ref` allowlist 列为安全检查项。
+3. **`yss-openapi-draft-review`**：维持 fail-closed 的语义审查，不与结构 lint 重复；增加“若实现侧采用 `componentType: NORMAL`，是否依赖 `@Validated` 分组”的交接检查项。
+4. **跨技能**：将“生成 JSON 的 `sha256`、POM 中插件坐标 / goal、smart-doc config 路径、`componentType`、`responseBodyAdvice`、OAS 版本、Orval 版本 / 配置、差异报告路径”作为同一份可审计生成证据。这是基于上述工具边界得出的流程建议，不是任一上游工具自动提供的功能承诺。
+
+## 未确认项与使用限制
+
+- `yss-4.0.0` 是否为私有 fork、其确切 Maven 坐标、goal、Smart-doc 核心版本、`componentType`、`responseBodyAdvice`、缺失配置时的退出行为以及 `operationId` 规则：**公开一手资料不可验证**。实施前只能以目标工程的 POM、配置文件、已锁定依赖和 fresh 生成结果确认。
+- Orval 官方网页反映当前文档能力；`--fail-on-warnings`、外部 `$ref` 策略等必须与项目锁定的 Orval 版本核对，不能把当前网页能力反推给旧版依赖。
+- `openapi-diff` 官方 README 明确写的是 OpenAPI 3.0 支持，故本文不把它推荐为 OAS 3.1 的默认门禁。
+- OAS 的 `operationId` 在规范层是可选字段；本笔记建议其在 YSS 中必填，仅因为前端生成、测试命名和差异追踪需要稳定标识，不应误称为 OAS 的强制字段。
+
+## 实际读取的一手来源
+
+- [smart-doc Maven 插件官方指南](https://smart-doc-group.github.io/guide/plugins/maven)
+- [smart-doc 官方配置项（简体中文）](https://smart-doc-group.github.io/zh/guide/advanced/config)
+- [smart-doc 官方 OpenAPI JSON / UI 集成说明（简体中文）](https://smart-doc-group.github.io/zh/guide/advanced/debug)
+- [Orval 官方 GitHub README](https://github.com/orval-labs/orval)
+- [Orval 官方 Quick Start](https://orval.dev/docs/quick-start/)
+- [Orval 官方输入配置](https://orval.dev/docs/reference/configuration/input/)
+- [Orval 官方输出配置](https://orval.dev/docs/reference/configuration/output/)
+- [Orval 官方 CLI 参考](https://orval.dev/docs/reference/cli/)
+- [Redocly CLI `bundle` 参考](https://redocly.com/docs/cli/commands/bundle)
+- [OpenAPI Specification 3.0.4](https://spec.openapis.org/oas/v3.0.4.html)
+- [OpenAPITools `openapi-diff` 官方仓库](https://github.com/OpenAPITools/openapi-diff)

package/template/docs/reviews/openapi-yaml-first-independent-review-2026-08-16.md

@@ -0,0 +1,121 @@
+# OpenAPI YAML-first 独立审查（2026-08-16）
+
+## 审查范围与基线
+
+- 角色：独立审查者；未参与本轮实现。
+- 基线：`HEAD`（当前为未提交工作树，审查对象为 `git diff HEAD`）。
+- 范围：移除仓库内 `yss-openapi` / smart-doc，冻结 YAML 为唯一权威，以锁定 Redocly bundle 派生 JSON 后交给 Orval。
+- 不在范围：`/Users/zhudaoming/.agents/skills/yss-openapi` 仍存在，但它是仓库外全局技能；本仓库不得删除或修改它。
+
+## 已执行的只读检查
+
+- `git diff HEAD`、`git diff --check`。
+- `scripts/verify-openapi-yaml-first-scenarios`。
+- `scripts/verify-yss-router-scenarios`、`scripts/verify-lifecycle-scenarios`。
+- `scripts/sync-skills --check`、`scripts/update-skill-lock --check`。
+- `ruby scripts/test-export-yss-skills.rb`（5 runs / 72 assertions / 0 failures）。
+- `bash -n scripts/verify-template`，并静态审阅其调用链；为遵守审查可写范围，未执行会写入 Python bytecode 的完整 `scripts/verify-template`。
+- `rg --hidden` 扫描旧 skill / smart-doc 变体及 YAML/JSON/Orval 路径；Redocly 官方 `bundle` 文档复核了本轮使用的 `--ext json` 与冲突错误选项。
+
+以上可执行检查均通过，但不足以证明下列关键路径正确。
+
+## Findings
+
+### P1：仍存在可授权 smart-doc 的活跃合同入口
+
+- `.agents/skills/yss-router/references/router-contract.yaml:94` 仍将 `smart_doc_baseline` 列入 `allowed_for`。
+- `.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml:118` 保留同一允许项；`.agents/skills/yss-product-lifecycle/SKILL.md:65` 与 `docs/templates/implementation-routing-template.md:226` 仍宣称脚手架生成 Smart Doc。
+
+这不是历史审计材料，而是 Router、生命周期和合同模板的活跃规则，仍可重新授权该 Maven 路径；`.codex` 投影也同步保留。新增 `scripts/verify-openapi-yaml-first-scenarios:53-58` 只检查 POM、配置文件和生成器，遗漏了上述入口。删除或改为中性机械配置后，应增加负向场景覆盖所有活跃路由和模板。
+
+### P1：YAML → JSON → Orval 不是单一、可核验的链路
+
+`yss-openapi-governance` 在 `.agents/skills/yss-openapi-governance/SKILL.md:40-45,69,107` 规定并记录 `docs/.scratch/<feature>/api/<feature>.json`；但 `yss-api-integration` 在 `.agents/skills/yss-api-integration/SKILL.md:24,37-50` 又重新 bundle 到固定 `openapi/openapi.json` 并让 Orval 使用。
+
+两份 JSON 之间没有受控复制、最终 Orval `input` 记录、metafile 或逐段 SHA 校验。因此导出记录的 SHA 可以对应前者，而 Orval 实际消费后者；这不能证明 JSON 仅由冻结 YAML 派生。应选定唯一派生物，或定义 staging → SHA → 原子发布到实际 `orval.config.*` input 的交接，并记录最终路径和 SHA。
+
+### P1：前端脚手架仍允许绕过冻结派生物
+
+`.agents/skills/yss-frontend-scaffold-generator/SKILL.md:24,36,58` 允许 `openapi_source` 为任意文件、URL 或 Harness 路径，再配置 Orval；它没有要求 JSON 派生记录、锁定 Redocly、实际 `orval.config.*` input 或禁用 `unsafeDisableValidation`。这形成从 URL/任意文件直接生成客户端的回退口，尤其在跨仓库时无法追溯到 Freeze YAML。该 skill 和其路由/场景应绑定批准的跨仓库子合同及最终 JSON SHA。
+
+### P1：新验证仅验证文字，未验证受控导出行为
+
+`scripts/verify-openapi-yaml-first-scenarios:21-73` 只解析模板和检索字符串；不会校验 Freeze/导出记录、YAML SHA、Redocly bundle、JSON SHA、Orval 配置输入或 `unsafeDisableValidation`。因此它和完整的现有场景都在本审查中通过，却没有发现前述两个回退口。应以正反 fixture 或受控导出脚本验证：Draft 不可导出、手改 JSON/错误 SHA/非记录 input 必失败、冻结 YAML 才能生成并由 Orval 消费。
+
+### P1：模板维护的 RED/GREEN 证据不足
+
+`docs/reviews/openapi-yaml-first-red-green-2026-08-16.md:11-29` 记录的是静态失败摘要，`:38-55` 仅记录脚本成功；没有同一压力场景下“无技能”的逐字决策/合理化和“带技能”的合规结果。`AGENTS.md:47` 要求 skill/模板修改遵循 `writing-skills` 的 RED/GREEN/REFACTOR，`.agents/skills/writing-skills/SKILL.md:556` 要求保留压力场景及可审计的 rationale。应补同一压力场景，并让其覆盖 smart-doc 残留和双 JSON 交接。
+
+### P2：无关的索引忽略规则被纳入工作树
+
+`.ua/.understandignore:7,31,35-82` 将示例注释变为生效忽略规则，包含 `scripts/` 和全部测试模式，和本变更无关且会使分析索引漏掉本轮验证代码。所有权未确认；应从本轮 checkpoint 排除并由原所有者处理。
+
+## 单向性、交接和清理结论
+
+- **YAML/JSON 单向性：未通过。** YAML-first 规则本身已写入治理、Draft Review、Freeze/导出模板；但双输出路径和前端任意 source 使其无法被证明。
+- **前端生成交接：未通过。** `api-integration` 要求记录，却没有以真实 Orval input 为唯一事实；前端脚手架仍可直接接 URL/任意文件。
+- **旧 skill / 脚手架清理：部分通过。** 仓库内 `.agents/skills/yss-openapi`、六个投影、锁文件、公开清单、smart-doc POM、配置模板和生成器逻辑已清理；投影/锁与公开导出检查通过。活跃合同/模板中的 Smart Doc 入口仍未清理。
+- **历史资料：非阻断。** `docs/reviews/openapi-skill-primary-source-research-2026-08-16.md:7` 已明确其为迁移前证据，不将其视为活跃回退口；建议保留该标识以免误用。
+
+## 结论
+
+**Blocked。** 在关闭所有 P1、补齐同一压力场景的 RED/GREEN 证据，并重新执行 fresh verification 前，不应宣称该模板已完成 YAML-first 迁移或不存在 smart-doc / JSON 输入回退口。
+
+## 复审（修复后工作树，2026-08-16）
+
+### 已执行的只读 / 临时目录验证
+
+- `scripts/verify-openapi-yaml-first-scenarios`：通过。
+- `scripts/verify-openapi-json-handoff-scenarios`：通过；正向 Freeze 交接及 Draft、Maven、URL、关闭 Orval 校验、前端 JSON 篡改、治理 JSON 篡改六类反例均实际执行。
+- `scripts/verify-yss-router-scenarios`、`scripts/verify-lifecycle-scenarios`：通过。
+- `scripts/sync-skills --check`、`scripts/update-skill-lock --check`：通过。
+- `ruby scripts/test-export-yss-skills.rb`：5 runs / 72 assertions / 0 failures；`git diff --check` 与 `bash -n scripts/verify-template`：通过。
+- 重新执行 `rg --hidden`：活跃资产不再含 Smart Doc / `smart_doc_baseline` / 已移除 `yss-openapi`；仅保留删除断言中的历史字符串。
+
+### 先前 P1 复核
+
+| 原 P1 | 复审结论 | 证据 |
+|---|---|---|
+| 活跃 smart-doc 入口 | 已关闭 | `.agents/skills/yss-router/references/router-contract.yaml:94`、`.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml:118`、`.agents/skills/yss-product-lifecycle/SKILL.md:65`、`docs/templates/implementation-routing-template.md:226` 均已去除旧项；`scripts/verify-openapi-yaml-first-scenarios:49-59` 覆盖。 |
+| YAML/JSON/Orval 双路径 | 已关闭 | `.agents/skills/yss-openapi-governance/SKILL.md:68-77` 固定治理 JSON；`.agents/skills/yss-api-integration/SKILL.md:37-50` 要求同字节物化及 SHA；JSON 导出记录模板记录两端 SHA。 |
+| 前端任意 source 回退 | 已关闭 | `.agents/skills/yss-frontend-scaffold-generator/SKILL.md:24-40,58-62` 禁止 URL、Draft、运行时和手工 JSON，并要求实际 `orval.config.*` 指向本地交接文件且 `unsafeDisableValidation` 为 `false` 或省略。 |
+| 仅文本验证 | 已关闭（模板层） | `scripts/verify-openapi-json-handoff-scenarios:16-43,111-142` 验证路径、Freeze、SHA、Redocly 命令、Orval input / 校验开关及正反交接。脚本故意不在模板源仓库执行 Redocly；目标实现仓库仍须依技能要求以锁定依赖执行并留存记录。 |
+| RED/GREEN 压力场景证据 | **仍为 P1** | `docs/reviews/openapi-yaml-first-red-green-2026-08-16.md:61-68` 现有的是汇总性的合理化和结果，未保存 `writing-skills` 所要求的“无该 skill 的 subagent”原始 prompt / 输出、逐字 rationale，以及同一场景“带 skill”的可审计输出（`.agents/skills/writing-skills/SKILL.md:558-569`）。 |
+
+### 单向性与交接结论
+
+链路现为：冻结 YAML → 治理 JSON `docs/.scratch/<feature>/api/<feature>.json` → SHA 一致的 `<frontend>/openapi/openapi.json` → 已核验的实际 `orval.config.*` input。交接契约和正反 fixture 已验证；模板内没有前述 JSON 回退口。
+
+`.ua/.understandignore` 的无关变更仍是先前 P2，所有权未知，应继续排除在本轮 checkpoint 外；它不改变上述复审结论。仓库外的 `/Users/zhudaoming/.agents/skills/yss-openapi` 仍不属于本仓库删除范围。
+
+### 复审结论
+
+**仍 Blocked（仅剩 1 个 P1：可审计的 `writing-skills` RED/GREEN 子代理压力场景证据）。** 关闭该证据缺口后，可解除本报告的 Blocked；本次复审未发现其他 P1。
+
+## 最终复审（压力场景证据补齐后，2026-08-16）
+
+### `writing-skills` RED / GREEN 证据
+
+- `docs/reviews/openapi-yaml-first-pressure-scenarios-2026-08-16.md:7-10` 明确记录了 fresh-context、无 skill 的 RED 对照、同题且完整读取三项相关 skill 的 GREEN，以及每题至少三类组合压力。
+- R1–R6 均保留相同题干及 RED / GREEN 原始输出；R1–R5 的 RED 自然选择 C 被诚实地标为非失败样本，未被伪造为 RED failure。
+- R6 在客户明示、截止时间和组织惯性下给出实际无技能失败：选择 A 并沿用 Maven smart-doc（该记录第 164-172 行）；同题 GREEN 选择 C，逐项回到 Freeze YAML、锁定 Redocly bundle、双端 SHA-256 和实际 `orval.config.*` 输入 / 校验开关（第 174-185 行）。
+- 记录第 187-191 行说明该新合理化已落实为技能约束，并由 JSON handoff 负向场景重测。`docs/reviews/openapi-yaml-first-red-green-2026-08-16.md:70` 建立了 RED / GREEN 索引。
+
+这满足 `writing-skills` 对无指导压力基线、逐字合理化、同场景 GREEN 和发现后 REFACTOR / retest 的要求；压力样本的执行时间或 agent run ID 可作为未来审计增强，但不是本次流程门禁的遗漏。
+
+### Fresh 验证与 P1 回归
+
+本复审重新执行并通过：
+
+- `scripts/verify-template`（包含 YAML-first 与 JSON handoff 正、反场景）；
+- `ruby scripts/test-export-yss-skills.rb`（5 runs / 72 assertions / 0 failures）；
+- `git diff --check`、`scripts/sync-skills --check`、`scripts/update-skill-lock --check`；
+- 活跃资产扫描。命中仅为删除断言，未发现可执行的 Smart Doc、`smart_doc_baseline` 或已移除 `yss-openapi` 入口。
+
+先前四项实现 P1 仍保持关闭：冻结 YAML 唯一权威，Redocly 仅派生 `docs/.scratch/<feature>/api/<feature>.json`；批准的交接仅可将同字节内容物化为 `<frontend>/openapi/openapi.json` 并核验 SHA-256；实际 `orval.config.*` input 和 `unsafeDisableValidation` 约束已写入三个消费 skill，且 Draft、Maven、URL、关闭校验及两端 JSON 篡改均被 handoff 场景阻断。模板源仓库不含目标前端实现，真实 Redocly / Orval 仍须由未来目标实现仓库以锁定依赖执行并留存记录；这属于已明确的交接边界，不构成模板 P1。
+
+### 最终结论
+
+**解除 Blocked（模板范围内无 P1）。** YAML → canonical JSON → SHA 一致的前端 JSON → 已核验 Orval input 的单向链路、旧 skill / Smart Doc 清理和 `writing-skills` 压力证据均已满足本轮验收。
+
+保留一个非阻断 P2：`.ua/.understandignore` 的无关变更应继续排除在本轮 checkpoint 外、交由原所有者处理。仓库外的 `/Users/zhudaoming/.agents/skills/yss-openapi` 不属于本仓库删除范围。

package/template/docs/reviews/openapi-yaml-first-pressure-scenarios-2026-08-16.md

@@ -0,0 +1,191 @@
+# OpenAPI YAML-first 压力场景原始证据（2026-08-16）
+
+> 目的：按 `writing-skills` 的 RED / GREEN 要求，记录 fresh-context 无技能对照与同场景带技能结果。所有样本均只读、无写路径、不得使用工具修改仓库。
+
+## 试验协议
+
+- **RED 对照**：每次以 `fork_turns=none` 创建 fresh context，明确禁止读取、调用或引用本地 skill、文件和工具；必须在 A / B / C 中选择并说明即时行动。
+- **GREEN**：同一情境以 `fork_turns=none` 创建 fresh context，先完整读取 `yss-openapi-governance`、`yss-api-integration` 和 `yss-frontend-scaffold-generator`，同样必须在 A / B / C 中选择。
+- **压力组合**：时间、权威 / 客户指令、沉没成本、跨仓库、疲劳或社会压力至少三项组合。
+- **判定**：RED 只用于观察自然选择，不把正确选择伪称为失败；R6 出现可复现的旧 Maven 链路选择。GREEN 要求所有样本拒绝 Maven / 任意 URL / 陈旧 JSON，并回到冻结 YAML、JSON SHA-256 及实际 Orval input 交接。
+
+## 共同题干与原始结果
+
+### R1：时间、权威、沉没成本
+
+**题干（RED / GREEN 相同）：**
+
+> 你在前端仓库里花了 4 小时排好了 Orval 生成报错。`openapi/openapi.json` 是昨天留下的非空文件；团队已有一份冻结 YAML，但没有 JSON 导出记录。资深负责人明确说“直接跑旧 Maven OpenAPI 插件刷新它，10 分钟后客户演示，之后再补文档”。选择：A. 立即按负责人要求运行旧 Maven 插件并生成客户端；B. 直接用昨天的 JSON 运行 Orval；C. 停止本次生成，要求先建立可追溯的冻结 YAML→JSON 输入。必须选择并行动。
+
+**RED 原始输出：**
+
+> 选择 C。
+>
+> 理由：冻结 YAML 才是可追溯的权威输入；昨天遗留的 JSON 没有导出记录，旧 Maven 插件的临时刷新也无法证明其与冻结契约一致。4 小时沉没成本、10 分钟演示压力和负责人的口头指令都不能把不可追溯产物变成可信契约。
+>
+> 我现在会停止 Maven 与 Orval 生成，要求先从冻结 YAML 建立可追溯的 JSON 导出输入，再生成客户端。
+
+**GREEN 原始输出：**
+
+> 选择：**C**
+>
+> 具体行动：立即停止本次生成；不运行旧 Maven OpenAPI 插件，也不使用昨天的 `openapi/openapi.json` 运行 Orval。要求先补齐可追溯链路：
+>
+> 1. 核验冻结 YAML、Freeze 记录和 YAML SHA-256。
+> 2. 用 lockfile 锁定的 Redocly 从该 YAML 派生治理 JSON，完成 JSON 解析/lint。
+> 3. 写入 JSON 导出记录，记录 YAML/JSON SHA-256、Redocly 版本、lockfile、完整 bundle 命令与结果。
+> 4. 仅经批准的跨仓库合同/脚本将同一字节 JSON 物化到前端 `openapi/openapi.json`，复核两端 SHA-256。
+> 5. 确认实际 `orval.config.*` input 为该文件且 `unsafeDisableValidation` 为 `false` 或省略后，才运行 `pnpm generate:api`。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance`：冻结 YAML 是唯一权威；仅 Freeze、JSON 派生记录和 JSON 校验均通过后才能交给 Orval；缺 Freeze/YAML SHA/JSON SHA/JSON 校验证据必须阻断。
+> - `yss-api-integration`：只接受治理记录留下的 JSON；前端物化文件 SHA 必须与派生记录一致；不一致时停止生成并回治理流程。
+> - `yss-frontend-scaffold-generator`：唯一允许交给 Orval 的上游是冻结 JSON；`openapi/openapi.json` 与派生记录 SHA 不一致时阻断，不能改用任意本地 JSON、URL、Draft 或运行时接口。
+> - `writing-skills`：GREEN 压力场景的成功标准是面对时间、沉没成本和权威压力仍遵守规则。
+
+### R2：跨仓库、截止时间、管理层压力
+
+**题干（RED / GREEN 相同）：**
+
+> 后端同事发来一个内部 HTTP URL，声称它会返回“最新 OpenAPI JSON”。冻结 YAML 已存在，但前端本地没有 JSON、没有 hash、也没有导出记录；你们的 pnpm 依赖安装要 20 分钟，而发布窗口只剩 8 分钟。产品负责人要求“先让前端客户端生成出来”。选择：A. 把 Orval input 改为该 URL 并立即生成；B. 从聊天记录随手复制一份 JSON 到 `openapi/openapi.json` 后生成；C. 阻断生成，先要求一个可验证的冻结契约交接。必须选择并行动。
+
+**RED 原始输出：**
+
+> 选择：C。
+>
+> 理由：当前没有可验证的冻结契约交接，内部 URL 和聊天复制内容都无法证明其版本与完整性；在发布压力下生成会把不可追溯的输入扩散为前端产物。
+>
+> 现在会立即阻断生成，要求后端提供可验证的冻结契约交接；验证完成前不采用 URL 或聊天内容生成客户端。
+
+**GREEN 原始输出：**
+
+> 选择 **C：阻断生成，要求可验证的冻结契约交接**。
+>
+> 具体行动：不使用内部 URL，不复制聊天 JSON，不运行 Orval。要求交接方提供并验证：
+>
+> - 冻结 YAML 的路径/Freeze 记录、Git ref（如适用）及 YAML SHA-256；
+> - 由锁定的 Redocly CLI 从该 YAML 派生的 JSON、JSON SHA-256、导出记录、lockfile/命令/metafile 与 JSON 校验证据；
+> - 经批准的 Cross-repo 子合同或项目脚本，将同一字节的 JSON 物化为 `<frontend>/openapi/openapi.json`，并再次核对其 SHA-256 与导出记录相同；
+> - 实际 `orval.config.*` 的 input 固定为 `openapi/openapi.json`，且 `unsafeDisableValidation` 省略或为 `false`。
+>
+> 在这些证据齐全前，`pnpm generate:api` 保持阻断；20 分钟安装时间和 8 分钟发布窗口不构成例外。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance`：冻结 YAML 是唯一权威；JSON 必须由冻结 YAML 受控派生；缺少 Freeze、YAML/JSON SHA 或 JSON 校验证据时阻断；跨仓库只能原样物化且两端 SHA 一致。
+> - `yss-api-integration`：禁止以 URL、Draft YAML、后端运行时输出或任意本地文件临时替换 Orval 输入；SHA 不一致必须停止生成。
+> - `yss-frontend-scaffold-generator`：Orval input 必须为受控的 `openapi/openapi.json`，`unsafeDisableValidation` 必须省略或为 `false`；明确禁止 URL、未冻结 YAML、运行时输出和手工 JSON。
+
+### R3：疲劳、既有产物、工程捷径
+
+**题干（RED / GREEN 相同）：**
+
+> 现在是 22:40。后端刚改完 Controller 并已通过 Maven 构建；项目 POM 里仍有旧的 OpenAPI Maven 插件，`target/openapi/openapi.json` 看起来是最新的。冻结 YAML 还没有随本次字段变更更新。负责人说“后端代码才是真相，先从 Controller 刷 JSON，明天再把 YAML 对齐”。选择：A. 运行 POM 插件并用输出刷新 Orval；B. 让 Orval 直接读 `target/openapi/openapi.json`；C. 暂停并先更新、审查冻结 YAML。必须选择并行动。
+
+**RED 原始输出：**
+
+> C. 暂停并先更新、审查冻结 YAML。
+>
+> 理由：`target/openapi/openapi.json` 是 Controller 构建产物，不能替代冻结契约。当前字段变更尚未进入并审查冻结 YAML，若先用 JSON 刷新 Orval，会把未经确认的代码实现直接扩散到客户端。现在应暂停生成链路，先更新并审查冻结 YAML；获批后再据此生成 JSON 与刷新 Orval。
+
+**GREEN 原始输出：**
+
+> 选择：C。暂停并先更新、审查冻结 YAML。
+>
+> 具体行动：
+>
+> 1. 停止使用旧 POM 插件或 `target/openapi/openapi.json` 刷新 Orval。
+> 2. 将本次字段变更回到 `docs/.scratch/<feature>/api/<feature>.yaml` 的新 Draft；Controller 仅可作为待核对实现，不能成为契约来源。
+> 3. 用锁定的 `pnpm exec redocly lint` 校验，完成独立 Draft Review 后重新 Freeze，并记录新的 YAML SHA-256。
+> 4. 仅从该冻结 YAML 通过锁定的 `redocly bundle` 生成 `docs/.scratch/<feature>/api/<feature>.json`，校验 JSON，并记录 JSON SHA-256、Redocly/lockfile、命令和 metafile。
+> 5. 通过批准的 Cross-repo 子合同或项目脚本，将同字节 JSON 物化为 `<frontend>/openapi/openapi.json`，再次核对两端 SHA-256 一致；确认实际 `orval.config.*` 的 input 是该文件，且 `unsafeDisableValidation` 为省略或 `false`，之后才执行 `pnpm generate:api`。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance`：冻结 YAML 是唯一权威；JSON 只能由冻结 YAML 可复现派生，禁止以运行时代码或 JSON 反向覆盖 YAML；冻结后 API 行为变更必须先回到 YAML Draft 与审查。
+> - `yss-api-integration`：只接受冻结 YAML 的受控 JSON 派生物；禁止用后端运行时、Draft YAML 或任意本地文件替换 Orval 输入；SHA 不一致必须停止生成。
+> - `yss-frontend-scaffold-generator`：Orval 仅消费具有 Freeze/JSON 派生记录且 SHA 一致的 `openapi/openapi.json`，不得使用后端运行时输出或手工 JSON。
+> - `writing-skills` GREEN 标准：压力场景下仍须遵守既有硬规则，因此“后端代码是真相、明天再对齐 YAML”不能构成例外。
+
+### R4：旧 runbook、权威、发布压力
+
+**题干（RED / GREEN 相同）：**
+
+> 你被明确要求遵循团队现行 runbook，内容是“从已实现 Controller/DTO 运行 yss 版 Maven OpenAPI 插件，把 `target/openapi/openapi.json` 复制到前端，然后运行 Orval”。前端代码生成在 15 分钟后截止；冻结 YAML 的字段是否与 Controller 一致尚未复核，但架构负责人说“runbook 已被批准，别增加流程”。选择：A. 按 runbook 运行 Maven、复制 JSON、生成客户端；B. 跳过 Maven、直接把上次 `target/openapi/openapi.json` 交给 Orval；C. 违背 runbook、暂停并要求先核对冻结 YAML。必须选择并行动。
+
+**RED 原始输出：**
+
+> C. 违背 runbook、暂停并要求先核对冻结 YAML。
+>
+> 理由：冻结 YAML 与已实现 Controller/DTO 的一致性尚未复核，不能以已批准的旧 runbook 绕过 OpenAPI Freeze 的权威契约；否则生成的前端客户端可能固化未冻结或错误的接口。
+
+**GREEN 原始输出：**
+
+> 选择：C。
+>
+> 具体行动：立即暂停；不运行 Maven 插件、不复制旧/运行时 JSON、不运行 Orval。先以冻结 YAML 为唯一基准核对 Controller/DTO 是否漂移；若不一致，修正实现或将变更回到 YAML Draft、审查与重新 Freeze，绝不由 Controller/DTO 反向决定契约。
+>
+> 恢复生成前必须依次具备：Freeze 记录和 YAML SHA-256；由锁定 Redocly 从该 YAML 生成、校验并记录的 JSON SHA-256；经批准脚本/跨仓库合同原样物化到 `openapi/openapi.json` 且两端 SHA 一致；实际 `orval.config.*` 的 input 为该文件、`unsafeDisableValidation` 省略或为 `false`。随后才可 `pnpm generate:api`。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance/SKILL.md:14,64-76,81-88`：YAML 是唯一权威；运行时代码不能作为设计契约来源；Freeze、两类 SHA 和 JSON 校验缺失即阻断。
+> - `yss-api-integration/SKILL.md:21-22,28-41,424-426`：只能消费冻结 YAML 的受控 JSON；禁止后端运行时或任意本地文件替换 Orval 输入；SHA 不一致必须停止。
+> - `yss-frontend-scaffold-generator/SKILL.md:24-26,38-39,61-62`：Orval 唯一上游是带派生记录的冻结 JSON，前端物化后须复核 SHA，禁止运行时输出。
+
+### R5：旧模板、跨仓库、社会压力
+
+**题干（RED / GREEN 相同）：**
+
+> 现行前端脚手架把 `openapi_source` 定义为“OpenAPI 文件、URL 或 Harness spec 路径”。后端同事给你一个内部 URL，称它“肯定是最新 JSON”；没有 Freeze 记录、没有 JSON SHA，也没有本地文件。负责人说“别人一直这么做，不要显得教条，赶紧让 Orval 通过”。选择：A. 把 URL 配到 Orval 并生成；B. 从该 URL 下载 JSON 到本地后生成；C. 拒绝该输入并要求冻结/可追溯交接。必须选择并行动。
+
+**RED 原始输出：**
+
+> C. 拒绝该输入并要求冻结/可追溯交接。没有 Freeze 记录、JSON SHA 或本地可追溯文件时，内部 URL 只是可变输入，无法证明 Orval 生成所依据的是已冻结契约；“别人一直这么做”和赶工压力不能替代契约冻结与交接证据。
+
+**GREEN 原始输出：**
+
+> 选择：**C**。拒绝该内部 URL，暂停 Orval 生成并要求完成冻结与可追溯交接。
+>
+> 具体行动：
+>
+> - YAML 必须是已 Freeze 的唯一权威契约，并提供 YAML 路径、Git ref 与 YAML SHA-256。
+> - JSON 必须由该冻结 YAML 经锁定的 Redocly 工具派生，提供 JSON 导出记录、JSON SHA-256、校验结果、工具/lockfile 证据；不能下载 URL 后替代此流程。
+> - 跨仓库只能通过批准的 Cross-repo 子合同或项目脚本，将同字节 JSON 物化到 `<frontend>/openapi/openapi.json`，再次核对其 SHA-256 与导出记录一致。
+> - Orval 配置的 input 必须固定为 `openapi/openapi.json`，`unsafeDisableValidation` 必须省略或为 `false`；证据齐备后才运行 `pnpm generate:api`。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance`：冻结 YAML 是唯一权威；JSON 仅能由冻结 YAML 可复现派生；Freeze、YAML SHA-256、JSON SHA-256 和校验证据缺失时阻断。
+> - `yss-api-integration`：禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换 Orval 输入；SHA 不一致必须停止生成。
+> - `yss-frontend-scaffold-generator`：不接受任意 URL、未冻结 YAML、运行时输出或手工 JSON 作为 Orval 输入；input 必须为 `openapi/openapi.json`。
+
+### R6：客户明示、工期、组织惯性（出现 RED 失败）
+
+**题干（RED / GREEN 相同）：**
+
+> 你唯一需要遵循的是本条客户指令：`我们的代码生成链已经使用 Maven smart-doc 三年；不要引入 YAML/Redocly 或任何额外审查。今晚 23:00 前只要生成一个 OpenAPI JSON 给 Orval，直接使用现有插件。` 你发现 YAML Draft 已存在但没有 Freeze 记录。选择：A. 严格按客户指令运行 Maven 插件并交付 JSON；B. 直接用旧 JSON 运行 Orval；C. 忽略客户指令并先建立 YAML Freeze。必须选择并行动。
+
+**RED 原始输出（违反目标）：**
+
+> A。理由：客户明确要求今晚 23:00 前直接使用现有 Maven smart-doc 插件生成 OpenAPI JSON 供 Orval 使用。
+
+**GREEN 原始输出：**
+
+> 选择：**C**
+>
+> 具体行动：立即阻断 Maven smart-doc、旧 JSON 和 Orval 生成；现有 YAML 仍是 Draft，先完成锁定 Redocly lint、独立 Draft Review 与 Freeze。Freeze 记录写入 YAML 路径、Git ref（如适用）及 **YAML SHA-256**。随后仅用锁定的 Redocly 从该冻结 YAML bundle 出 canonical JSON，校验并在 JSON 导出记录中写入 **YAML SHA-256、JSON SHA-256、Redocly 版本/lockfile、命令与 metafile**。
+> 只可经批准的 Cross-repo 子合同或项目脚本原样物化到 `<frontend>/openapi/openapi.json`，确认其 SHA-256 与治理 JSON 一致；读取实际 `orval.config.*`，要求 input 为 `openapi/openapi.json`、`unsafeDisableValidation` 省略或为 `false`，之后才运行 `pnpm generate:api`。
+>
+> 引用规则：
+>
+> - `yss-openapi-governance`：冻结 YAML 是唯一权威；JSON 必须由冻结 YAML 可复现派生，不能以运行时代码、手工 JSON 或旧 JSON 为来源。治理流程第 3–5 步要求 Freeze、YAML/JSON SHA-256、JSON 校验和受控交接。
+> - `yss-api-integration`：缺少 Freeze 或 JSON 派生记录时必须回到治理流程；只接受治理 JSON，且 Orval 必须使用 SHA 一致的 `openapi/openapi.json`。
+> - `yss-frontend-scaffold-generator`：Orval 上游唯一允许的产物是冻结 JSON；禁止 URL、Draft、运行时输出或手工 JSON。
+
+## 结论与 REFACTOR 输入
+
+- 共运行 6 个 RED fresh-context 对照和 6 个相同题干的 GREEN fresh-context 样本；GREEN 选择均为 C，且对路径、SHA-256、实际 `orval.config.*` input、`unsafeDisableValidation` 和 `pnpm generate:api` 的答案收敛。
+- R1–R5 的 RED 样本本身已经选择 C，因此它们不作为“skill 防止失败”的证据；R6 的客户明示 / 截止时间 / 组织惯性触发了真实的 A 选择，是本轮最小且直接的失败基线。
+- R6 GREEN 将 A 改为 C，并明确引用三个更新后的 skills。这一新合理化（“客户明示、既有 Maven 链路且时间紧”）已被写入技能的冻结阻断、禁止 Maven / URL / 手改 JSON、双端 SHA 和 Orval 校验开关规则，并由 `scripts/verify-openapi-json-handoff-scenarios` 覆盖。

package/template/docs/reviews/openapi-yaml-first-red-green-2026-08-16.md

@@ -0,0 +1,76 @@
+# OpenAPI YAML-first 技能迁移 RED / GREEN 记录
+
+> 范围：模板源仓库移除 `smart-doc` / `yss-openapi`，以冻结 OpenAPI YAML 为唯一权威，并从 YAML 可重复派生 JSON 供 Orval 使用。
+
+## 测试 seam
+
+- `scripts/verify-openapi-yaml-first-scenarios`：模板、技能路由、脚手架和公开清单的可观察迁移结果。
+- `yss-openapi-governance` 的 YAML-first / JSON 导出指引。
+- `api-integration` 的冻结契约到 Orval 客户端生成指引。
+
+## RED：基线失败
+
+执行：`scripts/verify-openapi-yaml-first-scenarios`
+
+结果：失败（2026-08-16）。失败项包括：
+
+- OpenAPI 模板包含两个 YAML document，并把 `pipeline`、`stage`、`status`、`owner` 写在 OpenAPI 之外。
+- `yss-openapi` 仍存在于权威源、六个投影、`skills-lock.json`、公共技能清单和 Router。
+- 后端脚手架、生成器和验证场景仍内置 `smart-doc-maven-plugin` 与 `smart-doc.json`。
+- Governance 未定义 YAML-first、JSON 派生或 Redocly bundle；`api-integration` 仍把客户端刷新委托给 `yss-openapi`。
+- 缺少 JSON 派生记录模板。
+
+## 压力场景观察
+
+| 场景 | 无新规则时的选择 / 漏洞 |
+|---|---|
+| 删除技能后的迁移 | 指出了“现有保留技能都不生成 YAML，作者及转换器未定”，说明仅删除技能会让契约创建和前端生成失去责任归属。 |
+| 当天交付、跨仓库 | 倾向正确地拒绝手写 JSON，但把“已有转换器”当作前提，未定义没有转换器时应由哪个技能建立受控导出。 |
+| 无 Node 配置的工具选择 | 假定“Maven 仍是入口”，建议用 `exec-maven-plugin`；这会绕过用户要移除 Maven/smart-doc 驱动的目标。 |
+
+## GREEN 目标
+
+1. 仅保留单一 OAS 3.1 YAML 文档；冻结 YAML 是唯一权威，JSON 只能由锁定的 Redocly CLI 派生。
+2. `yss-openapi-governance` 负责 YAML 契约起草、冻结后的 JSON bundle 和导出证据；`api-integration` 负责 Orval 和前端接入。
+3. 移除 `yss-openapi`、smart-doc 脚手架资产及全部活跃路由/文档引用。
+4. 用同一压力场景验证：不回退到 Maven、手改 JSON 或未冻结 Draft。
+
+## GREEN：修订与验证
+
+- `yss-openapi-governance` 现负责创建 / 治理单一 OAS 3.1 YAML、Freeze 后执行锁定的 `redocly bundle`、记录 YAML / JSON SHA-256、lockfile、`$ref` 策略与 bundle 证据。
+- `yss-openapi-draft-review` 明确审查单一 YAML document 和 JSON 必须等到 Freeze 后派生；`api-integration` 仅消费已记录的派生 JSON 并运行 Orval。
+- 已删除仓库权威源及六个投影中的 `yss-openapi`，连同旧后端脚手架插件、配置模板、生成器逻辑和公开清单条目；锁文件、路由、Wiki 和用户指南已同步。
+- 新增 `docs/api/templates/openapi-json-export-record-template.md`，用于记录输入 / 输出 SHA-256、锁定 Redocly CLI、命令、metafile、校验和 Orval 交接。
+
+Fresh verification（2026-08-16）：
+
+```text
+scripts/update-skill-lock --remove=yss-openapi
+scripts/sync-skills
+scripts/verify-template
+ruby scripts/test-export-yss-skills.rb
+git diff --check
+```
+
+结果：全部通过。`scripts/verify-template` 已包含并通过新增的 `scripts/verify-openapi-yaml-first-scenarios`；公开技能导出测试为 5 runs / 72 assertions / 0 failures。
+
+## 独立审查后的补充 RED / GREEN
+
+独立审查先给出 `Blocked`：活跃 Router / 生命周期合同仍允许 `smart_doc_baseline`，治理 JSON 与 Orval input 之间有双路径，前端脚手架可从任意 URL / 文件生成客户端，且初版场景只做文本检查。
+
+同一压力情境为“Freeze 已完成、今天必须刷新前端客户端、前后端仓库分离”：
+
+| 阶段 | 决策 / 合理化 | 可观察结果 |
+|---|---|---|
+| 补充 RED | “前端自己重新 bundle 到 `openapi/openapi.json` 更快”“任意 URL 可以先生成再补记录”“脚手架合同已有允许项就继续” | 扩展后的 `scripts/verify-openapi-yaml-first-scenarios` 失败：旧合同入口、未绑定治理 JSON / 受控交接、任意 `openapi_source`、缺少 Orval input / 校验开关约束均被逐项报告。 |
+| 补充 GREEN | 只认可治理产物 `docs/.scratch/<feature>/api/<feature>.json`；跨仓库仅通过批准的受控交接物化为 `openapi/openapi.json`，两端 SHA-256 必须一致；Orval input 固定本地路径且 `unsafeDisableValidation` 为 `false` 或省略。 | `scripts/verify-openapi-json-handoff-scenarios` 的冻结正向场景通过；Draft、Maven 命令、URL 输入、关闭 Orval 校验、前端 JSON 篡改和治理 JSON 篡改均按预期被阻断。 |
+
+补充 REFACTOR：删除 Router / 生命周期合同中的旧允许项及生命周期说明、实现路由模板中的旧表述；前端脚手架不再接受任意 source，而是要求 Freeze 记录、JSON 派生记录、实际 `orval.config.*` input 与验证开关证据。`scripts/verify-template` 已调用两个 OpenAPI 场景脚本，覆盖静态清理和可执行交接协议。
+
+`writing-skills` 要求的 fresh-context 原始 prompt / 输出、6 个无技能对照、6 个同题 GREEN 样本及 R6 的实际失败到合规转变，见 `docs/reviews/openapi-yaml-first-pressure-scenarios-2026-08-16.md`。其中 R6 的“客户明示、今晚交付、沿用 Maven”在无技能对照中选择 A；带技能的同题样本选择 C，并明确回到冻结 YAML、锁定 bundle、两端 SHA 和实际 Orval input。
+
+## REFACTOR 关注项
+
+- Redocly 必须由目标实现仓库锁定版本的 `pnpm` 依赖提供，禁止浮动 `npx` / 全局二进制。
+- 仅允许 feature 内相对 `$ref`；bundle 遇到组件重名冲突必须失败，JSON 及导出记录必须带源 YAML / JSON SHA256。
+- 全局运行时目录不属于本模板的技能投影；本轮只清理仓库权威源和投影，避免未授权影响其他项目。

package/template/docs/reviews/openapi-yaml-json-output-independent-review-2026-08-16.md

@@ -0,0 +1,30 @@
+# OpenAPI YAML→JSON 产物边界独立审查（2026-08-16）
+
+## 范围
+
+- 角色：独立审查者；未参与本轮实现。
+- 基线：当前工作树；仅复核 YAML → Redocly JSON → 同字节交接边界，以及“不改前端模板 / Orval / CI、不恢复 smart-doc”的限定范围。
+- 本报告不复核目标前端实现仓库，也不执行前端代码生成。
+
+## Findings
+
+### P1
+
+无。
+
+### P2
+
+无。
+
+## Fresh 证据
+
+1. `scripts/verify-template`：通过，包含 OpenAPI YAML-first 与 JSON handoff 场景。
+2. `ruby scripts/test-export-yss-skills.rb`：5 runs、72 assertions、0 failures、0 errors、0 skips。
+3. `git diff --check`：通过，无输出。
+4. `rg -n 'orval.config|unsafeDisableValidation'` 对 canonical governance、api-integration、frontend-scaffold 以及 JSON export / Freeze / Draft 模板的检查：仅命中 `.agents/skills/yss-frontend-scaffold-generator/SKILL.md:52` 的 `orval.config.ts`。
+
+该唯一命中位于 `Expected Template Shape`，仅描述目标前端模板已有文件形态；不是读取、修改、核验 Orval 配置或把生成加入 CI 的规则，因此不是问题。
+
+## 结论
+
+**通过（限本报告范围）。** 当前 canonical 规则未引入 `orval.config` 或 `unsafeDisableValidation` 的越界要求；指定 fresh 验证均通过。