create-yss-spec 3.0.0 → 3.1.0

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

@@ -0,0 +1,227 @@
+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";
+import { architectureDigest, assertArchitectureAgreement, validateArchitectureIdentity } from "./backend-architecture.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,
+  architecture_identity,
+  architecture_evidence
+}) {
+  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 retiredRecipes = new Set(["backend.domain-behavior", "backend.persistence-mybatis", "backend.http-api"]);
+  for (const recipe of orderedRecipes) if (retiredRecipes.has(recipe.id) || recipe.maturity === "deprecated") fail(`deprecated/read-only Recipe ${recipe.id}；必须按架构重新编译`);
+  const architectural = orderedRecipes.some((recipe) => recipe.architecture_family) || requiredCapabilities.some((id) => id.startsWith("layer."));
+  let architectureProfile;
+  if (architectural || architecture_identity) {
+    architectureProfile = validateArchitectureIdentity(architecture_identity, registry);
+    if (!architecture_evidence?.engineering_baseline || !architecture_evidence?.repository_registration || !architecture_evidence?.manifest) fail("缺少工程基线、仓库登记或 Manifest 架构证据");
+    assertArchitectureAgreement(architecture_identity, architecture_evidence, registry);
+    for (const recipe of orderedRecipes) if (recipe.architecture_family && recipe.architecture_family !== architecture_identity.architecture_family) fail(`Recipe ${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 dddCapabilities = new Set(["layer.domain", "layer.application", "layer.persistence", "layer.web-adapter"]);
+  for (const id of orderedCapabilities) {
+    const family = capabilities.get(id).architecture_family ?? (dddCapabilities.has(id) ? "domain-driven" : null);
+    if (family && family !== architecture_identity?.architecture_family) fail(`capability ${id} 与 architecture_identity 不匹配`);
+  }
+  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",
+    ...(architecture_identity ? {
+      architecture_identity: structuredClone(architecture_identity),
+      architecture_identity_digest: architectureDigest(architecture_identity),
+      profile_maturity: architectureProfile.maturity,
+      readiness_blockers: architectureProfile.maturity === "supported" ? [] : ["backend-profile-not-supported"],
+      skill_profiles: Object.fromEntries(orderedSkills.map((skill) => [skill, architecture_identity.architecture_profile]))
+    } : {}),
+    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");
+  if (resolution.architecture_identity) {
+    try { validateArchitectureIdentity(resolution.architecture_identity, registry); }
+    catch { reasons.push("architecture-identity-invalid"); }
+    if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-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 (resolution.architecture_identity && architectureDigest(result.architecture_identity ?? null) !== resolution.architecture_identity_digest) blockers.push("architecture-identity-mismatch");
+  if (resolution.readiness_blockers?.length) blockers.push(...resolution.readiness_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");
+    else if (item.exit_code !== 0) blockers.push("verification-failed");
+  }
+  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/lifecycle-registry.mjs

@@ -51,7 +51,10 @@ function canonicalize(value) {
 }
 
 export function semanticProjection(registry) {
-  return COLLECTIONS.flatMap((kind) => registry[kind].map((record) => ({ kind, record: canonicalize(record) })))
+  return COLLECTIONS.flatMap((kind) => registry[kind].map((record) => ({
+    kind,
+    record: canonicalize(Object.fromEntries(Object.entries(record).filter(([key]) => !key.startsWith("public_"))))
+  })))
     .sort((left, right) => left.record.id.localeCompare(right.record.id));
 }
 
@@ -117,6 +120,9 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
       const prefix = collection === "work_units" ? "work-unit." : collection === "evidence" ? "evidence." : `${collection.slice(0, -1)}.`;
       if (!id.startsWith(prefix)) fail(`${id} 与 ${collection} 类型不匹配`);
       if (typeof record.name !== "string" || record.name.length === 0) fail(`${id} 缺少名称`);
+      for (const [key, value] of Object.entries(record).filter(([key]) => key.startsWith("public_"))) {
+        if (typeof value !== "string" || value.trim().length === 0) fail(`${id}.${key} 必须是非空字符串`);
+      }
       ids.set(id, collection);
     }
   }
@@ -143,25 +149,27 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
 }
 
 export function renderLifecycleStructure(registry) {
+  const display = (record, field) => record[`public_${field}`] ?? record[field];
   const lines = [
     "<!-- lifecycle-registry:structure:start -->",
     `> 此结构区由 \`docs/process/lifecycle-registry.yaml\` 生成。当前为 \`${registry.status}\` 模式：它校验结构和派生文档，不改变运行时状态 schema 或人工批准语义。`, "",
     "## 1. 主阶段", "", "| 稳定 ID | 阶段 | 目标 | 退出标准 |", "|---|---|---|---|"
   ];
-  for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${stage.name} | ${stage.goal} | ${stage.exit_criteria} |`);
+  for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${display(stage, "name")} | ${display(stage, "goal")} | ${display(stage, "exit_criteria")} |`);
   lines.push("", "## 2. 生命周期对象", "", "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 \`not-applicable\` 及原因，不生成空文档。", "", "### 2.1 条件门禁", "", "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 前置门禁 | 必须留下的证据 |", "|---|---|---|---|---|---|");
-  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${gate.name} | \`${gate.stage}\` | ${gate.trigger} | ${(gate.requires_gates ?? []).map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
+  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${display(gate, "name")} | \`${gate.stage}\` | ${display(gate, "trigger")} | ${(gate.requires_gates ?? []).map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
   lines.push("", "### 2.2 生命周期产物", "", "| 稳定 ID | 产物 | 所属阶段 | 触发条件 |", "|---|---|---|---|");
-  for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${artifact.name} | \`${artifact.stage}\` | ${artifact.trigger} |`);
+  for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${display(artifact, "name")} | \`${artifact.stage}\` | ${display(artifact, "trigger")} |`);
   lines.push("", "### 2.3 执行证据", "", "| 稳定 ID | 证据 | 说明 |", "|---|---|---|");
