create-yss-spec 3.5.6 → 3.5.9

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

@@ -43,7 +43,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 
 ## 执行
 
-优先使用一键入口：
+优先使用一键入口。以下命令从 Skill 根目录执行；坐标、平台及合同参数消费当前批准输入，示例不授予生成或覆盖权限：
 
 ```bash
 node scripts/generate_and_verify_scaffold.mjs \

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

@@ -7,6 +7,10 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 
 本 Skill 只维护 `yss-component-persistence` 的组件能力、选择条件和排障顺序。PO、Repository、Convertor、Gateway/Query Adapter 的结构与生成边界由 `yss-repository` 负责。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-mybatis` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 入口与前置
 
 1. 读取批准且当前的 `architecture_identity`、`persistence_profile`、实现仓登记和 Slice Implementation Contract。没有合同的故障诊断可以继续，但不得据此生成或改变架构。
@@ -74,10 +78,6 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 - 使用项目根 `./mvnw ...` 记录实际命令、退出码和时间；H2 只证明本地/测试行为，不证明生产方言。
 - 按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回证据、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
 
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-mybatis --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
-
 ## 持久化选择记录
 
 在已有数据合同 / persistence_strategy 中记录：实际 Mapper 基类、组件源码与平台绑定、分页唯一责任者、主键与审计填充，以及命中批量时的 SQL 入口、分批大小和方言证据。`BaseMapper` 与组件扩展基类按所需能力选择，不因命名不同判违规；依赖存在和循环 insert 均不证明批量能力。未命中的能力不强制生成。

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

@@ -9,6 +9,8 @@ description: "审查 YSS OpenAPI Draft 的需求覆盖、页面动作、响应
 
 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.
 
+先辨认当前批准协议。普通采用 YSS wrapper 的 HTTP/JSON 响应消费 DTO wire profile；下载、流式和第三方回调按批准协议审查媒体类型、状态、Header、错误及权限边界，不强套 wrapper。例外须有契约依据且仍通过本技能的结构和语义审查。
+
 ## Required Inputs
 
 - OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
@@ -26,7 +28,7 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 
 - Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
 - `scripts/verify-openapi-draft-validation-record` owns validation-record shape, current-byte SHA binding, locked toolchain evidence and deterministic structural rechecks. It does not decide whether a business property correctly implements the Spec.
-- `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.
+- `scripts/verify-yss-dto-openapi-profile` owns the reusable DTO mapping invariants; the review checks every endpoint's approved protocol, concrete schema and evidence, including the wrapper extension when the endpoint uses the YSS wrapper.
 - 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.
@@ -41,9 +43,9 @@ Block if any of these are true:
 - Multiple lifecycle operations reuse one schema even though requiredness or omission semantics differ and no explicit conditional contract resolves the difference.
 - 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.
+- Pagination does not align with the `PageResult` profile or documented exception, or an endpoint using the YSS pagination protocol exposes `offset` / `needTotalCount` / `tempTotalCount` as client input.
+- An ordinary response using the YSS wrapper omits `x-yss-response-wrapper`, uses the compatibility `com.yss.cloud.dto.response` package for a new wrapper contract, writes Java generic notation as an OAS schema, or fails `YssResultMeta` + `allOf` + concrete `data` mapping.
+- In a YSS wrapper, `code` is modeled as arbitrary object or `dataType` loses explicit nullability; or computed fields such as `totalPages` lack target wire evidence.
 - An in-scope behavior lacks a contract-test seam. Select import, mapping coverage, validation, review, publish, export or optimistic-locking seams only when the Spec/API actually includes that behavior; record a reasoned not-applicable for absent operations. A read-only query does not acquire write/import/publish requirements.
 - YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
 

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

@@ -4,6 +4,8 @@
 
 ## Output Contract
 
+Wrapper 与分页检查按实际协议填写：采用 YSS 协议时记录 profile 符合性；下载、流式、回调或已批准分页例外记录协议依据、适用性和实际检查，不生成空 wrapper 或用不适用跳过审查证据。
+
 ```markdown
 ### Review Result
 <Approved / Blocked>

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

@@ -9,8 +9,8 @@
 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.
