create-yss-spec 2.1.3 → 2.1.5

package/template/docs/process/lifecycle-registry.yaml

@@ -0,0 +1,289 @@
+schema_version: 1
+registry_id: yss.lifecycle
+status: shadow
+description: >-
+  YSS 生命周期结构化事实源。Phase 1 以 shadow/check 方式派生结构表并校验漂移，
+  不切换任何运行时状态 schema 或人工批准语义。
+id_policy:
+  pattern: '^(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$'
+  published_ids_immutable: true
+  baseline: docs/process/lifecycle-registry-baseline.json
+  deprecated_ids: []
+
+stages:
+  - id: stage.entry-triage
+    name: 入口分诊
+    goal: 确认仓库身份、问题范围和影响面。
+    exit_criteria: yss-project.yaml 合法，影响面和最近可信阶段可解释。
+  - id: stage.discovery
+    name: Discovery
+    goal: 澄清问题、用户、约束和机会。
+    exit_criteria: 问题边界、关键假设和待确认项已记录。
+  - id: stage.spec-architecture
+    name: Spec / 功能架构
+    goal: 固化解决方案和功能边界。
+    exit_criteria: Spec 基线和功能边界可审查。
+  - id: stage.product-design
+    name: 产品设计
+    goal: 在存在产品设计影响时校准页面流和状态。
+    exit_criteria: 命中的设计门禁通过；未命中项记录 not-applicable 及原因。
+  - id: stage.system-data-engineering
+    name: 系统 / 数据架构与工程契约
+    goal: 固化系统、数据、工程基线和 API 契约。
+    exit_criteria: 受影响工程契约冻结或记录无 API 影响；required 脚手架证据齐全。
+  - id: stage.ticket-formalization
+    name: Ticket 正式化
+    goal: 将冻结范围拆为可追踪的父 Ticket 和垂直切片。
+    exit_criteria: 工作单元窄、依赖清晰、验收和测试 seam 可执行。
+  - id: stage.vertical-slice-implementation
+    name: 垂直切片实现
+    goal: 以批准合同驱动 TDD 实现和跨仓库协作。
+    exit_criteria: 允许写路径、禁止模式、证据和验证命令全部满足。
+  - id: stage.verification-release-retrospective
+    name: 验证 / 发布 / 复盘
+    goal: 完成 fresh verification、发布和回顾。
+    exit_criteria: 所有命中门禁通过，人工审查点已完成，checkpoint 可追溯。
+
+evidence:
+  - id: evidence.impact-assessment
+    name: 影响面分析记录
+    description: 受影响仓库、资产、风险与最近可信阶段。
+  - id: evidence.repository-identity-check
+    name: 仓库身份校验结果
+    description: yss-project.yaml 的合法性与 repository_mode 裁决。
+  - id: evidence.approval-record
+    name: 人工批准记录
+    description: 对需要人工批准的 Spec、设计、契约或发布裁决的可追溯记录。
+  - id: evidence.design-review-result
+    name: 设计审查结果
+    description: API、架构或产品设计审查意见及处理结果。
+  - id: evidence.prototype-review-result
+    name: 原型评审结果
+    description: 低保真页面、流程、状态与 API 反推的独立评审结论和阻断项。
+  - id: evidence.antd-cli-validation
+    name: Ant Design CLI 校验证据
+    description: 设计语言、组件、demo、token、semantic 与 lint 的实际 CLI/目标版本和可读输出引用。
+  - id: evidence.browser-prototype-verification
+    name: 浏览器原型验证证据
+    description: 高保真原型的非空渲染、主流程、异常状态、视口和控制台验证记录。
+  - id: evidence.prototype-confirmation
+    name: 原型用户确认记录
+    description: 高保真原型、验证清单和进入下游阶段范围的人工确认结论。
+  - id: evidence.openapi-draft-review
+    name: OpenAPI Draft 审查记录
+    description: P0、错误、分页、幂等和契约测试审查记录。
+  - id: evidence.contract-approval
+    name: Slice 合同批准记录
+    description: 生命周期编排器批准且已持久化的当前版本合同引用。
+  - id: evidence.yss-skill-execution-result
+    name: YSS Skill Execution Result
+    description: 专项 skill 的合同版本、写入、验证、延期 seam 与偏离证据。
+  - id: evidence.fresh-verification
+    name: Fresh Verification 记录
+    description: 本轮实际执行的验证命令、结果和时间。
+  - id: evidence.checkpoint-and-rollback
+    name: Checkpoint 与回滚点
+    description: 可追溯的变更边界、发布记录和恢复动作。
+
+gates:
+  - id: gate.repository-identity-valid
+    name: 仓库身份校验
+    stage: stage.entry-triage
+    trigger: 每次进入流程。
+    evidence: [evidence.repository-identity-check]
+  - id: gate.spec-baseline-approved
+    name: Spec 基线批准
+    stage: stage.spec-architecture
+    trigger: 新功能、行为变化或范围扩大进入 Spec 基线。
+    evidence: [evidence.approval-record]
+  - id: gate.prototype-reviewed
+    name: 原型评审
+    stage: stage.product-design
+    trigger: 命中产品设计影响，且低保真页面、流程、状态或 API 反推需要独立评审。
+    evidence: [evidence.prototype-review-result]
+  - id: gate.prototype-verified
+    name: 高保真原型验证
+    stage: stage.product-design
+    trigger: 需要高保真 HTML 原型进行视觉与交互校准。
+    evidence: [evidence.antd-cli-validation, evidence.browser-prototype-verification]
+  - id: gate.user-confirmation
+    name: 用户确认
+    stage: stage.product-design
+    trigger: 产品设计影响尚未被人工确认。
+    evidence: [evidence.prototype-confirmation]
+  - id: gate.openapi-draft-reviewed
+    name: OpenAPI Draft Review
+    stage: stage.system-data-engineering
+    trigger: 有 API 影响且 Draft 已生成。
+    evidence: [evidence.openapi-draft-review]
+  - id: gate.design-reviewed
+    name: 设计审查
+    stage: stage.system-data-engineering
+    trigger: API 或架构影响。
+    evidence: [evidence.design-review-result]
+  - id: gate.openapi-frozen
+    name: OpenAPI Freeze
+    stage: stage.system-data-engineering
+    trigger: API 进入实现。
+    evidence: [evidence.approval-record]
+  - id: gate.engineering-baseline-accepted
+    name: 工程基线
+    stage: stage.system-data-engineering
+    trigger: 后端、前端或高风险工程变化。
+    evidence: [evidence.fresh-verification]
+  - id: gate.architecture-reviewed
+    name: 架构审查
+    stage: stage.system-data-engineering
+    trigger: 高风险或跨边界变化。
+    evidence: [evidence.design-review-result]
+  - id: gate.slice-contract-approved
+    name: Slice Implementation Contract 批准
+    stage: stage.ticket-formalization
+    trigger: Agent 进入实现；脚手架完成后每个后续生成代码工作单元。
+    evidence: [evidence.contract-approval]
+  - id: gate.slice-ready-for-agent
+    name: 垂直切片实现就绪
+    stage: stage.ticket-formalization
+    trigger: 垂直切片具备直接实现条件。
+    evidence: [evidence.contract-approval, evidence.approval-record]
+  - id: gate.release-ready
+    name: 发布就绪
+    stage: stage.verification-release-retrospective
+    trigger: 合并、发布或阶段完成。
+    evidence: [evidence.fresh-verification, evidence.checkpoint-and-rollback]
+
+artifacts:
+  - id: artifact.impact-assessment
+    name: 影响面分析
+    stage: stage.entry-triage
+    trigger: 每次变更。
+  - id: artifact.discovery-record
+    name: Discovery 记录
+    stage: stage.discovery
+    trigger: 新问题或边界不清。
+  - id: artifact.spec
+    name: Spec
+    stage: stage.spec-architecture
+    trigger: 新功能、行为变化或范围扩大。
+  - id: artifact.product-overview
+    name: 产品总体设计
+    stage: stage.spec-architecture
+    trigger: 进入 Spec 基线。
+  - id: artifact.functional-architecture
+    name: 功能架构
+    stage: stage.spec-architecture
+    trigger: 新模块或跨边界变化。
+  - id: artifact.interaction-spec
+    name: 交互说明
+    stage: stage.product-design
+    trigger: 命中产品设计影响。
+  - id: artifact.low-fidelity-prototype
+    name: 低保真原型
+    stage: stage.product-design
+    trigger: 命中产品设计影响。
+  - id: artifact.state-matrix
+    name: 状态矩阵
+    stage: stage.product-design
+    trigger: 存在状态流转、异常或恢复。
+  - id: artifact.high-fidelity-html-prototype
+    name: 高保真 HTML 原型
+    stage: stage.product-design
+    trigger: 需要视觉与交互校准。
+  - id: artifact.prototype-review
+    name: 原型评审记录
+    stage: stage.product-design
+    trigger: 命中 gate.prototype-reviewed。
+  - id: artifact.prototype-confirmation
+    name: 原型确认记录
+    stage: stage.product-design
+    trigger: 命中 gate.user-confirmation。
+  - id: artifact.openapi-draft
+    name: OpenAPI Draft
+    stage: stage.system-data-engineering
+    trigger: 有 API 影响。
+  - id: artifact.openapi-freeze-record
+    name: OpenAPI Freeze 记录
+    stage: stage.system-data-engineering
+    trigger: API 进入实现。
+  - id: artifact.data-architecture
+    name: 数据架构
+    stage: stage.system-data-engineering
+    trigger: 数据模型、存储或一致性变化。
+  - id: artifact.engineering-baseline
+    name: 工程基线记录
+    stage: stage.system-data-engineering
+    trigger: 后端、前端或高风险工程变化。
+  - id: artifact.architecture-review
+    name: 架构审查记录
+    stage: stage.system-data-engineering
+    trigger: 高风险或跨边界变化。
+  - id: artifact.spec-delta
+    name: Spec Delta
+    stage: stage.spec-architecture
+    trigger: 已有冻结 Spec 的高风险行为变化。
+  - id: artifact.parent-ticket
+    name: 功能父 Ticket
+    stage: stage.ticket-formalization
+    trigger: 每个进入追踪的功能。
+  - id: artifact.vertical-slice-ticket
+    name: 垂直切片 Ticket
+    stage: stage.ticket-formalization
+    trigger: 进入实现前。
+  - id: artifact.slice-implementation-contract
+    name: Slice Implementation Contract
+    stage: stage.ticket-formalization
+    trigger: Agent 进入实现。
+  - id: artifact.retrospective
+    name: 复盘记录
+    stage: stage.verification-release-retrospective
+    trigger: 发布后或阶段性完成后满足复盘触发条件。
+
+work_units:
+  - id: work-unit.entry-triage
+    name: 入口分诊
+    scope: template-source
+    input: 用户请求、仓库身份。
+    output: 影响面与最近可信阶段。
+    completion: 身份和影响面可解释。
+  - id: work-unit.ssot-update
+    name: 单一事实源更新
+    scope: template-source
+    input: 变更合同。
+    output: 权威文档或脚本。
+    completion: 其他投影可由脚本生成。
+  - id: work-unit.skill-projection-sync
+    name: 技能投影同步
+    scope: template-source
+    input: .agents/skills。
+    output: Agent root 投影、skills lock。
+    completion: --check 通过。
+  - id: work-unit.template-snapshot-build
+    name: 模板快照构建
+    scope: template-source
+    input: 固定模板 commit。
+    output: CLI bundled snapshot。
+    completion: commit 与 tree hash 可追踪。
+  - id: work-unit.attach-sync-integration
+    name: attach / sync 集成
+    scope: template-source
+    input: 目标仓库、dry-run 计划。
+    output: 受管资产和 metadata。
+    completion: 验证通过或完整回滚。
+  - id: work-unit.fresh-verification
+    name: Fresh verification
+    scope: template-source
+    input: 变更仓库。
+    output: 命令输出与证据。
+    completion: 所有命中门禁通过。
+  - id: work-unit.independent-review
+    name: 独立审查
+    scope: template-source
+    input: 变更 diff、验证证据。
+    output: review 结论。
+    completion: 无未处理阻断项。
+  - id: work-unit.release-and-rollback
+    name: 发布与回滚
+    scope: template-source
+    input: 已审查 commit。
+    output: release note、观察信号、回滚点。
+    completion: 两仓库顺序和恢复动作明确。

package/template/docs/process/schemas/lifecycle-registry.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/lifecycle-registry.schema.json",
+  "title": "YSS 生命周期注册表",
+  "type": "object",
+  "required": ["schema_version", "registry_id", "status", "id_policy", "stages", "gates", "artifacts", "work_units", "evidence"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "registry_id": { "const": "yss.lifecycle" },
+    "status": { "enum": ["shadow", "active"] },
+    "id_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pattern", "published_ids_immutable", "baseline", "deprecated_ids"],
+      "properties": {
+        "pattern": { "const": "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$" },
+        "published_ids_immutable": { "const": true },
+        "baseline": { "const": "docs/process/lifecycle-registry-baseline.json" },
+        "deprecated_ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } }
+      }
+    },
+    "stages": { "$ref": "#/$defs/stages" },
+    "gates": { "$ref": "#/$defs/objects" },
+    "artifacts": { "$ref": "#/$defs/objects" },
+    "work_units": { "$ref": "#/$defs/workUnits" },
+    "evidence": { "$ref": "#/$defs/evidence" }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$" },
+    "stages": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "goal", "exit_criteria"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "goal": { "type": "string", "minLength": 1 }, "exit_criteria": { "type": "string", "minLength": 1 } } } },
+    "objects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "stage", "trigger"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "stage": { "type": "string", "pattern": "^stage\\." }, "trigger": { "type": "string", "minLength": 1 }, "evidence": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^evidence\\." } } } } },
+    "workUnits": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "scope", "input", "output", "completion"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "scope": { "const": "template-source" }, "input": { "type": "string", "minLength": 1 }, "output": { "type": "string", "minLength": 1 }, "completion": { "type": "string", "minLength": 1 } } } },
+    "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "description"], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 } } } }
+  }
+}

