create-yss-spec 1.1.3 → 2.0.0

package/template/.codex/skills/yss-cache/scripts/verify-cache-component.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -u
+
+source_root=""
+consumer_root=""
+consumer_module=""
+
+usage() {
+  echo "Usage: $0 [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]" >&2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --source-root) [ "$#" -ge 2 ] || { usage; exit 2; }; source_root=$2; shift 2 ;;
+    --consumer-root) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_root=$2; shift 2 ;;
+    --consumer-module) [ "$#" -ge 2 ] || { usage; exit 2; }; consumer_module=$2; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage; exit 2 ;;
+  esac
+done
+
+if [ -z "$source_root" ]; then
+  source_root=${YSS_SOURCE_ROOT:-}
+fi
+if [ -z "$source_root" ]; then
+  for candidate in "$PWD" "$PWD/.." "$HOME/Projects/yss-cloud-microservice" "$HOME/Documents/yss-project/yss-cloud-microservice"; do
+    if [ -d "$candidate/yss-microservice-components/yss-component-cache-parent" ]; then
+      source_root=$candidate
+      break
+    fi
+  done
+fi
+
+parent="${source_root%/}/yss-microservice-components/yss-component-cache-parent"
+if [ -z "$source_root" ] || [ ! -f "$parent/pom.xml" ]; then
+  echo "ERROR: cannot locate cache parent; use --source-root or YSS_SOURCE_ROOT" >&2
+  exit 2
+fi
+if [ ! -x "$source_root/mvnw" ]; then
+  echo "ERROR: Maven wrapper is missing or not executable: $source_root/mvnw" >&2
+  exit 2
+fi
+if { [ -n "$consumer_root" ] && [ -z "$consumer_module" ]; } || { [ -z "$consumer_root" ] && [ -n "$consumer_module" ]; }; then
+  echo "ERROR: --consumer-root and --consumer-module must be provided together" >&2
+  exit 2
+fi
+
+echo "== Cache reactor verify =="
+(cd "$source_root" && ./mvnw -f "$parent/pom.xml" verify) || exit 1
+
+echo "== Docker integration status =="
+report="$parent/yss-component-redis-cache/target/surefire-reports/TEST-com.yss.cloud.cache.redis.config.RedisStandaloneIntegrationTest.xml"
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+  if [ ! -f "$report" ]; then
+    echo "ERROR: Docker is available but Redis integration report is missing" >&2
+    exit 1
+  fi
+  if grep -Eq 'skipped="[1-9]' "$report"; then
+    echo "ERROR: Docker is available but Redis integration test was skipped" >&2
+    exit 1
+  fi
+  echo "PASS: real Redis integration test executed"
+else
+  echo "SKIP: Docker is unavailable; Redis integration test may be skipped by assumption"
+fi
+
+echo "== Diff whitespace =="
+if command -v git >/dev/null 2>&1 && git -C "$source_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  git -C "$source_root" diff --check || exit 1
+else
+  echo "SKIP: source root is not a Git worktree"
+fi
+
+echo "== Java 8 bytecode =="
+classes=$(find "$parent" -path '*/target/classes/*.class' -type f | head -1)
+if [ -z "$classes" ]; then
+  echo "ERROR: no compiled cache class found" >&2
+  exit 1
+fi
+if ! command -v javap >/dev/null 2>&1; then
+  echo "ERROR: javap is required for bytecode verification" >&2
+  exit 2
+fi
+majors=$(find "$parent" -path '*/target/classes/*.class' -type f -exec javap -verbose {} \; 2>/dev/null | sed -n 's/.*major version: *//p' | sort -u)
+if [ "$majors" != "52" ]; then
+  echo "ERROR: expected only Java 8 major version 52, found: $majors" >&2
+  exit 1
+fi
+echo "PASS: all cache classes use major version 52"
+
+if [ -n "$consumer_root" ]; then
+  echo "== Consumer build =="
+  if [ ! -x "$consumer_root/mvnw" ] || [ ! -f "$consumer_root/pom.xml" ]; then
+    echo "ERROR: invalid consumer root: $consumer_root" >&2
+    exit 2
+  fi
+  (cd "$consumer_root" && ./mvnw -pl "$consumer_module" -am -DskipTests package) || exit 1
+fi
+
+echo "RESULT: cache verification passed"
+exit 0

