create-yss-spec 3.5.0 → 3.5.3

package/template/.template-spec/templates/verification-record-template.md

@@ -0,0 +1,64 @@
+---
+pipeline: <feature-id>
+stage: verify
+status: draft
+owner: ai
+---
+
+# <功能名称>Fresh Verification 记录
+
+> 适用场景：合并、发布、归档或宣称完成前。
+> 本文记录最新验证证据；没有 fresh verification，不得给出“完成 / 可合并 / 可发布”结论。
+
+## 1. 验证范围
+
+- 当前验证对象：<候选 / 合同 / 工作树范围及其实际摘要记录引用>。
+- 上游验收依据：<当前 Spec、Ticket、适用契约与质量基线引用>。
+- 实际运行记录：<可读日志或结构化结果引用；未运行写未执行>。
+
+以下摘要从上述证据形成，保留证据来源；资产变化后按影响重新验证，不能沿用旧通过结论。
+
+| 范围 | 说明 | 是否覆盖 |
+|------|------|----------|
+| Spec 验收标准 |  | 是 / 否 |
+| OpenAPI / 契约 |  | 是 / 否 / 不适用 |
+| 后端行为 |  | 是 / 否 / 不适用 |
+| 前端组件 / 页面 |  | 是 / 否 / 不适用 |
+| E2E 关键路径 |  | 是 / 否 / 不适用 |
+| 风险 / 回滚约束 |  | 是 / 否 / 不适用 |
+
+## 2. 命令与结果
+
+引用已有运行记录，核对其中的候选 / 输入、cwd、实际命令、开始与结束时间、退出码及日志位置。Agent 从记录整理下面的阅读摘要，人工无需另抄机器摘要；记录缺项时明确写未知，不能将计划命令写成已执行。
+
+| 运行记录引用 | 覆盖的验收 / 范围 | 实际结果与未覆盖项 |
+|---|---|---|
+| <日志 / 结构化结果> | <规则或验收引用> | <pass / fail / skipped / 未执行，及依据> |
+
+## 3. 手工验证
+
+| 场景 | 步骤 | 结果 | 证据 |
+|------|------|------|------|
+|  |  |  |  |
+
+## 4. 未覆盖风险
+
+| 风险 | 原因 | 处理方式 |
+|------|------|----------|
+|  |  |  |
+
+## 5. 完成标准
+
+- [ ] 验证命令是本次完成前新鲜执行的结果。
+- [ ] 失败项已有修复或明确阻断。
+- [ ] skipped 项有原因和处理方式；命中的必需项未执行仍阻断，未命中项才按证据记录不适用。
+- [ ] 发布 / 合并 / 归档所需证据已能追溯。
+
+## 6. 结论
+
+- 验证结论：<待验证 / 通过 / 阻断；仅针对上述候选和覆盖范围>。
+- 未覆盖范围及阻断项：<实际依据；无则说明核验范围>。
+- 合并 / 发布前提与决定：<引用当前适用门禁、Fresh Verification 和真实授权；缺失则待处理>。
+- 下一动作与负责人：<依据已有登记>。
+
+验证通过不产生合并或发布授权；实际动作仍按原流程和授权边界执行。

package/template/{docs → .template-spec}/templates/vertical-slice-ticket-template.md

@@ -72,14 +72,9 @@ Agent 使用 `scripts/slice-contract view <合同.yaml>` 展示审阅说明，
 
 ### 后端阻断规则
 
-- [ ] 未填写 `Backend Slice Implementation Contract` 时不得写后端业务代码。
-- [ ] `CMD` / `Query` / `VO` / `SingleResult` / `MultiResult` / `PageResult` 按 `yss-dto` 定义或复用；不私自新建 / 混用响应包装。
-- [ ] Controller 不用内部类或非约定包临时承载主要 DTO / VO；写操作参数继承 `CommandDTO`，读操作参数继承 `QueryDTO` 或 `PageQuery`，分页查询优先继承 `PageQuery`。
-- [ ] Controller 不手工分页主要业务集合，不穿透 Repository / Mapper / PO。
-- [ ] Application 只做用例编排、事务边界和跨聚合协调，核心领域规则放入 Domain。
-- [ ] 需要持久化的切片必须补 PO / Repository / Convertor / GatewayImpl；临时 `InMemory*Gateway` 必须标记 `seam-deferred`。
-- [ ] POJO 样板代码默认使用 Lombok；成片手写 getter/setter、constructor、builder、logger 必须说明例外原因、测试证据和 review 结论。
-- [ ] MapStruct / Convertor 强制优先；`BeanUtils.copyProperties`、反射式通用拷贝或重复手写 mapping 必须说明例外原因、测试证据和 review 结论。
+- [ ] 涉及后端业务代码时，已批准且当前的 Slice Implementation Contract 绑定 Technical Design 的架构族、工程基线、适用 Skill、测试 seam 和实现写范围。
+- [ ] 根据已批准的 `domain-driven` 或 `layered-mvc` 路线，执行合同编译器给出的 DTO、Controller、Application、持久化和对象映射约束；不得把另一架构族的 Gateway、Domain 模块或映射方式强加给本切片。
+- [ ] 合同缺失、过期、验证失败或出现新影响时停止实现，返回生命周期重新编译与批准。
 
 ## 阻塞关系
 
@@ -105,7 +100,7 @@ Agent 使用 `scripts/slice-contract view <合同.yaml>` 展示审阅说明，
 
 | 门禁 | 记录路径 | 会签角色 | 状态 |
 |---|---|---|---|
-|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `docs/agents/digital-human-roles.yaml` | pending / approved / blocked / not-applicable |
+|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `.template-spec/agents/digital-human-roles.yaml` | pending / approved / blocked / not-applicable |
 
 ## 状态
 
