create-yss-spec 3.0.0 → 3.0.1

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { DEFAULT_REGISTRY, loadSkillRegistry } from "./skill-registry.mjs";
+import { ROOT } from "./skill-supply-chain.mjs";
+
+export const DEFAULT_COMPILER_CONTRACT = path.join(
+  ROOT,
+  ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"
+);
+
+const REMOVED_SKILL_IDS = new Set(["yss-router", "yss-source-index"]);
+const EXPANDING_TYPES = new Set(["context-required", "context-conditional"]);
+const EXECUTION_STATUSES = new Set(["implemented", "seam-deferred", "drift", "violation", "not-applicable"]);
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+export function digestDocument(value) {
+  return createHash("sha256").update(JSON.stringify(stable(value))).digest("hex");
+}
+
+function loadYaml(filePath, label) {
+  const document = parseDocument(readFileSync(filePath, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) fail(`${label} 无法解析: ${document.errors[0].message}`);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+export function loadCompilerContract(filePath = DEFAULT_COMPILER_CONTRACT) {
+  return loadYaml(filePath, "实现合同编译器合同");
+}
+
+function assertV2(registry, compilerContract) {
+  if (registry?.schema_version !== 2) fail("技能注册表 schema v1 已停止支持；请迁移到 capability/typed-dependency v2");
+  if (compilerContract?.schema_version !== 2) fail("实现合同编译器合同 schema v1 已停止支持；请迁移到 v2");
+}
+
+function assertNoRemovedId(value, field) {
+  for (const id of value) if (REMOVED_SKILL_IDS.has(id)) fail(`${field} 使用已移除 skill id ${id}；不提供兼容 alias`);
+}
+
+/**
+ * 把多个窄 Recipe 与显式 capability 合并为一个确定性的最小 skill 闭包。
+ */
+export function compileImplementationContract({
+  registry,
+  compilerContract,
+  recipeIds = [],
+  requiredCapabilities = [],
+  conditions = [],
+  compiledAt = new Date().toISOString(),
+  registryDigest,
+  compilerContractDigest
+}) {
+  assertV2(registry, compilerContract);
+  if (!Array.isArray(recipeIds) || !Array.isArray(requiredCapabilities) || !Array.isArray(conditions)) {
+    fail("recipeIds、requiredCapabilities 与 conditions 必须是数组");
+  }
+  assertNoRemovedId(recipeIds, "recipeIds");
+  assertNoRemovedId(requiredCapabilities, "requiredCapabilities");
+
+  const requestedRecipes = new Set(recipeIds);
+  const knownRecipes = new Map(registry.recipes.map((recipe) => [recipe.id, recipe]));
+  for (const recipeId of requestedRecipes) if (!knownRecipes.has(recipeId)) fail(`未知 recipe: ${recipeId}`);
+  const orderedRecipes = registry.recipes.filter((recipe) => requestedRecipes.has(recipe.id));
+
+  const capabilitySources = new Map();
+  const orderedCapabilities = [];
+  const addCapability = (capabilityId, source) => {
+    if (!capabilitySources.has(capabilityId)) {
+      capabilitySources.set(capabilityId, []);
+      orderedCapabilities.push(capabilityId);
+    }
+    capabilitySources.get(capabilityId).push(source);
+  };
+  for (const recipe of orderedRecipes) {
+    if (recipe.skills !== undefined) fail(`recipe ${recipe.id} 不得直接引用 skills`);
+    for (const capabilityId of recipe.capabilities) addCapability(capabilityId, { kind: "recipe", recipe_id: recipe.id });
+  }
+  for (const capabilityId of requiredCapabilities) addCapability(capabilityId, { kind: "explicit-capability" });
+  if (!orderedCapabilities.length) fail("至少需要一个 recipe 或 required capability");
+
+  const capabilities = new Map(registry.capabilities.map((capability) => [capability.id, capability]));
+  for (const capabilityId of orderedCapabilities) if (!capabilities.has(capabilityId)) fail(`未知 capability: ${capabilityId}`);
+  const knownSkills = new Set(registry.skills.map((skill) => skill.id));
+  const conditionSet = new Set(conditions);
+  const reasons = new Map();
+  const nonExpanding = [];
+  const excludedConditional = [];
+  const addReason = (skill, reason) => {
+    if (!reasons.has(skill)) reasons.set(skill, []);
+    const encoded = JSON.stringify(reason);
+    if (!reasons.get(skill).some((item) => JSON.stringify(item) === encoded)) reasons.get(skill).push(reason);
+  };
+
+  const roots = [];
+  for (const capabilityId of orderedCapabilities) {
+    const skill = capabilities.get(capabilityId).primary_skill;
+    if (!knownSkills.has(skill)) fail(`${capabilityId} 解析到未知 skill: ${skill}`);
+    if (!roots.includes(skill)) roots.push(skill);
+    for (const source of capabilitySources.get(capabilityId)) addReason(skill, { ...source, capability: capabilityId });
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  const orderedSkills = [];
+  const visit = (skill, chain = []) => {
+    if (visiting.has(skill)) fail(`依赖循环: ${[...chain, skill].join(" -> ")}`);
+    if (visited.has(skill)) return;
+    visiting.add(skill);
+    const dependencies = [...(registry.skill_dependencies?.[skill] ?? [])]
+      .sort((left, right) => left.skill.localeCompare(right.skill));
+    for (const dependency of dependencies) {
+      const conditionMatches = !dependency.when || conditionSet.has(dependency.when);
+      if (dependency.type === "context-conditional" && !conditionMatches) {
+        excludedConditional.push({ from: skill, ...dependency });
+        continue;
+      }
+      const reason = { kind: "dependency", from: skill, type: dependency.type, ...(dependency.when ? { condition: dependency.when } : {}) };
+      if (!EXPANDING_TYPES.has(dependency.type)) {
+        if (conditionMatches) nonExpanding.push({ skill: dependency.skill, ...reason });
+        continue;
+      }
+      addReason(dependency.skill, reason);
+      if (knownSkills.has(dependency.skill)) visit(dependency.skill, [...chain, skill]);
+      else if (!orderedSkills.includes(dependency.skill)) orderedSkills.push(dependency.skill);
+    }
+    visiting.delete(skill);
+    visited.add(skill);
+    orderedSkills.push(skill);
+  };
+  for (const root of roots) visit(root);
+
+  return {
+    schema_version: 2,
+    status: "draft",
+    recipe_ids: orderedRecipes.map((recipe) => recipe.id),
+    conditions: [...conditionSet].sort(),
+    required_capabilities: orderedCapabilities,
+    required_skills: orderedSkills,
+    reason_chains: Object.fromEntries(orderedSkills.map((skill) => [skill, reasons.get(skill) ?? []])),
+    non_expanding_dependencies: nonExpanding,
+    excluded_conditional_dependencies: excludedConditional,
+    registry_digest: registryDigest ?? digestDocument(registry),
+    compiler_contract_digest: compilerContractDigest ?? digestDocument(compilerContract),
+    compiled_at: compiledAt,
+    freshness: "current"
+  };
+}
+
+export function compileDefaultImplementationContract(input = {}) {
+  return compileImplementationContract({
+    ...input,
+    registry: loadSkillRegistry(DEFAULT_REGISTRY),
+    compilerContract: loadCompilerContract()
+  });
+}
+
+export function evaluateContractFreshness(contract, { registry, compilerContract }) {
+  assertV2(registry, compilerContract);
+  if (contract?.schema_version !== 2) fail("Slice Implementation Contract schema v1 已停止支持；必须重新编译 v2 合同");
+  const resolution = contract.resolution ?? contract;
+  const reasons = [];
+  if (resolution.registry_digest !== digestDocument(registry)) reasons.push("registry-digest-changed");
+  if (resolution.compiler_contract_digest !== digestDocument(compilerContract)) reasons.push("compiler-contract-digest-changed");
+  return { freshness: reasons.length ? "stale" : "current", reasons };
+}
+
+export function validateExecutionResult(result, contract, current) {
+  if (result?.schema_version !== 2) fail("YSS Skill Execution Result schema v1 已停止支持；请迁移到 v2");
+  if (contract?.schema_version !== 2) fail("Slice Implementation Contract schema v1 已停止支持；必须重新编译 v2 合同");
+  if (!EXECUTION_STATUSES.has(result.status)) fail(`未知 execution result status: ${result.status}`);
+  const freshness = evaluateContractFreshness(contract, current);
+  if (freshness.freshness === "stale") return { status: "stale", blockers: freshness.reasons };
+  const consumed = result.consumed_contract ?? {};
+  const resolution = contract.resolution ?? contract;
+  const blockers = [];
+  if (consumed.contract_id !== contract.contract_id || consumed.contract_version !== contract.contract_version) blockers.push("contract-version-mismatch");
+  if (consumed.registry_digest !== resolution.registry_digest || consumed.compiler_contract_digest !== resolution.compiler_contract_digest) blockers.push("resolution-digest-mismatch");
+  if (!Array.isArray(result.verification_results) || !result.verification_results.length) blockers.push("verification-not-executed");
+  else for (const item of result.verification_results) {
+    if (!item?.command || item.exit_code === undefined || !item.executed_at) blockers.push("verification-result-incomplete");
+  }
+  if (Array.isArray(result.new_impacts) && result.new_impacts.length) blockers.push("new-impacts");
+  return { status: blockers.length ? "blocked" : "accepted", blockers: [...new Set(blockers)] };
+}

package/template/scripts/lib/scenario-checks.mjs

@@ -64,6 +64,9 @@ function validateInvocationBoundary(data) {
   ensure(strategyResearch?.profile === "strategy-evidence" && strategyResearch.mode_before_gate === "evidence-audited" && strategyResearch.artifact_owner === "yss-research" && strategyResearch.downstream_owner === "yss-stage-decision", "领域战略研究合同缺少 profile、门禁前审计或资产所有权边界");
   const stageDecisionResearch = routes?.["work-unit.stage-decision"]?.research_contract;
   ensure(routes?.["work-unit.stage-decision"]?.skills?.includes("yss-research") && stageDecisionResearch?.profile === "strategy-evidence" && stageDecisionResearch.mode_before_gate === "evidence-audited" && stageDecisionResearch.artifact_owner === "yss-research" && stageDecisionResearch.downstream_owner === "yss-stage-decision", "阶段决策工作单元缺少 evidence-audited 战略研究合同");
+  const prototypeRoute = routes?.["work-unit.prototype-design"];
+  ensure(!prototypeRoute?.skills?.includes("yss-ui") && !prototypeRoute?.supporting_skills?.includes("yss-ui"), "原型工作单元不得调用生产实现技能 yss-ui");
+  ensure(JSON.stringify(Object.keys(prototypeRoute?.profile_contract?.profiles ?? {})) === JSON.stringify(["H1", "H2"]) && prototypeRoute?.version_boundary?.prototype_must_not_call === "yss-ui", "原型档位必须仅包含 H1/H2 并明确 yss-ui 边界");
   ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui-business-page-generation"), "原生实现工作单元缺少 TDD、UI 或业务页面生成路由");
   const frontendRoute = routes?.["work-unit.slice-implementation"]?.frontend_route;
   ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口、业务页面生成或页面编排技能");
@@ -77,7 +80,7 @@ function validateInvocationBoundary(data) {
   const disposition = reviewRoute?.review_standards_route?.finding_disposition;
   ensure(includesAll(disposition?.same_loop_for, ["product-slice", "template-maintenance"]) && disposition?.reviewer_write_implementation === "forbidden", "审查 finding 闭环未同时覆盖产品切片与模板维护，或允许审查者写实现");
   ensure(includesAll(disposition?.repair_then_full_rereview?.kinds, ["violation", "machine_check_failure", "blank_applicable_row", "missing_evidence"]) && disposition?.repair_then_full_rereview?.actor === "implementer" && disposition?.repair_then_full_rereview?.then === "recapture_candidate_and_rerun_all_axes", "violation 类 finding 未要求实现者修复后全轴复审");
-  ensure(includesAll(disposition?.stale_and_reroute?.kinds, ["drift", "new_impacts", "required_skills_mismatch"]) && disposition?.stale_and_reroute?.continue_coding_on_old_contract === "forbidden" && disposition?.stale_and_reroute?.next === "router-or-earlier-lifecycle", "drift / new_impacts 未要求合同 stale 并回 Router");
+  ensure(includesAll(disposition?.stale_and_reroute?.kinds, ["drift", "new_impacts", "required_skills_mismatch"]) && disposition?.stale_and_reroute?.continue_coding_on_old_contract === "forbidden" && disposition?.stale_and_reroute?.next === "compiler-or-earlier-lifecycle", "drift / new_impacts 未要求合同 stale 并回 实现合同编译器");
   ensure(disposition?.exemption_policy?.not_applicable === "impact_not_triggered_only" && disposition?.exemption_policy?.mandatory_waiver === "forbidden" && includesAll(disposition?.exemption_policy?.allowed_exits, ["repair", "seam-deferred-complete"]) && disposition?.exemption_policy?.new_human_waiver_gate === "forbidden", "审查豁免策略允许未命中以外的 not-applicable 或 mandatory 豁免");
   ensure(data.review_input?.unique_default_skill === "code-review" && data.review_input?.second_generic_review_skill === "forbidden" && data.review_input?.completed_requires_specialist_coverage === true && data.review_input?.finding_disposition_required === true && data.review_input?.completed_requires_no_open_mandatory_violations === true && data.review_input?.completed_requires_no_blank_applicable_rows === true && data.review_input?.reviewer_write_implementation === "forbidden" && includesAll(data.review_input?.standards_sources, ["slice_contract_required_skills", "specialist_check_inputs", "review_report_template"]), "review_input 未强制专项检查覆盖或 finding 闭环完成条件");
   for (const id of ["work-unit.spec-synthesis", "work-unit.ticket-decomposition", "work-unit.slice-implementation"]) {
@@ -184,13 +187,13 @@ const profiles = {
   },
   prototype: {
     message: "原型到后端脚手架及后续 YSS 代码生成压力场景验证通过",
-    files: [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", ".agents/skills/yss-router/references/router-contract.yaml"],
+    files: [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml"],
     markers: [[".agents/skills/yss-product-lifecycle/SKILL.md", "controlled-generation"]]
   },
-  router: {
-    message: "YSS Router stage 7 scenarios passed",
-    files: [".agents/skills/yss-router/references/router-contract.yaml", ".agents/skills/yss-router/SKILL.md"],
-    markers: [[".agents/skills/yss-router/references/router-contract.yaml", "slice_contract_required"]]
+  implementationContractCompiler: {
+    message: "YSS implementation contract compiler stage 7 scenarios passed",
+    files: [".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml", ".agents/skills/yss-implementation-contract-compiler/SKILL.md"],
+    markers: [[".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml", "impact_to_capabilities"], [".agents/skills/yss-implementation-contract-compiler/SKILL.md", "required_capabilities"]]
   },
   openapiYaml: {
     message: "OpenAPI YAML-first 场景验证通过",

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)), "../..");
 
@@ -48,6 +49,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,6 +63,26 @@ 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-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])));
@@ -77,14 +99,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", "schema v3", "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", "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: 3", "prototype_profile", "visual_review", "flow_review", "implementation_handoff", "project_token_baseline_digest", "verification/design-qa.md"]) {
+    if (!prototypeEvidence.includes(marker)) fail(`原型证据模板缺少 schema v3 字段: ${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"))) {
+    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")
   });