create-yss-spec 3.4.10 → 3.5.2

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

@@ -2,17 +2,25 @@
 
 ## 有界推进循环
 
-1. 按 `orchestration-contract.yaml.request_triage` 理解请求并选择模式，再识别仓库身份、任务规模和影响面；问题理解与澄清细节见 [请求分诊协议](request-triage.md)。
+1. 按 `orchestration-contract.yaml.request_triage` 理解请求并选择模式，再识别仓库身份、任务规模和影响面；问题理解与澄清细节见 [请求分诊协议](request-triage.md)。查看已有项目进度可用 `scripts/lifecycle-status --root <项目> --checkpoint <引用>` 读取当前阶段、阻塞、负责人和下一动作；此视图不推进状态或代替流转校验。
 2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
-3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段；按 `docs/process/stage-tracking.md` 登记、恢复并核验当前阶段工作项，写入前确保 checkpoint 已持久化，工作单元结果带 checkpoint_ref。
+3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段；按 `.template-spec/process/stage-tracking.md` 登记、恢复并核验当前阶段工作项，写入前确保 checkpoint 已持久化，工作单元结果带 checkpoint_ref。
 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，其他阶段不伪造该合同。
+5. 执行最小生命周期工作单元：主控先按 `.template-spec/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，不因合并记录而丢失阶段因果关系。
 
+## 状态查看与中断恢复
+
+`lifecycle-status` 保留原 JSON 字段，并以 `verification_scope` 区分已检查、失败、未检查和不适用；`diagnostics` 给出来源、已有负责人及恢复建议，`next_step` 给出前置条件和可用的命令参数数组。`blockers: []` 仅表示本次读取未发现阻塞，退出 0 不证明批准有效或允许实现。视图只写 stdout，不调用完整验证、远端或状态写入；缺少预检脚本时显示缺口，不能猜命令。
+
+恢复按合同 `execution_efficiency.recovery` 执行：读取当前 checkpoint、阶段工作项、任务包和真实结果，先识别运行中任务、已有完成证据及操作已完成但尚未登记的情况。运行中或结果未知时核对原任务身份，不因缺少摘要再次派发；已有完成证据须先复核新鲜度，再计算下一单元。外部动作缺可查询结果时报告缺口，不能重做副作用。
+
+上游变化按既有依赖关系使受影响资产过期，保留未受影响工作和历史记录；恢复、派发和交付边界仍执行适用 Context、决定/延续、门禁、仓库和允许写范围的校验。核验后输入变化即重验。有效授权不重复询问；未知或实质变化回交原责任方。历史实例缺 stage_tracking 时按已登记兼容和显式迁移入口处理，状态查询不自动补写。
+
 ## 执行成本
 
 执行策略以 `orchestration-contract.yaml.execution_efficiency` 为准，通过同一次 `query-lifecycle-context` 查询取得。Plan → Spec → Ticket 的耗时应分清脚本执行、Agent 读取与编排、人工等待；没有计时记录时不把总时长归因于摘要计算。
@@ -41,11 +49,11 @@ Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命
 
 所有命中项目必须达到 `existing-and-onboarded` 或 `initialized-and-verified`，未命中的交付面必须有带原因的 `not-applicable`。聚合结果、Manifest、验证和 onboarding 证据必须可读且当前；否则 `check.implementation-repositories-ready` 阻断 Ticket 正式化。旧实例恢复时保留已有 Ticket，但将相关 Ticket / Slice Contract 标为 `blocked` / `stale` 并返回本工作单元。
 
-`prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，在进入 DDD / MVC 分支设计前完成 `gate.backend-architecture-platform-approved`：Agent 按领域复杂度给出 `domain-driven` / `layered-mvc` 推荐和依据，并从 `docs/engineering/backend-platforms.json` 展示可选平台的精确 Spring Boot 补丁版本与 Java 版本；用户在同一次决定中确认架构与平台。本体选择作为子项目预填默认值，用户可批量确认全部项目或逐项覆盖。选择写入 `scaffold-architecture-decisions.yaml`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时必须阻断，不得默认 DDD、MVC 或 Spring Boot 版本，也不得在生成器内交互。既有工程使用当前 `existing-registration` 的架构及固定工程基线/POM 中的实际 Spring Boot 版本，核验摘要和支持状态后将该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。
+`prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，在进入 DDD / MVC 分支设计前完成 `gate.backend-architecture-platform-approved`：Agent 按领域复杂度给出 `domain-driven` / `layered-mvc` 推荐和依据，并从 `.template-spec/engineering/backend-platforms.json` 展示可选平台的精确 Spring Boot 补丁版本与 Java 版本；用户在同一次决定中确认架构与平台。本体选择作为子项目预填默认值，用户可批量确认全部项目或逐项覆盖。选择写入 `scaffold-architecture-decisions.yaml`；处于 `undecided`、`recommended`、`awaiting-user-decision` 或 `stale` 时必须阻断，不得默认 DDD、MVC 或 Spring Boot 版本，也不得在生成器内交互。既有工程使用当前 `existing-registration` 的架构及固定工程基线/POM 中的实际 Spring Boot 版本，核验摘要和支持状态后将该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。
 
-`gate.backend-architecture-platform-approved` 通过、选择达到 `lifecycle-approved` 且 digest 当前后，才可进入对应的 DDD 战术设计或 MVC 技术设计分支，再完成批准且当前的 Technical Design、Data Architecture Decision v1 和 API Contract Decision v1。数据与 API 均按影响强制：命中则绑定设计及评审闭包，未命中则绑定评估、明确原因和证据。再由 `yss-implementation-contract-compiler` 编译脚手架 schema v4 `controlled-generation` 工作单元合同。顺序为：工程基线与架构/平台推荐 → 用户确认与选择持久化 → DDD / MVC 分支设计 → 技术/数据/API 设计 → 工程合同原子批准 → 脚手架合同持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v4 校验 → 仓库准备 v2 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换或平台升级必须单独立项。schema v3 只允许历史 Manifest 的只读恢复审计，不得新生成。
+`gate.backend-architecture-platform-approved` 通过、选择达到 `lifecycle-approved` 且 digest 当前后，才可进入对应的 DDD 战术设计或 MVC 技术设计分支，再完成批准且当前的 Technical Design、Data Architecture Decision v1 和 API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`）。数据与 API 均按影响强制：命中则绑定设计及评审闭包，未命中则绑定评估、明确原因和证据。再由 `yss-implementation-contract-compiler` 编译脚手架 schema v4 `controlled-generation` 工作单元合同。顺序为：工程基线与架构/平台推荐 → 用户确认与选择持久化 → DDD / MVC 分支设计 → 技术/数据/API 设计 → 工程合同原子批准 → 脚手架合同持久化 → `domain-driven` 使用 `yss-ddd-scaffold-generator` 或 `layered-mvc` 使用 `yss-layered-mvc-scaffold-generator` → 对应基线/Manifest v4 校验 → 仓库准备 v2 → 实现合同编译器业务合同重编译。`existing` / `initialized` 不重复生成；架构转换或平台升级必须单独立项。schema v3 只允许历史 Manifest 的只读恢复审计，不得新生成。
 
