create-yss-spec 3.4.10 → 3.5.0

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);
@@ -53,6 +54,7 @@ function classifySyncOperations({
     }
 
     const currentHash = getFileHash(operation);
+    currentHashes[operation.relativePath] = currentHash;
 
     if (operation.safeSectionMerge && currentHash !== operation.desiredHash) {
       updated.push(operation);
@@ -117,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": "9e17922a0a718e5bd1845ddab11850a2f43becad",
+  "source_revision": "9b579c7b954c153d2347696f53123aebaccde48f",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {

package/template/.agents/skills/yss-cache/SKILL.md

@@ -10,8 +10,8 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工作流
 
 1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
-2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
-3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
+2. 识别使用模型：Spring Cache 单后端路由、Redis 故障处理，或独立的 JetCache local + remote。`fail-fast`/`bypass`/`fallback` 是当前 Boot 3 Redis 契约；Boot 2 以其独立源码索引为准，不要混用两代或三种模型的行为假设。
+3. 明确缓存名、key、区域 TTL/容量/空值策略、更新/删除路径、跨节点一致性和序列化兼容要求。
 4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
 5. 修改后执行对应 reference 的验证；组件跨模块修改必须从父 reactor 构建，不要依赖本地旧 SNAPSHOT。
 
@@ -20,13 +20,14 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 - 新增查询缓存时同时覆盖更新、删除和状态变更的失效路径。
 - key 必须稳定并显式包含租户、机构、账套等隔离维度；不要依赖 DTO 的不稳定序列化结果。
 - 不要把 Redis fallback 当作正常二级缓存。Caffeine fallback 存在节点间不一致窗口。
-- 不要声称纯 Redis 后端会广播本地缓存失效。只有确认 JetCache 配置了 local、remote 和 broadcast channel 后才能作此判断。
+- 不要声称纯 Redis 后端会广播本地缓存失效。JetCache 即使存在 broadcast channel 配置，也须验证实际 local/remote 实例和同步开关后才能作此判断。
 - 不要在没有双读、版本前缀、灰度清理或迁移窗口时修改 serializer、key prefix 或 cache name。
 - 不明确一致性要求时，不默认启用本地缓存或 fallback。
 
 ## 按场景读取
 
 - 模块、后端选择或多级缓存边界：[architecture.md](references/architecture.md)
+- JetCache 包装器、`QuickConfig`、跨 JVM 失效与故障边界：[jetcache.md](references/jetcache.md)
 - 新增或修改缓存注解、SpEL、空 key、全量清理：[annotations.md](references/annotations.md)
 - 依赖、启动注解、TTL、Caffeine/Hazelcast、Bean backoff：[configuration.md](references/configuration.md)
 - Redis 单机、哨兵、集群、认证、SSL、超时、Jedis pool：[redis-topology.md](references/redis-topology.md)
@@ -38,10 +39,10 @@ description: "接入或排查 YSS QueryCache、UpdateCache、ClearCache、TTL、
 ## 工具
 
 - `scripts/inspect-cache-usage.sh <project-root>`：只读扫描消费项目；发现阻断缺陷返回 1，输入或环境错误返回 2。
-- `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
+- `scripts/verify-cache-component.sh --platform-line <boot2-java8|boot3-java17> [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：从匹配的平台源码根干净构建，验证组件、可用时的真实 Redis、对应 Java 字节码及可选消费模块。
 - `scripts/check-skill-freshness.sh <boot2-java8|boot3-java17> [source-root]`：比较所选平台线的技能契约与当前组件源码；发现平台错配或漂移返回 1。
 
-当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。
+本 Skill 中新增的 `failure-mode`、区域策略和 `empty-key-eviction` 指引针对当前 Boot 3 组件；Boot 2 的精确配置与默认值须查其独立索引及源码。组件源码形成干净、固定的来源后，用 `yss-skill-source-index-refresh` 刷新所选平台的生成索引，再运行 freshness 检查。`source-index.md` 是平台选择页；不要手工修改生成索引或把 dirty 工作树的观察说成已核验事实。
 
 ## 平台与源码门禁
 

package/template/.agents/skills/yss-cache/references/annotations.md

@@ -1,5 +1,7 @@
 # 注解契约
 
+以下 `empty-key-eviction` 可配置行为针对当前 Boot 3 / Java 17 组件；Boot 2 的空 key 处理以其独立源码索引和当前源码为准。
+
 ## 映射
 
 - `@QueryCache` -> Spring `CacheableOperation`。
@@ -28,7 +30,7 @@ public void delete(String tenantId, Long planId) { ... }
 ```
 
 - 未配置 key 时由 Spring KeyGenerator 生成；无参数方法会得到 `SimpleKey.EMPTY`。
-- 当前 YSS 拦截器将 `SimpleKey.EMPTY` 视为全量清理。需要单 key 清理时必须给出稳定 key。
+- 当前 Boot 3 的 `yss.cache.empty-key-eviction=legacy-clear`（默认）把 `SimpleKey.EMPTY` 当作清区；`evict` 时只删该 key。迁移前核对原有无参数清理调用及实际属性，不能把默认行为说成所有配置下的不变量。
 - 全量清理优先显式写 `allEntries=true`，不要依赖偶然 key 形态。
 - 集合参数先稳定排序；null、大小写和空白必须归一化。
 

package/template/.agents/skills/yss-cache/references/architecture.md

@@ -1,12 +1,14 @@
 # 架构与选择
 
+以下模型划分适用于接入决策；具体配置、默认值及跨节点行为按所选平台线的当前源码核验。本轮新增的 Redis 故障模式、区域策略和 JetCache 运行证据属于 Boot 3 当前组件。
+
 ## 三种模型
 
 | 模型 | 行为 | 一致性边界 |
 |---|---|---|
 | Spring Cache 后端路由 | `yss.cache.active-type` 在 Redis、Caffeine、Hazelcast 中选择一个 Provider | 同一时刻是单后端，不是多级缓存 |
 | Redis fallback | Redis 故障时可临时改用另一个 Provider | 是故障降级；Caffeine 会产生节点间不一致窗口 |
-| JetCache | 独立扩展，可配置 local + remote | 只有实际配置 broadcast channel 才能认为本地失效会同步 |
+| JetCache | 独立扩展，可配置 local + remote | broadcast channel 配置本身不证明包装器已启用跨 JVM 本地失效同步 |
 
 ## 模块
 
@@ -22,4 +24,4 @@
 - 跨节点共享且不接受节点本地旧值：使用纯 Redis。
 - 读多写少并允许短暂节点差异：可选择 Caffeine。
 - Redis 故障期间业务可用性高于缓存一致性：评估后启用 fallback。
-- 需要 local + remote：先确认 JetCache 的 local、remote、序列化和广播配置，不要只看依赖名称。
+- 需要 local + remote：按 [JetCache 专项参考](jetcache.md) 核对实际创建的 Cache、配置来源及首次创建参数，并用跨 JVM 测试证明同步，不要只看依赖或 `bootstrap.yml`。

package/template/.agents/skills/yss-cache/references/configuration.md

@@ -13,20 +13,23 @@
 
 ## 公共属性
 
+以下示例及 `failure-mode`、区域策略、空值策略说明针对当前 Boot 3 / Java 17 组件。Boot 2 / Java 8 维护须先核对其独立源码索引与匹配源码，不套用这些新属性或默认值。
+
 ```yaml
 yss:
   cache:
     active-type: redis       # redis | caffeine | hazelcast
     default-ttl: 1h
+    failure-mode: fail-fast  # fail-fast | bypass | fallback；仅 active-type=redis
     redis:
       fallback-enabled: false
       fallback-type: caffeine
       clear-fallback-on-recovery: true
 ```
 
-- Redis 动态 cache 和 Caffeine 默认 TTL 使用 `yss.cache.default-ttl`。
-- `CacheKeyCode` 中声明的 TTL 覆盖默认 TTL。
-- Caffeine 的 `spring.cache.caffeine.spec` 可覆盖默认构建规格，修改前检查项目现有配置。
+- `failure-mode` 默认 fail-fast；旧 `redis.fallback-enabled=true` 仍映射 fallback，同时配置为冲突值会拒绝启动。bypass 仅将 Redis 连接/资源故障的查询视为 miss，显式写入和失效仍报告错误；业务与序列化异常不降级。fallback 仅可选择已安装的 Caffeine，不是默认二级缓存。
+- 区域 `yss.cache.regions[区域名]` 可逐字段设置 `ttl`、`caffeine-maximum-size`、`null-policy`。TTL 以区域值优先；Caffeine 用户显式过期策略、`CacheKeyCode` 与 `default-ttl` 的实际优先级按当前组件源码核对。`null-policy=cache` 必须指定正的区域 TTL；`skip` 不等于删除旧值，`reject` 的契约错误不能吞成 Redis 故障。
+- Caffeine `spring.cache.caffeine.spec`、自定义 Builder/Loader 与区域覆盖的组合可能无法表达；核对当前组件的启动拒绝条件。自定义 CacheManager/Provider 时需证明区域策略真实生效，不能因配置存在就宣称 TTL、容量或空值策略已应用。
 - Hazelcast 不在 starter 生产依赖中；使用时显式引入模块并配置 `active-type=hazelcast`。
 
 ## 自定义 Bean

package/template/.agents/skills/yss-cache/references/jetcache.md

@@ -0,0 +1,21 @@
+# JetCache 独立接入与验证
+
+本页记录当前 Boot 3 / Java 17 `yss-component-jetcache` 工作树的接入判断；Boot 2 的精确能力以其平台索引和匹配源码为准。JetCache 与 YSS Spring Cache 是两条独立入口，不继承 `yss.cache.active-type`、区域 TTL 或 Redis `failure-mode`。
+
+## 先确认实际入口
+
+- 检查运行时上游 `CacheManager`、local/remote builder、应用自己的 JetCache 配置及实际创建的 area/name。依赖 JAR 中有 `bootstrap.yml` 不证明应用加载了它；无有效 local builder 时，LOCAL 请求可能在运行时失败。
+- 组件兼容包装器的两参数 `getCache` 默认 TTL 为 5 分钟，重载接收 `Duration`；它不设置 `syncLocal`、loader 或刷新策略。包装器的类型映射也不证明 LOCAL 实际采用 Caffeine。需要这些能力时核对原生 `QuickConfig` 与上游管理器。
+- 管理器按 area/name 复用已创建缓存。类型、TTL、`syncLocal` 等参数在第一次创建时确定，后续 `getOrCreateCache` 不会重建同名缓存；修改配置须使用新名称或明确的生命周期切换。
+
+## 跨 JVM 本地失效
+
+原生 `QuickConfig` 选择 `BOTH`、设置 `syncLocal(true)`，并为所有参与节点配置兼容的 `jetcache.remote.default.broadcastChannel`、编码及相同 area/name。包装器即使存在广播频道也不会自行开启 `syncLocal`；缺频道时不能据 `syncLocal(true)` 宣称已同步。
+
+验收时启动两个独立 JVM，在两端创建同名缓存，确认广播订阅实际建立后，从一端更新和删除并观察另一端本地值失效；同时用未同步的对照缓存确认失效范围。广播是异步通知，不承诺强一致或断连期间的持久补偿。
+
+## 故障与数据格式
+
+- 读取 `CacheResult` 状态来区分未命中和故障；便利 `get`/`getValue` 可能将远端故障折叠为 `null`。REMOTE 与 BOTH 的故障结果也不同，不能套用主线 Redis 的 fail-fast/bypass/fallback。
+- JetCache Java 编码保存 `CacheValueHolder`，与 Spring RedisCache 的 JDK 业务值及 RedisTemplate 的 Jackson 值不同。缓存名称、key 前缀或 serializer 迁移前，核对实际物理 key 和兼容方案，避免混写。
+- 包装器不提供主线缓存的事务后提交协调。刷新须核对原生 loader 与 refresh policy 是否同时配置；本轮未验证多节点刷新去重、断连补偿或生产 SLA。

package/template/.agents/skills/yss-cache/references/redis-fallback.md

@@ -1,11 +1,13 @@
 # Redis 故障降级与恢复
 
+以下故障模式和脏 Redis 区域恢复顺序是当前 Boot 3 / Java 17 组件契约。Boot 2 / Java 8 的故障处理和恢复默认值须单独核对其索引及源码。
+
 ## 状态流
 
 ```text
 Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 -> 可选 fallback -> 周期健康检查 -> Redis 可连接
--> 清理脏 Redis cache 与本地 fallback cache -> 恢复 Redis
+-> 清理脏 Redis cache；按配置清理本地 fallback cache -> 恢复 Redis
 ```
 
 - fallback 默认关闭，默认目标是 Caffeine。
@@ -13,11 +15,11 @@ Redis 健康 -> 命令或健康检查失败 -> 标记不健康 -> 跳过 Redis
 - Redis 命令级连接故障也会立即报告不健康，不必等待下一轮检查。
 - 只读 fallback 不标记 Redis cache 为脏。
 - put、putIfAbsent、evict、clear、invalidate 和 valueLoader 产生的回退写入会标记为脏。
-- 恢复时先清理降级期间发生写操作的 Redis cache，再清理本地 fallback cache。
+- 恢复时始终先清理降级期间发生写操作的 Redis cache；`clear-fallback-on-recovery=true` 时还清理本地 fallback cache。
 - Redis 失效失败时继续保持不健康状态并在后续检查重试，不能提前切回旧 Redis 数据。
 
 ## 一致性判断
 
 - Caffeine fallback 是每节点独立数据，不能保证跨节点读到相同值。
-- `clear-fallback-on-recovery=false` 会跳过恢复清理，可能重新暴露 Redis 旧值；除非业务明确接受，不要关闭。
+- `clear-fallback-on-recovery=false` 只跳过本地备用缓存清理，不跳过脏 Redis 区域失效。Redis 失效失败时不切回；关闭本地清理仍须评估后续备用使用时的本地旧值窗口。
 - 强一致、锁、幂等状态或余额类数据不应依赖缓存 fallback 保证正确性。