create-yss-spec 2.1.3 → 2.1.5

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

@@ -119,7 +119,7 @@ description: "YSS 服务的后端开发脚手架框架和技术指南。在开
 - Infrastructure 是否只实现 Gateway / Repository，并隔离 PO、Mapper、SQL、外部系统客户端。
 - Web / Adapter 是否只做协议适配、鉴权上下文、参数校验、DTO/VO 转换和响应包装。
 - Application 是否承载用例编排、事务边界和跨聚合协调，不把领域规则下沉到 Controller 或 Mapper。
-- OpenAPI Draft / Freeze、ADR、测试 seam 和安全红线是否已经明确。
+- OpenAPI Draft / Freeze、ADR、测试 seam 和已批准的架构约束是否已经明确。
 
 ## 5. 常用命令
 

package/template/.claude/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py

@@ -321,9 +321,6 @@ class ScaffoldGenerator:
         required_files = [
             self.project_root / "pom.xml",
             self.project_root / f"{self.project_name}-bootstrap" / "pom.xml",
-            self.project_root
-            / f"{self.project_name}-bootstrap"
-            / "src/main/resources/smart-doc.json",
             self.project_root / "mvnw",
             self.project_root / ".yss/scaffold-generation.json",
         ]
@@ -331,9 +328,7 @@ class ScaffoldGenerator:
         if missing:
             raise FileNotFoundError(f"生成产物缺失: {', '.join(missing)}")
 
-        smart_doc_path = required_files[2]
-        json.loads(smart_doc_path.read_text(encoding="utf-8"))
-        manifest = json.loads(required_files[4].read_text(encoding="utf-8"))
+        manifest = json.loads(required_files[3].read_text(encoding="utf-8"))
         if (
             manifest.get("contract_id") != self.contract_id
             or manifest.get("contract_version") != self.contract_version
@@ -343,14 +338,6 @@ class ScaffoldGenerator:
             != ["./mvnw validate", "./mvnw test", "./mvnw package"]
         ):
             raise ValueError("脚手架生成元数据清单与当前批准合同或固定验证命令不一致")
-        bootstrap_pom = required_files[1].read_text(encoding="utf-8")
-        plugin_versions = re.findall(
-            r"<artifactId>smart-doc-maven-plugin</artifactId>\s*<version>([^<]+)</version>",
-            bootstrap_pom,
-        )
-        if plugin_versions != ["yss-4.0.0"]:
-            raise ValueError("smart-doc-maven-plugin 必须且只能使用 yss-4.0.0")
-
         binary_suffixes = {".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"}
         for path in self.project_root.rglob("*"):
             if not path.is_file() or path.suffix in binary_suffixes:
@@ -452,17 +439,10 @@ class ScaffoldGenerator:
                 / f"{self.project_name}-bootstrap"
                 / "src/main/resources/logback-spring.xml",
             ),
-            (
-                self.config_template_dir / "smart-doc.json.template",
-                self.project_root
-                / f"{self.project_name}-bootstrap"
-                / "src/main/resources/smart-doc.json",
-            ),
         ]
         self._render_and_write_templates(config_templates)
         print("  ✓ application.yml")
         print("  ✓ logback-spring.xml")
-        print("  ✓ smart-doc.json")
 
     def _generate_database_scripts(self):
         """只保留数据库目录布局，不生成业务表或初始化数据。"""

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

@@ -13,6 +13,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - 项目 token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`。
 - 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
 - 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
+- 原型阶段合同：`yss-prototype-stage`，用于统一跨 Agent 的原型资产、AntD 事实和浏览器验证证据。
 
 如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 token，必须读项目内 `docs/design/design.md`；若要执行评审或实现检查，再读 `references/design-system.md`。
 
@@ -21,7 +22,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
 2. 读取已有资产：`docs/design/design.md`、相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
 3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
-4. 若是产品设计阶段，配合 `product-design-prototype` 产出页面、流程、状态矩阵和 OpenAPI 反推清单。
+4. 若是产品设计阶段，先使用 `yss-prototype-stage`；Codex 以 `product-design:index` 为主入口，其他 Agent 必须交付等价合同资产和证据。
 5. 若是前端实现阶段，配合 `yss-ui`、`yss-components`、`yss-formily`、`yss-page-module-development`，但本技能负责风格与体验一致性门禁。
 6. 若发现现有设计系统文档不足，先更新 `docs/design/design.md`，再让实现或评审引用该文档。
 
@@ -76,15 +77,15 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 
 | 场景 | 配合技能 |
 | --- | --- |
-| Spec 后做页面 / 原型 / 交互说明 | `product-design-prototype` |
+| Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
-| 低保真评审通过后的高保真 HTML 原型 | `high-fidelity-html-prototype` |
-| 低保真线框或流程图 | `wireframe-prototype` / `excalidraw-diagram-generator` |
+| 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
+| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 / `excalidraw-diagram-generator` |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
 | Ant Design v6 组件 / token / demo 查询 | 官方 `@ant-design/cli` / `https://ant.design/docs/react/for-agents` |
