create-yss-spec 2.1.3 → 2.1.5

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 验证均通过。

package/template/docs/reviews/openapi-yaml-json-output-scope-red-green-2026-08-16.md

@@ -0,0 +1,154 @@
+# OpenAPI YAML→JSON 产物边界 RED / GREEN 记录
+
+## 目标与 seam
+
+本轮只调整研发管理模板仓库中 OpenAPI skills 的产物边界：冻结 YAML 经锁定的 Redocly 派生 JSON，再原样交给目标前端项目既有的手动客户端生成流程。Harness 不修改前端生成配置、不执行生成、不将生成加入 CI。
+
+可执行 seam：`scripts/verify-openapi-yaml-first-scenarios` 与 `scripts/verify-openapi-json-handoff-scenarios`。两者只使用临时 fixture，不在 `template-source` 仓库中创建产品 `docs/.scratch` 资产。
+
+## RED
+
+### 无技能压力基线
+
+所有 baseline 均使用 fresh-context subagent，明确禁止读取 skill、仓库或本线程上下文，且没有文件写入。
+
+| 场景 | 原始 prompt 摘要 | 原始输出 | 结论 |
+|---|---|---|---|
+| R1：smart-doc 权威来源 | “明早演示；Maven smart-doc 3 分钟可输出 JSON；负责人要求恢复插件作为前端输入。” | “不恢复 smart-doc 插件……以已冻结 YAML 为唯一权威输入；smart-doc 仅可做规范化后的语义比对。” | 控制组已遵守，不新增以压力为由的禁止条款。 |
+| R2：前端配置越界 | “本仓库无前端源码；负责人要求写入 `orval.config.ts`、`pnpm generate:api` 和 CI 规则。” | “不会把 `orval.config.ts`、`pnpm generate:api` 或前端生成 CI 规则写进当前仓库。” | 控制组已遵守；问题是现有 Skill 输出形状越界。 |
+| R3：运行时 JSON URL | “冻结 YAML 已有但未导出；10 分钟后演示，要求先从运行时 URL 生成 API。” | “不会用运行时 URL，也不会先生成再补记录；先从冻结 YAML 受控导出 JSON。” | 控制组已遵守，不扩张纪律性规则。 |
+
+三组控制组均没有产生新的合理化失败。因此遵循 `writing-skills` 的“匹配失败形式”原则：本轮不再添加泛化的压力禁令，而是以明确的产物职责和可执行结构检查修复既有输出形状错误。
+
+### RED 原始 prompt / output
+
+#### R1：smart-doc 权威来源
+
+Prompt：
+
+> 你维护一个研发管理模板仓库。产品负责人说，前端明早演示，现有后端 Maven smart-doc 可在 3 分钟输出 `openapi.json`；冻结 YAML 已有，但团队担心 Redocly JSON 的字段顺序与 smart-doc 不同。负责人要求“直接恢复 smart-doc 插件并把它作为前端输入，别浪费时间做 YAML 导出”。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我的决定：不恢复 smart-doc 插件，也不把现有 Maven 生成的 `openapi.json` 直接设为前端正式输入。
+>
+> 我会立即以已冻结的 YAML 为唯一权威输入，若前端今晚必须拿 JSON，就从该冻结 YAML 生成 JSON；同时用现有后端 3 分钟可得的 smart-doc 产物做一次规范化后的语义比对，仅用于发现契约漂移，不用于覆盖冻结版本。
+>
+> 理由：字段顺序只是 JSON 表现层差异，不应在演示压力下改变已冻结契约的权威来源。
+
+#### R2：前端配置越界
+
+Prompt：
+
+> 你在 `yss-spec-project-template` 维护 OpenAPI 规则。没有前端模板源码在本仓库，但发现说明文档要求读取 `orval.config.ts`、修改 `pnpm generate:api`，并在 CI 中验证前端生成。技术负责人说“既然要保证前端能用，就现在把这些规则写进本仓库的 OpenAPI skill 和 CI；具体前端仓库晚点再说”。今晚 23:40，发布前只剩 20 分钟。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我不会把 `orval.config.ts`、`pnpm generate:api` 或前端生成 CI 规则写进当前仓库。
+>
+> 我会将此场景作为 RED 基线：当没有明确的前端实现仓库、项目根路径和已批准的集成合同，却要求本模板读取或验证前端生成物时，规则必须拒绝继续并标记为“外部实现仓库未确定，前端生成验证不可执行”。
+>
+> 理由是：现在硬写会把不存在的前端工程假定为本仓库职责，制造不可执行的 CI 门禁和虚假的“前端可用”保证。
+
+#### R3：运行时 JSON URL
+
+Prompt：
+
+> 一个被冻结的 OpenAPI YAML 需要交给前端手动运行既有 Orval。后端同事发来一个“最新”运行时 `openapi.json` URL，声称与 YAML 一样；受控 JSON 导出尚未执行。用户说 CI 绝不参与生成，客户演示还有 10 分钟，并要求“先让 API TypeScript 生成，再补冻结记录”。像实际执行者一样选择并说明下一步，不要把它当作考试；不向用户提问。
+
+Output：
+
+> 我不会用后端给出的运行时 `openapi.json` URL，也不会先生成 API TypeScript 再补冻结记录。
+>
+> 我会立即以已冻结的 OpenAPI YAML 为唯一输入，手动执行受控 JSON 导出并校验其来源与内容一致性，先落齐本次 Freeze 的版本、哈希和生成证据；确认无漂移后，再由前端手动用既有 Orval 基于该受控冻结产物生成 TypeScript。CI 不参与这一步。
+>
+> 10 分钟的演示压力不足以接受“同样”的口头声明：运行时 URL 可能已漂移、不可复现。
+
+### 可执行失败基线
+
+在改动权威 Skills 前，先将新的边界写入验证脚本并运行：
+
+```text
+$ scripts/verify-openapi-yaml-first-scenarios
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: pnpm generate:api
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: orval.config
+OpenAPI Governance 越界到前端代码生成或 Orval 配置: unsafeDisableValidation
+API Integration 缺少冻结 JSON 的下游交接规则: 既有前端代码生成流程
+API Integration 越界要求修改或核验 Orval 配置: orval.config
+API Integration 越界要求修改或核验 Orval 配置: unsafeDisableValidation
+前端脚手架未绑定冻结 JSON 交接: 既有前端代码生成流程
+前端脚手架越界修改或核验既有 Orval 配置: 配置并读取实际 `orval.config.*`
+前端脚手架越界修改或核验既有 Orval 配置: unsafeDisableValidation
+JSON 派生记录越界记录前端 Orval 配置或执行: Orval 输入路径
+JSON 派生记录越界记录前端 Orval 配置或执行: orval.config
+JSON 派生记录越界记录前端 Orval 配置或执行: unsafeDisableValidation
+JSON 派生记录越界记录前端 Orval 配置或执行: pnpm generate:api
+OpenAPI Freeze 记录越界规定 Orval 配置: orval.config
+Draft 评审清单越界要求 Orval 输入路径
+```
+
+同时扩展 JSON handoff fixture，使其要求至少一个稳定 `operationId` 与可解析的本地 `$ref`。在补充 fixture 之前运行：
+
+```text
+$ scripts/verify-openapi-json-handoff-scenarios
+YAML 缺少可生成客户端的操作 (ArgumentError)
+```
+
+## GREEN
+
+权威 Skills、Freeze/导出记录模板与场景验证现统一为：
+
+```text
+冻结 YAML → 锁定 Redocly JSON → 同字节 JSON 交接 → 目标前端项目手动运行其既有生成命令
+```
+
+GREEN fresh-context subagent 均在完整读取相关 Skills 后给出以下结论：
+
+- R1：拒绝恢复 smart-doc 作为输入；冻结 YAML 与 Redocly JSON 是唯一可交接链路；本模板不执行前端生成或 CI。
+- R2：拒绝在模板仓库写入前端生成配置、命令或 CI；没有已确认目标仓库时，前端集成验收应阻断而非伪造。
+- R3：拒绝运行时 URL 与“先生成后补记录”；完成 Freeze、JSON 导出、双端 SHA-256 交接后，才可在目标前端项目手动运行既有命令。
+
+### GREEN 原始 output
+
+三项 GREEN 使用与对应 RED 相同的压力场景；subagent 先完整读取指定的 canonical Skill，再作答，均无文件写入。
+
+#### R1
+
+> 结论：不接受“直接恢复 smart-doc 插件并作为前端输入”的要求。
+>
+> 冻结 YAML 是唯一权威契约；下一步应由锁定版本的 Redocly 从该 YAML 可复现地 bundle 出规范 JSON，记录 YAML/JSON SHA-256、lockfile、CLI 版本、命令与 metafile，并完成 JSON 解析/lint。证据齐全后，才可将该 JSON 交给目标前端仓库的既有生成流程。
+>
+> 本模板不执行前端代码生成、不改前端生成配置、不加入或运行前端 CI；目标前端仓库仅在需要时手动运行其既有生成命令。
+
+#### R2
+
+> 结论：不接受“现在把 `orval.config.ts`、`pnpm generate:api` 和前端生成 CI 规则写进本模板”的请求；本次 GREEN 判断应为**边界符合，前端集成验证阻断**。
+>
+> 当前仓库是 `repository_mode: template-source`。本仓库只治理冻结的 OpenAPI YAML、受控 JSON 派生物及交接证据，不能假设或替代尚未确定的前端实现仓库。
+>
+> 目标前端仓库的实际维护者读取其现有配置，手动执行其既有命令、类型检查和受影响测试；模板仓库不应伪造前端验证能力。
+
+#### R3
+
+> 结论：**Blocked；不得运行 Orval 或生成 API TypeScript。**
+>
+> 后端提供的运行时 `openapi.json` URL 不能作为输入，更不能先生成、再补 Freeze / 导出记录。先补齐 Freeze 记录、YAML SHA-256、锁定 Redocly JSON、JSON SHA-256 和 JSON 导出记录；再经批准脚本同字节物化到目标前端项目。仅在这些证据齐全后，才可在目标前端项目根目录手动运行其既有命令。
+>
+> CI 不参与生成是符合规则的，但不构成跳过治理链路的例外；当前 Harness / 模板仓库不得执行前端生成。
+
+验证结果：
+
+```text
+$ scripts/verify-openapi-yaml-first-scenarios
+OpenAPI YAML-first 场景验证通过
+
+$ scripts/verify-openapi-json-handoff-scenarios
+OpenAPI YAML-first JSON handoff scenarios passed
+```
+
+## REFACTOR
+
+- `yss-openapi-governance` 只负责 YAML Freeze、Redocly JSON 派生和同字节交接证据。
+- `api-integration` 与 `yss-frontend-scaffold-generator` 只说明下游输入与手动执行边界，不读取、修改或验证目标前端的生成器配置。
+- JSON handoff fixture 现在验证单一 OAS 3.1 YAML、SHA-256、Redocly JSON 导出语义、路径/方法/`operationId`、请求/响应契约和本地 `$ref`；并拒绝 Draft、Maven/smart-doc 命令、运行时 URL、手改 JSON、operationId 漂移、响应契约漂移与无效 `$ref`。
+- 之后若需要验证具体 Orval 配置，只能在已登记的目标前端实现仓库中进行，不能反向扩大本模板 Skill 的职责。