create-yss-spec 2.1.3 → 2.1.5

package/README.md

@@ -33,7 +33,7 @@ npx create-yss-spec@latest
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
 
-本次新增能力按 `2.1.3` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次新增能力按 `2.1.4` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/template/.agents/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/.agents/skills/high-fidelity-html-prototype/SKILL.md

@@ -5,6 +5,10 @@ description: Use after low-fidelity prototype review is approved and before Spec
 
 # High Fidelity HTML Prototype
 
+## 兼容入口
+
+本 skill 仅服务旧名称或既有链接；新的高保真产出遵循 `yss-prototype-stage`，在 Codex 由 `product-design:index` 路由。它不批准生命周期门禁或实现就绪状态。
+
 Use this skill only after `prototype-review` approves the low-fidelity prototype / interaction design. It turns reviewed product design into a high-fidelity, browser-runnable HTML artifact for business, UX, frontend, and API review.
 
 ## Required Inputs
@@ -16,33 +20,33 @@ Use this skill only after `prototype-review` approves the low-fidelity prototype
 - Approved low-fidelity prototype review: `docs/.scratch/<feature>/design/<feature>-prototype-review.md` or equivalent issue comment.
 - Project design system: `docs/design/design.md` and `docs/design/tokens/*`.
 
-If low-fidelity `prototype-review` is blocked or missing, stop and return to `product-design-prototype` / `prototype-review`.
+If low-fidelity `prototype-review` is blocked or missing, stop and return to `yss-prototype-stage` / `prototype-review`.
 
 ## Ant Design Official Agent Baseline
 
-Use the official Ant Design agent guidance as the implementation baseline:
+Use the official Ant Design agent guidance as the fact baseline through `yss-prototype-stage`:
 
 - Read or reference `https://ant.design/docs/react/for-agents` when the task starts.
 - Use `@ant-design/cli` before choosing unfamiliar components, props, tokens, or migration-sensitive APIs.
 - Prefer direct CLI subcommands because `--help` may fail in some Node environments while subcommands still work.
 
-Recommended commands:
+Record the installed CLI version and the target AntD version in `prototype-evidence.yaml`. Use `--format json`; pass the recorded target version to version-sensitive queries:
 
 ```bash
-npm view antd version
-npm view @ant-design/cli version
-npx -y @ant-design/cli@6.5.0 info Button
-npx -y @ant-design/cli@6.5.0 token Button
-npx -y @ant-design/cli@6.5.0 demo Select basic
-npx -y @ant-design/cli@6.5.0 changelog 5.0.0 6.5.0 Table
+antd design.md --format json
+antd info Button --version <target_antd_version> --format json
+antd token Button --version <target_antd_version> --format json
+antd demo Select basic --version <target_antd_version> --format json
+antd semantic Button --version <target_antd_version> --format json
+antd lint <prototype-path> --format json
 ```
 
-Use the latest verified v6.x version instead of `6.5.0` when npm reports a newer v6 release. Record the exact version and any queried components in the output.
+Use the project-selected version when one exists; otherwise record the CLI's actual default version before making version-sensitive decisions. Record every queried component in the evidence manifest.
 
 ## Core Rules
 
 - Output is HTML: `docs/.scratch/<feature>/design/prototypes/index.html`.
-- The prototype must use Ant Design v6. Before generating or updating code, verify the current v6 package with `npm view antd version` and `npm view @ant-design/cli version`. If the latest version is not v6.x, pin the newest available v6.x version and record the choice.
+- The prototype must use the approved Ant Design v6 target. Obtain component facts from the official `antd` CLI and record the exact CLI/target versions; do not infer version-sensitive APIs from memory.
 - Use React >= 18, `antd@6.x`, and `@ant-design/icons@6.x` for interactive prototypes.
 - Prefer Ant Design components and tokens over hand-built controls: `Layout`, `Menu`, `Breadcrumb`, `Button`, `Input`, `Select`, `Table`, `Form`, `Tabs`, `Steps`, `Drawer`, `Modal`, `Alert`, `Tooltip`, `Tag`, `Badge`, `DatePicker`, `Upload`, `Pagination`, `Empty`, `Spin`, `Result`.
 - Do not create extra data-service or fixture artifacts. Use embedded sample data inside the HTML/JS for visual and interaction demonstration only.
@@ -71,7 +75,7 @@ Run a local browser verification before calling the artifact ready:
 - Check that the page renders nonblank.
 - Exercise the main flow and at least one failure / permission / conflict state.
 - Check at least one desktop and one mobile viewport.