-| API 契约 / 接入 | `api-integration` / `yss-openapi` |
+| API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
 
 ## 更新设计系统
 

package/template/.claude/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -21,7 +21,9 @@ branch: template
 - `app_name`：应用名。
 - `microapp_name`：微应用注册名。
 - `base_route`：基础路由。
-- `openapi_source`：OpenAPI 文件、URL 或 Harness spec 路径。
+- OpenAPI Freeze 记录：已批准的冻结 YAML 版本和引用。
+- OpenAPI JSON 派生记录：`docs/.scratch/<feature>/api/<feature>-json-export.md`，包含 YAML / JSON SHA-256、Redocly CLI 版本和 lockfile 引用。
+- 冻结 JSON 产物：`docs/.scratch/<feature>/api/<feature>.json`；这是唯一允许交给既有前端代码生成流程的上游产物。
 - `target_git_url` 或 `output_dir`：目标实现仓库或本地输出目录。
 - `package_manager`：默认 pnpm。
 - `init_git`：是否初始化 Git；默认必须用户明确确认。
@@ -33,9 +35,10 @@ branch: template
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
-6. 配置 OpenAPI source，并准备 Orval 生成命令。
-7. 记录验证命令：`pnpm install`、`pnpm lint:check`、`pnpm type-check`、`pnpm build`、`pnpm generate:api`。
-8. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
+6. 核验 OpenAPI Freeze 记录和 OpenAPI JSON 派生记录；通过批准的 Cross-repo 子合同或项目脚本，将记录中的 JSON 原样物化到 `<frontend>/openapi/openapi.json`，并再次核对 SHA-256。
+7. 保持模板既有的前端代码生成配置不变；本 Harness 只将 SHA-256 一致的 JSON 原样交给既有前端代码生成流程，不修改该配置、不在此仓库执行生成，也不设置生成 CI 门禁。目标前端项目在需要时手动运行其既有命令。
+8. 记录目标前端项目的 install / lint / type-check / build 命令，以及既有客户端生成命令（如有）；生成命令仅作为目标项目的手动验证项。
+9. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
 
 ## Expected Template Shape
 
@@ -55,7 +58,9 @@ packages/package.json
 
 - 不直接创建远端 Git 项目，除非用户明确要求。
 - 不推送、不创建 MR / PR，除非用户明确要求。
-- 不绕过 OpenAPI Draft / Freeze；API client 生成必须有可追溯 OpenAPI source。
+- 不绕过 OpenAPI Draft / Freeze；API client 只消费与 OpenAPI JSON 派生记录 SHA-256 一致的冻结 JSON。
+- 不接受任意 URL、未冻结 YAML、后端运行时输出或手工 JSON 作为既有前端代码生成流程的输入。
+- 不修改模板既有的代码生成配置，也不把客户端生成加入 CI。
 - 不得把 `apps/frontend/` 容器根登记为项目根；Harness 内每个前端项目必须有独立的 `apps/frontend/<project>/` 路径。
 - 不把模板示例页面当作业务功能交付。
 - 生成后仍需使用 `yss-page-module-development`、`yss-components`、`api-integration` 等专项 skill 实现业务页面。
@@ -65,6 +70,7 @@ packages/package.json
 - 前端工程生成位置或目标仓库信息。
 - 模板来源和 commit / branch 证据。
 - 替换参数清单。
-- install / lint / type-check / build / generate:api 命令。
+- install / lint / type-check / build 命令，以及目标前端项目既有的手动客户端生成命令（如有）。
+- OpenAPI Freeze 记录、OpenAPI JSON 派生记录、JSON SHA-256 和 `openapi/openapi.json` 物化证据。
 - Harness 实现仓库登记草案。
 - 未覆盖项和 `TODO-HUMAN-REVIEW`。

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

