create-yss-spec 3.5.0 → 3.5.2

package/README.md

@@ -34,7 +34,7 @@ CLI 在规划和写入前检查模板家族身份，当前主路线识别：
 - `create-yss-harness-backend` / `.yss-harness-backend.json`
 - `create-yss-harness-frontend` / `.yss-harness-frontend.json`
 
-`docs/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
+`.template-spec/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
 
 旧 `create-yss-harness-dev` / `.yss-harness-dev.json` 仍会被识别并拒绝跨家族接管；既有实例按原固定版本维护，不再作为新项目入口。战略、后端和前端分别使用专职 CLI，任何家族都不做跨家族原地迁移。
 
@@ -183,4 +183,8 @@ npm pack --dry-run
 - [Ownership Policy v1](docs/implementation/ownership-policy-v1.md)
 - [Lifecycle Policies v1](docs/implementation/lifecycle-policies-v1.md)
 - [Programmatic API v1](docs/implementation/programmatic-api-v1.md)
-- [完整中文使用手册](docs/user-guide/create-yss-spec-cli-guide.md)
+- [完整中文使用手册](.template-spec/user-guide/create-yss-spec-cli-guide.md)
+
+## 治理目录迁移
+
+新实例将分发治理资产安装到 `.template-spec/`，项目规格产物放在 `docs/`。已有实例只有显式运行 `sync --migrate-layout --plan` 审阅后，才运行 `sync --migrate-layout --apply`；`attach` 同样支持该开关。迁移保留项目 tracker 配置，缺少可信摘要、旧文件被修改或目标路径冲突时阻断。普通 sync 不自动改变旧实例目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/api/_sync-service.js

@@ -12,6 +12,7 @@ const { collectGitRoots, gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildSyncPlanFromRuntime } = require("../template/sync-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { prepareLayoutMigration, combineMigrationPlans } = require("../template/layout-migration");
 const { classifyRemovedFiles } = require("../template/prune-planner");
 const { decorateMetadataOwnership } = require("../template/ownership-metadata");
 const { decorateMetadataLifecycle } = require("../template/lifecycle-metadata");
@@ -73,7 +74,7 @@ function affectedPathsForMigration(migrationPlan) {
   );
 }
 
