create-yss-spec 3.5.6 → 3.5.9

package/src/template/asset-runtime.js

@@ -2,6 +2,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { pathToFileURL } = require("node:url");
 
 const ASSET_PROFILE = "stage-selective";
 const INITIAL_STAGES = ["stage.entry-triage", "stage.plan"];
@@ -24,9 +25,11 @@ const COMMON = {
     ".template-spec/process/lifecycle-registry-baseline-v1.json",
     ".template-spec/process/lifecycle-artifact-map.md",
     ".template-spec/process/harness-process-tailoring.md",
+    ".template-spec/process/script-execution.md",
     ".template-spec/process/document-writing.md",
     ".template-spec/process/contract-reading.md",
     ".template-spec/process/structured-assets.md",
+    ".template-spec/process/runtime-storage.md",
     ".template-spec/process/schemas/approval-record.schema.json",
     ".template-spec/process/schemas/review-bundle.schema.json",
     ".template-spec/process/templates/lifecycle-checkpoint-template.json",
@@ -53,6 +56,7 @@ const COMMON = {
     ".template-spec/process/templates/user-decision-template.yaml",
     ".template-spec/templates/local-parent-ticket-template.md",
     ".template-spec/templates/approval-record-template.yaml",
+    ".template-spec/templates/review-bundle-template.yaml",
     ".template-spec/templates/review-report-template.md",
     ".template-spec/user-guide/用户手册.md",
   ],
@@ -69,7 +73,9 @@ const COMMON = {
     "scripts/verify-approval-record",
     "scripts/query-lifecycle-context",
     "scripts/prepare-read-only-intake",
+    "scripts/prepare-review-package",
     "scripts/run-read-only-intake",
+    "scripts/runtime-store",
     "scripts/contract",
     "scripts/check-plan-stage-coverage",
     "scripts/stage-tracking",
@@ -139,38 +145,100 @@ const STAGES = Object.freeze({
       ".template-spec/process/delivery-preflight.md",
       ".template-spec/templates/release-note-template.md",
       ".template-spec/templates/retro-report-template.md",
-      ".template-spec/templates/review-bundle-template.yaml",
     ],
     scripts: ["scripts/preflight-delivery"],
     skills: [],
   },
 });
 
+function assertContained(root, ref) {
+  if (path.posix.isAbsolute(ref) || ref.includes("\\") || ref.split("/").includes("..")) throw new Error(`阶段资产路径越界：${ref}`);
+  const file = path.join(root, ref);
+  const relative = path.relative(fs.realpathSync(root), fs.realpathSync(file));
+  if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`阶段资产路径越界：${ref}`);
+  return file;
+}
+
 function sourceFile(root, ref) {
   const file = path.join(root, ref);
   if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`CLI 快照缺少阶段资产：${ref}`);
-  return file;
+  return assertContained(root, ref);
 }
 
-function addFile(root, result, ref) {
-  sourceFile(root, ref);
-  result.add(ref);
+function recordReason(result, ref, reason) {
+  const reasons = result.inclusionReasons.get(ref) || [];
+  if (!reasons.some(item => JSON.stringify(item) === JSON.stringify(reason))) reasons.push(reason);
+  result.inclusionReasons.set(ref, reasons);
 }
 
-function addPrefix(root, result, prefix) {
+function addFile(root, result, ref, reason, uri) {
+  recordReason(result, ref, reason);
+  if (!result.has(ref)) {
+    sourceFile(root, ref);
+    result.add(ref);
+  } else if (!ref.endsWith(".schema.json")) return;
+  if (ref.endsWith(".schema.json")) {
+    const visited = result.schemaFiles.has(ref);
+    const text = result.schemaFiles.get(ref) || fs.readFileSync(path.join(root, ref), "utf8"), schema = JSON.parse(text);
+    const fileURI = pathToFileURL(path.join(root, ref)).href;
+    for (const id of [uri, fileURI, schema.$id].filter(Boolean)) {
+      if (result.schemaResources.has(id) && result.schemaResources.get(id) !== text) throw new Error(`阶段 Schema ID 冲突：${id}`);
+      result.schemaResources.set(id, text);
+    }
+    if (visited) return;
+    result.schemaFiles.set(ref, text);
+    const base = schema.$id || uri || fileURI;
+    function visit(value) {
+      if (!value || typeof value !== "object") return;
+      for (const [key, dependency] of Object.entries(value)) {
+        if (["$ref", "$dynamicRef"].includes(key) && typeof dependency === "string" && !dependency.startsWith("#")) {
+          const file = dependency.split("#")[0];
+          const resolvedURI = new URL(file, base).href;
+          if (result.schemaResources.has(resolvedURI)) continue;
+          if (/^[a-z][a-z0-9+.-]*:/i.test(file) || path.posix.isAbsolute(file) || file.includes("\\")) throw new Error(`阶段 Schema 依赖必须为本地相对路径：${ref} -> ${dependency}`);
+          const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(ref), file));
+          if (!resolved.startsWith(".template-spec/") && !resolved.startsWith("scripts/")) throw new Error(`阶段 Schema 依赖路径越界：${ref} -> ${dependency}`);
+          addFile(root, result, resolved, { kind: "schema-ref", from: ref, reference: dependency }, resolvedURI);
+        } else visit(dependency);
+      }
+    }
+    visit(schema);
+  }
+}
+
+function addPrefix(root, result, prefix, reason, ancestors = []) {
   const directory = path.join(root, prefix);
   if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) throw new Error(`CLI 快照缺少阶段目录：${prefix}`);