package/template/.codex/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -55,6 +55,7 @@ python3 scripts/generate_scaffold.py \
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
+- 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行、OpenAPI 生成和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 涉及 API 契约时，先确认 `docs/api/specs/` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
 
 ## 按需读取

package/template/.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -37,7 +37,7 @@ description: "YSS 服务的后端开发脚手架框架和技术指南。在开
 
 ### 构建工具
 
-- **Maven**: 3.x (请使用项目根目录下的 `./mvnw` 脚本进行构建)
+- **Maven**: 3.x (必须使用项目根目录下的 `./mvnw` 脚本进行构建、测试、运行和 CI 验证；不要默认使用裸 `mvn ...` 命令)
 
 ## 2. 架构设计 (Architecture)
 
@@ -107,7 +107,7 @@ description: "YSS 服务的后端开发脚手架框架和技术指南。在开
   - 单个对象: `SingleResult<T>`
   - 列表: `MultiResult<T>`
   - 分页: `PageResult<T>`
-- 涉及新增或变更前后端契约时，先在 `docs/api/specs/` 形成 OpenAPI Draft，经工程基线、架构 / OpenSpec / Comet design 和设计审查后 Freeze，再实现 Controller、DTO、前端调用和契约测试。
+- 涉及新增或变更前后端契约时，先在 `docs/api/specs/` 形成 OpenAPI Draft，经工程基线、架构 / Spec Delta 设计和设计审查后 Freeze，再实现 Controller、DTO、前端调用和契约测试。
 
 ## 4. 工程基线检查清单
 

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -19,7 +19,7 @@ description: YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。
 ## 使用流程
 
 1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
-2. 读取已有资产：`docs/design/design.md`、相关 PRD、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
+2. 读取已有资产：`docs/design/design.md`、相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
 4. 若是产品设计阶段，配合 `product-design-prototype` 产出页面、流程、状态矩阵和 OpenAPI 反推清单。
 5. 若是前端实现阶段，配合 `yss-ui`、`yss-components`、`yss-formily`、`yss-page-module-development`，但本技能负责风格与体验一致性门禁。
@@ -35,13 +35,18 @@ description: YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。
 - 表面层级：页面背景、内容容器、浮层三层模型。
 - 组件语言：优先 Ant Design / YSS UI 语义，不自造同类控件。
 - 状态完整性：loading、empty、error、readonly、disabled、no-permission、conflict、success 必须在设计或实现中可解释。
+- Ant Design v6 原型基线：先用语义 token 定义角色，再用组件 token 或 CSS variables 落地；不以局部硬编码替代主题层。
 
 ## 强制规则
 
 - 不把该系统改造成营销落地页风格；业务应用首屏应直接进入可用工作界面。
 - 不用大面积渐变、装饰插画、夸张 hero、过度卡片化或单色系视觉堆叠替代信息结构。
 - 不在同一决策区域放两个 primary 按钮。
+- 每个页面或决策区域只保留一个 single primary action；其余动作降级为默认、链接或危险操作。
 - 不硬编码表面色、边框色、状态色；优先使用 token 或主题变量。
+- 交互原型中的每个可点击主动作都必须给出 interaction feedback：状态变化、禁用原因、成功或失败反馈至少覆盖其一。
+- accessibility contrast：默认 token 不能满足目标文本对比度时，优先通过 `ConfigProvider` seed / component token 调整，不新增页面级特例色。
+- React + Ant Design 的暗色或紧凑密度必须使用 theme algorithm，不手工反转颜色或逐控件压缩尺寸。
 - 不用 Tag 表达关键错误、阻断或审批状态；关键状态必须有可读文本和语义反馈。
 - 不让按钮、标签、表头、弹窗、卡片中的文字溢出或遮挡。
 - 不在表格 / 筛选 / 批量操作密集页面使用松散营销式布局。
