create-yss-spec 2.1.2 → 2.1.4

package/template/.hermes/skills/yss-router/references/slice-implementation-contract.md

@@ -107,4 +107,4 @@ work_unit:
     behavior_tests_after_generation: []
 ```
 
-`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。
+`controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。

package/template/.hermes/skills/yss-router/references/yss-skill-execution-result.md

@@ -33,6 +33,7 @@ execution_result:
       owner:
       follow_up_ticket:
       verification_plan:
+      target_version_or_release_date:
   deviations:
     - rule:
       reason:
@@ -51,7 +52,7 @@ Router 必须验证：
 2. `changed_files` 全部位于工作单元和切片允许路径内。
 3. `expected_evidence_files` 全部存在并能回指行为。
 4. 验证命令包含实际结果和时间；计划命令不算证据。
-5. `seam_deferred` 有风险、责任人、补齐 Ticket 和验证计划。
+5. `seam_deferred` 有风险、责任人、补齐 Ticket、验证计划和目标版本 / 发布日期。
 6. `new_impacts` 非空时暂停并重路由。
 7. `drift` 触发 Architecture Re-check；`violation` 阻断 build。
 8. `status: not-applicable` 必须填写 `not_applicable_reason`；其他状态保留字段但可为空。

package/template/.pi/skills/code-review/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+Two-axis review of a pinned candidate against a fixed point:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
@@ -14,20 +14,46 @@ The issue tracker should have been provided to you — run `/setup-matt-pocock-s
 
 ## Process
 
-### 1. Pin the fixed point
+### 1. Pin the fixed point and candidate
 
 Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
 
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+Choose one candidate mode from the request or an upstream review contract:
 
-Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
+- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
+  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
+  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
+  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
+  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
+
+Record one **candidate manifest** before spawning reviewers:
+
+```yaml
+review_mode: committed # or worktree
+review_base_ref: <fixed-point>
+merge_base: <resolved-sha>
+implementation_candidate_ref: HEAD # or working-tree
+candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
+candidate_digest: <sha256-or-immutable-tree-id>
+tracked_diff_command: <command>
+untracked_inventory_command: <command-or-null>
+untracked_files: []
+commit_list_command: <command>
+```
+
+For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
+
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to both reviewers. The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. The immutable snapshot stores `candidate-manifest.yaml`, `tracked.diff` and the `untracked/` bytes under the digest identity; both reviewers must consume those captured bytes and must not independently reread a live worktree.
+
+Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not inside two parallel sub-agents. Do not silently downgrade Worktree review to `HEAD`-only review.
 
 ### 2. Identify the spec source
 
 Look for the originating spec, in this order:
 
-1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
-2. A path the user passed as an argument.
+1. A spec/Ticket/contract reference supplied by the user or an upstream lifecycle review input.
+2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
 3. A spec file under `docs/`, `specs/`, or `docs/.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
 
@@ -59,13 +85,13 @@ Each smell reads *what it is* → *how to fix*; match it against the diff:
 
 **Standards sub-agent prompt** — include:
 
-- The full diff command and commit list.
+- The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.
 - The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
 - The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
 
 **Spec sub-agent prompt** — include:
 
-- The diff command and commit list.
+- The same candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list.
 - The path or fetched contents of the spec.
 - The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
 
@@ -75,7 +101,9 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
 
-End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
+
+State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
 ## Why two axes
 

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/skills/yss-design-system/SKILL.md

@@ -84,7 +84,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | 表单 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/.pi/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/.pi/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.