create-yss-spec 3.5.3 → 3.5.5

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

@@ -20,16 +20,7 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 
 ## Review Flow
 
-1. Recompute the Draft SHA-256 and verify `<feature>-validation.yaml`. The record must bind a pnpm-lockfile-pinned Redocly version, the exact lint command, exit code, execution time and readable evidence; its structural checks and lint must all pass. Custom parser evidence may supplement this record but cannot replace locked Redocly lint.
-2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry. For P0 write/configuration models and read models that affect a key interaction, trace the exact property path, type/nesting, operation-specific requiredness, nullable/default/enum/format rules, source locator and error/test seam.
-3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
-4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
-   When create/update or other lifecycle operations share one schema, verify that omission and requiredness semantics match for every operation; otherwise require split schemas or an explicit conditional contract. For credentials, distinguish create, update, masked readback, omit-to-preserve and explicit-clear behavior instead of imposing a universal required rule.
-5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
-6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
-7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
-8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
-9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+开始语义审查时读取 [P0 追踪与审查步骤](references/semantic-review.md)，逐项覆盖当前 Spec / UI 命中的字段、操作、错误和测试 seam。当前 SHA 与锁定 lint 证据通过后才可能得出 Approved。
 
 ## Automation Boundary
 
@@ -58,42 +49,4 @@ Block if any of these are true:
 
 ## Output Contract
 
-```markdown
-### Review Result
-<Approved / Blocked>
-
-### Structural Validation
-<Passed / Blocked; validation record, Draft SHA-256, locked Redocly version, command and evidence>
-
-### Semantic Review
-<Passed / Blocked; P0 field traceability and remaining semantic findings>
-
-### Blocking Findings
-- <file:line grounded finding>
-
-### Non-Blocking Suggestions
-- <can wait until architecture/design>
-
-### Contract Coverage
-- <P0 requirement -> endpoint/schema/error/test mapping summary>
-- <P0 field source -> operationId/schema/property path/shape/requiredness/constraints/error/test mapping summary>
-
-### YSS Baseline
-- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
-- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
-- <DDD boundary implications, implementation feasibility>
-
-### Contract Test Checklist
-- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
-- <single object, non-page list empty array, page empty array and page boundary cases>
-- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
-- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
-- <minimum contract tests before OpenAPI Freeze>
-
-### Next Action
-- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
-```
-
-`Review Result` 只有在 `Structural Validation` 与 `Semantic Review` 均为 `Passed` 时才能是 `Approved`；不使用 `Conditionally Approved` 或 `Semantic Approved` 作为顶层结论。
-
-Prefer `.template-spec/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.
+形成持久化结论时读取 [审查输出契约](references/review-output.md)。`Review Result` 仅在 `Structural Validation` 和 `Semantic Review` 均为 `Passed` 时可为 `Approved`；否则 `Blocked`，不使用条件批准。

package/template/.cursor/skills/yss-openapi-draft-review/references/review-output.md

@@ -0,0 +1,45 @@
+# OpenAPI Draft 审查输出
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## Output Contract
+
+```markdown
+### Review Result
+<Approved / Blocked>
+
+### Structural Validation
+<Passed / Blocked; validation record, Draft SHA-256, locked Redocly version, command and evidence>
+
+### Semantic Review
+<Passed / Blocked; P0 field traceability and remaining semantic findings>
+
+### Blocking Findings
+- <file:line grounded finding>
+
+### Non-Blocking Suggestions
+- <can wait until architecture/design>
+
+### Contract Coverage
+- <P0 requirement -> endpoint/schema/error/test mapping summary>
+- <P0 field source -> operationId/schema/property path/shape/requiredness/constraints/error/test mapping summary>
+
+### YSS Baseline
+- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
+- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
+- <DDD boundary implications, implementation feasibility>
+
+### Contract Test Checklist
+- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
+- <single object, non-page list empty array, page empty array and page boundary cases>
+- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
+- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
+- <minimum contract tests before OpenAPI Freeze>
+
+### Next Action
+- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
+```
+
+`Review Result` 只有在 `Structural Validation` 与 `Semantic Review` 均为 `Passed` 时才能是 `Approved`；不使用 `Conditionally Approved` 或 `Semantic Approved` 作为顶层结论。
+
+Prefer `.template-spec/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

package/template/.cursor/skills/yss-openapi-draft-review/references/semantic-review.md

