create-yss-spec 3.5.0 → 3.5.2

package/template/.pi/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,13 +71,13 @@ 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:

package/template/.pi/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/.pi/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 猜测页面含义。
 
@@ -54,8 +54,8 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 
 - 档位、上游融合与迁移：[prototype-profile-routing.md](references/prototype-profile-routing.md)
 - 离线渲染适配与命令：[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`
+- 证据模板：`.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`
 
 ## 常见错误
 

package/template/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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)
@@ -56,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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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` 为准。

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 都可读的协作说明、标签约定、维护规范和技能路由注册表 |
 
 ## 当前文档
 

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` 尚未接管此步骤。
 
 ## 任务包最低字段