-脚手架工作单元必须使用结构化 schema v4 合同 JSON，除工程身份、架构决定、Profile、模块闭包、允许路径和验证命令外，必须以原始字节 digest 绑定 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和 `gate.engineering-contract-approved` 的真实批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时不得携带空占位资产。生成器在创建输出目录前读取并校验所有引用、版本、主体、gate、批准范围、资产绑定与摘要；虚构 URI、字符串自证或仅有 `status: approved` 均无效。三条 Wrapper 命令必须由受控工作单元真实执行并留存证据。非空目标、`--force`、旧项目迁移和模板升级均阻断。脚手架不得生成 Controller、Repository 实现、SQL、领域行为、业务规则、状态机、权限、事务、复杂查询、错误映射、用户可见行为或示例业务 API；`empty-scaffold-verified` 仍不是 `ready-for-agent`。
+脚手架工作单元必须使用结构化 schema v4 合同 JSON，除工程身份、架构决定、Profile、模块闭包、允许路径和验证命令外，必须以原始字节 digest 绑定 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 和 `gate.engineering-contract-approved` 的真实批准记录。API `required` 时 Draft、Validation、独立 Review、Freeze 与工程批准必须绑定同一 OpenAPI YAML 字节；`not-applicable` 时不得携带空占位资产。生成器在创建输出目录前读取并校验所有引用、版本、主体、gate、批准范围、资产绑定与摘要；虚构 URI、字符串自证或仅有 `status: approved` 均无效。三条 Wrapper 命令必须由受控工作单元真实执行并留存证据。非空目标、`--force`、旧项目迁移和模板升级均阻断。脚手架不得生成 Controller、Repository 实现、SQL、领域行为、业务规则、状态机、权限、事务、复杂查询、错误映射、用户可见行为或示例业务 API；`empty-scaffold-verified` 仍不是 `ready-for-agent`。
 
 脚手架完成后，所有后续生成的后端代码仍必须重新消费当前版本的批准 Slice Implementation Contract、YSS skill 依赖闭包、允许写路径、预期证据和 Execution Result。业务行为使用 `behavior-tdd`；只有机械结构、样板、配置和冻结客户端使用 `controlled-generation`。缺少合同、skill、证据或实际验证时立即阻断；生成范围从机械内容变成业务行为时触发完整重路由。
 
@@ -61,9 +69,9 @@ Readiness 结果在同一任务内复用。只有 tracker、主远端、真实
 | `degraded` | 已选择的 GitHub/GitLab 不可用 | 建 `docs/.scratch/<feature>/` 待发布草案，不改投平台 |
 | `not-applicable` | `template-source` | 只验证模板契约 |
 
-远程 tracker 必须检查真实标签；Local Markdown 必须检查功能包目录和 Ticket 顶部的 `Status:`。仅有 `docs/agents/triage-labels.md` 不代表远程标签存在，也不能替代 Local 文件状态检查。
+远程 tracker 必须检查真实标签；Local Markdown 必须检查功能包目录和 Ticket 顶部的 `Status:`。仅有 `.template-spec/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:` 检查结果和草案位置。
+tracker 选择和冲突按 `.template-spec/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 进入条件
 
@@ -78,11 +86,11 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 ## 审查与验证
 
-- 调用 `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` 前先固定 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，所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`） 必须消费同一不可变快照。返回后或完成 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 分类；产品切片执行下述候选审查闭环，模板维护按 `docs/process/harness-process-tailoring.md` 的 L1 / L2 / L3 验证强度闭合，不自动冻结候选或全轴复审。`violation`、机器检查失败、适用行空白由实现者在原合同路径修复，再重新捕获候选并全轴复审。`drift`、`new_impacts`、`required_skills` 与真实影响不一致时合同 `stale`，回 实现合同编译器 或更早阶段，禁止在旧合同上继续编码。审查者不得写实现。`not-applicable` 仅当影响面未命中；命中后 mandatory 不得豁免，只允许修复或完整 `seam-deferred`。禁止为日常 Alibaba / YSS 新增生物人豁免门禁。
+- 产品切片与模板维护共用 finding 分类；产品切片执行下述候选审查闭环，模板维护按 `.template-spec/process/harness-process-tailoring.md` 的 L1 / L2 / L3 验证强度闭合，不自动冻结候选或全轴复审。`violation`、机器检查失败、适用行空白由实现者在原合同路径修复，再重新捕获候选并全轴复审。`drift`、`new_impacts`、`required_skills` 与真实影响不一致时合同 `stale`，回 实现合同编译器 或更早阶段，禁止在旧合同上继续编码。审查者不得写实现。`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。
 
@@ -98,7 +106,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 ## 必须暂停
 
-- 注册表中的聚合门禁等待会签裁决（数字人或生物人，以 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 为准）。暂停输出必须包含：门禁 ID、指定 `role_id`、`runtime_id`、会签文件路径。恢复前执行 `scripts/verify-approval-record --require-approved`；角色错误、起草者自签或生物人门禁被数字人关闭时返回 `blocked`，不得标 `approved`。
+- 注册表中的聚合门禁等待会签裁决（数字人或生物人，以 `.template-spec/agents/digital-human-roles.yaml` 的 `gate_policy` 为准）。暂停输出必须包含：门禁 ID、指定 `role_id`、`runtime_id`、会签文件路径。恢复前执行 `scripts/verify-approval-record --require-approved`；角色错误、起草者自签或生物人门禁被数字人关闭时返回 `blocked`，不得标 `approved`。
 - 需要目标仓库、外部凭据、发布窗口或其他新授权。
 - 状态与证据冲突且无法可靠重建。
 - 专项 skill 失败或返回不可验收结果。
@@ -129,7 +137,7 @@ Decision ticket 产生决策，不是实现切片，不得标记 `ready-for-agen
 
 Prototype 回流必须有可核验证据：来源 handoff、prototype 资产或运行记录、结论、被更新的 Spec/设计/ADR/Ticket 引用、剩余未决项和返回 handoff。仅在对话中声称“已验证”不算回流完成。
 