-- Record verification evidence in the response or in the related review / issue.
+- Record verification evidence in `docs/.scratch/<feature>/verification/prototype-evidence.yaml` and link it from the review and confirmation record.
 
 ## Output Contract
 

package/template/.agents/skills/product-design-prototype/SKILL.md

@@ -5,7 +5,11 @@ description: Use when a Spec baseline or user story has UI impact and needs page
 
 # Product Design Prototype
 
-Use this skill after Spec baseline and before Spec calibration / OpenAPI Draft for features with user interfaces. Its job is to turn requirements into design assets that can drive a calibrated Spec, API, frontend acceptance, and vertical slices.
+## 兼容入口
+
+本 skill 仅服务旧名称或既有链接；它不是新的原型主入口。进入后先加载 `yss-prototype-stage`，并在 Codex 使用 `product-design:index` 产出设计资产。生命周期门禁仍由 `yss-product-lifecycle` 裁决。
+
+其余内容只描述可复用的交互说明检查项，不能替代统一合同中的 AntD CLI、浏览器验证或用户确认。
 
 ## Required Inputs
 
@@ -25,7 +29,7 @@ If no Spec baseline exists, route back to `yss-product-lifecycle` / `grill-with-
 5. Write the OpenAPI implication list: fields, filters, actions, errors, permissions, pagination, optimistic/concurrency states, and audit/version data.
 6. For every primary page action, add an action-to-contract row: page/component, action label, `actionKey`, endpoint or explicit non-goal, request fields, response shape, permission behavior, state transition, idempotency/concurrency rule, and error codes.
 7. For every P0 requirement containing verbs such as manage, maintain, configure, create, update, archive, retry, cancel, publish, export, or create draft, confirm the interaction spec either names the API implication or records that the capability is intentionally out of scope.
-8. Hand off to `prototype-review`. After low-fidelity review is approved, hand off to `high-fidelity-html-prototype`. Do not freeze/calibrate the Spec or enter OpenAPI Draft for UI work until the Ant Design v6 high-fidelity HTML prototype exists and has no blocking findings.
+8. Hand off to `prototype-review`. After approval, return to `yss-prototype-stage` for `product-design:index` 高保真产出、AntD CLI 与浏览器验证；未形成确认记录前不得冻结/校准 Spec 或进入 OpenAPI Draft。
 9. 交互原型应标注 semantic token 角色、single primary action、interaction feedback 和不可逆操作确认；若页面使用 Ant Design，主题密度或暗色策略必须使用 theme algorithm，并在关键文本上复核 accessibility contrast。
 
 ## Tool Routing

package/template/.agents/skills/prototype-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when reviewing low-fidelity UI design, wireframes, prototype li
 
 # Prototype Review
 
-Use this skill as the low-fidelity gate between product design/prototype work and high-fidelity HTML prototype work. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design.
+Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `gate.prototype-reviewed` decision.
 
 ## Trigger Boundary
 
@@ -17,6 +17,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
 - State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending evidence record, but CLI/browser validation belongs to the following high-fidelity verification gate.
 
 ## Review Gates
 
@@ -63,8 +64,11 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 ### Frontend Prototype Readiness
 - <component states, data dependencies, frontend acceptance notes>
 
+### Lifecycle Evidence
+- <persistent review path; blockers; `gate.prototype-reviewed` candidate result>
+
 ### Next Action
-- <high-fidelity-html-prototype / return to product-design-prototype>
+- <yss-prototype-stage / return to product design>
 ```
 
 Use `docs/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.

package/template/.agents/skills/wireframe-prototype/SKILL.md

@@ -5,6 +5,10 @@ description: Use when low-fidelity product screens, user flows, whiteboards, Exc
 
 # Wireframe Prototype
 
+## 兼容入口
+
+本 skill 仅服务旧名称或既有链接；新的低保真产出遵循 `yss-prototype-stage`，在 Codex 由 `product-design:index` 路由。它不批准产品设计门禁。
+
 Use this skill for low-fidelity product decisions. It favors fast, inspectable artifacts over polished visuals.
 
 ## Choose The Medium
@@ -49,4 +53,4 @@ Then link or paste this into `docs/.scratch/<feature>/design/<feature>-interacti
 
 ## Handoff
 
-After the wireframe is captured, return to `product-design-prototype` to fill state matrix and API implications, then run `prototype-review`.
+After the wireframe is captured, return to `yss-prototype-stage` to fill the interaction spec, state matrix, API implications, and then run `prototype-review`.

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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`。