-function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd() } = {}) {
+function buildSyncContext({ targetDir = ".", force = false, migrateLayout = false, cwd = process.cwd() } = {}) {
   const snapshot = readTemplateSnapshot();
   assertBundledFamily(snapshot);
   const resolvedTargetDir = normalizeTargetDir(targetDir, cwd);
@@ -84,17 +85,24 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
 
   const { metadata } = loadTemplateMetadata(resolvedTargetDir);
   const identity = readTargetIdentity(resolvedTargetDir);
-  const desiredOperations = buildSyncDesiredOperations(
+  const baseDesiredOperations = buildSyncDesiredOperations(
     resolvedTargetDir,
     metadata,
     identity,
     snapshot,
   );
-  const migrationPlan = buildLegacyMigrationPlan(
+  const layout = prepareLayoutMigration({
+    targetDir: resolvedTargetDir,
+    desiredOperations: baseDesiredOperations,
+    managedFiles: metadata.managedFiles || {},
+    explicit: migrateLayout,
+  });
+  const desiredOperations = layout.desiredOperations;
+  const migrationPlan = combineMigrationPlans(layout.plan, buildLegacyMigrationPlan(
     resolvedTargetDir,
     desiredOperations,
     { checkFlatTickets: false },
-  );
+  ));
   const warning = gitDirtyWarning(resolvedTargetDir);
 
   const { classified: syncPlan, plan } = buildSyncPlanFromRuntime({
@@ -110,7 +118,9 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     getFileHash: (operation) => fileHash(operation.targetPath),
   });
   const removedPlan = classifyRemovedFiles({
-    removed: syncPlan.removed.filter((relativePath) => relativePath !== "README.md"),
+    removed: syncPlan.removed.filter((relativePath) =>
+      relativePath !== "README.md" &&
+      !layout.plan.operations.some((operation) => operation.kind === "remove" && operation.path === relativePath)),
     managedFiles: metadata.managedFiles || {},
     getPathKind: (relativePath) => pathKind(targetPath(resolvedTargetDir, relativePath)),
     getFileHash: (relativePath) => fileHash(targetPath(resolvedTargetDir, relativePath)),
@@ -142,6 +152,7 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     identity,
     desiredOperations,
     migrationPlan,
+    migrateLayout,
     warning,
     syncPlan,
     plan,
@@ -261,8 +272,17 @@ function applySyncContext(context, { force = false, prune = false } = {}) {
           throw new Error(`${relativePath}: 待清理文件在规划后已变化，请重新运行 sync`);
         }
       }
-      const currentMigration = buildLegacyMigrationPlan(targetDir, desiredOperations, { checkFlatTickets: false });
+      const currentLayout = prepareLayoutMigration({
+        targetDir,
+        desiredOperations: buildSyncDesiredOperations(targetDir, metadata, readTargetIdentity(targetDir), context.snapshot),
+        managedFiles: metadata.managedFiles || {},
+        explicit: context.migrateLayout,
+      });
+      const currentMigration = combineMigrationPlans(currentLayout.plan,
+        buildLegacyMigrationPlan(targetDir, desiredOperations, { checkFlatTickets: false }));
       if (!isDeepStrictEqual(currentMigration.operations, migrationPlan.operations) ||
+          !isDeepStrictEqual(currentLayout.desiredOperations.map((operation) => [operation.relativePath, operation.desiredHash]),
+            desiredOperations.map((operation) => [operation.relativePath, operation.desiredHash])) ||
           currentMigration.unsafe.length || currentMigration.conflicts.length) {
         throw new Error("旧路径迁移在规划后已变化，请重新运行 sync");
       }
@@ -283,6 +303,11 @@ function applySyncContext(context, { force = false, prune = false } = {}) {
       const nextMetadata = decorateMetadataLifecycle(
         decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan, { snapshot: context.snapshot })),
       );
+      for (const operation of context.migrationPlan.operations) {
+        if (operation.kind === "remove" && operation.path.startsWith("docs/")) {
+          delete nextMetadata.managedFiles[operation.path];
+        }
+      }
       if (!isDeepStrictEqual({ ...nextMetadata, lastSyncedAt: metadata.lastSyncedAt }, metadata)) {
         writeTemplateMetadata(targetDir, nextMetadata, transaction);
       }

package/src/cli/args.js

@@ -39,6 +39,8 @@ function parseArgs(argv = []) {
       options.force = true;
     } else if (current === "--prune") {
       options.prune = true;
+    } else if (current === "--migrate-layout") {
+      options.migrateLayout = true;
     } else if (current === "--git-init") {
       options.gitInit = true;
     } else if (current === "--include-example-docs") {

package/src/cli/help.js

@@ -36,6 +36,7 @@ OPTIONS
                                      attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
                                      update：即使已是最新时仍重新安装；npx / 源码目录仍不覆盖
   --prune                            sync：备份并删除与旧受管基线一致的退出分发文件
+  --migrate-layout                   attach/sync：显式迁移旧 docs 治理布局，冲突时停止并保留备份
   --git-init                         初始化完成后执行 git init
   --include-example-docs             显式保留示例文档（默认关闭）
   --no-example-docs                  不生成示例文档
@@ -66,6 +67,8 @@ EXAMPLES
   $ npx create-yss-spec@latest sync
   $ npx create-yss-spec@latest sync --dry-run
   $ npx create-yss-spec@latest sync --plan
+  $ npx create-yss-spec@latest sync --plan --migrate-layout
+  $ npx create-yss-spec@latest sync --migrate-layout
   $ npx create-yss-spec@latest sync --json
   $ npx create-yss-spec@latest diff
   $ npx create-yss-spec@latest diff --json
@@ -86,7 +89,7 @@ EXAMPLES
 
 LEARN MORE
   仓库 README：https://github.com/iloveZzz/create-yss-spec#readme
-  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md
+  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/.template-spec/user-guide/create-yss-spec-cli-guide.md
   模板仓库：https://github.com/iloveZzz/yss-spec-project-template
 `;
 }

package/src/commands/attach.js

@@ -13,6 +13,7 @@ const { gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildAttachPlanFromRuntime } = require("../template/attach-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { prepareLayoutMigration, combineMigrationPlans } = require("../template/layout-migration");
 const {
   PACKAGE_ROOT,
   BUNDLED_TEMPLATE_ROOT,
@@ -190,14 +191,19 @@ async function runAttach(argv = []) {
 
   const variables = attachVariables(options);
   const identity = readTargetIdentity(targetDir);
-  const desiredOperations = buildAttachDesiredOperations(
+  const baseDesiredOperations = buildAttachDesiredOperations(
     targetDir,
     variables,
     identity,
   );
-  const migrationPlan = buildLegacyMigrationPlan(targetDir, desiredOperations, {
-    checkFlatTickets: true,
+  const layout = prepareLayoutMigration({
+    targetDir, desiredOperations: baseDesiredOperations,
+    explicit: Boolean(options.migrateLayout),
   });
+  const desiredOperations = layout.desiredOperations;
+  const migrationPlan = combineMigrationPlans(layout.plan, buildLegacyMigrationPlan(targetDir, desiredOperations, {
+    checkFlatTickets: true,
+  }));
   const warning = gitDirtyWarning(targetDir);
 
   const { classified: plan } = buildAttachPlanFromRuntime({

package/src/commands/diff.js

@@ -8,6 +8,7 @@ const { projectDiff } = require("../api/project-diff");
 function runDiff(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   const plan = projectDiff({
     targetDir: options.targetDir || ".",
     force: Boolean(options.force),

package/src/commands/doctor.js

@@ -394,6 +394,7 @@ function renderDoctorText(report) {
 function runDoctor(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   const targetDir = normalizeTargetDir(options.targetDir);
   const report = buildDoctorReport(targetDir);
 

package/src/commands/init.js

@@ -121,6 +121,7 @@ function parentDirectoryOperations(desiredOperations, targetDir) {
 async function runInit(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   if (options.help) {
     printHelp(PACKAGE_MANIFEST.version);
     return;
@@ -195,7 +196,7 @@ async function runInit(argv = []) {
       ? "2. 运行 git status 检查初始化结果"
       : "2. 如需版本管理，可执行 git init",
   );
-  console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
+  console.log("3. 检查 AGENTS.md、README 和 .template-spec 目录是否符合预期；docs 将在首次项目产出时创建");
 }
 
 module.exports = {

package/src/commands/sync.js

@@ -88,6 +88,7 @@ function runSync(argv = []) {
   const context = buildSyncContext({
     targetDir: options.targetDir || ".",
     force: Boolean(options.force),
+    migrateLayout: Boolean(options.migrateLayout),
   });
 
   if (options.json) {

package/src/family-identity.js

@@ -36,7 +36,7 @@ const FAMILIES = [
   },
 ];
 
-const PROFILE_PATH = "docs/process/harness-profile.yaml";
+const PROFILE_PATH = ".template-spec/process/harness-profile.yaml";
 
 function statOrMissing(file) {
   try {

package/src/template/asset-runtime.js

@@ -7,39 +7,40 @@ const ASSET_PROFILE = "stage-selective";
 const INITIAL_STAGES = ["stage.entry-triage", "stage.plan"];
 const TEMPLATE_ONLY_IMPORTS = new Set(["scripts/lib/maintenance-intensity.mjs"]);
 const RENDERED_SKILL_SCRIPTS = Object.freeze({ "yss-design-system": ["scripts/design-md"] });
-const SKILL_ASSET_PREFIXES = Object.freeze({ "yss-design-system": ["docs/design/tokens/"] });
+const SKILL_ASSET_PREFIXES = Object.freeze({ "yss-design-system": [".template-spec/design/tokens/"] });
 
 // Paths here are the entry points for each stage. Relative JavaScript imports
 // are included by moduleClosure; files named by an explicitly installed Skill
 // are included by skillReferences. The CLI snapshot retains every source file.
 const COMMON = {
   files: [
-    "docs/agents/yss-skill-registry.yaml",
-    "docs/agents/digital-human-roles.yaml",
-    "docs/agents/digital-human-roles.md",
-    "docs/agents/issue-tracker.md",
-    "docs/agents/triage-labels.md",
-    "docs/agents/domain.md",
-    "docs/process/lifecycle-registry.yaml",
-    "docs/process/lifecycle-registry-baseline.json",
-    "docs/process/lifecycle-artifact-map.md",
-    "docs/process/harness-process-tailoring.md",
-    "docs/process/document-writing.md",
-    "docs/process/contract-reading.md",
-    "docs/process/stage-tracking.md",
-    "docs/process/schemas/context-reconciliation.schema.json",
-    "docs/process/schemas/digital-human-task-package.schema.json",
-    "docs/process/schemas/lifecycle-checkpoint.schema.json",
-    "docs/process/schemas/stage-tracking.schema.json",
-    "docs/process/schemas/user-decision.schema.json",
-    "docs/process/templates/context-reconciliation-template.yaml",
-    "docs/process/templates/lifecycle-checkpoint-template.yaml",
-    "docs/process/templates/stage-checkpoint-template.md",
-    "docs/process/templates/user-decision-template.yaml",
-    "docs/templates/local-parent-ticket-template.md",
-    "docs/templates/approval-record-template.yaml",
-    "docs/templates/review-report-template.md",
-    "docs/user-guide/用户手册.md",
+    ".template-spec/agents/yss-skill-registry.yaml",
+    ".template-spec/agents/digital-human-roles.yaml",
+    ".template-spec/agents/digital-human-roles.md",
+    ".template-spec/agents/issue-tracker.md",
+    ".template-spec/agents/triage-labels.md",
+    ".template-spec/agents/domain.md",
+    ".template-spec/process/lifecycle-registry.yaml",
+    ".template-spec/process/lifecycle-registry-baseline.json",
+    ".template-spec/process/lifecycle-registry-baseline-v1.json",
+    ".template-spec/process/lifecycle-artifact-map.md",
+    ".template-spec/process/harness-process-tailoring.md",
+    ".template-spec/process/document-writing.md",
+    ".template-spec/process/contract-reading.md",
+    ".template-spec/process/stage-tracking.md",
+    ".template-spec/process/schemas/context-reconciliation.schema.json",
+    ".template-spec/process/schemas/digital-human-task-package.schema.json",
+    ".template-spec/process/schemas/lifecycle-checkpoint.schema.json",
+    ".template-spec/process/schemas/stage-tracking.schema.json",
+    ".template-spec/process/schemas/user-decision.schema.json",
+    ".template-spec/process/templates/context-reconciliation-template.yaml",
+    ".template-spec/process/templates/lifecycle-checkpoint-template.yaml",
+    ".template-spec/process/templates/stage-checkpoint-template.md",
+    ".template-spec/process/templates/user-decision-template.yaml",
+    ".template-spec/templates/local-parent-ticket-template.md",
+    ".template-spec/templates/approval-record-template.yaml",
+    ".template-spec/templates/review-report-template.md",
+    ".template-spec/user-guide/用户手册.md",
   ],
   scripts: [
     "scripts/verify-project-instance",
@@ -62,35 +63,35 @@ const COMMON = {
 const STAGES = Object.freeze({
   "stage.entry-triage": { files: [], scripts: [], skills: [] },
   "stage.plan": {
-    prefixes: ["docs/plan/"],
-    files: ["docs/process/plan-migration.md"],
+    prefixes: [".template-spec/plan/"],
+    files: [".template-spec/process/plan-migration.md"],
     scripts: ["scripts/verify-plan-spec-entry"],
     skills: [],
   },
   "stage.spec-architecture": {
     files: [
-      "docs/templates/spec-template.md",
-      "docs/templates/spec-delta-template.md",
-      "docs/architecture/templates/business-architecture-template.md",
-      "docs/architecture/templates/functional-architecture-template.md",
+      ".template-spec/templates/spec-template.md",
+      ".template-spec/templates/spec-delta-template.md",
+      ".template-spec/architecture/templates/business-architecture-template.md",
+      ".template-spec/architecture/templates/functional-architecture-template.md",
     ],
     scripts: [],
     skills: [],
   },
   "stage.product-design": {
-    prefixes: ["docs/design/"],
+    prefixes: [".template-spec/design/"],
     files: [],
     scripts: ["scripts/design-md"],
     skills: ["yss-prototype-stage"],
   },
   "stage.system-data-engineering": {
-    prefixes: ["docs/engineering/"],
+    prefixes: [".template-spec/engineering/"],
     files: [
-      "docs/process/implementation-repo-integration.md",
-      "docs/process/existing-backend-architecture.md",
-      "docs/process/existing-ui-baseline.md",
-      "docs/process/frontend-backend-delivery.md",
-      "docs/templates/implementation-repo-registry-template.md",
+      ".template-spec/process/implementation-repo-integration.md",
+      ".template-spec/process/existing-backend-architecture.md",
+      ".template-spec/process/existing-ui-baseline.md",
+      ".template-spec/process/frontend-backend-delivery.md",
+      ".template-spec/templates/implementation-repo-registry-template.md",
     ],
     scripts: [
       "scripts/backend-platforms",
@@ -101,21 +102,21 @@ const STAGES = Object.freeze({
     skills: ["yss-implementation-contract-compiler"],
   },
   "stage.ticket-formalization": {
-    files: ["docs/templates/vertical-slice-ticket-template.md", "docs/templates/cross-repo-slice-template.md"],
+    files: [".template-spec/templates/vertical-slice-ticket-template.md", ".template-spec/templates/cross-repo-slice-template.md"],
     scripts: ["scripts/dispatch-slice-task", "scripts/slice-contract"],
     skills: [],
   },
   "stage.vertical-slice-implementation": {
-    files: ["docs/templates/verification-record-template.md"],
+    files: [".template-spec/templates/verification-record-template.md"],
     scripts: ["scripts/implementation-path-policy", "scripts/complete-backend-delivery"],
     skills: [],
   },
   "stage.verification-release-retrospective": {
     files: [
-      "docs/process/delivery-preflight.md",
-      "docs/templates/release-note-template.md",
-      "docs/templates/retro-report-template.md",
-      "docs/templates/review-bundle-template.yaml",
+      ".template-spec/process/delivery-preflight.md",
+      ".template-spec/templates/release-note-template.md",
+      ".template-spec/templates/retro-report-template.md",
+      ".template-spec/templates/review-bundle-template.yaml",
     ],
     scripts: ["scripts/preflight-delivery"],
     skills: [],
@@ -181,7 +182,7 @@ function skillReferences(root, result, skillId, selectedSkills) {
       if (entry.isDirectory()) visit(file);
       else if (entry.isFile() && /\.(?:md|yaml|json)$/.test(entry.name)) {
         const source = fs.readFileSync(file, "utf8");
-        for (const match of source.matchAll(/(?:docs|scripts)\/[\p{L}\p{N}_.\/-]+/gu)) {
+        for (const match of source.matchAll(/(?:\.template-spec|scripts)\/[\p{L}\p{N}_.\/-]+/gu)) {
           const ref = match[0].replace(/[.,;]+$/, "");
           if (!fs.existsSync(path.join(root, ref)) || !fs.statSync(path.join(root, ref)).isFile()) continue;
           if (ref.startsWith("scripts/")) moduleClosure(root, result, ref, selectedSkills);
@@ -197,14 +198,21 @@ function skillReferences(root, result, skillId, selectedSkills) {
 
 function assetPaths(root, distribution) {
   if (distribution.mode !== "selected" || distribution.assetProfile !== ASSET_PROFILE) return null;
-  const lifecycle = fs.readFileSync(sourceFile(root, "docs/process/lifecycle-registry.yaml"), "utf8");
+  const lifecycle = fs.readFileSync(sourceFile(root, ".template-spec/process/lifecycle-registry.yaml"), "utf8");
   const stageIds = [...lifecycle.matchAll(/^  - id: (stage\.[a-z0-9-]+)\s*$/gm)].map((match) => match[1]).sort();
   if (JSON.stringify(stageIds) !== JSON.stringify(Object.keys(STAGES).sort())) {
     throw new Error("CLI 阶段资产映射与生命周期注册表阶段 ID 不一致");
   }
   const result = new Set();
   const selectedSkills = new Set(distribution.installedSkills);
-  for (const ref of COMMON.files) addFile(root, result, ref);
+  for (const ref of COMMON.files) {
+    if (ref === ".template-spec/process/lifecycle-registry-baseline-v1.json" &&
+        !fs.existsSync(path.join(root, ref))) {
+      const baseline = JSON.parse(fs.readFileSync(sourceFile(root, ".template-spec/process/lifecycle-registry-baseline.json"), "utf8"));
+      if (baseline.schema_version === 1) continue;
+    }
+    addFile(root, result, ref);
+  }
   for (const ref of COMMON.scripts) moduleClosure(root, result, ref, selectedSkills);
   for (const stage of distribution.installedStages) {
     const bundle = STAGES[stage];

package/src/template/attach-planner.js

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

package/src/template/distribution-runtime.js

@@ -6,16 +6,16 @@ const { ASSET_PROFILE, INITIAL_STAGES } = require("./asset-runtime");
 
 const RUNTIMES = Object.freeze({ codex: ".codex/skills", cursor: ".cursor/skills", pi: ".pi/skills" });
 const OMIT_INSTANCE_PATHS = [
-  "docs/process/github-workflows.md",
-  "docs/process/harness-executive-blueprint.md",
-  "docs/process/PDCA-SCRUM.md",
-  "docs/design/preview.html", "docs/design/preview.css", "docs/design/preview.js", "docs/design/preview-dark.html",
-  "docs/design/facts/antdv-next", "docs/user-guide/设备借用贯穿案例.md",
-  "docs/design/design-system-sync.yaml",
+  ".template-source/process/github-workflows.md",
+  ".template-spec/process/harness-executive-blueprint.md",
+  ".template-spec/process/PDCA-SCRUM.md",
+  ".template-spec/design/preview.html", ".template-spec/design/preview.css", ".template-spec/design/preview.js", ".template-spec/design/preview-dark.html",
+  ".template-spec/design/facts/antdv-next", ".template-spec/user-guide/设备借用贯穿案例.md",
+  ".template-spec/design/design-system-sync.yaml",
 ];
 
 function readDistributionRegistry(templateRoot) {
-  const registry = fs.readFileSync(path.join(templateRoot, "docs/agents/yss-skill-registry.yaml"), "utf8");
+  const registry = fs.readFileSync(path.join(templateRoot, ".template-spec/agents/yss-skill-registry.yaml"), "utf8");
   const match = registry.match(/^instance_distribution:\n([\s\S]*?)(?=^[^\s#][^\n]*:\s*$)/m);
   if (!match) throw new Error("Skill 注册表缺少 instance_distribution");
   const initial = match[1].match(/^  initial_skills: \[([^\]]+)\]/m);
@@ -50,7 +50,7 @@ function isIncludedInstancePath(relativePath, distribution) {
   if (relativePath === ".cursorrules" && !distribution.runtimes.includes("cursor")) return false;
   if (OMIT_INSTANCE_PATHS.some((excluded) => relativePath === excluded || relativePath.startsWith(`${excluded}/`))) return false;
   if (distribution.assetProfile === ASSET_PROFILE &&
-      (relativePath.startsWith("docs/") || relativePath.startsWith("scripts/") || relativePath.startsWith(".vscode/"))) {
+      (relativePath.startsWith(".template-spec/") || relativePath.startsWith("scripts/") || relativePath.startsWith(".vscode/"))) {
     return distribution.assetPaths.has(relativePath) ||
       [...distribution.assetPaths].some((ref) => ref.startsWith(`${relativePath}/`));
   }
@@ -103,7 +103,7 @@ function renderInstanceSkillSupplyChain(sourceText) {
 function renderInstanceDesignSkillFile(sourceText) {
   return sourceText
     .replaceAll("node .template-source/tooling/node/scripts/design-md.mjs", "scripts/design-md")
-    .replace("运行前先更新 `docs/design/design-system-sync.yaml` 的规范源摘要。", "项目实例无需模板间的 design-system-sync 摘要。")
+    .replace("运行前先更新 `.template-spec/design/design-system-sync.yaml` 的规范源摘要。", "项目实例无需模板间的 design-system-sync 摘要。")
     .replace("修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 →", "修改根 DESIGN.md →");
 }
 

package/src/template/instance-runtime.js

@@ -147,22 +147,22 @@ function renderTemplateFile(relativePath, content, variables) {
   if (relativePath === "skills-lock.json") return selectedSkillLock(content, distribution);
   if (relativePath === "scripts/lib/skill-supply-chain.mjs" && distribution.mode === "selected") return renderInstanceSkillSupplyChain(content);
   if (distribution.mode === "selected" && /^\.(agents|codex|cursor|pi)\/skills\/yss-design-system\/(SKILL\.md|references\/data-quality-theme\.md)$/.test(relativePath)) return renderInstanceDesignSkillFile(content);
-  if (relativePath === "docs/engineering/backend-platforms.json" && distribution.mode === "selected") {
+  if (relativePath === ".template-spec/engineering/backend-platforms.json" && distribution.mode === "selected") {
     return content.replaceAll(".template-source/evidence/maintenance/2026-09-18-yss-backend-components/aliyun-artifact-resolution.json", "docs/engineering/evidence/aliyun-artifact-resolution.json");
   }
-  if (relativePath === "docs/agents/backend-architecture-profiles.md" && distribution.mode === "selected") {
+  if (relativePath === ".template-spec/agents/backend-architecture-profiles.md" && distribution.mode === "selected") {
     return content.replace(/；依据见 `\.template-source\/evidence\/maintenance\/2026-09-12-existing-project-delivery\/maven-adapters-04\.json`/, "；适配验证证据保留在模板源，项目实例须对自身工程重新验证");
   }
-  if (relativePath === "docs/user-guide/用户手册.md" && distribution.mode === "selected") {
+  if (relativePath === ".template-spec/user-guide/用户手册.md" && distribution.mode === "selected") {
     if (distribution.assetProfile !== ASSET_PROFILE) {
       return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n阶段派发前，由 Agent 运行 \`create-yss-spec skills ensure <skill-id...> --plan\` 核对依赖，再运行 \`--apply\` 安装。旧实例继续沿用既有文件分发范围；增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；升级 CLI 后先运行 \`create-yss-spec sync\`。\n\n项目校验运行 \`scripts/verify-project-instance\`。\n`;
     }
     return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n初始化安装分诊与 Plan 入口资产、三项入口 Skill 与所选 Agent 平台。进入后续阶段前，运行 \`create-yss-spec assets ensure <stage-id> --plan\` 核对文件，再运行 \`--apply\` 原子安装；专项 Skill 使用 \`create-yss-spec skills ensure <skill-id...> --plan/--apply\`，会补齐该 Skill 引用的实例文件。增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；升级 CLI 后先运行 \`create-yss-spec sync\`。\n\n项目校验运行 \`scripts/verify-project-instance\`；实例 CI 应执行该命令和项目实际的构建、测试。\n`;
   }
-  if (distribution.mode === "selected" && relativePath === "docs/design/README.md") {
+  if (distribution.mode === "selected" && relativePath === ".template-spec/design/README.md") {
     return content.replace(/^.*design-system-sync\.yaml.*\n/m, "");
   }
-  if (distribution.mode === "selected" && relativePath.startsWith("docs/user-guide/") && relativePath.endsWith(".md")) {
+  if (distribution.mode === "selected" && relativePath.startsWith(".template-spec/user-guide/") && relativePath.endsWith(".md")) {
     return content.replaceAll("[设备借用贯穿案例](设备借用贯穿案例.md)", "[项目用户手册](用户手册.md)")
       .replaceAll("本仓是 `template-source`", "模板源是 `template-source`");
   }
@@ -186,10 +186,10 @@ function renderTemplateFile(relativePath, content, variables) {
       );
     if (distribution.mode !== "selected") return rendered;
     const base = rendered.replace(/## 4\. \`template-source\` 模板维护路由[\s\S]*?(?=## 5\.)/, "")
-      .replace(/\| 影响面、\`not-applicable\`、模板维护强度 \|[^\n]*\n/, "| 影响面与 `not-applicable` | `docs/process/harness-process-tailoring.md` |\n");
+      .replace(/\| 影响面、\`not-applicable\`、模板维护强度 \|[^\n]*\n/, "| 影响面与 `not-applicable` | `.template-spec/process/harness-process-tailoring.md` |\n");
     const guidance = distribution.assetProfile === ASSET_PROFILE
-      ? "## 按需阶段资产与 Skill\n\n进入后续生命周期阶段前，运行 `create-yss-spec assets ensure <stage-id> --plan` 查看完整依赖，核对后运行 `--apply`。专项任务根据 docs/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。缺少阶段资产时先补装，不以缺文件推定门禁不适用。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n"
-      : "## 按需 Skill\n\n此实例继续沿用原文件分发范围。阶段派发或专项任务开始前，根据 docs/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n";
+      ? "## 按需阶段资产与 Skill\n\n进入后续生命周期阶段前，运行 `create-yss-spec assets ensure <stage-id> --plan` 查看完整依赖，核对后运行 `--apply`。专项任务根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。缺少阶段资产时先补装，不以缺文件推定门禁不适用。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n"
+      : "## 按需 Skill\n\n此实例继续沿用原文件分发范围。阶段派发或专项任务开始前，根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n";
     return `${base}\n${guidance}`;
   }
 
@@ -197,7 +197,7 @@ function renderTemplateFile(relativePath, content, variables) {
     const assetGuidance = distribution.assetProfile === ASSET_PROFILE
       ? "后续阶段先运行 `create-yss-spec assets ensure <stage-id> --plan` 核对依赖，再运行 `--apply`；专项 Skill 使用 `create-yss-spec skills ensure <skill-id> --plan/--apply`。"
       : "专项 Skill 使用 `create-yss-spec skills ensure <skill-id> --plan/--apply`。";
-    return `# ${variables.projectName}\n\n本仓库用于管理 ${variables.businessDomain} 的研发资产。\n\n- 默认 Issue Tracker：${variables.issueTracker}\n- Agent 平台：${distribution.mode === "selected" ? distribution.runtimes.join(", ") : "legacy-all"}\n- 协作入口：[AGENTS.md](./AGENTS.md)\n- 业务词汇：[CONTEXT.md](./CONTEXT.md)\n- 用户指南：[docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md)\n\n项目校验：\`scripts/verify-project-instance\`。${assetGuidance}\n`;
+    return `# ${variables.projectName}\n\n本仓库用于管理 ${variables.businessDomain} 的研发资产。\n\n- 默认 Issue Tracker：${variables.issueTracker}\n- Agent 平台：${distribution.mode === "selected" ? distribution.runtimes.join(", ") : "legacy-all"}\n- 协作入口：[AGENTS.md](./AGENTS.md)\n- 业务词汇：[CONTEXT.md](./CONTEXT.md)\n- 用户指南：[.template-spec/user-guide/用户手册.md](./.template-spec/user-guide/用户手册.md)\n\n项目校验：\`scripts/verify-project-instance\`。${assetGuidance}\n`;
   }
 
   if (relativePath === ".gitignore") return extractManagedGitignoreBlock(content);