+5. Check the approved API protocol: REST shape and stable DTO/schema names; ordinary responses using the YSS wrapper declare `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult` and `YssResultMeta` plus `allOf` concrete schemas. Download, streaming and third-party callback protocols retain their approved media types, status, headers and error boundaries without forced wrapping. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
+6. For endpoints using the YSS wrapper, 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. Other approved protocols retain their own concrete wire shape and evidence.
+7. For endpoints using the YSS pagination protocol, check input against its profile: 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. Approved pagination exceptions retain their recorded boundary. `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/.codex/skills/yss-openapi-governance/SKILL.md

@@ -17,11 +17,9 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 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` 字段表。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+先识别当前批准协议：普通已采用 YSS wrapper 的 HTTP/JSON 接口按 wire profile 检查；下载、流式和第三方回调按批准契约检查媒体类型、状态、Header、错误及权限边界，不强套 wrapper。协议差异须有可读依据，不能以“特殊接口”为由豁免 Draft、审查、Freeze 或验证。
 
-## 文档写作
-
-编写接口说明和契约评审交接正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
+编写接口说明或契约评审交接正文时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引。作用域仅限当前产物；派发时传递条件及引用，协议标识、schema、冻结状态和验证记录按原合同保存。
 
 ## 边界与职责
 
@@ -29,7 +27,7 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 
 - 基于冻结前的 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、请求 / 响应方向和分页负向字段。
+- 采用 YSS wrapper / 分页协议时，按 `yss-dto` wire profile 校验 `com.yss.cloud.dto.result` canonical 包、`YssResultMeta` 公共字段、具体 wrapper schema、请求 / 响应方向和分页负向字段；其他批准协议记录适用性及实际契约检查。
 - 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
 - 在 `docs/.scratch/<feature>/api/<feature>-validation.yaml` 持久化结构校验记录，并用 `scripts/verify-openapi-draft-validation-record` 复核当前 YAML SHA-256、锁定的 Redocly 版本、实际命令、退出码、执行时间和证据引用。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
@@ -61,8 +59,8 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 - P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
 - P0 写模型、配置模型或关键交互读模型没有追到 property path、嵌套形状、requiredness、约束、来源和 test seam；跨操作复用 schema 却没有证明省略与必填语义一致。
 - `$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` 作为客户端字段。
+- `scripts/verify-yss-dto-openapi-profile` 失败、profile 版本未记录，或采用 YSS wrapper 的 Draft 响应未按 profile 建模 `x-yss-response-wrapper`、`YssResultMeta` / `allOf` 和具体 `data` schema。
+- 新的 YSS wrapper 契约引入 `com.yss.cloud.dto.response`、把 Java 泛型文字当成 OAS schema、把全局 `code` 放宽为任意 object，或采用 YSS 分页协议的接口把 `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 的权威来源。

package/template/.codex/skills/yss-openapi-governance/references/governance-output.md

@@ -1,5 +1,7 @@
 ## 输出契约
 
+Wrapper 与分页检查按实际协议填写：采用 YSS 协议时记录 profile 符合性；下载、流式、回调或已批准分页例外记录协议依据、适用性和实际检查，不生成空 wrapper 或用不适用跳过审查证据。
+
 ```markdown
 ### Governance Result
 <Draft / Approved for Freeze / Blocked / JSON Exported>

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

@@ -15,9 +15,9 @@
    - 从 `.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 行为检查。
+   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）。普通采用 YSS wrapper 的接口检查 `x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema；下载、流式和第三方回调检查其批准媒体类型、状态、Header 和错误边界。按实际协议检查分页、幂等 / 乐观锁和契约测试 seam，不强套 wrapper 或豁免证据。
+   - 每个响应按实际协议落成具体 endpoint schema。采用 YSS wrapper 时，`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
+   - 采用 YSS wrapper 时，`code` 按 profile 只允许 `string | integer | null`，`dataType` 为 `string | null`；采用 YSS 分页协议时，`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`。

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

@@ -5,11 +5,11 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 
 # YSS Product Lifecycle
 
-合同阅读与托管更新：`scripts/contract view|render|check-views`；见 `.template-spec/process/contract-reading.md`。
+合同阅读与更新：`scripts/contract view|render|check-views`；见 `.template-spec/process/contract-reading.md`。
 
 五类机器资产默认 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`。
 
 ## 事实源
 
@@ -24,23 +24,25 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 | 影响面、裁剪与维护强度 | `.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
+scripts/query-lifecycle-context --work-unit work-unit.plan-requirements --check-skills
 ```
 