@@ -127,7 +122,7 @@ Agent 使用 `scripts/slice-contract view <合同.yaml>` 展示审阅说明，
 - [ ] 实现完成
 - [ ] 已新增测试且测试通过
 - [ ] 已移除调试 / 原型代码
-- [ ] 已在任务包核验 `Backend Slice Implementation Contract` 和 `Build Architecture Checklist`
+- [ ] 涉及后端时，已在任务包核验当前 Slice Implementation Contract 与适用架构约束
 - [ ] 已在任务包核验当前 `contract_id` / `contract_version`、全部工作单元和对应 `YSS Skill Execution Result`
 - [ ] 实际 changed files 均在合同允许路径内，预期证据齐全，验证结果包含执行时间
 - [ ] `new_impacts`、`drift`、`violation` 和重路由状态均有明确结论，合同未处于 `stale`

package/template/{docs → .template-spec}/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -57,7 +57,7 @@ npx create-yss-harness-frontend@latest init --target-dir ./frontend-project --pr
 
 1. `yss-project.yaml` 是 `project-instance`。
 2. 只存在本家族 metadata，且 profile 与职责一致。
-3. 根 `CONTEXT.md`、`AGENTS.md` 和 `docs/user-guide/用户手册索引.md` 可读。
+3. 根 `CONTEXT.md`、`AGENTS.md` 和 `.template-spec/user-guide/用户手册索引.md` 可读。
 4. Git 状态、实现仓登记、验证命令和回滚点符合项目实际情况。
 
 ## 第一次让 Agent 工作

package/template/{docs → .template-spec}/user-guide//347/224/250/346/210/267/346/211/213/345/206/214/347/264/242/345/274/225.md

@@ -9,10 +9,10 @@
 
 ## 按职责进入子项目
 
