create-yss-spec 3.5.0 → 3.5.2

package/src/template/layout-migration.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+const { targetPath, pathKind } = require("../filesystem/path-utils");
+const {
+  createMigrationPlan,
+  addUnsafe,
+  addConflict,
+  addRemove,
+} = require("./migration-planner");
+
+const TRACKER_FROM = "docs/agents/issue-tracker.md";
+const TRACKER_TO = ".template-spec/agents/issue-tracker.md";
+const STATIC_DIRECTORIES = [
+  "docs/agents", "docs/process", "docs/templates", "docs/user-guide",
+  "docs/plan/templates", "docs/api/templates", "docs/architecture/templates",
+  "docs/design/templates", "docs/design/tokens", "docs/design/schemas",
+  "docs/design/diagrams", "docs/discovery/templates",
+];
+const STATIC_FILES = [
+  "docs/adr/README.md", "docs/architecture/README.md",
+  "docs/plan/README.md", "docs/plan/entry-review.md",
+  "docs/discovery/README.md", "docs/discovery/IDEATION.md",
+  "docs/design/README.md", "docs/design/design.md",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js", "docs/engineering/backend-platforms.json",
+  "docs/engineering/backend-platforms.md",
+];
+const RETIRED_SOURCE_ONLY = new Set([
+  "docs/agents/archify-integration.md", "docs/agents/skills-maintenance.md",
+  "docs/agents/strategic-design-skills-integration.md",
+  "docs/agents/yss-ui-skills-integration.md",
+  "docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md",
+  "docs/process/github-workflows.md", "docs/process/maintenance-intensity.yaml",
+  "docs/process/template-engineering-overview.md",
+  "docs/process/template-verification-profiles.yaml",
+  "docs/process/schemas/maintenance-review-record.schema.json",
+  "docs/process/templates/maintenance-checkpoint-template.yaml",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js",
+]);
+const SEPARATE_LEGACY_MAPPINGS = new Set([
+  "docs/templates/prd-template.md",
+  "docs/templates/vertical-slice-issue-template.md",
+]);
+
+function digest(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function legacyStaticPath(ref) {
+  return STATIC_FILES.includes(ref) ||
+    STATIC_DIRECTORIES.some((directory) => ref.startsWith(`${directory}/`));
+}
+
+function collectLegacyFiles(targetDir, desiredOperations, managedFiles, plan) {
+  const found = new Set();
+  function inspect(ref) {
+    let kind;
+    try { kind = pathKind(targetPath(targetDir, ref)); }
+    catch (error) { addUnsafe(plan, ref, error.message); return; }
+    if (kind === "missing") return;
+    if (kind === "other") { addUnsafe(plan, ref, "旧治理路径是符号链接或特殊文件"); return; }
+    if (kind === "file") { found.add(ref); return; }
+    for (const entry of fs.readdirSync(targetPath(targetDir, ref))) {
+      if (entry === ".DS_Store") continue;
+      inspect(`${ref}/${entry}`);
+    }
+  }
+  for (const directory of STATIC_DIRECTORIES) inspect(directory);
+  for (const ref of STATIC_FILES) inspect(ref);
+  for (const ref of Object.keys(managedFiles || {})) {
+    if (legacyStaticPath(ref)) inspect(ref);
+  }
+  for (const operation of desiredOperations) {
+    if (operation.relativePath.startsWith(".template-spec/")) {
+      inspect(`docs/${operation.relativePath.slice(".template-spec/".length)}`);
+    }
+  }
+  return [...found].filter((ref) => !SEPARATE_LEGACY_MAPPINGS.has(ref)).sort();
+}
+
+function prepareLayoutMigration({ targetDir, desiredOperations, managedFiles = {}, explicit = false }) {
+  const plan = createMigrationPlan(targetDir);
+  const legacyFiles = collectLegacyFiles(targetDir, desiredOperations, managedFiles, plan);
+  const desiredByPath = new Map(desiredOperations.map((operation) => [operation.relativePath, operation]));
+  const operations = [...desiredOperations];
+
+  for (const from of legacyFiles) {
+    const to = `.template-spec/${from.slice("docs/".length)}`;
+    if (!explicit) {
+      addConflict(plan, from, to, "旧治理目录布局需显式 --migrate-layout；普通 attach/sync 不写入");
+      continue;
+    }
+    const source = targetPath(targetDir, from);
+    const destination = targetPath(targetDir, to);
+    const sourceBytes = fs.readFileSync(source);
+    const destinationKind = pathKind(destination);
+    if (destinationKind !== "missing" && destinationKind !== "file") {
+      addUnsafe(plan, to, "迁移目标不是普通文件");
+      continue;
+    }
+    if (from === TRACKER_FROM) {
+      if (destinationKind === "file" && !sourceBytes.equals(fs.readFileSync(destination))) {
+        addConflict(plan, from, to, "项目 tracker 的新旧配置不一致，需人工处理");
+        continue;
+      }
+      const index = operations.findIndex((operation) => operation.relativePath === TRACKER_TO);
+      if (index < 0) {
+        addConflict(plan, from, to, "当前阶段缺少 tracker 目标资产");
+        continue;
+      }
+      if (destinationKind === "missing") {
+        operations[index] = {
+          ...operations[index], type: "render", desiredContent: sourceBytes,
+          desiredHash: digest(sourceBytes),
+        };
+      }
+      addRemove(plan, from, "保留项目 tracker 原内容并退出旧路径", { action: "preserve-project-config", to });
+      continue;
+    }
+    const recordedHash = managedFiles[from]?.contentHash;
+    if (!recordedHash || digest(sourceBytes) !== recordedHash) {
+      addConflict(plan, from, to, "缺少可信受管摘要或旧治理文件已被项目修改");
+      continue;
+    }
+    const desired = desiredByPath.get(to);
+    if (!desired && !RETIRED_SOURCE_ONLY.has(from)) {
+      addConflict(plan, from, to, "目标阶段未安装对应治理资产，不能静默丢弃");
+      continue;
+    }
+    if (destinationKind === "file" && (!desired || digest(fs.readFileSync(destination)) !== desired.desiredHash)) {
+      addConflict(plan, from, to, "目标路径已存在且与当前模板不一致");
+      continue;
+    }
+    addRemove(plan, from, desired ? "可信旧治理文件由新模板取代" : "可信模板专用文件退出实例", {
+      action: desired ? "replace-with-current-template" : "retire-template-only",
+      to: desired ? to : null,
+    });
+  }
+  return { desiredOperations: operations, plan, legacyFiles };
+}
+
+function combineMigrationPlans(...plans) {
+  const targetDir = plans[0]?.targetDir;
+  const combined = createMigrationPlan(targetDir);
+  for (const plan of plans) {
+    combined.operations.push(...plan.operations);
+    combined.legacy.push(...plan.legacy);
+    combined.conflicts.push(...plan.conflicts);
+    combined.unsafe.push(...plan.unsafe);
+  }
+  return combined;
+}
+
+module.exports = { prepareLayoutMigration, combineMigrationPlans, TRACKER_FROM, TRACKER_TO };

package/src/template/migration-runtime.js

@@ -28,10 +28,10 @@ const LEGACY_SKILL_MAPPINGS = [
 ];
 
 const LEGACY_FILE_MAPPINGS = [
-  ["docs/templates/prd-template.md", "docs/templates/spec-template.md"],
+  ["docs/templates/prd-template.md", ".template-spec/templates/spec-template.md"],
   [
     "docs/templates/vertical-slice-issue-template.md",
-    "docs/templates/vertical-slice-ticket-template.md",
+    ".template-spec/templates/vertical-slice-ticket-template.md",
   ],
 ];
 

package/src/template/sync-planner.js

@@ -48,7 +48,7 @@ function classifySyncOperations({
       continue;
     }
 
-    if (operation.relativePath === "docs/agents/issue-tracker.md") {
+    if (operation.relativePath === ".template-spec/agents/issue-tracker.md") {
       unchanged.push({ ...operation, reason: "project-owned-tracker-configuration" });
       continue;
     }

package/template/.agents/rules/yss-ai-skills.md

@@ -4,6 +4,6 @@ trigger: always_on
 
 # YSS UI 实现入口
 
-仅在生产前端或 YSS UI 实现影响命中时使用本入口。先按当前 Slice Implementation Contract 与 `docs/agents/yss-skill-registry.yaml` 选择最小技能集，再进入 `.agents/skills/yss-ui/SKILL.md`；完整业务页面使用 `.agents/skills/yss-ui-business-page-generation/SKILL.md`，并按任务触发读取其引用的 canonical `SKILL.md`。原型阶段使用 `yss-prototype-stage`，不得调用生产实现技能 `yss-ui`。
+仅在生产前端或 YSS UI 实现影响命中时使用本入口。先按当前 Slice Implementation Contract 与 `.template-spec/agents/yss-skill-registry.yaml` 选择最小技能集，再进入 `.agents/skills/yss-ui/SKILL.md`；完整业务页面使用 `.agents/skills/yss-ui-business-page-generation/SKILL.md`，并按任务触发读取其引用的 canonical `SKILL.md`。原型阶段使用 `yss-prototype-stage`，不得调用生产实现技能 `yss-ui`。
 
 YTable 使用真实 API：不得臆造 `request`、`search-params` 或 `actionConfig.actions`；主操作必须放入 `#toolbar-right`，只有确实需要列设置时才使用 `toolbar-config.custom`。其余组件、表单、主题、API 与导出细则以下沉技能为准。

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,30 +3,29 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "9b579c7b954c153d2347696f53123aebaccde48f",
-  "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
+  "source_revision": "15953d4f0191b06e026df285a95f4535d3243151",
+  "adaptation_ref": ".template-source/agents/strategic-design-skills-integration.md",
   "skills": [
     {
       "upstream": "prototype-review",
       "canonical": "prototype-review",
-      "upstream_hash": "6df02dd4de236a749a80efd5eba46d18be7979849af2a9af28636906ccfcb2a0"
+      "upstream_hash": "68c6e4613354ad919bab3d718739f1cc6930d8df0777d6f7db90435bdae77d52"
     },
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "6e1bcdf107d95c11faee2b988e4e0c36b8e5b76f6b40312a206b83733a96b0fc"
+      "upstream_hash": "7781df6293f381bd40781d2f6b163cf824f959624b1c34aeb9c241d6be709c89"
     },
     {
       "upstream": "yss-design-system",
       "canonical": "yss-design-system",
-      "upstream_hash": "e156229435c35827c48d3699b021e5e171ec565c2bf91cc91cbb033bf7802d7c"
+      "upstream_hash": "ae040c639056ecf2160f1231e30ac67360bd8aa1e030eac778520dd56af8068c"
     },
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "f7f765e20f4dca6aca667be03e2b9a7f2a8acc3510eefba88306961882d86ed4"
+      "upstream_hash": "6cd0ed5aa21d68cea871d0bd202beb3b28cca2981f075ad9c24667ac030118d2"
     }
   ],
-  "source_state": "committed",
-  "source_state_note": "source_revision、upstream_hash 与 gitlink 绑定同一已提交战略设计来源。"
+  "source_state": "committed"
 }