@@ -1,34 +1,33 @@
 ---
 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, permissions, pagination, optimistic locking, security red lines, and contract test seams.
+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 is not the smart-doc / Orval generation workflow.
+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`.
+- 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, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
 
 ## Review Flow
 
-1. Consume fresh automated evidence for YAML parsing, `$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.
-3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes.
+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, `SingleResult<T>` for single objects, `MultiResult<T>` for non-page lists, `PageResult<T>` for pagination, and stable DTO/schema names.
-6. Check error and permission contracts: field-level errors, model-level errors, 403 no-data leakage, disabled reasons, gate failures, and conflict responses.
-7. Check security red lines: authentication/authorization, SQL/DDL draft boundaries, downloads, audit/logging, sensitive field handling, and human-review items.
-8. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+6. 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.
+7. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
 
 ## Automation Boundary
 
-- Automated checks own YAML syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
-- Human or independent semantic review owns P0 traceability, page-action coverage, permission and error behavior, concurrency/idempotency, security red lines, scope downgrades, and contract-test seams.
+- Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
+- 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.
 
@@ -40,8 +39,8 @@ Block if any of these are true:
 - 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 YSS `PageResult<T>` or documented exception.
-- Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, permission, and optimistic locking.
-- Security red lines are unmarked or the Draft exposes execution endpoints for SQL/DDL migration.
+- 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
 
@@ -61,14 +60,11 @@ Block if any of these are true:
 ### YSS Baseline
 - <response wrappers, DDD boundary implications, implementation feasibility>
 
-### Security Review
-- <red lines and human-review items>
-
 ### Contract Test Checklist
 - <minimum contract tests before OpenAPI Freeze>
 
 ### Next Action
-- <return to OpenAPI Draft / enter Engineering Baseline / architecture design>
+- <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,145 +1,120 @@
 ---
 name: yss-openapi-governance
-description: Use when Govern and lint YSS OpenAPI design-time contracts with Spectral or Redocly CLI before OpenAPI Freeze. Use when creating or maintaining organization-level OpenAPI style rules, validating `docs/.scratch/<feature>/api/<feature>.yaml`, defining API naming/error/pagination/permission conventions, adding contract-test checklist rules, or checking generated smart-doc output against YSS API governance. Do not use for smart-doc or Orval generation; use yss-openapi for that implementation workflow.
+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
 
-Use this skill to make OpenAPI contracts consistent, lintable, and reviewable before implementation. This is the ruleset and governance layer for `docs/.scratch/<feature>/api/<feature>.yaml`; it is not the smart-doc / Orval generation workflow.
+本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
 
-## Boundary
+```text
+Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生物 → 下游既有前端代码生成流程
+```
 
-Use `yss-openapi-governance` for:
+`docs/.scratch/<feature>/api/<feature>.yaml` 是唯一权威的 OpenAPI 3.1 契约。JSON 只能由冻结后的 YAML 可复现地产生，用于前端代码生成或分发；不得手写、不得反向覆盖 YAML、不得把运行时代码当成设计契约来源。
 
-- Defining or applying reusable OpenAPI style rules.
-- Running Spectral or Redocly CLI against `docs/.scratch/<feature>/api/<feature>.yaml`.
-- Checking YSS response wrappers, error contracts, pagination, permissions, security red lines, and contract-test seams.
-- Comparing generated `openapi.json` against frozen design rules when backend code is already implemented.
-- Writing or updating governance notes under `docs/.scratch/<feature>/api/`, `docs/.scratch/<feature>/architecture/`, or the active Spec Delta design.
+## 边界与职责
 
-Use other skills for:
+使用 `yss-openapi-governance`：
 
-- `yss-openapi`: generate `target/openapi/openapi.json` from implemented controllers/DTOs and refresh Orval clients.
-- `yss-openapi-draft-review`: perform fail-closed semantic review against Spec, prototype, page actions, P0 coverage, and architecture readiness.
-- `docs/.scratch/<feature>/spec-delta/` and `to-tickets`: formalize behavior changes and implementation tickets after the contract is frozen.
+- 基于冻结前的 Spec、产品设计、架构约束创建或更新 `docs/.scratch/<feature>/api/<feature>.yaml`。
+- 保证 YAML 是单一 YAML document、根节点为 `openapi: 3.1.0`，且不把 `pipeline`、`stage`、`status`、`owner` 等生命周期元数据写入 OpenAPI 根节点。
+- 运行受项目 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`。
 
-## Preferred Tooling
+不使用本 skill 来替代：
 
-Prefer Spectral when the repo needs a portable, custom OpenAPI ruleset:
+- `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
+- `api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
+- `to-tickets`：在 Freeze 后正式化垂直切片。
 
-```bash
-npx --yes @stoplight/spectral-cli lint -r .spectral.yaml docs/.scratch/<feature>/api/<feature>.yaml
-```
+## 受控工具链
 
-Prefer Redocly CLI when the repo already uses Redocly for lint, bundle, docs, or CI:
+在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
 
 ```bash
-npx --yes @redocly/cli lint docs/.scratch/<feature>/api/<feature>.yaml
+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
 ```
 
-If neither tool is configured, do not invent project policy silently. Create or propose a minimal config and mark it as draft until reviewed. Use Spectral as the default baseline for custom YSS rules because its YAML rulesets are easy to version and extend.
-
-## Governance Flow
-
-1. Locate contract inputs.
-   - Check `docs/.scratch/<feature>/api/<feature>.yaml` first.
-   - If only generated contracts exist, inspect `*/target/openapi/openapi.json` or frontend `openapi/openapi.json` as implemented evidence, not as design authority.
-   - Confirm whether the task is pre-freeze design governance or post-implementation conformance checking.
-
-2. Detect existing lint configuration.
-   - Look for `.spectral.yaml`, `.spectral.yml`, `redocly.yaml`, `redocly.yml`, `package.json` scripts, or CI jobs.
-   - Reuse the existing toolchain and scripts when present.
-   - If both Spectral and Redocly exist, run the repo's documented CI path first, then targeted local lint.
-
-3. Validate baseline OpenAPI correctness.
-   - Parse YAML/JSON successfully.
-   - Check OpenAPI version, `$ref` resolution, duplicate `operationId`, path parameter coverage, unused schemas, and invalid examples.
-   - Bundle or dereference only when needed for tooling; keep source files maintainable.
-
-4. Apply YSS API governance rules.
-   - Paths are versioned under `/api/v1/` unless a documented exception exists.
-   - Operations use stable `operationId` values suitable for Orval/client generation.
-   - Single-object responses use `SingleResult<T>`.
-   - Non-page list responses use `MultiResult<T>`.
-   - Page responses use `PageResult<T>` and expose the project's standard page request/response fields.
-   - Error responses include a consistent envelope, machine-readable code, human-readable message, and field/model-level validation shape where applicable.
-   - Permission failures avoid data leakage; 403/disabled-action behavior is explicit.
-   - Mutating operations define idempotency, optimistic locking, or conflict semantics when repeated submission or concurrent edits are possible.
-   - Download, upload, export, import, audit, sensitive data, SQL, DDL, authentication, authorization, and encryption surfaces are marked for human/security review when they touch AGENTS.md safety red lines.
-   - Contract-test seams are named for each P0 workflow and critical error path.
-
-5. Produce governance output.
-   - For quick checks, report lint command, pass/fail result, and blocking findings with file paths.
-   - For durable decisions, write or update a Chinese governance artifact under `docs/.scratch/<feature>/api/` or `docs/.scratch/<feature>/architecture/`.
-   - For active Spec Delta work, reference `docs/.scratch/<feature>/spec-delta/` and keep rules aligned with the related design, task, and spec artifacts.
-
-## Minimal Spectral Baseline
-
-When the repo lacks a ruleset and the user asks to add one, start with a small `.spectral.yaml` that extends the OpenAPI baseline and encodes only stable YSS rules. Keep controversial product semantics in review checklists until the team agrees.
-
-```yaml
-extends:
-  - spectral:oas
-
-rules:
-  yss-paths-versioned:
-    description: YSS API paths should be versioned under /api/v1.
-    message: "Path '{{property}}' should start with /api/v1/ or document an exception."
-    severity: warn
-    given: "$.paths[*]~"
-    then:
-      function: pattern
-      functionOptions:
-        match: "^/api/v1/"
-
-  yss-operation-id-required:
-    description: Operation IDs must be stable for generated clients and contract tests.
-    severity: error
-    given: "$.paths[*][*]"
-    then:
-      field: operationId
-      function: truthy
-
-  yss-tags-required:
-    description: Operations should be grouped by bounded context or module.
-    severity: warn
-    given: "$.paths[*][*]"
-    then:
-      field: tags
-      function: truthy
-```
+默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
 
-Do not overfit Spectral rules when human review is better. For example, "uses `SingleResult<T>` correctly" may require schema convention inspection and YSS context; encode it only if the repo has stable wrapper schema names.
+`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
 