@@ -0,0 +1,16 @@
+# OpenAPI Draft 语义审查
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## Review Flow
+
+1. Recompute the Draft SHA-256 and verify `<feature>-validation.yaml`. The record must bind a pnpm-lockfile-pinned Redocly version, the exact lint command, exit code, execution time and readable evidence; its structural checks and lint must all pass. Custom parser evidence may supplement this record but cannot replace locked Redocly lint.
+2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry. For P0 write/configuration models and read models that affect a key interaction, trace the exact property path, type/nesting, operation-specific requiredness, nullable/default/enum/format rules, source locator and error/test seam.
+3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
+4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
+   When create/update or other lifecycle operations share one schema, verify that omission and requiredness semantics match for every operation; otherwise require split schemas or an explicit conditional contract. For credentials, distinguish create, update, masked readback, omit-to-preserve and explicit-clear behavior instead of imposing a universal required rule.
+5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
+6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
+7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
+8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
+9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.

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

@@ -45,57 +45,11 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 
 ## 受控工具链
 
-在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
-
-```bash
-pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
-
-pnpm exec redocly bundle \
-  docs/.scratch/<feature>/api/<feature>.yaml \
-  --output docs/.scratch/<feature>/api/<feature>.json \
-  --ext json \
-  --component-renaming-conflicts-severity=error \
-  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
-```
-
-默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
-
-`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
+执行 lint / bundle 前读取 [锁定工具链](references/locked-toolchain.md)。只用项目 pnpm lockfile 固定的 Redocly；默认 `$ref` 限本 feature API 目录，例外先登记。
 
 ## 治理流程
 
-1. **建立或读取 YAML Draft**
-   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
-   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
-   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
-
-2. **运行结构与治理校验**
-   - 先执行项目 lockfile 锁定版本的 `pnpm exec redocly lint`；CI 可以包装调用，但 validation record 必须记录这条实际命令与退出码。
-   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
-   - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
-   - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
-   - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
-   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
-   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
-   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
-
-3. **独立 Draft Review 与 Freeze**
-   - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
-   - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
-   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
-   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
-
-4. **从冻结 YAML 派生 JSON**
-   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
-   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
-   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `.template-spec/api/templates/openapi-json-export-record-template.md` 创建。
-   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
-
-5. **交给下游前端**
-   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
-   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
-   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
-   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
+当前任务涉及 Draft、结构校验、Review / Freeze 或派生交接时，读取 [治理分阶段步骤](references/governance-workflow.md) 中对应步骤。阶段顺序保持 Draft → 校验 → 独立 Review / Freeze → JSON → 下游；任何前置证据缺失不得越过阶段。前端 profile 仅消费后端权威，不能执行后端批准。
 
 ## 阻断规则
 

package/template/.cursor/skills/yss-openapi-governance/references/governance-workflow.md

@@ -0,0 +1,38 @@
+# OpenAPI 治理步骤
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## 治理流程
+
+1. **建立或读取 YAML Draft**
+   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
+   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
+   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
+
+2. **运行结构与治理校验**
+   - 先执行项目 lockfile 锁定版本的 `pnpm exec redocly lint`；CI 可以包装调用，但 validation record 必须记录这条实际命令与退出码。
+   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
+   - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
+   - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
+   - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
+   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
+   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
+   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
+
+3. **独立 Draft Review 与 Freeze**
+   - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。
+   - YAML、validation record 或 lint ruleset 变化后，旧结构证据与旧 Review 立即失效，必须重新校验和审查。阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
+   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
+   - 将同一 YAML 的版本与摘要、validation record、独立 Review 和 Freeze 写入 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。`gate.engineering-contract-approved` 一次批准同时绑定 Technical Design、Data Architecture Decision、API Contract Decision；API `required` 时还必须直接绑定冻结 YAML。不得另造字符串 URI 或仅凭 `status: approved` 关闭门禁。
+
+4. **从冻结 YAML 派生 JSON**
+   - 使用 [锁定工具链](locked-toolchain.md) 中的 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
+   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
+   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `.template-spec/api/templates/openapi-json-export-record-template.md` 创建。
+   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
+
+5. **交给下游前端**
+   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
+   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
+   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
+   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。

package/template/.cursor/skills/yss-openapi-governance/references/locked-toolchain.md

@@ -0,0 +1,22 @@
+# OpenAPI 锁定工具链
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+## 受控工具链
+
+在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
+
+```bash
+pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
+
+pnpm exec redocly bundle \
+  docs/.scratch/<feature>/api/<feature>.yaml \
+  --output docs/.scratch/<feature>/api/<feature>.json \
+  --ext json \
+  --component-renaming-conflicts-severity=error \
+  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
+```
+
+默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
+
+`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。