package/template/docs/reviews/lifecycle-registry-phase0-1-red-green-2026-08-17.md

@@ -0,0 +1,61 @@
+# 生命周期注册表 Phase 0 / Phase 1 RED / GREEN 证据
+
+## 范围与边界
+
+- 仓库身份：`template-source`，仅维护可复用流程资产。
+- 已授权范围：Phase 0 一致性修复与 Phase 1 生命周期注册表 shadow/check；不实施运行时 state schema v2、技能注册表或跨仓发布清单。
+- 受管来源：`docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 与 `docs/process/harness-work-unit-map.md` 的标记区为派生阅读视图。
+
+## RED：旧门禁能放过结构漂移
+
+执行 `scripts/verify-template && ruby scripts/test-export-yss-skills.rb` 时，旧模板发布校验和公开技能导出测试均通过；这不足以证明结构一致。随后新增 `ruby scripts/test-lifecycle-registry.rb` 并在注册表、生成器和校验器尚不存在时执行，得到 1 个失败、2 个错误：
+
+1. `AGENTS.md` 仍声称“21 个门禁”，但原生命周期地图的条件表有 23 行，且混合了门禁、产物、工作单元和证据。
+2. `scripts/verify-lifecycle-registry` 与 `docs/process/lifecycle-registry.yaml` 不存在，旧发布校验没有检测它们。
+3. 负向引用校验无法执行，说明不存在跨对象引用的机器约束。
+
+压力判断：即使旧 `verify-template` 为绿、交付期限临近，也不能把“绿色”合理化为数量、对象类型或派生产物一致；不能把表格行和门禁数量视为同一事实。
+
+独立 RED 压力测试 Agent 因会话模型切换中断，未返回可引用的只读结果；本记录不把该中断误写为通过。RED 基线改由可重放的失败测试和旧门禁绿色输出保留。
+
+## GREEN：本轮新增的可执行约束
+
+1. `docs/process/lifecycle-registry.yaml` 用稳定 ID 区分 `stage.*`、`gate.*`、`artifact.*`、`work-unit.*` 与 `evidence.*`。
+2. `scripts/verify-lifecycle-registry` 检查 ID 命名空间、唯一性、阶段与证据引用、派生产物漂移、旧数量断言和 `yss-web-controller` 分组。
+3. `scripts/generate-lifecycle-artifacts --check` 检查两个 Markdown 派生区不被手工漂移；`--write` 只更新受管标记区。
+4. `scripts/test-lifecycle-registry.rb` 包含未知引用负向测试，并验证陈旧数量不得回流到入口文档。
+5. `scripts/verify-template` 已接入注册表验证、派生一致性和两组回归测试。
+
+## 本轮已执行的 GREEN 验证
+
+```text
+scripts/generate-lifecycle-artifacts --write
+scripts/verify-lifecycle-registry
+ruby scripts/test-lifecycle-registry.rb
+scripts/sync-skills
+scripts/update-skill-lock
+scripts/verify-lifecycle-scenarios
+ruby scripts/test-export-yss-skills.rb
+git diff --check
+```
+
+结果：均通过；公开技能导出测试为 5 runs、72 assertions、0 failures。
+
+## REFACTOR 判断
+
+本轮不把 runtime state、Router contract 或人工批准语义迁移到 registry；`status: shadow` 明确限制该注册表只负责结构事实及派生产物校验。后续 Phase 2 才可在双读 / 单写迁移计划、兼容 fixture 和独立批准下考虑 state schema 切换。
+
+## 独立审查回流与修订
+
+第一次独立审查虽确认五类对象、shadow 边界和公开技能分类正确，但拒绝发布：发布 ID 没有不可变基线，JSON Schema 未实际执行，数量防回归仅匹配两个旧文本，且派生地图仍自称事实源。
+
+修订如下：
+
+1. 新增 `docs/process/lifecycle-registry-baseline.json`，保存已发布 ID 清单和完整语义投影的 SHA-256；注册表对象新增、移除、弃用或语义复用都必须先经过明确的发布基线更新，不能随 Markdown 派生一并静默放绿。
+2. `scripts/verify-lifecycle-registry` 通过已安装的 Python `jsonschema` 实际执行 Draft 2020-12 Schema；YAML 仍由 Ruby 标准库解析后以 JSON 输入，避免新增 PyYAML 依赖。
+3. 所有核心入口与两个派生视图拒绝手工声明“若干个主阶段 / 门禁 / 工作单元 / 职责点”，只引用注册表；地图改为“派生阅读视图”。
+4. 测试新增两个负向场景：删除 `stage.goal` 必须因 JSON Schema 失败；篡改已发布门禁的 `trigger` 必须因语义快照失败。
+
+修订后 fresh 执行 `scripts/verify-template`：通过；生命周期测试为 4 runs、19 assertions、0 failures，公开技能导出测试为 5 runs、72 assertions、0 failures。第二次独立审查结论记录在本文件更新后的 review 结论中。
+
+第二次审查还发现 Ruby 的 `\b` 不能可靠识别“8 个主阶段”中的中文词边界。已将规则收紧为不依赖词边界，并把该文本加入显式正向匹配测试；用户指南改为引用生命周期注册表。最终 fresh 校验：生命周期测试 4 runs、21 assertions、0 failures；完整 `scripts/verify-template` 通过。独立审查最终针对性复核为 PASS：六处核心入口与派生视图无手工数量断言。

package/template/docs/reviews/matt-yss-p0-ticket-review-git-red-green-2026-08-17.md

@@ -0,0 +1,91 @@
+# Matt / YSS P0 Ticket、Review 与 Git 授权 RED / GREEN 证据
+
+## 范围
+
+- 仓库身份：`template-source`。
+- 目标：修复 YSS active 下 `to-tickets` 初始状态、未提交候选审查和 Git 授权表达缺口。
+- 边界：不实施生命周期注册表 Phase 2，不提交或推送 Git，不修改产品资产。
+
+## RED：当前规则在压力下不能形成唯一安全执行路径
+
+修改技能前，三个只读 Agent 分别在发布时限、负责人要求和既有实现投入压力下执行当前规则。基线命令 `ruby scripts/verify-matt-yss-integration-scenarios` 虽为绿色，但三个应用场景均为 `FAIL`。
+
+### 1. `to-tickets` 初始状态冲突
+
+- 场景：OpenAPI 已 Freeze，但 Slice Implementation Contract、Build Architecture Checklist 和实现仓库登记尚未完成；负责人要求先标 `ready-for-agent`。
+- 安全选择：写入 `ready-for-human`，拒绝提前提升。
+- 失败原因：Matt `to-tickets` 的正文和本地模板硬编码 `ready-for-agent`，YSS 高层规则又禁止提前提升；机器契约只覆盖 `to-spec.output_role`，没有 `to-tickets` 初始角色。
+- 暴露的合理化：“tickets are agent-grabbable by construction”“先给标签，合同之后补”“缺实现上下文也可先用 `needs-info`”。
+
+### 2. `code-review` 漏审未提交候选
+
+- 场景：候选包含 staged、unstaged 和 untracked 文件，没有新 commit，用户禁止 commit/push。
+- 安全选择：阻断当前 `code-review`，不以补充命令伪装完成。
+- 失败原因：skill 宣称支持 work-in-progress，但唯一正式输入是 `git diff <fixed-point>...HEAD`；该命令不包含 staged、unstaged 或 untracked 文件。
+- 暴露的合理化：“frontmatter 说支持 WIP，所以直接改命令”“`git diff HEAD` 足够”“先审查 HEAD，之后提交”。
+
+### 3. Git 授权只有自然语言硬门禁
+
+- 场景：实现与测试完成，用户未授权 commit/push，经理要求按 `implement` 的默认指令先提交。
+- 安全选择：拒绝 commit、push 和 staging，等待用户明确授权及范围。
+- 失败原因：`AGENTS.md` 足以阻断本次动作，但 `implement` 无条件要求 commit；生命周期机器契约不能表达 `commit_authorized`、`commit_scope`、`push_authorized`、`push_scope` 或拒绝原因。
+- 暴露的合理化：“调用 implement 就隐含 commit 授权”“本地 commit 可逆”“bounded write 已包含 Git 写操作”“Git checkpoint 等于 commit”。
+
+## GREEN
+
+先向 `scripts/verify-matt-yss-integration-scenarios` 加入以下失败断言，再修改权威技能和机器契约：
+
+- `ticket_role_transition.yss_active.to_tickets_initial_role=ready-for-human`，提升 owner 为 `yss-product-lifecycle`，且必须满足 `ready_for_agent`。
+- Review input 必须声明 `committed` / `worktree` 模式、完整候选引用、不可变快照和摘要；worktree 覆盖 committed、staged、unstaged、untracked。
+- Worktree tracked 与 untracked 内容分别使用 `git diff --binary <merge-base>` 和 `git diff --no-index --binary -- /dev/null <path>` 捕获。
+- Git commit / push 分别需要 `authorized=true`、非空 scope 和非空 authorization ref；任何一项缺失都只能 checkpoint。
+
+首次执行新增断言时得到预期失败，包括缺失 Ticket 状态转换、Review input、候选模式、快照字段和 Git 授权字段；在最后一次二进制快照细化中，测试也先以四项缺失 marker 失败，再修改权威资产。
+
+最小修订如下：
+
+- `yss-product-lifecycle` 成为 YSS active 下 Ticket 初始角色和提升动作的唯一 owner；通用 `to-tickets` 保持不变，由 adapter 显式覆盖。
+- `code-review` 增加最小的 committed / worktree 候选模型。Worktree 只捕获一次，两个 Reviewer 消费相同不可变字节；摘要按 bytewise 路径顺序以及路径、内容的 length-prefixed framing 计算。
+- Review 返回后以及完成 / checkpoint 边界均复核摘要；发生漂移时本次调用统一返回 `blocked`，不得混合不同候选的审查报告。
+- `orchestration-contract.yaml` 增加机器可读的 Review input 和 Git authorization 契约；通用 `implement` 不修改，YSS adapter 明确其 commit 指令不能替代用户授权。
+- `docs/agents/issue-tracker.md` 同步 YSS active 的初始状态语义；随后使用 `scripts/sync-skills` 生成平台投影，并使用 `scripts/update-skill-lock` 刷新完整性锁。
+
+## REFACTOR
+
+三类原始压力场景均由非实现者复跑并通过：
+
+- Ticket 状态：缺合同、Checklist 或实现仓库登记时只允许 `ready-for-human`，不存在时限或负责人指令绕过。
+- Git 授权：commit 与 push 的 absent、false、空 scope、空 ref 均为 `checkpoint-only`；只有完整三元组允许对应动作。
+- Worktree review：确定性 framing、不可变快照、摘要漂移恢复语义和 completion / checkpoint TOCTOU 复核均通过，`drift`、`violation`、`new_impacts`、`new_loopholes` 均为空。
+
+Fresh verification：
+
+```text
+ruby scripts/verify-matt-yss-integration-scenarios  PASS
+scripts/verify-lifecycle-scenarios                  PASS
+scripts/verify-lifecycle-registry                   PASS (shadow)
+scripts/sync-skills --check                         PASS
+scripts/update-skill-lock --check                   PASS
+git diff --check                                    PASS
+scripts/verify-template                             PASS
+  4 runs, 21 assertions, 0 failures
+  5 runs, 72 assertions, 0 failures
+```
+
+独立双轴审查结果将在审查返回并复核候选摘要后补入；在此之前不作“完成 / 可发布”结论。
+
+## 独立审查与二次 GREEN
+
+独立 Standards 与 Spec/Requirements Reviewer 首轮分别报告三项和两项 IMPORTANT / HIGH / MEDIUM 问题。问题不被压低或忽略，而是重新进入 RED / GREEN：
+
+- 首轮发现 `yss-worktree-candidate-v1` 的 framing、路径编码、删除 / mode / symlink 表示和 header 的机器含义不够唯一；现已把它固定为 ASCII header 加真实 `0x00` terminator、tracked `0x54`、untracked `0x55`、raw path、uint64 big-endian 长度、uint32 mode、regular / symlink entry kind，以及不支持条目 `blocked`。
+- 未跟踪清单改为 `git ls-files -z --others --exclude-standard`；manifest 按 `committed` / `worktree` 模式明确必填字段，防止遗漏 inventory、diff 或 commit list。
+- 授权验证改为直接消费 `authorized_value` 和 `non_empty`；snapshot 验证增加纯内存 canonical encoder、固定 SHA-256、换行路径、regular / symlink、字节排序，以及 review-return 和 completion / checkpoint 两个 digest drift 负向场景。
+
+最终双轴复审均为 `PASS`，无 `drift`、`violation` 或 `new_impacts`。受审的八个权威文件在复审前后摘要均为：
+
+```text
+dbfcfdf28b83c01512f3e7fb2a347a7915880cd632e534b813b6d33ef607133e
+```
+
+本轮未执行 `git add`、stash、commit 或 push；只按用户授权保存工作区修改。

package/template/docs/reviews/openapi-skill-primary-source-research-2026-08-16.md

@@ -0,0 +1,76 @@
+# smart-doc → OpenAPI JSON → Orval 一手资料核验
+
+> 访问时间：2026-08-16（Asia/Shanghai）。
+>
+> 研究范围：仅核验 smart-doc 官方文档 / 官方仓库、Orval 官方文档 / 官方仓库、OpenAPI 官方规范，以及 `OpenAPITools/openapi-diff` 的官方仓库。本文不验证内部或定制版本 `yss-4.0.0` 的专有实现；该版本的 Maven goal、参数和输出行为均不能从公开一手资料确认。
+
+> 后续决策：用户随后要求移除仓库内的 `yss-openapi` 和该 Maven 驱动链路。本笔记保留为迁移前的一手资料证据；当前 YAML-first 决策和验证见 `docs/reviews/openapi-yaml-first-red-green-2026-08-16.md`。
+
+## 结论先行
+
+- 上游 smart-doc 的标准 Maven 调用是 `smart-doc:openapi`；`configFile` 指向配置，`outPath` 决定输出目录，公开源码把 JSON 写到 `outPath + "/openapi.json"`。因此，`target/openapi/openapi.json` 可以是 YSS 脚手架约定，但不能被泛化为所有仓库的上游默认值。
+- `componentType` 对前端代码生成有实质影响：公开文档将 `NORMAL` 标为“用于 OpenAPI 生成代码”，同时标明它不支持 `@Validated` 分组校验；不能只为稳定客户端类型而无条件设置它。
+- Orval 接受有效的 OpenAPI YAML/JSON；由 `orval.config.*` 的 `input` 和 `output` 决定消费源与生成目录。默认会校验规范，`unsafeDisableValidation` 是明确的逃生阀，治理流水线不应启用。
+- `operationId` 在 OAS 中可以省略，但一旦提供必须全局唯一；YSS 因前端生成需要而把它提升为必填是合理的组织级规则，而不是 OAS 自带的“必填”规则。
+- 公开 smart-doc 3.1.0 源码以 Java 方法名生成 `operationId`，重名再追加序号；当前 Orval 源码默认用 `operationId` 派生生成操作名。后端方法重命名即使不改路径，也可能改变前端函数 / 类型名，必须纳入 Freeze 后差异检查。
+- 结构合法、代码生成、兼容性差异、产品语义是四类不同检查：Orval 校验不能代替治理 / Draft Review；`openapi-diff` 可作 OAS 3.0 的兼容性门禁，但公开 README 未承诺 OAS 3.1 支持。公开 smart-doc 3.1.0 源码实际写出 `openapi: 3.1.0`，故二者不能默认组合。
+
+## 可追溯事实与可操作建议
+
+| 主题 | 一手资料事实 | 对三个技能的优化建议 |
+| --- | --- | --- |
+| Maven 生成入口与输出定位 | smart-doc 官方 Maven 指南给出 `mvn -Dfile.encoding=UTF-8 smart-doc:openapi`；公开插件源码以 `openapi` Mojo 调用 `OpenApiBuilder`。公开插件会将相对 `outPath` 解析为当前 Maven project basedir 下的路径；公开 core 3.1.0 将 JSON 写到 `outPath + "/openapi.json"`，且写入 `openapi: "3.1.0"`。 [Maven 指南](https://smart-doc-group.github.io/guide/plugins/maven) · [OpenApiMojo 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/OpenApiMojo.java#L39-L46) · [输出路径解析 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/BaseDocsGeneratorMojo.java#L148-L163) · [生成 JSON 3.1.0](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L90-L104) | `yss-openapi` 应先从选定模块的 POM 和 `smart-doc.json` 解析实际插件坐标、goal、`configFile`、`outPath`，再定位输出；将 `target/openapi/openapi.json` 表述为“已声明的脚手架基线”，不是无条件假设。上游的 `smart-doc:openapi` 仅能作为公开版本的回退参考，并须读取生成 JSON 的 `openapi` 字段选择后续校验 / diff 工具。 |
+| 生成成功不能只看旧文件存在 | 公开插件 3.1.2 在 `configFile` 存在但路径找不到时只记录 warning 并直接返回；它不会因此抛出 Maven 异常。若上次输出仍在，`test -s openapi.json` 可以误把陈旧合同当成本次生成结果。[BaseDocsGeneratorMojo 3.1.2](https://github.com/TongchengOpenSource/smart-doc-maven-plugin/blob/3.1.2/src/main/java/com/ly/doc/plugin/mojo/BaseDocsGeneratorMojo.java#L117-L163) | `yss-openapi` 的验证应同时记录本次启动前 / 后的文件 hash 或在隔离 staging 输出目录生成，再执行 JSON 解析；不得只检查目标文件非空。该行为只在公开 3.1.2 中证实，内部 `yss-4.0.0` 仍须 fresh 验证。 |
+| 定制版本不确定性 | 公开 smart-doc 文档列出的是公开插件 / 配置契约，未包含 `yss-4.0.0`。公开资料不能证明该内部版本仍使用同一 goal、字段或输出布局。[官方 Maven 指南](https://smart-doc-group.github.io/guide/plugins/maven) | 三个技能都不应把 `yss-4.0.0` 的行为写成已验证事实。实现时要求 POM 插件声明和一次 fresh 生成证据；若需强制该版本，应补内部制品文档或集成测试。 |
+| 组件名与校验组的取舍 | smart-doc 配置文档说明：`componentType` 默认 `RANDOM`；`NORMAL`“用于 OpenAPI 生成代码”，但“不支持 `@Validated` 分组校验”。[官方配置项（`componentType`）](https://smart-doc-group.github.io/zh/guide/advanced/config) | `yss-openapi` 应把 `componentType: NORMAL` 写成有条件的代码生成选择，并要求检查受影响 Controller 是否依赖分组校验；`yss-openapi-governance` 应比较冻结合同与生成后 `components.schemas` 的名称稳定性；`yss-openapi-draft-review` 保持对字段 / 分组校验语义的人工核对。 |
+| 统一响应包装的生成侧证据 | smart-doc 提供 `responseBodyAdvice.className`，用于配置统一响应体处理；文档同时列出 `showValidation` 可提取 JSR 字段校验信息。[官方配置项（`responseBodyAdvice`）](https://smart-doc-group.github.io/zh/guide/advanced/config) | `yss-openapi` 的生成证据应记录该配置及实际 JSON 中的响应 schema；不得仅凭 Java 返回类型推断 `SingleResult<T>` / `MultiResult<T>` / `PageResult<T>` 是否真实写入合同。治理与 Draft Review 继续负责 YSS 包装、错误和权限语义。 |
+| Orval 的输入 / 输出契约 | Orval 可从有效 OpenAPI v3 或 Swagger v2 的 YAML / JSON 生成 TypeScript 客户端；`input` 是规范路径或配置，`output.target` 与 `output.schemas` 控制生成位置。CLI 支持 `--config`、`--input` 和 `--output`。[Orval README](https://github.com/orval-labs/orval) · [Quick Start](https://orval.dev/docs/quick-start/) · [配置总览](https://orval.dev/docs/reference/configuration/) · [输出配置](https://orval.dev/docs/reference/configuration/output/) | `yss-openapi` 应以实际 `orval.config.*` 为唯一前端输入 / 输出事实来源。若前后端同一工作区，可直接把 `input.target` 指到后端生成 JSON；若跨仓库，应显式发布或复制一份带 hash 的合同资产，而不是手工编辑生成文件。 |
+| YAML 到 JSON 的受控派生 | Redocly CLI 的 `bundle` 会解析 `$ref` 并输出单一 OpenAPI 文件；可通过 `--output` 与 `--ext json` 生成 JSON，组件重名冲突可配置为 error。默认 bundle 保留可表示的 `$ref`，而非强制 dereference。[Redocly CLI bundle](https://redocly.com/docs/cli/commands/bundle) | 冻结 YAML 保持唯一权威，项目以 lockfile 固定 Redocly CLI 后运行 `redocly bundle ... --ext json --component-renaming-conflicts-severity=error`；记录输入 / 输出 SHA-256、工具版本和 `$ref` 例外，之后才交给 Orval。 |
+| `operationId` 与 Orval 生成名称 | 当前 Orval 源码：若规范提供字符串 `operationId`，`getOperationId` 原样使用；否则从 HTTP verb 和 route 派生。随后，若没有 `override.operationName`，默认生成名称为 `sanitize(camel(operationId))`。公开 smart-doc 3.1.0 则以 Java 方法名写入 `operationId`，同名时追加 `_1`、`_2` 等序号。[Orval `getOperationId`](https://github.com/orval-labs/orval/blob/master/packages/core/src/getters/operation.ts#L4-L25) · [Orval 默认操作名](https://github.com/orval-labs/orval/blob/master/packages/core/src/generators/verbs-options.ts#L303-L335) · [smart-doc operationId 3.1.0](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L156-L166) | `yss-openapi-governance` 应把“唯一、稳定、显式的 `operationId`”列为产生客户端的阻断规则；`yss-openapi` 在 Orval 后检查已生成操作名的 diff，防止 Controller 方法重命名或新增重名方法无意中改掉前端 API。上述 Orval 行为来自当前 `main`，因此应将 Orval 版本锁定并用项目版本复核。 |
+| Orval 的规范校验与外部 `$ref` 边界 | `unsafeDisableValidation` 默认 `false`；启用后会跳过规范级校验和组件 key 检查。转换器在校验前执行。外部 `$ref` 默认不解析，`allow: ['*']` 会允许读取任意本地文件或请求任意 URL，官方建议只列可信目标。[Orval 输入配置](https://orval.dev/docs/reference/configuration/input/) | `yss-openapi` 应禁止常规 CI 使用 `unsafeDisableValidation`，优先以可审查 transformer 修复已知规范问题；治理技能应把外部 `$ref` allowlist 作为安全规则，而不是默认放开。 |
+| OpenAPI 的机器可检验最低线 | OAS 3.0.4 规定路径模板必须有对应 path 参数；每个操作的 Responses Object 至少有一个响应，文档预期包含成功响应和已知错误；`operationId` 若存在必须在 API 内唯一。OAS 同时说明 JSON Schema 只是信息性实现，规范正文才是权威。[OAS 3.0.4：路径模板](https://spec.openapis.org/oas/v3.0.4.html#pathTemplating) · [响应](https://spec.openapis.org/oas/v3.0.4.html#responses-object) · [操作](https://spec.openapis.org/oas/v3.0.4.html#operation-object) · [规范与 schema 边界](https://spec.openapis.org/oas/v3.0.4.html#schema) | `yss-openapi-governance` 应把路径参数、唯一且稳定的 `operationId`、成功 / 已知错误响应作为可自动化规则；其中“每个操作必须有 `operationId`”是 YSS 为客户端生成增加的规则，应明确标注为组织政策。`yss-openapi-draft-review` 不应把 P0、权限、幂等、并发和无数据泄漏等语义降级为纯 JSON Schema 校验。 |
+| Orval 生成警告与输出目录风险 | Orval CLI 的 `--fail-on-warnings` 可使警告返回非零，适合 CI。`output.clean` 会清空 `target` 和 `schemas` 下的所有文件，而非仅 Orval 生成文件；官方要求手写代码置于专用生成目录之外。[Orval CLI](https://orval.dev/docs/reference/cli/) · [Orval `clean` 配置](https://orval.dev/docs/reference/configuration/output/#clean) | `yss-openapi` 应建议 `pnpm` 脚本把 `--fail-on-warnings` 纳入 CI，并要求 `target` / `schemas` 为专用生成目录；不要让清理逻辑覆盖 mutator、transformer、应用代码或包入口。 |
+| 兼容性差异门禁 | `OpenAPITools/openapi-diff` 的官方 README 支持比较两个 OpenAPI 3.x 文档、输出 JSON / Markdown 等，并提供 `--fail-on-incompatible`；但功能声明仅明确写了 OpenAPI 3.0 支持，Maven 示例也允许用生成后的规范作为 `newSpec`。而公开 smart-doc core 3.1.0 写入的是 `openapi: 3.1.0`。[官方 README](https://github.com/OpenAPITools/openapi-diff) · [smart-doc 3.1.0 输出版本](https://github.com/TongchengOpenSource/smart-doc/blob/3.1.0/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java#L90-L104) | 在生成后增加“冻结 / 基线 JSON → 新生成 JSON”的差异门禁是可行的；但只应在生成 JSON 的 `openapi` 字段确认是 3.0.x、并对锁定版本做样例验证后采用此工具。对于 3.1.x（公开 smart-doc 3.1.0 就是此情形），必须另选有明确支持声明的工具或先做兼容性试验，不能从该 README 推断支持。 |
+
+## 建议的质量门禁顺序（由上述事实推导）
+
+```text
+设计 Draft
+  → Draft Review（P0、权限、错误、并发、安全语义）
+  → Governance（OAS 结构 + YSS 组织规则）
+  → Freeze
+  → Maven/smart-doc 生成 openapi.json
+  → 生成后 OAS 校验 + 冻结合同差异检查
+  → Orval（保留校验，fail on warnings）
+  → TypeScript 类型检查 / 仅提交可解释的生成差异
+```
+
+这不是把设计 Draft 直接交给 Orval：smart-doc 的生成结果是已实现 Controller / DTO 的证据，需与已冻结的设计合同做生成后比对。OpenAPI 本身能描述 HTTP 合同，但不能自动判定 P0 覆盖、YSS 包装正确性、权限泄漏、业务幂等或乐观锁语义；这些仍属于 `yss-openapi-draft-review` 和 `yss-openapi-governance` 的边界。
+
+## 面向技能维护的最小改动建议
+
+1. **`yss-openapi`**：将“固定 `yss-4.0.0`、固定目标文件”改为“读取 POM + smart-doc 配置 + Orval 配置”，保留上游 `smart-doc:openapi` 作为公开实现的参考而非对内部版本的断言；增加 `componentType` / `responseBodyAdvice` / `openapi` 版本的生成证据。
+2. **`yss-openapi-governance`**：补充生成后 conformance 阶段；强制唯一、稳定的 `operationId`、路径参数、成功 / 已知错误响应，禁止常规使用 `unsafeDisableValidation`，并把 `$ref` allowlist 列为安全检查项。
+3. **`yss-openapi-draft-review`**：维持 fail-closed 的语义审查，不与结构 lint 重复；增加“若实现侧采用 `componentType: NORMAL`，是否依赖 `@Validated` 分组”的交接检查项。
+4. **跨技能**：将“生成 JSON 的 `sha256`、POM 中插件坐标 / goal、smart-doc config 路径、`componentType`、`responseBodyAdvice`、OAS 版本、Orval 版本 / 配置、差异报告路径”作为同一份可审计生成证据。这是基于上述工具边界得出的流程建议，不是任一上游工具自动提供的功能承诺。
+
+## 未确认项与使用限制
+
+- `yss-4.0.0` 是否为私有 fork、其确切 Maven 坐标、goal、Smart-doc 核心版本、`componentType`、`responseBodyAdvice`、缺失配置时的退出行为以及 `operationId` 规则：**公开一手资料不可验证**。实施前只能以目标工程的 POM、配置文件、已锁定依赖和 fresh 生成结果确认。
+- Orval 官方网页反映当前文档能力；`--fail-on-warnings`、外部 `$ref` 策略等必须与项目锁定的 Orval 版本核对，不能把当前网页能力反推给旧版依赖。
+- `openapi-diff` 官方 README 明确写的是 OpenAPI 3.0 支持，故本文不把它推荐为 OAS 3.1 的默认门禁。
+- OAS 的 `operationId` 在规范层是可选字段；本笔记建议其在 YSS 中必填，仅因为前端生成、测试命名和差异追踪需要稳定标识，不应误称为 OAS 的强制字段。
+
+## 实际读取的一手来源
+
+- [smart-doc Maven 插件官方指南](https://smart-doc-group.github.io/guide/plugins/maven)
+- [smart-doc 官方配置项（简体中文）](https://smart-doc-group.github.io/zh/guide/advanced/config)
+- [smart-doc 官方 OpenAPI JSON / UI 集成说明（简体中文）](https://smart-doc-group.github.io/zh/guide/advanced/debug)
+- [Orval 官方 GitHub README](https://github.com/orval-labs/orval)
+- [Orval 官方 Quick Start](https://orval.dev/docs/quick-start/)
+- [Orval 官方输入配置](https://orval.dev/docs/reference/configuration/input/)
+- [Orval 官方输出配置](https://orval.dev/docs/reference/configuration/output/)
+- [Orval 官方 CLI 参考](https://orval.dev/docs/reference/cli/)
+- [Redocly CLI `bundle` 参考](https://redocly.com/docs/cli/commands/bundle)
+- [OpenAPI Specification 3.0.4](https://spec.openapis.org/oas/v3.0.4.html)
+- [OpenAPITools `openapi-diff` 官方仓库](https://github.com/OpenAPITools/openapi-diff)