create-yss-spec 3.4.9 → 3.5.0

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 = [
+  "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",
+];
+
+function readDistributionRegistry(templateRoot) {
+  const registry = fs.readFileSync(path.join(templateRoot, "docs/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("docs/") || 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("运行前先更新 `docs/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 === "docs/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") {
+    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 (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") {
+    return content.replace(/^.*design-system-sync\.yaml.*\n/m, "");
+  }
+  if (distribution.mode === "selected" && relativePath.startsWith("docs/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` | `docs/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";
+    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- 用户指南：[docs/user-guide/用户手册.md](./docs/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/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 (

package/src/template/sync-planner.js

@@ -23,6 +23,7 @@ function classifySyncOperations({
   const conflicts = [];
   const forceableConflicts = [];
   const unsafe = [];
+  const currentHashes = Object.create(null);
 
   for (const operation of desiredOperations) {
     const unmanagedReason = getUnmanagedReason(operation);
@@ -47,7 +48,13 @@ function classifySyncOperations({
       continue;
     }
 
+    if (operation.relativePath === "docs/agents/issue-tracker.md") {
+      unchanged.push({ ...operation, reason: "project-owned-tracker-configuration" });
+      continue;
+    }
+
     const currentHash = getFileHash(operation);
+    currentHashes[operation.relativePath] = currentHash;
 
     if (operation.safeSectionMerge && currentHash !== operation.desiredHash) {
       updated.push(operation);
@@ -112,6 +119,7 @@ function classifySyncOperations({
     unsafe,
     removed,
     desiredOperations,
+    currentHashes,
   };
 }
 

package/src/template/verification-runtime.js

@@ -134,7 +134,61 @@ function verifyGeneratedAttach(targetDir) {
   runTemplateVerification(targetDir, "scripts/verify-project-instance", []);
 }
 
-function refreshGeneratedProjectInstance(targetDir) {
+function readProjectSkillLock(targetDir) {
+  const lockPath = targetPath(targetDir, "skills-lock.json");
+  if (pathKind(lockPath) === "missing") return null;
+  const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  const isRecord = (value) => value && typeof value === "object" && !Array.isArray(value);
+  if (
+    lock.version !== 3 || !isRecord(lock.skills?.shared) ||
+    !isRecord(lock.skills?.platform) || !isRecord(lock.sources) ||
+    !Array.isArray(lock.projectionRoots)
+  ) {
+    throw new Error("现有 skills-lock.json 结构非法，无法安全保留项目技能登记");
+  }
+  return lock;
+}
+
+function preserveProjectSkillRegistrations(targetDir, previousLock, previousManagedFiles, transaction) {
+  if (!previousLock) return;
+  const lockPath = targetPath(targetDir, "skills-lock.json");
+  const generated = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  const managedPaths = Object.keys(previousManagedFiles || {});
+  const wasManaged = (skillPath) => managedPaths.some((ref) => ref.startsWith(`${skillPath}/`));
+  let changed = false;
+
+  for (const [name, record] of Object.entries(previousLock.skills.shared)) {
+    const skillPath = `.agents/skills/${name}`;
+    if (generated.skills.shared[name] || wasManaged(skillPath)) continue;
+    if (pathKind(targetPath(targetDir, skillPath)) !== "directory") continue;
+    generated.skills.shared[name] = record;
+    changed = true;
+  }
+  for (const [root, entries] of Object.entries(previousLock.skills.platform || {})) {
+    if (!generated.projectionRoots.includes(root)) continue;
+    for (const [name, record] of Object.entries(entries)) {
+      const skillPath = `${root}/${name}`;
+      if (generated.skills.platform?.[root]?.[name] || wasManaged(skillPath)) continue;
+      if (pathKind(targetPath(targetDir, skillPath)) !== "directory") continue;
+      generated.skills.platform ||= {};
+      generated.skills.platform[root] ||= {};
+      generated.skills.platform[root][name] = record;
+      changed = true;
+    }
+  }
+  if (changed) {
+    generated.sources = { ...previousLock.sources, ...generated.sources };
+    transaction.writeFile(lockPath, `${JSON.stringify(generated, null, 2)}\n`);
+  }
+}
+
+function refreshGeneratedProjectInstance(targetDir, options = {}) {
+  preserveProjectSkillRegistrations(
+    targetDir,
+    options.previousSkillLock,
+    options.previousManagedFiles,
+    options.transaction,
+  );
   runTemplateVerification(targetDir, "scripts/update-skill-lock", []);
 }
 
@@ -146,6 +200,7 @@ module.exports = {
   verifyGeneratedInstance,
   verifyGeneratedInit,
   verifyGeneratedAttach,
+  readProjectSkillLock,
   refreshGeneratedProjectInstance,
   verifyGeneratedProjectInstance: verifyGeneratedAttach,
 };

package/src/validation/metadata.js

@@ -8,6 +8,7 @@ const OWNERSHIP_TYPES = new Set([
   "protected",
 ]);
 const MERGE_STRATEGIES = new Set(["replace-with-force", "manual"]);
+const { ASSET_PROFILE, INITIAL_STAGES, STAGES } = require("../template/asset-runtime");
 
 function assertPositiveInteger(value, name) {
   if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
@@ -22,7 +23,7 @@ function assertSha256(value, name) {
 }
 
 function validateTemplateMetadata(metadata, {
-  currentSchemaVersion = 2,
+  currentSchemaVersion = 3,
   templateName,
   templateSource,
 } = {}) {
@@ -35,6 +36,28 @@ function validateTemplateMetadata(metadata, {
   if (metadata.metadataSchemaVersion > currentSchemaVersion) {
     throw new Error(`不支持的模板元数据版本：${metadata.metadataSchemaVersion}`);
   }
+  if (metadata.metadataSchemaVersion === 3) {
+    const selection = metadata.distribution;
+    if (!selection || !["selected", "legacy-all"].includes(selection.mode)) throw new Error("模板元数据 distribution 非法");
+    if (selection.mode === "selected" && (
+      !Array.isArray(selection.runtimes) || !selection.runtimes.length ||
+      new Set(selection.runtimes).size !== selection.runtimes.length ||
+      selection.runtimes.some((runtime) => !["codex", "cursor", "pi"].includes(runtime)) ||
+      !Array.isArray(selection.installedSkills) ||
+      new Set(selection.installedSkills).size !== selection.installedSkills.length ||
+      selection.installedSkills.some((skill) => !/^[a-z][a-z0-9-]+$/.test(skill))
+    )) throw new Error("模板元数据 distribution 选择非法");
+    if (selection.mode === "selected" && selection.assetProfile !== undefined && (
+      selection.assetProfile !== ASSET_PROFILE ||
+      !Array.isArray(selection.installedStages) ||
+      INITIAL_STAGES.some((stage) => !selection.installedStages.includes(stage)) ||
+      new Set(selection.installedStages).size !== selection.installedStages.length ||
+      selection.installedStages.some((stage) => !Object.hasOwn(STAGES, stage)) ||
+      !Array.isArray(selection.resourceSkills) ||
+      new Set(selection.resourceSkills).size !== selection.resourceSkills.length ||
+      selection.resourceSkills.some((skill) => !selection.installedSkills.includes(skill))
+    )) throw new Error("模板元数据阶段资产选择非法");
+  }
   if (metadata.managedFiles !== undefined && (typeof metadata.managedFiles !== "object" || metadata.managedFiles === null || Array.isArray(metadata.managedFiles))) {
     throw new Error("模板元数据 managedFiles 必须是 JSON 对象");
   }

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

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "83d7bce7eab1adf16e02a419717c94fa8ba84f43",
+  "source_revision": "9b579c7b954c153d2347696f53123aebaccde48f",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {