create-yss-spec 3.5.0 → 3.5.3

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -5,24 +5,24 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 # YSS 技术设计
 
-已有生命周期资产优先用 `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-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
-文档输出时按 `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` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+起草或修订技术设计解释正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
 
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。
 
-按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `docs/agents/backend-architecture-profiles.md`。
+按项目绑定架构选择的来源及摘要。新工程必须先通过 `gate.backend-architecture-platform-approved`：Agent 展示 DDD / MVC 推荐依据及平台清单中的精确 Spring Boot、Java 版本，用户在同一次决定中确认两项内容；决定持久化到 `scaffold-architecture-decisions.yaml`，再进入对应分支，后续脚手架消费同一决定。既有工程核验并沿用当前登记架构及固定工程基线/POM 中的实际 Spring Boot 版本，该门禁记录为 `not-applicable`，不重复询问；架构转换或平台升级另行立项。只有 `domain-driven` 和 `layered-mvc` 两种架构族，不能从目录推断或默认 DDD、MVC 或 Spring Boot 版本。具体 Profile 及模块边界消费技能注册表与 `.template-spec/agents/backend-architecture-profiles.md`。
 
 - `domain-driven`：调用 `yss-tactical-design`，补齐适用的战略领域输入。
-- `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `docs/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
+- `layered-mvc`：由本 skill 直接设计模块职责与依赖方向、用例流程、业务规则、状态转换、事务与回滚、幂等与并发、持久化映射、外部集成和公开测试 seam；不要求战略 DDD、聚合、值对象、Domain Event 或 DDD Gateway。分层边界消费 `.template-spec/agents/backend-architecture-profiles.md`，不得为 MVC 加载 `yss-domain` 或生成 DDD Gateway。
 
 已有 Strategic Design Handoff 时，两种分支都必须先完成导入和目标词汇对账，再逐条承接规则与关键场景。没有战略交接包的项目直接消费批准需求，不能为 MVC 补造战略 DDD。
 
@@ -44,4 +44,4 @@ schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，
 
 ## 后端脚手架平台承接
 
-消费生命周期已确认的架构与 `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/.pi/skills/yss-technical-design/references/technical-design-contract.md

@@ -9,7 +9,7 @@
 - `inputs`：每行 `{kind, ref, version, digest}`，kind 为 context/spec/rules/scenarios/api/adr/engineering/strategic；至少包含根 CONTEXT.md 与 Spec。适用的工程/API 约束同样绑定。无 API 影响理由记录在需求或工程输入中。DDD 另须 strategic 输入，MVC 不要求。
 - `source_items`：无战略包时从批准需求提取稳定规则和场景 `{source_id, kind: rule | scenario, critical, source_ref}`。source_ref 必须对应 inputs，不复制源正文成为第二事实源。
 - `traceability`：逐项对应 source_items。沿用 `tactical_refs` 字段名以兼容承接协议，其值在新合同中可指向 MVC 用例、规则或 DDD 对象；其他字段与战略承接 rows 相同。implemented 仅表示设计承接已落实，不表示代码已实现。
-- 有战略包时追加 `strategic_handoff`，按 `docs/process/strategic-handoff-package.md` 绑定导入收据、摘要、正式对账及 rows；本地补充规则仍可写 source_items / traceability，但不能重复维护包内来源。
+- 有战略包时追加 `strategic_handoff`，按 `.template-spec/process/strategic-handoff-package.md` 绑定导入收据、摘要、正式对账及 rows；本地补充规则仍可写 source_items / traceability，但不能重复维护包内来源。
 - `evidence_refs`：现有审查证据的可读取路径。approved 状态必须有评审证据，真正批准仍由生命周期核验适用批准记录；本校验器不产生批准。
 - `digest`：删除根 digest 后按键排序、数组保持顺序的 canonical JSON SHA-256，前缀 `sha256:`。来源文件的 digest 使用原始字节 SHA-256；这两种摘要不可混用。
 

package/template/.pi/skills/yss-ui/SKILL.md

