create-yss-spec 2.2.10 → 3.0.1

package/template/.hermes/skills/yss-product-lifecycle/references/orchestration.md

@@ -1,116 +0,0 @@
-# 编排执行协议
-
-## 有界推进循环
-
-1. 识别模式、仓库身份、任务规模和影响面。
-2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
-3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段。
-4. 评估资产、门禁和 `stale`，选择第一个未阻塞工作单元。进入 `work-unit.slice-implementation` 前，必须先通过 `scripts/lib/lifecycle-transition.mjs` 的 Ticket 正式化、垂直切片绑定和合法 `next_route` 校验；父 Ticket、缺少垂直切片或 `ready-for-human` 的切片一律 `blocked`。
-5. 执行最小生命周期工作单元：主控先按 `docs/process/schemas/digital-human-task-package.schema.json` 编译并校验任务包，再只实际调用允许的 model-invoked skill；原生工作单元可直接持有正式资产，Matt 兼容 user-invoked skill 仅作为 workflow reference，仍由用户显式启动。将结果归一化为 `Workflow Execution Result`，验收输出并回写状态与证据。任务包的 `contract.kind` 按工作单元选择；只有实现子任务使用 `slice-implementation` 并消费 Slice Implementation Contract，其他阶段不伪造该合同。
-6. 若仍在授权和自动推进边界内，回到第 3 步；否则暂停。
-
-不要仅输出下一个提示词后结束 `orchestrate`/`resume`。不要因进入业务代码阶段而退出主控；应把实现交给专项 skill，并在返回后继续核验。
-
-连续阶段自动推进时累积 Ticket 同步和 Git 判断证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint。发生阻塞、责任人变化或资产需要单独批准时立即落 checkpoint，不因合并记录而丢失阶段因果关系。
-
-## 阶段边界
-
-Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命周期状态。按以下顺序判断，第一项适用即停止判断：
-
-1. **Continue**：下一阶段需要当前会话作为 primary source，或当前上下文仍在 smart zone 内。
-2. **`/clear`**：当前探索、死路和决策对下一阶段完全无关。
-3. **`/handoff`**：内容必须跨新 harness、新目录、同事或中途分叉的 side task 携带。
-4. **Subagent**：工作单元边界清晰，可以在无人值守时完成并返回报告。
-5. **`/compact`**：同一 harness、同一目录且上下文仍相关，但需要压缩后继续；它是最后选项。
-
-在 checkpoint 记录 `phase_boundary.decision`；使用 `handoff`、subagent 或 `compact` 时同时记录契约要求的引用。phase boundary 不得改变生命周期阶段、门禁或 Ticket 五态。
-
-## 原型到后端脚手架的接力
-
-`prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，先完成工程基线，由 `yss-router` 编译脚手架 `controlled-generation` 工作单元合同，生命周期编排器批准并持久化后才能运行生成器；顺序为：工程基线 → Router 脚手架合同 draft → 生命周期批准/持久化 → 脚手架生成 → `yss-backend-scaffold-parent` 基线校验 → Router 合同重编译。`existing` / `initialized` 不重复全量生成，但不能跳过基线校验和 Router 重编译。
-
-脚手架工作单元必须使用结构化合同 JSON 文件，至少记录 `contract_id`、`contract_version`、`slice_id`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；批准记录至少含 `approval_ref`、`approver`、`persisted_ref`、`current_version`。生成器必须读取该合同文件并校验状态、版本、skill、工作模式和固定命令，不能只接受任意字符串参数。它还必须记录生成器输入、预期文件、目标目录、实际 `./mvnw validate` / `./mvnw test` / `./mvnw package` 结果和 YSS Skill Execution Result。三条命令必须由受控工作单元真实执行，逐条留存 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的下一步命令不构成证据。生命周期生成关闭 `--with-example`；非空目标目录使用 `--force` 默认阻断，除非覆盖范围、备份、回滚点和批准引用已进入合同。脚手架不得把业务规则、状态机、权限、事务、复杂查询、错误映射或用户可见行为放进生成物；`validate` 通过、输出目录存在或生成器成功都不是生命周期批准、架构放行或 `ready-for-agent`。
-
-脚手架完成后，所有后续生成的后端代码仍必须重新消费当前版本的批准 Slice Implementation Contract、YSS skill 依赖闭包、允许写路径、预期证据和 Execution Result。业务行为使用 `behavior-tdd`；只有机械结构、样板、配置和冻结客户端使用 `controlled-generation`。缺少合同、skill、证据或实际验证时立即阻断；生成范围从机械内容变成业务行为时触发完整重路由。
-
-## Setup readiness
-
-Readiness 结果在同一任务内复用。只有 tracker、主远端、真实标签或配置发生变化，才重新执行检查；不得把 `setup-matt-pocock-skills` 当作每阶段或每工作单元的固定动作。
-
-| 状态 | 判定 | 动作 |
-|---|---|---|
-| `ready` | tracker、Local `Status:` 或远程标签和领域布局兼容 | 继续 |
-| `missing` | 必要配置缺失 | `needs-human`；说明缺失项并请用户显式运行 `setup-matt-pocock-skills`，随后回到 readiness |
-| `conflict` | 多个持久配置或真实标签/Local 状态互相矛盾 | 暂停并提出迁移方案，不覆盖 |
-| `degraded` | 已选择的 GitHub/GitLab 不可用 | 建 `docs/.scratch/<feature>/` 待发布草案，不改投平台 |
-| `not-applicable` | `template-source` | 只验证模板契约 |
-
-远程 tracker 必须检查真实标签；Local Markdown 必须检查功能包目录和 Ticket 顶部的 `Status:`。仅有 `docs/agents/triage-labels.md` 不代表远程标签存在，也不能替代 Local 文件状态检查。
-
-tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化 tracker 配置优先，本模板默认 `local-markdown`，Local root 为 `docs/.scratch/`；用户在初始化/迁移时明确选择 GitHub/GitLab 后才切换，Git remote 只代表代码托管。Local 主 tracker 不要求远程 Ticket；只有已选择远程平台但凭据不可用时，才降级为 `docs/.scratch/<feature>/` 待发布草案，不自动改投其他平台。发现根 `.scratch/` 或 `docs/requirements/tickets/` 旧资产时，保留 `migration_ref` 并暂停写入；新旧路径同时存在时返回 `conflict`。恢复前记录最终平台、真实五态标签或 Local `Status:` 检查结果和草案位置。
-
-## Matt flow 进入条件
-
-- `work-unit.technical-analysis` 命中聚合、状态机、不变量、一致性、Domain Event、Gateway 或持久化映射影响时，先调度 `yss-tactical-design` 完成 Tactical DDD Check；默认嵌入系统概要设计 / 数据架构，复杂场景才生成 `artifact.tactical-design`。无领域影响记录 `not-applicable`。该 skill 只返回设计合同和验证结果，批准仍由生命周期编排器维护，发现 `stale`、`drift` 或 `new_impacts` 时不得继续 Ticket 正式化。
-
-- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `research`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
-- 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始 Ticket 状态统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。该工作单元必须返回 `ticket_decomposition_result_ref` 和垂直切片引用，并作为实现的必经前置证据。
-- 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
-- `Workflow Execution Result.next_route` 必须通过生命周期转换校验；Spec、原型和技术分析不得直接跳转到 `work-unit.slice-implementation`，只能先进入 `work-unit.ticket-decomposition`。
-- `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 合同重编译均已回写；否则停在工程基线，不得写业务代码。
-- `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。
-
-## 审查与验证
-
-- 调用 `code-review` 前先固定 review input：`review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、Spec/Ticket、Slice Implementation Contract、Build Architecture Checklist 和 YSS Skill Execution Result 引用。`committed` 模式审查不可变 `HEAD`；`worktree` 模式一次捕获 committed、staged、unstaged 和 untracked 内容。必须按 `orchestration-contract.yaml.review_input` 的 manifest 按模式必填字段及 `yss-worktree-candidate-v1` 字节流（raw path、uint64 big-endian 长度、tracked/untracked record）计算 SHA-256，两个 Reviewer 必须消费同一不可变快照。返回后或完成 checkpoint 摘要变化时返回 `blocked`，由编排器决定重新审查。候选为空、漏项或 fixed point 不可解析时阻断。
-- 小改动和中等变更可由同一独立执行者完成 `code-review` 与 fresh verification，并在同一报告中分别记录 findings、命令、结果和残余风险。
-- 该执行者必须独立于实现者；新模块、高风险变更、职责冲突或需双人控制时，Reviewer 与 Verifier 分开。
-- `code-review` 是唯一默认代码审查 skill。GitLab、CI、Sonar、Alibaba Java 与 YSS 前端 / 后端 skill 作为仓库规则或专项检查输入接入 Standards 轴，由 `review_standards_route` 按影响面编译；不再叠加第二个通用审查 skill。漏掉合同 `required_skills`、适用报告行空白、mandatory `violation` 未关闭或可机器检查规则既无工具结果也无原文引用时，不得 `completed`。
-- 产品切片与模板维护共用同一 finding 闭环，强度分别绑定 Slice 合同与 L1 / L2 / L3。`violation`、机器检查失败、适用行空白由实现者在原合同路径修复，再重新捕获候选并全轴复审。`drift`、`new_impacts`、`required_skills` 与真实影响不一致时合同 `stale`，回 Router 或更早阶段，禁止在旧合同上继续编码。审查者不得写实现。`not-applicable` 仅当影响面未命中；命中后 mandatory 不得豁免，只允许修复或完整 `seam-deferred`。禁止为日常 Alibaba / YSS 新增生物人豁免门禁。
-- 独立 Reviewer 必须与实现者不同实例，并在能执行已登记 `pnpm` / `./mvnw` 的运行时中审查。模板源 `.cursor/environment.json` 只服务模板校验，不替代实现仓审查运行时。不为此再创建第二个 Cloud 审查环境或 `/code-review` skill。
-- UI 影响切片将 `UI fidelity` 作为 `code-review` 的条件第三轴；任何修复都会使候选摘要失效，必须重新捕获候选并重跑 Standards、Spec、UI fidelity 和 fresh verification。
-
-## Git 授权
-
-实现授权、`orchestrate`/`resume` 的有界写入、当前分支和 Git checkpoint 都不蕴含 commit 或 push 授权。执行 commit 前必须同时取得 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 前必须同时取得 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。任一缺失时只记录 checkpoint 判断并保持 Git 状态不变；负责人要求、时间压力、测试通过或“本地 commit 可逆”都不能补足用户授权。
-
-`repository_scope: git-submodule` 时授权按仓分别计算：禁止在 detached HEAD 提交；commit / push 顺序必须先子仓、再父仓 gitlink（`superproject-gitlink-update`）；父仓 push 使用 `git push --recurse-submodules=check`。空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录脚手架，也不得把实现源码复制进 Harness。登记字段必须能与 `harness-apps` / `external-repository` 区分，并对照工作树 gitlink。
-
-## 必须暂停
-
-- Spec baseline、需求冻结、原型确认、OpenAPI Freeze 或 Architecture Review 等普通门禁等待会签裁决（数字人或生物人，以 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 为准）。暂停输出必须包含：门禁 ID、指定 `role_id`、`runtime_id`、会签文件路径。恢复前执行 `scripts/verify-approval-record`；角色错误、起草者自签或生物人门禁被数字人关闭时返回 `blocked`，不得标 `approved`。
-- 需要目标仓库、外部凭据、发布窗口或其他新授权。
-- 状态与证据冲突且无法可靠重建。
-- 专项 skill 失败或返回不可验收结果。
-- 即将作出可合并、可发布或完成结论。
-
-暂停输出：门禁、指定会签 `role_id`、`runtime_id`、会签文件路径、证据、推荐答案、一个问题、恢复动作。
-
-## Context Plan 与质量基线
-
-实现合同先消费 `common.context_plan`：必需上下文只包含 `CONTEXT.md`、已批准 Spec、当前合同和适用 ADR / 工程基线；专项 references、实现仓库文件和历史证据按影响面按需加载。达到最小充分证据后停止扩展，缺失权威上下文只能 `blocked` 或 `reroute`。
-
-质量标准由 `engineering-baseline` 以 `baseline_id` / `baseline_version` 定义一次，Slice Contract、YSS Skill Execution Result、`code-review` 和发布检查只引用它，并将约束结果写入 `constraint_results`。命中 API / 数据迁移、跨仓契约、发布回滚、实际安全行为或生命周期 / 生成语义时，必须在现有决策或审查记录中完成 Doubt-Driven 主张、反证、证据、残余风险和 Reviewer 引用；普通低风险变更不触发该流程。
-
-## Wayfinder 完成判定
-
-“无 frontier”不等于完成。只有以下条件同时成立，才能 `wayfinder → handoff → to-spec`：
-
-- open child tickets 为 0；
-- 不存在 open blocked 或 open claimed child ticket；
-- `Not yet specified` 无剩余 fog；
-- destination 已清晰。
-
-Decision ticket 产生决策，不是实现切片，不得标记 `ready-for-agent`。
-
-## `grill-with-docs` 退出判定
-
-进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
-
-Prototype 回流必须有可核验证据：来源 handoff、prototype 资产或运行记录、结论、被更新的 Spec/设计/ADR/Ticket 引用、剩余未决项和返回 handoff。仅在对话中声称“已验证”不算回流完成。
-
-Matt `prototype` 的回流还必须注明 `prototype_branch`，并保留单文件 HTML 主来源；YSS 高保真 HTML 原型另走阶段 4 的评审、AntD CLI 校验和用户确认，不得用 throwaway prototype 替代。
-
-`to-questionnaire` 未收到答案时使用 `external-input-required` 暂停，记录问卷、接收人、所需输出和恢复路由；收到答案后记录 response、重新分类影响面和更新后的权威资产，再回到 `grill-with-docs` 或 `to-spec`。
-
-Release 与 Retrospective 属于生命周期编排器拥有的工作单元。发布和复盘前都必须重新取得 fresh verification；发布还需要发布/回滚证据和独立审查，复盘还需要复盘记录和治理回流判断，再回流权威资产。

