create-yss-spec 2.1.3 → 2.1.5

package/template/.hermes/skills/yss-router/SKILL.md

@@ -30,7 +30,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。
 - 后端端到端切片必须包含 Application；对象/POJO 影响按契约自动补 `mapstruct`、`lombok`、`alibaba-java-code-style`。
 - Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
-- 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。
+- 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
 - 原型确认后若 backend `scaffold_status=required`，先由本 Router 按 `scaffold_contract_schema` 编译 `yss-ddd-scaffold-generator` 的 `controlled-generation` 工作单元合同 draft；合同必须带 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据和验证命令。经生命周期编排器批准并持久化后才能运行生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后加载 `yss-backend-scaffold-parent` 并重新编译业务合同；脚手架不承载业务行为。
 - 脚手架合同在 Router 阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和 Router 重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
@@ -42,7 +42,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 
 - 切片基线路由：生成完整合同和技能闭包。
 - 工作单元增量路由：绑定一个行为、主/辅 skills、TDD 模式、路径和证据。
-- 完整重路由：API/schema、权限、状态机、数据模型、仓库、写路径、skill、测试 seam 或架构约束发生实质变化时触发。
+- 完整重路由：API/schema、状态机、数据模型、仓库、写路径、skill、测试 seam 或架构约束发生实质变化时触发。实现中出现未冻结的新行为（包括明确的权限业务行为）统一写入 `new_impacts`，由生命周期按普通影响面重新分诊。
 
 ## 输出
 

package/template/.hermes/skills/yss-router/references/router-contract.yaml

@@ -20,7 +20,7 @@ subcontract_statuses: [required, not-applicable]
 
 readiness:
   common: [spec, slice_ticket, architecture_review, build_architecture_checklist, implementation_repository, verification_commands]
-  ui_impact: [requirement_freeze, low_fidelity_review, high_fidelity_html, antd_cli_evidence, prototype_confirmation]
+  ui_impact: [requirement_freeze, low_fidelity_review, prototype_review, high_fidelity_html, prototype_verification, antd_cli_evidence, browser_verification_evidence, prototype_confirmation]
   api_impact: [openapi_freeze]
   no_api_impact: [no_api_impact_record]
   data_impact: [data_architecture]
@@ -33,13 +33,13 @@ routing_input_required:
   - lifecycle
   - implementation
   - acceptance
-impact_flags_required: [ui_impact, api_impact, no_api_impact, data_impact, backend_impact, cross_repo]
+impact_flags_required: [ui_impact, api_impact, no_api_impact, data_impact, backend_impact, cross_repo, existing_frozen_baseline]
 exclusive_flags:
   - [api_impact, no_api_impact]
 
 slice_contract_required:
   root: [schema_version, contract_id, contract_version, slice_id, status, lifecycle_refs, readiness, common, frontend, backend, contract, cross_repo, work_units]
-  lifecycle_refs: [spec, ticket, requirement_freeze, low_fidelity_review, high_fidelity_html, antd_cli_evidence, prototype_confirmation, openapi_freeze_or_no_impact, architecture_review, data_architecture, engineering_baseline, build_architecture_checklist, implementation_repository, frontend_repository, backend_repository, maven_wrapper]
+  lifecycle_refs: [spec, ticket, requirement_freeze, low_fidelity_review, prototype_review, high_fidelity_html, prototype_verification, antd_cli_evidence, browser_verification_evidence, prototype_confirmation, openapi_freeze_or_no_impact, architecture_review, data_architecture, engineering_baseline, build_architecture_checklist, implementation_repository, frontend_repository, backend_repository, maven_wrapper]
   readiness: [blockers, stale_inputs, not_applicable]
   common: [impacted_areas, implementation_path_policy, project_roots, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers]
   frontend: [status, required_skills, approved_prototype_ref, state_matrix_ref, allowed_write_paths, component_test_seams, e2e_paths]
@@ -55,8 +55,11 @@ lifecycle_ref_by_readiness:
   implementation_repository: implementation_repository
   requirement_freeze: requirement_freeze
   low_fidelity_review: low_fidelity_review
+  prototype_review: prototype_review
   high_fidelity_html: high_fidelity_html
+  prototype_verification: prototype_verification
   antd_cli_evidence: antd_cli_evidence
+  browser_verification_evidence: browser_verification_evidence
   prototype_confirmation: prototype_confirmation
   openapi_freeze: openapi_freeze_or_no_impact
   no_api_impact_record: openapi_freeze_or_no_impact
@@ -91,7 +94,7 @@ scaffold_contract_schema:
   work_unit:
     required: [id, behavior, primary_skill, supporting_skills, tdd_mode, allowed_write_paths, expected_evidence, verification_commands, controlled_generation]
   generation_boundary:
-    allowed_for: [project_scaffold, pom, mechanical_config, wrapper, smart_doc_baseline]
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper]
     forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
   verification:
     commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
@@ -147,7 +150,7 @@ dependency_closure:
     when_form: [yss-formily]
     when_api: [api-integration]
   api-integration:
-    when_regeneration: [yss-openapi]
+    when_regeneration: [yss-openapi-governance]
 
 component_impact_values:
   - current-user-context
@@ -191,7 +194,6 @@ full_reroute_triggers:
   - scaffold-baseline-drift
   - api-schema-impact
   - database-schema-impact
-  - permission-impact
   - state-machine-impact
   - data-model-impact
   - new-write-path
@@ -209,7 +211,6 @@ reroute_destinations:
   scaffold-baseline-drift: stage7-scaffold-revalidation
   api-schema-impact: system-data-architecture-and-contract-review
   database-schema-impact: data-architecture-and-migration-review
-  permission-impact: spec-product-design-and-contract-review
   state-machine-impact: spec-system-data-and-contract-review
   data-model-impact: data-architecture-and-contract-review
   new-write-path: stage7-contract-recompile
@@ -242,7 +243,7 @@ execution_result_required:
   - deviations
   - new_impacts
   - not_applicable_reason
-seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan]
+seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
 deviation_required: [rule, reason, approval_ref]
 not_applicable_required: [item, reason]
 unavailable_skill_required: [skill, provider, fallback, resolution]

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

@@ -14,8 +14,11 @@ slice_contract:
     ticket:
     requirement_freeze:
     low_fidelity_review:
+    prototype_review:
     high_fidelity_html:
+    prototype_verification:
     antd_cli_evidence:
+    browser_verification_evidence:
     prototype_confirmation:
     openapi_freeze_or_no_impact:
     architecture_review:
@@ -107,4 +110,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/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/.pi/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/.pi/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/.pi/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/.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):
         """只保留数据库目录布局，不生成业务表或初始化数据。"""