package/template/.cursor/skills/yss-product-lifecycle/SKILL.md

@@ -5,44 +5,42 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 
 # YSS Product Lifecycle
 
-合同阅读：`scripts/contract view`；见 `.template-spec/process/contract-reading.md`。
+合同阅读与托管更新：`scripts/contract view|render|check-views`；见 `.template-spec/process/contract-reading.md`。
 
-主控识别请求、身份和阶段，计算 frontier、派发并验收工作单元。
+五类机器资产默认 JSON；读写、迁移及恢复须遵循 `.template-spec/process/structured-assets.md`。
 
-文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `.template-spec/process/document-writing.md` 规范。
+文档及进度按 `document_writing` 调用 `i-have-adhd`，遵循 `.template-spec/process/document-writing.md`；正文用中文名称与动作，编号按需追踪。
 
-## 事实源与按需加载
+## 事实源
 
-先读 `yss-project.yaml`、`AGENTS.md`、`CONTEXT.md` 和当前任务视图；按需加载命中的合同子树：
+先读 `yss-project.yaml`、`AGENTS.md`、`CONTEXT.md` 和当前任务视图，按需读合同：
 
 | 事实 | 权威来源 |
 |---|---|
-| 阶段、聚合门禁、内部检查、产物、工作单元、证据和稳定 ID | `.template-spec/process/lifecycle-registry.yaml` |
-| 执行模式、流转、readiness、暂停、结果和授权语义 | `references/orchestration-contract.yaml` |
-| Skill 身份、capability、依赖和路由 | `.template-spec/agents/yss-skill-registry.yaml` |
+| 阶段、门禁、产物、工作单元、证据及 ID | `.template-spec/process/lifecycle-registry.yaml` |
+| 执行、流转和授权合同 | `references/orchestration-contract.yaml` |
+| Skill 身份、能力、依赖和路由 | `.template-spec/agents/yss-skill-registry.yaml` |
 | 数字人角色、运行时和会签策略 | `.template-spec/agents/digital-human-roles.yaml` |