-  for (const evidence of registry.evidence) lines.push(`| \`${evidence.id}\` | ${evidence.name} | ${evidence.description} |`);
+  for (const evidence of registry.evidence) lines.push(`| \`${evidence.id}\` | ${display(evidence, "name")} | ${display(evidence, "description")} |`);
   lines.push("<!-- lifecycle-registry:structure:end -->");
   return `${lines.join("\n")}\n`;
 }
 
 export function renderWorkUnits(registry) {
+  const display = (record, field) => record[`public_${field}`] ?? record[field];
   const lines = ["<!-- lifecycle-registry:work-units:start -->", "> 此表由 `docs/process/lifecycle-registry.yaml` 生成；工作单元按 `scope` 区分模板维护与项目实例流程。", "", "| 稳定 ID | 范围 | 工作单元 | 输入 | 输出 | 完成条件 |", "|---|---|---|---|---|---|"];
-  for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.scope} | ${unit.name} | ${unit.input} | ${unit.output} | ${unit.completion} |`);
+  for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.scope} | ${display(unit, "name")} | ${display(unit, "input")} | ${display(unit, "output")} | ${display(unit, "completion")} |`);
   lines.push("<!-- lifecycle-registry:work-units:end -->");
   return `${lines.join("\n")}\n`;
 }

