create-yss-spec 3.0.0 → 3.1.0

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

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isTemplateSource } from "./repository-mode.mjs";
 import { loadSkillRegistry } from "./skill-registry.mjs";
-import { validateYssUiSkillManifest } from "./skill-supply-chain.mjs";
+import { treeHash, validateStrategicDesignSkillManifest, validateYssUiSkillManifest } from "./skill-supply-chain.mjs";
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -13,7 +14,19 @@ function fail(message) {
 export function validateSkillGovernance({ read = (relative) => readFileSync(path.join(ROOT, relative), "utf8"), exists = (relative) => existsSync(path.join(ROOT, relative)) } = {}) {
   const globalRules = read(".agents/rules/yss-ai-skills.md");
   const tableSkill = read(".agents/skills/ytable-usage/SKILL.md");
-  const pageSkill = read(".agents/skills/yss-page-module-development/SKILL.md");
+  const pageSkill = read(".agents/skills/yss-ui-business-page-generation/SKILL.md");
+
+  for (const marker of ["trigger: always_on", "docs/agents/yss-skill-registry.yaml", ".agents/skills/yss-ui/SKILL.md", "原型阶段"]) {
+    if (!globalRules.includes(marker)) fail(`YSS UI 薄入口缺少路由标记: ${marker}`);
+  }
+  for (const staleHeading of ["## Available Skills", "## Mandatory Workflow"]) {
+    if (globalRules.includes(staleHeading)) fail(`YSS UI 薄入口不得回流技能清单或实现步骤: ${staleHeading}`);
+  }
+  const cursorRules = read(".cursorrules");
+  for (const marker of ["yss-project.yaml", "docs/agents/yss-skill-registry.yaml", "yss-ui-business-page-generation", ".cursor/skills"]) {
+    if (!cursorRules.includes(marker)) fail(`Cursor 薄入口缺少路由标记: ${marker}`);
+  }
+  if (cursorRules.includes("YSS AI SKILLS START")) fail("Cursor 薄入口不得回流技能清单");
 
   if (/toolbar-config\.custom.{0,30}(必须|必需)|必须.{0,30}toolbar-config\.custom/.test(globalRules)) {
     fail("全局规则不得把 toolbar-config.custom 作为无条件要求");
@@ -24,8 +37,8 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   for (const marker of ["无需配置 `:toolbar-config=\"{ custom: true }\"`", "仅在业务明确需要列设置时才传入"]) {
     if (!tableSkill.includes(marker)) fail(`YTable 专项技能缺少条件化工具栏规则: ${marker}`);
   }
-  if (!pageSkill.includes("只有确实需要列设置时才启用 `toolbar-config.custom`")) {
-    fail("页面模块 canonical 技能缺少条件化 toolbar-config 规则");
+  if (!pageSkill.includes("仅在业务明确需要列设置时才传入")) {
+    fail("业务页面 canonical 技能缺少条件化 toolbar-config 规则");
   }
 
   const yssUiManifest = validateYssUiSkillManifest(JSON.parse(read(".agents/skills/.yss-skills-manifest.json")));
@@ -48,6 +61,7 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   const yssUiSkill = read(".agents/skills/yss-ui/SKILL.md");
   if (!yssUiSkill.includes("`YFormily` 是新代码 canonical name")) fail("yss-ui 必须把 YFormily 声明为新代码 canonical name");
   if (!yssUiSkill.includes("| 新建或改造完整业务页面 | `yss-ui-business-page-generation` |")) fail("yss-ui 缺少完整业务页面生成路由");
+  if (!yssUiSkill.includes("原型阶段不得调用本技能") || yssUiSkill.includes("prototype-component-facts")) fail("yss-ui 必须保持生产实现边界，不得暴露原型模式");
   const expectedServer = { command: "npx", args: ["-y", "@yss-ui/mcp"] };
   for (const config of yssUiManifest.mcp.project_configs) {
     if (!exists(config.path)) fail(`缺少 yss-ui MCP 项目配置: ${config.path}`);
@@ -61,14 +75,37 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
     if (!mcpGuide.includes(marker)) fail(`YSS UI MCP 指南缺少边界或自检标记: ${marker}`);
   }
 
+  const strategicManifest = validateStrategicDesignSkillManifest(JSON.parse(read(".agents/skills/.strategic-design-skills-manifest.json")));
+  const strategicIds = ["prototype-review", "yss-prototype-stage", "yss-design-system", "yss-antd-design", "yss-antdv-next-design", "yss-stage-decision"];
+  if (JSON.stringify(strategicManifest.skills.map(({ canonical }) => canonical).sort()) !== JSON.stringify(strategicIds.slice().sort())) {
+    fail("战略设计 skills 清单必须恰好覆盖六项公共技能");
+  }
+  for (const skill of strategicManifest.skills) {
+    if (isTemplateSource(ROOT)) {
+      const upstreamDirectory = path.join(ROOT, "submodules/yss-harness-design-agent", strategicManifest.source_root, skill.upstream);
+      if (!existsSync(path.join(upstreamDirectory, "SKILL.md"))) fail(`战略设计上游 skill 不存在: ${skill.upstream}`);
+      if (treeHash(upstreamDirectory) !== skill.upstream_hash) fail(`战略设计上游 hash 漂移: ${skill.upstream}`);
+    }
+    const item = lock.skills?.shared?.[skill.canonical];
+    if (!item || item.source !== strategicManifest.source || item.sourceRevision !== strategicManifest.source_revision || item.upstreamHash !== skill.upstream_hash) {
+      fail(`战略设计 skill 缺少一致的来源锁定: ${skill.canonical}`);
+    }
+    if (item.effectiveHash !== item.upstreamHash && item.adaptationRef !== strategicManifest.adaptation_ref) {
+      fail(`战略设计 skill 差异缺少薄适配引用: ${skill.canonical}`);
+    }
+  }
+
   const registry = loadSkillRegistry();
   const canonicalIds = new Set(registry.skills.map((skill) => skill.id));
   const aliases = new Map(registry.skills.flatMap((skill) => skill.aliases.map((alias) => [alias, skill.id])));
-  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height"]);
+  const legacy = new Set(["api-integration", "use-table-height", "use-tree-height"]);
   for (const alias of legacy) {
     if (exists(`.agents/skills/${alias}`)) fail(`legacy alias 不得存在独立 canonical 目录: ${alias}`);
     if (!aliases.has(alias)) fail(`legacy alias 未登记: ${alias}`);
   }
+  if (exists(".agents/skills/page-module-development") || exists(".agents/skills/yss-page-module-development") || aliases.has("page-module-development")) {
+    fail("page-module-development / yss-page-module-development 已退役，不得保留物理目录或运行时 alias");
+  }
   if (exists(".agents/skills/high-fidelity-html-prototype") || aliases.has("high-fidelity-html-prototype")) {
     fail("high-fidelity-html-prototype 已退役，不得保留物理目录或运行时 alias");
   }
@@ -77,14 +114,14 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
   const prototypeEvidence = read("docs/design/templates/prototype-evidence-template.yaml");
   const projectDesign = read("docs/design/design.md");
   const antdvCompatibility = read(".agents/skills/yss-ui/references/antdv-compatibility.md");
-  for (const marker of ["product-design-adapter.md", "schema v2", "ant-design-v6", "ant-design-vue-4.x", "accessibility_verification"]) {
+  for (const marker of ["product-design-adapter.md", "Prototype Evidence schema v4", "Visual Baseline schema v1", "H1", "H2", "原型阶段不得调用 `yss-ui`"]) {
     if (!prototypeStage.includes(marker)) fail(`原型阶段合同缺少 YSS adapter 标记: ${marker}`);
   }
-  for (const marker of ["antd@6.x", "pnpm", "ConfigProvider", "visual_semantic_mapping", "react_only_api_not_copied", "1440x900", "390x844", "verification/design-qa.md"]) {
+  for (const marker of ["prepare-static", "prepare-flow", "vue-antdv-next", "react-antd-6", "fact pack", "ConfigProvider", "1440x900", "390x844"]) {
     if (!prototypeAdapter.includes(marker)) fail(`Product Design adapter 缺少执行约束: ${marker}`);
   }
-  for (const marker of ["schema_version: 2", "design_standard: ant-design-v6", "runtime_component_library: ant-design-vue-4.x", "actual_antd_version", "visual_semantic_mapping", "accessibility_verification", "verification/design-qa.md"]) {
-    if (!prototypeEvidence.includes(marker)) fail(`原型证据模板缺少 schema v2 字段: ${marker}`);
+  for (const marker of ["schema_version: 4", "visual_baseline", "prototype_profile", "visual_review", "flow_review", "implementation_handoff", "project_token_baseline_digest", "verification/design-qa.md"]) {
+    if (!prototypeEvidence.includes(marker)) fail(`原型证据模板缺少 schema v4 字段: ${marker}`);
   }
   if (prototypeEvidence.includes("与官方 #1677ff / Inter / 8px")) fail("原型证据模板仍把 Inter/8px 误写为官方 v6 默认差异");
   if (projectDesign.includes("`antdv6-design.md`")) fail("design.md 仍引用不存在的 antdv6-design.md");

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

@@ -5,12 +5,15 @@ 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 COMPILER_CONTRACT = path.join(ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml");
 const LIFECYCLE_CONTRACT = path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
 const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
 const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);
 const INVOCATION_MODES = new Set(["user", "model", "both"]);
+const DEPENDENCY_TYPES = new Set(["context-required", "context-conditional", "coordination-only", "review-only", "component-dependency"]);
+const TASK_MODES = new Set(["guidance", "integration", "slice-implementation", "troubleshooting", "component-maintenance", "review-input", "contract-compilation", "reroute", "result-validation", "source-index-refresh"]);
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const CAPABILITY_ID_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/;
 const PLATFORM_ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*(?::[a-z0-9][a-z0-9-]*)?$/;
 
 function fail(message) {
@@ -74,10 +77,10 @@ function sameStringSet(left, right) {
 function validateInvocationContract(registry, skill) {
   const contract = registry.invocation_contract;
   requireObject(contract, "invocation_contract");
-  if (contract.schema_version !== 1) fail("invocation_contract.schema_version 必须为 1");
-  if (contract.scope !== "routing-and-dependencies-only") fail("invocation_contract.scope 必须限定为 routing-and-dependencies-only");
+  if (contract.schema_version !== 2) fail("invocation_contract.schema_version 必须为 2；v1 已停止支持");
+  if (contract.scope !== "discovery-only") fail("invocation_contract.scope 必须限定为 discovery-only");
   requireStringArray(contract.required_fields, "invocation_contract.required_fields", { nonEmpty: true });
-  const expected = ["invocation_mode", "trigger_conditions", "exclusion_conditions", "primary_output", "required_dependencies", "optional_dependencies"];
+  const expected = ["invocation_mode", "trigger_conditions", "exclusion_conditions", "primary_output"];
   if (JSON.stringify(contract.required_fields) !== JSON.stringify(expected)) fail("invocation_contract.required_fields 顺序或字段不完整");
   requireStringArray(contract.allowed_invocation_modes, "invocation_contract.allowed_invocation_modes", { nonEmpty: true });
   if (![...INVOCATION_MODES].every((mode) => contract.allowed_invocation_modes.includes(mode))) {
@@ -100,8 +103,6 @@ function validateInvocationContract(registry, skill) {
   requireStringArray(contract.default.trigger_conditions, "invocation_contract.default.trigger_conditions", { nonEmpty: true });
   requireStringArray(contract.default.exclusion_conditions, "invocation_contract.default.exclusion_conditions", { nonEmpty: true });
   requireString(contract.default.primary_output, "invocation_contract.default.primary_output");
-  requireStringArray(contract.default.required_dependencies, "invocation_contract.default.required_dependencies");
-  requireStringArray(contract.default.optional_dependencies, "invocation_contract.default.optional_dependencies");
   for (const [skillId, override] of Object.entries(contract.overrides)) {
     requireObject(override, `invocation_contract.overrides.${skillId}`);
     if (!ID_PATTERN.test(skillId)) fail(`invocation_contract.overrides id 非法: ${skillId}`);
@@ -109,8 +110,6 @@ function validateInvocationContract(registry, skill) {
     if (override.trigger_conditions) requireStringArray(override.trigger_conditions, `${skillId}.trigger_conditions`, { nonEmpty: true });
     if (override.exclusion_conditions) requireStringArray(override.exclusion_conditions, `${skillId}.exclusion_conditions`, { nonEmpty: true });
     if (override.primary_output) requireString(override.primary_output, `${skillId}.primary_output`);
-    if (override.required_dependencies) requireStringArray(override.required_dependencies, `${skillId}.required_dependencies`);
-    if (override.optional_dependencies) requireStringArray(override.optional_dependencies, `${skillId}.optional_dependencies`);
   }
   const overrideIds = Object.keys(contract.overrides);
   const knownIds = new Set(registry.skills.map((item) => item?.id).filter(Boolean));
@@ -121,8 +120,6 @@ function validateInvocationContract(registry, skill) {
   requireStringArray(effective.trigger_conditions, `${skill.id}.trigger_conditions`, { nonEmpty: true });
   requireStringArray(effective.exclusion_conditions, `${skill.id}.exclusion_conditions`, { nonEmpty: true });
   requireString(effective.primary_output, `${skill.id}.primary_output`);
-  requireStringArray(effective.required_dependencies, `${skill.id}.required_dependencies`);
-  requireStringArray(effective.optional_dependencies, `${skill.id}.optional_dependencies`);
   const impactTriggers = skill.impacts.map((impact) => `impact:${impact}`);
   if (!impactTriggers.every((trigger) => effective.trigger_conditions.includes(trigger))) {
     fail(`${skill.id} 的调用契约必须覆盖其 impacts 触发条件`);
@@ -154,7 +151,7 @@ function validateFindingDisposition(disposition) {
   requireStringSet(stale.kinds, ["drift", "new_impacts", "required_skills_mismatch"], "finding_disposition.stale_and_reroute.kinds");
   if (stale.mark_contract !== "stale") fail("drift / new_impacts 必须将合同标为 stale");
   if (stale.continue_coding_on_old_contract !== "forbidden") fail("合同 stale 后禁止在旧合同上继续编码");
-  if (stale.next !== "router-or-earlier-lifecycle") fail("合同 stale 后必须回 Router 或更早生命周期阶段");
+  if (stale.next !== "compiler-or-earlier-lifecycle") fail("合同 stale 后必须回 实现合同编译器 或更早生命周期阶段");
   const exemption = disposition.exemption_policy;
   requireObject(exemption, "finding_disposition.exemption_policy");
   if (exemption.not_applicable !== "impact_not_triggered_only") fail("not-applicable 仅允许影响面未命中");
@@ -211,9 +208,9 @@ function validateCodeReviewRoute(route, resolve) {
   validateFindingDisposition(standards.finding_disposition);
 }
 
-export function validateSkillRegistry(registry, { lock, routerContract, lifecycleContract, skillSource } = {}) {
+export function validateSkillRegistry(registry, { lock, compilerContract, lifecycleContract, skillSource } = {}) {
   if (!registry || typeof registry !== "object" || Array.isArray(registry)) fail("技能路由注册表必须是对象");
-  if (registry.schema_version !== 1) fail("schema_version 必须为 1");
+  if (registry.schema_version !== 2) fail("schema_version 必须为 2；v1 已停止支持，请迁移 capability、typed dependencies 与 recipes");
   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");
@@ -221,11 +218,11 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
   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 (typeof runtime.consumed_by_compiler !== "boolean" || typeof runtime.consumed_by_lifecycle !== "boolean" || typeof runtime.discovery_enforced !== "boolean") {
+    fail("runtime_policy 必须声明 consumed_by_compiler、consumed_by_lifecycle、discovery_enforced");
   }
-  if (registry.status === "shadow" && (runtime.consumed_by_router || runtime.consumed_by_lifecycle || runtime.discovery_enforced)) {
-    fail("shadow 注册表不得被 Router、生命周期或发现面强制消费");
+  if (registry.status === "shadow" && (runtime.consumed_by_compiler || runtime.consumed_by_lifecycle || runtime.discovery_enforced)) {
+    fail("shadow 注册表不得被实现合同编译器、生命周期或发现面强制消费");
   }
   const roots = registry.agent_runtime_roots;
   if (!roots || typeof roots !== "object" || Array.isArray(roots)) fail("缺少 agent_runtime_roots");
@@ -233,7 +230,6 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
     claude: ".claude/skills",
     codex: ".codex/skills",
     cursor: ".cursor/skills",
-    hermes: ".hermes/skills",
     pi: ".pi/skills",
     qoder: ".qoder/skills",
     trae: ".trae/skills"
@@ -331,17 +327,88 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
     || externalIds.has(name)
     || platformAliases.has(name)
     || [...platformIds].some((key) => key.endsWith(`:${name}`));
-  for (const skill of skills) {
-    const effective = effectiveInvocationContract(registry, skill);
-    const required = effective.required_dependencies ?? [];
-    const optional = effective.optional_dependencies ?? [];
-    for (const dependency of [...required, ...optional]) {
-      if (!registeredDependency(dependency)) fail(`${skill.id} 的调用契约依赖引用了未登记技能: ${dependency}`);
-      if (dependency === skill.id) fail(`${skill.id} 的调用契约不得依赖自身`);
+  const capabilityContract = registry.capability_contract;
+  requireObject(capabilityContract, "capability_contract");
+  if (capabilityContract.schema_version !== 2) fail("capability_contract.schema_version 必须为 2");
+  requireStringSet(capabilityContract.dependency_types, [...DEPENDENCY_TYPES], "capability_contract.dependency_types");
+  requireStringSet(capabilityContract.task_modes, [...TASK_MODES], "capability_contract.task_modes");
+  requireObject(capabilityContract.closure, "capability_contract.closure");
+  requireStringSet(capabilityContract.closure.recursive_types, ["context-required"], "capability_contract.closure.recursive_types");
+  if (capabilityContract.closure.conditional_type !== "context-conditional") fail("条件依赖类型必须为 context-conditional");
+  requireStringSet(capabilityContract.closure.non_expanding_types, ["coordination-only", "review-only", "component-dependency"], "capability_contract.closure.non_expanding_types");
+  if (capabilityContract.closure.deduplicate_skills !== true || capabilityContract.closure.preserve_all_reasons !== true) {
+    fail("capability closure 必须去重 skill 并保留全部原因链");
+  }
+  if (JSON.stringify(capabilityContract.deterministic_order) !== JSON.stringify(["recipe-declaration", "dependency-topology", "skill-id"])) {
+    fail("capability_contract.deterministic_order 必须固定为 recipe-declaration、dependency-topology、skill-id");
+  }
+
+  if (!Array.isArray(registry.capabilities) || registry.capabilities.length === 0) fail("capabilities 不能为空");
+  const capabilityIds = new Set();
+  const capabilitySkills = new Set();
+  for (const [index, capability] of registry.capabilities.entries()) {
+    const prefix = `capabilities[${index}]`;
+    requireObject(capability, prefix);
+    requireString(capability.id, `${prefix}.id`);
+    if (!CAPABILITY_ID_PATTERN.test(capability.id)) fail(`${prefix}.id 必须使用 dotted namespace: ${capability.id}`);
+    if (capabilityIds.has(capability.id)) fail(`重复 capability id: ${capability.id}`);
+    capabilityIds.add(capability.id);
+    requireString(capability.primary_skill, `${prefix}.primary_skill`);
+    if (!ids.has(capability.primary_skill)) fail(`${capability.id} 的 primary_skill 未登记: ${capability.primary_skill}`);
+    requireStringArray(capability.task_modes, `${prefix}.task_modes`, { nonEmpty: true });
+    for (const mode of capability.task_modes) if (!TASK_MODES.has(mode)) fail(`${capability.id} 使用未知 task mode: ${mode}`);
+    capabilitySkills.add(capability.primary_skill);
+  }
+  for (const skill of skills.filter((item) => item.impacts.includes("backend") && item.maturity !== "deprecated")) {
+    if (!capabilitySkills.has(skill.id)) fail(`backend skill 缺少 capability: ${skill.id}`);
+  }
+
+  if (!Array.isArray(registry.recipes) || registry.recipes.length === 0) fail("recipes 不能为空");
+  const recipeIds = new Set();
+  for (const [index, recipe] of registry.recipes.entries()) {
+    const prefix = `recipes[${index}]`;
+    requireObject(recipe, prefix);
+    requireString(recipe.id, `${prefix}.id`);
+    if (!CAPABILITY_ID_PATTERN.test(recipe.id)) fail(`${prefix}.id 必须使用 dotted namespace: ${recipe.id}`);
+    if (recipeIds.has(recipe.id)) fail(`重复 recipe id: ${recipe.id}`);
+    recipeIds.add(recipe.id);
+    requireStringArray(recipe.capabilities, `${prefix}.capabilities`, { nonEmpty: true });
+    for (const capabilityId of recipe.capabilities) if (!capabilityIds.has(capabilityId)) fail(`${recipe.id} 引用了未知 capability: ${capabilityId}`);
+    if (recipe.skills !== undefined) fail(`${recipe.id} 只能引用 capabilities，不能直接引用 skills`);
+  }
+
+  requireObject(registry.skill_dependencies, "skill_dependencies");
+  const requiredGraph = new Map([...ids].map((id) => [id, []]));
+  for (const [owner, dependencies] of Object.entries(registry.skill_dependencies)) {
+    if (!ids.has(owner)) fail(`skill_dependencies 使用未知 owner: ${owner}`);
+    if (!Array.isArray(dependencies)) fail(`skill_dependencies.${owner} 必须是数组`);
+    const edgeKeys = new Set();
+    for (const [index, dependency] of dependencies.entries()) {
+      const prefix = `skill_dependencies.${owner}[${index}]`;
+      requireObject(dependency, prefix);
+      requireString(dependency.skill, `${prefix}.skill`);
+      if (!registeredDependency(dependency.skill)) fail(`${owner} 的依赖引用了未登记技能: ${dependency.skill}`);
+      if (dependency.skill === owner) fail(`${owner} 不得依赖自身`);
+      if (!DEPENDENCY_TYPES.has(dependency.type)) fail(`${owner} 使用未知依赖类型: ${dependency.type}`);
+      if (dependency.type === "context-conditional") requireString(dependency.when, `${prefix}.when`);
+      if (dependency.when !== undefined) requireString(dependency.when, `${prefix}.when`);
+      const edgeKey = `${dependency.skill}\0${dependency.type}\0${dependency.when ?? ""}`;
+      if (edgeKeys.has(edgeKey)) fail(`${owner} 包含重复依赖: ${dependency.skill}`);
+      edgeKeys.add(edgeKey);
+      if (dependency.type === "context-required" && ids.has(dependency.skill)) requiredGraph.get(owner).push(dependency.skill);
     }
-    const overlap = required.filter((dependency) => optional.includes(dependency));
-    if (overlap.length) fail(`${skill.id} 的必需依赖与可选依赖重复: ${overlap.join(", ")}`);
   }
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (skillId, chain = []) => {
+    if (visiting.has(skillId)) fail(`context-required 依赖存在循环: ${[...chain, skillId].join(" -> ")}`);
+    if (visited.has(skillId)) return;
+    visiting.add(skillId);
+    for (const dependency of requiredGraph.get(skillId) ?? []) visit(dependency, [...chain, skillId]);
+    visiting.delete(skillId);
+    visited.add(skillId);
+  };
+  for (const skillId of ids) visit(skillId);
 
   if (lock) {
     const shared = Object.keys(lock.skills?.shared ?? {}).sort();
@@ -375,41 +442,18 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
     }
   }
 
-  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) && !externalIds.has(name)) fail(`Router 闭包引用了未登记技能: ${name}`);
+  if (compilerContract) {
+    if (compilerContract.schema_version !== 2) fail("compiler-contract.yaml schema_version 必须为 2；v1 已停止支持");
+    if (compilerContract.compiled_by !== "yss-implementation-contract-compiler") fail("compiler-contract.yaml compiled_by 无效");
+    if (compilerContract.capability_source !== "docs/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml capability_source 必须指向技能注册表");
+    if (compilerContract.recipe_source !== "docs/agents/yss-skill-registry.yaml") fail("compiler-contract.yaml recipe_source 必须指向技能注册表");
+    requireObject(compilerContract.impact_to_capabilities, "compiler-contract.impact_to_capabilities");
+    for (const [impact, mapped] of Object.entries(compilerContract.impact_to_capabilities)) {
+      requireStringArray(mapped, `compiler-contract.impact_to_capabilities.${impact}`, { nonEmpty: true });
+      for (const capabilityId of mapped) if (!capabilityIds.has(capabilityId)) fail(`${impact} 映射了未知 capability: ${capabilityId}`);
     }
-    for (const dependencies of Object.values(routerContract.dependency_closure ?? {})) {
-      for (const names of Object.values(dependencies ?? {})) {
-        for (const name of names ?? []) if (!ids.has(name) && !aliases.has(name) && !externalIds.has(name)) fail(`Router 依赖引用了未登记技能: ${name}`);
-      }
-    }
-    for (const skillId of Object.keys(registry.invocation_contract.overrides)) {
-      const closure = routerContract.dependency_closure?.[skillId];
-      if (!closure) fail(`Router dependency_closure 缺少注册表覆写技能: ${skillId}`);
-      const skill = skills.find((item) => item.id === skillId);
-      const effective = effectiveInvocationContract(registry, skill);
-      const required = effective.required_dependencies ?? [];
-      const optional = effective.optional_dependencies ?? [];
-      const always = closure.always ?? [];
-      const conditional = Object.entries(closure)
-        .filter(([condition]) => condition !== "always")
-        .flatMap(([, names]) => names ?? []);
-      if (!sameStringSet(required, always)) {
-        fail(`${skillId} 的静态必需依赖与 Router always 不一致`);
-      }
-      if (!sameStringSet(optional, conditional)) {
-        fail(`${skillId} 的可选依赖与 Router 条件依赖不一致`);
-      }
+    for (const forbidden of ["skill_aliases", "skill_dependencies", "capabilities", "recipes", "dependency_closure", "end_to_end_backend_required", "component_impact_routing"]) {
+      if (compilerContract[forbidden] !== undefined) fail(`compiler-contract.yaml 不得重复注册表事实: ${forbidden}`);
     }
   }
 
@@ -468,10 +512,10 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
 export function validateDefaultSkillRegistry() {
   const registry = loadSkillRegistry();
   const lock = JSON.parse(readFileSync(LOCK_PATH, "utf8"));
-  const routerContract = yamlFromFile(ROUTER_CONTRACT, "Router 合同");
+  const compilerContract = yamlFromFile(COMPILER_CONTRACT, "实现合同编译器合同");
   return validateSkillRegistry(registry, {
     lock,
-    routerContract,
+    compilerContract,
     lifecycleContract: yamlFromFile(LIFECYCLE_CONTRACT, "生命周期编排合同"),
     skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8")
   });

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

@@ -8,8 +8,9 @@ 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 YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
-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", "research", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
+const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
+export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/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", "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 function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }
@@ -23,14 +24,16 @@ function treeFiles(directory, prefix = "") {
     const absolute = path.join(directory, entry.name);
     const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) return treeFiles(absolute, rel);
-    if (rel.split("/").includes("__pycache__") || /\.(pyc|pyo)$/.test(rel)) return [];
+    if (rel.split("/").includes("__pycache__") || /\.(iml|pyc|pyo)$/.test(rel)) return [];
     return entry.isFile() || entry.isSymbolicLink() ? [[rel, absolute]] : [];
   });
 }
 export function treeHash(directory) {
   const digest = createHash("sha256");
   for (const [name, file] of treeFiles(directory).sort(([left], [right]) => left.localeCompare(right))) {
-    digest.update(name).update("\0").update(readFileSync(file)).update("\0");
+    const content = readFileSync(file);
+    const normalized = content.includes(0) ? content : Buffer.from(content.toString("utf8").replaceAll("\r\n", "\n"));
+    digest.update(name).update("\0").update(normalized).update("\0");
   }
   return digest.digest("hex");
 }
@@ -86,9 +89,33 @@ export function validateYssUiSkillManifest(manifest) {
   return manifest;
 }
 
+export function validateStrategicDesignSkillManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new TypeError("战略设计 skills 清单必须是对象");
+  for (const field of ["source", "source_type", "source_root", "source_revision", "adaptation_ref"]) {
+    if (typeof manifest[field] !== "string" || !manifest[field].trim()) throw new TypeError(`战略设计 skills 清单缺少 ${field}`);
+  }
+  if (manifest.schema_version !== 1) throw new TypeError("战略设计 skills 清单 schema_version 必须为 1");
+  if (!/^[0-9a-f]{40}$/.test(manifest.source_revision)) throw new TypeError("战略设计 skills source_revision 必须是完整 Git SHA");
+  if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) throw new TypeError("战略设计 skills 清单缺少 skills");
+  const upstreamNames = new Set();
+  const canonicalNames = new Set();
+  for (const skill of manifest.skills) {
+    if (!skill || typeof skill.upstream !== "string" || typeof skill.canonical !== "string") throw new TypeError("战略设计 skill 缺少 upstream/canonical");
+    if (!/^[0-9a-f]{64}$/.test(skill.upstream_hash ?? "")) throw new TypeError(`${skill.canonical} 缺少有效 upstream_hash`);
+    if (upstreamNames.has(skill.upstream)) throw new TypeError(`战略设计 upstream 重复: ${skill.upstream}`);
+    if (canonicalNames.has(skill.canonical)) throw new TypeError(`战略设计 canonical 重复: ${skill.canonical}`);
+    upstreamNames.add(skill.upstream);
+    canonicalNames.add(skill.canonical);
+  }
+  return manifest;
+}
+
 function loadYssUiSkillManifest() {
   return validateYssUiSkillManifest(JSON.parse(readFileSync(YSS_UI_MANIFEST_PATH, "utf8")));
 }
+function loadStrategicDesignSkillManifest() {
+  return validateStrategicDesignSkillManifest(JSON.parse(readFileSync(STRATEGIC_DESIGN_MANIFEST_PATH, "utf8")));
+}
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
 function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
@@ -179,7 +206,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|cursor|hermes|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
+  if (canonical && /^\.(claude|codex|cursor|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;
@@ -200,6 +227,9 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   const yssUiManifest = loadYssUiSkillManifest();
   sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
   const yssUiSkills = new Map(yssUiManifest.skills.map((skill) => [skill.canonical, skill]));
+  const strategicDesignManifest = loadStrategicDesignSkillManifest();
+  sources[strategicDesignManifest.source] = { ...(sources[strategicDesignManifest.source] ?? {}), revision: strategicDesignManifest.source_revision };
+  const strategicDesignSkills = new Map(strategicDesignManifest.skills.map((skill) => [skill.canonical, skill]));
   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)));
@@ -223,6 +253,16 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
       if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = yssUiManifest.adaptation_ref;
       else delete item.adaptationRef;
     }
+    const strategicDesignSkill = strategicDesignSkills.get(name);
+    if (strategicDesignSkill) {
+      item.source = strategicDesignManifest.source;
+      item.sourceType = strategicDesignManifest.source_type;
+      item.skillPath = `${strategicDesignManifest.source_root}/${strategicDesignSkill.upstream}/SKILL.md`;
+      item.sourceRevision = strategicDesignManifest.source_revision;
+      item.upstreamHash = strategicDesignSkill.upstream_hash;
+      if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = strategicDesignManifest.adaptation_ref;
+      else delete item.adaptationRef;
+    }
     item.targets = targets;
     return [name, item];
   }));

package/template/scripts/lib/strategic-handoff-consumption.mjs

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { openBundle } from './strategic-handoff.mjs';
+import { read, safe, ensure, ROOT, digest, project } from './strategic-handoff-io.mjs';
+import { parseContextContract } from './context-contract.mjs';
+const present=x=>typeof x==='string'&&x.trim();
+const list=x=>Array.isArray(x)&&x.length&&x.every(present);
+const without=(value,keys)=>Object.fromEntries(Object.entries(value).filter(([key])=>!keys.includes(key)));
+const strategyBasis=value=>({
+  ...without(value,['domain_version','approval','rule_catalog','scenarios','invariants']),
+  invariants:(value.invariants||[]).map(item=>without(item,['statement'])),
+});
+export async function verifyConsumption(data,{root=process.cwd(),sliceRef}={}) {
+  project(root);
+  if (sliceRef) ensure(data.status === "approved", "切片只能消费 approved 战术合同");
+  const binding=data.strategic_handoff;
+  ensure(binding && present(binding.import_receipt_ref) && present(binding.context_reconciliation_ref),'缺少战略交接导入收据与目标对账引用');
+  const receipt=read(safe(root,binding.import_receipt_ref));
+  const expectedBase=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
+  ensure(binding.import_receipt_ref===`${expectedBase}/import-receipt.json` && receipt.package_ref===`${expectedBase}/package`,'导入收据路径与包身份不一致');
+  ensure(binding.bundle_digest===receipt.bundle_digest,'战术绑定与导入收据摘要不一致');
+  const result=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,binding.context_reconciliation_ref)],{encoding:'utf8'});
+  ensure(result.status===0,`目标术语对账未通过: ${result.error?.message || result.stderr}`);
+  const context=parseContextContract({root});
+  const parent=safe(root,`docs/handoffs/${receipt.bundle_id}`);
+  const versions=readdirSync(parent).filter(x=>/^v[1-9][0-9]*$/.test(x)&&existsSync(path.join(parent,x,'import-receipt.json'))).sort((a,b)=>Number(b.slice(1))-Number(a.slice(1)));
+  const latestReceipt=read(safe(root,`docs/handoffs/${receipt.bundle_id}/${versions[0]}/import-receipt.json`));
+  ensure(latestReceipt.version===versions[0]&&latestReceipt.package_ref===`docs/handoffs/${receipt.bundle_id}/${versions[0]}/package`,'最新收据路径无效');
+  return openBundle(safe(root,receipt.package_ref),async original=>{
+    ensure(original.manifest.bundle_digest===receipt.bundle_digest,'导入收据与包不一致');
+    return openBundle(safe(root,latestReceipt.package_ref),async current=>{
+      ensure(current.manifest.bundle_id===receipt.bundle_id && current.manifest.bundle_digest===latestReceipt.bundle_digest,'最新导入收据无效');
+      for(const op of ['added','updated'])for(const term of current.handoff.context_delta[op]) {
+        const actual=context.terms_by_ref.get(term.term_ref);ensure(actual,`目标缺少术语: ${term.term_ref}`);
+        for(const key of ['term','meaning','english_identifier','context_id','forbidden_aliases'])ensure(digest(actual[key])===digest(term[key]),`目标术语未对账: ${term.term_ref}`);
+      }
+      for(const term of current.handoff.context_delta.deprecated)ensure(!context.terms_by_ref.has(term.term_ref),`目标尚未处理废弃术语: ${term.term_ref}`);
+      ensure(Array.isArray(binding.rows),'缺少逐条承接 rows');
+      const known=new Map([...current.indexes.rules.map(x=>[x.rule_id,x]),...current.indexes.scenarios.filter(x=>x.critical).map(x=>[x.scenario_id,x])]);
+      const rows=new Map();for(const row of binding.rows){ensure(!rows.has(row.source_id),`重复承接: ${row.source_id}`);rows.set(row.source_id,row);}
+      const issues=[], blocked=new Set();let all=false;
+      const mark=(id,reason,row)=>{issues.push({source_id:id,reason});if(row?.dependency_status!=='known'||!list(row.dependent_slice_refs))all=true;else row.dependent_slice_refs.forEach(x=>blocked.add(x));};
+      const catalogs=['aggregate_catalog','entity_catalog','value_object_catalog','behavior_catalog','invariant_catalog','state_transition_catalog','domain_event_catalog','gateway_catalog'];
+      const ids=new Set(catalogs.flatMap(k=>(data[k]||[]).flatMap(x=>Object.entries(x).filter(([k])=>k.endsWith('_id')).map(([,v])=>v))));
+      const seams=new Map((data.test_seams||[]).map(x=>[x.seam_id,x]));
+      for(const[id,source]of known){
+        const row=rows.get(id);
+        if(!row){mark(id,'missing-mapping');continue;}
+        ensure(['known','unknown'].includes(row.dependency_status) && Array.isArray(row.dependent_slice_refs),'缺少切片依赖判定');
+        if(row.source_digest!==source.source_digest){mark(id,'stale-source',row);continue;}
+        if(row.disposition==='implemented'){
+          ensure(list(row.tactical_refs)&&row.tactical_refs.every(x=>ids.has(x)),`战术落点悬空: ${id}`);
+          ensure(list(row.test_seam_refs)&&row.test_seam_refs.every(x=>seams.has(x)&&row.tactical_refs.includes(seams.get(x).subject_ref)),`测试 seam 未关联战术落点: ${id}`);
+          if(id.startsWith('scenario.'))ensure(['success','failure'].every(outcome=>(row.scenario_tests||[]).some(x=>x.outcome===outcome&&row.test_seam_refs.includes(x.seam_ref))),`关键场景缺少成功/失败测试: ${id}`);
+          ensure(list(row.evidence_refs),`缺少落实证据: ${id}`);row.evidence_refs.forEach(ref=>safe(root,ref));
+        }else if(row.disposition==='deferred'){
+          for(const key of ['reason','risk','owner','followup_ticket_ref','verification_plan','target_version'])ensure(present(row[key]),`延期缺少 ${key}: ${id}`);
+          mark(id,'deferred',row);
+        }else if(row.disposition==='not-applicable'){
+          ensure(present(row.reason)&&list(row.evidence_refs),`不适用缺少依据: ${id}`);row.evidence_refs.forEach(ref=>safe(root,ref));
+        }else {ensure(['pending','conflict'].includes(row.disposition),`非法承接状态: ${id}`);mark(id,row.disposition,row);}
+      }
+      for(const[id,row]of rows)if(!known.has(id))mark(id,'removed-or-unknown-source',row);
+      for(const key of ['spec_ref','prototype_ref','visual_baseline_ref','business_ticket_set_ref'])if(original.handoff.source[key].digest!==current.handoff.source[key].digest){all=true;issues.push({source_id:key,reason:'upstream-asset-stale'});}
+      // Rule changes can be scoped to declared dependencies. Boundary/decision or
+      // runnable-prototype changes need the tactical contract rebound as a whole.
+      const stageKeys=['package_version','approval','domain_strategy_ref'];
+      if(digest(strategyBasis(original.strategy))!==digest(strategyBasis(current.strategy)) || digest(without(original.stage,stageKeys))!==digest(without(current.stage,stageKeys)) || digest(original.config.prototype)!==digest(current.config.prototype)) {
+        all=true;issues.push({source_id:'strategic-design-basis',reason:'upstream-design-stale'});
+      }
+      const blockedHere=all||(sliceRef?blocked.has(sliceRef):issues.length>0);
+      return {result:blockedHere?'blocked':'verified',bundle_digest:current.manifest.bundle_digest,consumed_bundle_digest:receipt.bundle_digest,tactical_digest:digest(data),scope:sliceRef||'whole-tactical-design',coverage_complete:[...known.keys()].every(id=>rows.has(id)),block_all:all,blocked_slice_refs:[...blocked].sort(),issues};
+    });
+  });
+}