@@ -22,7 +22,7 @@ description: "选择和核验 YSS Vue 生产页面组件及 Ant Design Vue 兼
 
 ## 2. 执行前版本预检
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `docs/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 进入实现前从前端工程根目录执行：
 

package/template/.pi/skills/yss-up-springboot3/SKILL.md

@@ -7,7 +7,7 @@ description: "审查或迁移 YSS Spring Boot 2 到 3 的依赖、Jakarta 与 Sp
 
 Use this skill for catalog-driven YSS backend upgrade analysis and approved migrations from an exact Spring Boot 2 platform to an exact Spring Boot 3 platform.
 
-中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `docs/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
+中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `.template-spec/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
 
 ## When To Use
 

package/template/.pi/skills/yss-web-controller/SKILL.md

@@ -101,4 +101,4 @@ node scripts/generate_controller.mjs \
 
 ## 新脚手架平台约束
 
-消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。DTO、Validation、Exception 或其他 YSS 组件命中时，逐项消费合同中的 `component_bindings`；缺少 verified 架构证据、构件摘要或绑定发生漂移时回合同编译器阻断。Validation namespace、Jackson wire 行为、Web starter 和自动配置机制只来自解析后的精确平台事实；命令参数必须使用该解析值，不在本 Skill 中按 Boot 大版本硬编码。不得在业务实现中升级、降级或替换组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `docs/engineering/backend-platforms.md`。
+消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。DTO、Validation、Exception 或其他 YSS 组件命中时，逐项消费合同中的 `component_bindings`；缺少 verified 架构证据、构件摘要或绑定发生漂移时回合同编译器阻断。Validation namespace、Jackson wire 行为、Web starter 和自动配置机制只来自解析后的精确平台事实；命令参数必须使用该解析值，不在本 Skill 中按 Boot 大版本硬编码。不得在业务实现中升级、降级或替换组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `.template-spec/engineering/backend-platforms.md`。

package/template/.pi/skills/yss-web-controller/references/profiles/layered-mvc-service.md

@@ -1,3 +1,3 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md`。server 的 Controller 只调用 service；私有 DTO 在 server，已批准 published-client 的公开 DTO 在 client。server 持有 MapStruct WebConvertor、HTTP 校验与错误脱敏。不得从表结构反推 OpenAPI，不得直连 Repository。执行脚本前确认其接受当前 Profile；不接受时返回 blocked，禁止伪造 DDD Manifest 绕过。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md`。server 的 Controller 只调用 service；私有 DTO 在 server，已批准 published-client 的公开 DTO 在 client。server 持有 MapStruct WebConvertor、HTTP 校验与错误脱敏。不得从表结构反推 OpenAPI，不得直连 Repository。执行脚本前确认其接受当前 Profile；不接受时返回 blocked，禁止伪造 DDD Manifest 绕过。

package/template/{docs → .template-spec}/adr/README.md

@@ -2,6 +2,6 @@
 
 本目录只记录当前项目自身的架构决策，不承载 `yss-spec-project-template` 模板源仓库的治理决策。
 
-创建 ADR 时使用 [`docs/templates/adr-template.md`](../templates/adr-template.md)，并为每条决策补充状态、背景、取舍、后果和相关资产。
+创建 ADR 时使用 [`.template-spec/templates/adr-template.md`](../templates/adr-template.md)，并为每条决策补充状态、背景、取舍、后果和相关资产。
 
 该目录仅供 `project-instance` 记录产品自身的架构决策。`template-source` 不维护实时治理 ADR；模板规则直接写入对应单一事实来源，历史决策通过 Git 历史和维护 evidence 审计。

package/template/{docs → .template-spec}/agents/README.md

@@ -9,7 +9,7 @@
 | `.agents/` | 共享技能的权威内容 |
 | `.cursor/skills/` | Cursor 的契约运行时投影 |
 | `.codex/skills/` | Codex 投影与平台专属 skills |
-| `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范和技能路由注册表 |
+| `.template-spec/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范和技能路由注册表 |
 
 ## 当前文档
 
@@ -18,7 +18,7 @@
 | `issue-tracker.md` | Ticket / Spec / triage 在 Local Markdown、GitLab Issues 与 GitHub Issues 间路由的操作约定 |
 | `triage-labels.md` | 标准五态 triage 标签与含义 |
 | `domain.md` | 领域文档读取和维护规则 |
-| `skills-maintenance.md` | Engineering Skills 的安装、升级和验证说明 |
+| `.template-source/agents/skills-maintenance.md`（仅模板源） | 模板源的技能安装、升级和验证说明；项目实例无需此维护文档 |
 | `yss-skill-registry.yaml` | 技能分层、别名与运行时入口（active；不替代锁文件） |
 | `gitlab-workflow-skills.md` | GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则 |
 

package/template/{docs → .template-spec}/agents/backend-architecture-profiles.md

@@ -6,7 +6,7 @@ Profile、模块闭包、生成器、成熟度和 Recipe 的权威映射见 `yss
 
 ## 既有工程适配
 
-`existing_project_profiles` 与下述生成器 Profile 独立维护。首版两个 Maven 适配器通过真实 Git/POM 三方核验、对应架构的成功/失败行为测试与 Maven test/package 后标记 supported；依据见 `.template-source/evidence/maintenance/2026-09-12-existing-project-delivery/maven-adapters-04.json`。这是适配协议支持证据，不是实际产品批准、数据库兼容或真实跨仓 S0 结论。每个工程仍须自己的固定来源、架构边界审查和执行证据，详见 `docs/process/existing-backend-architecture.md`。生成器原有 draft 和首切片要求保持。
+`existing_project_profiles` 与下述生成器 Profile 独立维护。首版两个 Maven 适配器通过真实 Git/POM 三方核验、对应架构的成功/失败行为测试与 Maven test/package 后标记 supported；依据见 `.template-source/evidence/maintenance/2026-09-12-existing-project-delivery/maven-adapters-04.json`。这是适配协议支持证据，不是实际产品批准、数据库兼容或真实跨仓 S0 结论。每个工程仍须自己的固定来源、架构边界审查和执行证据，详见 `.template-spec/process/existing-backend-architecture.md`。生成器原有 draft 和首切片要求保持。
 
 ## MVC 分层
 