-## Blocking Rules
+## 治理流程
 
-Block OpenAPI Freeze if any of these are true:
+1. **建立或读取 YAML Draft**
+   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
+   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
+   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
 
-- The contract cannot be parsed or linted with the repo's configured tool.
-- A public operation lacks `operationId`, response schema, or error contract.
-- Pagination, list, or single-object response wrappers contradict YSS baseline without a documented exception.
-- Permission, validation, conflict, import/export, upload/download, or sensitive-data behavior is ambiguous.
-- A safety-red-line area is implemented as final contract without `TODO-HUMAN-REVIEW` or equivalent review record.
-- Contract tests cannot be identified for P0 flows and critical error paths.
+2. **运行结构与治理校验**
+   - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
+   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
+   - 检查 `/api/v1/` 版本策略（或记录例外）、`SingleResult<T>` / `MultiResult<T>` / `PageResult<T>`、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
 
-## Output Contract
+3. **独立 Draft Review 与 Freeze**
+   - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
+   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
 
-```markdown
-### Governance Result
-<Pass / Blocked / Draft Rules Proposed>
+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 交给 `api-integration` 与目标前端实现仓库。
+   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
+   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
+   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
 
-### Tooling
-- <Spectral/Redocly command used or proposed>
+## 阻断规则
 
-### Blocking Findings
-- <file:line grounded finding>
+阻断 OpenAPI Freeze 或 JSON 导出，若：
 
-### Rule Changes
-- <ruleset/config changes made or proposed>
+- YAML 不是单一 OAS 3.1 document，或其根节点混入生命周期元数据。
+- YAML / `$ref` / lint 不通过，operationId 不稳定或不唯一，或路径参数、schema、examples 无法解析。
+- P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
+- `$ref` 超出允许范围，或转换器版本、lockfile、命令、输入 YAML 无法识别。
+- Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
+- JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。
 
-### YSS Contract Checks
-- <response wrappers, errors, pagination, permissions, security red lines, contract tests>
+## 输出契约
 
-### Next Action
-- <fix draft / run yss-openapi-draft-review / enter OpenAPI Freeze / compare generated contract>
+```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>
+- `$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 +1,4 @@
 interface:
   display_name: "YSS OpenAPI Governance"
-  short_description: "Lint and govern YSS OpenAPI drafts"
-  default_prompt: "Use $yss-openapi-governance to lint and govern a YSS OpenAPI draft before freeze."
+  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

@@ -12,7 +12,7 @@ YSS 产品研发的全生命周期主控编排器。它决定阶段、条件门
 1. 读取根目录 `yss-project.yaml`；非法或缺失时停止并进入迁移检查。
 2. 读取 `CONTEXT.md`、相关 ADR、父 Ticket/checkpoint、当前资产与 tracker 配置。
 3. `template-source` 只走模板维护流程；不得生成具体产品 Spec、原型、OpenAPI 或切片 Ticket。
-4. `project-instance` 以 `docs/process/lifecycle-artifact-map.md` 和 `docs/process/harness-process-tailoring.md` 为阶段、门禁和裁剪事实来源。
+4. `project-instance` 以 `docs/process/lifecycle-registry.yaml`、由其派生的 `docs/process/lifecycle-artifact-map.md` 和 `docs/process/harness-process-tailoring.md` 为阶段、门禁和裁剪事实来源。
 
 YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask-matt` 仅在用户显式调用时作为 Matt 通用导航，且不得修改 Matt skills。
 
@@ -29,7 +29,8 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 
 ## 核心规则
 
-- 保留 8 个主阶段；21 个门禁全部按影响面条件强制。命中项必须达到 `approved`，未命中项记录 `not-applicable` 和原因。
+- 保留生命周期注册表定义的主阶段；其中条件门禁全部按影响面强制。命中项必须达到 `approved`，未命中项记录 `not-applicable` 和原因；产物、工作单元和证据不得被统称为门禁。
+- 安全 / 权限不设独立生命周期资料、专属门禁或 `not-applicable` 记录。只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁；普通 action 注册、沿用认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不触发安全 / 权限流程。
 - 有效 `yss-project.yaml` 存在时，`ask-matt` 和 `setup-matt-pocock-skills` 只能作为子流程；最终入口、仓库身份和模式裁决归本编排器。
 - `template-source` 命中产品 flow 时必须返回 `blocked`（`template-source-product-artifact-forbidden`），不得继续到产品资产或 Ticket 生成。
 - 文件存在不等于就绪。按内容、审查结论和上游新鲜度评估资产。