package/template/.agents/skills/.yss-skills-manifest.json

@@ -7,7 +7,7 @@
   "excluded_categories": ["library"],
   "excluded_skills": ["component-selection-imports", "java-backend-commit", "page-form-module", "page-list-module", "page-module-development", "page-skeleton", "prototype-page-acceptance", "use-table-height", "use-tree-height", "vue3-best-practices"],
   "source_revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f",
-  "adaptation_ref": "docs/agents/yss-ui-skills-integration.md",
+  "adaptation_ref": ".template-source/agents/yss-ui-skills-integration.md",
   "package": {
     "name": "@yss-ui/skills",
     "version": "1.3.9"
@@ -37,6 +37,6 @@
       { "path": ".cursor/mcp.json", "container": "mcpServers" },
       { "path": ".vscode/mcp.json", "container": "servers" }
     ],
-    "global_install_guide": "docs/user-guide/yss-ui-mcp.md"
+    "global_install_guide": ".template-spec/user-guide/yss-ui-mcp.md"
   }
 }

package/template/.agents/skills/alibaba-java-code-style/SKILL.md

@@ -20,7 +20,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 
 ## Core Priorities
 
-- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `docs/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
+- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
 - Keep names readable, English, and consistent with Java layer conventions.
 - Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
 - Make logs useful without wasting CPU, disk, or alert budget.

package/template/.agents/skills/code-review/SKILL.md

@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
-文档输出时按 `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` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
 
 ## Process
 
@@ -30,13 +30,13 @@ If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-
 Look for the originating spec, in this order:
 
 1. A spec/Ticket/contract reference supplied by the user or an upstream lifecycle review input.
-2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `.template-spec/agents/issue-tracker.md`.
 3. A spec file under `docs/`, `specs/`, or `docs/.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
 
 ### 3. Identify the standards sources
 
-Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
+Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
 For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
 
@@ -89,7 +89,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

package/template/.agents/skills/code-review/references/yss-review-standards.md

@@ -2,7 +2,7 @@
 
 本文件只服务唯一默认审查技能 `code-review`。Alibaba Java、YSS 前端 / 后端 skill 是 **Standards 轴的专项检查输入**，不是第二个通用审查 skill。
 
-权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`docs/templates/review-report-template.md`。
+权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`.template-spec/templates/review-report-template.md`。
 
 ## 1. 编译标准源
 

package/template/.agents/skills/cross-repo-implementation-routing/SKILL.md

@@ -16,12 +16,12 @@ description: Use when a Harness change or vertical slice may require work across
 
 ## Workflow
 
-1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
+1. 读取 `.template-spec/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
 4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
 5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
-6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
+6. 按 `.template-spec/templates/cross-repo-slice-template.md` 生成切片记录草案。
 7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 
 ## Routing Matrix

package/template/.agents/skills/i-have-adhd/SKILL.md

@@ -6,7 +6,7 @@ license: MIT
 
 # i-have-adhd · YSS 适配
 
-为当前产物应用 `docs/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `docs/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
+为当前产物应用 `.template-spec/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `.template-spec/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
 
 ## 触发与作用域
 

package/template/.agents/skills/i-have-adhd/references/yss-adaptation.md

@@ -14,7 +14,7 @@
 | 原因与修复直接陈述 | 区分已知现象、待验证原因和实际验证结果 |
 | 平台专属 agent 配置 | 不安装上游 Gemini 持久提示；项目 OpenAI 配置只描述当前文档配套用途 |
 
-生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `docs/process/document-writing.md` 维护；本文件只解释来源差异。
+生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `.template-spec/process/document-writing.md` 维护；本文件只解释来源差异。
 
 注册表将本技能声明为模型可调用、实例默认可发现的通用工作流 core 技能（仍只作为文档配套）；调用者以条件依赖加载。上游 `disable-model-invocation: true` 在适配版移除；作用域由本技能触发条件限定，不延续上游会话开关。
 

package/template/.agents/skills/i-have-adhd/tests/verify-integration.mjs

@@ -7,7 +7,7 @@ import {pathToFileURL} from 'node:url';
 const root=path.resolve(process.argv[2] || '.');
 const read=ref=>fs.readFileSync(path.join(root,ref),'utf8');
 const {parse}=await import(pathToFileURL(path.join(root,'scripts/vendor/yaml.mjs')));
-const registry=parse(read('docs/agents/yss-skill-registry.yaml'));
+const registry=parse(read('.template-spec/agents/yss-skill-registry.yaml'));
 const skill=registry.skills.find(x=>x.id==='i-have-adhd');
 assert.equal(skill.instance_default_discoverable,true);
 assert.equal(registry.invocation_contract.overrides['i-have-adhd'].invocation_mode,'model');
@@ -27,7 +27,7 @@ for (const target of locked.targets) {
   const skillPath=target.endsWith('/i-have-adhd')?target:path.join(target,'i-have-adhd');
   assert.equal(treeHash(path.join(root,skillPath)),locked.effectiveHash,`projection ${target}`);
 }
-for(const ref of ['docs/process/document-writing.md','docs/templates/examples/lifecycle-writing-examples.md']) {
+for(const ref of ['.template-spec/process/document-writing.md','.template-spec/templates/examples/lifecycle-writing-examples.md']) {
   assert.ok(read(ref).length);
   assert.ok(!read(ref).includes('.template-source/'));
 }

package/template/.agents/skills/implementation-repo-onboarding/SKILL.md

@@ -16,12 +16,12 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 ## Workflow
 
-1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `docs/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `docs/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
+1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `.template-spec/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `.template-spec/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
 5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
+6. 按 `.template-spec/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
 7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。需要转入已授权写入时，先按 [写范围核验](references/write-scope.md) 检查工具对象结果；只有 `.writable === true` 可写，其他形态或状态一律阻断。
 
 ## Baseline Checks

