create-yss-spec 3.3.6 → 3.3.7

package/template/.agents/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs

@@ -18,6 +18,7 @@ const idPatterns = {
   concept_id: /^domain-concept\.[a-z0-9][a-z0-9-]*$/,
   invariant_id: /^invariant\.[a-z0-9][a-z0-9-]*$/
 };
+const consumerCapabilities = new Set(["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]);
 const relationshipPatterns = new Set(["Partnership", "Customer/Supplier", "Conformist", "Anti-Corruption Layer", "Open Host Service", "Published Language", "Shared Kernel", "Separate Ways"]);
 
 function fail(errors) {
@@ -53,7 +54,7 @@ function validate(data, contextRoot) {
   if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
   if (data.schema_version === 1) return ["migration-required: domain strategy v1 必须迁移到 v2 context_snapshot"];
   for (const field of required) requireField(data, field, "root", errors);
-  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
+  if (![2, 3].includes(data.schema_version)) errors.push("schema_version 不受支持；支持版本: 2, 3；新交付请迁移到 3");
   if (!idPatterns.domain_strategy_id.test(String(data.domain_strategy_id ?? ""))) errors.push("domain_strategy_id 格式非法");
   if (!/^v[0-9]+$/.test(String(data.domain_version ?? ""))) errors.push("domain_version 必须形如 v1");
   if (!["draft", "ready-for-human", "approved", "stale", "blocked"].includes(data.status)) errors.push("status 非法");
@@ -71,6 +72,23 @@ function validate(data, contextRoot) {
     if (context?.subdomain_type && !["Core Domain", "Supporting Subdomain", "Generic Subdomain"].includes(context.subdomain_type)) errors.push(`${path}.subdomain_type 非法`);
   }
 
+  const sourceIds = new Set();
+  if (data.schema_version === 3) {
+    if (data.traceability_version !== 1) errors.push("traceability_version 必须为 1");
+    requireArray(data, "rule_catalog", "root", errors, 1, "object");
+    const rules = list(data.rule_catalog) ? data.rule_catalog : [];
+    unique(rules.map((item) => item?.rule_id).filter(Boolean), "rule_id", errors);
+    for (const [index, rule] of rules.entries()) {
+      const path = `rule_catalog[${index}]`;
+      for (const field of ["rule_id", "statement", "responsible_context", "status"]) requireString(rule ?? {}, field, path, errors);
+      requireArray(rule ?? {}, "evidence_refs", path, errors, 1);
+      if (!/^rule\.[a-z0-9][a-z0-9-]*$/.test(String(rule?.rule_id ?? ""))) errors.push(`${path}.rule_id 格式非法`);
+      if (rule?.responsible_context && !contextIds.includes(rule.responsible_context)) errors.push(`${path}.responsible_context 未声明`);
+      if (rule?.status !== "confirmed") errors.push(`${path}.status 必须为 confirmed`);
+      if (rule?.rule_id) sourceIds.add(rule.rule_id);
+    }
+  }
+
   requireArray(data, "subdomains", "root", errors, 1, "object");
   const subdomains = list(data.subdomains) ? data.subdomains : [];
   unique(subdomains.map((item) => item?.subdomain_id).filter(Boolean), "subdomain_id", errors);
@@ -110,6 +128,14 @@ function validate(data, contextRoot) {
     if (scenario?.scenario_id && !idPatterns.scenario_id.test(scenario.scenario_id)) errors.push(`${path}.scenario_id 格式非法`);
     if (scenario?.responsible_context && !contextIds.includes(scenario.responsible_context)) errors.push(`${path}.responsible_context 未声明`);
     for (const consumer of scenario?.consumers ?? []) if (!contextIds.includes(consumer)) errors.push(`${path}.consumers 引用了未声明上下文: ${consumer}`);
+    if (scenario?.scenario_id) sourceIds.add(scenario.scenario_id);
+    if (data.schema_version === 3) {
+      requireArray(scenario ?? {}, "rule_refs", path, errors, 1);
+      requireArray(scenario ?? {}, "success_results", path, errors, 1);
+      requireArray(scenario ?? {}, "evidence_refs", path, errors, 1);
+      if (typeof scenario?.critical !== "boolean") errors.push(`${path}.critical 必须是 boolean`);
+      for (const reference of scenario?.rule_refs ?? []) if (!sourceIds.has(reference)) errors.push(`${path}.rule_refs 引用了未声明规则: ${reference}`);
+    }
   }
 
   const concepts = list(data.concept_candidates) ? data.concept_candidates : [];
@@ -132,6 +158,12 @@ function validate(data, contextRoot) {
     if (invariant?.invariant_id && !idPatterns.invariant_id.test(invariant.invariant_id)) errors.push(`${path}.invariant_id 格式非法`);
     if (invariant?.responsible_context && !contextIds.includes(invariant.responsible_context)) errors.push(`${path}.responsible_context 未声明`);
     for (const reference of invariant?.scenario_refs ?? []) if (!scenarioIds.includes(reference)) errors.push(`${path}.scenario_refs 引用了未声明场景: ${reference}`);
+    if (invariant?.invariant_id) sourceIds.add(invariant.invariant_id);
+    if (data.schema_version === 3) {
+      requireString(invariant ?? {}, "rule_ref", path, errors);
+      requireArray(invariant ?? {}, "evidence_refs", path, errors, 1);
+      if (invariant?.rule_ref && !sourceIds.has(invariant.rule_ref)) errors.push(`${path}.rule_ref 引用了未声明规则: ${invariant.rule_ref}`);
+    }
   }
 
   try {
@@ -141,11 +173,21 @@ function validate(data, contextRoot) {
   }
   requireArray(data, "evidence_refs", "root", errors, 1);
   const mappings = list(data.downstream_mapping) ? data.downstream_mapping : [];
+  if (data.schema_version === 3) unique(mappings.map((item) => item?.mapping_id).filter(Boolean), "mapping_id", errors);
   for (const [index, mapping] of mappings.entries()) {
     const path = `downstream_mapping[${index}]`;
-    for (const field of ["domain_change", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
-    requireArray(mapping ?? {}, "impacts", path, errors, 1);
-    if (mapping?.propagation && !["direct", "transitive", "stale"].includes(mapping.propagation)) errors.push(`${path}.propagation 非法`);
+    if (data.schema_version === 3) {
+      for (const field of ["mapping_id", "consumer_capability", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
+      for (const field of ["source_refs", "impacts", "evidence_refs"]) requireArray(mapping ?? {}, field, path, errors, 1);
+      if (!/^mapping\.[a-z0-9][a-z0-9-]*$/.test(String(mapping?.mapping_id ?? ""))) errors.push(`${path}.mapping_id 格式非法`);
+      if (mapping?.consumer_capability && !consumerCapabilities.has(mapping.consumer_capability)) errors.push(`${path}.consumer_capability 非法`);
+      for (const reference of mapping?.source_refs ?? []) if (!sourceIds.has(reference)) errors.push(`${path}.source_refs 引用了未声明来源: ${reference}`);
+      if (mapping?.propagation && !["direct", "transitive", "not-applicable", "stale"].includes(mapping.propagation)) errors.push(`${path}.propagation 非法`);
+    } else {
+      for (const field of ["domain_change", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
+      requireArray(mapping ?? {}, "impacts", path, errors, 1);
+      if (mapping?.propagation && !["direct", "transitive", "stale"].includes(mapping.propagation)) errors.push(`${path}.propagation 非法`);
+    }
   }
   const approval = data.approval ?? {};
   for (const field of ["approval_ref", "approver", "persisted_ref", "current_version"]) requireString(approval, field, "approval", errors);

package/template/.agents/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs

@@ -10,6 +10,7 @@ import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.
 
 const required = ["schema_version", "stage_decision_id", "package_version", "status", "problem_statement", "target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "unresolved_items", "context_snapshot", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"];
 const idPattern = /^stage-decision\.[a-z0-9][a-z0-9-]*$/;
+const consumerCapabilities = new Set(["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]);
 
 function fail(errors) {
   process.stderr.write(`${JSON.stringify({ result: "blocked", errors }, null, 2)}\n`);
@@ -18,7 +19,8 @@ function fail(errors) {
 function nonEmpty(value) { return typeof value === "string" && value.trim().length > 0; }
 function requireField(object, field, path, errors) { if (!(field in object) || object[field] === null || object[field] === undefined) errors.push(`${path}.${field} 缺失`); }
 function requireString(object, field, path, errors) { requireField(object, field, path, errors); if (field in object && !nonEmpty(object[field])) errors.push(`${path}.${field} 必须是非空字符串`); }
-function requireArray(object, field, path, errors, min = 0) { requireField(object, field, path, errors); if (field in object && (!Array.isArray(object[field]) || object[field].length < min)) errors.push(`${path}.${field} 必须是至少 ${min} 项的数组`); if (field in object && Array.isArray(object[field])) object[field].forEach((item, index) => { if (!nonEmpty(item)) errors.push(`${path}.${field}[${index}] 必须是非空字符串`); }); }
+function requireArray(object, field, path, errors, min = 0, itemKind = "string") { requireField(object, field, path, errors); if (field in object && (!Array.isArray(object[field]) || object[field].length < min)) errors.push(`${path}.${field} 必须是至少 ${min} 项的数组`); if (field in object && Array.isArray(object[field]) && itemKind === "string") object[field].forEach((item, index) => { if (!nonEmpty(item)) errors.push(`${path}.${field}[${index}] 必须是非空字符串`); }); }
+function unique(items, label, errors) { const seen = new Set(); for (const item of items) { if (seen.has(item)) errors.push(`${label} 重复: ${item}`); seen.add(item); } }
 function canonical(value) { if (Array.isArray(value)) return value.map(canonical); if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])); return value; }
 function digest(value) { return `sha256:${createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex")}`; }
 
@@ -27,12 +29,13 @@ async function validate(data, contextRoot) {
   if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
   if (data.schema_version === 1) return ["migration-required: stage decision package v1 必须迁移到 v2 context_snapshot"];
   for (const field of required) requireField(data, field, "root", errors);
-  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
+  if (![2, 3].includes(data.schema_version)) errors.push("schema_version 不受支持；支持版本: 2, 3；新交付请迁移到 3");
   if (!idPattern.test(String(data.stage_decision_id ?? ""))) errors.push("stage_decision_id 格式非法");
   if (!/^v[0-9]+$/.test(String(data.package_version ?? ""))) errors.push("package_version 必须形如 v1");
   if (!["draft", "ready-for-human", "approved", "stale", "blocked"].includes(data.status)) errors.push("status 非法");
   for (const field of ["problem_statement"]) requireString(data, field, "root", errors);
-  for (const field of ["target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "evidence_refs"]) requireArray(data, field, "root", errors, ["target_users", "mvp", "success_criteria", "test_seams", "confirmed_decisions", "evidence_refs"].includes(field) ? 1 : 0);
+  for (const field of ["target_users", "mvp", "non_goals", "evidence_refs"]) requireArray(data, field, "root", errors, ["target_users", "mvp", "evidence_refs"].includes(field) ? 1 : 0);
+  for (const field of ["success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints"]) requireArray(data, field, "root", errors, ["success_criteria", "test_seams", "confirmed_decisions"].includes(field) ? 1 : 0, data.schema_version === 3 ? "object" : "string");
 
   const unresolved = Array.isArray(data.unresolved_items) ? data.unresolved_items : [];
   for (const [index, item] of unresolved.entries()) {
@@ -56,9 +59,38 @@ async function validate(data, contextRoot) {
         if (strategy.domain_version !== domainRef.domain_version) errors.push("domain_strategy_ref.domain_version 与实际文件不一致");
         if (strategy.status !== domainRef.status) errors.push("domain_strategy_ref.status 与实际文件不一致");
         if (domainRef.digest !== digest(strategy)) errors.push("domain_strategy_ref.digest 与实际领域战略内容不一致");
+        if (data.schema_version === 3 && strategy.schema_version !== 3) errors.push("Stage Decision v3 必须引用 Domain Strategy v3");
       }
     } catch (error) { errors.push(`domain_strategy_ref.persisted_ref 无法读取: ${error.message}`); }
   }
+
+  if (data.schema_version === 3) {
+    const sourceIds = new Set([
+      ...(strategy?.rule_catalog ?? []).map((item) => item?.rule_id),
+      ...(strategy?.scenarios ?? []).map((item) => item?.scenario_id),
+      ...(strategy?.invariants ?? []).map((item) => item?.invariant_id)
+    ].filter(Boolean));
+    const recordFields = {
+      success_criteria: "success-criterion",
+      test_seams: "test-seam",
+      confirmed_decisions: "decision",
+      assumptions: "assumption",
+      constraints: "constraint"
+    };
+    const recordIds = [];
+    for (const [field, prefix] of Object.entries(recordFields)) {
+      for (const [index, record] of (Array.isArray(data[field]) ? data[field] : []).entries()) {
+        const path = `${field}[${index}]`;
+        for (const name of ["id", "statement"]) requireString(record ?? {}, name, path, errors);
+        requireArray(record ?? {}, "evidence_refs", path, errors, 1);
+        if (!new RegExp(`^${prefix}\\.[a-z0-9][a-z0-9-]*$`).test(String(record?.id ?? ""))) errors.push(`${path}.id 格式非法`);
+        for (const reference of record?.source_refs ?? []) if (!sourceIds.has(reference)) errors.push(`${path}.source_refs 未在领域战略中声明: ${reference}`);
+        if (record?.status && !["confirmed", "candidate", "stale"].includes(record.status)) errors.push(`${path}.status 非法`);
+        if (record?.id) recordIds.push(record.id);
+      }
+    }
+    unique(recordIds, "stage record id", errors);
+  }
   try {
     const contextIds = Array.isArray(strategy?.contexts) ? strategy.contexts.map((item) => item?.context_id).filter(Boolean) : [];
     verifyContextSnapshot(data.context_snapshot, { root: contextRoot, allowedContextIds: contextIds });
@@ -73,9 +105,21 @@ async function validate(data, contextRoot) {
   }
   const mappings = Array.isArray(data.downstream_mapping) ? data.downstream_mapping : [];
   if (mappings.length < 1) errors.push("downstream_mapping 至少需要一项");
+  if (data.schema_version === 3) unique(mappings.map((item) => item?.mapping_id).filter(Boolean), "mapping_id", errors);
+  const strategySourceIds = new Set([
+    ...(strategy?.rule_catalog ?? []).map((item) => item?.rule_id),
+    ...(strategy?.scenarios ?? []).map((item) => item?.scenario_id),
+    ...(strategy?.invariants ?? []).map((item) => item?.invariant_id)
+  ].filter(Boolean));
   for (const [index, mapping] of mappings.entries()) {
     const path = `downstream_mapping[${index}]`;
-    for (const field of ["domain_change", "consumer", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
+    if (data.schema_version === 3) {
+      for (const field of ["mapping_id", "consumer_capability", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
+      requireArray(mapping ?? {}, "source_refs", path, errors, 1);
+      requireArray(mapping ?? {}, "evidence_refs", path, errors, 1);
+      if (mapping?.consumer_capability && !consumerCapabilities.has(mapping.consumer_capability)) errors.push(`${path}.consumer_capability 非法`);
+      for (const reference of mapping?.source_refs ?? []) if (!strategySourceIds.has(reference)) errors.push(`${path}.source_refs 未在领域战略中声明: ${reference}`);
+    } else for (const field of ["domain_change", "consumer", "propagation", "reapproval_condition"]) requireString(mapping ?? {}, field, path, errors);
     if (mapping?.propagation && !["direct", "transitive", "not-applicable", "stale"].includes(mapping.propagation)) errors.push(`${path}.propagation 非法`);
   }
   const approval = data.approval ?? {};

package/template/.agents/skills/yss-stage-decision/tests/fixtures/valid-stage-decision-package.yaml

@@ -1,16 +1,41 @@
-schema_version: 2
+schema_version: 3
 stage_decision_id: stage-decision.supplier-admission
-package_version: v2
+package_version: v3
 status: approved
 problem_statement: 合规准入决定分散，采购无法稳定判断当前有效资格。
 target_users: [采购专员、合规专员]
 mvp: [提交供应商申请、合规准入决定、采购侧有效性校验]
 non_goals: [供应商结算、采购付款、通用工作流平台]
-success_criteria: [新采购订单 100% 校验当前有效准入决定]
-test_seams: [supplier-application-submit, admission-validity-check]
-confirmed_decisions: [ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定]
-assumptions: [供应商已有唯一 subject_ref]
-constraints: [保留现有采购订单流程]
+success_criteria:
+  - id: success-criterion.current-admission
+    statement: 新采购订单 100% 校验当前有效准入决定。
+    source_refs: [rule.current-admission-required]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
+test_seams:
+  - id: test-seam.admission-validity-check
+    statement: admission-validity-check
+    source_refs: [scenario.admission-expires, invariant.current-admission-required]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
+confirmed_decisions:
+  - id: decision.compliance-owns-admission-rules
+    statement: ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定。
+    source_refs: [rule.current-admission-required]
+    evidence_refs: [evidence.domain-strategy-review.supplier]
+    status: confirmed
+assumptions:
+  - id: assumption.unique-subject-ref
+    statement: 供应商已有唯一 subject_ref。
+    source_refs: [scenario.supplier-submits]
+    evidence_refs: [evidence.discovery.supplier]
+    status: confirmed
+constraints:
+  - id: constraint.preserve-procurement-flow
+    statement: 保留现有采购订单流程。
+    source_refs: [scenario.admission-expires]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
 unresolved_items:
   - item: 供应商历史资料迁移范围
     type: deferred
@@ -25,7 +50,7 @@ context_snapshot:
   term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 domain_strategy_ref:
   domain_strategy_id: domain-strategy.supplier-admission
-  domain_version: v2
+  domain_version: v3
   digest: <domain-strategy-digest>
   status: approved
   persisted_ref: domain-strategy.yaml
@@ -38,17 +63,21 @@ impact_assessment:
   cross_repo: false
   high_risk: false
 downstream_mapping:
-  - domain_change: admission-decision-validity
-    consumer: spec-synthesis
+  - mapping_id: mapping.backend-admission-validity
+    source_refs: [rule.current-admission-required, invariant.current-admission-required]
+    consumer_capability: backend-technical-design
     propagation: direct
     reapproval_condition: 领域策略版本或有效性规则变化
-  - domain_change: admission-decision-validity
-    consumer: ticket-decomposition
+    evidence_refs: [evidence.domain-strategy-review.supplier]
+  - mapping_id: mapping.frontend-admission-validity
+    source_refs: [scenario.admission-expires]
+    consumer_capability: frontend-engineering-design
     propagation: transitive
     reapproval_condition: Spec 基线变更
+    evidence_refs: [evidence.domain-strategy-review.supplier]
 evidence_refs: [evidence.discovery.supplier, evidence.domain-strategy-review.supplier]
 approval:
   approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml
   approver: role.product-manager
   persisted_ref: docs/.scratch/supplier/stage-decision/stage-decision-package-v1.yaml
-  current_version: v2
+  current_version: v3

package/template/.agents/skills/yss-stage-decision/tests/fixtures/valid-supplier-domain.yaml

@@ -1,7 +1,19 @@
-schema_version: 2
+schema_version: 3
 domain_strategy_id: domain-strategy.supplier-admission
-domain_version: v2
+domain_version: v3
 status: approved
+traceability_version: 1
+rule_catalog:
+  - rule_id: rule.application-material-complete
+    statement: 申请材料必须完整
+    responsible_context: SupplierManagement
+    status: confirmed
+    evidence_refs: [evidence.discovery.supplier]
+  - rule_id: rule.current-admission-required
+    statement: 新采购订单必须引用当前有效的准入决定。
+    responsible_context: ComplianceReview
+    status: confirmed
+    evidence_refs: [evidence.discovery.compliance]
 contexts:
   - context_id: SupplierManagement
     name: 供应商管理
@@ -64,6 +76,10 @@ scenarios:
     preconditions: [供应商资料可编辑]
     commands: [SubmitSupplierApplication]
     rules: [申请材料必须完整]
+    rule_refs: [rule.application-material-complete]
+    critical: true
+    success_results: [完整申请进入合规审查]
+    evidence_refs: [evidence.discovery.supplier]
     events: [SupplierApplicationSubmitted]
     failure_results: [材料不完整时拒绝提交]
     responsible_context: SupplierManagement
@@ -73,7 +89,11 @@ scenarios:
     actor: compliance-officer
     preconditions: [批准决定存在]
     commands: [EvaluateAdmissionValidity]
-    rules: [过期决定不得支持新采购订单]
+    rules: [新采购订单必须引用当前有效的准入决定。]
+    rule_refs: [rule.current-admission-required]
+    critical: true
+    success_results: [过期准入决定不能支持新采购订单]
+    evidence_refs: [evidence.discovery.compliance]
     events: [SupplierAdmissionExpired]
     failure_results: [采购下单时资格校验失败]
     responsible_context: ComplianceReview
@@ -94,6 +114,8 @@ invariants:
     responsible_context: ComplianceReview
     scenario_refs: [scenario.admission-expires]
     verification_method: 领域场景测试和事件版本校验
+    rule_ref: rule.current-admission-required
+    evidence_refs: [evidence.discovery.compliance]
 context_snapshot:
   context_ref: CONTEXT.md
   context_schema_version: 1
@@ -101,13 +123,23 @@ context_snapshot:
   referenced_terms_digest: <referenced-terms-digest>
   term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 downstream_mapping:
-  - domain_change: admission-decision-validity
+  - mapping_id: mapping.backend-admission-validity
+    source_refs: [rule.current-admission-required, invariant.current-admission-required]
+    consumer_capability: backend-technical-design
     impacts: [spec, openapi, procurement-acceptance-tests]
     propagation: stale
     reapproval_condition: ComplianceReview 决定和有效期重新批准
+    evidence_refs: [evidence.discovery.compliance]
+  - mapping_id: mapping.frontend-admission-validity
+    source_refs: [scenario.admission-expires]
+    consumer_capability: frontend-engineering-design
+    impacts: [ui, frontend]
+    propagation: direct
+    reapproval_condition: 场景结果或视觉基线变化
+    evidence_refs: [evidence.discovery.compliance]
 evidence_refs: [evidence.discovery.supplier, evidence.discovery.compliance]
 approval:
   approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml
   approver: role.product-manager
   persisted_ref: docs/.scratch/supplier/domain/domain-strategy-v1.yaml
-  current_version: v2
+  current_version: v3

package/template/.agents/skills/yss-stage-decision/tests/run-scenarios.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { buildDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -14,6 +13,7 @@ const validator = join(testsRoot, "..", "scripts", "validate-domain-strategy.mjs
 const packageValidator = join(testsRoot, "..", "scripts", "validate-stage-decision-package.mjs");
 const contextValidator = join(projectRoot, "scripts", "verify-context-contract");
 const migrationTool = join(testsRoot, "..", "scripts", "migrate-context-references.mjs");
+const v3MigrationTool = join(testsRoot, "..", "scripts", "migrate-contract-v3.mjs");
 const validTemplate = join(testsRoot, "fixtures", "valid-supplier-domain.yaml");
 const validPackageTemplate = join(testsRoot, "fixtures", "valid-stage-decision-package.yaml");
 
@@ -29,6 +29,58 @@ function digestYaml(source) {
   return `sha256:${createHash("sha256").update(JSON.stringify(canonical(document.toJS({ maxAliasCount: 0 })))).digest("hex")}`;
 }
 
+function parseYaml(source) {
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new Error(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+function toV2Domain(source) {
+  const value = structuredClone(parseYaml(source));
+  value.schema_version = 2;
+  value.domain_version = "v2";
+  delete value.traceability_version;
+  delete value.rule_catalog;
+  for (const scenario of value.scenarios) {
+    delete scenario.rule_refs;
+    delete scenario.critical;
+    delete scenario.success_results;
+    delete scenario.evidence_refs;
+  }
+  for (const invariant of value.invariants) {
+    delete invariant.rule_ref;
+    delete invariant.evidence_refs;
+  }
+  value.downstream_mapping = [{
+    domain_change: "admission-decision-validity",
+    impacts: ["spec", "openapi", "procurement-acceptance-tests"],
+    propagation: "stale",
+    reapproval_condition: "ComplianceReview 决定和有效期重新批准"
+  }];
+  value.approval.current_version = "v2";
+  return value;
+}
+
+function toV2Stage(source, domainDigest) {
+  const value = structuredClone(parseYaml(source));
+  value.schema_version = 2;
+  value.package_version = "v2";
+  for (const field of ["success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints"]) {
+    value[field] = value[field].map((item) => item.statement);
+  }
+  value.domain_strategy_ref.domain_version = "v2";
+  value.domain_strategy_ref.digest = domainDigest;
+  value.domain_strategy_ref.persisted_ref = "domain-strategy-v2.yaml";
+  value.downstream_mapping = [{
+    domain_change: "admission-decision-validity",
+    consumer: "spec-synthesis",
+    propagation: "direct",
+    reapproval_condition: "领域策略版本或有效性规则变化"
+  }];
+  value.approval.current_version = "v2";
+  return value;
+}
+
 function run(command, file, contextRoot) {
   return spawnSync(process.execPath, [command, file, "--root", contextRoot], { cwd: projectRoot, encoding: "utf8" });
 }
@@ -56,34 +108,59 @@ context_schema_version: 1
 | 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | ComplianceReview | 避免：\`审批结果\` |
 `;
 
-const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-stage-decision-v2-"));
+const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-stage-decision-v3-"));
 try {
   await writeFile(join(temporaryRoot, "CONTEXT.md"), contextSource);
   const contextResult = spawnSync(process.execPath, [contextValidator, "--root", temporaryRoot, "--allowed-context", "SupplierManagement", "--allowed-context", "ComplianceReview", "--allowed-context", "ProcurementExecution", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json"], { cwd: projectRoot, encoding: "utf8" });
   if (contextResult.status !== 0) throw new Error(`context fixture should pass: ${contextResult.stderr}`);
   const context = JSON.parse(contextResult.stdout);
 
-  const domainApprovalRef = join(temporaryRoot, "domain-approval.json");
   const domainSource = (await readFile(validTemplate, "utf8"))
-    .replace(".agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml", domainApprovalRef)
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest);
   const domainFile = join(temporaryRoot, "domain-strategy.yaml");
   await writeFile(domainFile, domainSource);
-  const domainDecision = buildDecisionFixture(join(temporaryRoot, "domain-decision"), { boundary: "check.domain-strategy-approved", subjectRef: domainFile });
-  const domainApproval = parseDocument(await readFile(join(testsRoot, "fixtures/domain-strategy-approval.yaml"), "utf8")).toJS();
-  await writeFile(domainApprovalRef, JSON.stringify({ ...domainApproval, subject_ref: domainFile, approval_scope: domainDecision.requirement.scope, user_decision_ref: domainDecision.ref }));
   const pass = run(validator, domainFile, temporaryRoot);
-  if (pass.status !== 0) throw new Error(`valid v2 fixture should pass: ${pass.stderr}`);
+  if (pass.status !== 0) throw new Error(`valid v3 fixture should pass: ${pass.stderr}`);
+
+  const v2Domain = toV2Domain(domainSource);
+  const v2DomainSource = JSON.stringify(v2Domain, null, 2);
+  const v2DomainFile = join(temporaryRoot, "domain-strategy-v2.yaml");
+  await writeFile(v2DomainFile, v2DomainSource);
+  const v2Pass = run(validator, v2DomainFile, temporaryRoot);
+  if (v2Pass.status !== 0) throw new Error(`read-only v2 fixture should pass: ${v2Pass.stderr}`);
+
+  const migratedDomainV3 = spawnSync(process.execPath, [v3MigrationTool, v2DomainFile, "--kind", "domain-strategy", "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
+  if (migratedDomainV3.status !== 0) throw new Error(`v2 domain strategy should migrate: ${migratedDomainV3.stderr}`);
+  const migratedDomainV3Value = JSON.parse(migratedDomainV3.stdout);
+  if (migratedDomainV3Value.schema_version !== 3 || migratedDomainV3Value.status !== "draft" || migratedDomainV3Value.approval.approval_ref !== "migration-required") throw new Error("domain v2 -> v3 migration must reset approval and status");
+
+  const duplicateRule = join(temporaryRoot, "duplicate-rule.yaml");
+  const duplicateRuleValue = parseYaml(domainSource);
+  duplicateRuleValue.rule_catalog.push(structuredClone(duplicateRuleValue.rule_catalog[0]));
+  await writeFile(duplicateRule, JSON.stringify(duplicateRuleValue, null, 2));
+  expectBlocked(run(validator, duplicateRule, temporaryRoot), /rule_id.*重复|重复.*rule_id/, "duplicate v3 rule id");
+
+  const danglingRule = join(temporaryRoot, "dangling-rule.yaml");
+  const danglingRuleValue = parseYaml(domainSource);
+  danglingRuleValue.scenarios[0].rule_refs = ["rule.missing"];
+  await writeFile(danglingRule, JSON.stringify(danglingRuleValue, null, 2));
+  expectBlocked(run(validator, danglingRule, temporaryRoot), /rule_refs.*未声明|悬空/, "dangling v3 rule ref");
+
+  const missingEvidence = join(temporaryRoot, "missing-rule-evidence.yaml");
+  const missingEvidenceValue = parseYaml(domainSource);
+  missingEvidenceValue.rule_catalog[0].evidence_refs = [];
+  await writeFile(missingEvidence, JSON.stringify(missingEvidenceValue, null, 2));
+  expectBlocked(run(validator, missingEvidence, temporaryRoot), /evidence_refs/, "missing v3 evidence");
 
   const legacyFile = join(temporaryRoot, "legacy-domain.yaml");
-  await writeFile(legacyFile, domainSource.replace("schema_version: 2", "schema_version: 1"));
+  await writeFile(legacyFile, JSON.stringify({ ...v2Domain, schema_version: 1 }, null, 2));
   expectBlocked(run(validator, legacyFile, temporaryRoot), /migration-required/, "legacy domain contract");
 
   const migratableLegacy = join(temporaryRoot, "migratable-legacy-domain.yaml");
-  const migratableLegacySource = domainSource
-    .replace("schema_version: 2", "schema_version: 1")
-    .replace(/context_snapshot:\n[\s\S]*?\ndownstream_mapping:/, "terminology_refs: [CONTEXT.md#Supplier, contexts/ComplianceReview/CONTEXT.md#AdmissionDecision]\ndownstream_mapping:");
+  const migratableLegacyValue = { ...structuredClone(v2Domain), schema_version: 1, terminology_refs: ["CONTEXT.md#Supplier", "contexts/ComplianceReview/CONTEXT.md#AdmissionDecision"] };
+  delete migratableLegacyValue.context_snapshot;
+  const migratableLegacySource = JSON.stringify(migratableLegacyValue, null, 2);
   await writeFile(migratableLegacy, migratableLegacySource);
   const migrated = spawnSync(process.execPath, [migrationTool, migratableLegacy, "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
   if (migrated.status !== 0) throw new Error(`migratable v1 contract should migrate: ${migrated.stderr}`);
@@ -91,7 +168,7 @@ try {
   if (migratedValue.schema_version !== 2 || migratedValue.terminology_refs !== undefined || migratedValue.context_snapshot.context_ref !== "CONTEXT.md" || migratedValue.context_snapshot.term_refs.join(",") !== "ComplianceReview/AdmissionDecision,Global/Supplier") throw new Error("migrated context snapshot is incomplete");
 
   const ambiguousLegacy = join(temporaryRoot, "ambiguous-legacy-domain.yaml");
-  await writeFile(ambiguousLegacy, migratableLegacySource.replace("CONTEXT.md#Supplier, contexts/ComplianceReview/CONTEXT.md#AdmissionDecision", "contexts/ComplianceReview/CONTEXT.md"));
+  await writeFile(ambiguousLegacy, JSON.stringify({ ...migratableLegacyValue, terminology_refs: ["contexts/ComplianceReview/CONTEXT.md"] }, null, 2));
   const ambiguousMigration = spawnSync(process.execPath, [migrationTool, ambiguousLegacy, "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
   expectBlocked(ambiguousMigration, /migration-required.*无法唯一定位|无法唯一定位.*migration-required/, "ambiguous legacy reference");
 
@@ -115,32 +192,48 @@ try {
   await writeFile(unknownContext, domainSource.replace("to_context: ComplianceReview", "to_context: UnknownContext"));
   expectBlocked(run(validator, unknownContext, temporaryRoot), /未引用已声明上下文|未在领域战略中登记/, "unknown context");
 
-  const packageApprovalRef = join(temporaryRoot, "package-approval.json");
   const packageSource = (await readFile(validPackageTemplate, "utf8"))
-    .replace(".agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml", packageApprovalRef)
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest)
     .replace("<domain-strategy-digest>", digestYaml(domainSource));
   const packageFile = join(temporaryRoot, "stage-decision.yaml");
   await writeFile(packageFile, packageSource);
-  const packageDecision = buildDecisionFixture(join(temporaryRoot, "package-decision"), { boundary: "check.stage-decision-package-approved", subjectRef: packageFile });
-  const packageApproval = parseDocument(await readFile(join(testsRoot, "fixtures/stage-decision-approval.yaml"), "utf8")).toJS();
-  await writeFile(packageApprovalRef, JSON.stringify({ ...packageApproval, subject_ref: packageFile, approval_scope: packageDecision.requirement.scope, user_decision_ref: packageDecision.ref }));
   const packagePass = run(packageValidator, packageFile, temporaryRoot);
-  if (packagePass.status !== 0) throw new Error(`valid v2 stage decision package should pass: ${packagePass.stderr}`);
+  if (packagePass.status !== 0) throw new Error(`valid v3 stage decision package should pass: ${packagePass.stderr}`);
+
+  const v2Stage = toV2Stage(packageSource, digestYaml(v2DomainSource));
+  const v2StageFile = join(temporaryRoot, "stage-decision-v2.yaml");
+  await writeFile(v2StageFile, JSON.stringify(v2Stage, null, 2));
+  const v2StagePass = run(packageValidator, v2StageFile, temporaryRoot);
+  if (v2StagePass.status !== 0) throw new Error(`read-only v2 stage decision package should pass: ${v2StagePass.stderr}`);
+
+  const migratedV3 = spawnSync(process.execPath, [v3MigrationTool, v2StageFile, "--kind", "stage-decision", "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
+  if (migratedV3.status !== 0) throw new Error(`v2 stage decision should migrate: ${migratedV3.stderr}`);
+  const migratedV3Value = JSON.parse(migratedV3.stdout);
+  if (migratedV3Value.schema_version !== 3 || migratedV3Value.status !== "draft" || migratedV3Value.approval.approval_ref !== "migration-required") throw new Error("v2 -> v3 migration must reset approval and status");
+
+  const wrongSourceRef = join(temporaryRoot, "stage-decision-wrong-source-ref.yaml");
+  const wrongSourceRefValue = parseYaml(packageSource);
+  wrongSourceRefValue.success_criteria[0].source_refs = ["rule.missing"];
+  await writeFile(wrongSourceRef, JSON.stringify(wrongSourceRefValue, null, 2));
+  expectBlocked(run(packageValidator, wrongSourceRef, temporaryRoot), /source_refs.*未在领域战略中声明|悬空/, "stage decision dangling source ref");
 
   const packageLegacy = join(temporaryRoot, "legacy-stage-decision.yaml");
-  await writeFile(packageLegacy, packageSource.replace("schema_version: 2", "schema_version: 1"));
+  await writeFile(packageLegacy, JSON.stringify({ ...v2Stage, schema_version: 1 }, null, 2));
   expectBlocked(run(packageValidator, packageLegacy, temporaryRoot), /migration-required/, "legacy stage decision contract");
 
   const packageBlocker = join(temporaryRoot, "stage-decision-blocker.yaml");
-  await writeFile(packageBlocker, packageSource.replace("type: deferred", "type: blocker"));
+  const blockerValue = parseYaml(packageSource);
+  blockerValue.unresolved_items[0].type = "blocker";
+  await writeFile(packageBlocker, JSON.stringify(blockerValue, null, 2));
   expectBlocked(run(packageValidator, packageBlocker, temporaryRoot), /blocker/, "blocker package");
 
   const packageWrongArray = join(temporaryRoot, "stage-decision-wrong-array.yaml");
-  await writeFile(packageWrongArray, packageSource.replace("target_users: [采购专员、合规专员]", "target_users: [42]"));
+  const wrongArrayValue = parseYaml(packageSource);
+  wrongArrayValue.target_users = [42];
+  await writeFile(packageWrongArray, JSON.stringify(wrongArrayValue, null, 2));
   expectBlocked(run(packageValidator, packageWrongArray, temporaryRoot), /target_users\[0\]/, "package non-string array item");
 } finally {
   await rm(temporaryRoot, { recursive: true, force: true });
 }
-process.stdout.write("业务边界与规则设计 v2 场景验证通过\n");
+process.stdout.write("业务边界与规则设计 v2/v3 场景验证通过\n");

package/template/.codex/skills/archify/SKILL.md

@@ -16,7 +16,7 @@ Create a self-contained, interactive HTML diagram from a small typed JSON specif
 
 When the current repository contains `yss-project.yaml`, these rules override the upstream update and delivery commands below:
 
-- Treat Archify as a conditional specialist. Use it only when the user or the current YSS contract explicitly requires an architecture, workflow, sequence, data-flow, lifecycle, or Mermaid-beautification artifact. A diagram is derived evidence; it never replaces Spec, ADR, OpenAPI, Tactical Design Contract, Slice Implementation Contract, review, or approval evidence.
+- Treat Archify as a conditional specialist. Use it only when the user or the current YSS contract explicitly requires an architecture, workflow, sequence, data-flow, lifecycle, or Mermaid-beautification artifact. A diagram is derived evidence; it never replaces the active profile's architecture contract (such as backend Tactical Design or Frontend Engineering Design), Spec, ADR, OpenAPI, Slice Implementation Contract, review, or approval evidence.
 - Do not run `scripts/check-update.mjs`. YSS pins the upstream revision in `skills-lock.json`; upgrades happen only through the repository's skill-maintenance workflow.
 - Validate with the upstream `validate` command, but deliver through the repository-safe wrapper from the repository root:
 

package/template/.codex/skills/yss-stage-decision/SKILL.md

@@ -24,13 +24,22 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有；从 `docs/plan/templates/plan-template.md` 汇总输入。旧资产按 `docs/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
 
-1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和父 Ticket/checkpoint。
+1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和当前 profile 的主索引/checkpoint；按 `yss-product-lifecycle` 的 `request-triage` 区分事实确认、产品决定、门禁确认和普通澄清。
 2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务故事、已发生的事实、规则、责任人和失败路径识别业务板块与业务责任区，不从数据库表或调用链直接反推边界。
 4. 为每个业务责任区建立统一业务词汇；对跨责任区协作记录规则提供方、规则使用方、业务决策权、信息传递方向和口径转换负责人。
 5. 记录待确认的关键业务对象，不提前指定技术模型。
-6. 生成 schema v2 `domain_strategy` 和 `stage_decision_package`，使用 `context_snapshot` 绑定根 `CONTEXT.md`、术语身份、完整文档 digest、引用术语 digest、证据和下游影响映射。
-7. 运行 Schema、根路径、术语引用、digest、语义一致性和传播验证；发现关键冲突时返回 `blocked`，不得生成 `approved` 包。v1 字符串引用只读并返回 `migration-required`；可唯一定位的旧锚点用 `scripts/migrate-context-references.mjs` 迁移，歧义引用不得猜测。
+6. 生成 schema v3 `domain_strategy` 和 `stage_decision_package`，使用稳定规则、场景、决定、假设、约束、成功标准、测试 seam 和 downstream mapping ID，并以 `context_snapshot` 绑定根 `CONTEXT.md`、术语身份、完整文档 digest、引用术语 digest和证据。
+7. 运行 Schema、唯一性、悬空引用、根路径、术语引用、digest、语义一致性和传播验证；发现关键冲突时返回 `blocked`，不得生成 `approved` 包。v2 仅只读；修改或重发必须使用 `scripts/migrate-contract-v3.mjs` 显式迁移为 `draft` 并重新批准。v1 字符串引用先用 `scripts/migrate-context-references.mjs` 迁移到 v2；歧义引用不得猜测。
+
+## 控制面引用
+
+- 用户决定遵循 `docs/process/lifecycle/references/user-decisions.md`：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。
+- checkpoint 是唯一机器状态源，业务 Ticket 只保存追踪引用，不复制阶段状态。
+- 每次批准、重发和消费者流转前执行 `context_reconciliation`，核验 `CONTEXT.md` 的全文与引用术语双摘要。
+- 技术事实与第三方行为走 `yss-research` 的 `technical-evidence`；产品策略依据走 `strategy-evidence`；市场与竞品判断走 `competitive-intelligence`。
+- 修改本 Skill 时只编辑 `.agents/skills` 权威副本，再由 `maintaining-skills` 生成投影和 `skills-lock.json`。
+- 本 Skill 只能标记影响、提出待解决问题和选择消费者能力；不得预选后端架构族，不得进入技术设计或实现流程，也不得授权实现。
 
 ## 语义方向规则
 
@@ -56,7 +65,7 @@ Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有
 - 不在业务方案设计阶段生成技术模型、生产代码或 API 契约。
 - 不把模板 Fixture 当作具体项目的业务事实。
 
-详细合同、字段和验证规则见 `references/domain-strategy-contract.md`、`references/stage-decision-package-contract.md` 与 `references/validation-rules.md`。机器可读合同分别为 `references/domain-strategy.schema.json` 和 `references/stage-decision-package.schema.json`；对应验证器为 `scripts/validate-domain-strategy.mjs` 与 `scripts/validate-stage-decision-package.mjs`。
+详细合同、字段和验证规则见 `references/domain-strategy-contract.md`、`references/stage-decision-package-contract.md` 与 `references/validation-rules.md`。当前机器可读合同分别为 `references/domain-strategy-v3.schema.json` 和 `references/stage-decision-package-v3.schema.json`；v2 schema 仅用于历史读取。对应验证器为 `scripts/validate-domain-strategy.mjs` 与 `scripts/validate-stage-decision-package.mjs`。
 
 ## 战略交接快照包