@@ -60,16 +65,18 @@ description: YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。
 实现类任务至少检查：
 
 - 是否通过 `ConfigProvider`、CSS variables 或项目 token 消费主题。
+- 是否将颜色、圆角、阴影和状态样式绑定到 semantic token，而不是复制表面色和交互色。
 - 是否保持 32px 默认控件高度、14px 默认正文、4px 间距网格。
 - 是否使用 YSS UI / Ant Design 的语义组件，而不是自造同类组件。
 - 是否保留 hover、focus、active、disabled、loading、error、empty 状态。
+- 是否为可提交、导出、保存、发布、审批等操作提供明确的 interaction feedback 与不可逆操作确认。
 - 是否在核心视口无横向溢出；表格横向滚动必须被限定在表格容器内。
 
 ## 与其他技能的关系
 
 | 场景 | 配合技能 |
 | --- | --- |
-| PRD 后做页面 / 原型 / 交互说明 | `product-design-prototype` |
+| Spec 后做页面 / 原型 / 交互说明 | `product-design-prototype` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
 | 低保真评审通过后的高保真 HTML 原型 | `high-fidelity-html-prototype` |
 | 低保真线框或流程图 | `wireframe-prototype` / `excalidraw-diagram-generator` |

package/template/.codex/skills/yss-design-system/references/design-system.md

@@ -62,6 +62,8 @@
 - `success`、`warning`、`error`、`info` 只表达功能状态。
 - 预设色板只用于 Tag、图表、分类可视化，不用于重新定义主操作。
 - 不硬编码白色、灰色、状态色；优先引用 token、CSS variables 或 Ant Design theme。
+- semantic token 优先于色值：页面先声明背景、容器、浮层、文本、边框、状态等角色，再映射到具体 token。
+- accessibility contrast 不足时，通过 `ConfigProvider` 的 seed token 或组件 token 调整；不要为单个页面制造不可复用的深浅色例外。
 
 ### 排版
 
@@ -129,6 +131,12 @@
 | Badge | 只做紧凑状态提示，不能替代文本 |
 | Tooltip | 只提供补充解释，不承载关键业务信息 |
 
+交互规则：
+
+- 每个决策区域只保留一个 single primary action；危险操作和次级动作必须在视觉层级上降级。
+- 保存、提交、审批、发布、导出等可点击动作必须产生 interaction feedback，包括结果消息、行内状态变化、禁用原因或确认弹窗。
+- 风险或不可逆动作使用 Modal 二次确认；禁止将“已发布”误表示为“已执行数据库变更”。
+
 ## 页面规则
 
 - 后台页面优先使用：Header / 查询区 / 工具栏 / 表格 / 详情抽屉 / 弹窗。
@@ -190,6 +198,7 @@
 React + Ant Design：
 
 - 使用 `ConfigProvider` 注入主题。
+- 默认主题使用 `theme.defaultAlgorithm`；暗色与紧凑模式通过 theme algorithm 切换，不手工反转色值或逐组件压缩。
 - 优先通过 token、component token、CSS variables、theme algorithm 实现样式。
 - 静态反馈 API 使用 `App`、hook API 或 context holder，避免主题上下文丢失。
 - 暗色模式使用 `darkAlgorithm` 或 `variables.dark.css`。
@@ -219,7 +228,10 @@ YSS UI / Vue：
 实现评审时检查：
 
 - 是否消费 token，而不是硬编码颜色和尺寸。
+- 是否以 semantic token 表达颜色、圆角、阴影和状态层级。
 - 是否保持默认 14px 正文、32px 控件、4px 间距网格。
 - 是否保留 hover、focus、active、disabled、loading、empty、error 状态。