@@ -37,20 +38,23 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - 上游变化按依赖图精准传播 `stale`；不要无条件重跑完整阶段。
 - Matt 五态保持原义。只有解除阻塞、门禁通过且可直接实现的垂直切片才能使用 `ready-for-agent`。
 - YSS active 调用 `to-spec` 时，必须把 Matt 独立 flow 的 `ready-for-agent` 发布提示归一化为 Spec `ready-for-human`；不得把 Spec 初稿当作可直接实现的 Ticket。
+- YSS active 调用 `to-tickets` 时，新建垂直切片统一写为 `ready-for-human`；只有本编排器复算完整 `ready-for-agent` 公式后才能提升，Matt 的通用默认标签不得提前覆盖生命周期状态。
 - `orchestrate`/`resume` 连续执行安全工作单元，直到人工门禁、真实阻塞、新授权、实现/发布裁决或专项失败。
-- 进入实现后继续主控，通过 `yss-router`、`implement`、`tdd` 和 YSS 专项 skills 执行；独立审查和 fresh verification 后才能作完成判断。
-- 原型确认 → 后端脚手架：当 YSS 高保真原型已经完成 Prototype Review、AntD CLI 校验和用户确认，且 backend `scaffold_status=required` 时，先完成工程基线，由 `yss-router` 编译脚手架受控生成工作单元合同，经生命周期编排器批准并持久化后，才使用 `yss-ddd-scaffold-generator` 生成后端骨架；随后由 `yss-backend-scaffold-parent` 校验并重新进入 `yss-router`，不得先写业务代码。
+- 进入实现后继续主控，通过 `yss-router`、`implement`、`tdd` 和 YSS 专项 skills 执行；独立审查和 fresh verification 后才能作完成判断。只有工作单元真实触碰当前用户、审计、加密或明确的权限业务行为时，才增加 `yss-userinfo`、`yss-audit-log`、`yss-security-algorithm` 等专项依赖。
+- 原型确认 → 后端脚手架：命中产品设计影响时，先按 `yss-prototype-stage` 形成交互说明、独立 Prototype Review、高保真 HTML、AntD CLI 与浏览器验证、用户确认；只有 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation` 均满足时，才能进入下游。若 backend `scaffold_status=required`，随后先完成工程基线，由 `yss-router` 编译脚手架受控生成工作单元合同，经生命周期编排器批准并持久化后，才使用 `yss-ddd-scaffold-generator` 生成后端骨架；随后由 `yss-backend-scaffold-parent` 校验并重新进入 `yss-router`，不得先写业务代码。
 - 所有后续生成的后端代码都必须消费生命周期批准、已持久化且版本当前的 Slice Implementation Contract，绑定最小 YSS skill 闭包、允许写路径、证据文件和 YSS Skill Execution Result；没有这些证据时必须阻断。
 - Harness 内承载运行时代码时，项目路径策略固定为 `apps/backend/<project>/` 和 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅是项目容器，`app/backend/`、`app/frontend/` 及其子路径禁止生成。外部实现仓库不强制使用该目录，但必须登记真实项目根路径并写入合同。
 - Setup readiness 每个任务只评估一次并在本轮缓存；只有 tracker、主远端、真实标签或配置变化时重查。
 - Ticket tracker 支持 `local-markdown`、GitHub 和 GitLab；模板默认 `local-markdown`，以 `docs/.scratch/<feature>/` 完整功能包为主载体。Git remote 只代表代码托管，不能覆盖已持久化的 tracker 选择；Local 主 tracker 不要求远程 Ticket。根 `.scratch/` 与 `docs/requirements/tickets/` 只作为旧路径迁移来源。
 - 小改动和中等变更允许同一独立执行者完成 Review 与 fresh verification；该执行者不得是实现者。新模块、高风险或职责冲突时拆分 Reviewer 与 Verifier。
+- 进入 `code-review` 前必须持久化或明确传入 `review_mode`、`review_base_ref`、`candidate_snapshot_ref`、`candidate_digest` 和完整候选引用；`worktree` 模式必须一次捕获 committed、staged、unstaged、untracked，并让两个 Reviewer 消费同一快照，不能用只看 `HEAD` 或实时变化的 diff 宣称已审查。候选 manifest 和 `yss-worktree-candidate-v1` 不可变摘要流以 `orchestration-contract.yaml.review_input` 为唯一机器契约。
+- 实现授权不包含 Git 授权。只有用户分别明确给出值为 `true` 的 `commit_authorized` / `push_authorized`、非空 scope 和对应 `*_authorization_ref` 时才执行动作；缺失时只记录 checkpoint 判断，不得把 `implement`、`orchestrate`、当前分支或负责人要求解释成隐含授权。
 - 连续自动推进期间累积 Ticket/Git 证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint；不为每个连续经过的概念阶段重复写同类记录。
 - 跨线程、仓库、原型分支或上下文边界时使用 `handoff` 或等价记录。
 - 在 Matt 阶段边界（phase boundary）先按 `Continue → /clear → /handoff → subagent → /compact` 判断上下文动作；只在 checkpoint 记录可选 `phase_boundary` 证据，不新增生命周期状态。
 - `to-questionnaire` 进入结构化 `external-input-required` 暂停；回答回流后必须重新分类影响面并更新权威资产，不能直接恢复下游实现。
 - `wait-what` 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` 状态；`wizard` 只处理人工才能完成的步骤，默认临时使用，秘密值不得进入持久化输出。