package/template/.agents/skills/llm-wiki/references/discover.md

@@ -17,9 +17,9 @@ Unless the user replaces this list with the host's single source-of-truth table:
 
 - Root authoritative files (for example `README`, `AGENTS`, `CONTEXT`, repository-identity manifest)
 - `docs/adr/`
-- `docs/process/`
-- `docs/agents/`
-- `docs/templates/`
+- `.template-spec/process/`
+- `.template-spec/agents/`
+- `.template-spec/templates/`
 - Frozen contracts the user names
 
 `full` adds only roots the user listed. It is not "everything under `docs/`".

package/template/.agents/skills/prototype-review/SKILL.md

@@ -7,7 +7,7 @@ description: Use when independently reviewing low-fidelity UI, interaction specs
 
 Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `check.prototype-reviewed` decision.
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## Trigger Boundary
 
@@ -17,9 +17,9 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 
 - Spec baseline or confirmed user stories.
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
-- State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
+- State matrix, preferably based on `.template-spec/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
-- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending Prototype Evidence schema v4 record from `docs/design/templates/prototype-evidence-template.yaml`, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending Prototype Evidence schema v4 record from `.template-spec/design/templates/prototype-evidence-template.yaml`, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
 
 ## Review Gates
 
@@ -74,4 +74,4 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - <yss-prototype-stage / return to product design>
 ```
 