-Matt `prototype` 的回流还必须注明 `prototype_branch`，并保留单文件 HTML 主来源；该结果只能作为 YSS 原型输入，仍须完成阶段 4 的低保真评审、H1/H2 档位路由、schema v3 验证和用户确认，不得用 throwaway prototype 替代。
+Matt `prototype` 的回流还必须注明 `prototype_branch`，并保留单文件 HTML 主来源；该结果只能作为 YSS 原型输入，仍须完成阶段 4 的低保真评审、H1/H2 档位路由、schema v4 验证和用户确认，不得用 throwaway prototype 替代。
 
 `to-questionnaire` 未收到答案时使用 `external-input-required` 暂停，记录问卷、接收人、所需输出和恢复路由；收到答案后记录 response、重新分类影响面和更新后的权威资产，再回到 `grill-with-docs` 或 `to-spec`。
 
@@ -147,8 +155,8 @@ Checkpoint 中已批准门禁必须带 `basis: [{ref, digest}]` 和按 `evidence
 
 ## 专项合同加载索引
 
-专项加载提示：实现仓库与脚手架查询 `implementation_repository_preparation`、`backend_scaffold`；切片实现查询 `ticket_formalization`、`ready_for_agent`；UI 查询 `frontend_implementation_plan`、`frontend_implementation_verification`；审查查询 `review_input`；发布查询 `release_readiness`、`git_authorization`、`user_decision_evidence`；战略交接读取 `docs/process/strategic-handoff-package.md` 并按其中验证器执行。
+专项加载提示：实现仓库与脚手架查询 `implementation_repository_preparation`、`backend_scaffold`；切片实现查询 `ticket_formalization`、`ready_for_agent`；UI 查询 `frontend_implementation_plan`、`frontend_implementation_verification`；审查查询 `review_input`；发布查询 `release_readiness`、`git_authorization`、`user_decision_evidence`；战略交接读取 `.template-spec/process/strategic-handoff-package.md` 并按其中验证器执行。
 
 ## 后端脚手架平台
 
-在工程基线中合并展示、确认架构和 Boot 精确版本、Java、YSS 父 POM/BOM；缺少选择时询问，当前批准可复用。独立子项目可继承或覆盖，并可一次确认明确列出的多个项目。同一 Maven 工程统一平台。执行 `scripts/backend-platforms` 展示兼容状态；只允许已验证组合。决定、合同、Manifest 和下游身份绑定同一平台摘要；变更重新确认。合同见仓库 `docs/engineering/backend-platforms.md`。
+在工程基线中合并展示、确认架构和 Boot 精确版本、Java、YSS 父 POM/BOM；缺少选择时询问，当前批准可复用。独立子项目可继承或覆盖，并可一次确认明确列出的多个项目。同一 Maven 工程统一平台。执行 `scripts/backend-platforms` 展示兼容状态；只允许已验证组合。决定、合同、Manifest 和下游身份绑定同一平台摘要；变更重新确认。合同见仓库 `.template-spec/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-product-lifecycle/references/request-triage.md

@@ -14,6 +14,8 @@
 
 “帮我修复”“开始实施”等明确行动请求可选择有界执行；“只讨论”“不要改文件”限制当前范围。“继续”只恢复已明确且仍有效的动作，不扩展授权。仅“能否优化”可能是评估请求，应结合上下文判断；不得用关键词匹配替代理解。
 
+明确要求“查一下”“排查”时，即使首步仅为只读取证，也用 `orchestrate` 推进调查；`route` 留给咨询、澄清和明确只讨论的请求。取证不扩大成代码修改授权。
+
 模式选择不代替仓库身份、实现合同、用户决定或 Git/发布授权检查。排查授权不自动包含修改；实现缺少前置条件时说明具体阻塞并推进可独立开展的授权工作。用户请求简单咨询时直接回答，不创建流程产物。
 
 “排查慢接口，并评估是否重构”包含两个目标：先取得性能证据，再评估重构；不能把评估自动升级为重构实施。将每个目标的下一动作和依赖带入任务包，返回时逐项验收。复杂请求只需向用户简述理解和下一步，不强制每次确认复述。

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

@@ -12,7 +12,7 @@
 | `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` 指定的会签人（数字人或生物人），不是「必须是生物人」。但 `user_decision_policy` 命中的关键决定还必须有真实用户回复，数字人会签不能解除该等待。