@@ -21,7 +21,7 @@ Profile、模块闭包、生成器、成熟度和 Recipe 的权威映射见 `yss
 
 - 新脚手架统一 `verification_database=h2`、`production_database=not-bound`。仅测试和显式 `scaffold-local` 使用 H2；普通配置不设置数据库或默认激活 Profile。不另加生产驱动、第三方数据源或 Mock 服务。
 - 生产数据库、DDL、索引和方言在后续批准的存储工作单元接入；H2 测试不能证明生产方言兼容。脚手架不包含业务 SQL、schema/data 占位或业务 API。
-- DDD / 通用 MVC 消费批准的 `platform_configuration` v2，平台清单与证据规则见 `docs/engineering/backend-platforms.md`。凡注册表标记 `component_binding: required` 的能力，编译器必须从该配置指向的同一 compatibility 条目解析 `component_capabilities`；未登记、非 `verified`、架构证据缺失或构件摘要漂移均阻断。数据分析初始化器保留 `spring-boot-2.7-jdk8` / `javax`，不自动开放新平台。组件 Skill 不擅自升级 Java、Boot、处理器或替换 YSS 依赖。MapStruct + Lombok 必须验证 binding 与生成代码编译。
+- DDD / 通用 MVC 消费批准的 `platform_configuration` v2，平台清单与证据规则见 `.template-spec/engineering/backend-platforms.md`。凡注册表标记 `component_binding: required` 的能力，编译器必须从该配置指向的同一 compatibility 条目解析 `component_capabilities`；未登记、非 `verified`、架构证据缺失或构件摘要漂移均阻断。数据分析初始化器保留 `spring-boot-2.7-jdk8` / `javax`，不自动开放新平台。组件 Skill 不擅自升级 Java、Boot、处理器或替换 YSS 依赖。MapStruct + Lombok 必须验证 binding 与生成代码编译。
 - 对 SQL 注入、敏感信息、权限和事务的规则不因 H2 或模板而豁免。MySQL 专属语法规则仅适用于批准的 MySQL 存储工作单元；框架命名/返回包装等差异须记录明确的 YSS 基线例外。
 
 ## 验证含义

package/template/{docs → .template-spec}/agents/digital-human-roles.md

@@ -1,6 +1,6 @@
 # 数字人角色
 
-结构化事实源是 `docs/agents/digital-human-roles.yaml`。角色、技能、协作组和会签级别与运行时无关。Cursor、Codex、Grok Bot 等只通过 YAML `runtimes` 绑定。冲突时以 YAML 为准。
+结构化事实源是 `.template-spec/agents/digital-human-roles.yaml`。角色、技能、协作组和会签级别与运行时无关。Cursor、Codex、Grok Bot 等只通过 YAML `runtimes` 绑定。冲突时以 YAML 为准。
 
 ## 何时读本文
 
@@ -16,7 +16,7 @@
 | 执行态 | Explorer / Drafter / Worker / Reviewer / Verifier | 数字人角色 |
 | 运行时绑定 | 如何在 Cursor / Codex / Grok 等落地 | 角色职责本身 |
 
-一次数字人任务包同时写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色、执行态、当前 `runtime_id`，以及从角色表复制的 `core_skills` / `forbidden_skills`。可用 `taskPackageDefaults(roleId)`（`scripts/lib/digital-human-roles.mjs`）读取，禁止手写第二套技能包。`role.test-engineer` 的 core_skills 含 YSS / Alibaba 专项 skill，仅作为 `code-review` Standards 只读输入，不得写实现；finding 交实现者修复或回 实现合同编译器，审查者不得当场改代码。任务包 canonical Schema 为 `docs/process/schemas/digital-human-task-package.schema.json`，按 `contract.kind` 选择生命周期、切片实现或模板维护合同。
+一次数字人任务包同时写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色、执行态、当前 `runtime_id`，以及从角色表复制的 `core_skills` / `forbidden_skills`。可用 `taskPackageDefaults(roleId)`（`scripts/lib/digital-human-roles.mjs`）读取，禁止手写第二套技能包。`role.test-engineer` 的 core_skills 含 YSS / Alibaba 专项 skill，仅作为 `code-review` Standards 只读输入，不得写实现；finding 交实现者修复或回 实现合同编译器，审查者不得当场改代码。任务包 canonical Schema 为 `.template-spec/process/schemas/digital-human-task-package.schema.json`，按 `contract.kind` 选择生命周期、切片实现或模板维护合同。
 
 ## 会签人
 
@@ -24,7 +24,7 @@
 
 Plan、产品设计、工程契约统一呈现适用检查后批准。`gate.delivery-accepted` 由测试角色进行交付验收，实际合并或发布仍须另有生物人授权。内部检查不独立请求用户决定；检查失败仍阻断聚合门禁。专业审查可在同一工作单元完成多个检查项，但必须保留逐项结论、资产摘要与独立执行者身份。
 
-会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，形状见 `docs/templates/approval-record-template.yaml`。恢复前运行 `scripts/verify-approval-record --require-approved`。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。
+会签写入 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`，形状见 `.template-spec/templates/approval-record-template.yaml`。恢复前运行 `scripts/verify-approval-record --require-approved`。错误会签只能得到 `blocked`，不能把门禁标成 `approved`。Checkpoint 里会签桶门禁为 `approved` 时必须有可读 `approval_ref`。
 
 `paused-human-gate` 表示等待指定会签人；`user_decision_policy` 命中的关键决定同时强制真实用户回复，数字人审查不能代答。请求展示、原始回复证据、复用和恢复规则见 [用户决定协议](../../.agents/skills/yss-product-lifecycle/references/user-decisions.md)。
 
