create-yss-spec 2.1.10 → 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", "batch-grill-me"]);
+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) {
@@ -115,7 +118,7 @@ function sourceRevisionMap(oldLock, arguments_) {
 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) };
   const sourceInfo = sources[result.source];
   if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;

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 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-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,6 +18,7 @@ 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
@@ -36,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-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence 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)