create-yss-spec 3.4.10 → 3.5.2

package/src/template/distribution-runtime.js

@@ -0,0 +1,165 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+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 = [
+  ".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, ".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);
+  if (!initial) throw new Error("Skill 注册表缺少 initial_skills");
+  return {
+    initialSkills: initial[1].split(",").map((item) => item.trim()),
+    text: registry,
+  };
+}
+
+function assertRuntime(runtime) {
+  if (!Object.hasOwn(RUNTIMES, runtime)) throw new Error(`--agent-runtime 必须是 ${Object.keys(RUNTIMES).join("| ")}`);
+  return runtime;
+}
+
+function distributionForVariables(variables, templateRoot) {
+  if (variables.distribution?.mode === "legacy-all") return { mode: "legacy-all" };
+  if (variables.distribution?.mode === "selected") return variables.distribution;
+  const runtime = assertRuntime(variables.agentRuntime);
+  return {
+    mode: "selected",
+    runtimes: [runtime],
+    installedSkills: [...readDistributionRegistry(templateRoot).initialSkills],
+    assetProfile: ASSET_PROFILE,
+    installedStages: [...INITIAL_STAGES],
+    resourceSkills: [],
+  };
+}
+
+function isIncludedInstancePath(relativePath, distribution) {
+  if (distribution.mode === "legacy-all") return true;
+  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(".template-spec/") || relativePath.startsWith("scripts/") || relativePath.startsWith(".vscode/"))) {
+    return distribution.assetPaths.has(relativePath) ||
+      [...distribution.assetPaths].some((ref) => ref.startsWith(`${relativePath}/`));
+  }
+  for (const [runtime, root] of Object.entries(RUNTIMES)) {
+    const runtimeRoot = root.split("/")[0];
+    if (relativePath === runtimeRoot || relativePath.startsWith(`${runtimeRoot}/`)) {
+      if (!distribution.runtimes.includes(runtime)) return false;
+      if (relativePath.startsWith(`${root}/`)) {
+        const name = relativePath.slice(root.length + 1).split("/")[0];
+        if (name && !name.startsWith(".") && !distribution.installedSkills.includes(name)) return false;
+      }
+    }
+  }
+  if (relativePath.startsWith(".agents/skills/")) {
+    const name = relativePath.slice(".agents/skills/".length).split("/")[0];
+    if (name && !name.startsWith(".") && !distribution.installedSkills.includes(name)) return false;
+  }
+  return true;
+}
+
+function selectedSkillLock(sourceText, distribution) {
+  if (distribution.mode === "legacy-all") return sourceText;
+  const source = JSON.parse(sourceText);
+  const roots = distribution.runtimes.map((runtime) => RUNTIMES[assertRuntime(runtime)]);
+  source.projectionRoots = roots;
+  source.skills.shared = Object.fromEntries(Object.entries(source.skills.shared).filter(([name]) => distribution.installedSkills.includes(name)).map(([name, record]) => [name, { ...record, targets: [".agents/skills", ...roots] }]));
+  source.skills.platform = Object.fromEntries(roots.map((root) => [root, Object.fromEntries(Object.entries(source.skills.platform?.[root] || {}).filter(([name]) => distribution.installedSkills.includes(name)))]).filter(([, entries]) => Object.keys(entries).length));
+  return `${JSON.stringify(source, null, 2)}\n`;
+}
+
+function renderInstanceSkillSupplyChain(sourceText) {
+  const additions = `\nfunction projectionRootsFor(lock) {
+  const identityPath = path.join(ROOT, "yss-project.yaml");
+  const isInstance = existsSync(identityPath) && /^repository_mode:\\s*project-instance\\s*$/m.test(readFileSync(identityPath, "utf8"));
+  if (!isInstance) return PROJECTION_ROOTS;
+  const roots = lock?.projectionRoots;
+  if (!Array.isArray(roots) || !roots.length || roots.some((root) => !PROJECTION_ROOTS.includes(root))) throw new TypeError("project-instance skills-lock.json 缺少有效 projectionRoots");
+  return [...new Set(roots)];
+}\n`;
+  const marker = 'export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];';
+  if (!sourceText.includes(marker)) throw new Error("Skill 投影脚本分发基线已变化");
+  return sourceText.replace(marker, marker + additions)
+    .replace("  const shared = sharedFromLock(lock);", "  const shared = sharedFromLock(lock);\n  const projectionRoots = projectionRootsFor(lock);")
+    .replace("  const oldLock = parseLock(); const previous = priorMetadata(oldLock);", "  const oldLock = parseLock(); const projectionRoots = projectionRootsFor(oldLock); const previous = priorMetadata(oldLock);")
+    .replaceAll("for (const root of PROJECTION_ROOTS) {", "for (const root of projectionRoots) {")
+    .replace("const targets = [\".agents/skills\", ...PROJECTION_ROOTS];", "const targets = [\".agents/skills\", ...projectionRoots];")
+    .replace("projectionRoots: PROJECTION_ROOTS, sources, skills", "projectionRoots, sources, skills");
+}
+
+function renderInstanceDesignSkillFile(sourceText) {
+  return sourceText
+    .replaceAll("node .template-source/tooling/node/scripts/design-md.mjs", "scripts/design-md")
+    .replace("运行前先更新 `.template-spec/design/design-system-sync.yaml` 的规范源摘要。", "项目实例无需模板间的 design-system-sync 摘要。")
+    .replace("修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 →", "修改根 DESIGN.md →");
+}
+
+function linkedSkillDependencies(templateRoot, name) {
+  const skillRoot = path.join(templateRoot, ".agents/skills");
+  const current = path.join(skillRoot, name);
+  const result = new Set();
+  function visitDir(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visitDir(file);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const content = fs.readFileSync(file, "utf8");
+        for (const match of content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+          const ref = match[1].split("#")[0];
+          if (!ref || ref.startsWith("/") || ref.includes("://")) continue;
+          const resolved = path.resolve(path.dirname(file), ref);
+          const relative = path.relative(skillRoot, resolved).split(path.sep);
+          if (relative.length > 1 && relative[0] !== name && !relative[0].startsWith(".") && !relative[0].includes("..") && fs.existsSync(resolved)) result.add(relative[0]);
+        }
+      }
+    }
+  }
+  visitDir(current);
+  return [...result];
+}
+
+function requiredSkills(registryText, requested, triggers = [], templateRoot = null) {
+  const skillBlock = registryText.split(/^skills:\s*$/m)[1]?.split(/^platform_skills:\s*$/m)[0] || "";
+  const available = new Set([...skillBlock.matchAll(/^  - (?:\{ )?id: ([a-z][a-z0-9-]+)/gm)].map((match) => match[1]));
+  const platformBlock = registryText.split(/^platform_skills:\s*$/m)[1]?.split(/^external_skills:\s*$/m)[0] || "";
+  const platformSkills = new Set([...platformBlock.matchAll(/^  - id: ([a-z][a-z0-9-]+)/gm)].map((match) => match[1]));
+  const block = registryText.split(/^skill_dependencies:\s*$/m)[1]?.split(/^[^\s#][^\n]*:\s*$/m)[0] || "";
+  const dependencies = new Map();
+  let current = null;
+  for (const line of block.split("\n")) {
+    const header = line.match(/^  ([a-z][a-z0-9-]+):\s*$/);
+    if (header) { current = header[1]; continue; }
+    const item = line.match(/^    - \{ skill: ([a-z][a-z0-9-]+), type: ([a-z-]+)(?:, when: ([a-z0-9-]+))? \}/);
+    if (current && item) {
+      if (!dependencies.has(current)) dependencies.set(current, []);
+      dependencies.get(current).push({ name: item[1], type: item[2], when: item[3] });
+    }
+  }
+  const result = new Set();
+  function visit(name) {
+    if (!available.has(name)) throw new Error(platformSkills.has(name) ? `平台专属 Skill 不可作为共享 Skill 补装：${name}` : `Skill 未在注册表登记：${name}`);
+    if (result.has(name)) return;
+    result.add(name);
+    for (const dep of dependencies.get(name) || []) {
+      if (dep.type === "context-required" || (dep.type === "context-conditional" && triggers.includes(dep.when))) visit(dep.name);
+    }
+    if (templateRoot) for (const linked of linkedSkillDependencies(templateRoot, name)) visit(linked);
+  }
+  requested.forEach(visit);
+  return [...result].sort();
+}
+
+module.exports = { RUNTIMES, assertRuntime, readDistributionRegistry, distributionForVariables, isIncludedInstancePath, selectedSkillLock, renderInstanceSkillSupplyChain, renderInstanceDesignSkillFile, requiredSkills };

package/src/template/instance-runtime.js

@@ -8,6 +8,8 @@ const { treeHash } = require("../template-hash");
 const { targetPath, pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
 const { validateTemplateSnapshot } = require("../validation/snapshot");
 const { validateTemplateMetadata } = require("../validation/metadata");
+const { distributionForVariables, isIncludedInstancePath, selectedSkillLock, renderInstanceSkillSupplyChain, renderInstanceDesignSkillFile } = require("./distribution-runtime");
+const { ASSET_PROFILE, assetPaths } = require("./asset-runtime");
 const {
   extractManagedGitignoreBlock,
   mergeManagedGitignoreBlock,
@@ -29,7 +31,7 @@ const TEMPLATE_MANIFEST_TEXT = fs.readFileSync(BUNDLED_MANIFEST_PATH, "utf8");
 const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
 const TEMPLATE_SOURCE = "github:iloveZzz/yss-spec-project-template";
-const METADATA_SCHEMA_VERSION = 2;
+const METADATA_SCHEMA_VERSION = 3;
 
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
 const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
@@ -47,8 +49,6 @@ const INIT_EXCLUDED_RELATIVE_PATHS = new Set(
 const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
 const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
 
-let bundledPathToLogicalPath = null;
-
 function sha256(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
@@ -79,16 +79,16 @@ function readTemplateSnapshot() {
   });
 }
 
-function logicalTemplatePath(bundledPath) {
-  if (bundledPathToLogicalPath === null) {
-    const snapshot = readTemplateSnapshot();
-    bundledPathToLogicalPath = new Map(
-      Object.entries(snapshot.encodedPaths || {}).map(([logicalPath, encodedPath]) => [
-        normalizeRelativePath(encodedPath),
-        normalizeRelativePath(logicalPath),
-      ]),
-    );
-  }
+function logicalPathMap(snapshot) {
+  return new Map(
+    Object.entries(snapshot.encodedPaths || {}).map(([logicalPath, encodedPath]) => [
+      normalizeRelativePath(encodedPath),
+      normalizeRelativePath(logicalPath),
+    ]),
+  );
+}
+
+function logicalTemplatePath(bundledPath, bundledPathToLogicalPath) {
   return (
     bundledPathToLogicalPath.get(normalizeRelativePath(bundledPath)) ||
     normalizeRelativePath(bundledPath)
@@ -143,12 +143,35 @@ function readTargetIdentity(targetDir) {
 }
 
 function renderTemplateFile(relativePath, content, variables) {
+  const distribution = variables.distribution || distributionForVariables(variables, BUNDLED_TEMPLATE_ROOT);
+  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 === ".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 === ".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 === ".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 === ".template-spec/design/README.md") {
+    return content.replace(/^.*design-system-sync\.yaml.*\n/m, "");
+  }
+  if (distribution.mode === "selected" && relativePath.startsWith(".template-spec/user-guide/") && relativePath.endsWith(".md")) {
+    return content.replaceAll("[设备借用贯穿案例](设备借用贯穿案例.md)", "[项目用户手册](用户手册.md)")
+      .replaceAll("本仓是 `template-source`", "模板源是 `template-source`");
+  }
   if (relativePath === "yss-project.yaml") {
     return convertTemplateSourceToInstance(content);
   }
 
   if (relativePath === "AGENTS.md") {
-    return content
+    const rendered = content
       .replace(
         /(\*\*项目名称：\*\*\s*)\[填写\]/,
         (_, prefix) => `${prefix}${variables.projectName}`,
@@ -161,10 +184,20 @@ function renderTemplateFile(relativePath, content, variables) {
         /(\*\*团队规模：\*\*\s*)\[填写\]/,
         (_, prefix) => `${prefix}${variables.teamSize}`,
       );
+    if (distribution.mode !== "selected") return rendered;
+    const base = rendered.replace(/## 4\. \`template-source\` 模板维护路由[\s\S]*?(?=## 5\.)/, "")
+      .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`。专项任务根据 .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}`;
   }
 
   if (relativePath === "README.md") {
-    return `# ${variables.projectName}\n\n本仓库用于管理 ${variables.businessDomain} 的研发资产。\n\n- 默认 Issue Tracker：${variables.issueTracker}\n- 协作入口：[AGENTS.md](./AGENTS.md)\n- 业务词汇：[CONTEXT.md](./CONTEXT.md)\n- 用户指南：[docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md)\n`;
+    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- 用户指南：[.template-spec/user-guide/用户手册.md](./.template-spec/user-guide/用户手册.md)\n\n项目校验：\`scripts/verify-project-instance\`。${assetGuidance}\n`;
   }
 
   if (relativePath === ".gitignore") return extractManagedGitignoreBlock(content);
@@ -178,6 +211,8 @@ function buildCopyPlan(
   variables,
   relativeDir = "",
   mode = "managed",
+  bundledPathToLogicalPath,
+  distribution = { mode: "legacy-all" },
 ) {
   const operations = [];
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
@@ -188,9 +223,10 @@ function buildCopyPlan(
     const bundledRelativePath = relativeDir
       ? path.posix.join(relativeDir, entry.name)
       : entry.name;
-    const relativePath = logicalTemplatePath(bundledRelativePath);
+    const relativePath = logicalTemplatePath(bundledRelativePath, bundledPathToLogicalPath);
 
     if (shouldExcludeRelativePath(relativePath, mode)) continue;
+    if (!isIncludedInstancePath(relativePath, distribution)) continue;
     if (!variables.includeExampleDocs && EXAMPLE_DOC_PATHS.has(relativePath)) continue;
 
     const sourcePath = path.join(sourceDir, entry.name);
@@ -205,6 +241,8 @@ function buildCopyPlan(
           variables,
           bundledRelativePath,
           mode,
+          bundledPathToLogicalPath,
+          distribution,
         ),
       );
       continue;
@@ -235,8 +273,9 @@ function buildSyncVariables(metadata) {
     issueTracker: variables.issueTracker || "github",
     includeExampleDocs:
       variables.includeExampleDocs === undefined
-        ? true
+        ? !(metadata.metadataSchemaVersion >= 3)
         : Boolean(variables.includeExampleDocs),
+    distribution: metadata.metadataSchemaVersion >= 3 ? metadata.distribution : { mode: "legacy-all" },
   };
 }
 
@@ -254,15 +293,18 @@ function buildDesiredManagedFile(operation, variables) {
     };
   }
 
+  const desiredContent = fs.readFileSync(operation.sourcePath);
   return {
     ...operation,
-    desiredContent: fs.readFileSync(operation.sourcePath),
-    desiredHash: fileHash(operation.sourcePath),
+    desiredContent,
+    desiredHash: sha256(desiredContent),
   };
 }
 
-function buildDesiredManagedOperations(targetDir, variables, mode = "managed") {
-  return buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, variables, "", mode)
+function buildDesiredManagedOperations(targetDir, variables, mode = "managed", snapshot = readTemplateSnapshot()) {
+  const distribution = variables.distribution || distributionForVariables(variables, BUNDLED_TEMPLATE_ROOT);
+  const effectiveDistribution = { ...distribution, assetPaths: assetPaths(BUNDLED_TEMPLATE_ROOT, distribution) };
+  return buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, { ...variables, distribution }, "", mode, logicalPathMap(snapshot), effectiveDistribution)
     .filter((operation) => operation.type === "copy" || operation.type === "render")
     .map((operation) => buildDesiredManagedFile(operation, variables));
 }
@@ -297,9 +339,9 @@ function adaptGitignoreOperation(
   };
 }
 
-function buildSyncDesiredOperations(targetDir, metadata, identity) {
+function buildSyncDesiredOperations(targetDir, metadata, identity, snapshot = readTemplateSnapshot()) {
   const variables = buildSyncVariables(metadata);
-  return buildDesiredManagedOperations(targetDir, variables, "init")
+  return buildDesiredManagedOperations(targetDir, variables, "init", snapshot)
     .filter((operation) => operation.relativePath !== "README.md")
     .map((operation) =>
       adaptGitignoreOperation(operation, targetDir, {
@@ -327,7 +369,7 @@ function buildSyncDesiredOperations(targetDir, metadata, identity) {
 }
 
 function buildAttachDesiredOperations(targetDir, variables, identity) {
-  return buildDesiredManagedOperations(targetDir, variables, "managed")
+  return buildDesiredManagedOperations(targetDir, variables, "init")
     .filter((operation) => operation.relativePath !== "README.md")
     .map((operation) => adaptGitignoreOperation(operation, targetDir, { attach: true }))
     .map((operation) => {
@@ -396,6 +438,7 @@ function collectManagedFiles(desiredOperations) {
 
 function buildMetadata(variables, desiredOperations, timestamp = nowIsoString()) {
   const snapshot = readTemplateSnapshot();
+  const distribution = variables.distribution || distributionForVariables(variables, BUNDLED_TEMPLATE_ROOT);
   return {
     metadataSchemaVersion: METADATA_SCHEMA_VERSION,
     templateName: PACKAGE_MANIFEST.name,
@@ -408,6 +451,7 @@ function buildMetadata(variables, desiredOperations, timestamp = nowIsoString())
     initializedAt: timestamp,
     lastSyncedAt: timestamp,
     managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    distribution,
     variables: {
       projectName: variables.projectName,
       businessDomain: variables.businessDomain,
@@ -429,19 +473,21 @@ function writeTemplateMetadata(targetDir, metadata, transaction = null) {
   fs.writeFileSync(metadataPath, content, "utf8");
 }
 
-function buildNextSyncMetadata(metadata, syncPlan) {
-  const snapshot = readTemplateSnapshot();
+function buildNextSyncMetadata(metadata, syncPlan, {
+  snapshot = readTemplateSnapshot(),
+  currentHashes = null,
+} = {}) {
   const nextManagedFiles = { ...(metadata.managedFiles || {}) };
   delete nextManagedFiles["README.md"];
   for (const relativePath of syncPlan.alreadyMissing || []) delete nextManagedFiles[relativePath];
   for (const relativePath of syncPlan.pruned || []) delete nextManagedFiles[relativePath];
   for (const operation of syncPlan.desiredOperations) {
     if (pathKind(operation.targetPath) !== "file") continue;
-    const currentHash = fileHash(operation.targetPath);
-    if (currentHash === operation.desiredHash) {
+    const currentHash = currentHashes?.[operation.relativePath] ?? fileHash(operation.targetPath);
+    if (currentHash === operation.desiredHash || operation.relativePath === "skills-lock.json") {
       nextManagedFiles[operation.relativePath] = {
         type: operation.type,
-        contentHash: operation.desiredHash,
+        contentHash: currentHash,
       };
     }
   }
@@ -449,6 +495,7 @@ function buildNextSyncMetadata(metadata, syncPlan) {
   return {
     ...metadata,
     metadataSchemaVersion: METADATA_SCHEMA_VERSION,
+    distribution: metadata.metadataSchemaVersion >= 3 ? metadata.distribution : { mode: "legacy-all" },
     templateName: PACKAGE_MANIFEST.name,
     cliVersion: PACKAGE_MANIFEST.version,
     templateVersion: PACKAGE_MANIFEST.version,

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/ownership-policy.js

@@ -124,10 +124,25 @@ function isWriteProtectedOwnership(ownership) {
   return ownership === "user-owned" || ownership === "protected";
 }
 
+function projectAssetWriteViolation(relativePath) {
+  const path = normalizePolicyPath(relativePath);
+  if (path === "docs/implementation/.gitkeep" || path === "docs/requirements/tickets/.gitkeep") return null;
+  if (
+    path === "scaffold-architecture-decisions.yaml" ||
+    path.startsWith("docs/implementation/") ||
+    path.startsWith("docs/requirements/tickets/")
+  ) {
+    return `${path} 是项目合同或决策资产，CLI 同步不得写入或清理`;
+  }
+  return null;
+}
+
 function ownershipWriteViolation(operation) {
+  const path = operation?.relativePath || operation?.path || "unknown";
+  const projectAssetViolation = projectAssetWriteViolation(path);
+  if (projectAssetViolation) return projectAssetViolation;
   const ownership = operation?.ownership || "managed";
   if (!isWriteProtectedOwnership(ownership)) return null;
-  const path = operation?.relativePath || operation?.path || "unknown";
   return ownership === "protected"
     ? `${path} 被 ownership policy 标记为 protected，CLI 不得写入或覆盖`
     : `${path} 被 ownership policy 标记为 user-owned，不属于受管模板文件`;
@@ -145,5 +160,6 @@ module.exports = {
   resolveOwnership,
   isTemplateManagedOwnership,
   isWriteProtectedOwnership,
+  projectAssetWriteViolation,
   ownershipWriteViolation,
 };

package/src/template/prune-planner.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const { isTemplateManagedOwnership } = require("./ownership-policy");
+const { isTemplateManagedOwnership, projectAssetWriteViolation } = require("./ownership-policy");
 const { resolveTemplateOwnership } = require("./ownership-runtime");
 
 function classifyRemovedFiles({
@@ -29,6 +29,11 @@ function classifyRemovedFiles({
       retainedRemoved.push({ path: relativePath, reason: "缺少可信受管基线" });
       continue;
     }
+    const projectAssetViolation = projectAssetWriteViolation(relativePath);
+    if (projectAssetViolation) {
+      retainedRemoved.push({ path: relativePath, reason: projectAssetViolation });
+      continue;
+    }
     const recordedOwnership = record.ownership || getCurrentOwnership(relativePath);
     const currentOwnership = getCurrentOwnership(relativePath);
     if (