package/template/.hermes/skills/yss-product-lifecycle/references/state-model.md

@@ -1,112 +0,0 @@
-# 生命周期状态模型
-
-## 命名空间
-
-| 域 | 允许值 |
-|---|---|
-| `lifecycle.status` | `routing`、`running`、`paused-human-gate`、`blocked`、`completed` |
-| `workflow.status` | `not-started`、`active`、`paused`、`resolved`、`failed` |
-| `artifacts.*.status` | `missing`、`draft`、`ready-for-human`、`approved`、`stale`、`not-applicable` |
-| `gates.*.status` | `not-evaluated`、`blocked`、`ready-for-human`、`approved`、`stale`、`not-applicable` |
-| `tracker.kind` | `local-markdown`、`github`、`gitlab` |
-| `ticket.role` | `needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix` |
-
-Matt 五态不得扩义。资产的 `ready-for-human` 与 Ticket label 必须带命名空间表达。`paused-human-gate` 表示等待 `docs/agents/digital-human-roles.yaml` 指定的会签人（数字人或生物人），不是「必须是生物人」。
-
-## 上下文与外部输入证据
-
-状态模型不新增 context 状态域。阶段边界只在状态块或 checkpoint 中保存可选证据：
-
-```yaml
-phase_boundary:
-  decision: continue # continue / clear / handoff / subagent / compact
-  reason: <why-this-choice>
-  source_ref: null
-  destination_ref: null
-  task_package_ref: null
-  convergence_ref: null
-  next_phase: null
-```
-
-`handoff` 必须有来源和目的地；subagent 必须有任务包和汇合证据；`compact` 必须有下一阶段。`Continue`、`clear` 不要求跨上下文引用，但仍应记录判断理由。
-
-`to-questionnaire` 的暂停使用 `pause.reason_code: external-input-required`，并保存 `questionnaire_ref`、`recipient_role`、`requested_outputs` 和 `resume_route`。答案回流后补 `response_ref`、`reclassified_impact` 和 `updated_authoritative_asset`，然后重新计算 `stale`、门禁和可执行 frontier。
-
-## `ready-for-agent` 公式
-
-仅当以下全部为真，垂直切片 Ticket 才能获得该 Ticket 状态：
-
-```text
-required gates ∈ {approved, not-applicable}
-AND related artifacts 不含 stale（若命中领域影响，`artifact.tactical-design` 或嵌入式 Tactical DDD Check 引用必须为当前版本）
-AND blocking edges 全部关闭
-AND implementation repo/branch/CI/test/rollback 已明确
-AND `work-unit.ticket-decomposition` 已返回 `completed`，且其 `ticket_decomposition_result_ref` 证据可读取
-AND `vertical_slice_ticket_ref` 指向 `docs/.scratch/<feature>/issues/` 下的垂直切片 Ticket
-AND `vertical_slice_ticket_kind=vertical-slice-ticket` 且 `vertical_slice_ticket_role=ready-for-agent`
-AND `vertical_slice_ticket_ref` 不得指向 `parent-ticket.md`
-AND Slice Implementation Contract 已由生命周期编排器批准并持久化
-AND Slice Implementation Contract 的 `ticket_ref` 与 `vertical_slice_ticket_ref` 完全一致
-AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
-AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
-AND backend 影响且 scaffold_status=required 时，原型确认后的脚手架策略、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 重编译均已完成
-AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
-AND UI 影响切片的前端实现还原计划已通过 schema 校验、`template=false`、`status=approved`，且基线引用可读取
-```
-
-父 Ticket、Spec、设计、原型、OpenAPI Draft、wayfinder map 和 decision ticket 不得使用 `ready-for-agent`。
-
-发布前还必须满足所有已触发门禁均为 `approved` 或 `not-applicable`；UI 影响切片必须额外通过 `gate.frontend-implementation-verified`，不能只凭 fresh verification 和回滚点放行。
-
-用户显式运行 `to-tickets` 后，垂直切片初始 Ticket 状态固定为 `ready-for-human`。原生路径执行 `work-unit.ticket-decomposition` 时同样必须产生等价的垂直切片和 `Workflow Execution Result` 证据。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，但不得跳过 Ticket 正式化工作单元。其默认标签也不参与该裁决。
-
-## Review 与 Git 授权状态
-
-进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用，并记录专项检查覆盖与机器检查结果。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。两个 Reviewer 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。Finding 分流不新增生命周期状态：`violation` 仍在当前合同路径由实现者修复后复审；`drift` / `new_impacts` 把合同标 `stale` 并走既有重路由。该清单只作为审查证据。
-
-Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
-
-## 状态块
-
-状态块位于主 tracker 的功能父 Ticket，并使用 `docs/process/templates/lifecycle-checkpoint-template.yaml` 的结构化形状和 `lifecycle-checkpoint.schema.json` 校验；Local Markdown 使用 `docs/.scratch/<feature>/parent-ticket.md`，可将完整 checkpoint 保存在 `docs/.scratch/<feature>/gates/lifecycle-checkpoint.yaml` 后由父 Ticket 引用，远程 tracker 使用 Issue 并在本地功能包保留引用。平台不可用时才位于 stage checkpoint。只保存索引、状态、引用和因果关系：
-
-```yaml
-lifecycle:
-  schema_version: 1
-  mode: resume
-  stage: system-data-architecture-and-contract-review
-  status: blocked
-workflow:
-  matt_flow: main
-  active_skill: yss-openapi-draft-review
-  status: paused
-artifacts:
-  spec: {status: approved, ref: docs/.scratch/example/spec.md}
-  openapi: {status: stale, ref: docs/.scratch/example/api/example.yaml, stale_by: [spec]}
-gates:
-  openapi_freeze: {status: stale}
-tracker:
-  kind: local-markdown
-  root: docs/.scratch
-  parent_ticket: docs/.scratch/example/parent-ticket.md
-  role: ready-for-human
-pause:
-  reason_code: human-gate
-  gate_ref: requirement-freeze
-  owner_or_authority: product-owner
-  resume_condition: requirement-freeze-approved
-  next_work_unit: api-impact-assessment
-```
-
-## Schema 兼容与迁移
-
-- 当前只支持 `schema_version: 1`，支持版本列表以 `orchestration-contract.yaml` 为准。
-- 版本缺失、解析失败或版本不在支持列表时，必须暂停并进入迁移检查；不得按 v1 猜测、覆盖或降级写回。
-- 主 tracker 的父 Ticket 状态块优先作为主索引；Local Markdown 的 `docs/.scratch/<feature>/parent-ticket.md` 是主载体，远程 Issue 只是显式选择远程 tracker 时的主载体。根 `.scratch/` 与 `docs/requirements/tickets/` 只作为旧路径迁移来源。stage checkpoint 只在选定平台不可用时降级。两者版本或内容冲突时，不做字段级静默合并：读取真实资产重建新状态，保留旧块引用和迁移记录，再由人工确认主载体。
-- 不得用旧版本状态覆盖较新版本。迁移记录至少包含来源版本、目标版本、来源载体、冲突、真实资产证据、迁移人和时间。
-
-## Resume
-
-读取状态块后必须重新读取引用资产、审查记录、Ticket 最新事件和相关 Git 变化。时间戳只能提示变化，不能单独证明语义失效；应比较内容和影响面。冲突时以权威资产为准，记录修复原因，然后重算依赖、门禁和可执行 frontier。
-
-所有暂停/阻塞必须填写结构化 `pause`：`reason_code`、`gate_ref` 或证据引用、`owner_or_authority`、`resume_condition`、`next_work_unit`。`lifecycle.status` 保持粗粒度，恢复条件以 `pause` 为准。

package/template/.hermes/skills/yss-prototype-stage/SKILL.md

@@ -1,47 +0,0 @@
----
-name: yss-prototype-stage
-description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs prototype assets before implementation readiness.
----
-
-# YSS Prototype Stage
-
-把产品设计影响收敛为跨 Agent 一致的产物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
-
-## 进入条件与主入口
-
-- 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
-- Codex 的产出主入口是 `product-design:index`；其他 Agent 使用等价的产品设计能力，但必须产出本技能规定的相同资产和证据。能力或证据不能等价时，暂停并回到人工确认。
-- `high-fidelity-html-prototype` 仅为历史兼容入口；从它进入时立即回到本合同。已退休的原型技能（含 `product-design-prototype`）不得继续路由。
-
-## 资产与门禁顺序
-
-1. 以 Spec、产品总体设计、`yss-design-system` 和 `docs/design/design.md` 形成交互说明、低保真页面/流程与状态矩阵。
-2. 用 `prototype-review` 形成独立评审结论；未通过不得生成高保真或进入需求冻结。
-3. 用 `yss-antd-design` 固定目标 React `antd@6.x`，先查询 `design.md` 与本功能组件事实。
-4. 通过 `product-design:index` 的 `get-context → ideate → 用户选择 → image-to-code → design-qa` 产出 feature 级 React/Vite 原型；必须套用 `references/product-design-adapter.md`，不能把通用 starter 视为已符合 YSS。
-5. 完成 AntD post-build manifest/lint（按产物类型）、同视口 Design QA、浏览器与无障碍验证，写入 schema v2 `docs/.scratch/<feature>/verification/prototype-evidence.yaml`。
-6. 用户确认后，才可校准 Spec、分析 API 影响或进入 Router readiness。
-
-## 设计与 AntD 依据
-
-优先级固定为：官方 `design.md` 的上游默认 → `docs/design/design.md` 与项目 token 的 `project_design` 项目覆盖 → 当前功能的语义组件映射。不得用上游默认覆盖项目 token。
-
-Codex `$design-qa` 仍走官方对比流程；Colors/tokens 与 Fonts/typography 必须以项目覆盖为 source visual truth。对照清单见 `yss-design-system/references/design-qa-theme.md`。仍用官方 `#1677ff`、强制 `Inter` 或历史 8px 品牌圆角当默认主题，视为项目覆盖漂移。
-
-主题与视觉标准固定为 `ant-design-v6`；生产运行时固定为 Vue 3 + YSS UI + `ant-design-vue-4.x`，精确生产版本来自实现仓 lockfile。版本号不同本身不是冲突。Ant Design v6 事实由 `yss-antd-design` 查询并回写证据，不要并列调用官方 `antd` skill，也不要在前端代码落地时继续使用它。进入实现后改走 `yss-ui`。
-
-标准原型组件存在 Ant Design 实现时必须精确锁定与 CLI 目标一致的 `antd@6.x`，并通过 `ConfigProvider` 消费项目主题 adapter。执行与验证命令见 `references/product-design-adapter.md` 和 `scripts/prototype-contract.mjs`。
-
-## 验证与回流
-
-`browser_verification` 至少覆盖非空渲染、主流程、一个失败/权限/冲突状态、桌面与窄屏视口和控制台错误；`accessibility_verification` 至少覆盖对比度、键盘/焦点、语义标签与 Dialog、200% zoom、reduced motion、目标尺寸和自动化扫描。优先使用 Browser 或可执行浏览器自动化，Computer Use 只作人工交互补充。把路径、命令、版本、视口、结果和阻塞项写入证据清单。
-
-`gate.prototype-reviewed` 的证据是评审记录；`gate.prototype-verified` 的证据是 AntD CLI 与浏览器验证；`gate.user-confirmation` 的证据是确认记录。三者均不是实现授权。
-
-## 常见错误
-
-- 仅有截图或 HTML，却没有可复现的 CLI、浏览器和确认记录。
-- 把 `product-design:index` 或某个旧技能当作生命周期批准者。
-- 直接复制官方默认颜色、圆角或间距，忽略项目覆盖。
-- 只证明查询过 AntD v6，却没有 v6 semantic role → 项目 Token → YSS/AntDV4 的映射证据。
-- 沿用 Product Design starter 的 npm、根目录 `design-qa.md` 或未安装 `antd` 的通用配置。