-| 影响面、裁剪和模板维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
-
-用 `scripts/query-lifecycle-context` 查询合同：
+| 影响面、裁剪与维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
 
 ```bash
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
-`--include` 接受合同顶层键，非法键或 ID 失败。细节按需读 `references/orchestration.md` 及其索引，证据充分即停止加载。
+`--include` 接受合同顶层键，非法输入失败。详见 `references/orchestration.md`。
 
-按 `execution_efficiency` 合并查询、复用未变资料并验证当前资产；产品流转不重跑模板套件。词汇对账、恢复核验及门禁不变，执行细节见 `references/orchestration.md`。
+按 `execution_efficiency` 合并查询、复用未变资料；仍核验当前资产、词汇和门禁，产品流转不重跑模板套件。
 
 ## 入口与模式
 
 1. 严格解析 `yss-project.yaml`，不得按目录、Git remote 或占位符猜仓库身份。
-2. 判定影响面和最近可信阶段；阶段完成必须同时满足内容、审查结论、上游新鲜度和可读证据，文件存在不代表通过。
+2. 判定影响面和最近可信阶段；完成须满足内容、审查、上游新鲜度和可读证据，文件存在不代表通过。
 3. 按合同 `request_triage` 选择 `route`、`orchestrate`、`resume`、`audit`；明确行动请求无需模式关键字，意图不明时只读 `route`。`modes`、门禁及授权边界仍适用。
 4. `project-instance` 按生命周期注册表推进；`template-source` 只走模板维护流程。
 
-Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/plan-migration.md`，核查战略输入与退出条件。关键未决项阻断 Spec；其他未决项记录责任人、解决时点和接收方。只用 Plan 标识；旧阶段不兼容解析，历史批准不自动沿用。
+Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/plan-migration.md`，核查战略输入与退出条件。关键未决项阻断 Spec；其余记录责任人、解决时点和接收方。只用 Plan 标识，旧阶段不解析，历史批准不自动沿用。
 
-理解、澄清与纠错见 [请求分诊协议](references/request-triage.md)；用 `scripts/query-lifecycle-context --include request_triage` 查询合同。先查上下文和证据，只问影响下一动作的缺口，不按问题长度追问。
+分诊见 [协议](references/request-triage.md) 与 `--include request_triage`。先查证据，只问下一动作所需缺口，不按问题长度追问。
 
 ## 不可越过的边界
 
@@ -56,7 +54,7 @@ Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/pl
 
 聚合批准见 `gate_consolidation`。普通功能默认一个独立审查者，按能力缺口、冲突或外部制度增员；相邻检查组合审查、逐项留证。
 
-项目职责与后端终点见 `execution_scopes`；恢复、编译和派发必须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
+职责与后端终点见 `execution_scopes`，恢复、编译和派发须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
 
 ### 用户决定
 
@@ -71,30 +69,32 @@ Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/pl
 1. 从真实资产重建当前状态，查询当前 mode、stage、work-unit 及必要合同子树。
 2. 评估影响面、上游新鲜度、门禁和阻塞，选择第一个未阻塞工作单元；不把 `not-applicable` 当作豁免。
 3. 原生工作单元由主控持有正式资产；专项按结构化任务包派发，只调用合同允许的 model-invoked skill。
-4. `to-spec`、`to-tickets`、`implement` 等兼容入口只可由用户显式调用。主控先预检输入、路径和门禁；入口按 `matt_invocation_boundary` 写入其产物并回交验收，不批准或改变 Ticket 就绪状态。原生资产仍归主控。
-5. 先对照用户目标逐项验收，检查遗漏诉求、错误假设与尚未解决的问题，再验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract v3；其他阶段不得伪造该合同。
-6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
+4. `to-spec`、`to-tickets`、`implement` 等兼容入口只可由用户显式调用。主控预检输入、路径和门禁；入口按 `matt_invocation_boundary` 写入其产物并回交验收，不批准或改变 Ticket 就绪状态。原生资产仍归主控。
+5. 先逐项验收用户目标、遗漏、错误假设和未决问题，再验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract v3；其他阶段不得伪造该合同。
+6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断独立工作。
 
 每个 `project-instance` 工作单元批准或流转前，回写稳定术语到唯一根 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
 
 ## 面向业务角色
 
-使用业务语言推进：
-
-`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
-
-按当前决策澄清目标、流程、责任、规则、范围和验收例子。业务方案总览引用权威资产，展示状态、未决项、责任人和下一步；不复制正文或新增门禁。
+澄清目标、流程、责任、规则、范围和验收例子。业务总览引用权威资产，展示状态、未决项、责任人和下一步，不复制正文或新增门禁。
 
 Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `.template-spec/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
 
 ## 结果与暂停
 
-咨询直接回答；工作单元完整留证，对外展示当前决定。
-
-工作单元结果至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。
+结构化结果保留模式、仓库身份、阶段/工作单元、影响面、资产/门禁/Ticket/Slice/合同状态、证据新鲜度、就绪、阻塞、本轮动作、下一单元、暂停理由、Ticket 同步和 Git checkpoint；用户说明按中文写作规范呈现。
 
-暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
+会签记录保留门禁 ID、`role_id`、`runtime_id`、文件路径、推荐答案和恢复动作；用户提示解释待决定事项与责任方。恢复前运行适用验证器。同一候选通过适用审查与 fresh verification 才可提出完成、合并或发布结论；发布仍须生物人决定。
 
 Plan / Spec / Design 追踪按 `.template-spec/process/stage-tracking.md`。
 
 需求澄清读 [对账](references/plan-requirements.md)；外部输入读 [问卷](references/external-input-questionnaire.md)。
+
+Spec 起草业务票，Design 校准后正式化；无设计影响直接正式化，研发再细化 Slice。按 `.template-spec/process/business-tickets.md` 检查覆盖和批准；业务票不授予实现资格。
+
+## 功能资产整理
+
+整理与旧票迁移先读 `.template-spec/process/feature-assets.md`，只按显式候选计划处理，保留状态、批准依据和原文；不得推进阶段。临时输入与草稿放临时工作区，引用后按正式资产保留。
+
+既有 YSS 实例的模板版本升级、旧治理布局迁移或升级恢复路由到 `yss-harness-upgrade`，按 `.template-spec/process/harness-upgrade.md` 执行；不由升级动作推进产品阶段或重写历史批准。