package/template/scripts/lib/lifecycle-transition.mjs

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { parseDocument } from "../vendor/yaml.mjs";
+import { assertWorkUnitUserDecision, assertImplementationDecision } from "./user-decision.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
@@ -110,10 +111,13 @@ function validateTicketReference(ref, trackerKind) {
  * Workflow Execution Result may omit a route; completed results are checked
  * by `validateWorkflowExecutionResult` before this function is called.
  */
-export function validateNextRoute(currentWorkUnit, nextRoute) {
+export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
   const routes = NEXT_ROUTES[currentWorkUnit];
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
-  if (nextRoute === null && routes.length === 0) return allowedResult();
+  if (nextRoute === null && routes.length === 0) {
+    if (decisionState) return validateDecisionBoundary(currentWorkUnit, decisionState, options);
+    return allowedResult();
+  }
   if (!hasText(nextRoute) || !routes.includes(nextRoute)) {
     const signals = [BLOCKING_SIGNALS.invalidRoute];
     if (nextRoute === IMPLEMENTATION_WORK_UNIT && currentWorkUnit !== TICKET_DECOMPOSITION_WORK_UNIT) {
@@ -121,14 +125,19 @@ export function validateNextRoute(currentWorkUnit, nextRoute) {
     }
     return blockedResult(signals, ["allowed_next_route"]);
   }
-  return allowedResult();
+  return decisionState ? validateDecisionBoundary(currentWorkUnit, decisionState, options) : allowedResult();
+}
+
+function validateDecisionBoundary(workUnit, state, options) {
+  try { assertWorkUnitUserDecision(workUnit, state, options); return allowedResult(); }
+  catch (error) { return blockedResult([error.code || "user-decision-invalid"], [error.message]); }
 }
 
 /**
  * Validate that Ticket formalization produced a real, implementable vertical slice.
  * `exists` is injectable so external adapters can resolve their own tracker refs.
  */
-export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8") } = {}) {
+export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
   const decomposition = state?.ticket_decomposition_result;
   const ticket = state?.vertical_slice_ticket;
   const contract = state?.slice_contract;
@@ -233,6 +242,12 @@ export function validateTicketFormalization(state, { exists = existsSync, read =
     missing.push("ticket formalization inputs are current");
   }
 
+  try {
+    assertImplementationDecision(state, { ...decisionOptions, read });
+  } catch (error) {
+    signals.push(error.code || "user-decision-invalid");
+    missing.push(error.message);
+  }
   return signals.length === 0 ? allowedResult(evidenceRefs) : blockedResult(signals, missing, evidenceRefs);
 }
 

package/template/scripts/lib/scaffold-local-database.mjs

@@ -0,0 +1,26 @@
+/** 新后端骨架仅提供显式本地验证配置；不绑定生产数据库。 */
+export const VERIFICATION_DATABASE = "h2";
+export const PRODUCTION_DATABASE = "not-bound";
+
+export function assertLocalDatabaseProfile(profiles) {
+  if (profiles?.verification_database !== VERIFICATION_DATABASE || profiles?.production_database !== PRODUCTION_DATABASE || Object.hasOwn(profiles ?? {}, "database")) {
+    throw new Error("新脚手架必须声明 verification_database=h2、production_database=not-bound；旧 database Profile 必须重新批准，不作静默迁移");
+  }
+}
+
+export function localDatabaseConfiguration(name) {
+  return `# 仅通过 scaffold-local 显式启用；不用于生产。\nspring:\n  datasource:\n    url: jdbc:h2:mem:${name.replaceAll("-", "_")};DB_CLOSE_DELAY=-1\n    username: sa\n    password: \"\"\n    driver-class-name: org.h2.Driver\n  sql:\n    init:\n      mode: never\n  cloud:\n    discovery:\n      enabled: false\n    service-registry:\n      auto-registration:\n        enabled: false\n    nacos:\n      discovery:\n        enabled: false\n      config:\n        enabled: false\n  cache:\n    type: none\n`;
+}
+
+export function scaffoldArchitectureIdentity(contract, contractDigest) {
+  return {
+    architecture_family: contract.architecture_family,
+    architecture_profile: contract.architecture_profile,
+    generator_skill: contract.generator_skill,
+    requested_capabilities: contract.module_profile.requested_capabilities,
+    resolved_modules: contract.module_profile.resolved_modules,
+    contract_digest: contractDigest,
+    verification_database: VERIFICATION_DATABASE,
+    production_database: PRODUCTION_DATABASE
+  };
+}

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

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { buildDecisionFixture, buildImplementationFixture } from "../fixtures/user-decision/build-fixture.mjs";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { parseDocument } from "../vendor/yaml.mjs";
@@ -15,10 +17,8 @@ const virtualTicketDecompositionRef = "docs/.scratch/demo/evidence/ticket-decomp
 const virtualTicketDecomposition = "result_schema: workflow-execution-result-v1\nwork_unit: work-unit.ticket-decomposition\nresult: completed\nevidence_refs:\n  - docs/.scratch/demo/evidence/ticket-decomposition-result.yaml\n";
 
 function validateMattContract(data) {
-  const direct = data.entry_routing?.direct_matt_entry;
-  ensure(direct?.skill === "ask-matt" && direct?.delegate_to === "yss-product-lifecycle" && direct?.requires_valid_manifest === true && direct?.action === "navigate-only" && direct?.lifecycle_state_mutation === "forbidden" && direct?.lifecycle_artifact_write === "forbidden" && direct?.return_to_orchestrator === "required", "ask-matt 导航入口尚未形成验明身份、只导航、禁止生命周期写入并强制回交主控的完整契约");
   const formal = data.entry_routing?.formal_user_entry;
-  ensure(includesAll(formal?.skills, ["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]) && formal?.action === "lifecycle-validate-and-accept" && formal?.lifecycle_artifact_write === "conditional-explicit-user-entry" && formal?.return_to_orchestrator === "required", "正式用户入口未区分于 ask-matt 导航入口");
+  ensure(includesAll(formal?.skills, ["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]) && formal?.action === "lifecycle-validate-and-accept" && formal?.lifecycle_artifact_write === "conditional-explicit-user-entry" && formal?.return_to_orchestrator === "required", "正式用户入口缺少生命周期预检与回交约束");
   const setup = data.setup_readiness;
   ensure(setup?.missing_action === "needs-human" && setup?.requested_skill === "setup-matt-pocock-skills" && setup?.resume_route === "setup-readiness" && setup?.lifecycle_may_invoke_setup === false, "setup 缺失时未限制为显式用户入口暂停");
   ensure(includesAll(setup?.preserves, ["lifecycle.status", "gate.status", "ticket.role"]) && setup?.legacy_artifacts_detected?.action === "migration-check" && setup.legacy_artifacts_detected.setup === "forbidden" && setup.legacy_artifacts_detected.write === "paused", "setup 暂停或旧资产迁移暂停契约不完整");
@@ -39,8 +39,8 @@ function validateMattContract(data) {
 
 function validateInvocationBoundary(data) {
   const boundary = data.matt_invocation_boundary;
-  const expectedUserInvoked = ["ask-matt", "grill-me", "grill-with-docs", "handoff", "implement", "improve-codebase-architecture", "loop-me", "setup-matt-pocock-skills", "setup-ts-deep-modules", "teach", "to-questionnaire", "to-spec", "to-tickets", "triage", "wait-what", "wayfinder", "writing-beats", "writing-fragments", "writing-shape"];
-  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "migrate-to-shoehorn", "prototype", "resolving-merge-conflicts", "scaffold-exercises", "setup-pre-commit", "tdd", "writing-for-agents", "yss-research"];
+  const expectedUserInvoked = ["grill-me", "grill-with-docs", "handoff", "implement", "improve-codebase-architecture", "setup-matt-pocock-skills", "to-questionnaire", "to-spec", "to-tickets", "triage", "wait-what", "wayfinder"];
+  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "resolving-merge-conflicts", "tdd", "writing-for-agents", "yss-research"];
   const expectedLifecycleModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "tdd", "yss-research"];
   ensure(JSON.stringify(boundary?.user_invoked_skills) === JSON.stringify(expectedUserInvoked), "Matt user-invoked skills 清单不完整或已漂移");
   ensure(JSON.stringify(boundary?.lifecycle_managed_user_entries) === JSON.stringify(["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]), "生命周期管理的显式用户入口清单不完整");
@@ -53,10 +53,10 @@ function validateInvocationBoundary(data) {
   const result = data.workflow_execution_result;
   ensure(data.matt_skill_result?.status === "compatibility-read-only" && data.matt_skill_result?.may_influence_routing === false && data.matt_skill_result?.normalize_to === "workflow-execution-result-v1", "旧 Matt Skill Result 未限制为只读兼容 adapter");
   ensure(result?.canonical_output_schema === "workflow-execution-result-v1" && JSON.stringify(result?.accepted_input_schemas) === JSON.stringify(["workflow-execution-result-v1"]) && result?.legacy?.["matt-skill-result-v1"]?.status === "compatibility-read-only" && result.legacy["matt-skill-result-v1"].may_influence_routing === false && result.legacy["matt-skill-result-v1"].normalize_to === "workflow-execution-result-v1", "Workflow Execution Result 未将旧 Matt Skill Result 限制为只读兼容");
-  ensure(includesAll(result?.required, ["result_schema", "work_unit", "workflow_reference", "result", "evidence_refs", "changed_artifacts", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) && includesAll(result?.result_values, ["completed", "blocked", "needs-human", "failed"]) && includesAll(result?.blocking_signals, ["drift", "new_impacts", "violation", "missing_evidence", "stale_candidates"]) && includesAll(result?.completed_requires_empty, ["new_impacts", "stale_candidates"]) && includesAll(result?.completed_requires_non_empty, ["evidence_refs"]) && result?.completed_requires_readable_evidence_refs === true && result?.evidence_ref_validation === "readable-or-resolvable" && result?.completed_requires_no_blocking_signals === true && includesAll(result?.workflow_reference?.required, ["source", "skill", "invocation_mode"]), "Workflow Execution Result 的完成态证据、阻断信号或 workflow_reference 契约不完整");
+  ensure(includesAll(result?.required, ["result_schema", "work_unit", "workflow_reference", "result", "context_reconciliation", "evidence_refs", "changed_artifacts", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) && includesAll(result?.result_values, ["completed", "blocked", "needs-human", "failed"]) && includesAll(result?.blocking_signals, ["drift", "new_impacts", "violation", "missing_evidence", "stale_candidates"]) && includesAll(result?.completed_requires_empty, ["new_impacts", "stale_candidates"]) && includesAll(result?.completed_requires_non_empty, ["evidence_refs"]) && result?.completed_requires_readable_evidence_refs === true && result?.evidence_ref_validation === "readable-or-resolvable" && result?.completed_requires_no_blocking_signals === true && result?.context_reconciliation?.creates_gate === false && includesAll(result?.workflow_reference?.required, ["source", "skill", "invocation_mode"]), "Workflow Execution Result 的完成态证据、阻断信号、context_reconciliation 或 workflow_reference 契约不完整");
   const native = data.lifecycle_native_entries;
   ensure(native?.default_entry === "yss-product-lifecycle" && native?.formal_artifact_owner === "yss-product-lifecycle", "生命周期原生入口未持有默认正式资产所有权");
-  ensure(JSON.stringify(native?.user_confirmation_required_at) === JSON.stringify(["spec-baseline", "prototype-confirmation", "openapi-freeze", "merge-or-release"]), "生命周期人工门禁集合已漂移");
+  ensure(native?.user_confirmation_policy_ref === "docs/agents/digital-human-roles.yaml#user_decision_policy", "生命周期人工门禁集合已漂移");
   const routes = data.work_unit_routes;
   ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
   ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "yss-research:technical-evidence" && routes["work-unit.discovery-opportunity"].route_by.strategy_fact === "yss-research:strategy-evidence", "机会调研事实路由不准确");
@@ -64,9 +64,12 @@ 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 主入口、业务页面生成或页面编排技能");
+  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-ui-business-page-generation", "前端实现路由缺少 yss-ui 主入口或统一业务页面技能");
   for (const impact of ["api_impact", "formily_impact", "table_impact", "tree_impact", "height_impact", "export_impact", "theme_impact"]) {
     ensure(Array.isArray(frontendRoute?.conditional_skills?.[impact]) && frontendRoute.conditional_skills[impact].length > 0 && typeof frontendRoute.not_applicable_reasons?.[impact] === "string", `前端条件专项路由缺少 ${impact}`);
   }
@@ -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"]) {
@@ -102,8 +105,10 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   const workUnit = workUnitRoutes?.[payload.work_unit];
   ensure(workUnit, `未知 Workflow Execution Result work_unit: ${payload.work_unit}`);
   if (payload.result === "completed") {
-    const routeResult = validateNextRoute(payload.work_unit, payload.next_route);
+    const routeResult = validateNextRoute(payload.work_unit, payload.next_route, payload);
     ensure(routeResult.result === "allowed", `Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
+    ensure(payload.context_reconciliation?.status === "reconciled", "project-instance 完成态必须具有 reconciled context_reconciliation");
+    ensure(hasText(payload.context_reconciliation?.ref) && payload.evidence_refs.includes(payload.context_reconciliation.ref) && exists(payload.context_reconciliation.ref), "context_reconciliation.ref 必须可读并包含在 evidence_refs 中");
   }
   const accepted = [workUnit.native, workUnit.compatibility].filter(Boolean);
   ensure(contract.workflow_reference.allowed_sources.includes(payload.workflow_reference.source) && accepted.some((route) => route.source === payload.workflow_reference.source && route.skill === payload.workflow_reference.skill && route.invocation_mode === payload.workflow_reference.invocation_mode), "Workflow Execution Result workflow_reference 与 work_unit route 不匹配");
@@ -118,6 +123,8 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   }
   if (payload.work_unit === "work-unit.slice-implementation" && payload.result === "completed") {
     const implementationState = {
+      user_decisions: payload.user_decisions,
+      slice_contract_ref: payload.slice_contract_ref,
       tracker_kind: payload.tracker_kind,
       predecessor_work_unit: payload.predecessor_work_unit,
       ready_for_agent: payload.ready_for_agent,
@@ -138,7 +145,7 @@ function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
       // The scenario uses one explicit virtual fixture; arbitrary local refs
       // must still pass the real readability check and cannot use a fallback.
       exists: (ref) => exists(ref) || ref === "docs/.scratch/demo/issues/01-valid-slice.md" || ref === virtualTicketDecompositionRef,
-      read: (ref) => ref === virtualTicketDecompositionRef ? virtualTicketDecomposition : readFileSync(path.join(root, ref), "utf8"),
+      read: (ref) => ref === virtualTicketDecompositionRef ? virtualTicketDecomposition : readFileSync(path.resolve(root, ref), "utf8"),
     });
     ensure(semantic.result === "allowed", `Workflow Execution Result implementation Ticket 语义非法: ${semantic.blocking_signals.join(", ")}`);
   }
@@ -184,13 +191,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 场景验证通过",
@@ -253,11 +260,17 @@ export function runScenario(name) {
     const data = contract.toJS({ maxAliasCount: 0 });
     validateMattContract(data);
     validateInvocationBoundary(data);
+    const decisionTemp = mkdtempSync(path.join(os.tmpdir(), "matt-decision-test-"));
+    process.on("exit", () => rmSync(decisionTemp, { recursive: true, force: true }));
+    const specDecision = buildDecisionFixture(path.join(decisionTemp, "spec"));
+    const implementationDecision = buildImplementationFixture(path.join(decisionTemp, "implementation"), "docs/.scratch/demo/issues/01-valid-slice.md");
     const validResult = {
+      user_decisions: [specDecision.requirement],
       result_schema: "workflow-execution-result-v1",
       work_unit: "work-unit.spec-synthesis",
       workflow_reference: { source: "yss-product-lifecycle", skill: "yss-product-lifecycle", invocation_mode: "model-invoked" },
       result: "completed",
+      context_reconciliation: { status: "reconciled", ref: "docs/process/lifecycle-registry.yaml" },
       evidence_refs: ["docs/process/lifecycle-registry.yaml"],
       changed_artifacts: [],
       new_impacts: [],
@@ -276,6 +289,7 @@ export function runScenario(name) {
     validateWorkflowExecutionResult(validTicketResult, data.workflow_execution_result, data.work_unit_routes);
     const validImplementationResult = {
       ...validResult,
+      ...implementationDecision.state,
       evidence_refs: [virtualTicketDecompositionRef, "docs/process/lifecycle-registry.yaml"],
       work_unit: "work-unit.slice-implementation",
       next_route: "work-unit.code-review",
@@ -321,6 +335,8 @@ export function runScenario(name) {
     validateWorkflowExecutionResult(compatibleResult, data.workflow_execution_result, data.work_unit_routes);
     for (const mutate of [
       (item) => { delete item.workflow_reference; },
+      (item) => { delete item.context_reconciliation; },
+      (item) => { item.context_reconciliation.status = "blocked"; },
       (item) => { item.evidence_refs = []; },
       (item) => { item.evidence_refs = ["docs/process/not-found.md"]; },
       (item) => { item.blocking_signals = ["drift"]; },
@@ -341,7 +357,7 @@ export function runScenario(name) {
     } catch { metadataRejected = true; }
     ensure(metadataRejected, "user-invoked front matter 变异未被 baseline oracle 拒绝");
     const mutations = [
-      (item) => { delete item.entry_routing.direct_matt_entry.return_to_orchestrator; },
+      (item) => { delete item.entry_routing.formal_user_entry.return_to_orchestrator; },
       (item) => { item.entry_routing.formal_user_entry.lifecycle_artifact_write = "forbidden"; },
       (item) => { item.matt_invocation_boundary.user_invoked_skills.push("unexpected-user-entry"); },
       (item) => { item.setup_readiness.lifecycle_may_invoke_setup = true; },