-Use `docs/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.
+Use `.template-spec/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.

package/template/.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -24,7 +24,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - Root `AGENTS.md` — does it exist, and is there already an `## Agent skills` section?
 - The case-sensitive `CONTEXT.md` at the Git repository root; also detect lowercase, nested, or duplicate context files as migration problems
 - `docs/adr/` and any `src/*/docs/adr/` directories
-- `docs/agents/` — does this skill's prior output already exist?
+- `.template-spec/agents/` — does this skill's prior output already exist?
 - `docs/.scratch/` — sign that the canonical local-markdown issue tracker convention is already in use
 - `.scratch/` and `docs/requirements/tickets/` — legacy local-tracker roots; inspect them read-only for migration and never use them as new write targets
 - Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
@@ -40,7 +40,7 @@ Lead each section with the recommended answer so the user can accept it in a wor
 > Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Path resolution is configuration-first: every Local-aware skill must read the
-persisted `tracker.root` from `docs/agents/issue-tracker.md` before resolving an
+persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
 artifact path. If the field is absent, use `docs/.scratch` as the default. Do
 not infer a tracker or replace the configured root from `git remote`; the legacy
 `.scratch/` and `docs/requirements/tickets/` roots are read-only migration
@@ -54,7 +54,7 @@ The supported tracker choices in this template are exactly `local-markdown`, `gi
 
 Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
 
-Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
 
 **Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
 
@@ -73,7 +73,7 @@ If the root `CONTEXT.md` is missing, initialize it with `context_schema_version:
 Show the user a draft of:
 
 - The `## Agent skills` block to add to `AGENTS.md`
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
+- The contents of `.template-spec/agents/issue-tracker.md`, `.template-spec/agents/domain.md`, and `.template-spec/agents/triage-labels.md` (the last only when `triage` is installed)
 
 Let them edit before writing.
 
@@ -93,18 +93,18 @@ The block:
 
 ### Issue tracker
 
-[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
 
 ### Triage labels
 
-[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
 
 ### Domain docs
 
-[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See `docs/agents/domain.md`.
+[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See `.template-spec/agents/domain.md`.
 ```
 
-Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+Include the `### Triage labels` sub-block, and write `.template-spec/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
 
 Then write the docs files using the seed templates in this skill folder as a starting point:
 
@@ -114,8 +114,8 @@ Then write the docs files using the seed templates in this skill folder as a sta
 - [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
 - [domain.md](./domain.md) — domain doc consumer rules + layout
 
-For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `docs/agents/issue-tracker.md`.
+For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.
 
 ### 5. Done
 
-Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `.template-spec/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/template/.agents/skills/triage/SKILL.md

@@ -30,7 +30,7 @@ Two categories:
 - `bug` — something is broken
 - `enhancement` — new feature or improvement
 
-五态语义由 `docs/agents/triage-labels.md` 定义：
+五态语义由 `.template-spec/agents/triage-labels.md` 定义：
 
 - `needs-triage` — maintainer needs to evaluate
 - `needs-info` — waiting on reporter for more information

package/template/.agents/skills/yss-application/references/profiles/layered-mvc-service.md

@@ -1,3 +1,3 @@
 # layered-mvc-service
 
-先读仓库 `docs/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `service` 的 command/query/result/service 包；事务与业务行为通过公开用例 seam 做 behavior-tdd。调用 Repository/Adapter；不得生成 Domain Gateway 或引用 client DTO、Spring MVC、生产驱动。需要 HTTP 协议变更时返回 new_impacts，由 Web 工作单元处理。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `service` 的 command/query/result/service 包；事务与业务行为通过公开用例 seam 做 behavior-tdd。调用 Repository/Adapter；不得生成 Domain Gateway 或引用 client DTO、Spring MVC、生产驱动。需要 HTTP 协议变更时返回 new_impacts，由 Web 工作单元处理。

package/template/.agents/skills/yss-application/references/profiles/mvc-data-analysis-v1.md

@@ -1,3 +1,3 @@
 # mvc-data-analysis-v1
 
-先读仓库 `docs/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `core` 的 command/query/result/service 包；core 是薄应用层，拥有事务与内部模型，不依赖 client/server。读取/计算/导出编排不能自动扩大 SQL 或 API 合同；数据行为采用 behavior-tdd。不要套用 DDD application-layer-guide。
+先读仓库 `.template-spec/agents/backend-architecture-profiles.md` 的 MVC 约定。写入 `core` 的 command/query/result/service 包；core 是薄应用层，拥有事务与内部模型，不依赖 client/server。读取/计算/导出编排不能自动扩大 SQL 或 API 合同；数据行为采用 behavior-tdd。不要套用 DDD application-layer-guide。

package/template/.agents/skills/yss-backend-spec-review/SKILL.md

@@ -35,7 +35,7 @@ description: 审计既有 Java 后端工程对 YSS 技能规范和已批准业
 
 ## 输出与完成依据
 
-复用 `docs/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
+复用 `.template-spec/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
 
 ## 必须评估、适用必审
 

package/template/.agents/skills/yss-backend-spec-review/references/check-inputs.md

@@ -12,7 +12,7 @@
 | wire / 参数 / 错误 | `yss-dto`、`yss-validation`、`yss-exception` | 真实响应/分页/错误协议、Bean Validation、命名空间、敏感字段与冻结 OpenAPI 一致 |
 | 映射 / 注解处理 | `mapstruct`、`lombok` | 显式字段策略、处理器版本、领域工厂重建；不强迫聚合开放 setter |
 | 实际组件调用 | Registry 中对应组件 Skill 与精确平台源码索引 | cache、userinfo、audit、ID、Excel、resilience 等按能力加载；不因“审查全面”要求安装不用的组件 |
-| 工程和平台 | `docs/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
+| 工程和平台 | `.template-spec/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
 
 每个后端范围显式评估 `yss-web-controller` / `yss-dto` / `yss-domain` / `yss-application` / `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
 

package/template/.agents/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -32,7 +32,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
-版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
 
 ## 优先流程
 
@@ -74,7 +74,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision（新建 v2；历史 v1 只读兼容，准备与迁移见 `.template-spec/process/contract-reading.md`） 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
 - DDD 固定 `target-domain-model`、`mybatis-plus`、H2 验证、`web` DTO、`yss-internal`；平台与 Validation 命名空间由共享清单约束。普通 MyBatis、独立 client module、client-in-domain 和其他旧架构仍为 `unsupported`。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 当前合同 freshness、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -209,7 +209,7 @@ export class ScaffoldGenerator {
     if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
     if (contract.schema_version !== 4) fail(`unsupported: 后端新生成只接受 Project Scaffold Contract v4，收到 v${contract.schema_version}`);
     if (contract.kind !== "project-scaffold-contract" || contract.delivery_role !== "backend" || contract.scaffold_kind !== "backend-ddd") fail("schema v4 合同必须绑定 backend/backend-ddd");
-    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, "docs/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
+    validateJsonSchema(contract, path.join(REPOSITORY_ROOT, ".template-spec/process/schemas/project-scaffold-contract.schema.json"), { label: "Project Scaffold Contract v4" });
     const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--compiler-draft-ref", this.options.compilerDraftRef], ["--persisted-ref", this.options.persistedRef]];
     const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
     if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);