create-yss-spec 2.2.3 → 2.2.5

package/template/.pi/skills/yss-stage-decision/references/domain-strategy-contract.md

@@ -0,0 +1,26 @@
+# DDD 战略设计合同
+
+## 顶层结构
+
+机器可读合同使用 `references/domain-strategy.schema.json`。顶层必须包含：
+
+- `schema_version`、`domain_strategy_id`、`domain_version`、`status`；
+- `contexts`、`subdomains`、`relationships`、`scenarios`；
+- `concept_candidates`、`invariants`、`terminology_refs`；
+- `downstream_mapping`、`evidence_refs`、`approval`。
+
+## 上下文
+
+每个上下文声明 `context_id`、职责边界、非职责、子域分类、模型所有者、关键场景和本地词汇引用。`context_id` 是稳定身份，不得使用代码模块、数据库 schema 或菜单路径替代。
+
+## 关系
+
+关系必须声明 `relationship_pattern`、`semantic_upstream`、`semantic_downstream`、`business_authority`、`model_change_impact`、`transport_direction` 和 `translation_responsibility`。语义方向与技术方向可以不同；关系模式只能使用合同中列出的 DDD 模式。
+
+## 核心概念
+
+使用 `domain_concept_candidate` 表达战略阶段的核心概念候选，记录身份特征、生命周期、不变量引用、可能的战术角色和置信度。不得在该合同中把概念直接批准为 Entity 或 Aggregate Root。
+
+## 阶段决策包
+
+阶段包应通过 `domain_strategy_ref` 引用 DDD 合同的当前版本和 digest，并使用 `domain_to_downstream_mapping` 描述领域变化对 Spec、设计、API、数据、Ticket 和测试 seam 的传播。

package/template/.pi/skills/yss-stage-decision/references/domain-strategy.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/domain-strategy-v1.json",
+  "title": "YSS DDD Strategic Design",
+  "type": "object",
+  "required": ["schema_version", "domain_strategy_id", "domain_version", "status", "contexts", "subdomains", "relationships", "scenarios", "concept_candidates", "invariants", "terminology_refs", "downstream_mapping", "evidence_refs", "approval"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "domain_strategy_id": {"type": "string", "pattern": "^domain-strategy\\.[a-z0-9][a-z0-9-]*$"},
+    "domain_version": {"type": "string", "pattern": "^v[0-9]+$"},
+    "status": {"enum": ["draft", "ready-for-human", "approved", "stale", "blocked"]},
+    "contexts": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/context"}},
+    "subdomains": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/subdomain"}},
+    "relationships": {"type": "array", "items": {"$ref": "#/$defs/relationship"}},
+    "scenarios": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/scenario"}},
+    "concept_candidates": {"type": "array", "items": {"$ref": "#/$defs/concept"}},
+    "invariants": {"type": "array", "items": {"$ref": "#/$defs/invariant"}},
+    "terminology_refs": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "downstream_mapping": {"type": "array", "items": {"$ref": "#/$defs/mapping"}},
+    "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "approval": {"$ref": "#/$defs/approval"}
+  },
+  "$defs": {
+    "context": {
+      "type": "object",
+      "required": ["context_id", "name", "responsibilities", "non_responsibilities", "subdomain_type", "owner", "status"],
+      "properties": {
+        "context_id": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "name": {"type": "string", "minLength": 1},
+        "responsibilities": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+        "non_responsibilities": {"type": "array", "items": {"type": "string", "minLength": 1}},
+        "subdomain_type": {"enum": ["Core Domain", "Supporting Subdomain", "Generic Subdomain"]},
+        "owner": {"type": "string", "minLength": 1},
+        "status": {"enum": ["candidate", "confirmed", "stale"]}
+      }
+    },
+    "subdomain": {
+      "type": "object",
+      "required": ["subdomain_id", "name", "type", "rationale", "evidence_refs"],
+      "properties": {
+        "subdomain_id": {"type": "string", "pattern": "^subdomain\\.[a-z0-9][a-z0-9-]*$"},
+        "name": {"type": "string", "minLength": 1},
+        "type": {"enum": ["Core Domain", "Supporting Subdomain", "Generic Subdomain"]},
+        "rationale": {"type": "string", "minLength": 1},
+        "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+      }
+    },
+    "relationship": {
+      "type": "object",
+      "required": ["relationship_id", "from_context", "to_context", "relationship_pattern", "semantic_upstream", "semantic_downstream", "business_authority", "model_change_impact", "transport_direction", "translation_responsibility", "direction_explanation"],
+      "properties": {
+        "relationship_id": {"type": "string", "pattern": "^relationship\\.[a-z0-9][a-z0-9-]*$"},
+        "from_context": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "to_context": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "relationship_pattern": {"enum": ["Partnership", "Customer/Supplier", "Conformist", "Anti-Corruption Layer", "Open Host Service", "Published Language", "Shared Kernel", "Separate Ways"]},
+        "semantic_upstream": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "semantic_downstream": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "business_authority": {"type": "string", "minLength": 1},
+        "model_change_impact": {"type": "string", "minLength": 1},
+        "transport_direction": {"type": "string", "minLength": 1},
+        "translation_responsibility": {"type": "string", "minLength": 1},
+        "direction_explanation": {"type": "string", "minLength": 1}
+      }
+    },
+    "scenario": {
+      "type": "object",
+      "required": ["scenario_id", "actor", "preconditions", "commands", "rules", "events", "failure_results", "responsible_context", "consumers", "status"],
+      "properties": {
+        "scenario_id": {"type": "string", "pattern": "^scenario\\.[a-z0-9][a-z0-9-]*$"},
+        "actor": {"type": "string", "minLength": 1},
+        "preconditions": {"type": "array", "items": {"type": "string"}},
+        "commands": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "rules": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "events": {"type": "array", "items": {"type": "string"}},
+        "failure_results": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "responsible_context": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "consumers": {"type": "array", "items": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"}},
+        "status": {"enum": ["candidate", "confirmed", "stale"]}
+      }
+    },
+    "concept": {
+      "type": "object",
+      "required": ["concept_id", "name", "context_id", "identity_features", "lifecycle", "confidence", "status"],
+      "properties": {
+        "concept_id": {"type": "string", "pattern": "^domain-concept\\.[a-z0-9][a-z0-9-]*$"},
+        "name": {"type": "string", "minLength": 1},
+        "context_id": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "identity_features": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "lifecycle": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "invariant_refs": {"type": "array", "items": {"type": "string"}},
+        "possible_tactical_role": {"type": "string"},
+        "confidence": {"enum": ["low", "medium", "high"]},
+        "status": {"enum": ["candidate", "confirmed", "stale"]}
+      }
+    },
+    "invariant": {
+      "type": "object",
+      "required": ["invariant_id", "statement", "responsible_context", "scenario_refs", "verification_method"],
+      "properties": {
+        "invariant_id": {"type": "string", "pattern": "^invariant\\.[a-z0-9][a-z0-9-]*$"},
+        "statement": {"type": "string", "minLength": 1},
+        "responsible_context": {"type": "string", "pattern": "^[A-Z][A-Za-z0-9]+$"},
+        "scenario_refs": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "verification_method": {"type": "string", "minLength": 1}
+      }
+    },
+    "mapping": {
+      "type": "object",
+      "required": ["domain_change", "impacts", "propagation", "reapproval_condition"],
+      "properties": {
+        "domain_change": {"type": "string", "minLength": 1},
+        "impacts": {"type": "array", "minItems": 1, "items": {"type": "string"}},
+        "propagation": {"enum": ["direct", "transitive", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1}
+      }
+    },
+    "approval": {
+      "type": "object",
+      "required": ["approval_ref", "approver", "persisted_ref", "current_version"],
+      "properties": {
+        "approval_ref": {"type": "string", "minLength": 1},
+        "approver": {"type": "string", "minLength": 1},
+        "persisted_ref": {"type": "string", "minLength": 1},
+        "current_version": {"type": "string", "pattern": "^v[0-9]+$"}
+      }
+    }
+  }
+}

package/template/.pi/skills/yss-stage-decision/references/stage-decision-package-contract.md

@@ -0,0 +1,19 @@
+# 阶段决策包合同
+
+`stage_decision_package` 是 Discovery、需求/产品/商务决策与 DDD 战略设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制领域模型事实。
+
+## 必须包含
+
+- 问题陈述、目标用户、MVP、非目标、成功标准和可执行的测试 seam；
+- 已确认决策、假设、约束和未决项；
+- `domain_strategy_ref`：领域战略合同的稳定 ID、版本、digest 和批准状态；
+- UI/API/Data/Backend/Frontend/跨仓/高风险影响面布尔值；
+- 每个下游消费者的传播方式、重新批准条件、证据引用和批准记录。`approval.approval_ref` 必须指向可读取且通过 `scripts/verify-approval-record` 的 `gate.stage-decision-package-approved` 会签记录；`approval.approver` 必须与记录中的 `role_id` 一致。
+
+## 未决项规则
+
+`blocker` 必须阻断批准；`deferred` 必须同时记录责任人、下一动作和目标版本/发布日期。没有责任人或恢复路径的未决项不得隐藏在备注中。
+
+## 下游消费规则
+
+只有 `approved` 且引用的领域战略为 `approved`、版本当前的阶段包，才可以进入 Spec synthesis。任何领域战略 digest、版本或影响面变化都使阶段包 `stale`，并要求重新评估。

package/template/.pi/skills/yss-stage-decision/references/stage-decision-package.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/stage-decision-package-v1.json",
+  "title": "YSS Stage Decision Package",
+  "type": "object",
+  "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", "terminology_refs", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "stage_decision_id": {"type": "string", "pattern": "^stage-decision\\.[a-z0-9][a-z0-9-]*$"},
+    "package_version": {"type": "string", "pattern": "^v[0-9]+$"},
+    "status": {"enum": ["draft", "ready-for-human", "approved", "stale", "blocked"]},
+    "problem_statement": {"type": "string", "minLength": 1},
+    "target_users": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "mvp": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "success_criteria": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "test_seams": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "confirmed_decisions": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "assumptions": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "constraints": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "unresolved_items": {"type": "array", "items": {"$ref": "#/$defs/unresolved"}},
+    "terminology_refs": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "domain_strategy_ref": {"$ref": "#/$defs/domainRef"},
+    "impact_assessment": {"$ref": "#/$defs/impact"},
+    "downstream_mapping": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/mapping"}},
+    "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+    "approval": {"$ref": "#/$defs/approval"}
+  },
+  "$defs": {
+    "unresolved": {
+      "type": "object",
+      "required": ["item", "type", "owner", "next_action", "target_version"],
+      "properties": {
+        "item": {"type": "string", "minLength": 1},
+        "type": {"enum": ["blocker", "deferred"]},
+        "owner": {"type": "string", "minLength": 1},
+        "next_action": {"type": "string", "minLength": 1},
+        "target_version": {"type": "string", "minLength": 1}
+      }
+    },
+    "domainRef": {
+      "type": "object",
+      "required": ["domain_strategy_id", "domain_version", "digest", "status", "persisted_ref"],
+      "properties": {
+        "domain_strategy_id": {"type": "string", "pattern": "^domain-strategy\\.[a-z0-9][a-z0-9-]*$"},
+        "domain_version": {"type": "string", "pattern": "^v[0-9]+$"},
+        "digest": {"type": "string", "minLength": 1},
+        "status": {"enum": ["approved", "stale", "blocked"]},
+        "persisted_ref": {"type": "string", "minLength": 1}
+      }
+    },
+    "impact": {
+      "type": "object",
+      "required": ["ui", "api", "data", "backend", "frontend", "cross_repo", "high_risk"],
+      "properties": {
+        "ui": {"type": "boolean"},
+        "api": {"type": "boolean"},
+        "data": {"type": "boolean"},
+        "backend": {"type": "boolean"},
+        "frontend": {"type": "boolean"},
+        "cross_repo": {"type": "boolean"},
+        "high_risk": {"type": "boolean"}
+      }
+    },
+    "mapping": {
+      "type": "object",
+      "required": ["domain_change", "consumer", "propagation", "reapproval_condition"],
+      "properties": {
+        "domain_change": {"type": "string", "minLength": 1},
+        "consumer": {"type": "string", "minLength": 1},
+        "propagation": {"enum": ["direct", "transitive", "not-applicable", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1}
+      }
+    },
+    "approval": {
+      "type": "object",
+      "required": ["approval_ref", "approver", "persisted_ref", "current_version"],
+      "properties": {
+        "approval_ref": {"type": "string", "minLength": 1},
+        "approver": {"type": "string", "minLength": 1},
+        "persisted_ref": {"type": "string", "minLength": 1},
+        "current_version": {"type": "string", "pattern": "^v[0-9]+$"}
+      }
+    }
+  }
+}

package/template/.pi/skills/yss-stage-decision/references/validation-rules.md

@@ -0,0 +1,18 @@
+# 验证规则
+
+验证分为结构、引用和语义三层：
+
+1. **结构**：Schema 版本、稳定 ID、状态枚举、必填字段、条件字段和证据格式。
+2. **引用**：上下文端点、场景、不变量、术语和下游资产引用必须可解析。
+3. **语义**：禁止关系自环、未知上下文、未批准 Shared Kernel、未解释的语义/技术方向差异、职责重叠、无责任人的不变量和跨上下文直接共享实体。
+
+以下情况必须 `blocked`：关键规则所有权未知、关键术语冲突、上下文边界未定、关键失败场景缺失、事件语义无法解释、领域专家确认缺失。
+
+以下变化应触发精确传播：
+
+- 术语含义变化 → Spec、验收、原型或 API；
+- 上下文边界变化 → 系统架构、OpenAPI、数据和切片；
+- Context Map 关系变化 → 集成契约和模型翻译；
+- 不变量变化 → 测试 seam、实现合同和验证策略。
+
+验证器允许“语义方向 ≠ 技术方向”，但要求 `direction_explanation` 和翻译责任非空。

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

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecordFile } from "../../../../scripts/lib/approval-record.mjs";
+
+const required = ["schema_version", "domain_strategy_id", "domain_version", "status", "contexts", "subdomains", "relationships", "scenarios", "concept_candidates", "invariants", "terminology_refs", "downstream_mapping", "evidence_refs", "approval"];
+const idPatterns = {
+  context_id: /^[A-Z][A-Za-z0-9]+$/,
+  domain_strategy_id: /^domain-strategy\.[a-z0-9][a-z0-9-]*$/,
+  subdomain_id: /^subdomain\.[a-z0-9][a-z0-9-]*$/,
+  relationship_id: /^relationship\.[a-z0-9][a-z0-9-]*$/,
+  scenario_id: /^scenario\.[a-z0-9][a-z0-9-]*$/,
+  concept_id: /^domain-concept\.[a-z0-9][a-z0-9-]*$/,
+  invariant_id: /^invariant\.[a-z0-9][a-z0-9-]*$/
+};
+const relationshipPatterns = new Set(["Partnership", "Customer/Supplier", "Conformist", "Anti-Corruption Layer", "Open Host Service", "Published Language", "Shared Kernel", "Separate Ways"]);
+
+function fail(errors) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", errors }, null, 2)}\n`);
+  process.exitCode = 1;
+}
+
+function nonEmpty(value) { return typeof value === "string" && value.trim().length > 0; }
+function list(value) { return Array.isArray(value); }
+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 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, itemKind = "string") {
+  requireField(object, field, path, errors);
+  if (field in object && (!list(object[field]) || object[field].length < min)) errors.push(`${path}.${field} 必须是至少 ${min} 项的数组`);
+  if (field in object && list(object[field]) && itemKind === "string") object[field].forEach((item, index) => { if (!nonEmpty(item)) errors.push(`${path}.${field}[${index}] 必须是非空字符串`); });
+}
+
+function validate(data) {
+  const errors = [];
+  if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
+  for (const field of required) requireField(data, field, "root", errors);
+  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
+  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 非法");
+
+  requireArray(data, "contexts", "root", errors, 1, "object");
+  const contexts = list(data.contexts) ? data.contexts : [];
+  const contextIds = contexts.map((item) => item?.context_id).filter(Boolean);
+  unique(contextIds, "context_id", errors);
+  for (const [index, context] of contexts.entries()) {
+    const path = `contexts[${index}]`;
+    for (const field of ["context_id", "name", "owner", "status", "subdomain_type"]) requireString(context ?? {}, field, path, errors);
+    for (const field of ["responsibilities", "non_responsibilities"]) requireArray(context ?? {}, field, path, errors, field === "responsibilities" ? 1 : 0);
+    if (context?.context_id && !idPatterns.context_id.test(context.context_id)) errors.push(`${path}.context_id 格式非法`);
+    if (context?.status && !["candidate", "confirmed", "stale"].includes(context.status)) errors.push(`${path}.status 非法`);
+    if (context?.subdomain_type && !["Core Domain", "Supporting Subdomain", "Generic Subdomain"].includes(context.subdomain_type)) errors.push(`${path}.subdomain_type 非法`);
+  }
+
+  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);
+  for (const [index, item] of subdomains.entries()) {
+    const path = `subdomains[${index}]`;
+    for (const field of ["subdomain_id", "name", "type", "rationale"]) requireString(item ?? {}, field, path, errors);
+    requireArray(item ?? {}, "evidence_refs", path, errors, 1);
+    if (item?.subdomain_id && !idPatterns.subdomain_id.test(item.subdomain_id)) errors.push(`${path}.subdomain_id 格式非法`);
+    if (item?.type && !["Core Domain", "Supporting Subdomain", "Generic Subdomain"].includes(item.type)) errors.push(`${path}.type 非法`);
+  }
+
+  const relationships = list(data.relationships) ? data.relationships : [];
+  unique(relationships.map((item) => item?.relationship_id).filter(Boolean), "relationship_id", errors);
+  for (const [index, relationship] of relationships.entries()) {
+    const path = `relationships[${index}]`;
+    for (const field of ["relationship_id", "from_context", "to_context", "relationship_pattern", "semantic_upstream", "semantic_downstream", "business_authority", "model_change_impact", "transport_direction", "translation_responsibility", "direction_explanation"]) requireString(relationship ?? {}, field, path, errors);
+    if (relationship?.relationship_id && !idPatterns.relationship_id.test(relationship.relationship_id)) errors.push(`${path}.relationship_id 格式非法`);
+    for (const field of ["from_context", "to_context", "semantic_upstream", "semantic_downstream"]) {
+      if (relationship?.[field] && !contextIds.includes(relationship[field])) errors.push(`${path}.${field} 未引用已声明上下文`);
+    }
+    if (relationship?.from_context === relationship?.to_context) errors.push(`${path} 不允许上下文自环`);
+    if (relationship?.semantic_upstream && ![relationship.from_context, relationship.to_context].includes(relationship.semantic_upstream)) errors.push(`${path}.semantic_upstream 必须是关系端点`);
+    if (relationship?.semantic_downstream && ![relationship.from_context, relationship.to_context].includes(relationship.semantic_downstream)) errors.push(`${path}.semantic_downstream 必须是关系端点`);
+    if (relationship?.relationship_pattern && !relationshipPatterns.has(relationship.relationship_pattern)) errors.push(`${path}.relationship_pattern 非法`);
+    if (relationship?.relationship_pattern === "Shared Kernel" && !nonEmpty(relationship.shared_kernel_approval_ref)) errors.push(`${path} Shared Kernel 必须有 shared_kernel_approval_ref`);
+    if (relationship?.semantic_upstream && relationship?.semantic_downstream && relationship.semantic_upstream === relationship.semantic_downstream) errors.push(`${path} semantic_upstream 与 semantic_downstream 不能相同`);
+  }
+
+  requireArray(data, "scenarios", "root", errors, 1, "object");
+  const scenarios = list(data.scenarios) ? data.scenarios : [];
+  const scenarioIds = scenarios.map((item) => item?.scenario_id).filter(Boolean);
+  unique(scenarioIds, "scenario_id", errors);
+  for (const [index, scenario] of scenarios.entries()) {
+    const path = `scenarios[${index}]`;
+    for (const field of ["scenario_id", "actor", "responsible_context", "status"]) requireString(scenario ?? {}, field, path, errors);
+    for (const field of ["preconditions", "commands", "rules", "events", "failure_results", "consumers"]) requireArray(scenario ?? {}, field, path, errors, field === "commands" || field === "rules" || field === "failure_results" ? 1 : 0);
+    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}`);
+  }
+
+  const concepts = list(data.concept_candidates) ? data.concept_candidates : [];
+  unique(concepts.map((item) => item?.concept_id).filter(Boolean), "concept_id", errors);
+  for (const [index, concept] of concepts.entries()) {
+    const path = `concept_candidates[${index}]`;
+    for (const field of ["concept_id", "name", "context_id", "confidence", "status"]) requireString(concept ?? {}, field, path, errors);
+    for (const field of ["identity_features", "lifecycle"]) requireArray(concept ?? {}, field, path, errors, 1);
+    if (concept?.concept_id && !idPatterns.concept_id.test(concept.concept_id)) errors.push(`${path}.concept_id 格式非法`);
+    if (concept?.context_id && !contextIds.includes(concept.context_id)) errors.push(`${path}.context_id 未声明`);
+    if (concept?.confidence && !["low", "medium", "high"].includes(concept.confidence)) errors.push(`${path}.confidence 非法`);
+  }
+
+  const invariants = list(data.invariants) ? data.invariants : [];
+  unique(invariants.map((item) => item?.invariant_id).filter(Boolean), "invariant_id", errors);
+  for (const [index, invariant] of invariants.entries()) {
+    const path = `invariants[${index}]`;
+    for (const field of ["invariant_id", "statement", "responsible_context", "verification_method"]) requireString(invariant ?? {}, field, path, errors);
+    requireArray(invariant ?? {}, "scenario_refs", path, errors, 1);
+    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}`);
+  }
+
+  requireArray(data, "terminology_refs", "root", errors, 0);
+  requireArray(data, "evidence_refs", "root", errors, 1);
+  const mappings = list(data.downstream_mapping) ? data.downstream_mapping : [];
+  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 非法`);
+  }
+  const approval = data.approval ?? {};
+  for (const field of ["approval_ref", "approver", "persisted_ref", "current_version"]) requireString(approval, field, "approval", errors);
+  if (data.status === "approved") {
+    if (contexts.some((context) => context.status !== "confirmed")) errors.push("approved 合同要求所有上下文 status=confirmed");
+    if (approval.current_version !== data.domain_version) errors.push("approval.current_version 必须等于 domain_version");
+    try {
+      const approvalPath = resolveApprovalRef(approval.approval_ref);
+      validateApprovalRecordFile(approvalPath, { requireApproved: true });
+      const record = loadApprovalRecord(approvalPath);
+      if (record.gate_id !== "gate.domain-strategy-approved") errors.push("approval.approval_ref 的 gate_id 必须为 gate.domain-strategy-approved");
+      if (record.role_id !== approval.approver) errors.push("approval.approver 必须与会签记录 role_id 一致");
+    } catch (error) { errors.push(`approval.approval_ref 会签记录无效: ${error.message}`); }
+  }
+  return errors;
+}
+
+const file = process.argv[2];
+if (!file) fail(["用法: validate-domain-strategy.mjs <contract.yaml>"]);
+else {
+  try {
+    const source = await readFile(file, "utf8");
+    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length) fail([document.errors[0].message]);
+    else {
+      const errors = validate(document.toJS({ maxAliasCount: 0 }));
+      if (errors.length) fail(errors);
+      else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
+    }
+  } catch (error) { fail([error.message]); }
+}

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import process from "node:process";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecordFile } from "../../../../scripts/lib/approval-record.mjs";
+
+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", "terminology_refs", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"];
+const idPattern = /^stage-decision\.[a-z0-9][a-z0-9-]*$/;
+
+function fail(errors) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", errors }, null, 2)}\n`);
+  process.exitCode = 1;
+}
+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 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")}`; }
+
+async function validate(data) {
+  const errors = [];
+  if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
+  for (const field of required) requireField(data, field, "root", errors);
+  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
+  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", "terminology_refs", "evidence_refs"]) requireArray(data, field, "root", errors, ["target_users", "mvp", "success_criteria", "test_seams", "confirmed_decisions", "evidence_refs"].includes(field) ? 1 : 0);
+
+  const unresolved = Array.isArray(data.unresolved_items) ? data.unresolved_items : [];
+  for (const [index, item] of unresolved.entries()) {
+    const path = `unresolved_items[${index}]`;
+    for (const field of ["item", "type", "owner", "next_action", "target_version"]) requireString(item ?? {}, field, path, errors);
+    if (item?.type && !["blocker", "deferred"].includes(item.type)) errors.push(`${path}.type 非法`);
+  }
+  const domainRef = data.domain_strategy_ref ?? {};
+  for (const field of ["domain_strategy_id", "domain_version", "digest", "status", "persisted_ref"]) requireString(domainRef, field, "domain_strategy_ref", errors);
+  if (domainRef.status && !["approved", "stale", "blocked"].includes(domainRef.status)) errors.push("domain_strategy_ref.status 非法");
+  if (data.status === "approved" && domainRef.status !== "approved") errors.push("approved 阶段包必须引用 approved 的 domain strategy");
+  if (nonEmpty(domainRef.persisted_ref)) {
+    try {
+      const strategySource = await readFile(resolve(process.cwd(), domainRef.persisted_ref), "utf8");
+      const strategyDocument = parseDocument(strategySource, { maxAliasCount: 0, uniqueKeys: true });
+      if (strategyDocument.errors.length) errors.push(`domain_strategy_ref.persisted_ref YAML 非法: ${strategyDocument.errors[0].message}`);
+      else {
+        const strategy = strategyDocument.toJS({ maxAliasCount: 0 });
+        if (strategy.domain_strategy_id !== domainRef.domain_strategy_id) errors.push("domain_strategy_ref.domain_strategy_id 与实际文件不一致");
+        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 与实际领域战略内容不一致");
+      }
+    } catch (error) { errors.push(`domain_strategy_ref.persisted_ref 无法读取: ${error.message}`); }
+  }
+
+  const impact = data.impact_assessment ?? {};
+  for (const field of ["ui", "api", "data", "backend", "frontend", "cross_repo", "high_risk"]) {
+    requireField(impact, field, "impact_assessment", errors);
+    if (field in impact && typeof impact[field] !== "boolean") errors.push(`impact_assessment.${field} 必须是 boolean`);
+  }
+  const mappings = Array.isArray(data.downstream_mapping) ? data.downstream_mapping : [];
+  if (mappings.length < 1) errors.push("downstream_mapping 至少需要一项");
+  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 (mapping?.propagation && !["direct", "transitive", "not-applicable", "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);
+  if (data.status === "approved" && approval.current_version !== data.package_version) errors.push("approval.current_version 必须等于 package_version");
+  if (unresolved.some((item) => item?.type === "blocker") && data.status === "approved") errors.push("存在 blocker 未决项时不得 approved");
+  if (data.status === "approved" && nonEmpty(approval.approval_ref)) {
+    try {
+      const approvalPath = resolveApprovalRef(approval.approval_ref);
+      validateApprovalRecordFile(approvalPath, { requireApproved: true });
+      const record = loadApprovalRecord(approvalPath);
+      if (record.gate_id !== "gate.stage-decision-package-approved") errors.push("approval_ref 的 gate_id 必须为 gate.stage-decision-package-approved");
+      if (record.role_id !== approval.approver) errors.push("approval.approver 必须与会签记录 role_id 一致");
+    } catch (error) { errors.push(`approval_ref 会签记录无效: ${error.message}`); }
+  }
+  return errors;
+}
+
+const file = process.argv[2];
+if (!file) fail(["用法: validate-stage-decision-package.mjs <package.yaml>"]);
+else {
+  try {
+    const source = await readFile(file, "utf8");
+    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+    if (document.errors.length) fail([document.errors[0].message]);
+    else {
+      const errors = await validate(document.toJS({ maxAliasCount: 0 }));
+      if (errors.length) fail(errors);
+      else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
+    }
+  } catch (error) { fail([error.message]); }
+}

package/template/.pi/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+gate_id: gate.domain-strategy-approved
+decision: approved
+actor_kind: digital-human
+role_id: role.product-manager
+runtime_id: runtime.generic
+runtime_instance_ref: "runtime.generic:role.product-manager"
+principal_ref: "instance:role.product-manager"
+drafter_role_id: role.requirements-manager
+countersigner_role_ids:
+  - role.product-manager
+evidence_refs:
+  - evidence.domain-strategy-review.supplier
+biological_veto: false
+notes: DDD 战略设计由需求经理起草，产品经理独立会签。