-- Matt `prototype` 是保留在 `prototype/<name>` 分支的单文件可分享 HTML 主来源；YSS 高保真 HTML 原型仍必须经过 Prototype Review、AntD CLI 校验和用户确认，两者不得互相替代。
+- Matt `prototype` 是保留在 `prototype/<name>` 分支的单文件可分享 HTML 主来源；YSS 高保真 HTML 原型仍必须经过 Prototype Review、AntD CLI、浏览器验证和用户确认，两者不得互相替代。
 - Matt skill 返回结果必须先归一化为 `Matt Skill Result`；`drift`、`new_impacts`、`violation`、`stale_candidates`、缺失证据或不完整结果不得推进为 `completed`。
 
 ### 原型完成后的后端脚手架与代码生成边界
@@ -62,15 +66,17 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - `yss-ddd-scaffold-generator` 必须读取已持久化的结构化脚手架合同 JSON，并校验 `status=approved`、当前版本、主 skill、`controlled-generation` 和固定验证命令；只传任意字符串引用不得放行。
 - 生成项目必须包含 `.yss/scaffold-generation.json`，回勾实际使用的合同 ID、版本、Router draft 引用、生命周期批准引用、持久化引用、生成输入、受控模式和固定验证命令；元数据清单缺失或过期时阻断后续 Router。
 - 三条 `./mvnw` 命令必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的命令、输出目录存在或“生成成功”都不构成验证证据。
-- 脚手架只生成多模块工程结构、POM、配置、Wrapper、Smart Doc 和经验证的机械模板；不得生成或承载领域规则、状态机、权限、事务、复杂查询、错误映射或用户可见业务行为。
+- 脚手架只生成多模块工程结构、POM、配置、Wrapper 和经验证的机械模板；不得生成或承载领域规则、状态机、权限、事务、复杂查询、错误映射或用户可见业务行为。
 - 该生命周期脚手架工作单元必须关闭 `--with-example`，不得把 User CRUD 或业务字段伪装成样板；目标目录非空时 `--force` 默认阻断，只有覆盖范围、备份、回滚点和明确批准全部进入合同后才能另行审查。
 - `scaffold_status=existing` 或 `initialized` 时不重复全量生成，但仍须完成 `yss-backend-scaffold-parent` 基线证据、Wrapper 校验和 `yss-router` 合同重编译。
 - 脚手架完成不等于实现仓库接入、架构放行、契约批准或 `ready-for-agent`。后续每一个 Agent / generator 写入的后端代码都必须绑定批准合同和对应 YSS skill；业务行为只能使用 `behavior-tdd`，机械生成才可使用 `controlled-generation`。
 
 | 压力诱因 | 统一裁决 |
 |---|---|
+| “普通 action、SQL / DDL 或下载也要补安全姿态吗” | 不补。没有明确的安全 / 权限行为需求时只按实际 API、Data 或工程影响推进；明确改变相关行为时也只复用普通产物和门禁。 |
+| “延期项先不写责任人和目标版本，之后再补” | 阻断 `seam-deferred`；必须写风险、责任人、后续 Ticket、验证计划和目标版本 / 发布日期。 |
 | “脚手架本来就是 YSS，先生成代码再补合同” | 先阻断；Router draft 不能批准合同或替代生命周期放行。 |
-| “`./mvnw validate` 已通过，直接继续最省时间” | 只证明工程基线可验证，不证明业务、权限、事务或契约已获批；三条实际命令的结果还必须进入 Execution Result。 |
+| “`./mvnw validate` 已通过，直接继续最省时间” | 只证明工程基线可验证，不证明业务、事务或契约已获批；三条实际命令的结果还必须进入 Execution Result。 |
 | “后续代码也是生成物，不需要重新路由” | 只要写入业务代码，就必须重新消费当前 Slice Implementation Contract 和 YSS skill 闭包。 |
 | “发布窗口快结束了，可以把业务字段放进脚手架” | 时间、上级要求、已有产出和演示压力都不能放宽禁止模式；必须拆为 `behavior-tdd` 工作单元。 |
 

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

@@ -16,7 +16,7 @@ Implementation → Independent Review → Fresh Verification → Release
 
 ## 传播算法
 
-1. 分类变化：文案、UI 状态、权限、API schema、状态机、数据模型、服务边界、NFR、部署、安全。
+1. 分类变化：文案、UI 状态、API schema、状态机、数据模型、服务边界、NFR、部署。
 2. 只遍历与变化类型相关的边。
 3. 受影响下游先标记 `stale`；不要删除或立即重建。
 4. 移除相关切片的 `ready-for-agent`，直到必要门禁重新为 `approved/not-applicable`。
@@ -27,6 +27,6 @@ Implementation → Independent Review → Fresh Verification → Release
 
 每个 `stale` 节点必须记录 `stale_by`、影响类型、证据引用和重新批准条件。重新批准 direct 节点后，逐个重新核验 transitive 节点；只有其全部受影响上游恢复为 `approved/not-applicable` 且本节点重新验证通过，才能移除 `stale`。
 
-权限/状态机变化通常影响 Spec/Spec Delta、页面权限状态、OpenAPI security/errors、Design Review、Ticket 验收和测试映射；不会自动使竞品情报或完整业务架构失效。
+明确写入需求的认证、授权、租户隔离、敏感数据或合规行为变化不使用独立影响类型；按它实际改变的 UI 状态、API schema、状态机、数据模型或服务边界传播。普通 action 注册、SQL / DDL / 迁移和上传 / 下载只使用既有技术影响类型，不增加安全 / 权限传播。
 
 OpenAPI Freeze 后发生上游变化时，不得仅因父 Ticket 仍写阶段 6 就继续实现。先做影响分析，再精准更新相关资产和门禁。

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

@@ -20,7 +20,7 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
 | Spec 综合 | `to-spec` | 初稿进入 `ready-for-human`，不得直接实现 |
-| 切片 | `to-tickets` | 仅在冻结/无影响记录后拆垂直切片 |
+| 切片 | `to-tickets` | 仅在冻结/无影响记录后拆垂直切片；初始角色为 `ready-for-human` |
 | 实现 | `implement`、`tdd` | `yss-router` 编译 Slice Implementation Contract 草案；本编排器核验并持久化后才执行，专项 Execution Result 返回后再次核验 |
 | Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
 | 审查 | `code-review` | 唯一默认代码审查入口；审查者独立，结合 Spec、仓库治理规则和 YSS 标准 |
@@ -61,9 +61,15 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 | Matt flow | 进入条件 | 生命周期结果 |
 |---|---|---|
 | `to-spec` | `grill-with-docs` 已满足退出条件，且不存在未回流的 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | Spec 初稿为 `ready-for-human`，不等于批准 |
-| `to-tickets` | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 只能生成垂直切片 Ticket |
+| `to-tickets` | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 只能生成垂直切片 Ticket；YSS active 的 `to-tickets` 初始统一为 `ready-for-human` |
 | `implement` | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 单会话实现同样适用，不得绕过门禁 |
 
+## 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`。`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 复核摘要未变化。缺少输入、候选为空或摘要变化时返回 `blocked`，不能缩小审查范围或合并不同候选的结论。
+
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
+
 ## Setup readiness
 
 编排器先做幂等 readiness 检查，再决定是否调用 `setup-matt-pocock-skills`。检查结果只能是：