-- [战略设计](https://github.com/iloveZzz/yss-harness-design-agent/blob/main/docs/user-guide/用户手册索引.md)
-- [后端交付](https://github.com/iloveZzz/yss-harness-backend-agent/blob/main/docs/user-guide/用户手册索引.md)
-- [前端接收与验收](https://github.com/iloveZzz/yss-harness-frontend-agent/blob/main/docs/user-guide/用户手册索引.md)
+- [战略设计](https://github.com/iloveZzz/yss-harness-design-agent/blob/main/.template-spec/user-guide/用户手册索引.md)
+- [后端交付](https://github.com/iloveZzz/yss-harness-backend-agent/blob/main/.template-spec/user-guide/用户手册索引.md)
+- [前端接收与验收](https://github.com/iloveZzz/yss-harness-frontend-agent/blob/main/.template-spec/user-guide/用户手册索引.md)
 
 既有通用研发实例按其固定版本和本地 README 维护，不再作为新项目入口。生成实例通过 GitHub 链接跨项目导航，但实际操作以本地 profile、CLI `--help`、包版本和模板 snapshot 为准。
 
-CLI 详解：[综合 CLI](https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md)、[战略 CLI](https://github.com/iloveZzz/create-yss-harness-design)、[后端 CLI](https://github.com/iloveZzz/create-yss-harness-backend)、[前端 CLI](https://github.com/iloveZzz/create-yss-harness-frontend)。组件专项见 [YSS UI MCP](yss-ui-mcp.md)。
+CLI 详解：[综合 CLI](https://github.com/iloveZzz/create-yss-spec/blob/main/.template-spec/user-guide/create-yss-spec-cli-guide.md)、[战略 CLI](https://github.com/iloveZzz/create-yss-harness-design)、[后端 CLI](https://github.com/iloveZzz/create-yss-harness-backend)、[前端 CLI](https://github.com/iloveZzz/create-yss-harness-frontend)。组件专项见 [YSS UI MCP](yss-ui-mcp.md)。

package/template/AGENTS.md

@@ -15,11 +15,11 @@
 |---|---|
 | 词汇 | `CONTEXT.md` |
 | Agent 入口红线 | `AGENTS.md` |
-| 阶段、门禁、产物、工作单元、证据、稳定 ID | `docs/process/lifecycle-registry.yaml`；`docs/process/lifecycle-artifact-map.md` 仅为派生阅读视图 |
-| 影响面、`not-applicable`、模板维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
-| Skill 来源、版本、投影、路由 | `skills-lock.json`、`docs/agents/yss-skill-registry.yaml` |
-| 数字人角色、运行时与会签 | `docs/agents/digital-human-roles.yaml` |
-| 视觉规范 | `DESIGN.md`；治理见 `docs/design/design.md` |
+| 阶段、门禁、产物、工作单元、证据、稳定 ID | `.template-spec/process/lifecycle-registry.yaml`；`.template-spec/process/lifecycle-artifact-map.md` 仅为派生阅读视图 |
+| 影响面、`not-applicable`、模板维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
+| Skill 来源、版本、投影、路由 | `skills-lock.json`、`.template-spec/agents/yss-skill-registry.yaml` |
+| 数字人角色、运行时与会签 | `.template-spec/agents/digital-human-roles.yaml` |
+| 视觉规范 | `DESIGN.md`；治理见 `.template-spec/design/design.md` |
 
 其他文档和派生视图只引用，不重复定义。
 
@@ -34,25 +34,25 @@
 
 主流程：分诊 → Plan → Spec / 功能架构 → 产品设计 → 工程契约 → Ticket → 切片 → 验证 / 发布 / 复盘。
 
-- 先按 `docs/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `docs/process/lifecycle-registry.yaml`；阅读导航见 `docs/process/lifecycle-artifact-map.md`。
+- 先按 `.template-spec/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `.template-spec/process/lifecycle-registry.yaml`；阅读导航见 `.template-spec/process/lifecycle-artifact-map.md`。
 - 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
-- 新功能和较大变更先进入 Plan；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
+- 新功能和较大变更先进入 Plan；`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
 - Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
 - `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 
 ## 6. Ticket 与状态
 
-- Plan / Spec / Design 按 `docs/process/stage-tracking.md` 从阶段入口登记工作、按需拆分并在恢复 / 流转时验证；工作项进度不替代 Ticket 五态和阶段批准。
+- Plan / Spec / Design 按 `.template-spec/process/stage-tracking.md` 从阶段入口登记工作、按需拆分并在恢复 / 流转时验证；工作项进度不替代 Ticket 五态和阶段批准。
 
 - 每个功能先建父 Ticket，汇总阶段资产、审查、阻塞和证据。
 - Spec、设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`；只有门禁通过、阻塞清除且可直接实现的垂直切片才能使用 `ready-for-agent`。
-- 按 `docs/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `docs/agents/triage-labels.md`。
+- 按 `.template-spec/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `.template-spec/agents/triage-labels.md`。
 
 ## 7. 实现与 YSS 路由硬门禁
 
-- 实现前按 `docs/process/implementation-repo-integration.md` 登记仓库、项目根、分支、CI、验证命令、回滚点；再用 `yss-implementation-contract-compiler` 编译最小 Skill 集和当前合同。
+- 实现前按 `.template-spec/process/implementation-repo-integration.md` 登记仓库、项目根、分支、CI、验证命令、回滚点；再用 `yss-implementation-contract-compiler` 编译最小 Skill 集和当前合同。
 - 无工程先确认外部仓库或输出目录。Backend `scaffold_status=required` 时，由生命周期推荐 `domain-driven` / `layered-mvc`，用户逐项目确认后路由；Frontend 用 `yss-frontend-scaffold-generator`。缺目录不改路由。
-- 脚手架仅在 `scaffold-architecture-decisions.yaml` 已确认且当前、schema v3 合同已持久化并获批准后无交互运行，只生成机械骨架。既有工程不得重选或覆盖；架构转换单独立项。
+- 脚手架仅在 `scaffold-architecture-decisions.yaml` 已确认且当前、Project Scaffold Contract schema v4 已持久化并获批准后无交互运行，只生成机械骨架。既有工程不得重选或覆盖；架构转换单独立项。
 - 正式切片只消费已批准、已持久化且当前的 Slice Implementation Contract；编译器只起草，不批准、不设置 `ready-for-agent`、不宣布完成。
 - UI 切片在 `ready-for-agent` 前须有已校验的 `frontend_implementation_plan`，实现后补 `frontend_implementation_verification`，覆盖截图 / 视觉回归、状态交互、console warning、实际 `pnpm` 退出码。
 - 前端验证优先 `pnpm`，后端优先根 `./mvnw`；缺少时记录受控例外和实际命令。
@@ -62,7 +62,7 @@
 
 - 技术事实、标准、第三方 API 或框架行为用 `yss-research`（`technical-evidence` / `strategy-evidence`）；竞品、市场、口碑用 `competitive-intelligence`。
 - 产品设计由 `yss-prototype-stage` 持有合同并调用设计系统、独立评审、H1 / H2 适配器；原型禁用 `yss-ui`。真实组件事实只用于实现计划、已批准实现和还原验证。
-- 数字人协同或会签先读 `docs/agents/digital-human-roles.yaml`；角色不得另起生命周期、批准 Slice 合同、设置 `ready-for-agent` 或宣布可发布。
+- 数字人协同或会签先读 `.template-spec/agents/digital-human-roles.yaml`；角色不得另起生命周期、批准 Slice 合同、设置 `ready-for-agent` 或宣布可发布。
 - 业务行为默认按 `tdd` 的 `behavior-tdd` 使用已确认公开 seam 逐切片实现；一次性生成、纯配置或流程文档不适用时，记录例外理由和可执行验证。
 
 ## 9. 工作区与实现仓库边界
@@ -81,7 +81,7 @@
 
 ## 11. Subagent 协同
 
-- 使用 subagent 或其他运行时前读 `docs/process/subagent-collaboration.md`，建立含角色、`runtime_id`、执行态、技能约束和不重叠写范围的任务包；共享工作区不是安全边界。
+- 使用 subagent 或其他运行时前读 `.template-spec/process/subagent-collaboration.md`，建立含角色、`runtime_id`、执行态、技能约束和不重叠写范围的任务包；共享工作区不是安全边界。
 - 仓库身份、Ticket 最终状态、Git checkpoint、Slice 合同批准和完成结论由主控裁决；实现者不得兼任独立审查者或会签自己的资产。
 
 ## 12. 测试质量基线

package/template/CONTEXT.md

@@ -9,6 +9,10 @@ context_schema_version: 1
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。
 
+## 消费规则
+
+探索仓库、起草 Spec / Ticket、架构设计和实现前读取根目录唯一的 CONTEXT.md，并按当前影响面读取 docs/adr/。合同缺失时先恢复，不能临时另建词汇表。Spec、Ticket 标题、测试、架构说明和总结使用已确认的中文术语；与冻结术语或 ADR 冲突时先明确冲突。稳定术语由 domain-modeling 维护，临时猜测留在决策前沿。生命周期引用保存结构化 snapshot 与双摘要，不使用 Markdown 伪锚点。
+
 ## 流程术语
 
 模板源与生命周期协作概念放在本节。`英文标识` 填 `—`，不回溯补译。
@@ -19,10 +23,10 @@ context_schema_version: 1
 | Agent | 执行特定工作流步骤的 AI 协作者。 | — | 不要与生物人审查者、数字人角色或 Ticket 状态混用。运行时实例（Cursor Agent、Codex、Grok Bot 等）是 Agent 的承载，不是角色本身。 |
 | 运行时绑定 | 把数字人角色落到某个 Agent 平台的适配声明，权威清单在数字人角色注册表的 `runtimes`。 | — | 不要为每个平台复制一套职称职责。 |
 | Grok Bot | Grok 平台上的持久数字队友实例；对应 `runtime.grok`。 | — | 不是数字人角色、技能或门禁。 |
-| 数字人角色 | 叠加在生命周期编排器上的职称配置；一个运行时实例绑定一种。v1 清单以 `docs/agents/digital-human-roles.yaml` 为准。 | — | 不要称为 Ticket「标准角色」、职能 Agent 或某个平台的产品名。 |
+| 数字人角色 | 叠加在生命周期编排器上的职称配置；一个运行时实例绑定一种。v1 清单以 `.template-spec/agents/digital-human-roles.yaml` 为准。 | — | 不要称为 Ticket「标准角色」、职能 Agent 或某个平台的产品名。 |
 | 主控数字人 | 运行 `yss-product-lifecycle` 的协调实例。 | — | 不是第八个业务职称；默认兼任项目经理。 |
 | 角色配置 | 某数字人角色的关注阶段、技能包、可起草产物和禁止事项。 | — | 不是独立编排器，也不含平台群聊人数。 |
-| 生命周期会签 | 指定数字人或生物人关闭 `gate.*` / 独立审查并写入 `evidence.approval-record`。 | — | 不是运行时副作用审批。会签人由 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 指定。起草者不得会签自己起草的资产。`paused-human-gate` 表示等待该会签人，不是必须生物人。 |
+| 生命周期会签 | 指定数字人或生物人关闭 `gate.*` / 独立审查并写入 `evidence.approval-record`。 | — | 不是运行时副作用审批。会签人由 `.template-spec/agents/digital-human-roles.yaml` 的 `gate_policy` 指定。起草者不得会签自己起草的资产。`paused-human-gate` 表示等待该会签人，不是必须生物人。 |
 | 用户决定 | 提问者或其明确指定的生物人负责人针对已展示资产、版本及范围作出的可追溯回复。 | — | 数字人审查不能代答；原始回复、指定依据及批准范围按用户决定协议记录。 |
 | 运行时副作用审批 | 对发消息、改生产、付款、删数据等工具动作的账号级确认。 | — | 点 Allow 不等于门禁已批准或可发布。避免只称「Grok 平台审批」。 |
 | Ticket 状态 | Tracker 五态：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 | — | 不要称为数字人角色或「标准角色」。 |
@@ -62,7 +66,7 @@ context_schema_version: 1
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | — | 不等同于“之前跑过”或实现者自述。 |
 | `implementation-ready` | 模板维护实现和命中影响面的快速核验已经完成，但尚未冻结正式审查候选。 | — | 是模板维护默认出口；不等同于 `ready-for-agent`、已审查或可发布。 |
 | `review-ready` | 模板维护显式选择独立审查时的就绪状态；旧候选协议要求 candidate 核验、首次完整验证和摘要冻结。 | — | Reviewer 必须消费同一候选摘要；候选字节变化后旧审查失效。 |
-| `release-ready` | 模板维护已完成维护者自检和发布前完整 Fresh Verification；显式选择独立审查时还须闭合该审查。 | — | 仍不替代 `gate.release-ready` 所需的生物人发布裁决。 |
+| `release-ready` | 模板维护已完成维护者自检和发布前完整 Fresh Verification；显式选择独立审查时还须闭合该审查。 | — | 交付验收使用 `gate.delivery-accepted`；实际合并、发布仍须单独取得生物人授权。 |
 | 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | — | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
 | 脚手架架构选择 | 新建后端工程在工程基线中对 `domain-driven` 与 `layered-mvc` 的结构化选择；Agent 提供证据化推荐，用户确认后由生命周期批准并供脚手架合同消费。 | — | 不是新门禁，也不是生成器内的交互参数；缺失、未确认或摘要漂移时阻断生成。 |
 | 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | — | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
@@ -92,7 +96,7 @@ context_schema_version: 1
 | 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 实现合同编译器 默认技能闭包。 |
 | 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | — | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
 | 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | — | 不等同于文件存在、已被投影或能够安装。 |
-| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `active`，实现合同编译器、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `.template-spec/agents/yss-skill-registry.yaml` 为 `active`，实现合同编译器、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
 | LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | — | 不是 `yss-research` 一次性研究包，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | — | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | — | 不等同于前端 / 后端代码 monorepo。 |

package/template/README.md

@@ -9,48 +9,36 @@
 ## 项目结构
 
 ```text
-├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
-├── .codex/                  ← Codex skills 投影与平台专属 skills
-├── .cursor/                 ← Cursor skills 投影
-├── .pi/                     ← Pi skills 投影与平台专属 skills
-├── AGENTS.md                ← AI 指令
-├── CONTEXT.md               ← 领域词汇表
-├── yss-project.yaml         ← 仓库身份清单
-├── docs/
-│   ├── api/                 ← OpenAPI 3.1 契约
-│   ├── adr/                 ← 架构决策记录
-│   ├── requirements/        ← Spec / 用户故事 / 需求草案 / 垂直切片
-│   ├── plan/                ← 战略规划与 Spec 上游输入
-│   ├── design/              ← 产品设计、原型、交互说明和状态矩阵
-│   ├── architecture/        ← 架构设计与审查模板
-│   ├── releases/            ← 发布说明
-│   ├── implementation/      ← 实施方案、上线记录和回滚方案
-│   ├── testing/             ← 测试策略和验证记录
-│   ├── agents/              ← Agent 协作规范、Ticket/Triage/领域文档约定
-│   ├── templates/           ← 通用文档模板
-│   └── process/             ← 生命周期、裁剪、Scrum 和技能治理说明
-└── scripts/                 ← 模板轻量校验脚本
+├── .agents/skills/          ← 共享技能权威内容
+├── .codex/、.cursor/、.pi/  ← 技能投影与平台专属能力
+├── AGENTS.md                ← Agent 入口规则
+├── CONTEXT.md               ← 唯一业务词汇表
+├── yss-project.yaml         ← 仓库身份
+├── .template-spec/          ← 可复用流程、门禁、契约与文档模板
+├── .template-source/        ← 模板维护、分发工具和历史证据（不进入实例）
+├── docs/                    ← 项目实例按需创建的 Plan、Spec、设计、Ticket 与交付证据
+└── scripts/                 ← 合同与流程验证工具
 ```
 
-项目需要生成度量、外部实现仓库记录或其他临时产物时再按需创建对应目录。前后端实现仓库接入规则见 `docs/process/implementation-repo-integration.md`。
+项目需要生成度量、外部实现仓库记录或其他临时产物时再按需创建对应目录。前后端实现仓库接入规则见 `.template-spec/process/implementation-repo-integration.md`。
 
 ## Quickstart
 
 1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
-2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
+2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实以生命周期注册表和裁剪指南为准。
 3. `template-source` 修改后先按 `maintenance-intensity.yaml` 判定 L1 / L2 / L3，默认用 `scripts/verify-template-fast` 达到 `implementation-ready`；L3 日常采用维护者自检，正式发布前执行完整门禁；只有共享 skill 变更才运行 `scripts/sync-skills` 和 `scripts/update-skill-lock`。
-4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
+4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
 5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 
-YSS UI 组件知识同时通过项目级 MCP 配置提供；支持的客户端、Codex 全局安装和自检方法见 [YSS UI MCP 接入](./docs/user-guide/yss-ui-mcp.md)。
+YSS UI 组件知识同时通过项目级 MCP 配置提供；支持的客户端、Codex 全局安装和自检方法见 [YSS UI MCP 接入](./.template-spec/user-guide/yss-ui-mcp.md)。
 
 ## 模板初始化 CLI
 
 `create-yss-spec` 的发布仓库是 [iloveZzz/create-yss-spec](https://github.com/iloveZzz/create-yss-spec)。用户从统一手册选择家族；CLI 源码、测试、打包和发布仍在各自仓库维护：
 
-- [YSS 用户手册：CLI 能力与写入方式](./docs/user-guide/用户手册.md#cli-能力与写入方式)
-- [YSS 用户手册：接管、同步与恢复](./docs/user-guide/用户手册.md#接管同步与恢复)
+- [YSS 用户手册：CLI 能力与写入方式](./.template-spec/user-guide/用户手册.md#cli-能力与写入方式)
+- [YSS 用户手册：接管、同步与恢复](./.template-spec/user-guide/用户手册.md#接管同步与恢复)
 
 推荐入口：
 
@@ -94,36 +82,36 @@ scripts/verify-template-fast
 - 示例 OpenAPI YAML 是否可解析。
 - Git diff 是否存在空白错误。
 
-显式准备审查候选时执行 `scripts/verify-template-candidate`；首次正式冻结前和最终发布前执行不可裁剪的 `scripts/verify-template`。
+PR 执行 `scripts/verify-template-candidate`；main 与正式发布前执行不可裁剪的 `scripts/verify-template`。独立审查和候选冻结仅在显式采用旧兼容协议时执行。
 
 ## 关键文档
 
-业务方可从[用户手册](./docs/user-guide/用户手册.md)了解工作入口；阶段、条件门禁和完成证据以生命周期注册表及流程裁剪规则为准。
+业务方可从[用户手册](./.template-spec/user-guide/用户手册.md)了解工作入口；阶段、条件门禁和完成证据以生命周期注册表及流程裁剪规则为准。
 
 | 文档 | 内容 |
 |------|------|
 | [AGENTS.md](./AGENTS.md) | 全局 AI 指令 + 工程基线入口 + Agent 协作 |
-| [docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
-| [阶段接入与产物复用使用手册](./docs/user-guide/阶段接入与产物复用使用手册.md) | 复用上游资产，从指定入口继续；含后端交付后前端开发操作 |
-| [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
-| [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
-| [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
-| [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
-| [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
-| [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
-| [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
+| [.template-spec/user-guide/用户手册.md](./.template-spec/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
+| [阶段接入与产物复用使用手册](./.template-spec/user-guide/阶段接入与产物复用使用手册.md) | 复用上游资产，从指定入口继续；含后端交付后前端开发操作 |
+| [.template-source/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./.template-source/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
+| [.template-spec/process/lifecycle-registry.yaml](./.template-spec/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
+| [.template-spec/process/harness-process-tailoring.md](./.template-spec/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
+| [.template-spec/process/implementation-repo-integration.md](./.template-spec/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
+| [.template-spec/agents/README.md](./.template-spec/agents/README.md) | Agent 协作文档目录说明 |
+| [.template-spec/user-guide/yss-ui-mcp.md](./.template-spec/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
+| [.template-spec/architecture/README.md](./.template-spec/architecture/README.md) | 架构设计 + 审查清单 |
 
 ## 核心模板
 
 | 模板 | 用途 |
 |------|------|
-| [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
-| [docs/templates/local-parent-ticket-template.md](./docs/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
-| [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
-| [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
-| [docs/templates/cross-repo-slice-template.md](./docs/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |
-| [docs/architecture/templates/architecture-deepening-template.md](./docs/architecture/templates/architecture-deepening-template.md) | 架构 deepening 候选与 seam 设计 |
+| [.template-spec/templates/spec-template.md](./.template-spec/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
+| [.template-spec/templates/local-parent-ticket-template.md](./.template-spec/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
+| [.template-spec/templates/vertical-slice-ticket-template.md](./.template-spec/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
+| [.template-spec/templates/implementation-repo-registry-template.md](./.template-spec/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |
+| [.template-spec/templates/cross-repo-slice-template.md](./.template-spec/templates/cross-repo-slice-template.md) | 跨仓库垂直切片记录 |
+| [.template-spec/architecture/templates/architecture-deepening-template.md](./.template-spec/architecture/templates/architecture-deepening-template.md) | 架构 deepening 候选与 seam 设计 |
 
 ## 按职责使用与升级
 
-[四个现行家族用户手册](docs/user-guide/用户手册.md)提供选型、初始化及升级；[设备借用贯穿案例](docs/user-guide/设备借用贯穿案例.md)演示战略、后端、前端与统一验收。[全部手册](docs/user-guide/用户手册索引.md)给出本体和子项目入口。GitHub 当前能力、npm 发布版本与实例模板快照分别核对。
+[四个现行家族用户手册](.template-spec/user-guide/用户手册.md)提供选型、初始化及升级；[设备借用贯穿案例](.template-spec/user-guide/设备借用贯穿案例.md)演示战略、后端、前端与统一验收。[全部手册](.template-spec/user-guide/用户手册索引.md)给出本体和子项目入口。GitHub 当前能力、npm 发布版本与实例模板快照分别核对。

package/template/scripts/backend-delivery

@@ -8,7 +8,7 @@ async function preflightExport(values) {
   const root=path.resolve(values['source-root']),delivery=read(safe(root,values.delivery));
   const document=read(safe(root,delivery.slice_contract.ref)),contract=document.slice_contract||document;
   const identity=contract.resolution?.architecture_identity||contract.backend?.architecture_identity||contract.architecture_identity;
-  ensure(identity?.schema_version!==2||values['preflight-input'],'preflight-required: 既有工程身份 v2 导出必须提供 --preflight-input <file>；先按 docs/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
+  ensure(identity?.schema_version!==2||values['preflight-input'],'preflight-required: 既有工程身份 v2 导出必须提供 --preflight-input <file>；先按 .template-spec/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
   if(!values['preflight-input'])return;
   const {preflightDelivery}=await import('./lib/delivery-preflight.mjs');
   const input=read(path.resolve(values['preflight-input']));

package/template/scripts/contract

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import path from 'node:path';
-import {viewContract,diffContract} from './lib/contract-views.mjs';
+import {viewContract,diffContract,prepareContractReview} from './lib/contract-views.mjs';
 try{
  const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
- for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
- const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined};
+ for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root','decision','task-layout'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
+ const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,task_layout:options['task-layout']||'legacy',beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined,decision_ref:options.decision};
  if(!options.kind)throw Error('必须用 --kind 明确资产类型');
- if(!['view','diff'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff <旧资产> <新资产> --kind <类型>');
- const result=mode==='view'?viewContract(positional[0],config):diffContract(positional[0],positional[1],config);
+ if(!['view','diff','prepare-review'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff|prepare-review <旧资产> <新资产> --kind <类型> [--decision <原决定>]');
+ const result=mode==='view'?viewContract(positional[0],config):mode==='prepare-review'?prepareContractReview(positional[0],positional[1],config):diffContract(positional[0],positional[1],config);
  process.stdout.write(options.json||!result.markdown?JSON.stringify(result,null,2)+'\n':result.markdown);
  if(result.blockers?.length)process.exitCode=1;
 }catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}

package/template/scripts/lib/api-contract-decision.mjs

@@ -8,7 +8,7 @@ import { validateJsonSchema } from "./json-schema.mjs";
 import { openApiDigest, resolveOpenApiRef, validateOpenApiDraftValidationRecord } from "./openapi-draft-validation.mjs";
 
 const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const SCHEMA = path.join(TEMPLATE_ROOT, "docs/process/schemas/api-contract-decision.schema.json");
+const SCHEMA = path.join(TEMPLATE_ROOT, ".template-spec/process/schemas/api-contract-decision.schema.json");
 const fail = (message) => { throw new TypeError(message); };
 const readBound = (root, ref, label) => {
   const file = resolveOpenApiRef(root, ref);

package/template/scripts/lib/approved-execution-context.mjs

@@ -38,13 +38,13 @@ export function verifySliceContractApproval(binding,{root=process.cwd(),contract
   assertExistingSliceStructure(contract);
   check((!binding.id||binding.id===contract.contract_id)&&(!binding.version||binding.version===contract.contract_version),'EXECUTION_CONTRACT_CONFLICT','当前合同身份或版本不匹配');
   if(expected)check(same(sourceSliceContract(expected),sourceSliceContract(contract)),'EXECUTION_CONTRACT_CONFLICT','调用方合同与持久化原字节不一致');
-  const roles=read(safe(root,'docs/agents/digital-human-roles.yaml'));
+  const roles=read(safe(root,'.template-spec/agents/digital-human-roles.yaml'));
   const approval=read(safe(root,binding.approval_ref));
   if(!countersignRuleForGate(roles.gate_policy,gateId)&&roles.gate_policy.orchestrator?.includes(gateId)) {
     // The current lifecycle already owns this gate. Consume its checkpoint and existing
     // implementation-scope decision instead of inventing an approval-record countersignature.
     check(approval?.gates&&approval?.human_review&&!approval.gate_id,'EXECUTION_APPROVAL_PROTOCOL','当前主控 gate 需要生命周期 checkpoint，不接受伪造 approval-record');
-    schema(approval,'docs/process/schemas/lifecycle-checkpoint.schema.json');
+    schema(approval,'.template-spec/process/schemas/lifecycle-checkpoint.schema.json');
     const gate=approval.gates?.[gateId],review=approval.human_review||{};
     check(approval.repository_mode==='project-instance'&&approval.status!=='blocked'&&approval.blockers.length===0,'EXECUTION_APPROVAL_BLOCKED','主控 checkpoint 仍有阻断或不是产品实例');
     check(gate?.status==='approved'&&gate.subject_ref===binding.ref,'EXECUTION_APPROVAL_SCOPE','主控 gate 未批准当前持久化 Slice');
@@ -80,11 +80,11 @@ function primeApprovalSchemas(binding,root){
     // Original consumers still validate every semantic and authorization rule below.
     try{
       const source=parseSliceYaml(readFileSync(safe(root,binding.ref))),raw=source.slice_contract||source;
-      if(raw.schema_version===3)add(raw,'docs/process/schemas/slice-implementation-contract-v3.schema.json',false,'verbose');
+      if(raw.schema_version===3)add(raw,'.template-spec/process/schemas/slice-implementation-contract-v3.schema.json',false,'verbose');
       const approval=read(safe(root,binding.approval_ref));
       if(approval.gates&&approval.human_review&&!approval.gate_id){
-        add(approval,'docs/process/schemas/lifecycle-checkpoint.schema.json',false,'verbose');
-        for(const requirement of approval.human_review.user_decisions||[])if(requirement.user_decision_ref&&!requirement.continuation_ref){const ref=path.isAbsolute(requirement.user_decision_ref)?path.relative(root,requirement.user_decision_ref):requirement.user_decision_ref;add(read(safe(root,ref)),'docs/process/schemas/user-decision.schema.json',true,'compact');}
+        add(approval,'.template-spec/process/schemas/lifecycle-checkpoint.schema.json',false,'verbose');
+        for(const requirement of approval.human_review.user_decisions||[])if(requirement.user_decision_ref&&!requirement.continuation_ref){const ref=path.isAbsolute(requirement.user_decision_ref)?path.relative(root,requirement.user_decision_ref):requirement.user_decision_ref;add(read(safe(root,ref)),'.template-spec/process/schemas/user-decision.schema.json',true,'compact');}
       }
     }catch{/* The original consumer reports missing or invalid input with its existing code. */}
     if(jobs.length)validateJsonSchemas(jobs);return true;

package/template/scripts/lib/backend-delivery.mjs

@@ -20,7 +20,7 @@ async function approvedFile(root, binding, gate) {
   const bytes=boundFile(root,binding);
   if(gate==='gate.slice-contract-approved'){verifySliceContractApproval(binding,{root});return bytes;}
   const record=read(safe(root,binding.approval_ref));
-  const roles=sourceApprovalPolicy(read(safe(root,'docs/agents/digital-human-roles.yaml')));
+  const roles=sourceApprovalPolicy(read(safe(root,'.template-spec/agents/digital-human-roles.yaml')));
   await sourceApproval(record,roles,root);
   ensure((Array.isArray(gate)?gate:[gate]).includes(record.gate_id),`交付资产批准门禁不匹配: ${binding.ref}`);
   ensure(record.artifact_bindings?.some(x=>x.id===binding.id&&x.version===binding.version&&x.digest===binding.digest),`批准未绑定当前交付资产: ${binding.ref}`);
@@ -30,7 +30,7 @@ async function approvedFile(root, binding, gate) {
 function verification(root, binding, basis, kind) {
   boundFile(root,binding);
   const record=read(safe(root,binding.ref));
-  schema(record,'docs/process/schemas/backend-delivery-verification.schema.json');
+  schema(record,'.template-spec/process/schemas/backend-delivery-verification.schema.json');
   ensure(record.kind===kind&&record.subject_digest===basis,`验证未绑定当前交付: ${kind}`);
   ensure(record.results.every(x=>x.exit_code===0),`后端验证失败: ${kind}`);
   for(const result of record.results) {
@@ -43,7 +43,7 @@ function verification(root, binding, basis, kind) {
 export async function inspectBackendDelivery(root, ref, { readOnly = false } = {}) {
   project(root);
   const delivery=read(safe(root,ref));
-  schema(delivery,'docs/process/schemas/backend-delivery.schema.json');
+  schema(delivery,'.template-spec/process/schemas/backend-delivery.schema.json');
   ensure(boundFile(root,delivery.environment.test_data).length>0,'测试数据准备说明为空');
   await approvedFile(root,delivery.openapi,['gate.engineering-contract-approved','gate.openapi-frozen','gate.openapi-freeze-confirmed']);
   await approvedFile(root,delivery.slice_contract,'gate.slice-contract-approved');
@@ -115,7 +115,7 @@ export async function exportBackendDelivery({sourceRoot,deliveryRef,output,zip=f
   const root=project(sourceRoot), target=path.resolve(output);
   ensure(!existsSync(target)&&(!zip||!existsSync(`${target}.zip`)),'后端包输出已存在');
   const {delivery}=await inspectBackendDelivery(root,deliveryRef);
-  const refs=new Set([deliveryRef,'yss-project.yaml','CONTEXT.md','docs/agents/digital-human-roles.yaml',delivery.openapi.ref,delivery.openapi.approval_ref,delivery.slice_contract.ref,delivery.slice_contract.approval_ref,delivery.environment.test_data.ref,...delivery.supporting_files]);
+  const refs=new Set([deliveryRef,'yss-project.yaml','CONTEXT.md','.template-spec/agents/digital-human-roles.yaml',delivery.openapi.ref,delivery.openapi.approval_ref,delivery.slice_contract.ref,delivery.slice_contract.approval_ref,delivery.environment.test_data.ref,...delivery.supporting_files]);
   for(const binding of Object.values(delivery.verification)) {
     refs.add(binding.ref);
     for(const result of read(safe(root,binding.ref)).results)for(const file of result.evidence)refs.add(file.ref);

package/template/scripts/lib/backend-platform.mjs

@@ -6,7 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const PLATFORM_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-export const PLATFORM_CATALOG_REF = "docs/engineering/backend-platforms.json";
+export const PLATFORM_CATALOG_REF = ".template-spec/engineering/backend-platforms.json";
 export const PLATFORM_SKILLS = ["yss-ddd-scaffold-generator", "yss-layered-mvc-scaffold-generator"];
 const fail = (message) => { throw new TypeError(`backend-platform: ${message}`); };
 const componentFail = (code, message) => {

package/template/scripts/lib/backend-review.mjs

@@ -124,7 +124,7 @@ function validateBaselineReview(state,{root}) {
     ensure(digest(fs.readFileSync(file(root,input.spec_binding.ref)))===input.spec_binding.digest.replace(/^sha256:/,''),'Spec evidence stale');
     ensure(text(input.spec_binding.approval_ref),'Spec approval record required');
     const approval=parseSliceYaml(fs.readFileSync(file(root,input.spec_binding.approval_ref),'utf8'));
-    validateApprovalRecord(approval,{root,requireApproved:true,rolesDoc:parseSliceYaml(fs.readFileSync(file(root,'docs/agents/digital-human-roles.yaml'),'utf8'))});
+    validateApprovalRecord(approval,{root,requireApproved:true,rolesDoc:parseSliceYaml(fs.readFileSync(file(root,'.template-spec/agents/digital-human-roles.yaml'),'utf8'))});
     ensure(approval.gate_id==='gate.spec-baseline-approved' && approval.artifact_bindings?.some(b=>b.digest.replace(/^sha256:/,'')===input.spec_binding.digest.replace(/^sha256:/,'')),'Spec approval does not bind current baseline');
     ensure(Array.isArray(result.constraint_results)&&result.constraint_results.some(r=>r.axis==='Spec'&&r.status==='passed'&&text(r.evidence_ref)),'Spec acceptance evidence required');
     for(const row of result.constraint_results.filter(r=>r.axis==='Spec')) {

package/template/scripts/lib/backend-scaffold-prerequisites.mjs

@@ -8,7 +8,7 @@ import { ROOT } from "./lifecycle-registry.mjs";
 import { validateTechnicalDesign } from "../../.agents/skills/yss-technical-design/scripts/validate-technical-design.mjs";
 import { validateApiContractDecision } from "./api-contract-decision.mjs";
 
-const DATA_DECISION_SCHEMA = path.join(ROOT, "docs/process/schemas/data-architecture-decision.schema.json");
+const DATA_DECISION_SCHEMA = path.join(ROOT, ".template-spec/process/schemas/data-architecture-decision.schema.json");
 
 const fail = (message) => { throw new TypeError(message); };
 const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;

package/template/scripts/lib/backend-standards-coverage.mjs

@@ -153,7 +153,7 @@ export function compileStandardsCoverage({root,projectRoot,contract=null,scope_k
   // Derive component ownership from the existing registry and the locked platform index.
   // These are discovery signals only; they never certify component compatibility.
   const discovery_sources=[];
-  const registryRef='docs/agents/yss-skill-registry.yaml';
+  const registryRef='.template-spec/agents/yss-skill-registry.yaml';
   if(fs.existsSync(path.join(root,registryRef))) {
     const registryBytes=fs.readFileSync(coverageFile(root,registryRef));
     discovery_sources.push({ref:registryRef,digest:coverageDigest(registryBytes)});
@@ -195,7 +195,7 @@ export function compileStandardsCoverage({root,projectRoot,contract=null,scope_k
   for(const skill of observedSkills){const {rules,sourceDigests}=readRules(root,skill);rulesSources.push(...sourceDigests);for(const rule of rules){const applicability=tags.has(rule.when)?'required':(['pagination','batch'].includes(rule.when)?'conditional':'not-applicable');constraints.push({...rule,constraint_id:rule.id,applicability,applicability_basis:applicability==='required'?[...reasons.get(skill)].sort():[`no-observed-${rule.when}; reviewer must reconcile actual behavior`]});}}
   ensure(new Set(constraints.map(r=>r.constraint_id)).size===constraints.length,'duplicate canonical constraint_id');
   const platform=identity?.platform_configuration;
-  const catalogRef='docs/engineering/backend-platforms.json';
+  const catalogRef='.template-spec/engineering/backend-platforms.json';
   const catalogPath=path.join(root,catalogRef);
   let platform_catalog_digest=null;
   if(platform?.profile_id && fs.existsSync(catalogPath)) {

package/template/scripts/lib/context-reconciliation.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { resolveContextTermRefs, verifyContextSnapshot } from "./context-contract.mjs";
 import { validateJsonSchema } from "./json-schema.mjs";
-const schemaPath = path.resolve(import.meta.dirname, "../../docs/process/schemas/context-reconciliation.schema.json");
+const schemaPath = path.resolve(import.meta.dirname, "../../.template-spec/process/schemas/context-reconciliation.schema.json");
 export function parseReconciliationFile(file) {
   const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
   if (document.errors.length) throw new TypeError(document.errors[0].message);