-`--include` 接受合同顶层键，非法输入失败。详见 `references/orchestration.md`。
+`--include` 限合同顶层键。调用前按 [来源与补装](references/matt-yss-adapter.md) 预检，在既有授权内补装并重验。
 
-按 `execution_efficiency` 合并查询、复用未变资料；仍核验当前资产、词汇和门禁，产品流转不重跑模板套件。
+按 `execution_efficiency` 复用入口、合并查询和未变资料，核验资产与门禁；见项目 `.template-spec/process/script-execution.md`。
 
 ## 入口与模式
 
 1. 严格解析 `yss-project.yaml`，不得按目录、Git remote 或占位符猜仓库身份。
-2. 判定影响面和最近可信阶段；完成须满足内容、审查、上游新鲜度和可读证据，文件存在不代表通过。
-3. 按合同 `request_triage` 选择 `route`、`orchestrate`、`resume`、`audit`；明确行动请求无需模式关键字，意图不明时只读 `route`。`modes`、门禁及授权边界仍适用。
+2. 判定影响面及最近可信阶段；完成须有内容、审查、新鲜上游和可读证据，文件存在不代表通过。
+3. 按 `request_triage` 选 `route`、`orchestrate`、`resume`、`audit`；行动请求无需模式关键字，意图不明只读 `route`。模式、门禁及授权边界仍适用。
 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) 与 `--include request_triage`。先查证据，只问下一动作所需缺口，不按问题长度追问。
+必须确认的未决项按 `planning.clarification_policy` 主动调用 `grilling`，见 [澄清](references/plan-requirements.md)。
+
+分诊见 [协议](references/request-triage.md) 与 `--include request_triage`；先查证据，再问必要缺口。
 
 ## 不可越过的边界
 
@@ -52,49 +54,53 @@ Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/pl
 
 不得越过命中的阶段、门禁、实现仓库准备或 Ticket 正式化。实现只接收绑定垂直切片、已批准且持久化、版本当前并通过完整 `ready-for-agent` 计算的合同；父 Ticket、`ready-for-human` 切片、`stale`、`drift`、`new_impacts`、`violation` 或缺失证据均阻断。实现仓库、脚手架、UI 还原、review input 和发布条件从对应合同子树查询，不在入口重复定义。
 
-聚合批准见 `gate_consolidation`。普通功能默认一个独立审查者，按能力缺口、冲突或外部制度增员；相邻检查组合审查、逐项留证。
+按 `gate_consolidation` 默认一名独立审查者，按能力缺口、冲突或外部制度增员；相邻检查组合、逐项留证。复审按 `review_input.rereview` 首轮完整、修复定向、当前候选重绑定，未知先调查。
 
-职责与后端终点见 `execution_scopes`，恢复、编译和派发须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
+职责及后端终点见 `execution_scopes`，恢复、编译、派发须复验。保留产品设计门禁，后端交付不等于业务完成或发布。
 
 ### 用户决定
 
-按角色表 `user_decision_policy` 和 `references/user-decisions.md` 先展示可审阅资产、范围、风险及后续动作，再取得提问者或其指定生物人的原始回复。数字人、超时和默认项不能代答。已有授权优先用 `continuation_ref` 核验延续；未知/实质变化或强制审批缺失才重新决定。缺陷和缺证据阻断，建议记待办；合同、验证及外部动作授权仍须满足。
+按角色表 `user_decision_policy` 与 `references/user-decisions.md` 展示资产、范围、风险、后续动作，再取得提问者或指定生物人的原始回复。数字人、超时、默认项不得代答。先验 `continuation_ref`；未知先调查，实质变化或缺强制审批时重新决定。缺陷/缺证据阻断，建议记待办；合同、验证、外部授权仍适用。
 
 ### 外部副作用与 Git
 
-生命周期批准、实现授权和自然语言意向不构成结构化 Git 授权。commit、push、远端仓库创建、发布及其他运行时外部副作用分别检查明确动作、范围和可读授权引用；缺失时保持外部状态不变。`git-submodule` 还必须遵守逐仓授权、非 detached HEAD 和先子仓后父仓 gitlink 的顺序。
+生命周期批准、实现授权、泛泛意向不构成 Git 授权。按 `references/user-decisions.md` 整理明确动作与范围的真实回复，无需重填字段。commit、push、其他外部动作分别核验；来源不可读、撤回、越界则不执行。`git-submodule` 逐仓授权、非 detached HEAD、先子仓后父仓 gitlink。
 
 ## 有界编排循环
 