+Matt 五态不得扩义。资产的 `ready-for-human` 与 Ticket label 必须带命名空间表达。`paused-human-gate` 表示等待 `.template-spec/agents/digital-human-roles.yaml` 指定的会签人（数字人或生物人），不是「必须是生物人」。但 `user_decision_policy` 命中的关键决定还必须有真实用户回复，数字人会签不能解除该等待。
 
 Slice v3 冻结需求文件的 status 是冻结时快照，不能用来推断当前执行状态。状态流转和验收结果写入已配置主 tracker / 任务包；需求改版后重新编译、审查与绑定批准，见 [Slice 冻结需求协议](../../yss-implementation-contract-compiler/references/slice-implementation-contract.md#第二轮增量规则)。
 
@@ -71,29 +71,29 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 ## 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` 并走既有重路由。该清单只作为审查证据。
+进入代码审查时保存 `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` 为唯一执行定义。所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`） 消费同一不可变快照；返回后或完成 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。只保存索引、状态、引用和因果关系：
+状态块位于主 tracker 的功能父 Ticket，并使用 `.template-spec/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
+  stage: stage.spec-architecture
+  status: needs-human
 workflow:
   matt_flow: main
-  active_skill: yss-openapi-draft-review
+  active_skill: yss-product-lifecycle
   status: paused
 artifacts:
-  spec: {status: approved, ref: docs/.scratch/example/spec.md}
+  spec: {status: ready-for-human, ref: docs/.scratch/example/spec.md}
   openapi: {status: stale, ref: docs/.scratch/example/api/example.yaml, stale_by: [spec]}
 gates:
-  openapi_freeze: {status: stale}
+  gate.spec-baseline-approved: {status: needs-human}
 tracker:
   kind: local-markdown
   root: docs/.scratch
@@ -101,10 +101,10 @@ tracker:
   role: ready-for-human
 pause:
   reason_code: human-gate
-  gate_ref: requirement-freeze
+  gate_ref: gate.spec-baseline-approved
   owner_or_authority: product-owner
-  resume_condition: requirement-freeze-approved
-  next_work_unit: api-impact-assessment
+  resume_condition: gate.spec-baseline-approved approved
+  next_work_unit: work-unit.technical-analysis
 ```
 
 ## Schema 兼容与迁移

package/template/.codex/skills/yss-product-lifecycle/references/user-decisions.md

@@ -1,6 +1,6 @@
 # 关键决策的真实用户回复协议
 
-适用门禁、工作单元和条件事项只由 `docs/agents/digital-human-roles.yaml.user_decision_policy` 定义。本协议解释执行和证据格式，不新增阶段、门禁或 Ticket 状态。专业审查记录与用户决定分别保存；关键决定缺少任一适用条件都不能放行。
+适用门禁、工作单元和条件事项只由 `.template-spec/agents/digital-human-roles.yaml.user_decision_policy` 定义。本协议解释执行和证据格式，不新增阶段、门禁或 Ticket 状态。专业审查记录与用户决定分别保存；关键决定缺少任一适用条件都不能放行。
 
 ## 六条执行规则
 
@@ -13,7 +13,7 @@
 
 ## 记录与来源
 
-使用 `docs/process/schemas/user-decision.schema.json` 和 `docs/process/templates/user-decision-template.yaml`。存于 `docs/.scratch/<feature>/decisions/<request-id>.yaml`；已展示的请求快照不改写，修改方案产生新请求并保留旧引用。请求中的 `subject` 指向可独立摘要的资产正文或冻结快照，批准记录另存，避免正文包含自己的批准摘要形成循环。`basis` 列出影响决定的额外冻结依据。
+使用 `.template-spec/process/schemas/user-decision.schema.json` 和 `.template-spec/process/templates/user-decision-template.yaml`。存于 `docs/.scratch/<feature>/decisions/<request-id>.yaml`；已展示的请求快照不改写，修改方案产生新请求并保留旧引用。请求中的 `subject` 指向可独立摘要的资产正文或冻结快照，批准记录另存，避免正文包含自己的批准摘要形成循环。`basis` 列出影响决定的额外冻结依据。
 
 原始消息可由运行时直接读取，或保存为原始会话导出 / 用户提供的确认文件。跨平台统一捕获封装如下；字段必须来自原始来源，保留原始引用和完整原文，不能把 Agent 编写的摘要包装成来源：
 

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

@@ -5,20 +5,20 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 # YSS Prototype Stage
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-起草或修订交互说明、状态说明和设计结论前，读取 `docs/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
+起草或修订交互说明、状态说明和设计结论前，读取 `.template-spec/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
 
 ## 进入条件与主入口
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
-- 先读取 Spec、产品总体设计、`CONTEXT.md`、`yss-design-system`，再按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序消费设计基线，形成交互说明、低保真页面/流程和状态矩阵。
+- 先读取 Spec、产品总体设计、`CONTEXT.md`、`yss-design-system`，再按 `DESIGN.md` → `.template-spec/design/design.md` → `.template-spec/design/tokens/*` 顺序消费设计基线，形成交互说明、低保真页面/流程和状态矩阵。
 - 用独立 `prototype-review` 评审低保真与状态；未通过不得选择档位或构建原型交付物。
 - 按 [原型档位路由](references/prototype-profile-routing.md) 选择 H1/H2 中满足当前决策风险的最低档位。没有充分证据时默认 H2。
 - 默认以 `DESIGN.md`、交互说明和状态矩阵进入 YSS HTML 适配器；有已选视觉稿时才条件调用 `product-design:index` 的还原 workflow。规范直出不调用要求先有图片的 `prototype/image-to-code/design-qa`；六轴 QA 仍由本阶段合同持有，所有 Agent 交付等价证据。
@@ -42,7 +42,7 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 ## 事实、QA 与确认
 
-优先级固定为：根 `DESIGN.md` 规范 Token / 组件变体 → `docs/design/design.md` 治理解释 → `docs/design/tokens/*` 派生快照。行为由 Spec、交互说明与状态矩阵定义。HTML 消费包内 Token CSS，保存根规范与 Token 摘要，不再调用组件 Provider 或采集新的 fact pack。标准格式与工具版本沿用项目锁定值，不跟随上游 main 自动升级。
+优先级固定为：根 `DESIGN.md` 规范 Token / 组件变体 → `.template-spec/design/design.md` 治理解释 → `.template-spec/design/tokens/*` 派生快照。行为由 Spec、交互说明与状态矩阵定义。HTML 消费包内 Token CSS，保存根规范与 Token 摘要，不再调用组件 Provider 或采集新的 fact pack。标准格式与工具版本沿用项目锁定值，不跟随上游 main 自动升级。
 
 Design QA 合并 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再建立第二份评审。所有档位至少证明 desktop/narrow 非空渲染、项目 Token、console 和基础键盘/焦点/对比度；H2 追加主流程、关键异常、200% zoom/reduced motion 与按风险视觉回归。规范直出使用 `design_qa.mode=design-contract`，对照规范和实际计算样式审查；已有视觉稿使用 `visual-comparison`，对照同视口同状态源图。首版截图在审查和用户确认后冻结，不能与自身对比来证明符合规范。图片是视觉基准而非唯一事实来源；模型必须从 `visual-baseline.yaml` 的 `case_id` 读取对应语义引用，禁止靠目录 glob 猜测页面含义。
 
@@ -53,15 +53,15 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 ## 按需读取
 
 - 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
-- 渲染适配、fact pack 与命令：[product-design-adapter.md](references/product-design-adapter.md)
-- 证据模板：`docs/design/templates/prototype-evidence-template.yaml`
-- Visual Baseline 模板与 schema：`docs/design/templates/visual-baseline-template.yaml`、`docs/design/schemas/visual-baseline.schema.json`
+- 离线渲染适配与命令：[product-design-adapter.md](references/product-design-adapter.md)
+- 证据模板：`.template-spec/design/templates/prototype-evidence-template.yaml`
+- Visual Baseline 模板与 schema：`.template-spec/design/templates/visual-baseline-template.yaml`、`.template-spec/design/schemas/visual-baseline.schema.json`
 
 ## 常见错误
 
 - 把 H1/H2 当作低/高保真；把离线 HTML 降为静态截图，或继续要求 Provider、Node starter、预先生成图片。
 - 低保真未评审就选择技术栈；用主观评分代替确定性触发规则。
-- 空填 lockfile/fact pack；把自身生成图当成独立来源，或宣称已验证生产真实组件。
+- 编造组件版本或构建来源；把自身生成图当成独立来源，或宣称已验证生产真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
 

package/template/.codex/skills/yss-prototype-stage/references/existing-ui-entry.md

@@ -1,6 +1,6 @@
 ## 既有 UI 的交接入口
 
-现有工程需要跨仓交接且确认 UI、交互、状态和权限体验均无改动时，先读取 `docs/process/existing-ui-baseline.md`，使用独立 `existing-ui-baseline` v1，不进入 H1/H2 原型构建。绑定固定源码、锁文件、实际构建、原始动作、PNG 截图和真实 API 交换证据；可离线审阅不等于可离线运行原型。
+现有工程需要跨仓交接且确认 UI、交互、状态和权限体验均无改动时，先读取 `.template-spec/process/existing-ui-baseline.md`，使用独立 `existing-ui-baseline` v1，不进入 H1/H2 原型构建。绑定固定源码、锁文件、实际构建、原始动作、PNG 截图和真实 API 交换证据；可离线审阅不等于可离线运行原型。
 
 通过 `gate.product-design-approved` 的现有用户决定协议确认当前基线 manifest 原字节，Handoff v5 明确声明 `ui_baseline_kind: existing-ui-baseline`。截图、代码可运行或旧原型批准都不能替代该确认；本技能只能准备审阅资产，不代答或批准。发现任何 UI 改动，包括后端行为导致的体验变化，回到上述原型流程；新设计继续保留现有原型与验证要求。
 

package/template/.codex/skills/yss-prototype-stage/scripts/build-antd-prototype.mjs

@@ -18,7 +18,7 @@ export async function buildAntdPrototype({projectRoot,root,feature,toolchain,rea
  }
  const lock=await readFile(new URL('pnpm-lock.yaml',assets));
  if(sha(await readFile(path.join(toolchain,'pnpm-lock.yaml')))!==sha(lock))throw new Error('作者工具 pnpm lock 与技能基线不匹配');
- const tokenCss=await readFile(path.join(projectRoot,'docs/design/tokens/variables.css'),'utf8');
+ const tokenCss=await readFile(path.join(projectRoot,'.template-spec/design/tokens/variables.css'),'utf8');
  // This adapter targets the default light :root baseline, never the later dark-theme overrides.
  const lightCss=tokenCss.match(/^:root\s*\{([^}]+)\}/m)?.[1];
  if(!lightCss)throw new Error('缺少明确的 :root light Token 基线');

package/template/.codex/skills/yss-prototype-stage/scripts/offline-html.mjs

@@ -78,7 +78,7 @@ async function inspect(root, profile, checkDigests) {
     for (const token of ["--brand-font-family", "--brand-color-text", "--brand-color-bg-layout", "--brand-color-bg-container", "--yss-color-primary-control", "--yss-control-height"]) if (!styles.includes(token)) errors.push(`styles.css 未消费项目 Token ${token}`);
   }
   if (manifest.design_source?.path !== "DESIGN.md" || !/^sha256:[a-f0-9]{64}$/.test(manifest.design_source?.digest ?? "")) errors.push("缺少根 DESIGN.md 来源摘要");
-  if (manifest.token_source?.path !== "docs/design/tokens/variables.css" || manifest.token_source?.digest !== files["tokens.css"]) errors.push("tokens.css 与登记的 Token 来源摘要不一致");
+  if (manifest.token_source?.path !== ".template-spec/design/tokens/variables.css" || manifest.token_source?.digest !== files["tokens.css"]) errors.push("tokens.css 与登记的 Token 来源摘要不一致");
   if (checkDigests && JSON.stringify(manifest.files) !== JSON.stringify(files)) errors.push("原型资源摘要或清单已变化，审查后重新 seal-project");
   return { errors, manifest, files };
 }
@@ -107,7 +107,7 @@ export async function prepareOfflineHtml({ projectRoot, root, feature, profile,
   // Refuse an occupied destination instead of replacing an existing or frozen prototype.
   if (existsSync(root) && ((await lstat(root)).isSymbolicLink() || (await readdir(root)).length)) throw new Error("原型目录已存在内容；请在保留旧版本后选择新 feature 工作目录，不覆盖已有原型");
   const design = await readFile(path.join(projectRoot, "DESIGN.md"));
-  const tokens = await readFile(path.join(projectRoot, "docs/design/tokens/variables.css"));
+  const tokens = await readFile(path.join(projectRoot, ".template-spec/design/tokens/variables.css"));
   await mkdir(root, { recursive: true });
   for (const file of ["index.html", "styles.css", "app.js", "scenarios.js"]) {
     const folder = pattern === "workbench" && file !== "scenarios.js" ? new URL("../assets/native-workbench/", import.meta.url) : assetRoot;
@@ -115,7 +115,7 @@ export async function prepareOfflineHtml({ projectRoot, root, feature, profile,
     await writeFile(path.join(root, file), source.replaceAll("__FEATURE__", feature).replaceAll("__PROFILE__", profile));
   }
   await writeFile(path.join(root, "tokens.css"), tokens);
-  const manifest = { schema_version: 4, feature, pattern, prototype_profile: profile, profile_kind: profile === "H1" ? "visual-review" : "flow-review", component_basis: "html-css-js", runtime_build_required: false, entry: "index.html", design_source: { path: "DESIGN.md", digest: sha(design) }, token_source: { path: "docs/design/tokens/variables.css", digest: sha(tokens) }, files: {} };
+  const manifest = { schema_version: 4, feature, pattern, prototype_profile: profile, profile_kind: profile === "H1" ? "visual-review" : "flow-review", component_basis: "html-css-js", runtime_build_required: false, entry: "index.html", design_source: { path: "DESIGN.md", digest: sha(design) }, token_source: { path: ".template-spec/design/tokens/variables.css", digest: sha(tokens) }, files: {} };
   await writeFile(path.join(root, manifestName), JSON.stringify(manifest));
   return sealOfflineHtml(root, profile);
 }

package/template/.codex/skills/yss-prototype-stage/tests/browser-smoke.mjs

@@ -9,9 +9,9 @@ import { prepareFlowPrototype, prepareStaticPrototype } from "../scripts/prototy
 const { chromium } = await import(process.env.YSS_PLAYWRIGHT_MODULE || "playwright");
 const temp = await mkdtemp(path.join(os.tmpdir(), "yss-offline-browser-"));
 const source = path.join(temp, "source");
-await mkdir(path.join(source, "docs/design/tokens"), { recursive: true });
+await mkdir(path.join(source, ".template-spec/design/tokens"), { recursive: true });
 await cp(new URL("../../../../DESIGN.md", import.meta.url), path.join(source, "DESIGN.md"));
-await cp(new URL("../../../../docs/design/tokens/variables.css", import.meta.url), path.join(source, "docs/design/tokens/variables.css"));
+await cp(new URL("../../../../.template-spec/design/tokens/variables.css", import.meta.url), path.join(source, ".template-spec/design/tokens/variables.css"));
 const root = path.join(source, "docs/.scratch/fixture/design/prototypes");
 await prepareFlowPrototype({ projectRoot: source, root, feature: "fixture" });
 const portable = path.join(temp, "portable");

package/template/.codex/skills/yss-prototype-stage/tests/run-scenarios.mjs

@@ -12,11 +12,11 @@ import { sealOfflineHtml } from "../scripts/offline-html.mjs";
 const tempRoot = await mkdtemp(path.join(os.tmpdir(), "yss-prototype-contract-"));
 const projectRoot = path.join(tempRoot, "project");
 const feature = "order-review";
-await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
+await mkdir(path.join(projectRoot, ".template-spec/design/tokens"), { recursive: true });
 await writeFile(path.join(projectRoot, "DESIGN.md"), "---\nversion: alpha\n---\n");
-await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
+await writeFile(path.join(projectRoot, ".template-spec/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
 
-await cp(new URL("../../../../docs/design/tokens/variables.css", import.meta.url), path.join(projectRoot, "docs/design/tokens/variables.css"));
+await cp(new URL("../../../../.template-spec/design/tokens/variables.css", import.meta.url), path.join(projectRoot, ".template-spec/design/tokens/variables.css"));
 
 const h1Root = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
 await prepareStaticPrototype({ projectRoot, root: h1Root, feature });
@@ -75,7 +75,7 @@ function common(profile, kind, block) {
     },
     upstream_refs: { spec_ref: "spec.md", interaction_spec_ref: "interaction.md", low_fidelity_ref: "low.md", state_matrix_ref: "states.md", prototype_review_ref: "review.md" },
     source_visual: { ideation_status: "not-applicable", selected_ref: "approved-pattern.md", reuse_reason: "复用已批准模式" },
-    design_baseline: { canonical_design_ref: "DESIGN.md", canonical_design_digest: "sha256:design", project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
+    design_baseline: { canonical_design_ref: "DESIGN.md", canonical_design_digest: "sha256:design", project_design_ref: ".template-spec/design/design.md", project_token_refs: [".template-spec/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
     visual_baseline: { manifest_ref: `docs/.scratch/${feature}/handoff/visual-baseline-v1/visual-baseline.yaml`, baseline_id: `visual-baseline.${feature}`, version: "v1", digest: `sha256:${"a".repeat(64)}`, status: "approved", case_ids: ["primary-desktop", "primary-narrow"] },
     browser_delivery: {
       delivery_kind: "static-directory", entry_ref: `docs/.scratch/${feature}/design/prototypes/index.html`, rendered_nonblank: true, prototype_digest: "sha256:prototype",

package/template/.codex/skills/yss-prototype-stage/tests/workbench-smoke.mjs

@@ -8,7 +8,7 @@ import {prepareFlowPrototype,validatePrototypeProject} from '../scripts/prototyp
 import {buildAntdPrototype} from '../scripts/build-antd-prototype.mjs';
 const {chromium}=await import(process.env.YSS_PLAYWRIGHT_MODULE||'playwright');
 const temp=await mkdtemp(path.join(os.tmpdir(),'yss-workbench-browser-'));const source=path.join(temp,'source');
-await mkdir(path.join(source,'docs/design/tokens'),{recursive:true});for(const ref of ['DESIGN.md','docs/design/tokens/variables.css'])await cp(new URL(`../../../../${ref}`,import.meta.url),path.join(source,ref));
+await mkdir(path.join(source,'.template-spec/design/tokens'),{recursive:true});for(const ref of ['DESIGN.md','.template-spec/design/tokens/variables.css'])await cp(new URL(`../../../../${ref}`,import.meta.url),path.join(source,ref));
 const results=[];const browser=await chromium.launch(process.env.YSS_BROWSER_CHANNEL?{channel:process.env.YSS_BROWSER_CHANNEL}:{});
 try{
  for(const kind of ['native','antd']){

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

@@ -10,7 +10,7 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 ## 架构分流
 
 1. 读取当前 Slice Implementation Contract 的 `architecture_identity`、`persistence_profile`、实现仓登记、数据合同、`allowed_write_paths` 和预期证据。
-2. 将架构身份与当前工程基线、既有工程观测（生成 Manifest 只证明历史来源）和 `docs/agents/yss-skill-registry.yaml` 核对；成熟度以注册表为准，不能把 `draft` 称为已支持。
+2. 将架构身份与当前工程基线、既有工程观测（生成 Manifest 只证明历史来源）和 `.template-spec/agents/yss-skill-registry.yaml` 核对；成熟度以注册表为准，不能把 `draft` 称为已支持。
 3. 根据 `architecture_profile` **且只**加载一个文件：
    - [target-domain-model](references/profiles/target-domain-model.md)
    - [layered-mvc-service](references/profiles/layered-mvc-service.md)
@@ -29,6 +29,7 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 <a id="repository.mapping"></a>
 <!-- yss-rule {"id":"repository.mapping","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 数据合同必须显式覆盖主键、逻辑删除、审计字段、空值、枚举/值对象映射和敏感字段；动态排序、分组与过滤必须使用批准白名单和参数绑定。
+- 数据合同选择 YSS 分布式主键时，记录已选 `component.distributed-id` 绑定、Segment/Snowflake 策略、实体主键类型与批量插入路径，并消费 `yss-distributed-id` 的当前平台证据；不由 Repository 自行切换算法或创建发号合同。
 <a id="repository.transaction"></a>
 <!-- yss-rule {"id":"repository.transaction","when":"persistence","level":"mandatory","evidence":"code-and-verification"} -->
 - 事务归所选 Profile 的用例边界。Repository/Gateway Adapter 不临时新增业务事务，也不把数据库异常原文或凭据暴露给上层。
@@ -55,6 +56,6 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 
 ## 新脚手架平台约束
 
-消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。命中 MyBatis 时，`framework.mybatis` 必须从该配置指向的 compatibility 条目解析出对当前架构有效的 `component_binding`；构件、摘要、源码 tree、证据或绑定状态不一致时回合同编译器阻断。Validation namespace、Jackson、starter 和处理器版本只消费解析后的精确平台事实，不在本 Skill 中按 Boot 大版本推导。不得在业务实现中升级、降级或替换 YSS 组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。命中 MyBatis 时，`framework.mybatis` 必须从该配置指向的 compatibility 条目解析出对当前架构有效的 `component_binding`；构件、摘要、源码 tree、证据或绑定状态不一致时回合同编译器阻断。Validation namespace、Jackson、starter 和处理器版本只消费解析后的精确平台事实，不在本 Skill 中按 Boot 大版本推导。不得在业务实现中升级、降级或替换 YSS 组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 只读审计可先盘点、记录缺失合同；不得用实施前置要求阻止发现既有违规。整改仍需批准合同，不因缺少生成 Manifest 阻断已有效登记的既有工程。

package/template/.codex/skills/yss-repository/references/profiles/layered-mvc-service.md

@@ -1,6 +1,6 @@
 # layered-mvc-service
 
-仅适用于注册表中 `architecture_family=layered-mvc`、用例层为 `service` 的当前合同。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+仅适用于注册表中 `architecture_family=layered-mvc`、用例层为 `service` 的当前合同。先读仓库 `.template-spec/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
 
 ## 前置与所有权
 

package/template/.codex/skills/yss-repository/references/profiles/mvc-data-analysis-v1.md

@@ -1,6 +1,6 @@
 # mvc-data-analysis-v1
 
-仅适用于注册表中的数据分析 MVC Profile。先读仓库 `docs/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
+仅适用于注册表中的数据分析 MVC Profile。先读仓库 `.template-spec/agents/backend-architecture-profiles.md`；Profile 的成熟度沿用注册表。
 
 ## 前置与所有权
 

package/template/.codex/skills/yss-repository/tests/profile-routing.test.mjs

@@ -16,7 +16,7 @@ async function text(target) {
 test("repository router exposes exactly the registered profile entry points", async () => {
   const profilesRoot = path.join(repositorySkillRoot, "references/profiles");
   const profiles = (await readdir(profilesRoot)).filter((name) => name.endsWith(".md")).sort();
-  const registry = parseDocument(await text(path.join(projectRoot, "docs/agents/yss-skill-registry.yaml"))).toJS();
+  const registry = parseDocument(await text(path.join(projectRoot, ".template-spec/agents/yss-skill-registry.yaml"))).toJS();
   assert.deepEqual(profiles, [...Object.keys(registry.architecture_profiles), ...Object.keys(registry.existing_project_profiles)].map(id => `${id}.md`).sort());
 
   const skill = await text(path.join(repositorySkillRoot, "SKILL.md"));
@@ -47,7 +47,7 @@ test("normative persistence skills do not contain business-specific templates or
 
 test("code review wires Repository and MyBatis with registered backend scope", async () => {
   const standards = await text(path.join(skillsRoot, "code-review/references/yss-review-standards.md"));
-  const report = await text(path.join(projectRoot, "docs/templates/review-report-template.md"));
+  const report = await text(path.join(projectRoot, ".template-spec/templates/review-report-template.md"));
   const lifecycle = await text(path.join(skillsRoot, "yss-product-lifecycle/references/orchestration-contract.yaml"));
 
   for (const source of [standards, report, lifecycle]) {

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

@@ -9,11 +9,11 @@ Investigate facts that a YSS decision depends on. Produce evidence and bounded c
 
 `research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-撰写研究简报或结论前，读取 `docs/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
+撰写研究简报或结论前，读取 `.template-spec/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
 
 ## Profiles
 

package/template/.codex/skills/yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md

@@ -24,4 +24,4 @@
 - BOM 版本不等于每个组件 artifact 的实际版本。比较依赖树中的精确 GAV；索引输出的本地 POM lineage 是定位证据，不代替 effective POM 和运行验证。
 - `javax.sql`、`javax.crypto` 等 Java SE 包不是 Jakarta 迁移目标，不能用简单字符串替换处理。
 
-共享平台事实源为 `docs/engineering/backend-platforms.json` 和 `docs/engineering/backend-platforms.md`。
+共享平台事实源为 `.template-spec/engineering/backend-platforms.json` 和 `.template-spec/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-stage-decision/SKILL.md

@@ -5,15 +5,15 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 # YSS Stage Decision
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-撰写方案决策包和业务边界说明前，读取 `docs/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
+撰写方案决策包和业务边界说明前，读取 `.template-spec/process/document-writing.md` 的共用写法及 Plan 指引；原业务规则、决定依据和未决项完整保留。
 
 ## 适用边界
 
@@ -24,7 +24,7 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 ## 执行顺序
 
-Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有；从 `docs/plan/templates/plan-template.md` 汇总输入。旧资产按 `docs/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
+Plan 的目标与退出条件由 `.template-spec/process/lifecycle-registry.yaml` 持有；从 `.template-spec/plan/templates/plan-template.md` 汇总输入。旧资产按 `.template-spec/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
 
 1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和当前 profile 的主索引/checkpoint；按 `yss-product-lifecycle` 的 `request-triage` 区分事实确认、产品决定、门禁确认和普通澄清。
 2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
@@ -36,7 +36,7 @@ Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有
 
 ## 控制面引用
 
-- 用户决定遵循 `docs/process/lifecycle/references/user-decisions.md`：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。
+- 用户决定遵循 [用户决定协议](../yss-product-lifecycle/references/user-decisions.md)：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。
 - checkpoint 是唯一机器状态源，业务 Ticket 只保存追踪引用，不复制阶段状态。
 - 每次批准、重发和消费者流转前执行 `context_reconciliation`，核验 `CONTEXT.md` 的全文与引用术语双摘要。
 - 技术事实与第三方行为走 `yss-research` 的 `technical-evidence`；产品策略依据走 `strategy-evidence`；市场与竞品判断走 `competitive-intelligence`。

package/template/.codex/skills/yss-stage-decision/references/domain-strategy-contract.md

@@ -32,4 +32,4 @@
 
 ## 便携交付的逐条追溯
 
-正式导出要求场景 `rule_refs / critical / success_results / evidence_refs` 和不变量 `rule_ref / evidence_refs`。`downstream_mapping` 必须使用稳定 `mapping_id`、来源 ID、消费者能力、影响项、传播规则和证据。已有 v2 文档继续只读兼容；修改或重发须显式迁移为 v3 `draft` 并重新批准。具体合同见 `docs/process/strategic-handoff-package.md`，不得由导出器发明业务身份。
+正式导出要求场景 `rule_refs / critical / success_results / evidence_refs` 和不变量 `rule_ref / evidence_refs`。`downstream_mapping` 必须使用稳定 `mapping_id`、来源 ID、消费者能力、影响项、传播规则和证据。已有 v2 文档继续只读兼容；修改或重发须显式迁移为 v3 `draft` 并重新批准。具体合同见 `.template-spec/process/strategic-handoff-package.md`，不得由导出器发明业务身份。

package/template/.codex/skills/yss-stage-decision/references/strategic-handoff-routing.md

@@ -1,3 +1,3 @@
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `.template-spec/process/strategic-handoff-package.md`。

package/template/.codex/skills/yss-tactical-design/SKILL.md

@@ -5,7 +5,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 # yss-tactical-design
 
-已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `.template-spec/process/contract-reading.md`。
 
 本 skill 负责 DDD 战术设计，不新增生命周期主阶段，也不替代 `yss-stage-decision` 或 `yss-domain`。
 
@@ -42,4 +42,4 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 ## 后端脚手架平台承接
 
-消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。

package/template/.codex/skills/yss-tactical-design/references/strategic-handoff-routing.md

@@ -1,5 +1,5 @@
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `.template-spec/process/strategic-handoff-package.md`。
 
 战术合同必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。

package/template/.codex/skills/yss-tactical-design/references/tactical-design-contract.md

@@ -42,4 +42,4 @@ evidence_refs: []
 6. 复杂跨聚合一致性、并发、幂等、事件补偿或持久化错位必须写明策略，必要时升级独立文档。
 7. 实现发现新影响时必须阻断并回到生命周期重新路由。
 
-跨仓快照消费在 v2 共同头（旧独立 v1 则为根对象）绑定 `strategic_handoff`；字段与实际命令以 `docs/process/strategic-handoff-package.md` 为准。
+跨仓快照消费在 v2 共同头（旧独立 v1 则为根对象）绑定 `strategic_handoff`；字段与实际命令以 `.template-spec/process/strategic-handoff-package.md` 为准。