create-yss-spec 2.1.9 → 2.1.11

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

@@ -0,0 +1,198 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { PROJECTION_ROOTS, ROOT } from "./skill-supply-chain.mjs";
+
+export const DEFAULT_REGISTRY = path.join(ROOT, "docs/agents/yss-skill-registry.yaml");
+const LOCK_PATH = path.join(ROOT, "skills-lock.json");
+const ROUTER_CONTRACT = path.join(ROOT, ".agents/skills/yss-router/references/router-contract.yaml");
+const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
+const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function yamlFromFile(filePath, label) {
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
+    throw error;
+  }
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
+  return value;
+}
+
+export function loadSkillRegistry(filePath = DEFAULT_REGISTRY) {
+  return yamlFromFile(filePath, "技能路由注册表");
+}
+
+function frontmatterName(skillMd) {
+  const match = skillMd.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) fail("SKILL.md 缺少 frontmatter");
+  const name = match[1].match(/^name:\s*["']?([a-z0-9-]+)["']?\s*$/m);
+  if (!name) fail("SKILL.md frontmatter 缺少 name");
+  return name[1];
+}
+
+function requireString(value, field) {
+  if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`);
+}
+
+export function validateSkillRegistry(registry, { lock, routerContract, skillSource } = {}) {
+  if (!registry || typeof registry !== "object" || Array.isArray(registry)) fail("技能路由注册表必须是对象");
+  if (registry.schema_version !== 1) fail("schema_version 必须为 1");
+  if (registry.registry_id !== "yss.skill-routing") fail("registry_id 必须为 yss.skill-routing");
+  if (!["shadow", "active"].includes(registry.status)) fail("status 必须是 shadow 或 active");
+  requireString(registry.description, "description");
+  requireString(registry.canonical_content_root, "canonical_content_root");
+  if (registry.canonical_content_root !== ".agents/skills") fail("canonical_content_root 必须为 .agents/skills");
+  const runtime = registry.runtime_policy;
+  if (!runtime || typeof runtime !== "object") fail("缺少 runtime_policy");
+  if (typeof runtime.consumed_by_router !== "boolean" || typeof runtime.consumed_by_lifecycle !== "boolean" || typeof runtime.discovery_enforced !== "boolean") {
+    fail("runtime_policy 必须声明 consumed_by_router、consumed_by_lifecycle、discovery_enforced");
+  }
+  if (registry.status === "shadow" && (runtime.consumed_by_router || runtime.consumed_by_lifecycle || runtime.discovery_enforced)) {
+    fail("shadow 注册表不得被 Router、生命周期或发现面强制消费");
+  }
+  const roots = registry.agent_runtime_roots;
+  if (!roots || typeof roots !== "object" || Array.isArray(roots)) fail("缺少 agent_runtime_roots");
+  const expected = {
+    claude: ".claude/skills",
+    codex: ".codex/skills",
+    cursor: ".cursor/skills",
+    hermes: ".hermes/skills",
+    pi: ".pi/skills",
+    qoder: ".qoder/skills",
+    trae: ".trae/skills"
+  };
+  for (const [agent, root] of Object.entries(expected)) {
+    if (roots[agent] !== root) fail(`agent_runtime_roots.${agent} 必须为 ${root}`);
+  }
+  const extraAgents = Object.keys(roots).filter((key) => !(key in expected));
+  if (extraAgents.length) fail(`未知 Agent 运行时根: ${extraAgents.join(", ")}`);
+  if (JSON.stringify(Object.values(expected).sort()) !== JSON.stringify([...PROJECTION_ROOTS].sort())) {
+    fail("agent_runtime_roots 与投影根清单不一致");
+  }
+
+  const skills = registry.skills;
+  if (!Array.isArray(skills) || skills.length === 0) fail("skills 不能为空");
+  const ids = new Set();
+  const aliases = new Map();
+  for (const [index, skill] of skills.entries()) {
+    const prefix = `skills[${index}]`;
+    if (!skill || typeof skill !== "object" || Array.isArray(skill)) fail(`${prefix} 必须是对象`);
+    requireString(skill.id, `${prefix}.id`);
+    if (!ID_PATTERN.test(skill.id)) fail(`${prefix}.id 非法: ${skill.id}`);
+    if (ids.has(skill.id)) fail(`重复 skill id: ${skill.id}`);
+    ids.add(skill.id);
+  }
+  for (const [index, skill] of skills.entries()) {
+    const prefix = `skills[${index}]`;
+    if (!LAYERS.has(skill.layer)) fail(`${skill.id} 未知 layer: ${skill.layer}`);
+    if (!MATURITIES.has(skill.maturity)) fail(`${skill.id} 未知 maturity: ${skill.maturity}`);
+    if (typeof skill.instance_default_discoverable !== "boolean") fail(`${skill.id} 缺少 instance_default_discoverable`);
+    if (skill.layer === "core" && skill.instance_default_discoverable !== true) fail(`${skill.id} 作为 core 必须默认可发现`);
+    if ((skill.layer === "specialist" || skill.layer === "maintainer-only") && skill.instance_default_discoverable !== false) {
+      fail(`${skill.id} 作为 ${skill.layer} 不得默认可发现`);
+    }
+    if (skill.maturity === "deprecated") requireString(skill.replaced_by, `${skill.id}.replaced_by`);
+    if (skill.replaced_by && !ids.has(skill.replaced_by) && !skills.some((item) => item.id === skill.replaced_by)) {
+      // resolved in second pass
+    }
+    if (!Array.isArray(skill.aliases) || skill.aliases.some((alias) => typeof alias !== "string" || !ID_PATTERN.test(alias))) {
+      fail(`${skill.id} aliases 必须是合法 id 数组`);
+    }
+    for (const alias of skill.aliases) {
+      if (alias === skill.id) fail(`${skill.id} 不得把自身列为 alias`);
+      if (aliases.has(alias) || ids.has(alias)) fail(`alias 冲突: ${alias}`);
+      aliases.set(alias, skill.id);
+    }
+    if (!Array.isArray(skill.impacts) || skill.impacts.length === 0 || skill.impacts.some((item) => typeof item !== "string" || !item.trim())) {
+      fail(`${skill.id} impacts 不能为空`);
+    }
+  }
+  for (const skill of skills) {
+    if (skill.replaced_by && !ids.has(skill.replaced_by)) fail(`${skill.id}.replaced_by 引用了未登记技能: ${skill.replaced_by}`);
+  }
+
+  const platform = registry.platform_skills ?? [];
+  if (!Array.isArray(platform)) fail("platform_skills 必须是数组");
+  const platformIds = new Set();
+  for (const skill of platform) {
+    requireString(skill.id, "platform_skills.id");
+    requireString(skill.root, `${skill.id}.root`);
+    if (!LAYERS.has(skill.layer)) fail(`${skill.id} 未知 layer`);
+    if (typeof skill.instance_default_discoverable !== "boolean" || skill.instance_default_discoverable !== false) {
+      fail(`${skill.id} 平台技能不得作为实例默认可发现`);
+    }
+    if (platformIds.has(`${skill.root}:${skill.id}`)) fail(`重复平台技能: ${skill.root}/${skill.id}`);
+    platformIds.add(`${skill.root}:${skill.id}`);
+  }
+
+  if (lock) {
+    const shared = Object.keys(lock.skills?.shared ?? {}).sort();
+    const registered = [...ids].sort();
+    const missing = shared.filter((name) => !ids.has(name));
+    const extra = registered.filter((name) => !shared.includes(name));
+    if (missing.length) fail(`注册表缺少锁文件共享技能: ${missing.join(", ")}`);
+    if (extra.length) fail(`注册表包含未锁定共享技能: ${extra.join(", ")}`);
+    const platformLock = lock.skills?.platform ?? {};
+    for (const [root, group] of Object.entries(platformLock)) {
+      for (const name of Object.keys(group)) {
+        if (!platformIds.has(`${root}:${name}`)) fail(`注册表缺少平台技能 ${root}/${name}`);
+      }
+    }
+    for (const key of platformIds) {
+      const [root, name] = key.split(":");
+      if (!platformLock[root]?.[name]) fail(`注册表平台技能未出现在锁文件: ${root}/${name}`);
+    }
+    if (JSON.stringify(lock.projectionRoots) !== JSON.stringify(PROJECTION_ROOTS)) {
+      fail("skills-lock.json projectionRoots 与权威投影清单不一致");
+    }
+  }
+
+  if (skillSource) {
+    for (const skill of skills) {
+      const skillMd = skillSource(skill.id);
+      const discovered = frontmatterName(skillMd);
+      if (discovered !== skill.id && aliases.get(discovered) !== skill.id) {
+        fail(`${skill.id} 的 SKILL.md name=${discovered} 既不是 id 也不在 aliases 中`);
+      }
+    }
+  }
+
+  if (routerContract) {
+    const declared = routerContract.skill_aliases;
+    if (!declared || typeof declared !== "object" || Array.isArray(declared)) fail("router-contract.yaml 缺少 skill_aliases");
+    for (const [alias, canonical] of Object.entries(declared)) {
+      if (aliases.get(alias) !== canonical) fail(`router-contract alias ${alias} -> ${canonical} 与注册表不一致`);
+    }
+    for (const [alias, canonical] of aliases.entries()) {
+      if (declared[alias] !== canonical) fail(`注册表 alias ${alias} 未写入 router-contract.skill_aliases`);
+    }
+    const closures = Object.keys(routerContract.dependency_closure ?? {});
+    for (const name of closures) {
+      if (!ids.has(name) && !aliases.has(name)) fail(`Router 闭包引用了未登记技能: ${name}`);
+    }
+  }
+
+  return { skill_count: skills.length, platform_count: platform.length, status: registry.status };
+}
+
+export function validateDefaultSkillRegistry() {
+  const registry = loadSkillRegistry();
+  const lock = JSON.parse(readFileSync(LOCK_PATH, "utf8"));
+  const routerContract = yamlFromFile(ROUTER_CONTRACT, "Router 合同");
+  return validateSkillRegistry(registry, {
+    lock,
+    routerContract,
+    skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8")
+  });
+}

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

@@ -7,8 +7,11 @@ import { fileURLToPath } from "node:url";
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
-const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
-const OBSOLETE = new Set(["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"]);
+export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
+export const OBSOLETE = new Set(["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", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
+export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
+  return names.filter((name) => obsolete.has(name)).sort();
+}
 
 function relative(target) { return path.relative(ROOT, target).replaceAll(path.sep, "/"); }
 function entries(directory) { return existsSync(directory) ? readdirSync(directory, { withFileTypes: true }) : []; }
@@ -51,7 +54,7 @@ export function syncSkills({ check = false } = {}) {
   const shared = sharedFromLock(lock);
   const absent = shared.filter((name) => !lstatSafe(path.join(SOURCE_ROOT, name))?.isDirectory());
   if (absent.length) throw new TypeError(`锁文件声明的共享 skills 缺少权威内容: ${absent.join(", ")}`);
-  const obsolete = shared.filter((name) => OBSOLETE.has(name));
+  const obsolete = [...new Set([...shared.filter((name) => OBSOLETE.has(name)), ...obsoleteCanonicalResidues(skillNames(SOURCE_ROOT))])];
   if (obsolete.length) throw new TypeError(`obsolete skills remain in canonical root: ${obsolete.join(", ")}`);
   const drift = [];
   for (const root of PROJECTION_ROOTS) {
@@ -59,7 +62,7 @@ export function syncSkills({ check = false } = {}) {
     ensureSafeProjection(projection);
     if (!check) mkdirSync(projection, { recursive: true });
     const allowed = [...shared, ...Object.keys(lock.skills?.platform?.[root] ?? {})];
-    for (const entry of unlockedProjectionEntries(entries(projection), allowed, (name) => tracked(relative(path.join(projection, name))))) {
+    for (const entry of unlockedProjectionEntries(entries(projection), allowed, (name) => tracked(relative(path.join(projection, name)))).filter((entry) => !OBSOLETE.has(entry.name))) {
       const target = path.join(projection, entry.name);
       if (!check && entry.isSymbolicLink() && !existsSync(target)) rmSync(target, { force: true });
       else drift.push(`unlocked projection: ${relative(target)}`);
@@ -96,16 +99,41 @@ function priorMetadata(lock) {
   if (!["shared", "platform"].some((key) => key in skills)) return skills;
   return { ...skills.shared, ...Object.values(skills.platform ?? {}).reduce((all, group) => ({ ...all, ...group }), {}), ...Object.fromEntries(Object.entries(skills).filter(([key]) => !["shared", "platform"].includes(key))) };
 }
-function metadata(name, skillPath, directory, previous, canonical = false) {
+function option(arguments_, name) {
+  const prefix = `--${name}=`;
+  const value = arguments_.find((argument) => argument.startsWith(prefix));
+  return value?.slice(prefix.length) || null;
+}
+function sourceRevisionMap(oldLock, arguments_) {
+  const sources = structuredClone(oldLock?.sources ?? {});
+  const revision = option(arguments_, "source-revision");
+  if (revision) {
+    const separator = revision.lastIndexOf(":");
+    if (separator <= 0 || separator === revision.length - 1) throw new TypeError("--source-revision 必须使用 source:revision 格式");
+    const source = revision.slice(0, separator);
+    sources[source] = { ...(sources[source] ?? {}), revision: revision.slice(separator + 1) };
+  }
+  return sources;
+}
+function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null) {
   const old = previous[name] ?? {};
   let recordedPath = old.skillPath ?? skillPath;
-  if (canonical && /^\.(claude|codex|hermes|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
+  if (canonical && /^\.(claude|codex|cursor|hermes|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
   const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
-  if (old.upstreamHash ?? old.computedHash) result.upstreamHash = old.upstreamHash ?? old.computedHash;
+  const sourceInfo = sources[result.source];
+  if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;
+  let upstreamDirectory = null;
+  if (upstreamRoot && result.source === "mattpocock/skills") {
+    upstreamDirectory = path.join(upstreamRoot, recordedPath).replace(/\/SKILL\.md$/, "");
+    if (!existsSync(upstreamDirectory)) throw new TypeError(`${name} 的上游路径不存在: ${recordedPath}`);
+    result.upstreamHash = treeHash(upstreamDirectory);
+  } else if (old.upstreamHash ?? old.computedHash) result.upstreamHash = old.upstreamHash ?? old.computedHash;
+  if (result.source === "mattpocock/skills" && result.upstreamHash && result.effectiveHash !== result.upstreamHash) result.adaptationRef = "docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md";
   return result;
 }
 export function updateSkillLock(arguments_ = process.argv.slice(2)) {
-  const oldLock = parseLock(); const previous = priorMetadata(oldLock);
+  const oldLock = parseLock(); const previous = priorMetadata(oldLock); const sources = sourceRevisionMap(oldLock, arguments_); const upstreamRoot = option(arguments_, "upstream-root");
+  if (upstreamRoot && !existsSync(upstreamRoot)) throw new TypeError(`--upstream-root 不存在: ${upstreamRoot}`);
   const additions = arguments_.filter((arg) => arg.startsWith("--add=")).map((arg) => arg.slice(6));
   const removals = new Set(arguments_.filter((arg) => arg.startsWith("--remove=")).map((arg) => arg.slice(9)));
   const platformAdds = arguments_.filter((arg) => arg.startsWith("--add-platform=")).map((arg) => arg.slice(15).split(":", 2));
@@ -117,7 +145,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); item.targets = targets; return [name, item];
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot); item.targets = targets; return [name, item];
   }));
   const platform = {};
   for (const root of PROJECTION_ROOTS) {
@@ -126,9 +154,9 @@ 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); 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); item.targets = [root]; return [name, item]; }));
   }
-  const manifest = { version: 3, generatedBy: "scripts/update-skill-lock", canonicalRoot: ".agents/skills", projectionRoots: PROJECTION_ROOTS, skills: { shared, platform } };
+  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`;

package/template/scripts/verify-frontend-implementation-evidence

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(root, "docs/process/schemas/frontend-implementation-evidence.schema.json");
+const validator = String.raw`
+import json
+import sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    location = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{location}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+
+try {
+  const { values, positionals } = parseArgs({ options: { "allow-template": { type: "boolean" } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-frontend-implementation-evidence [--allow-template] <file.yaml>");
+  const document = parseDocument(readFileSync(path.resolve(positionals[0]), "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  const value = document.toJS({ maxAliasCount: 0 });
+  const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
+  if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
+  if (!values["allow-template"] && value.template !== false) throw new TypeError("正式证据必须设置 template: false");
+  if (!values["allow-template"] && value.status !== "approved") throw new TypeError("正式证据必须达到 status: approved");
+  const serialized = JSON.stringify(value);
+  if (!values["allow-template"] && /REPLACE_ME|<[^>]+>|docs\/\.scratch\/example/.test(serialized)) throw new TypeError("正式证据不得保留模板占位值");
+  if (!values["allow-template"]) {
+    for (const field of ["prototype_ref", "spec_ref"]) {
+      const reference = value[field];
+      if (!/^https?:\/\//.test(reference) && !existsSync(path.resolve(root, reference))) throw new TypeError(`${field} 不可读取: ${reference}`);
+    }
+  }
+  if (!values["allow-template"] && value.kind === "verification") {
+    if (value.console_warning_check !== "pass") throw new TypeError("前端验证必须通过 console warning 检查");
+    if (value.uncovered_differences.length > 0 && !value.difference_owner) throw new TypeError("存在未覆盖差异时必须填写 difference_owner");
+    if (value.independent_review?.status !== "approved") throw new TypeError("前端验证必须通过独立 UI fidelity review");
+  }
+  process.stdout.write(`前端实现还原 ${value.kind} 验证通过\n`);
+} catch (error) {
+  process.stderr.write(`前端实现还原证据验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-lifecycle-checkpoint

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(root, "docs/process/schemas/lifecycle-checkpoint.schema.json");
+const validator = String.raw`
+import json
+import sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    location = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{location}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+
+try {
+  const { positionals } = parseArgs({ allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-lifecycle-checkpoint <checkpoint.yaml|checkpoint.json>");
+  const sourcePath = path.resolve(positionals[0]);
+  const document = parseDocument(readFileSync(sourcePath, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  const value = document.toJS({ maxAliasCount: 0 });
+  const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
+  if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
+  process.stdout.write("生命周期 checkpoint 验证通过\n");
+} catch (error) {
+  process.stderr.write(`生命周期 checkpoint 验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-skill-registry

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { validateDefaultSkillRegistry } from "./lib/skill-registry.mjs";
+
+try {
+  const result = validateDefaultSkillRegistry();
+  process.stdout.write(`技能路由注册表校验通过（${result.status}，${result.skill_count} 个共享，${result.platform_count} 个平台）\n`);
+} catch (error) {
+  process.stderr.write(`技能路由注册表校验失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-template

@@ -5,7 +5,7 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT_DIR"
 node -e 'const [major]=process.versions.node.split(".").map(Number); if (major < 22 || major >= 27) { console.error("模板工具需要 Node >=22 <27"); process.exit(1); }'
 
-required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json docs/process/maintenance-intensity.yaml scripts/repository-mode scripts/implementation-path-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/export-yss-skills)
+required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/agents/yss-skill-registry.yaml docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json docs/process/maintenance-intensity.yaml docs/process/schemas/lifecycle-checkpoint.schema.json docs/process/schemas/frontend-implementation-evidence.schema.json docs/process/templates/lifecycle-checkpoint-template.yaml docs/process/templates/frontend-implementation-plan-template.yaml docs/process/templates/frontend-implementation-verification-template.yaml scripts/repository-mode scripts/implementation-path-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/export-yss-skills)
 for required in "${required_files[@]}"; do test -f "$required" || { echo "缺少模板必需文件: $required" >&2; exit 1; }; done
 
 repository_mode="$(scripts/repository-mode)"
@@ -18,9 +18,13 @@ fi
 
 scripts/sync-skills --check
 scripts/update-skill-lock --check
+scripts/verify-skill-registry
 scripts/verify-yss-dto-openapi-profile
 scripts/verify-yss-dto-openapi-scenarios
 scripts/verify-lifecycle-registry
+scripts/verify-lifecycle-checkpoint docs/process/templates/lifecycle-checkpoint-template.yaml
+scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-plan-template.yaml
+scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-verification-template.yaml
 scripts/verify-lifecycle-scenarios
 scripts/verify-maintenance-intensity-scenarios
 scripts/verify-governance-release
@@ -33,7 +37,7 @@ scripts/verify-yss-ui-scenarios
 scripts/verify-openapi-yaml-first-scenarios
 scripts/verify-openapi-json-handoff-scenarios
 
-for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/export-yss-skills; do node --check "$entry"; done
+for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/export-yss-skills; do node --check "$entry"; done
 
 legacy_runtime="ru""by"
 script_roots=(scripts)

package/template/scripts/verify-upstream-skill-source

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { treeHash } from "./lib/skill-supply-chain.mjs";
+
+const root = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const args = process.argv.slice(2);
+const sourceRootArg = args.find((arg) => arg.startsWith("--source-root="))?.slice("--source-root=".length);
+if (!sourceRootArg) {
+  process.stderr.write("用法: scripts/verify-upstream-skill-source --source-root=<上游 checkout>\n");
+  process.exit(2);
+}
+const sourceRoot = path.resolve(sourceRootArg);
+const lock = JSON.parse(readFileSync(path.join(root, "skills-lock.json"), "utf8"));
+const source = "mattpocock/skills";
+const revision = lock.sources?.[source]?.revision;
+if (!revision) throw new TypeError(`锁文件缺少 ${source} source revision`);
+const git = spawnSync("git", ["-C", sourceRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
+if (git.status !== 0) throw new TypeError(`无法读取上游 checkout revision: ${sourceRoot}`);
+if (git.stdout.trim() !== revision) throw new TypeError(`上游 revision 不匹配: expected=${revision} actual=${git.stdout.trim()}`);
+
+const shared = lock.skills?.shared ?? {};
+for (const [name, item] of Object.entries(shared)) {
+  if (item.source !== source) continue;
+  if (item.sourceRevision !== revision) throw new TypeError(`${name} 缺少一致的 sourceRevision`);
+  const directory = path.dirname(path.join(sourceRoot, item.skillPath));
+  if (!existsSync(directory)) throw new TypeError(`${name} 的上游路径不存在: ${item.skillPath}`);
+  const actualHash = treeHash(directory);
+  if (actualHash !== item.upstreamHash) throw new TypeError(`${name} upstreamHash 不匹配: expected=${item.upstreamHash} actual=${actualHash}`);
+}
+process.stdout.write(`上游 ${source}@${revision} 及其 skill hashes 验证通过\n`);