@@ -50,7 +50,7 @@ Plan、产品设计、工程契约统一呈现适用检查后批准。`gate.deli
 
 新增平台：先加 `runtimes` 条目，再写适配说明。不要把平台限制写进 `roles`。
 
-Grok 专用操作见 `docs/templates/grok-bot-profile-template.md`。通用实例化见 `docs/templates/digital-human-runtime-profile-template.md`。
+Grok 专用操作见 `.template-spec/templates/grok-bot-profile-template.md`。通用实例化见 `.template-spec/templates/digital-human-runtime-profile-template.md`。
 
 ## 两套批准
 
@@ -59,12 +59,12 @@ Grok 专用操作见 `docs/templates/grok-bot-profile-template.md`。通用实
 | 运行时副作用审批 | 发消息、改生产、付款、删数据等工具动作 | 生物人（各平台自己的 Allow / 确认框） |
 | 生命周期会签 | `gate.*` 与独立 code review | 见 YAML `gate_policy` |
 
-会签写入 `docs/templates/approval-record-template.yaml`，带 `runtime_id`、`principal_ref` 与实例引用。起草者不得出现在会签人里。对外商务合同和运行时外部副作用仍须生物人；交付验收不授予这些权限。
+会签写入 `.template-spec/templates/approval-record-template.yaml`，带 `runtime_id`、`principal_ref` 与实例引用。起草者不得出现在会签人里。对外商务合同和运行时外部副作用仍须生物人；交付验收不授予这些权限。
 
 ## 实例化
 
 - 模板仓：`publish-singleton-profiles`。账户级只发布一套职称 profile，不按功能再拆。
-- `project-instance`：`duplicate-and-bind-repo-path`。复制 YAML 的 `title` / `description` / `core_skills`，写入本仓库路径，选择 `runtime_id`。步骤见 `docs/templates/digital-human-runtime-profile-template.md`。外部 `create-yss-spec` 尚未接管此步骤。
+- `project-instance`：`duplicate-and-bind-repo-path`。复制 YAML 的 `title` / `description` / `core_skills`，写入本仓库路径，选择 `runtime_id`。步骤见 `.template-spec/templates/digital-human-runtime-profile-template.md`。外部 `create-yss-spec` 尚未接管此步骤。
 
 ## 任务包最低字段
 

package/template/{docs → .template-spec}/agents/digital-human-roles.yaml

@@ -3,7 +3,7 @@ registry_id: yss.digital-human-roles
 status: active
 description: >-
   数字人角色、主控、阶段协作组、技能启用/禁止与生命周期会签的单一事实源。 角色配置与运行时无关；Cursor / Codex / Grok 等只通过 runtimes 绑定。 Ticket 五态不是数字人角色。
-canonical_path: docs/agents/digital-human-roles.yaml
+canonical_path: .template-spec/agents/digital-human-roles.yaml
 runtime_policy:
   overlay_on_lifecycle: true
   consumed_by_lifecycle: true
@@ -41,7 +41,7 @@ runtimes:
     shared_workspace_is_not_security_boundary: false
     side_effect_approval: biological-human
     notes: >-
-      覆盖 docs/agents/yss-skill-registry.yaml 的 agent_runtime_roots （codex / cursor / pi）。 技能仍从 .agents/skills 投影，不按职称再维护一份。
+      覆盖 .template-spec/agents/yss-skill-registry.yaml 的 agent_runtime_roots （codex / cursor / pi）。 技能仍从 .agents/skills 投影，不按职称再维护一份。
   - id: runtime.grok
     kind: grok-bot
     instance_kind: durable-bot
@@ -76,7 +76,7 @@ roles:
     title: YSS 需求经理
     stages: [ stage.plan, stage.spec-architecture ]
     draft_artifact_ids: [ artifact.plan-record, artifact.spec ]
-    core_skills: [ grilling, domain-modeling, yss-research, competitive-intelligence, grill-with-docs ]
+    core_skills: [ grilling, domain-modeling, yss-research, competitive-intelligence ]
     forbidden_skills: [ yss-ui, yss-domain, yss-web-controller, yss-repository, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator, implement, tdd ]
     description: >-
       Own Plan language, users, MVP, non-goals, success criteria, test seams, and Spec prose. Propose CONTEXT.md glossary entries. Do not freeze visual prototypes, OpenAPI, or code. Do not guess unconfirmed business rules. Hand off to the orchestrator when the frontier is empty.
@@ -87,7 +87,7 @@ roles:
     contract_version: 1
     title: YSS 产品经理
     stages: [ stage.plan, stage.spec-architecture, stage.product-design, stage.verification-release-retrospective ]
-    draft_artifact_ids: [ artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation ]
+    draft_artifact_ids: [ artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation-v2 ]
     core_skills: [ yss-design-system, yss-prototype-stage, prototype-review, yss-research, competitive-intelligence ]
     forbidden_skills: [ yss-ui, yss-domain, yss-repository, yss-web-controller, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, implement, tdd ]
     description: >-
@@ -290,7 +290,7 @@ user_decision_policy:
   work_unit_gates:
     work-unit.spec-synthesis:
       - gate.spec-baseline-approved
-    work-unit.prototype-design:
+    work-unit.prototype-design-v2:
       - gate.product-design-approved
     work-unit.technical-analysis:
       - gate.backend-architecture-platform-approved
@@ -298,5 +298,5 @@ user_decision_policy:
   conditional_decisions: [ scaffold-choice, external-input, new-authorization, risk-acceptance ]
   waiting_allows: independent-work-only
   expiry: basis-change-or-revocation-only
-  record_schema: docs/process/schemas/user-decision.schema.json
+  record_schema: .template-spec/process/schemas/user-decision.schema.json
   verifier: scripts/verify-user-decision

package/template/{docs → .template-spec}/agents/gitlab-workflow-skills.md

@@ -6,7 +6,7 @@
 
 当项目主远端为 GitLab 时，默认使用 GitLab 作为代码托管、Merge Request、CI/CD 和工作流协作入口。
 
-Spec、Ticket 和 triage 不在本文中写死到 GitLab；它们按 `docs/agents/issue-tracker.md` 在 Local Markdown、GitLab / GitHub 间路由。
+Spec、Ticket 和 triage 不在本文中写死到 GitLab；它们按 `.template-spec/agents/issue-tracker.md` 在 Local Markdown、GitLab / GitHub 间路由。
 
 已集成能力：
 
@@ -112,7 +112,7 @@ scripts/gitworks ci-status
 
 1. 读取项目状态：`scripts/gitworks status`。
 2. 需要 GitLab API / clone / push workflow 时，使用 `gitlab-workflow` skill。
-3. 需要 MR / CI / Pipeline 时，使用 `glab` 或 `scripts/gitworks`；需要 Ticket / Spec / triage 时，先按 `docs/agents/issue-tracker.md` 判断 Local Markdown、GitLab 或 GitHub。
+3. 需要 MR / CI / Pipeline 时，使用 `glab` 或 `scripts/gitworks`；需要 Ticket / Spec / triage 时，先按 `.template-spec/agents/issue-tracker.md` 判断 Local Markdown、GitLab 或 GitHub。
 4. 执行自动提交前，必须先检查工作区脏文件，避免把无关 `.agents/`、`.codex/`、本机配置或用户未确认文件混入提交。
 5. 不直接提交到受保护主分支；默认使用 `feature/*`、`fix/*`、`chore/*` 分支。
 6. 自动 workflow 只在用户明确授权提交/推送时执行。

package/template/{docs → .template-spec}/agents/issue-tracker.md

@@ -92,7 +92,7 @@ Git checkpoint 必须说明主 tracker、同步状态、验证命令、剩余风
 - Apply labels: `glab issue update <iid> --label "ready-for-agent"`
 - Close an issue: `glab issue close <iid>`
 
-GitLab 相关配置和 MR / CI 工作流见 `docs/agents/gitlab-workflow-skills.md`。
+GitLab 相关配置和 MR / CI 工作流见 `.template-spec/agents/gitlab-workflow-skills.md`。
 
 ## GitHub Issues
 

package/template/{docs → .template-spec}/agents/skill-migrations.md

@@ -65,7 +65,7 @@ DDD 脚手架的 Parent 工程约束由 `yss-ddd-scaffold-generator/references/e
 
 新工作迁移到：
 
-- 通用生命周期路由直接使用 `yss-product-lifecycle`；并行执行遵循 `docs/process/subagent-collaboration.md` 和运行时原生协调能力。
+- 通用生命周期路由直接使用 `yss-product-lifecycle`；并行执行遵循 `.template-spec/process/subagent-collaboration.md` 和运行时原生协调能力。
 - 前端业务页面统一使用 `yss-ui` + `yss-ui-business-page-generation`，按影响面加载组件、Formily、表格、树、API、主题和高度专项 Skill。
 - 原型还原使用批准且摘要当前的 Visual Baseline、`frontend_implementation_plan` 与 `frontend_implementation_verification`；只做 type-check 不构成还原通过。
 - 前端与微应用提交统一使用 `frontend-commit`，scope 以仓库真实规则和业务模块为准，不再按目录机械映射。
@@ -80,7 +80,7 @@ DDD 脚手架的 Parent 工程约束由 `yss-ddd-scaffold-generator/references/e
 同步升级内容：
 
 - 技能注册表和调用者使用新 canonical ID；Registry、编译器合同、Slice Implementation Contract 与 YSS Skill Execution Result 使用 schema v2。
-- Recipe 只引用 dotted capability；类型化依赖只由 `docs/agents/yss-skill-registry.yaml` 持有。
+- Recipe 只引用 dotted capability；类型化依赖只由 `.template-spec/agents/yss-skill-registry.yaml` 持有。
 - 旧 schema v1 输入明确拒绝并返回迁移提示，不自动升级。
 - 历史冻结证据和不可变候选快照不改写。旧 ID 仅可继续出现在本迁移记录、`OBSOLETE` 阻断集合及负向测试中。
 
@@ -98,3 +98,18 @@ DDD 脚手架的 Parent 工程约束由 `yss-ddd-scaffold-generator/references/e
 - 独立低保真评审：`prototype-review`
 
 已关闭的 Prototype Evidence schema v1/v2/v3、旧 artifact ID、AntD CLI、浏览器验证和确认记录只读保留。在途 UI 工作迁移到 Prototype Evidence schema v4、Visual Baseline schema v1 与 `artifact.prototype-deliverable` 后再关闭门禁；无 UI 影响不创建空包。不得创建同名兼容目录或删除历史证据。
+
+## 2026-09-28 入口收敛
+
+以下旧 Skill ID 已硬退役：新调用返回 `skill-retired` 和迁移提示，不能自动执行替代入口或改变阶段状态。历史证据只读保留。
+
+| 旧入口 | 承接位置 |
+|---|---|
+| wait-what | 普通解释对话，按文档写作规范或 i-have-adhd 调整表达 |
+| grill-with-docs | 当前生命周期的 work-unit.plan-requirements，保留 Context 校验、对账和退出判定 |
+| to-questionnaire | 当前生命周期外部输入问卷，保留 external-input-required 与答案回流合同 |
+| improve-codebase-architecture | codebase-design 显式架构审计模式及可选 HTML 报告 |
+
+Data Analytics 平台包从本模板及 frontend 分发退出；不卸载用户另装插件。frontend-commit / java-backend-commit 保留专项入口并读取内部 git-commit-core。prototype 仅做逻辑与状态试验；正式 UI 由生命周期产品设计阶段承接。
+
+存量实例先预览同步计划。只按旧版本基线移除未修改的受管文件，用户修改保留并报告冲突；不自动迁移历史审批、问卷或快照。

package/template/{docs → .template-spec}/agents/triage-labels.md

@@ -10,6 +10,6 @@
 | `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要会签（指定数字人或生物人）或特权访问 |
 | `wontfix` | `wontfix` | 不会处理 |
 
-当 skill 提及某个 Ticket 状态时，使用表中对应的 Tracker 标签。会签人由 `docs/agents/digital-human-roles.yaml` 指定，不由本表指定。
+当 skill 提及某个 Ticket 状态时，使用表中对应的 Tracker 标签。会签人由 `.template-spec/agents/digital-human-roles.yaml` 指定，不由本表指定。
 
 Local Markdown 主 tracker 不调用远程标签：在 Ticket 文件顶部使用同名 `Status:` 值记录 Ticket 状态。Wayfinder 的 `claimed` / `resolved` 仅是临时工作状态，不属于本表五态；进入交付 Ticket 前必须转换为标准 `Status:`。

package/template/{docs → .template-spec}/agents/yss-skill-registry.yaml

@@ -121,14 +121,14 @@ capability_contract:
   platform_component_binding:
     marker: provider
     required_kind: yss-component
-    catalog_source: docs/engineering/backend-platforms.json
+    catalog_source: .template-spec/engineering/backend-platforms.json
   provider_kinds: [yss-component, platform-managed, none]
 retirement_contract:
   schema_version: 1
   stages: [deprecated, retired]
   deprecated_new_use: forbidden
   cleanup_statuses: [migration-only, remove-ready]
-  hard_retirement_tombstone: docs/agents/skill-migrations.md
+  hard_retirement_tombstone: .template-spec/agents/skill-migrations.md
   retired_id_source: scripts/lib/skill-supply-chain.mjs#OBSOLETE
   failure_codes:
     deprecated: skill-deprecated
@@ -190,6 +190,10 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  frontend-commit:
+    - { skill: git-commit-core, type: context-required }
+  java-backend-commit:
+    - { skill: git-commit-core, type: context-required }
   yss-backend-spec-review:
     - { skill: alibaba-java-code-style, type: context-required }
     - { skill: yss-implementation-contract-compiler, type: coordination-only }
@@ -361,12 +365,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [discovery]
-  - id: grill-with-docs
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: grilling
     layer: core
     maturity: supported
@@ -391,12 +389,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [lifecycle]
-  - id: improve-codebase-architecture
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [quality]
   - id: llm-wiki
     layer: core
     maturity: verified
@@ -457,12 +449,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [quality]
-  - id: to-questionnaire
-    layer: maintainer-only
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: to-spec
     layer: compatibility
     maturity: supported
@@ -487,12 +473,6 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [setup]
-  - id: wait-what
-    layer: maintainer-only
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [setup]
   - id: wayfinder
     layer: maintainer-only
     maturity: supported
@@ -751,6 +731,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [frontend]
+  - id: git-commit-core
+    layer: maintainer-only
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [template-maintenance]
   - id: frontend-commit
     layer: maintainer-only
     maturity: supported
@@ -788,11 +774,6 @@ skills:
     aliases: []
     impacts: [frontend]
 platform_skills:
-  - id: data-analytics
-    root: .codex/skills
-    layer: maintainer-only
-    instance_default_discoverable: false
-    aliases: []
   - id: product-design
     root: .codex/skills
     layer: specialist

package/template/{docs → .template-spec}/architecture/README.md

@@ -21,38 +21,14 @@
 
 推荐模板：
 
-- `docs/design/templates/product-overview-design-template.md`：Spec 初稿之后、页面 / 原型 / 交互设计之前的产品总体设计 / 功能架构评审稿。
-- `docs/architecture/templates/system-overview-design-template.md`：系统 / 数据架构与工程契约设计审查阶段的系统概要设计评审稿，承接 API 影响分析 / 契约草案 / OpenAPI Draft 与工程基线，并在 OpenAPI Freeze 前反向校验 Draft。
+- `.template-spec/design/templates/product-overview-design-template.md`：Spec 初稿之后、页面 / 原型 / 交互设计之前的产品总体设计 / 功能架构评审稿。
+- `.template-spec/architecture/templates/system-overview-design-template.md`：系统 / 数据架构与工程契约设计审查阶段的系统概要设计评审稿，承接 API 影响分析 / 契约草案 / OpenAPI Draft 与工程基线，并在 OpenAPI Freeze 前反向校验 Draft。
 
 ---
 
-## AI 四种角色
-
-### 方案生成器
-```python
-delegate_task(
-    goal="为'[功能]'生成 3 种技术方案并做 trade-off 对比",
-    context="评估维度：复杂度/安全/性能/扩展性/契合度/开发成本"
-)
-```
-
-### 预审者 — 六维度审查
-```python
-delegate_task(
-    goal="从可扩展性、安全性、性能、可靠性、可维护性、成本六个维度预审此方案",
-    context="每个维度打分 1-5，评分<3 给出替代方案"
-)
-```
-
-### ADR 记录者
-```python
-delegate_task(
-    goal="根据技术讨论记录，自动生成 ADR",
-    context="使用 docs/templates/adr-template.md 模板"
-)
-```
+## 方案比较与审查
 
----
+存在真实取舍时比较候选方案，按业务风险说明依据，不固定方案数量或评分阈值。审查和批准只消费生命周期注册表及流程裁剪规则；本说明不增加架构师签字或进入实现的独立条件。ADR 仅记录难以回滚、非显而易见且存在真实取舍的决定。
 
 ## 六维度审查清单 (39项)
 
@@ -71,7 +47,7 @@ delegate_task(
 
 ## Deep Module 治理
 
-当出现模块难改、测试 seam 不清晰、逻辑散落、Agent 难以理解代码路径时，优先使用 `improve-codebase-architecture` 和 `codebase-design`。
+当出现模块难改、测试 seam 不清晰、逻辑散落、Agent 难以理解代码路径时，优先使用 `codebase-design` 的显式架构审计模式。
 
 落地产物：
 
@@ -82,10 +58,3 @@ delegate_task(
 架构讨论必须使用统一术语：`module`、`interface`、`seam`、`adapter`、`depth`、`leverage`、`locality`。
 
 ---
-
-## AI-Human Loop
-
-```
-需求 → AI 3方案对比 → 架构师选方向 → AI 详细方案
-→ AI 六维预审 → 架构师签字 → ADR 记录 → 进入实现
-```

package/template/{docs → .template-spec}/architecture/templates/tech-design-template.md

@@ -1,5 +1,7 @@
 # 技术方案：[功能名称]
 
+> 本文仅作为技术方案阅读模板；后端交付的批准与实现输入以 `yss-technical-design` 持有的当前结构化 Technical Design 合同为准。性能目标从已确认的需求和工程基线填写，不预设阈值。
+
 > 版本: 0.1 | 作者: | 日期: | 关联: Spec-xxx / ADR-xxx
 
 ---
@@ -101,7 +103,7 @@ CREATE TABLE xxx (
 | 指标 | 目标 | 方案 |
 |------|------|------|
 | 预期 QPS | | |
-| P99 响应时间 | ≤ 200ms | |
+| P99 响应时间 | <已确认目标及依据；未确认则留待决定> | |
 | 数据量 (1年) | | |
 | 缓存策略 | | Redis / CDN / 浏览器缓存 |
 | 数据库索引 | | |

package/template/{docs → .template-spec}/design/README.md

@@ -5,16 +5,16 @@
 设计系统基线：
 
 - `DESIGN.md`：机器可读的视觉 token 与组件变体规范源，按 Google `design.md` alpha 格式维护。
-- `docs/design/design-system-sync.yaml`：主模板与可独立分发的战略设计模板之间的共享章节版本与 SHA-256 同步摘要。
-- `docs/design/design.md`：YSS 设计治理、双轨运行时、生命周期和验证说明；不与规范源重复定义 token。
-- `docs/design/tokens/`：随仓库保存的主题、亮色 / 暗色 / 紧凑 token 和 CSS 变量快照，后续实现不得依赖本机 Downloads 目录或原始 Less。
+- `.template-source/design/design-system-sync.yaml`：主模板与可独立分发的战略设计模板之间的共享章节版本与 SHA-256 同步摘要。
+- `.template-spec/design/design.md`：YSS 设计治理、双轨运行时、生命周期和验证说明；不与规范源重复定义 token。
+- `.template-spec/design/tokens/`：随仓库保存的主题、亮色 / 暗色 / 紧凑 token 和 CSS 变量快照，后续实现不得依赖本机 Downloads 目录或原始 Less。
 - 默认工作界面密度：`theme.json` 使用 default algorithm，与 Data Quality 的 32px 控件、14px 正文、20px Card 内距一致；仅显式紧凑模式叠加一次 compact algorithm；暗色紧凑模式组合 dark 与 compact algorithm，禁止重复压缩。
 
 Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生快照；治理说明不得复制具体值。业务状态、API、权限和交互验收继续使用 Spec、交互说明及状态矩阵。
 
 产品原型由 `yss-prototype-stage` 持有阶段合同：先评审低保真/状态矩阵，再选择 H1 视觉或 H2 流程，并按需调用 `product-design:index` focused workflow。YSS 生命周期负责校验档位选择、Prototype Evidence schema v4、Visual Baseline schema v1、统一 Design QA、用户确认和 Spec / OpenAPI 回填。原型阶段不得调用生产实现技能 `yss-ui`。
 
-进入 Spec 初稿 / 需求基线流程后，必须先沉淀产品总体设计 / 功能架构，再进入页面 / 原型 / 交互设计、Spec 校准、API 影响分析 / 契约草案或实现。产品总体设计文档必须包含低保真原型 / 页面草图，用于验证页面结构、关键操作和主流程。无 UI 的功能也需要产品总体设计 / 功能架构来说明功能域、业务对象、模块边界、API / 数据影响和不适用的页面状态；只有不进入 Spec 生命周期的小改动可在影响面评估中记录不适用原因。
+进入 Spec 初稿 / 需求基线流程后，先沉淀产品总体设计 / 功能架构，再进入页面 / 原型 / 交互设计、Spec 校准、API 影响分析 / 契约草案或实现。有 UI 影响时，产品总体设计记录早期页面 / 流程草图与待验证问题；正式低保真原型属于产品设计阶段。无 UI 的功能仍需说明功能域、业务对象、模块边界及 API / 数据影响，并记录页面草图不适用的依据；不生成空原型。
 
 进入 API 影响分析 / 契约草案前，有用户界面的功能还必须沉淀：
 
@@ -31,13 +31,14 @@ Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生
 
 推荐模板：
 
-- `docs/design/templates/product-overview-design-template.md`：Spec 初稿之后、页面 / 原型 / 交互设计之前，用于团队评审产品总体设计、功能架构、低保真原型、页面/API/数据影响和 Spec 回填项；它是后续交互设计输入，不替代详细交互说明。
-- `docs/design/templates/interaction-spec-template.md`：页面、流程、交互、Spec 回填项和 OpenAPI 反推清单。
-- `docs/design/templates/state-matrix-template.md`：loading、empty、error、readonly、no-permission、conflict 等状态。
-- `docs/design/templates/prototype-review-checklist.md`：进入 Spec 校准 / API 影响分析 / 契约草案前的原型评审门禁。
-- `docs/design/templates/prototype-confirmation-template.md`：原型交付物验证后的用户确认记录。
-- `docs/design/templates/prototype-evidence-template.yaml`：Prototype Evidence schema v4 原型档位、浏览器、统一 Design QA、Visual Baseline 引用、条件组件事实、评审和确认的机器可读证据清单。
-- `docs/design/templates/visual-baseline-template.yaml`：Visual Baseline schema v1 页面语义、视口、状态、图片、mask、来源和采集环境的可移植清单。
+- `.template-spec/design/templates/product-overview-design-template.md`：Spec 初稿之后、产品设计之前，用于评审功能架构、早期页面 / 流程草图、影响面和 Spec 回填项；正式低保真原型在产品设计阶段完成。
+- `.template-spec/design/templates/interaction-spec-template.md`：页面、流程、交互、Spec 回填项和 OpenAPI 反推清单。
+- `.template-spec/design/templates/state-matrix-template.md`：loading、empty、error、readonly、no-permission、conflict 等状态。
+- `.template-spec/design/templates/examples/`：已填示例仅说明填写方式，不构成项目需求或批准结论。
+- `.template-spec/design/templates/prototype-review-checklist.md`：进入 Spec 校准 / API 影响分析 / 契约草案前的原型评审门禁。
+- `.template-spec/design/templates/prototype-confirmation-template.md`：原型交付物验证后的用户确认记录。
+- `.template-spec/design/templates/prototype-evidence-template.yaml`：Prototype Evidence schema v4 原型档位、浏览器、统一 Design QA、Visual Baseline 引用、条件组件事实、评审和确认的机器可读证据清单。
+- `.template-spec/design/templates/visual-baseline-template.yaml`：Visual Baseline schema v1 页面语义、视口、状态、图片、mask、来源和采集环境的可移植清单。
 
 推荐技能：