create-yss-spec 3.4.10 → 3.5.0

package/template/scripts/lib/design-md.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { parseDocument } from "../vendor/yaml.mjs";
+
+const repositoryRoot = path.resolve(new URL("../..", import.meta.url).pathname);
+const designPath = path.join(repositoryRoot, "DESIGN.md");
+const projectionDir = path.join(repositoryRoot, "docs/design/tokens");
+const manifestPath = path.join(projectionDir, ".design-md-projection.json");
+const syncMetadataPath = path.join(repositoryRoot, "docs/design/design-system-sync.yaml");
+const expectedSections = ["Overview", "Colors", "Typography", "Layout", "Elevation & Depth", "Shapes", "Components", "Do's and Don'ts"];
+const requiredFrontmatter = ["version", "name", "description", "colors", "typography", "rounded", "spacing", "components"];
+const componentProperties = new Set(["backgroundColor", "textColor", "typography", "rounded", "padding", "size", "height", "width"]);
+
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function fail(message) { throw new Error(message); }
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
+function resolveValue(value, frontmatter) {
+  const match = typeof value === "string" ? value.match(/^\{(colors|typography|rounded|spacing)\.([\w-]+)\}$/) : null;
+  return match ? frontmatter[match[1]]?.[match[2]] : value;
+}
+
+function projectedCssVariables(frontmatter) {
+  const components = frontmatter.components;
+  return {
+    "yss-color-primary-control": resolveValue(components["button-primary"].backgroundColor, frontmatter),
+    "yss-color-primary-control-hover": resolveValue(components["button-primary-hover"].backgroundColor, frontmatter),
+    "yss-color-on-primary": resolveValue(components["button-primary"].textColor, frontmatter),
+    "yss-control-height": resolveValue(components["button-primary"].height, frontmatter),
+    "yss-card-padding": resolveValue(components["card-default"].padding, frontmatter),
+    "yss-control-height-compact": resolveValue(components["button-compact"].height, frontmatter),
+    "yss-card-compact-padding": resolveValue(components["card-compact"].padding, frontmatter)
+  };
+}
+
+function writeCssProjection(frontmatter) {
+  const cssPath = path.join(projectionDir, "variables.css");
+  let source = readFileSync(cssPath, "utf8");
+  for (const [name, value] of Object.entries(projectedCssVariables(frontmatter))) {
+    const declaration = `  --${name}: ${value};`;
+    const pattern = new RegExp(`^\\s*--${escapeRegExp(name)}:.*;$`, "m");
+    source = pattern.test(source) ? source.replace(pattern, declaration) : source.replace(":root {\n", `:root {\n${declaration}\n`);
+  }
+  writeFileSync(cssPath, source);
+}
+
+function validateCssProjection(frontmatter) {
+  const source = readFileSync(path.join(projectionDir, "variables.css"), "utf8");
+  for (const [name, value] of Object.entries(projectedCssVariables(frontmatter))) {
+    if (!new RegExp(`^\\s*--${escapeRegExp(name)}: ${escapeRegExp(String(value))};$`, "m").test(source)) fail(`variables.css 的 --${name} 与 DESIGN.md 不一致`);
+  }
+}
+
+function readDesign(file = designPath) {
+  const source = readFileSync(file, "utf8");
+  if (!source.startsWith("---\n")) fail(`${path.relative(repositoryRoot, file)} 缺少 YAML frontmatter`);
+  const end = source.indexOf("\n---", 4);
+  if (end < 0) fail(`${path.relative(repositoryRoot, file)} frontmatter 未闭合`);
+  const document = parseDocument(source.slice(4, end), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) fail(document.errors[0].message);
+  const frontmatter = document.toJS({ maxAliasCount: 0 });
+  for (const field of requiredFrontmatter) if (!frontmatter?.[field]) fail(`frontmatter 缺少 ${field}`);
+  const body = source.slice(end + 4);
+  const headings = [...body.matchAll(/^## ([^\n]+)$/gm)].map((match) => match[1].trim());
+  const actual = headings.slice(0, expectedSections.length);
+  if (JSON.stringify(actual) !== JSON.stringify(expectedSections)) fail(`canonical H2 章节顺序必须为: ${expectedSections.join(" → ")}`);
+  for (const section of expectedSections) {
+    if (headings.filter((heading) => heading === section).length !== 1) fail(`canonical H2 章节必须且只能出现一次: ${section}`);
+  }
+  const canonicalH1 = [...body.matchAll(/^# ([^\n]+)$/gm)].map((match) => match[1].trim()).filter((heading) => expectedSections.includes(heading));
+  if (canonicalH1.length > 0) fail(`canonical 正文章节必须使用 H2，不能使用 H1: ${canonicalH1.join(", ")}`);
+  for (const [name, component] of Object.entries(frontmatter.components)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) fail(`组件变体名称非法: ${name}`);
+    for (const key of Object.keys(component)) if (!componentProperties.has(key)) fail(`组件 ${name} 使用不支持的属性: ${key}`);
+  }
+  const references = [...source.matchAll(/\{(colors|typography|rounded|spacing)\.([\w-]+)\}/g)].map((match) => match[0]);
+  for (const reference of references) {
+    const [, group, token] = reference.match(/^\{([^}]+)\.([^}]+)\}$/);
+    if (frontmatter[group]?.[token] === undefined) fail(`悬空 token 引用: ${reference}`);
+  }
+  if (file === designPath && existsSync(syncMetadataPath)) {
+    const syncDocument = parseDocument(readFileSync(syncMetadataPath, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
+    if (syncDocument.errors.length) fail(syncDocument.errors[0].message);
+    const sync = syncDocument.toJS({ maxAliasCount: 0 })?.design_system_sync;
+    if (!sync?.baseline_sha256 || sync.baseline_sha256 !== sha256(source)) {
+      fail("design-system-sync.yaml 的 baseline_sha256 与 DESIGN.md 不一致，请更新跨仓同步摘要");
+    }
+    if (!Array.isArray(sync.synchronized_sections) || sync.synchronized_sections.length === 0) {
+      fail("design-system-sync.yaml 缺少 synchronized_sections");
+    }
+  }
+  return { source, frontmatter };
+}
+
+function runUpstream(args) {
+  const result = spawnSync("npx", ["--yes", "@google/design.md@0.4.0", ...args], { cwd: repositoryRoot, encoding: "utf8" });
+  if (result.error || result.status !== 0) fail(result.stderr?.trim() || result.stdout?.trim() || "design.md CLI 执行失败");
+  return result.stdout;
+}
+
+function projectionFiles() {
+  return ["theme.json", "tokens.default.json", "tokens.dark.json", "tokens.compact.json", "variables.css", "variables.dark.css"].map((file) => path.join(projectionDir, file));
+}
+
+function writeProjectionManifest() {
+  const { source } = readDesign();
+  const files = Object.fromEntries(projectionFiles().map((file) => [path.relative(repositoryRoot, file), sha256(readFileSync(file))]));
+  writeFileSync(manifestPath, `${JSON.stringify({ schema_version: 1, source: "DESIGN.md", source_sha256: sha256(source), files }, null, 2)}\n`);
+}
+
+function writeThemeProjection(frontmatter) {
+  const themeFile = path.join(projectionDir, "theme.json");
+  const theme = { token: {}, algorithm: "default" };
+  const token = theme.token || (theme.token = {});
+  const colors = frontmatter.colors;
+  const typography = frontmatter.typography;
+  const rounded = frontmatter.rounded;
+  const spacing = frontmatter.spacing;
+  Object.assign(token, {
+    colorPrimary: colors.primary,
+    colorSuccess: colors.success,
+    colorWarning: colors.warning,
+    colorError: colors.error,
+    colorInfo: colors.info ?? colors.primary,
+    colorTextBase: "#000000",
+    colorBgBase: colors.surface ?? "#ffffff",
+    colorBgLayout: colors["canvas-layout"] ?? "#f0f2f5",
+    colorText: colors.text,
+    colorTextSecondary: colors["text-secondary"],
+    colorBorder: colors.border ?? "#d9d9d9",
+    fontFamily: typography.body.fontFamily,
+    fontSize: Number.parseInt(typography.body.fontSize, 10),
+    borderRadius: Number.parseInt(rounded.md, 10),
+    sizeUnit: Number.parseInt(spacing.xxs, 10),
+    sizeStep: Number.parseInt(spacing.xxs, 10),
+    controlHeight: Number.parseInt(frontmatter.components["button-primary"].height, 10),
+    controlHeightSM: Number.parseInt(frontmatter.components["button-small"].height, 10),
+    controlHeightLG: Number.parseInt(frontmatter.components["button-large"].height, 10),
+    fontSizeSM: Number.parseInt(typography.caption.fontSize, 10),
+    borderRadiusSM: Number.parseInt(rounded.sm, 10),
+    borderRadiusLG: Number.parseInt(rounded.lg, 10),
+    padding: Number.parseInt(spacing.md, 10),
+    paddingSM: Number.parseInt(spacing.sm, 10),
+    paddingXS: Number.parseInt(spacing.xs, 10),
+    paddingLG: Number.parseInt(spacing.card, 10)
+  });
+  theme.components = { Card: { borderRadiusLG: token.borderRadiusLG, paddingLG: token.paddingLG } };
+  writeFileSync(themeFile, `${JSON.stringify(theme, null, 2)}\n`);
+}
+
+function writeAlgorithmProjections(toolchain) {
+  if (!toolchain) fail("export --write 需要 --antd-toolchain <独立作者工具目录>，固定 antd 6.6.4");
+  const require = createRequire(path.join(path.resolve(toolchain), "package.json"));
+  if (require("antd/package.json").version !== "6.6.4") fail("主题算法需要 antd 6.6.4");
+  const { theme } = require("antd");
+  const config = JSON.parse(readFileSync(path.join(projectionDir, "theme.json")));
+  const kebab = key => key.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+  const snapshots = {};
+  for (const [mode, algorithm] of Object.entries({ default: theme.defaultAlgorithm, dark: theme.darkAlgorithm, compact: theme.compactAlgorithm })) {
+    const token = { ...config.token };
+    // Let the dark algorithm derive neutral colors instead of pinning light aliases.
+    if (mode === "dark") for (const key of ["colorBgBase", "colorTextBase", "colorBgLayout", "colorText", "colorTextSecondary", "colorBorder"]) delete token[key];
+    snapshots[mode] = theme.getDesignToken({ token, algorithm });
+    writeFileSync(path.join(projectionDir, `tokens.${mode}.json`), JSON.stringify(snapshots[mode], null, 2) + "\n");
+  }
+  const rewrite = (css, token) => {
+    const values = Object.fromEntries(Object.entries(token).map(([key,value]) => [kebab(key),value]));
+    return css.replace(/(--brand-([\w-]+):\s*)([^;]+);/g, (all, prefix, key, old) => {
+      const value = values[key];
+      if (value === undefined || typeof value === "object") return all;
+      const unit = typeof value === "number" ? old.trim().match(/(?:px|ms|s)$/)?.[0] || "" : "";
+      return `${prefix}${value}${unit};`;
+    });
+  };
+  const cssPath = path.join(projectionDir, "variables.css");
+  const css = readFileSync(cssPath, "utf8");
+  const darkStart = css.indexOf('[data-theme="dark"]');
+  writeFileSync(cssPath, darkStart < 0 ? rewrite(css, snapshots.default) : rewrite(css.slice(0, darkStart), snapshots.default) + rewrite(css.slice(darkStart), snapshots.dark));
+  const darkPath = path.join(projectionDir, "variables.dark.css");
+  writeFileSync(darkPath, rewrite(readFileSync(darkPath, "utf8"), snapshots.dark));
+}
+
+function driftCheck() {
+  const { source, frontmatter } = readDesign();
+  validateCssProjection(frontmatter);
+  if (!existsSync(manifestPath)) fail(`缺少 ${path.relative(repositoryRoot, manifestPath)}，请先执行 export --write-manifest`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.source_sha256 !== sha256(source)) fail("DESIGN.md 已变化但投影未重新生成（source_sha256 漂移）");
+  for (const [relative, digest] of Object.entries(manifest.files || {})) {
+    const file = path.join(repositoryRoot, relative);
+    if (!existsSync(file) || sha256(readFileSync(file)) !== digest) fail(`派生文件漂移: ${relative}`);
+  }
+}
+
+function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "lint") {
+    const file = args.find((arg) => !arg.startsWith("-")) || designPath;
+    readDesign(path.resolve(repositoryRoot, file));
+    process.stdout.write(`${runUpstream(["lint", file, "--format", "json"])}`);
+    return;
+  }
+  if (command === "diff") {
+    if (args.length < 2) fail("用法: design-md diff <before> <after>");
+    process.stdout.write(runUpstream(["diff", ...args.slice(0, 2), "--format", "json"]));
+    return;
+  }
+  if (command === "export") {
+    const format = args[0] || "dtcg";
+    const { frontmatter } = readDesign();
+    process.stdout.write(runUpstream(["export", "DESIGN.md", "--format", format]));
+    if (args.includes("--write")) {
+      const toolchain = args[args.indexOf("--antd-toolchain") + 1];
+      if (!args.includes("--antd-toolchain") || !toolchain) fail("缺少 --antd-toolchain");
+      writeThemeProjection(frontmatter);
+      writeAlgorithmProjections(toolchain);
+      writeCssProjection(frontmatter);
+    }
+    if (args.includes("--write-manifest")) writeProjectionManifest();
+    return;
+  }
+  if (command === "drift") { driftCheck(); process.stdout.write("DESIGN.md 投影无漂移\n"); return; }
+  fail("用法: design-md lint|diff|export|drift");
+}
+
+try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/scripts/lib/skill-registry.mjs

@@ -65,10 +65,17 @@ export function loadSkillRegistry(filePath = DEFAULT_REGISTRY) {
 export function resolveSkillForNewUse(registry, requestedId) {
   requireString(requestedId, "requested skill id");
   if (OBSOLETE.has(requestedId)) {
+    const replacementSkill = requestedId === "grill-me" ? "grilling" : null;
     throw new SkillLifecycleError(
       SKILL_LIFECYCLE_FAILURE_CODES.retired,
-      `${requestedId} 已硬退役；按迁移 tombstone 重新路由`,
-      { skill: requestedId, migration_ref: "docs/agents/skill-migrations.md" }
+      replacementSkill
+        ? `${requestedId} 已硬退役；请使用 ${replacementSkill}`
+        : `${requestedId} 已硬退役；按迁移 tombstone 重新路由`,
+      {
+        skill: requestedId,
+        migration_ref: "docs/agents/skill-migrations.md",
+        ...(replacementSkill ? { replacement_skill: replacementSkill } : {})
+      }
     );
   }
   const aliases = new Map((registry.skills ?? []).flatMap((skill) => (skill.aliases ?? []).map((alias) => [alias, skill.id])));

package/template/scripts/lib/skill-supply-chain.mjs

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,7 +10,7 @@ const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
 export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];
-export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
+export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
 for (const id of ["component-selection-imports", "page-form-module", "page-list-module", "page-skeleton", "vue3-best-practices", "yss-use-table-height", "yss-use-tree-height", "yss-components", "yss-mvc-scaffold-generator", "yss-mvc-design", "yss-mvc-data-analysis-project-initializer", "yss-backend-scaffold-parent", "yss-backend-scaffold-adapter", "yss-application-layer-reference", "yss-domain-layer-reference", "yss-infrastructure-layer-reference", "yss-web-layer-reference"]) OBSOLETE.add(id);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
@@ -49,6 +49,21 @@ export function treeHash(directory) {
   return digest.digest("hex");
 }
 
+// treeHash is the published, normalized Skill digest. A no-op copy needs the
+// stricter filesystem comparison so modes, links and raw line endings survive.
+function projectionMatchesSource(source, target) {
+  const sourceInfo = lstatSafe(source);
+  const targetInfo = lstatSafe(target);
+  if (!sourceInfo || !targetInfo || (sourceInfo.mode & 0o7777) !== (targetInfo.mode & 0o7777)) return false;
+  if (sourceInfo.isSymbolicLink()) return targetInfo.isSymbolicLink() && readlinkSync(source) === readlinkSync(target);
+  if (sourceInfo.isFile()) return targetInfo.isFile() && readFileSync(source).equals(readFileSync(target));
+  if (!sourceInfo.isDirectory() || !targetInfo.isDirectory()) return false;
+  const sourceNames = readdirSync(source).sort();
+  const targetNames = readdirSync(target).sort();
+  return sourceNames.length === targetNames.length && sourceNames.every((name, index) =>
+    name === targetNames[index] && projectionMatchesSource(path.join(source, name), path.join(target, name)));
+}
+
 /**
  * 校验并返回 YSS UI 前端 skills 与 MCP 的上游集成合同。
  *
@@ -156,13 +171,12 @@ export function unlockedCanonicalEntries(names, allowedNames, hasSkillMd = () =>
   const allowed = new Set(allowedNames);
   return names.filter((name) => !allowed.has(name) && !OBSOLETE.has(name) && hasSkillMd(name)).sort();
 }
-export function syncSkills({ check = false } = {}) {
+export function syncSkills({ check = false, hashCache = new Map() } = {}) {
   let trackedSet;
   const tracked = ref => (trackedSet ??= trackedPaths()).has(ref);
-  const sourceHashes = new Map();
   const sourceHash = source => {
-    if (!sourceHashes.has(source)) sourceHashes.set(source, treeHash(source));
-    return sourceHashes.get(source);
+    if (!hashCache.has(source)) hashCache.set(source, treeHash(source));
+    return hashCache.get(source);
   };
   const lock = parseLock();
   const shared = sharedFromLock(lock);
@@ -192,10 +206,12 @@ export function syncSkills({ check = false } = {}) {
         else if (sourceHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
       } else if (info?.isSymbolicLink() && existsSync(target) && realpathSync(target) === realpathSync(source)) {
         continue;
+      } else if (info?.isDirectory() && tracked(relative(target)) && projectionMatchesSource(source, target)) {
+        continue;
       } else {
         rmSync(target, { recursive: true, force: true });
         if (!info || !tracked(relative(target))) symlinkSync(path.relative(projection, source), target, "dir");
-        else cpSync(source, target, { recursive: true, preserveTimestamps: true });
+        else cpSync(source, target, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
       }
     }
     for (const name of OBSOLETE) {
@@ -230,11 +246,12 @@ function sourceRevisionMap(oldLock, arguments_) {
   }
   return sources;
 }
-function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null) {
+function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null, hashCache = new Map()) {
   const old = previous[name] ?? {};
   let recordedPath = old.skillPath ?? skillPath;
   if (canonical && /^\.(codex|cursor|pi)\/skills\//.test(recordedPath)) recordedPath = skillPath;
-  const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
+  if (!hashCache.has(directory)) hashCache.set(directory, treeHash(directory));
+  const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: hashCache.get(directory) };
   const sourceInfo = sources[result.source];
   if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;
   let upstreamDirectory = null;
@@ -249,7 +266,7 @@ function metadata(name, skillPath, directory, previous, canonical = false, sourc
   }
   return result;
 }
-export function updateSkillLock(arguments_ = process.argv.slice(2)) {
+export function updateSkillLock(arguments_ = process.argv.slice(2), { hashCache = new Map() } = {}) {
   const oldLock = parseLock(); const previous = priorMetadata(oldLock); const sources = sourceRevisionMap(oldLock, arguments_); const upstreamRoot = option(arguments_, "upstream-root");
   const yssUiManifest = loadYssUiSkillManifest();
   sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
@@ -269,7 +286,7 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   if (unlocked.length) throw new TypeError(`发现未登记到 skills-lock.json 的已跟踪共享 skills: ${unlocked.join(", ")}\n确认新增后运行 scripts/update-skill-lock --add=<skill-name>`);
   const targets = [".agents/skills", ...PROJECTION_ROOTS];
   const shared = Object.fromEntries(sharedNames.map((name) => {
-    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot);
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot, hashCache);
     const yssUiSkill = yssUiSkills.get(name);
     if (yssUiSkill) {
       item.source = yssUiManifest.source;
@@ -300,10 +317,12 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
     if (!names.length) continue;
     const absentPlatform = names.filter((name) => !lstatSafe(path.join(location, name))?.isDirectory());
     if (absentPlatform.length) throw new TypeError(`锁文件声明的平台 skills 缺少内容 (${root}): ${absentPlatform.join(", ")}`);
-    platform[root] = Object.fromEntries(names.map((name) => { const item = metadata(name, `${root}/${name}/SKILL.md`, path.join(location, name), previous, false, sources, upstreamRoot); item.targets = [root]; return [name, item]; }));
+    platform[root] = Object.fromEntries(names.map((name) => { const item = metadata(name, `${root}/${name}/SKILL.md`, path.join(location, name), previous, false, sources, upstreamRoot, hashCache); item.targets = [root]; return [name, item]; }));
   }
   const manifest = { version: 3, generatedBy: "scripts/update-skill-lock", canonicalRoot: ".agents/skills", projectionRoots: PROJECTION_ROOTS, sources, skills: { shared, platform } };
   const rendered = `${JSON.stringify(manifest, null, 2)}\n`;
-  if (arguments_.includes("--check")) { if (!existsSync(LOCK_PATH) || readFileSync(LOCK_PATH, "utf8") !== rendered) throw new TypeError("skills-lock.json is stale; run scripts/update-skill-lock"); return "skills-lock.json matches distributed skills"; }
-  writeFileSync(LOCK_PATH, rendered); return `updated skills-lock.json with ${sharedNames.length} shared skills and ${Object.values(platform).reduce((sum, group) => sum + Object.keys(group).length, 0)} platform skills`;
+  const current = existsSync(LOCK_PATH) ? readFileSync(LOCK_PATH, "utf8") : null;
+  if (arguments_.includes("--check")) { if (current !== rendered) throw new TypeError("skills-lock.json is stale; run scripts/update-skill-lock"); return "skills-lock.json matches distributed skills"; }
+  if (current !== rendered) writeFileSync(LOCK_PATH, rendered);
+  return `updated skills-lock.json with ${sharedNames.length} shared skills and ${Object.values(platform).reduce((sum, group) => sum + Object.keys(group).length, 0)} platform skills`;
 }

package/template/scripts/verify-project-instance

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { loadRegistry, validateRegistry } from "./lib/lifecycle-registry.mjs";
+import { syncSkills, updateSkillLock } from "./lib/skill-supply-chain.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const identityPath = path.join(root, "yss-project.yaml");
@@ -16,18 +17,18 @@ if (identity?.schema_version !== 1 || identity?.repository_mode !== "project-ins
   throw new TypeError("verify-project-instance 仅适用于合法 project-instance");
 }
 
-const commands = [
-  ["scripts/sync-skills", ["--check"]],
-  ["scripts/update-skill-lock", ["--check"]],
-  ["scripts/verify-context-contract", ["--root", ".", "--json"]],
-];
-for (const [command, args] of commands) {
+const commands = ["scripts/sync-skills", "scripts/update-skill-lock", "scripts/verify-context-contract"];
+for (const command of commands) {
   const executable = path.join(root, command);
   if (!existsSync(executable)) throw new TypeError(`缺少项目实例校验入口: ${command}`);
-  const result = spawnSync(executable, args, { cwd: root, encoding: "utf8" });
-  if (result.status !== 0) {
-    throw new TypeError(result.stderr.trim() || result.stdout.trim() || `${command} 校验失败`);
-  }
+}
+const hashCache = new Map();
+syncSkills({ check: true, hashCache });
+updateSkillLock(["--check"], { hashCache });
+const command = "scripts/verify-context-contract";
+const result = spawnSync(path.join(root, command), ["--root", ".", "--json"], { cwd: root, encoding: "utf8" });
+if (result.status !== 0) {
+  throw new TypeError(result.stderr.trim() || result.stdout.trim() || `${command} 校验失败`);
 }
 validateRegistry(loadRegistry());
 process.stdout.write("项目实例校验通过\n");

package/template/skills-lock.json

@@ -18,7 +18,7 @@
       "revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f"
     },
     "iloveZzz/yss-harness-design-agent": {
-      "revision": "9e17922a0a718e5bd1845ddab11850a2f43becad"
+      "revision": "9b579c7b954c153d2347696f53123aebaccde48f"
     },
     "ayghri/i-have-adhd": {
       "revision": "7b9069b39972e269e61bd95c2f66ebb90cac6a02"
@@ -226,21 +226,6 @@
           ".pi/skills"
         ]
       },
-      "grill-me": {
-        "source": "mattpocock/skills",
-        "sourceType": "github",
-        "skillPath": "skills/productivity/grill-me/SKILL.md",
-        "effectiveHash": "916cf7ff0d81cf47fe578bd86695e09a53fbe8a4b371586e19dde6573549e88d",
-        "sourceRevision": "0ab1b63a410a03d3627979a109c8695de27af954",
-        "upstreamHash": "5a13e157f85835632b132390a162d234822658b6a544f31cc2578280062bd044",
-        "adaptationRef": "docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md",
-        "targets": [
-          ".agents/skills",
-          ".codex/skills",
-          ".cursor/skills",
-          ".pi/skills"
-        ]
-      },
       "grill-with-docs": {
         "source": "mattpocock/skills",
         "sourceType": "github",
@@ -425,7 +410,7 @@
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/prototype-review/SKILL.md",
         "effectiveHash": "410ed10f248f6eb396cd50cea905032e45ec9b203aad41dbf78dbd03aba84b55",
-        "sourceRevision": "9e17922a0a718e5bd1845ddab11850a2f43becad",
+        "sourceRevision": "9b579c7b954c153d2347696f53123aebaccde48f",
         "upstreamHash": "6df02dd4de236a749a80efd5eba46d18be7979849af2a9af28636906ccfcb2a0",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
@@ -682,7 +667,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-cache/SKILL.md",
-        "effectiveHash": "aa18e0996bdc49f0d7ee4a75f49f8ab765259ec3b60d6e9bfe871c3c2f6a8346",
+        "effectiveHash": "64a24a5108feae462d5cf53d2892a27e9ae00c552e6a184f8b59c7dcafe9b62d",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -707,7 +692,7 @@
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-design-system/SKILL.md",
         "effectiveHash": "b3ddbff30926f6675ac60cbf89182593df7ed272d7a1dc75f657f7640960c1b8",
-        "sourceRevision": "9e17922a0a718e5bd1845ddab11850a2f43becad",
+        "sourceRevision": "9b579c7b954c153d2347696f53123aebaccde48f",
         "upstreamHash": "e156229435c35827c48d3699b021e5e171ec565c2bf91cc91cbb033bf7802d7c",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
@@ -721,7 +706,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-distributed-id/SKILL.md",
-        "effectiveHash": "07f3915e94a37c47178f23e97720be9c293fa7019d48e7dbf1e5d2d8856029a5",
+        "effectiveHash": "d7e61711f9ccc8a1f5a7c768f4016cd57bbcd3ff9d5fc0375c550ea387a68d31",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -856,7 +841,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-mybatis/SKILL.md",
-        "effectiveHash": "c844472c366438f0c84d22246a82eca645753cf562a909c8857d4a621bf5ad7c",
+        "effectiveHash": "59cc457511213d05c1cd5a035f41f22ca14d77f296be7e7a4ccc9067f0f158b3",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -892,7 +877,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-product-lifecycle/SKILL.md",
-        "effectiveHash": "0904753ec31459a719530aae71864e5a8f2d8acef66f64065c7e2848a362c23e",
+        "effectiveHash": "509c9a2b5bbb8e4c1a0b72bd59e75ef3cde0d70452a0c9d7ffa5864a737814ba",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -904,8 +889,8 @@
         "source": "iloveZzz/yss-harness-design-agent",
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-prototype-stage/SKILL.md",
-        "effectiveHash": "4cc7d388f89feddf50d208b2d5db3a4ffa41974afb364328270c097970fc39c0",
-        "sourceRevision": "9e17922a0a718e5bd1845ddab11850a2f43becad",
+        "effectiveHash": "ac8390003dd1cf661cf01f9b13fdb37f16463810af0c74fe9a8428cc569a5167",
+        "sourceRevision": "9b579c7b954c153d2347696f53123aebaccde48f",
         "upstreamHash": "6e1bcdf107d95c11faee2b988e4e0c36b8e5b76f6b40312a206b83733a96b0fc",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
@@ -919,7 +904,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-repository/SKILL.md",
-        "effectiveHash": "b70b05ba98192eaf3f463d5409e43ed221d53ed097c00bf740364c786954de96",
+        "effectiveHash": "4c67dbfa563761b60668e4622ae7043ded94458f29b2ad0525fd53fa6c98d672",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -983,7 +968,7 @@
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-stage-decision/SKILL.md",
         "effectiveHash": "43a83bc02fea3c36105be6791ad019036b7ea1a17e5f0704daf93fb7be29b60b",
-        "sourceRevision": "9e17922a0a718e5bd1845ddab11850a2f43becad",
+        "sourceRevision": "9b579c7b954c153d2347696f53123aebaccde48f",
         "upstreamHash": "f7f765e20f4dca6aca667be03e2b9a7f2a8acc3510eefba88306961882d86ed4",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [

package/template.manifest.json

@@ -101,11 +101,26 @@
     ".gitignore",
     "AGENTS.md",
     "README.md",
+    "skills-lock.json",
+    "docs/user-guide/用户手册.md",
+    "docs/user-guide/用户手册索引.md",
+    "docs/user-guide/阶段接入与产物复用使用手册.md",
+    "docs/user-guide/技术设计用户指南.md",
+    "docs/design/README.md",
+    "docs/engineering/backend-platforms.json",
+    "scripts/lib/skill-supply-chain.mjs",
+    "docs/agents/backend-architecture-profiles.md",
+    ".agents/skills/yss-design-system/SKILL.md",
+    ".agents/skills/yss-design-system/references/data-quality-theme.md",
+    ".codex/skills/yss-design-system/SKILL.md",
+    ".codex/skills/yss-design-system/references/data-quality-theme.md",
+    ".cursor/skills/yss-design-system/SKILL.md",
+    ".cursor/skills/yss-design-system/references/data-quality-theme.md",
+    ".pi/skills/yss-design-system/SKILL.md",
+    ".pi/skills/yss-design-system/references/data-quality-theme.md",
     "yss-project.yaml"
   ],
-  "exampleDocPaths": [
-    "docs/plan/IDEATION.md"
-  ],
+  "exampleDocPaths": [],
   "initExcludeRootEntries": [],
   "initExcludeRootFiles": [
     "yss-public-skills.json"

package/template.snapshot.json

@@ -3,10 +3,10 @@
   "templateName": "yss-spec-project-template",
   "templateSource": "github:iloveZzz/yss-spec-project-template",
   "templateRepository": "https://github.com/iloveZzz/yss-spec-project-template.git",
-  "requestedRef": "445172278b7a107ac42ec00ee1dd936bdd244933",
-  "templateCommit": "445172278b7a107ac42ec00ee1dd936bdd244933",
+  "requestedRef": "085a80540035c6430a2dff1fb3fb7396469152df",
+  "templateCommit": "085a80540035c6430a2dff1fb3fb7396469152df",
   "sourceState": "committed",
-  "manifestHash": "7c2fe5e36a464fd32b4ec6466e18e8c762a59bda9cb5b598950aba7dd6358891",
+  "manifestHash": "d60babd9ea2ec16ee054c0c3f467379ba42915b348e1a0451c2975a60c4496d0",
   "encodedPaths": {
     ".agents/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/.gitignore": ".agents/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/__yss_dotfile__.gitignore",
     ".codex/skills/data-analytics/.gitignore": ".codex/skills/data-analytics/__yss_dotfile__.gitignore",
@@ -17,6 +17,6 @@
     ".gitignore": "__yss_dotfile__.gitignore",
     ".pi/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/.gitignore": ".pi/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/__yss_dotfile__.gitignore"
   },
-  "snapshotHash": "7a8f13451bd03f54c57a0b4fa3f713fcf0e43601212590a3fb6e8e5db34f5b37",
-  "generatedAt": "2026-09-22T11:13:45.412Z"
+  "snapshotHash": "11dfca9873c856b70ec0ae6309e9e391143c4fc102a92553bd118b19640ead16",
+  "generatedAt": "2026-09-24T13:20:11.384Z"
 }

package/template/.agents/skills/grill-me/SKILL.md

@@ -1,7 +0,0 @@
----
-name: grill-me
-description: A relentless interview to sharpen a plan or design.
-disable-model-invocation: true
----
-
-Call the Skill tool with `grilling`.

package/template/.agents/skills/grill-me/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill Me"
-  short_description: "Sharpen a plan through interview"
-policy:
-  allow_implicit_invocation: false