+- 是否只保留一个 single primary action，并让每个关键操作提供 interaction feedback。
+- 是否在目标字号和背景下复核 accessibility contrast。
 - 是否存在卡片套卡片、营销式 hero、装饰性渐变或无意义插画。
 - 是否存在横向溢出、文本遮挡或按钮文字溢出。

package/template/.codex/skills/yss-domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-domain-modeling
-description: 用于 YSS 项目在实现前进行 DDD 领域建模。当用户提供 PRD、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先识别统一语言、上下文边界、聚合、实体、值对象、领域行为、状态流转、Domain Gateway、领域事件、ADR 和实现 handoff 时调用。
+description: 用于 YSS 项目在实现前进行 DDD 领域建模。当用户提供 Spec、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先识别统一语言、上下文边界、聚合、实体、值对象、领域行为、状态流转、Domain Gateway、领域事件、ADR 和实现 handoff 时调用。
 ---
 
 # yss-domain-modeling
@@ -10,7 +10,7 @@ description: 用于 YSS 项目在实现前进行 DDD 领域建模。当用户提
 ## 何时使用
 
 - 用户要求先做 DDD、领域建模、聚合分析、上下文边界或统一语言。
-- 用户提供 PRD、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先沉淀领域模型。
+- 用户提供 Spec、RDD Spec、OpenAPI、页面流程、业务规则、DDL、元数据或现有代码，希望先沉淀领域模型。
 - 用户要求从业务规则推导实体、值对象、领域行为、状态流转、Domain Gateway 或领域事件。
 - 用户要判断某个设计是否应该写 ADR、更新 `CONTEXT.md`，或如何交给后续实现。
 
@@ -23,7 +23,7 @@ description: 用于 YSS 项目在实现前进行 DDD 领域建模。当用户提
 
 ## 工作流
 
-1. 先读取输入资料：PRD、RDD Spec、OpenAPI、页面流程、DDL、`CONTEXT.md`、ADR 和现有代码。
+1. 先读取输入资料：Spec、RDD Spec、OpenAPI、页面流程、DDL、`CONTEXT.md`、ADR 和现有代码。
 2. 抽取业务术语，识别同义词、歧义词、禁用词和待确认含义。
 3. 划分上下文边界，明确每个上下文负责什么、不负责什么、依赖什么。
 4. 识别聚合、聚合根、实体、值对象、领域服务和领域事件。

package/template/.codex/skills/yss-domain-modeling/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "YSS Domain Modeling"
   short_description: "Model YSS domains before implementation"
-  default_prompt: "Use $yss-domain-modeling to derive YSS domain aggregates, boundaries, rules, and implementation handoff from PRD/RDD/spec inputs."
+  default_prompt: "Use $yss-domain-modeling to derive YSS domain aggregates, boundaries, rules, and implementation handoff from Spec/RDD inputs."

package/template/.codex/skills/yss-domain-modeling/references/modeling-workflow.md

@@ -1,12 +1,12 @@
 # Modeling Workflow
 
-Use this reference to turn PRD/RDD/OpenAPI/page flow/DDL/current code into a YSS domain model brief.
+Use this reference to turn Spec/RDD/OpenAPI/page flow/DDL/current code into a YSS domain model brief.
 
 ## 1. Read Inputs
 
 Collect only the inputs needed for the current task:
 
-- PRD, user stories, acceptance criteria, and non-scope.
+- Spec, user stories, acceptance criteria, and non-scope.
 - RDD Spec, OpenAPI, state machine, error codes, and business rules.
 - Page flow, form fields, table columns, actions, permissions, and visible states.
 - Existing `CONTEXT.md`, `CONTEXT-MAP.md`, ADRs, and related code.

package/template/.codex/skills/yss-filerunner/SKILL.md