-1. 从真实资产重建当前状态，查询当前 mode、stage、work-unit 及必要合同子树。
-2. 评估影响面、上游新鲜度、门禁和阻塞，选择第一个未阻塞工作单元；不把 `not-applicable` 当作豁免。
-3. 原生工作单元由主控持有正式资产；专项按结构化任务包派发，只调用合同允许的 model-invoked skill。
-4. `to-spec`、`to-tickets`、`implement` 等兼容入口只可由用户显式调用。主控预检输入、路径和门禁；入口按 `matt_invocation_boundary` 写入其产物并回交验收，不批准或改变 Ticket 就绪状态。原生资产仍归主控。
+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. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断独立工作。
+6. 按 `blocking_disposition` 自主处理阻塞；缺真实决定或新授权才展示资产后询问。独立工作继续，完成结论不新增暂停。
 
-每个 `project-instance` 工作单元批准或流转前，回写稳定术语到唯一根 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
+`project-instance` 批准或流转前按根 `AGENTS.md` 完成术语回写与 `context_reconciliation`；候选术语、错误路径、摘要漂移或冲突阻断。质量标准由 `engineering-baseline` 唯一定义，高风险反证按裁剪合同。
 
 ## 面向业务角色
 
 澄清目标、流程、责任、规则、范围和验收例子。业务总览引用权威资产，展示状态、未决项、责任人和下一步，不复制正文或新增门禁。
 
-Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `.template-spec/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
+Plan → Spec 写入前按 `.template-spec/plan/entry-review.md` 持久化审阅包，执行 `node scripts/verify-plan-spec-entry <state.yaml>`；缺项、过期或无真实回复阻断，独立调研继续。
+
+`checks.grill_exit=passed` 仅准备就绪；共同理解与当前 Plan 合并真实确认后，入口判定完整退出。
 
 ## 结果与暂停
 
-结构化结果保留模式、仓库身份、阶段/工作单元、影响面、资产/门禁/Ticket/Slice/合同状态、证据新鲜度、就绪、阻塞、本轮动作、下一单元、暂停理由、Ticket 同步和 Git checkpoint；用户说明按中文写作规范呈现。
+每轮返回/暂停按 `user_progress_report` 说明阶段及依据、结果、下一阶段/单元及条件、问题/阻塞、责任方、解除与复验、主控动作、用户决定。未知写“待核验”，负责人缺失写“未登记”；目标不代表批准，已授权修复继续。
+
+按 `workflow_execution_result` 与 `references/state-model.md` 记录状态、证据新鲜度、阻塞、动作、路由、Ticket / Git checkpoint。
 
-会签记录保留门禁 ID、`role_id`、`runtime_id`、文件路径、推荐答案和恢复动作；用户提示解释待决定事项与责任方。恢复前运行适用验证器。同一候选通过适用审查与 fresh verification 才可提出完成、合并或发布结论；发布仍须生物人决定。
+发送前核对状态、证据新鲜度、阻塞与结构化结果；见 [结果提示](references/orchestration.md#结果与友好提示)。会签保留门禁、角色/运行时、文件、推荐答案、恢复动作。恢复先验证；完成/合并/发布须同一候选通过适用审查和 fresh verification；发布须生物人决定。
 
-Plan / Spec / Design 追踪按 `.template-spec/process/stage-tracking.md`。
+Plan/Spec/Design 追踪见 `.template-spec/process/stage-tracking.md`。
 
-需求澄清读 [对账](references/plan-requirements.md)；外部输入读 [问卷](references/external-input-questionnaire.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`，只按显式候选计划处理，保留状态、批准依据和原文；不得推进阶段。临时输入与草稿放临时工作区，引用后按正式资产保留。
+资产整理及旧票迁移按 `.template-spec/process/feature-assets.md` 和显式计划保留状态、批准依据、原文，不推进阶段；被引用草稿按正式资产保留。
 
