create-yss-spec 3.3.0 → 3.3.3

package/template/.claude/skills/yss-mybatis/references/source-index.md

@@ -1,113 +0,0 @@
-# yss-mybatis Source Index
-
-Generated: 2026-09-08T17:00:36.490Z
-Source commit: `2ccbd3f3f145f9bf74b217a2c211e4bf7a8a2074`
-Component worktree: `clean`
-Component tree `yss-microservice-components/yss-component-persistence`: `274d9f4c948d0bd8a58e7f6fb50685d6de740f7b`
-Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
-
-This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
-
-Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.
-
-## Component Path Hints
-
-- `yss-microservice-components/yss-component-persistence` (existed when indexed)
-
-## Documentation Files
-
-- `yss-microservice-components/yss-component-persistence/HELP.md`
-- `yss-microservice-components/yss-component-persistence/README.md`
-- `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
-
-Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-persistence`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common`
-
-## Capability Matrix
-
-### Repository abstractions
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java` — `sha256:fd6d72ff759b3438a2cf9d8a2ba24e848a9e68995fc8a100a0a53c65ee3500bb`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:20` — `public interface BaseRepository<T, D extends Serializable> extends Mapper<T>, BaseMapper<T, D>, ListMapper<T> {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:66` — `<S extends T> int insert(S entity);`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:80` — `<S extends T> int insertSelective(S entity);`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:85` — `<S extends T> int insertList(@Param("entityList") List<S> entityList);`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:96` — `<S extends T> int updateList(@Param("entityList") List<S> entityList);`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java:108` — `<S extends T> int updateListSelective(@Param("entityList") List<S> entityList);`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java` — `sha256:3c37b73a2a2dcaa1ad47fee42f8fb4f9b9ecf51b095f8d1fef816cf785fcbb05`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:12` — `public interface BasePlusRepository<T> extends BaseMapper<T> {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:21` — `default Integer insertBatchSomeColumn(List<T> entityList) {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:29` — `Integer rows = insertBatchSomeColumnInternal(entityList.subList(fromIndex, toIndex));`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java:43` — `Integer insertBatchSomeColumnInternal(List<T> entityList);`
-
-### Pagination and activation
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java` — `sha256:617d5eba33a8266bfc485c8e5f39f43519dd16f4d89c9fea7f918d87b00293ba`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:22` — `@Around("( (execution(public * (@org.springframework.stereotype.Repository *).*(..)) || execution(* com.yss..*.gateway.impl.*.*(..))))&& (args(pageQuery)||args(pageQuery,..))")`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java:27` — `Page<Object> page = PageHelper.offsetPage(pageQuery.getOffset(), pageQuery.getPageSize());`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java` — `sha256:c2659f417c10db7fd9e1a91f825d3b6396ae949f7858dbd3b3d9f8917ae42031`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java:15` — `@ConditionalOnProperty(name = "yss.mybatis.page-helper.enabled", havingValue = "true", matchIfMissing = true)`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java` — `sha256:2fda7b769434bd6942f680cdc7ffa71030c0d6a0e448d762e0f19b2d0b33cd85`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:8` — `@ConfigurationProperties(value = "yss.mybatis",ignoreUnknownFields = false)`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:10` — `private String mapperLocation = "mappers/*.xml";`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:11` — `private String mapperScan = "com.yss.cloud.**.mapper";`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:15` — `private Integer batchSize = 200;`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:21` — `private PageHelper pageHelper = new PageHelper();`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:27` — `private MybatisPlusPagination mybatisPlusPagination = new MybatisPlusPagination();`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:36` — `private String dbType;`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:164` — `private Boolean enabled = true;`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java:183` — `private Boolean enabled = true;`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java` — `sha256:79509947c12aeac7b9d6d3e8610edea438240b6613368b84b57b492f06a6b7fc`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:47` — `PageInterceptor pageInterceptor = new PageInterceptor();`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:264` — `batchSqlInjector.setDbType(dbType);`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:265` — `BatchInsertSettings.setBatchSize(yssMybatisMapperProperties.getBatchSize());`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java:275` — `PaginationInnerInterceptor paginationInnerInterceptor = new PaginationInnerInterceptor(dbType);`
-
-### SQL-level batch insertion
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java` — `sha256:b1ae05aed5f90a97c36ad29d240b05f9f7c5ee5796f2bc293917e09f7d1c8bd2`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:8` — `private static final int DEFAULT_BATCH_SIZE = 200;`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:9` — `private static volatile int batchSize = DEFAULT_BATCH_SIZE;`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:18` — `public static void setBatchSize(Integer configuredBatchSize) {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:19` — `batchSize = configuredBatchSize == null || configuredBatchSize <= 0`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchInsertSettings.java:20` — `? DEFAULT_BATCH_SIZE : configuredBatchSize;`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java` — `sha256:463dfc881c0c33e27ed2a9157041e8b06d2b2e8bbab0dae1a106f467c31fb4ef`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:16` — `public class BatchSqlInjector extends DefaultSqlInjector {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java:28` — `"insertBatchSomeColumnInternal", dbType, i -> FieldFill.UPDATE != i.getFieldFill()));`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java` — `sha256:9cc31f71154fffbc99e4f67816b9026f286f864cfb56a57420185f5e0362dca3`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:24` — `public class DialectInsertBatchSomeColumn extends AbstractMethod {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:82` — `return dbType == DbType.ORACLE`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:83` — `|| dbType == DbType.ORACLE_12C`
-  - `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/DialectInsertBatchSomeColumn.java:84` — `|| dbType == DbType.DM;`
-
-### Multi-data-source capability boundary
-
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java` — `sha256:d19370f6a63af76ccb0d05084ef9f0aa71488dcc98b320933ffb8ccf9b9bf896`
-  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:10` — `public class MultiDataSourceHolder {`
-  - `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java:12` — `private Map<String, DataSource> multiDataSource;`
-
-### Auto-configuration registration
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/resources/META-INF/spring.factories` — `sha256:592ecdc43e8e11f86c6d1c4b335661f7a05ae8faf4ebb206ec49ef25512d5e46`
-  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration=\`
-  - `io.mybatis.config.spring.SpringEnvAutoConfiguration`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/resources/META-INF/spring.factories` — `sha256:22d8e4510b67fffe9a132b20524c1982c530d80594a3c4e9f839e914068e0a58`
-  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisPlusConfiguration`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/resources/META-INF/spring.factories` — `sha256:ab6be3903a3af9369ecc56d47dac769511e62bc4a7215ebb7171a920415fa23f`
-  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MybatisBaseConfiguration,com.yss.cloud.mybatis.MybatisPlusConfiguration`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/resources/META-INF/spring.factories` — `sha256:59e4a12550a854ad5a5b253ba3300058edc6646b2b221505aab4fb6bfcad1721`
-  - `org.springframework.boot.autoconfigure.EnableAutoConfiguration = com.yss.cloud.mybatis.MultiDataSourceConfiguration`
-
-## Freshness and Use
-
-- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.
-- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.
-- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.
-- Read only the source entries needed for the current decision or troubleshooting path.

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

@@ -1,82 +0,0 @@
----
-name: yss-openapi-draft-review
-description: Use when reviewing a `docs/.scratch/<feature>/api/` OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/Spec Delta design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, pagination, optimistic locking, and contract test seams.
----
-
-# YSS OpenAPI Draft Review
-
-Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
-
-## Required Inputs
-
-- OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
-- Calibrated Spec.
-- Interaction spec / prototype review when UI exists.
-- YSS engineering baseline rules and `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；先运行 `scripts/verify-yss-dto-openapi-profile`。
-- 若 Draft 包含 computed getter（例如 `totalPages`），必须提供目标 HTTP mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP evidence。
-
-## Review Flow
-
-1. Consume fresh automated evidence for YAML parsing, single-document OAS 3.1 shape, `$ref`, path parameters, and lint. Generate it once with the Draft or when the Draft changes; do not manually repeat unchanged structural checks.
-2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry.
-3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
-4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
-5. Check YSS API baseline: REST shape, `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.
-
-## Automation Boundary
-
-- Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
-- `scripts/verify-yss-dto-openapi-profile` owns the reusable DTO mapping invariants; the review still checks each endpoint's concrete schema, wrapper extension and evidence.
-- Human or independent semantic review owns P0 traceability, page-action coverage, error behavior, concurrency/idempotency, scope downgrades, contract-test seams, and any explicitly specified authentication or authorization behavior.
-- Fresh passing automation evidence may be referenced by the semantic review; copying the same findings into a second checklist is unnecessary.
-- Re-run structural automation only when the Draft, ruleset, or referenced schema changes.
-
-## Blocking Rules
-
-Block if any of these are true:
-
-- A P0 requirement has no endpoint, schema, error contract, or explicit non-goal.
-- A UI action has no endpoint/non-goal mapping.
-- A configurable rule or gate lacks a source, owner, fixed/default decision, or API representation.
-- Pagination does not align with the `PageResult` profile or documented exception, or exposes `offset` / `needTotalCount` / `tempTotalCount` as client input.
-- A response omits `x-yss-response-wrapper`, uses the compatibility `com.yss.cloud.dto.response` package for a new contract, writes Java generic notation as an OAS schema, or fails `YssResultMeta` + `allOf` + concrete `data` mapping.
-- `code` is modeled as arbitrary object, `dataType` loses explicit nullability, or computed fields such as `totalPages` lack target wire evidence.
-- Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, and optimistic locking.
-- YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
-
-## Output Contract
-
-```markdown
-### Review Result
-<Approved / Blocked>
-
-### Blocking Findings
-- <file:line grounded finding>
-
-### Non-Blocking Suggestions
-- <can wait until architecture/design>
-
-### Contract Coverage
-- <P0 requirement -> endpoint/schema/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>
-```
-
-Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

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

@@ -1,130 +0,0 @@
----
-name: yss-openapi-governance
-description: Use when creating, governing, linting, freezing, or exporting YSS OpenAPI 3.1 design-time contracts. The frozen YAML is the only authority; this skill produces the reviewed JSON derivative consumed by frontend client generation.
----
-
-# YSS OpenAPI Governance
-
-本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
-
-```text
-Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生物 → 下游既有前端代码生成流程
-```
-
-`docs/.scratch/<feature>/api/<feature>.yaml` 是唯一权威的 OpenAPI 3.1 契约。JSON 只能由冻结后的 YAML 可复现地产生，用于前端代码生成或分发；不得手写、不得反向覆盖 YAML、不得把运行时代码当成设计契约来源。
-
-YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
-
-## 边界与职责
-
-使用 `yss-openapi-governance`：
-
-- 基于冻结前的 Spec、产品设计、架构约束创建或更新 `docs/.scratch/<feature>/api/<feature>.yaml`。
-- 保证 YAML 是单一 YAML document、根节点为 `openapi: 3.1.0`，且不把 `pipeline`、`stage`、`status`、`owner` 等生命周期元数据写入 OpenAPI 根节点。
-- 按 `yss-dto` wire profile 校验 `com.yss.cloud.dto.result` canonical 包、`YssResultMeta` 公共字段、具体 wrapper schema、请求 / 响应方向和分页负向字段。
-- 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
-- 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
-- 维护治理记录、Freeze 记录和 JSON 派生记录。
-- Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
-
-不使用本 skill 来替代：
-
-- `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
-- `yss-api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
-- `to-tickets`：在 Freeze 后正式化垂直切片。
-
-## 受控工具链
-
-在持有冻结 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。
-
-## 治理流程
-
-1. **建立或读取 YAML Draft**
-   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
-   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
-   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
-
-2. **运行结构与治理校验**
-   - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
-   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、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**
-   - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
-   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
-
-4. **从冻结 YAML 派生 JSON**
-   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
-   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
-   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `docs/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。
-
-## 阻断规则
-
-阻断 OpenAPI Freeze 或 JSON 导出，若：
-
-- YAML 不是单一 OAS 3.1 document，或其根节点混入生命周期元数据。
-- YAML / `$ref` / lint 不通过，operationId 不稳定或不唯一，或路径参数、schema、examples 无法解析。
-- P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
-- `$ref` 超出允许范围，或转换器版本、lockfile、命令、输入 YAML 无法识别。
-- `scripts/verify-yss-dto-openapi-profile` 失败、profile 版本未记录，或 Draft 未按 profile 建模 `x-yss-response-wrapper`、`YssResultMeta` / `allOf` 和具体 `data` schema。
-- 新契约引入 `com.yss.cloud.dto.response`、把 Java 泛型文字当成 OAS schema、把全局 `code` 放宽为任意 object，或把 `offset` / `needTotalCount` / `tempTotalCount` 作为客户端字段。
-- `totalPages`、任何 computed getter 或 Lombok / `@JsonIgnore` 推导字段没有目标 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
-- Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
-- JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。
-
-## 输出契约
-
-```markdown
-### Governance Result
-<Draft / Approved for Freeze / Blocked / JSON Exported>
-
-### YAML Authority
-- YAML: <docs/.scratch/<feature>/api/<feature>.yaml>
-- OAS: 3.1.0
-- YAML SHA-256: <sha256>
-- Freeze record: <path / ref>
-
-### Validation
-- Lint command and result: <locked pnpm command / result>
-- YSS DTO wire profile: <`.agents/skills/yss-dto/references/openapi-wire-profile.yaml`, schema_version, verifier result>
-- Wrapper conformance: <`x-yss-response-wrapper`, `YssResultMeta`, `allOf`, concrete data schema, direction and forbidden-field result>
-- `$ref` policy / approved exceptions: <details>
-- Blocking findings: <file:line grounded finding>
-
-### JSON Derivative
-- JSON: <docs/.scratch/<feature>/api/<feature>.json>
-- JSON SHA-256: <sha256>
-- Redocly CLI / lockfile: <version and lock reference>
-- Bundle command and metafile: <command / path>
-- JSON validation result: <pass / blocked>
-
-### Downstream Handoff
-- Canonical JSON / frontend materialization SHA-256: <same sha / blocked>
-- Frontend materialization path: <frontend/openapi/openapi.json / blocked>
-- Existing frontend code generation: <manual command in target repository / blocked reason>
-- Template boundary: <no frontend configuration, code-generation execution, or CI change>
-```

package/template/.claude/skills/yss-openapi-governance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS OpenAPI Governance"
-  short_description: "Govern YAML-first OpenAPI and export frozen JSON"
-  default_prompt: "Use $yss-openapi-governance to govern an OpenAPI YAML Draft, freeze it, and export its reviewed JSON derivative."

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

@@ -1,83 +0,0 @@
----
-name: yss-product-lifecycle
-description: 编排 YSS 产品或模块从机会调研到 Spec、原型、技术契约、垂直切片实现、审查、发布和复盘；当阶段、产物、门禁或 YSS skill 不清晰时使用。
----
-
-# YSS Product Lifecycle
-
-生命周期的单一主控入口。它识别仓库身份和最近可信阶段，计算可执行 frontier，选择并验收下一个工作单元；业务设计、实现和独立审查交给相应专项 skill。主控不替代专项 skill，也不复制它们的执行手册。
-
-## 事实源与按需加载
-
-先读取项目根 `yss-project.yaml`、`CONTEXT.md`、相关 ADR、父 Ticket/checkpoint 和当前资产。随后只加载当前决策需要的合同子树：
-
-| 事实 | 权威来源 |
-|---|---|
-| 阶段、门禁、产物、工作单元、证据和稳定 ID | `docs/process/lifecycle-registry.yaml` |
-| 执行模式、流转、readiness、暂停、结果和授权语义 | `references/orchestration-contract.yaml` |
-| Skill 身份、capability、依赖和路由 | `docs/agents/yss-skill-registry.yaml` |
-| 数字人角色、运行时和会签策略 | `docs/agents/digital-human-roles.yaml` |
-| 影响面、裁剪和模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
-
-使用 `scripts/query-lifecycle-context` 获取确定性 JSON 投影，不要为普通路由整份读取编排合同：
-
-```bash
-scripts/query-lifecycle-context --mode route
-scripts/query-lifecycle-context --stage stage.discovery
-scripts/query-lifecycle-context --work-unit work-unit.discovery-requirements
-scripts/query-lifecycle-context --work-unit work-unit.slice-implementation --include ready_for_agent --include ticket_formalization
-```
-
-`--include` 接受编排合同的顶层键；非法模式、ID 或合同键必须失败。查询结果只是带摘要的权威事实投影，不成为新的事实源。解释性细节按需读取 `references/orchestration.md`、`references/state-model.md`、`references/artifact-dependencies.md`、`references/user-decisions.md` 和 `references/matt-yss-adapter.md`，达到最小充分证据后停止扩展上下文。
-
-## 入口与模式
-
-1. 严格解析 `yss-project.yaml`，不得按目录、Git remote 或占位符猜仓库身份。
-2. 判定影响面和最近可信阶段；阶段完成必须同时满足内容、审查结论、上游新鲜度和可读证据，文件存在不代表通过。
-3. 模式为 `route`、`orchestrate`、`resume`、`audit`；未明确时使用只读 `route`。具体写入边界从编排合同的 `modes` 子树读取。
-4. `project-instance` 按生命周期注册表推进；`template-source` 只走模板维护流程。
-
-## 不可越过的边界
-
-### 仓库身份
-
-`template-source` 不得生成产品 Spec、原型、OpenAPI 或垂直切片 Ticket；命中产品流程时返回 `blocked: template-source-product-artifact-forbidden`。模板维护使用 `maintaining-skills`，按 L1/L2/L3 留下对应证据。
-
-### 流转与实现
-
-不得越过命中的阶段、门禁、实现仓库准备或 Ticket 正式化。实现只接收绑定垂直切片、已批准且持久化、版本当前并通过完整 `ready-for-agent` 计算的合同；父 Ticket、`ready-for-human` 切片、`stale`、`drift`、`new_impacts`、`violation` 或缺失证据均阻断。实现仓库、脚手架、UI 还原、review input 和发布条件从对应合同子树查询，不在入口重复定义。
-
-### 用户决定
-
-命中 `docs/agents/digital-human-roles.yaml.user_decision_policy` 的关键决定，必须先展示当前资产、版本、变化、风险、推荐方案、批准范围和后续动作，再取得提问者或其明确指定生物人负责人的原始回复。数字人同意、超时、默认项或无反对意见不能代答；恢复前按 `references/user-decisions.md` 验证当前资产与原始回复绑定。
-
-### 外部副作用与 Git
-
-生命周期批准、实现授权和自然语言意向不构成结构化 Git 授权。commit、push、远端仓库创建、发布及其他运行时外部副作用分别检查明确动作、范围和可读授权引用；缺失时保持外部状态不变。`git-submodule` 还必须遵守逐仓授权、非 detached HEAD 和先子仓后父仓 gitlink 的顺序。
-
-## 有界编排循环
-
-1. 从真实资产重建当前状态，查询当前 mode、stage、work-unit 及必要合同子树。
-2. 评估影响面、上游新鲜度、门禁和阻塞，选择第一个未阻塞工作单元；不把 `not-applicable` 当作豁免。
-3. 原生工作单元由主控持有正式资产；专项工作通过结构化任务包派发，只调用编排合同允许的 model-invoked skill。
-4. Matt 的 `grill-with-docs`、`to-spec`、`to-tickets`、`implement` 等仅为显式 user-invoked 兼容入口。主控不得自动调用它们或代替其创建正式资产；Matt 仅导航，不得写生命周期资产或改变门禁/Ticket 状态，任何写入前回交本编排器。
-5. 验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract；其他阶段不得伪造该合同。
-6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
-
-每个 `project-instance` 工作单元在申请批准或流转前，先把稳定术语回写到根目录唯一 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
-
-## 面向业务角色
-
-默认使用业务语言推进：
-
-`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
-
-先问清用户与结果、通常流程、责任交接、规则与例外、可独立交付的最小范围、证明结果正确的例子和证据。每轮可生成一页“业务方案总览”，只引用权威资产并显示状态、未决问题、责任人和下一步；不复制正文、不成为新的事实源、不新增门禁。
-
-## 结果与暂停
-
-输出至少包含：模式、仓库身份、当前阶段和工作单元、影响面、资产与门禁状态、证据、新鲜度、Ticket/垂直切片/合同状态、`ready-for-agent` 结论、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断。
-
-暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
-
-专项加载提示：实现仓库与脚手架查询 `implementation_repository_preparation`、`backend_scaffold`；切片实现查询 `ticket_formalization`、`ready_for_agent`；UI 查询 `frontend_implementation_plan`、`frontend_implementation_verification`；审查查询 `review_input`；发布查询 `release_readiness`、`git_authorization`、`user_decision_evidence`；战略交接读取 `docs/process/strategic-handoff-package.md` 并按其中验证器执行。

package/template/.claude/skills/yss-product-lifecycle/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS Product Lifecycle"
-  short_description: "编排 YSS 产品全生命周期、门禁、状态与专项技能"
-  default_prompt: "使用 $yss-product-lifecycle，判断模式并有界推进这个需求。"

package/template/.claude/skills/yss-product-lifecycle/references/artifact-dependencies.md

@@ -1,41 +0,0 @@
-# 资产依赖与失效传播
-
-## 基础依赖
-
-```text
-Discovery → Spec → Product Overview / Functional Architecture
-Root CONTEXT.md + current work-unit changes → Context Reconciliation → approval / next work unit
-Spec + Product Overview → Product Design / Requirement Freeze
-Spec + Product Overview → API Impact / OpenAPI Draft
-Spec + Product Overview → System / Data Architecture
-System / Data Architecture + confirmed project architecture → Technical Design Contract (DDD / MVC)
-Technical Design Contract → Architecture Review / Engineering Baseline → implementation repository choice
-implementation repository choice → existing repository onboarding OR approved Project Scaffold Contract → scaffold generation / verification
-Repository Onboarding Result OR Scaffold Manifest + Verification → Implementation Repository Preparation Result → gate.implementation-repositories-ready
-API impact = yes: Requirement Freeze + Design Review + Draft Review → OpenAPI Freeze
-API impact = no: API Impact Assessment approved → No-API-Impact record；Draft/Freeze gates = not-applicable
-Frozen Contract + gate.implementation-repositories-ready → Vertical Slice Tickets
-Tickets + Architecture → Implementation Contract / Build Architecture Checklist
-Implementation → Independent Review → Fresh Verification → Release
-```
-
-## 传播算法
-
-1. 分类变化：文案、UI 状态、API schema、状态机、数据模型、服务边界、NFR、部署。
-2. 只遍历与变化类型相关的边。
-3. 受影响下游先标记 `stale`；不要删除或立即重建。
-4. 移除相关切片的 `ready-for-agent`，直到必要门禁重新为 `approved/not-applicable`。
-5. 重新审查后优先恢复原 Ticket；仅在范围或验收目标根本变化时重建。
-6. 原 `not-applicable` 的条件被推翻时，改为 `missing` 或 `draft`。
-
-具体 `impact type → artifact/gate → direct/transitive → when` 以 `orchestration-contract.yaml` 为机器可执行事实。条件满足时，`direct` 节点直接标记 `stale`；`transitive` 节点仅在其依赖的 direct 节点发生语义变化时传播。条件不满足时保持原状态，尤其不得把 `not-applicable` 改成 `stale`。表中未列出的节点不传播；无法分类的变化暂停影响面裁决，不得猜测。
-
-每个 `stale` 节点必须记录 `stale_by`、影响类型、证据引用和重新批准条件。重新批准 direct 节点后，逐个重新核验 transitive 节点；只有其全部受影响上游恢复为 `approved/not-applicable` 且本节点重新验证通过，才能移除 `stale`。
-
-明确写入需求的认证、授权、租户隔离、敏感数据或合规行为变化不使用独立影响类型；按它实际改变的 UI 状态、API schema、状态机、数据模型或服务边界传播。普通 action 注册、SQL / DDL / 迁移和上传 / 下载只使用既有技术影响类型，不增加安全 / 权限传播。
-
-OpenAPI Freeze 后发生上游变化时，不得仅因父 Ticket 仍写阶段 6 就继续实现。先做影响分析，再精准更新相关资产和门禁。
-
-战术设计合同上游引用发生版本变化时，先将 tactical-design 标记为 `stale`，再传播到 Slice Contract；发现新的聚合、状态、不变量、一致性或 Gateway 影响时标记 `drift` / `new_impacts` 并重新路由。
-
-`CONTEXT.md` 全文摘要变化时，先复核当前和下游资产保存的 `document_digest`；只有其 `referenced_terms_digest` 也变化，才将实际引用这些术语的资产精准标记为 `stale`。无法解析、作用域变化或候选术语未确认时阻断批准/流转，不得用嵌套文件、跨仓路径或 Markdown 锚点绕过。

package/template/.claude/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -1,120 +0,0 @@
-# Matt / YSS 工作流适配
-
-Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS 专项 skills 决定如何符合工程规范。
-
-生命周期默认使用 `work_unit_routes.*.native`；下表中的 Matt flow 是 `work_unit_routes.*.compatibility` 显式兼容输入。兼容入口的正式资产由用户创建并回交生命周期验收，原生工作单元的正式资产由生命周期编排器创建。
-
-## 入口与仓库身份裁决
-
-- 所有入口先读取 `yss-project.yaml`。缺失、解析失败、schema 不支持或 `repository_mode` 非法时，停止路由并进入 migration-check。
-- **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
-- **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用任何 Matt user-invoked skill；编排器直接使用原生工作单元和允许的 model-invoked 原语。Matt user-invoked skill 保持显式兼容入口，生命周期负责准备、校验并验收其结果。
-- `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`setup-matt-pocock-skills` 不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
-- `project-instance` 才允许进入产品 Discovery → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
-
-| 情形 | Matt flow | 生命周期验收 |
-|---|---|---|
-| 首次启用或配置缺失 | `setup-matt-pocock-skills`（用户显式） | `needs-human`，说明缺失项；用户完成 setup 后重新计算 readiness |
-| 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
-| 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
-| 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
-| 技术或战略事实 | `yss-research`（`research` 为 deprecated alias） | `technical-evidence` 核验一手技术资料；`strategy-evidence` 为领域战略和阶段决策提供可审计证据；研究包不得自行修改或批准下游资产 |
-| runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，只能作为阶段 4 输入，不得替代低保真评审、H1/H2 档位路由、schema v3 验证和用户确认 |
-| Spec 综合 | 原生 `work-unit.spec-synthesis`；`to-spec`（用户显式兼容） | 初稿进入 `ready-for-human`，不得直接实现 |
-| 切片 | 原生 `work-unit.ticket-decomposition`；`to-tickets`（用户显式兼容） | 仅在冻结/无影响记录后拆垂直切片，初始 Ticket 状态为 `ready-for-human` |
-| 实现 | 原生 `work-unit.slice-implementation`；`implement`（用户显式兼容） | 当前合同批准并持久化后执行；内部使用 `tdd`，结果回交后再次核验 |
-| Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
-| 审查 | `code-review` | 唯一默认代码审查入口；审查者独立且不得写实现；Standards 消费 Spec、仓库治理规则、Slice `required_skills` 和 YSS / Alibaba 专项检查输入；finding 按合同分流修复或 stale 回 实现合同编译器 |
-| 跨上下文 | `handoff` | 保存来源、阶段、未决项、命令和下一责任人 |
-| 阶段边界 | 生命周期 phase-boundary 合同 | 按 `Continue → /clear → /handoff → subagent → /compact` 选择上下文动作；只记录证据，不扩展生命周期状态 |
-| 解释未落地 | `wait-what` | 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` |
-| 人工步骤 | 人工 checkpoint | 记录 Agent 无法替代的点击、审批、凭据和迁移步骤；秘密值必须隐藏并脱敏 |
-| 编写 Agent 文档 | `writing-for-agents`；维护 skill 时使用 `maintaining-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
-
-尽量不修改 Matt skill 以复制 YSS 规则。只有它违反模板硬门禁时才做最小兼容修改。
-
-实现合同编译器 只能返回 `draft`、`blocked` 或 `ready-for-lifecycle-review`，不得自行批准合同、设置 `ready-for-agent` 或宣布完成。`new_impacts`、`drift`、`violation`、越界路径或缺失实际验证会暂停当前工作单元，并由本编排器决定增量重路由、完整重路由或回到更早生命周期阶段。
-
-## Workflow Execution Result
-
-生命周期工作单元必须输出 `Workflow Execution Result`，再由编排器验收。旧 `Matt Skill Result` 仅可通过只读 compatibility adapter 归一化，且不得影响路由或作为行为基线；workflow reference 不表示调用了对应 Matt user-invoked skill。结果至少包含：
-
-```yaml
-result_schema: workflow-execution-result-v1
-work_unit: work-unit.spec-synthesis
-workflow_reference:
-  source: mattpocock/skills
-  skill: to-spec
-  invocation_mode: reference
-result: completed # completed / blocked / needs-human / failed
-evidence_refs:
-  - docs/process/yss-product-lifecycle-orchestrator-validation.md
-changed_artifacts: []
-new_impacts: []
-stale_candidates: []
-next_route: <next-work-unit-or-null>
-blocking_signals: []
-```
-
-存在 `drift`、`new_impacts`、`violation`、`missing_evidence` 或 `stale_candidates`，以及证据缺失时，不得返回 `completed`；必须暂停并由编排器决定增量重路由、完整重路由或回到更早阶段。
-
-实现合同编译器 状态映射为：`draft → completed`、`blocked → blocked`、`ready-for-lifecycle-review → needs-human`。这里的 `completed` 只表示 Matt 工作单元已产出可验收结果，不表示生命周期完成或可发布。
-
-`completed` 的 `evidence_refs` 至少包含一条可读取或可解析的证据引用；只有字段存在但为空，不能证明工作单元完成。兼容入口下的正式 Spec、Ticket 或实现资产仍只能由对应显式用户入口创建；原生工作单元由生命周期编排器创建并持有状态。
-
-## Matt flow 前置条件
-
-| Matt flow | 进入条件 | 生命周期结果 |
-|---|---|---|
-| `to-spec`（用户显式） | Discovery work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
-| `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human`；必须留下 `ticket_decomposition_result_ref` 和 `vertical_slice_ticket_ref` |
-| `implement`（用户显式） | `ready-for-agent` 公式、Ticket 正式化结果、垂直切片引用/类型/状态、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁；父 Ticket、`ready-for-human` 切片或跳过 Ticket 正式化的 `next_route` 必须 `blocked` |
-
-`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `yss-research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
-
-## Review 候选与 Git 授权
-
-YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。Standards 还必须编译 `review_standards_route`：合同 `required_skills`、影响面专项检查输入、报告模板与 `finding_disposition`；机器检查按 `run_if_present` 执行。质量标准只从 `engineering-baseline` 引用，禁止在 review input 或切片中另起一份。命中高风险影响时，review input 还要引用 Doubt-Driven 主张 / 反证记录；缺少反证或残余风险未处理时返回 `blocked`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。
-
-Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
-
-“然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
-
-## Setup readiness
-
-编排器先做幂等 readiness 检查。`missing` 时不得调用 `setup-matt-pocock-skills`，而是结构化暂停并请用户显式运行它。检查结果只能是：
-
-`ready`、`missing`、`conflict`、`degraded`、`not-applicable`。
-
-该检查每个任务只执行一次并缓存；只有 tracker、主远端、真实标签或配置变化时重查。
-
-证据必须覆盖实际 platform、五态 `label_check` 或 Local `Status:` 检查、`domain_layout`、`artifact_root` 和 `migration_ref`。已持久化 tracker 配置优先于主远端；配置之间或真实标签/Local 状态之间冲突时不覆盖。Local 主 tracker 使用 `docs/.scratch/<feature>/` 完整功能包，不要求远程 Ticket；根 `.scratch/` 与 `docs/requirements/tickets/` 只可作为旧路径迁移来源。仅发现旧路径资产时返回迁移所需结果并暂停写入；新旧路径同时存在时返回 `conflict`。已选择的 GitHub/GitLab 暂不可用时才保留“待发布平台”草案，并在父 Ticket 保留目标平台、`publication: pending` 和 `pending_publication_to`。`template-source` 只执行 validate-only，不初始化具体产品 tracker。
-
-当 YSS 生命周期处于 active 状态时，Matt `to-spec` 中独立运行时的 `ready-for-agent` 发布提示由本适配层覆盖为 `ready-for-human`：Spec 必须先经过产品总体设计 / 功能架构、必要的设计与契约门禁，之后才由生命周期编排器决定垂直切片 Ticket 的 `ready-for-agent`。这只约束 YSS 编排下的状态写入，不修改 Matt skill 单独运行时的核心行为。
-
-`setup-matt-pocock-skills` 仅由用户显式启动。readiness=`missing` 时返回 `needs-human`、`requested_skill=setup-matt-pocock-skills` 和 `resume_route=setup-readiness`；仅发现旧路径资产仍进入 migration-check 并暂停写入。`ready` 直接继续，`conflict` 进入迁移裁决，`degraded` 保留待发布草案，`not-applicable` 仅验证模板契约。通用 setup 文案与 YSS tracker 合同冲突时，以 `docs/agents/issue-tracker.md` 和本编排契约为准。
-
-### Local Markdown 兼容映射
-
-当 `docs/agents/issue-tracker.md` 的 `platform` 为 `local-markdown` 时，Matt flow 的本地输出归一化为以下 YSS 载体：
-
-| Matt 产物 | Local 载体 |
-|---|---|
-| Discovery | `docs/.scratch/<feature>/discovery/` |
-| Spec | `docs/.scratch/<feature>/spec.md` |
-| Spec Delta | `docs/.scratch/<feature>/spec-delta/` |
-| 功能父 Ticket | `docs/.scratch/<feature>/parent-ticket.md` |
-| Wayfinder map | `docs/.scratch/<feature>/map.md` |
-| 垂直切片 Ticket | `docs/.scratch/<feature>/issues/NN-<slug>.md` |
-| 设计 / API / 架构草案 | `docs/.scratch/<feature>/design/`、`api/`、`architecture/` |
-| 门禁 / 验证 / checkpoint | `docs/.scratch/<feature>/gates/`、`verification/` |
-
-Local Ticket 的文件路径是稳定身份，顶部 `Status:` 保存 Matt 五态；远程 URL 只作为显式镜像引用。`ready-for-agent` 仍只能由生命周期编排器在所有必要门禁、阻塞边、实现上下文和 Slice Implementation Contract 满足后设置。
-
-## Phase boundary 优先级
-
-Matt 的上下文建议不能覆盖 YSS 的 phase-boundary 契约。固定按 `Continue → /clear → /handoff → subagent → /compact` 判断，`/clear` 不是每个 Ticket 的强制动作；任何选择都不得改变生命周期阶段、门禁或 Ticket 五态。
-
-## Release / Retrospective
-
-Release 和 Retrospective 是生命周期编排器拥有的工作单元，不由任何兼容流程隐式完成。进入发布或完成结论前必须重新取得 fresh verification、发布/回滚证据和独立审查结果；复盘同样必须有 fresh verification，再按模板治理规则回流 `AGENTS.md`、`CONTEXT.md`、ADR 或 Skill。