@@ -22,7 +22,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 1. Identify whether the task is running SQL/Python files, exposing file-runner APIs, parsing scheduler logs, or adding a new file execution type.
 2. Read `references/source-index.md`, then inspect `FileRunnerController`, `FileRunnerService`, `FileExecuterManager`, and concrete executers.
 3. Current supported `FileType` values are `SQL` and `PYTHON`; unsupported types throw `BizException`.
-4. `FileExecuterManager` depends on `SchedulerFacadeApi`; load `yss-anti-scheduler` when execution delegates to scheduler APIs.
+4. `FileExecuterManager` depends on `SchedulerFacadeApi`; inspect the filerunner source index and local scheduler integration code directly when execution delegates to scheduler APIs.
 5. For logs, inspect `DolphinLogParser` and `LogType`.
 6. For starter integration, inspect `DefaultFileRunnerConfiguration`.
 

package/template/.codex/skills/yss-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-openapi
-description: Generate OpenAPI JSON from implemented YSS Java controllers, request DTOs, and response DTOs, then refresh frontend Orval API clients. Use only for the smart-doc plus Orval implementation workflow where smart-doc-maven-plugin emits target/openapi/openapi.json and frontend scripts such as generate:api, orval, api-schema-cleanup.cjs, api-flatten-exports.cjs, or format:generated regenerate src/api client code. Do not use this as the unified OpenAPI style guide, design-time API governance, or docs/api/specs Draft review skill.
+description: Generate OpenAPI JSON from implemented YSS Java controllers, request DTOs, and response DTOs, then refresh frontend Orval API clients. Use only for the smart-doc plus Orval implementation workflow where smart-doc-maven-plugin emits an OpenAPI JSON file and frontend generation scripts regenerate API client code. Do not use this as the unified OpenAPI style guide, design-time API governance, or design-time Draft review skill.
 ---
 
 # YSS OpenAPI
@@ -9,22 +9,22 @@ Use this skill to move an already implemented backend controller/DTO contract in
 
 This is an implementation/generation skill, not the product API design step and not the unified OpenAPI specification governance skill. It generates `openapi.json` from controller methods, request DTOs, response DTOs, annotations, and Java comments; it does not decide naming conventions, resource modeling, error taxonomy, pagination policy, permission semantics, or organization-wide OpenAPI style rules.
 
-For new or changed API contracts, first produce OpenAPI Draft in `docs/api/specs/`, pass engineering baseline, architecture / OpenSpec / Comet design, and Design Review, then Freeze the contract before using this skill to refresh generated clients. When the backend is already the implemented source of truth, use this skill to regenerate and inspect the emitted contract before updating call sites.
+For new or changed API contracts, first produce an OpenAPI Draft in the repository's agreed API draft location, pass engineering baseline, architecture / Spec Delta design, and Design Review, then Freeze the contract before using this skill to refresh generated clients. When the backend is already the implemented source of truth, use this skill to regenerate and inspect the emitted contract before updating call sites.
 
 ## Scope Boundary
 
 Use this skill for:
 
-- Running `smart-doc-maven-plugin` to generate `target/openapi/openapi.json` from implemented backend code.
+- Running `smart-doc-maven-plugin` to generate an OpenAPI JSON file from implemented backend code.
 - Copying generated `openapi.json` into the frontend OpenAPI input path expected by Orval.
 - Running frontend API client generation and inspecting generated TypeScript changes.
 - Verifying that implemented controllers/DTOs emit the expected OpenAPI shape before call-site updates.
 
 Do not use this skill for:
 
-- Designing a new API contract from PRD, prototype, or architecture inputs.
+- Designing a new API contract from Spec, prototype, or architecture inputs.
 - Defining the unified OpenAPI style guide or reusable API governance rules.