-既有 YSS 实例的模板版本升级、旧治理布局迁移或升级恢复路由到 `yss-harness-upgrade`，按 `.template-spec/process/harness-upgrade.md` 执行；不由升级动作推进产品阶段或重写历史批准。
+既有实例模板升级、旧布局迁移和升级恢复用 `yss-harness-upgrade`，遵循 `.template-spec/process/harness-upgrade.md`；不推进产品阶段或重写历史批准。

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

@@ -28,7 +28,7 @@ Implementation → Independent Review → Fresh Verification → Release
 5. 重新审查后优先恢复原 Ticket；仅在范围或验收目标根本变化时重建。
 6. 原 `not-applicable` 的条件被推翻时，改为 `missing` 或 `draft`。
 
-具体 `impact type → artifact/gate → direct/transitive → when` 以 `orchestration-contract.yaml` 为机器可执行事实。条件满足时，`direct` 节点直接标记 `stale`；`transitive` 节点仅在其依赖的 direct 节点发生语义变化时传播。条件不满足时保持原状态，尤其不得把 `not-applicable` 改成 `stale`。表中未列出的节点不传播；无法分类的变化暂停影响面裁决，不得猜测。
+具体 `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`。
 

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

@@ -1,5 +1,25 @@
 # Matt / YSS 工作流适配
 