+  assertContained(root, prefix);
+  const physical = fs.realpathSync(directory);
+  if (ancestors.includes(physical)) throw new Error(`阶段资产目录链接循环：${prefix}`);
+  const nextAncestors = [...ancestors, physical];
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     const ref = `${prefix}${entry.name}`;
-    if (entry.isDirectory()) addPrefix(root, result, `${ref}/`);
-    else if (entry.isFile()) result.add(ref);
+    const stat = entry.isSymbolicLink() ? fs.statSync(path.join(root, ref)) : entry;
+    if (stat.isDirectory()) addPrefix(root, result, `${ref}/`, reason, nextAncestors);
+    else if (stat.isFile()) addFile(root, result, ref, reason);
   }
 }
 
-function moduleClosure(root, result, ref, selectedSkills) {
-  if (result.has(ref)) return;
+function moduleClosure(root, result, ref, selectedSkills, reason) {
+  addFile(root, result, ref, reason);
+  if (result.modules.has(ref)) return;
+  result.modules.add(ref);
   const source = fs.readFileSync(sourceFile(root, ref), "utf8");
-  result.add(ref);
+  for (const match of source.matchAll(/\b(?:spawnSync|spawn|execFileSync|execFile)\(\s*['"](python3|node)['"]\s*,/g)) {
+    const dependency = result.runtimeDependencies.get(match[1]) || { executable: match[1], requiredBy: new Set(), packages: new Set() };
+    dependency.requiredBy.add(ref);
+    if (match[1] === "python3") {
+      for (const pkg of ["jsonschema", "referencing"]) if (new RegExp(`^from ${pkg}(?:\\.|\\s)`, "m").test(source)) dependency.packages.add(pkg);
+    }
+    result.runtimeDependencies.set(match[1], dependency);
+  }
+  if (/\b(?:spawnSync|spawn|execFileSync|execFile)\(\s*process\.execPath\s*,/.test(source)) {
+    const dependency = result.runtimeDependencies.get("node") || { executable: "node", requiredBy: new Set(), packages: new Set() };
+    dependency.requiredBy.add(ref);
+    result.runtimeDependencies.set("node", dependency);
+  }
   const expressions = [
     /\b(?:import|export)\s+(?:[^'"\n]*?\s+from\s*)?['"]([^'"]+)['"]/g,
     /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
@@ -191,9 +259,27 @@ function moduleClosure(root, result, ref, selectedSkills) {
         continue;
       }
       if (!candidate || !candidate.startsWith("scripts/")) throw new Error(`阶段脚本依赖未分发：${ref} -> ${match[1]}`);
-      moduleClosure(root, result, candidate, selectedSkills);
+      moduleClosure(root, result, candidate, selectedSkills, { kind: "module-import", from: ref, reference: match[1] });
     }
   }
+  // File names passed to a subprocess or Schema loader are runtime resources,
+  // not JavaScript imports. Include only complete, fixed local file references.
+  for (const match of source.matchAll(/['"]((?:scripts\/[\p{L}\p{N}_.\/-]+\.py|\.template-spec\/[\p{L}\p{N}_.\/-]+\.(?:json|yaml)))['"]/gu)) {
+    if (!fs.existsSync(path.join(root, match[1])) && !/\.(?:py|schema\.json)$/.test(match[1])) continue;
+    addFile(root, result, match[1], { kind: "runtime-resource", from: ref });
+  }
+  for (const match of source.matchAll(/\bnew\s+URL\(\s*['"](\.[^'"]+\.(?:json|yaml|py))['"]\s*,\s*import\.meta\.url\s*\)/g)) {
+    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(ref), match[1]));
+    if (!resolved.startsWith("scripts/") && !resolved.startsWith(".template-spec/")) throw new Error(`阶段资源依赖路径越界：${ref} -> ${match[1]}`);
+    addFile(root, result, resolved, { kind: "runtime-resource", from: ref, reference: match[1] });
+  }
+  // Caller-supplied roots can address another registered project. Only the
+  // module's fixed template root proves a dependency in this distribution.
+  for (const match of source.matchAll(/\b(?:spawnSync|spawn|execFileSync|execFile)\(\s*(?:(?:process\.execPath|['"](?:node|python3)['"])\s*,\s*\[\s*)?(?:path\.)?(?:join|resolve)\(\s*(?:ROOT|TEMPLATE_ROOT)\s*,\s*['"](scripts\/[\p{L}\p{N}_.\/-]+)['"]\s*\)/gu)) {
+    const reason = { kind: "subprocess-entry", from: ref };
+    if (/\.(?:py|json|yaml)$/.test(match[1])) addFile(root, result, match[1], reason);
+    else moduleClosure(root, result, match[1], selectedSkills, reason);
+  }
 }
 
 function skillReferences(root, result, skillId, selectedSkills) {
@@ -208,15 +294,16 @@ function skillReferences(root, result, skillId, selectedSkills) {
         for (const match of source.matchAll(/(?:\.template-spec|scripts)\/[\p{L}\p{N}_.\/-]+/gu)) {
           const ref = match[0].replace(/[.,;]+$/, "");
           if (!fs.existsSync(path.join(root, ref)) || !fs.statSync(path.join(root, ref)).isFile()) continue;
-          if (ref.startsWith("scripts/")) moduleClosure(root, result, ref, selectedSkills);
-          else addFile(root, result, ref);
+          const reason = { kind: "skill-reference", skill: skillId, from: path.relative(root, file).split(path.sep).join("/") };
+          if (ref.startsWith("scripts/")) moduleClosure(root, result, ref, selectedSkills, reason);
+          else addFile(root, result, ref, reason);
         }
       }
     }
   }
   visit(skillRoot);
-  for (const prefix of SKILL_ASSET_PREFIXES[skillId] || []) addPrefix(root, result, prefix);
-  for (const ref of RENDERED_SKILL_SCRIPTS[skillId] || []) moduleClosure(root, result, ref, selectedSkills);
+  for (const prefix of SKILL_ASSET_PREFIXES[skillId] || []) addPrefix(root, result, prefix, { kind: "skill-resource", skill: skillId, prefix });
+  for (const ref of RENDERED_SKILL_SCRIPTS[skillId] || []) moduleClosure(root, result, ref, selectedSkills, { kind: "skill-resource", skill: skillId });
 }
 
 function assetPaths(root, distribution) {
@@ -227,6 +314,11 @@ function assetPaths(root, distribution) {
     throw new Error("CLI 阶段资产映射与生命周期注册表阶段 ID 不一致");
   }
   const result = new Set();
+  result.inclusionReasons = new Map();
+  result.runtimeDependencies = new Map();
+  result.modules = new Set();
+  result.schemaFiles = new Map();
+  result.schemaResources = new Map();
   const selectedSkills = new Set(distribution.installedSkills);
   for (const ref of COMMON.files) {
     if (ref === ".template-spec/process/lifecycle-registry-baseline-v1.json" &&
@@ -234,15 +326,15 @@ function assetPaths(root, distribution) {
       const baseline = JSON.parse(fs.readFileSync(sourceFile(root, ".template-spec/process/lifecycle-registry-baseline.json"), "utf8"));
       if (baseline.schema_version === 1) continue;
     }
-    addFile(root, result, ref);
+    addFile(root, result, ref, { kind: "common-asset" });
   }
-  for (const ref of COMMON.scripts) moduleClosure(root, result, ref, selectedSkills);
+  for (const ref of COMMON.scripts) moduleClosure(root, result, ref, selectedSkills, { kind: "common-entry" });
   for (const stage of distribution.installedStages) {
     const bundle = STAGES[stage];
     if (!bundle) throw new Error(`未知生命周期阶段：${stage}`);
-    for (const prefix of bundle.prefixes || []) addPrefix(root, result, prefix);
-    for (const ref of bundle.files || []) addFile(root, result, ref);
-    for (const ref of bundle.scripts || []) moduleClosure(root, result, ref, selectedSkills);
+    for (const prefix of bundle.prefixes || []) addPrefix(root, result, prefix, { kind: "stage-asset", stage, prefix });
+    for (const ref of bundle.files || []) addFile(root, result, ref, { kind: "stage-asset", stage });
+    for (const ref of bundle.scripts || []) moduleClosure(root, result, ref, selectedSkills, { kind: "stage-entry", stage });
   }
   const resourceSkills = new Set(distribution.resourceSkills || []);
   if (selectedSkills.has("yss-harness-upgrade")) resourceSkills.add("yss-harness-upgrade");
@@ -250,4 +342,14 @@ function assetPaths(root, distribution) {
   return result;
 }
 
-module.exports = { ASSET_PROFILE, INITIAL_STAGES, STAGES, assetPaths };
+function assetRequirements(root, distribution) {
+  const files = assetPaths(root, distribution);
+  if (!files) return { selective: false, inclusionReasons: {}, runtimeDependencies: [] };
+  return {
+    selective: true,
+    inclusionReasons: Object.fromEntries([...files.inclusionReasons].sort(([a], [b]) => a.localeCompare(b)).map(([ref, reasons]) => [ref, reasons.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))])),
+    runtimeDependencies: [...files.runtimeDependencies.values()].sort((a, b) => a.executable.localeCompare(b.executable)).map(item => ({ executable: item.executable, requiredBy: [...item.requiredBy].sort(), packages: [...item.packages].sort() })),
+  };
+}
+
+module.exports = { ASSET_PROFILE, INITIAL_STAGES, STAGES, assetPaths, assetRequirements };

package/src/template/instance-runtime.js

@@ -8,6 +8,7 @@ const { treeHash } = require("../template-hash");
 const { targetPath, pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
 const { validateTemplateSnapshot } = require("../validation/snapshot");
 const { validateTemplateMetadata } = require("../validation/metadata");
+const { identityForPaths } = require("../content-identity");
 const { distributionForVariables, isIncludedInstancePath, selectedSkillLock, renderInstanceSkillSupplyChain, renderInstanceDesignSkillFile } = require("./distribution-runtime");
 const { ASSET_PROFILE, assetPaths } = require("./asset-runtime");
 const {
@@ -143,6 +144,7 @@ function readTargetIdentity(targetDir) {
 }
 
 function renderTemplateFile(relativePath, content, variables) {
+  const skillPreflight = "\n\n专项技能调用前，运行 `scripts/query-lifecycle-context --work-unit <当前工作单元> --check-skills`；多运行时用 `--agent-runtime`，已确认条件用 `--when`。未安装技能先核对结果中的补装计划，在既有任务授权内应用后重验；漂移、冲突和版本不匹配暂停当前调用，不自动覆盖或迁移。\n";
   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);
@@ -155,9 +157,9 @@ function renderTemplateFile(relativePath, content, variables) {
   }
   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阶段派发前，由 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 --plan\`，不自动扩展同步范围。\n\n项目校验运行 \`scripts/verify-project-instance\`。\n` + skillPreflight;
     }
-    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`;
+    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 --plan\`，不自动扩展同步范围。\n\n项目校验运行 \`scripts/verify-project-instance\`；实例 CI 应执行该命令和项目实际的构建、测试。\n` + skillPreflight;
   }
   if (distribution.mode === "selected" && relativePath === ".template-spec/design/README.md") {
     return content.replace(/^.*design-system-sync\.yaml.*\n/m, "");
@@ -188,9 +190,9 @@ function renderTemplateFile(relativePath, content, variables) {
     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}`;
+      ? "## 按需阶段资产与 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 快照与实例模板提交不一致，先核对匹配的 CLI 或 `create-yss-spec sync --plan`；不自动扩展同步范围。\n"
+      : "## 按需 Skill\n\n此实例继续沿用原文件分发范围。阶段派发或专项任务开始前，根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。若 CLI 快照与实例模板提交不一致，先核对匹配的 CLI 或 `create-yss-spec sync --plan`；不自动扩展同步范围。\n";
+    return `${base}\n${guidance}${skillPreflight}`;
   }
 
   if (relativePath === "README.md") {
@@ -428,11 +430,16 @@ function loadTemplateMetadata(targetDir) {
 
 function collectManagedFiles(desiredOperations) {
   const managedFiles = {};
-  for (const operation of desiredOperations) {
-    if (operation.relativePath === "README.md" || pathKind(operation.targetPath) !== "file") continue;
+  const files = desiredOperations.filter((operation) => operation.relativePath !== "README.md" && pathKind(operation.targetPath) === "file");
+  // One batched Git identity per repository, recorded alongside the legacy
+  // sha256 contentHash so older CLIs keep reading the same metadata.
+  const identities = identityForPaths(files.map((operation) => operation.targetPath));
+  for (const operation of files) {
+    const identity = identities.get(operation.targetPath);
     managedFiles[operation.relativePath] = {
       type: operation.type,
       contentHash: fileHash(operation.targetPath),
+      ...(identity ? { identity } : {}),
     };
   }
   return managedFiles;
@@ -483,13 +490,22 @@ function buildNextSyncMetadata(metadata, syncPlan, {
   delete nextManagedFiles["README.md"];
   for (const relativePath of syncPlan.alreadyMissing || []) delete nextManagedFiles[relativePath];
   for (const relativePath of syncPlan.pruned || []) delete nextManagedFiles[relativePath];
+  const desiredFiles = syncPlan.desiredOperations.filter((operation) => pathKind(operation.targetPath) === "file");
+  const identities = identityForPaths(desiredFiles.map((operation) => operation.targetPath));
   for (const operation of syncPlan.desiredOperations) {
     if (pathKind(operation.targetPath) !== "file") continue;
     const currentHash = currentHashes?.[operation.relativePath] ?? fileHash(operation.targetPath);
     if (currentHash === operation.desiredHash || operation.relativePath === "skills-lock.json") {
+      // Keep the recorded identity while the content hash is unchanged so a sync
+      // with nothing to do stays byte-identical (no churn, no needless backup).
+      const previousRecord = metadata.managedFiles?.[operation.relativePath];
+      const identity = previousRecord?.contentHash === currentHash && previousRecord.identity
+        ? previousRecord.identity
+        : identities.get(operation.targetPath);
       nextManagedFiles[operation.relativePath] = {
         type: operation.type,
         contentHash: currentHash,
+        ...(identity ? { identity } : {}),
       };
     }
   }

package/src/validation/metadata.js

@@ -100,6 +100,14 @@ function validateTemplateMetadata(metadata, {
         `模板元数据 managedFiles.${relativePath}.generatorVersion 必须是正整数`,
       );
     }
+    if (
+      record.identity !== undefined &&
+      !/^(git-sha1:[0-9a-f]{40}|git-sha256:[0-9a-f]{64}|sha256:[0-9a-f]{64})$/.test(record.identity)
+    ) {
+      throw new Error(
+        `模板元数据 managedFiles.${relativePath}.identity 非法`,
+      );
+    }
   }
 
   if (metadata.metadataSchemaVersion === currentSchemaVersion) {

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": "fbe4084276a8fe9a8f59e58481f2913133346eaf",
+  "source_revision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e",
   "adaptation_ref": ".template-source/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -14,7 +14,7 @@
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "0e82e8c0f6b5446dbe48aec8df092574ab895be303efe33d8fc8457bce98d02e"
+      "upstream_hash": "9d1177a3f7f4737e08f084049ca3c0a6e8da0c5327da8370a87262a1b5db3b8e"
     },
     {
       "upstream": "yss-design-system",
@@ -24,7 +24,7 @@
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "77fa3075f90966821881998ff5fa9d674672bd2568e70b8d877402efeb360453"
+      "upstream_hash": "5a55a18e996920c5e5ec683b6dfa89d714bb0a3299632ecc75e0d4865b71d108"
     }
   ],
   "source_state": "committed"

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

@@ -3,50 +3,44 @@ name: alibaba-java-code-style
 description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
-# Alibaba Java Code Style
+# 阿里巴巴 Java 规范
 
-This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
+本 Skill 从用户提供的《阿里巴巴 Java 开发手册》1.4.0 提炼适用规范。`mandatory` 违规阻断审查，除非仓库 `AGENTS.md`、安全约束或现有框架约定明确要求不同模式；例外须有依据。`recommended` / `reference` 保留建议等级，不因进入下文检查提要变为强制规则。
 
-## Workflow
+## 工作流
 
-1. Identify the touched surface:
-   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
-   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
-   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
-2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
-3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
-4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. For auth, payment, encryption, SQL, migrations or public-library changes, check the current contract and actual authorization. Continue an already authorized repair with its required verification; produce a draft or `TODO-HUMAN-REVIEW` only for a real missing decision or approval, and identify that gap.
+1. 按影响面读取对应规范：Java 命名、常量、OOP、集合、并发、控制流和注释读 [Java 编程](references/java-programming.md)；异常、日志、测试或安全读 [可靠性与安全](references/reliability-test-security.md)；MySQL、ORM/MyBatis、Maven、分层、服务器/JVM 或设计资产读 [工程与数据库](references/database-engineering-design.md)。
+2. 先执行适用 mandatory，再按实际风险采用 recommended；审查报告保留规则等级。建议仅在产生真实风险或处于本次范围时报告。
+3. 实现优先复用工程框架与已有生成能力，不新增重复基础设施。
+4. 认证、付款、加密、SQL、迁移或公共库变更先核验当前合同及实际授权。已授权修复继续完成适用验证；仅真实缺决定或批准时形成草案 / `TODO-HUMAN-REVIEW`，并说明缺口。
 
-## Core Priorities
+## 适用原则
 
 - 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
-- Keep names readable, English, and consistent with Java layer conventions.
-- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
-- Make logs useful without wasting CPU, disk, or alert budget.
-- Keep unit tests automatic, independent, repeatable, and close to public behavior.
-- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
-- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
-
-## Review Checklist
-
-- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
-- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
-- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
-- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
-- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
-- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
-- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
-- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
-- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
-  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
-
-## Source
-
-Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
+- 名称使用清晰英文标识并遵循当前 Java 分层约定。
+- 核验 null、相等、包装类型比较、集合和并发的运行时边界，不能以编译通过代替行为正确。
+- 日志有诊断用途，并控制 CPU、磁盘和告警成本。
+- 单元测试自动、独立、可重复，围绕公开行为验证。
+- SQL 使用参数绑定与显式 ORM 映射，不依赖字符串拼接。
+- 按已登记架构保持职责：Web/controller 校验和适配，service/manager 编排业务，DAO/repository 持有持久化。
+
+## 检查提要
+
+- 命名与格式：camel case、常量、包名、括号、间距、行长、UTF-8/Unix 换行；类型后缀和 boolean 命名符合适用规范。
+- 对象语义：`equals/hashCode`、包装类型比较、`toString`、`serialVersionUID`、构造器、可见性和访问器。
+- 集合：`subList`、`Arrays.asList`、`toArray`、foreach 删除、null map 和 comparator 的边界。
+- 并发：命名线程池、生产 `Executors` 工厂限制、锁顺序、日期格式和定时任务。
+- 异常：正确分层、上下文与堆栈、避免重复日志、不吞异常、不用于普通控制流。
+- 测试：断言、外部依赖隔离、`src/test/java` 与边界/正确/设计/错误场景。
+- 安全：按真实输入与认证方式核验校验、授权、转义、CSRF、限流和 SQL 参数绑定，不能泛用某项检查豁免其他风险。
+- MySQL：仅适用存储核验显式字段、映射、索引、时间戳与 `#{}` 绑定，以及危险级联、存储过程、`select *` 和分页边界。
+
+## 来源
+
+用户提供的《阿里巴巴 Java 开发手册》1.4.0，阿里巴巴集团技术团队，更新于 2018-05-20；具体条款等级保留在对应 references 中。
 
 ## 阶段 7 执行结果
 
 - 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
-- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
+- 适用 mandatory violation 返回 `violation`，附文件/位置/规则证据；高风险项仅在当前合同确有未满足人工决定或批准要求时保留 `TODO-HUMAN-REVIEW`。
 - 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

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

@@ -25,10 +25,10 @@ When the current repository contains `yss-project.yaml`, these rules override th
   node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json docs/architecture/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
 
   # template-source
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.archify.json .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
+  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.archify.json)" "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.html)" --quality showcase
   ```
 
-- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use `.template-source/evidence/maintenance/diagrams/<diagram-id>/`. The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
+- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use the current workspace's external `maintenance:diagrams/<diagram-id>/` (resolve with `scripts/maintenance-path`). The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
 - The safe wrapper rejects `--open`, non-HTML targets, symlink escapes, unrelated existing files, and stable source/output pairs outside those roots. Do not bypass it with the raw `deliver` or `preview` commands in a YSS repository.
 
 ## Fast authoring path

package/template/.agents/skills/archify/scripts/yss-safe-deliver.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(scriptDirectory, '..');
@@ -93,11 +93,12 @@ function assertReplaceableReceipt(receipt) {
   if (parsed?.yssArchifyReceipt !== true) fail(`拒绝覆盖非 YSS Archify receipt: ${receipt}`);
 }
 
-function stableContract(projectRoot, mode, input, output) {
+async function stableContract(projectRoot, mode, input, output) {
   const relativeBase = mode === 'project-instance'
     ? 'docs/architecture/diagrams'
-    : '.template-source/evidence/maintenance/diagrams';
-  const base = path.join(projectRoot, relativeBase);
+    : 'maintenance:diagrams';
+  const base = mode === 'project-instance' ? path.join(projectRoot, relativeBase)
+    : (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput(relativeBase, { root: projectRoot });
   const relativeOutput = path.relative(base, output);
   const segments = relativeOutput.split(path.sep);
   if (segments.length !== 2 || !diagramIdPattern.test(segments[0])) {
@@ -139,7 +140,10 @@ const temporaryBase = fs.realpathSync(os.tmpdir());
 // parent symlink resolves into the OS temporary directory. Otherwise the
 // temporary-delivery exception could be used to escape the stable output root.
 const requestedWithinProject = requestedProjectRoot !== null;
-const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output);
+const projectMode = projectRoot ? repositoryMode(projectRoot) : null;
+const templateDiagramBase = projectMode === 'template-source'
+  ? (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput('maintenance:diagrams', { root: projectRoot }) : null;
+const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output) && !(templateDiagramBase && isWithin(templateDiagramBase, output));
 let mode = null;
 let receipt;
 let allowedBase;
@@ -150,7 +154,7 @@ if (isTemporary) {
 } else {
   if (!projectRoot) fail('稳定交付必须从包含 yss-project.yaml 的仓库内运行');
   mode = repositoryMode(projectRoot);
-  const contract = stableContract(projectRoot, mode, input, output);
+  const contract = await stableContract(projectRoot, mode, input, output);
   allowedBase = contract.base;
   receipt = contract.receipt;
 }

package/template/.agents/skills/archify/test/yss-safe-deliver.test.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
+import { resolveMaintenanceOutput } from '../../../../scripts/lib/maintenance-storage.mjs';
 import { fileURLToPath } from 'node:url';
 
 const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -12,6 +13,12 @@ const example = path.join(skillRoot, 'examples', 'web-app.architecture.json');
 
 function repository(mode = 'project-instance') {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'yss-archify-safe-'));
+  if (mode === 'template-source') {
+    fs.mkdirSync(path.join(root, 'scripts/lib'), { recursive: true });
+    for (const name of ['maintenance-storage.mjs', 'runtime-store.mjs', 'repository-mode.mjs']) fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/lib', name), path.join(root, 'scripts/lib', name));
+    fs.mkdirSync(path.join(root, 'scripts/vendor'), { recursive: true });
+    fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/vendor/yaml.mjs'), path.join(root, 'scripts/vendor/yaml.mjs'));
+  }
   fs.writeFileSync(path.join(root, 'yss-project.yaml'), `schema_version: 1\nrepository_mode: ${mode}\n`);
   return root;
 }
@@ -104,9 +111,9 @@ test('delivers a paired project artifact and an auditable receipt', () => {
   assert.equal(receipt.archify.validation.warnings, 0);
 });
 
-test('uses the template-source evidence root for stable maintenance diagrams', () => {
+test('uses the external workspace maintenance root for stable diagrams', () => {
   const root = repository('template-source');
-  const directory = path.join(root, '.template-source', 'evidence', 'maintenance', 'diagrams', 'workflow-map');
+  const directory = resolveMaintenanceOutput('maintenance:diagrams/workflow-map', { root });
   fs.mkdirSync(directory, { recursive: true });
   const input = path.join(directory, 'workflow-map.archify.json');
   const output = path.join(directory, 'workflow-map.html');