-- Reviewing `docs/api/specs/*.yaml` before OpenAPI Freeze.
+- Reviewing design-time OpenAPI Draft files before OpenAPI Freeze.
 - Choosing REST resource boundaries, error models, permission behavior, pagination standards, or contract test policy.
 
 For design-time contract review, use `yss-openapi-draft-review`. For a stronger organization-wide OpenAPI governance baseline, prefer a separate OpenAPI lint/style skill backed by a maintained ruleset tool such as Stoplight Spectral or Redocly CLI, then layer YSS-specific response wrappers, permission, pagination, and security-red-line rules on top.
@@ -32,57 +32,52 @@ For design-time contract review, use `yss-openapi-draft-review`. For a stronger
 ## Core Flow
 
 1. Locate the backend module that owns smart-doc generation.
-   - In `yss-valuation-outsourced`, this is usually `valuation-outsourced-starter`.
-   - Confirm the module has `smart-doc-maven-plugin` and a config such as `src/main/resources/smart-doc.json`.
-   - The smart-doc config's `outPath` determines the generated directory; in this repo it is `target/openapi`.
+   - Search the repository for `smart-doc-maven-plugin`, `configFile`, `outPath`, and `smart-doc.json`.
+   - Confirm which module contains the controllers/DTOs being changed and which plugin execution includes them.
+   - Read the smart-doc config instead of assuming a directory. Its `outPath` determines where the generated OpenAPI JSON is emitted.
 
 2. Generate the backend OpenAPI contract from the repository root.
-   - Use the exact project profile/options the repo expects.
-   - For this repo, run the root `mvnw`; do not add IntelliJ-specific listener or `-Didea.*` parameters:
+   - Use the exact Maven wrapper, profiles, module selector, and plugin version already used by the repository.
+   - Prefer the repo's documented generation command if one exists in scripts, docs, CI, or previous command history.
+   - Do not add IntelliJ-specific listener or `-Didea.*` parameters.
 
 ```bash
-sh mvnw -P SpringCloud.2021.0.9,aliyun-only -DskipTests=true -Dmaven.repo.local=/Users/zhudaoming/.m2/repository com.github.shalousun:smart-doc-maven-plugin:yss-4.0.0:openapi -f pom.xml
+./mvnw <repo profiles/options> <smart-doc plugin goal> -f <root-or-module-pom>
 ```
 
 3. Find the generated `openapi.json`.
-   - Use `find . -path '*/target/openapi/openapi.json' -print`.
-   - For this repo, the expected source is `valuation-outsourced-starter/target/openapi/openapi.json`.
-   - If multiple files exist, choose the one from the module whose `smart-doc.json` and plugin includes cover the controllers/DTOs being changed.
+   - Use the smart-doc `outPath` from the selected config as the primary source of truth.
+   - If the exact file name is not obvious, search under the configured output directory for OpenAPI JSON files.
+   - If multiple files exist, choose the one from the module whose config and plugin includes cover the controllers/DTOs being changed.
 
 4. Copy the generated contract into the frontend OpenAPI input.
-   - In `yss-valuation-outsourced`, copy to `valuation-outsourced-frontend/openapi/openapi.json`.
-   - Preserve the frontend path expected by `orval.config.ts`; do not invent a new input path unless the config is updated too.
+   - Locate the frontend root by finding `orval.config.*` and the package script that runs Orval or API generation.
+   - Read the Orval config to identify the OpenAPI input path.
+   - Preserve the frontend input path expected by Orval; do not invent a new input path unless the config is updated too.
 
 ```bash
-cp valuation-outsourced-starter/target/openapi/openapi.json valuation-outsourced-frontend/openapi/openapi.json
+cp <generated-openapi-json> <orval-input-openapi-json>
 ```
 
 5. Regenerate the frontend API client from the frontend root.
-   - In this repo, run from `valuation-outsourced-frontend`:
+   - Use the API generation script already defined by the frontend package when present.
+   - If there is no wrapper script, run the configured Orval command and any local cleanup/format scripts referenced by the package scripts.
 
 ```bash
-pnpm generate:api
-```
-
-   - The script expands to:
-
-```bash
-orval && node scripts/api-schema-cleanup.cjs && node scripts/api-flatten-exports.cjs && pnpm format:generated
+pnpm <api-generation-script>
 ```
 
 6. Inspect generated changes before touching call sites.
-   - Check `openapi/openapi.json`.
-   - Check `packages/src/api/generated/**`.
+   - Check the Orval input JSON path from the config.
+   - Check the generated client output paths from the Orval config.
    - Update handwritten call sites only after seeing the regenerated function names, request body shape, params type, and result type.
 
 ## How It Works
 
 - `smart-doc-maven-plugin` scans Java controller methods, request/response DTOs, annotations, comments, and configured dependency source jars. It emits an OpenAPI contract under the configured `outPath`.
 - The backend module is the source of truth for routes, HTTP verbs, DTO field names, enum descriptions, binary responses, multipart inputs, and operation IDs.
-- The frontend `orval.config.ts` reads `openapi/openapi.json` and generates TypeScript schema types plus axios client functions under `packages/src/api/generated`.
-- `scripts/api-schema-cleanup.cjs` changes empty object-like generated schemas from `{ [key: string]: unknown }` to `Record<string, never>` so empty bodies/responses are stricter.
-- `scripts/api-flatten-exports.cjs` converts Orval single-mode `getApi()` factory internals into top-level named exports, then keeps `getApi()` as a compatibility wrapper.
-- `pnpm format:generated` formats generated TypeScript files.
+- The frontend `orval.config.*` determines which OpenAPI input file is read and where TypeScript schema types plus client functions are generated.
+- Local cleanup, export-flattening, or formatting scripts may post-process generated files. Use them only when they are part of the repository's generation script.
 
 ## Repo Checks
 
@@ -90,35 +85,28 @@ Run these discovery commands when the layout is uncertain:
 
 ```bash
 rg -n "smart-doc-maven-plugin|configFile|outPath|openapi" -S pom.xml '**/pom.xml' '**/smart-doc.json'
-find . -maxdepth 5 \( -name 'orval.config.*' -o -name 'package.json' -o -name 'api-schema-cleanup.cjs' -o -name 'api-flatten-exports.cjs' \) -print
+find . -maxdepth 6 \( -name 'orval.config.*' -o -name 'package.json' -o -name 'smart-doc.json' \) -print
+rg -n "orval|format:generated|api-schema-cleanup|api-flatten-exports" -S '**/package.json' '**/orval.config.*'
 ```
 
-For `yss-valuation-outsourced`, expect:
-
-- Backend smart-doc config: `valuation-outsourced-starter/src/main/resources/smart-doc.json`
-- Backend generated file: `valuation-outsourced-starter/target/openapi/openapi.json`
-- Frontend Orval input: `valuation-outsourced-frontend/openapi/openapi.json`
-- Frontend Orval config: `valuation-outsourced-frontend/orval.config.ts`
-- Frontend generated code: `valuation-outsourced-frontend/packages/src/api/generated`
-
 ## Troubleshooting
 
 - If a controller or DTO is missing, check `smart-doc.json` `packageFilters`, the plugin `<includes>`, module dependencies, and whether source jars are available in the local Maven repository.
-- If schema names look unstable or invalid, check `componentType`; this repo uses `NORMAL` to keep class-like schema names.
+- If schema names look unstable or invalid, check `componentType` and the repository's smart-doc configuration.
 - If binary download or Excel upload contracts are wrong, inspect backend annotations and any OpenAPI normalizer/override code in the repo before manually editing generated JSON.
 - If Orval changes a client function signature, update frontend call sites to match the generated contract. Do not preserve old call shapes by hand-editing generated files.
 - If `api-flatten-exports.cjs` cannot parse `getApi`, inspect the generated `index.ts`; an Orval version or mode change may have changed the output shape.
-- If formatting or generation fails in nested workspaces, run from the frontend root that owns `orval.config.ts` and the `generate:api` script.
+- If formatting or generation fails in nested workspaces, run from the frontend root that owns `orval.config.*` and the API generation script.
 
 ## Verification
 
 Prefer targeted checks:
 
 ```bash
-test -s valuation-outsourced-starter/target/openapi/openapi.json
-test -s valuation-outsourced-frontend/openapi/openapi.json
-cd valuation-outsourced-frontend && pnpm generate:api
-git diff -- valuation-outsourced-frontend/openapi/openapi.json valuation-outsourced-frontend/packages/src/api/generated
+test -s <generated-openapi-json>
+test -s <orval-input-openapi-json>
+cd <frontend-root> && pnpm <api-generation-script>
+git diff -- <orval-input-openapi-json> <generated-client-output-paths>
 ```
 
-For frontend behavior after API signature changes, run the smallest build or type check that is reliable for the repo. In `yss-valuation-outsourced`, `pnpm exec vite build` from the frontend package workspace has historically been a better signal than broad repo-wide checks when toolchain noise exists.
+For frontend behavior after API signature changes, run the smallest build or type check that is reliable for the repository and the affected frontend package.

package/template/.codex/skills/yss-openapi-draft-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-openapi-draft-review
-description: "Use when reviewing a docs/api/specs OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/OpenSpec/Comet 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/api/specs 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."
 ---
 
 # YSS OpenAPI Draft Review
@@ -10,14 +10,14 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 ## Required Inputs
 
 - OpenAPI Draft under `docs/api/specs/*.yaml`.
-- Calibrated PRD.
+- Calibrated Spec.
 - Interaction spec / prototype review when UI exists.
 - YSS engineering baseline rules, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
 
 ## Review Flow
 
 1. Parse the OpenAPI file and verify YAML, `$ref`, path parameters, and lint when tooling is available.
-2. Build a P0 traceability matrix from PRD functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests.
+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.
 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.

package/template/.codex/skills/yss-openapi-governance/SKILL.md

@@ -15,13 +15,13 @@ Use `yss-openapi-governance` for:
 - Running Spectral or Redocly CLI against `docs/api/specs/*.yaml`.
 - Checking YSS response wrappers, error contracts, pagination, permissions, security red lines, and contract-test seams.
 - Comparing generated `openapi.json` against frozen design rules when backend code is already implemented.
-- Writing or updating governance notes under `docs/api/`, `docs/architecture/`, or the active OpenSpec / Comet design.
+- Writing or updating governance notes under `docs/api/`, `docs/architecture/`, or the active Spec Delta design.
 
 Use other skills for:
 
 - `yss-openapi`: generate `target/openapi/openapi.json` from implemented controllers/DTOs and refresh Orval clients.
-- `yss-openapi-draft-review`: perform fail-closed semantic review against PRD, prototype, page actions, P0 coverage, and architecture readiness.
-- `openspec-*` or `comet-*`: formalize behavior changes and implementation tasks after the contract is frozen.
+- `yss-openapi-draft-review`: perform fail-closed semantic review against Spec, prototype, page actions, P0 coverage, and architecture readiness.
+- `docs/specs/*-spec-delta.md` and `to-tickets`: formalize behavior changes and implementation tickets after the contract is frozen.
 
 ## Preferred Tooling
 
@@ -71,7 +71,7 @@ If neither tool is configured, do not invent project policy silently. Create or
 5. Produce governance output.
    - For quick checks, report lint command, pass/fail result, and blocking findings with file paths.
    - For durable decisions, write or update a Chinese governance artifact under `docs/api/` or `docs/architecture/`.
-   - For active OpenSpec / Comet work, reference the active change and keep rules aligned with `proposal.md`, `design.md`, `tasks.md`, and specs.
+   - For active Spec Delta work, reference the active change and keep rules aligned with the related design, task, and spec artifacts.
 
 ## Minimal Spectral Baseline