+上游来源是 [mattpocock/skills](https://github.com/mattpocock/skills)。固定提交、原始哈希和实际生效的 YSS 适配哈希以根 `skills-lock.json` 为准；补装使用模板快照中的适配版，不直接覆盖为上游最新版本。
+
+项目实例按需分发：注册表中受支持的技能可能尚未安装；改名与别名由 `.template-spec/agents/yss-skill-registry.yaml` 解析；已退役名称按 `.template-spec/agents/skill-migrations.md` 重新路由。这三种情况不能混用，也不需要把整个上游仓库装进实例。
+
+## 工作单元技能预检与补装
+
+准备调用原生工作单元的专项技能前，运行：
+
+```bash
+scripts/query-lifecycle-context --work-unit work-unit.plan-requirements --check-skills --agent-runtime codex
+```
+
+运行时只在实例登记了唯一平台时可以省略；条件依赖用重复的 `--when <条件>` 传入。查询只检查当前工作单元和已触发依赖，不加载兼容入口的纯引用或整个角色技能包。普通查询仍不证明技能已安装。
+
+`skill_readiness` 为 `ready` 时退出 0；`missing` / `blocked` 时退出 2；非法输入或查询失败退出 1。技能可用不证明阶段批准、切片资格或任务完成。
+
+收到 `missing` 后，由 Agent 执行结果中的 `remediation.plan_command`，核对新增技能、路径和依赖。已有任务授权覆盖该范围且计划无冲突时执行 `apply_command`，利用现有事务刷新锁文件并校验实例；随后重新执行同一预检，通过后才调用技能。安装 user-invoked 技能不授予调用资格。
+
+`blocked` 中的受管文件丢失、哈希／投影漂移、同名路径冲突、运行时未配置、退役或外部技能缺失必须分别处理；CLI 快照不匹配时补装计划也会拒绝。不得自动覆盖、强制同步或扩展迁移范围。旧实例只读检查现有文件，缺失时按本家族 CLI 规划同步或迁移，不自动转换分发模式。
+
 Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS 专项 skills 决定如何符合工程规范。
 
 生命周期默认使用 `work_unit_routes.*.native`；下表中的 Matt flow 是 `work_unit_routes.*.compatibility` 显式兼容输入。兼容入口的正式资产由用户创建并回交生命周期验收，原生工作单元的正式资产由生命周期编排器创建。
@@ -15,7 +35,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 情形 | Matt flow | 生命周期验收 |
 |---|---|---|
 | 首次启用或配置缺失 | `setup-matt-pocock-skills`（用户显式） | `needs-human`，说明缺失项；用户完成 setup 后重新计算 readiness |
-| 需求澄清 | 原生 `work-unit.plan-requirements`，按需使用 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
+| 需求澄清 | 原生 `work-unit.plan-requirements`，按 `planning.clarification_policy` 主动调用 `grilling` 处理必须确认的未决决定，术语使用 `domain-modeling` | 逐项验收未决项和证据回流；完整退出联合当前 Plan 用户决定 |
 | 信息在其他人手中 | 生命周期外部输入问卷 | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `work-unit.plan-requirements` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder`（可选） | 仅在跨会话 / 跨 Agent 或 frontier 不清晰时启用；map 真正完成后 `handoff → to-spec` |
 | 技术或战略事实 | `yss-research`（`research` 为 deprecated alias） | `technical-evidence` 核验一手技术资料；`strategy-evidence` 为领域战略和阶段决策提供可审计证据；研究包不得自行修改或批准下游资产 |
@@ -33,7 +53,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 
 尽量不修改 Matt skill 以复制 YSS 规则。只有它违反模板硬门禁时才做最小兼容修改。
 
-实现合同编译器 只能返回 `draft`、`blocked` 或 `ready-for-lifecycle-review`，不得自行批准合同、设置 `ready-for-agent` 或宣布完成。`new_impacts`、`drift`、`violation`、越界路径或缺失实际验证会暂停当前工作单元，并由本编排器决定增量重路由、完整重路由或回到更早生命周期阶段。
+实现合同编译器 只能返回 `draft`、`blocked` 或 `ready-for-lifecycle-review`，不得自行批准合同、设置 `ready-for-agent` 或宣布完成。`new_impacts`、`drift`、`violation`、越界路径或缺失实际验证阻断依赖动作，由本编排器先调查实际变化及依赖，再修复、补证据或回到受影响生命周期工作单元；不因此默认全轴复审或向用户索取新决定。
 
 ## Workflow Execution Result
 
@@ -56,7 +76,7 @@ next_route: <next-work-unit-or-null>
 blocking_signals: []
 ```
 
-存在 `drift`、`new_impacts`、`violation`、`missing_evidence` 或 `stale_candidates`，以及证据缺失时，不得返回 `completed`；必须暂停并由编排器决定增量重路由、完整重路由或回到更早阶段。
+存在 `drift`、`new_impacts`、`violation`、`missing_evidence` 或 `stale_candidates`，以及证据缺失时，不得返回 `completed`；由编排器调查变化、受影响结论 / 行为及依赖，定向修复 / 重路由、复验并重绑定当前候选。专业等待自主派发并等待，缺真实决定或新授权才展示资产后询问，无依赖的已授权工作继续。
 
 实现合同编译器 状态映射为：`draft → completed`、`blocked → blocked`、`ready-for-lifecycle-review → needs-human`。这里的 `completed` 只表示 Matt 工作单元已产出可验收结果，不表示生命周期完成或可发布。
 
@@ -72,13 +92,15 @@ blocking_signals: []
 
 `grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `yss-research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
 
+按 `planning.clarification_policy` 主动开始必要澄清，调查、实验和专业审查分别取得证据，分轮仅询问前提已明确的必要决定。审阅包中的 `checks.grill_exit=passed` 表示澄清准备就绪；共同理解总述与完整当前 Plan 审阅包合并展示，由同一真实回复确认。入口联合准备检查与当前 `gate.plan-approved` 决定后才判断完整退出；回复独立保存，不回写审阅包或依据，不增加批准阶段。
+
 ## 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，让所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`） 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能缩小审查范围、另起通用审查 skill、由审查者改实现，或合并不同候选的结论。`violation` 类 finding 交实现者在原合同路径修复后全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。
+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，让所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`）消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空、专项覆盖缺失、未关闭 mandatory `violation`、适用行空白或摘要变化时返回 `blocked`，不能漏掉首轮适用项、另起通用审查 skill、由审查者改实现，或合并未重绑定的不同候选结论。`violation` 类 finding 交实现者在原合同路径修复，按差异、受影响结论 / 行为及依赖定向复审并重绑定；摘要变化、UI 或 `new_impacts` 不触发全轴默认或兜底，未知先调查。`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。
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。执行 commit 必须同时具备 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 必须同时具备 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。commit 与 push 分别检查，commit 授权不包含 push。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
-“然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
+按既有 [用户决定协议](user-decisions.md)，编排器可以把具体 Git 动作、仓库和改动范围明确的真实用户回复整理成上述三字段，并保留可读原始来源，不要求用户再填写内部字段。结合可读原始上下文，指向明确范围的“做完提交”可整理为 commit 授权；泛泛的“继续”、实现授权、当前分支或测试通过不能补足动作和范围。字段缺失、来源不可读、授权撤回或动作超出范围时不执行对应 Git 动作，只记录 checkpoint 判断；不得补造同意或扩大原回复范围。
 
 ## Setup readiness