package/template/.hermes/skills/yss-prototype-stage/references/product-design-adapter.md

@@ -1,54 +0,0 @@
-# YSS Product Design Adapter
-
-本合同把 Codex Product Design 的通用 React/Vite 产出接入 YSS 原型阶段。它不修改上游 Product Design skill，也不把 React API 带入 Vue 生产实现。
-
-## 双轨版本
-
-- `design_standard: ant-design-v6`：高保真原型的主题、视觉语义、标准组件和 CLI 事实。
-- `runtime_component_library: ant-design-vue-4.x`：生产 Vue/YSS 组件 API；精确版本只从实现仓 lockfile 读取。
-- 标准原型组件存在 Ant Design 实现时，React 原型必须精确锁定与 CLI 查询一致的 `antd@6.x`。YSS 专有布局可用适配 CSS，但仍消费项目 Token。
-- 禁止把 React hook、props、JSX、静态 API 或事件模型作为 Vue/YSS 实现合同。
-
-## 产出前适配
-
-1. 目标目录固定为 `docs/.scratch/<feature>/design/prototypes/`。
-2. Product Design 完成 `get-context`、三方案 `ideate` 和用户视觉选择后，进入 `image-to-code` 的 local preflight，只执行官方 bootstrap 创建空 starter；在安装依赖或编写 UI 前立即运行 adapter：
-
-   ```bash
-   node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare \
-     --project-root <project-root> \
-     --root <project-root>/docs/.scratch/<feature>/design/prototypes \
-     --feature <feature> \
-     --target-antd-version <exact-6.x-version> \
-     --pnpm-version <actual-pnpm-version>
-   ```
-
-3. adapter 只做机械动作：精确写入 `antd` 版本、登记 pnpm、生成 `src/yss-theme.js` 和 `yss-prototype-adapter.json`。随后由 Product Design 将入口包在 `ConfigProvider theme={yssTheme}` 中，并优先使用标准 `antd` 组件。
-4. 执行 `pnpm install`、`pnpm build`，保留 `pnpm-lock.yaml`、源码入口、构建入口、实际命令与退出码。禁止用 npm lockfile 代替受控例外记录。
-5. 校验项目：
-
-   ```bash
-   node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project \
-     --root <project-root>/docs/.scratch/<feature>/design/prototypes \
-     --target-antd-version <exact-6.x-version>
-   ```
-
-## 视觉与实现映射
-
-每个关键组件在 `visual_semantic_mapping` 中记录四层映射：Ant Design v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 目标。映射的是视觉角色、状态和验收行为，不是 React API 表面形状。
-
-至少覆盖主操作、表单输入、表格/列表、反馈、弹层和导航中本功能实际出现的类型。每项记录 `default/hover/active/disabled/loading/error` 等适用状态，并把 `react_only_api_not_copied` 设为 `true` 后才能通过。
-
-## 视口、QA 与无障碍
-
-- 默认视觉目标和同状态 QA 使用 desktop `1440x900`、mobile `390x844`；按影响追加 tablet/laptop/wide，不机械要求九个视口。
-- Design QA 报告固定到 `docs/.scratch/<feature>/verification/design-qa.md`，不得写仓库根共享文件。
-- 项目品牌 Seed `#3371ff` 保持不变；普通文本、按钮及状态组合不满足 WCAG 2.2 AA 时，通过组件 Token 调整实际填充或文字色，并保存对比度证据。
-- 验证至少包含键盘、焦点、语义标签/Dialog、200% zoom、reduced motion、目标尺寸和自动化扫描；工具不可用时记录人工替代与未覆盖缺口，不得空填 passed。
-
-## 交互档位
-
-- `reviewable-flow`（默认）：合同内主路径和关键状态可操作；非范围控件禁用或明确标注，不伪装完整功能。
-- `full-prototype`：brief 明确要求的全部可见范围控件可操作。
-
-不得使用含义冲突的 `static` / `mostly-static` 作为 YSS 交付状态。

package/template/.hermes/skills/yss-prototype-stage/scripts/prototype-contract.mjs

@@ -1,207 +0,0 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
-
-const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
-const object = (value) => value && typeof value === "object" && !Array.isArray(value);
-const semver = /^6\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
-const pnpmSemver = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
-
-function required(data, field, parent, errors) {
-  if (!object(data) || data[field] === undefined || data[field] === null) errors.push(`${parent}.${field} 缺失`);
-}
-
-function requiredString(data, field, parent, errors) {
-  required(data, field, parent, errors);
-  if (object(data) && data[field] !== undefined && !nonEmpty(data[field])) errors.push(`${parent}.${field} 必须是非空字符串`);
-}
-
-function requiredPassed(data, field, parent, errors) {
-  requiredString(data, field, parent, errors);
-  if (object(data) && nonEmpty(data[field]) && !["passed", "approved"].includes(data[field])) errors.push(`${parent}.${field} 必须为 passed/approved`);
-}
-
-export function validatePrototypeEvidence(data, { allowTemplate = false, allowLegacy = false } = {}) {
-  const errors = [];
-  const warnings = [];
-  if (!object(data)) return { errors: ["原型证据必须是对象"], warnings };
-  if (data.schema_version === 1) {
-    if (!allowLegacy) errors.push("schema_version 1 是旧证据；完成 gate.prototype-verified 前必须迁移到 2，或只读时显式 --allow-legacy");
-    else warnings.push("legacy prototype evidence schema v1");
-    return { errors, warnings };
-  }
-  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
-  for (const field of ["feature", "prototype_ref", "prototype_stack", "design_baseline", "visual_semantic_mapping", "antd", "browser_verification", "design_qa", "accessibility_verification", "review", "user_confirmation", "blockers"]) required(data, field, "root", errors);
-
-  const templateValue = (value) => allowTemplate && nonEmpty(value) && /<[^>]+>/.test(value);
-  const stack = data.prototype_stack;
-  if (object(stack)) {
-    for (const field of ["framework", "package_manager", "package_manifest_ref", "lockfile_ref", "source_entry_ref", "build_entry_ref", "build_command", "build_result", "actual_antd_version"]) requiredString(stack, field, "prototype_stack", errors);
-    if (stack.framework !== "react") errors.push("prototype_stack.framework 必须为 react");
-    if (stack.package_manager !== "pnpm") errors.push("prototype_stack.package_manager 必须为 pnpm");
-    if (nonEmpty(stack.lockfile_ref) && !stack.lockfile_ref.endsWith("pnpm-lock.yaml")) errors.push("prototype_stack.lockfile_ref 必须指向 pnpm-lock.yaml");
-    if (!templateValue(stack.actual_antd_version) && nonEmpty(stack.actual_antd_version) && !semver.test(stack.actual_antd_version)) errors.push("prototype_stack.actual_antd_version 必须是明确的 antd 6.x semver");
-    if (!allowTemplate) requiredPassed(stack, "build_result", "prototype_stack", errors);
-  }
-
-  const baseline = data.design_baseline;
-  if (object(baseline)) {
-    for (const field of ["design_standard", "project_design_ref", "project_token_refs", "theme_adapter_ref", "project_override_reviewed"]) required(baseline, field, "design_baseline", errors);
-    if (baseline.design_standard !== "ant-design-v6") errors.push("design_baseline.design_standard 必须为 ant-design-v6");
-    if (!Array.isArray(baseline.project_token_refs) || baseline.project_token_refs.length === 0) errors.push("design_baseline.project_token_refs 必须是非空数组");
-    if (!allowTemplate && baseline.project_override_reviewed !== true) errors.push("design_baseline.project_override_reviewed 必须为 true");
-  }
-
-  const mapping = data.visual_semantic_mapping;
-  if (object(mapping)) {
-    if (mapping.runtime_component_library !== "ant-design-vue-4.x") errors.push("visual_semantic_mapping.runtime_component_library 必须为 ant-design-vue-4.x");
-    if (mapping.runtime_version_source !== "implementation-lockfile") errors.push("visual_semantic_mapping.runtime_version_source 必须为 implementation-lockfile");
-    if (!Array.isArray(mapping.components) || mapping.components.length === 0) errors.push("visual_semantic_mapping.components 必须是非空数组");
-    for (const [index, component] of (mapping.components ?? []).entries()) {
-      const parent = `visual_semantic_mapping.components[${index}]`;
-      for (const field of ["semantic_role", "antd_v6_component", "project_token_refs", "yss_or_antdv_target", "state_mapping", "react_only_api_not_copied", "verification_ref"]) required(component, field, parent, errors);
-      if (!Array.isArray(component?.project_token_refs) || component.project_token_refs.length === 0) errors.push(`${parent}.project_token_refs 必须是非空数组`);
-      if (!Array.isArray(component?.state_mapping) || component.state_mapping.length === 0) errors.push(`${parent}.state_mapping 必须是非空数组`);
-      if (!allowTemplate && component?.react_only_api_not_copied !== true) errors.push(`${parent}.React-only API 未确认隔离`);
-    }
-  }
-
-  if (object(data.antd)) {
-    requiredString(data.antd, "target_antd_version", "antd", errors);
-    if (object(stack) && nonEmpty(data.antd.target_antd_version) && nonEmpty(stack.actual_antd_version) && !templateValue(data.antd.target_antd_version) && data.antd.target_antd_version !== stack.actual_antd_version) errors.push("antd.target_antd_version 必须与 prototype_stack.actual_antd_version 一致");
-  }
-  if (object(data.design_qa)) {
-    requiredString(data.design_qa, "report_ref", "design_qa", errors);
-    requiredString(data.design_qa, "result", "design_qa", errors);
-    if (nonEmpty(data.design_qa.report_ref) && !/^docs\/\.scratch\/[^/]+\/verification\/design-qa\.md$/.test(data.design_qa.report_ref) && !templateValue(data.design_qa.report_ref)) errors.push("design_qa.report_ref 必须是 feature 级 verification/design-qa.md");
-    if (!allowTemplate) requiredPassed(data.design_qa, "result", "design_qa", errors);
-  }
-  const accessibility = data.accessibility_verification;
-  if (object(accessibility)) {
-    for (const field of ["contrast_results_ref", "keyboard_navigation_result", "focus_visible_and_order_result", "semantic_label_dialog_result", "zoom_200_result", "reduced_motion_result", "target_size_result", "automated_scan"]) required(accessibility, field, "accessibility_verification", errors);
-    requiredString(accessibility, "contrast_results_ref", "accessibility_verification", errors);
-    if (!allowTemplate) for (const field of ["keyboard_navigation_result", "focus_visible_and_order_result", "semantic_label_dialog_result", "zoom_200_result", "reduced_motion_result", "target_size_result"]) requiredPassed(accessibility, field, "accessibility_verification", errors);
-    if (object(accessibility.automated_scan)) for (const field of ["tool", "version", "result", "ref"]) requiredString(accessibility.automated_scan, field, "accessibility_verification.automated_scan", errors);
-  }
-  if (!Array.isArray(data.blockers)) errors.push("root.blockers 必须是数组");
-  if (!allowTemplate && Array.isArray(data.blockers) && data.blockers.length > 0) errors.push("存在 blockers，不能通过原型验证");
-  return { errors, warnings };
-}
-
-function safePrototypeRoot(projectRoot, root, feature) {
-  const resolvedProject = path.resolve(projectRoot);
-  const resolvedRoot = path.resolve(root);
-  const expected = path.resolve(resolvedProject, "docs/.scratch", feature, "design/prototypes");
-  if (resolvedRoot !== expected) throw new TypeError(`原型目录必须精确匹配 ${expected}`);
-  if (!resolvedRoot.startsWith(`${resolvedProject}${path.sep}`)) throw new TypeError("原型目录越出项目根");
-  return { resolvedProject, resolvedRoot };
-}
-
-export async function preparePrototype({ projectRoot, root, feature, targetAntdVersion, pnpmVersion }) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
-  if (!semver.test(targetAntdVersion ?? "")) throw new TypeError("targetAntdVersion 必须是明确的 antd 6.x semver");
-  if (!pnpmSemver.test(pnpmVersion ?? "")) throw new TypeError("pnpmVersion 必须是明确 semver");
-  const { resolvedProject, resolvedRoot } = safePrototypeRoot(projectRoot, root, feature);
-  const packagePath = path.join(resolvedRoot, "package.json");
-  if (!existsSync(packagePath)) throw new TypeError(`缺少 Product Design starter package.json: ${packagePath}`);
-  const pkg = JSON.parse(await readFile(packagePath, "utf8"));
-  pkg.packageManager = `pnpm@${pnpmVersion}`;
-  pkg.dependencies = { ...(pkg.dependencies ?? {}), "@ant-design/icons": "^6.0.0", antd: targetAntdVersion };
-  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
-
-  const themeSourcePath = path.join(resolvedProject, "docs/design/tokens/theme.json");
-  if (!existsSync(themeSourcePath)) throw new TypeError(`缺少项目主题: ${themeSourcePath}`);
-  const themeSource = JSON.parse(await readFile(themeSourcePath, "utf8"));
-  const generated = [
-    'import { theme } from "antd";',
-    "",
-    `const source = ${JSON.stringify(themeSource, null, 2)};`,
-    'const layoutKeys = new Set(["layoutHeaderHeight", "layoutSiderBackground", "layoutBodyBackground"]);',
-    "export const yssLayoutTokens = Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => layoutKeys.has(key)));",
-    "export const yssTheme = {",
-    "  algorithm: [theme.defaultAlgorithm, theme.compactAlgorithm],",
-    "  token: Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => !layoutKeys.has(key)))",
-    "};",
-    ""
-  ].join("\n");
-  await mkdir(path.join(resolvedRoot, "src"), { recursive: true });
-  await writeFile(path.join(resolvedRoot, "src/yss-theme.js"), generated);
-  const manifest = {
-    schema_version: 1,
-    feature,
-    design_standard: "ant-design-v6",
-    target_antd_version: targetAntdVersion,
-    prototype_framework: "react",
-    package_manager: `pnpm@${pnpmVersion}`,
-    theme_source: "docs/design/tokens/theme.json",
-    theme_adapter: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`,
-    production_runtime: { framework: "vue-3", component_library: "ant-design-vue-4.x", version_source: "implementation-lockfile" },
-    next_commands: ["pnpm install", "pnpm build"]
-  };
-  await writeFile(path.join(resolvedRoot, "yss-prototype-adapter.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-  return manifest;
-}
-
-export async function validatePrototypeProject({ root, targetAntdVersion }) {
-  const errors = [];
-  const packagePath = path.join(root, "package.json");
-  if (!existsSync(packagePath)) return { errors: ["缺少 package.json"] };
-  const pkg = JSON.parse(await readFile(packagePath, "utf8"));
-  if (pkg.dependencies?.antd !== targetAntdVersion) errors.push(`package.json 必须精确锁定 antd ${targetAntdVersion}`);
-  if (!String(pkg.packageManager ?? "").startsWith("pnpm@")) errors.push("package.json 必须记录实际 pnpm packageManager");
-  if (!existsSync(path.join(root, "pnpm-lock.yaml"))) errors.push("缺少 pnpm-lock.yaml");
-  if (!existsSync(path.join(root, "src/yss-theme.js"))) errors.push("缺少 src/yss-theme.js");
-  const sourceFiles = ["src/App.jsx", "src/App.tsx", "src/main.jsx", "src/main.tsx"].filter((file) => existsSync(path.join(root, file)));
-  const source = (await Promise.all(sourceFiles.map((file) => readFile(path.join(root, file), "utf8")))).join("\n");
-  if (!/ConfigProvider/.test(source) || !/yssTheme/.test(source)) errors.push("原型入口必须通过 ConfigProvider 消费 yssTheme");
-  if (!existsSync(path.join(root, "yss-prototype-adapter.json"))) errors.push("缺少 yss-prototype-adapter.json");
-  return { errors };
-}
-
-function args(argv) {
-  const result = { _: [] };
-  for (let index = 0; index < argv.length; index += 1) {
-    const item = argv[index];
-    if (!item.startsWith("--")) { result._.push(item); continue; }
-    const key = item.slice(2);
-    const value = argv[index + 1];
-    if (!value || value.startsWith("--")) result[key] = true;
-    else { result[key] = value; index += 1; }
-  }
-  return result;
-}
-
-async function loadYaml(file) {
-  const document = parseDocument(await readFile(file, "utf8"), { uniqueKeys: true });
-  if (document.errors.length > 0) throw new TypeError(document.errors[0].message);
-  return document.toJS({ maxAliasCount: 0 });
-}
-
-async function main(argv) {
-  const parsed = args(argv);
-  const command = parsed._[0];
-  if (command === "prepare") {
-    const result = await preparePrototype({ projectRoot: parsed["project-root"], root: parsed.root, feature: parsed.feature, targetAntdVersion: parsed["target-antd-version"], pnpmVersion: parsed["pnpm-version"] });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-  if (command === "validate-project") {
-    const result = await validatePrototypeProject({ root: parsed.root, targetAntdVersion: parsed["target-antd-version"] });
-    if (result.errors.length > 0) throw new TypeError(result.errors.join("\n"));
-    process.stdout.write("prototype project contract passed\n");
-    return;
-  }
-  if (command === "validate-evidence") {
-    const result = validatePrototypeEvidence(await loadYaml(parsed._[1]), { allowTemplate: Boolean(parsed["allow-template"]), allowLegacy: Boolean(parsed["allow-legacy"]) });
-    if (result.errors.length > 0) throw new TypeError(result.errors.join("\n"));
-    process.stdout.write(`prototype evidence passed${result.warnings.length ? ` with warnings: ${result.warnings.join(", ")}` : ""}\n`);
-    return;
-  }
-  throw new TypeError("usage: prototype-contract.mjs prepare|validate-project|validate-evidence ...");
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv.slice(2)).catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });