create-yss-spec 2.2.3 → 2.2.4

package/template/.cursor/skills/yss-router/references/slice-implementation-contract.md

@@ -25,6 +25,7 @@ slice_contract:
     architecture_review:
     data_architecture:
     engineering_baseline:
+    tactical_design:
     build_architecture_checklist:
     implementation_repository:
     frontend_repository:
@@ -70,6 +71,24 @@ slice_contract:
     application_boundary:
     transaction_boundary:
     persistence_strategy:
+    tactical_design_ref:
+    tactical_design_version:
+    aggregate_refs: []
+    invariant_refs: []
+    state_behavior_refs: []
+    gateway_boundary_ref:
+    domain_test_seams: []
+    application_test_seams: []
+    tactical_ddd:
+      status: not-applicable
+      tactical_design_ref:
+      tactical_design_version:
+      aggregate_refs: []
+      invariant_refs: []
+      state_behavior_refs: []
+      gateway_boundary_ref:
+      domain_test_seams: []
+      application_test_seams: []
     allowed_write_paths: []
     forbidden_patterns: []
     expected_evidence_files: []
@@ -87,7 +106,43 @@ slice_contract:
     delivery_order: []
     integration_verification: []
     rollback_order: []
-  work_units: []
+  work_units:
+    - id: slice-frontend
+      role_id: role.frontend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id: # must equal slice_contract.contract_id
+      contract_version: # must equal slice_contract.contract_version
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
+    - id: slice-backend
+      role_id: role.backend-engineer
+      runtime_id: runtime.skill-projection
+      execution_state: Worker
+      workflow_status: not-started
+      task_package_ref:
+      contract_id:
+      contract_version:
+      downstream_consumers: []
+      convergence_ref:
+      work_unit:
+        behavior:
+        primary_skill:
+        supporting_skills: []
+        tdd_mode: behavior-tdd
+        allowed_write_paths: []
+        expected_evidence: []
+        verification_commands: []
 ```
 
 工作单元：
@@ -112,3 +167,5 @@ work_unit:
 ```
 
 `controlled_generation` 仅在 `tdd_mode: controlled-generation` 时必填；其他模式标记 `not-applicable`。明确写入需求的权限业务行为仍使用 `behavior-tdd`；API schema 与 database schema 分别触发契约或数据架构回退，不得用一个含糊的 schema 类型决定路线。
+
+`work_units` 中的前端、后端和测试任务是切片级子任务，不是新的生命周期阶段。每个子任务必须引用独立任务包；任务包只能消费同一份已批准且版本当前的 Slice Contract。`workflow_status` 追踪执行过程，不能替代生命周期状态；`contract_id` 或 `contract_version` 不一致时必须阻断并回到 Router。

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

@@ -0,0 +1,50 @@
+---
+name: yss-stage-decision
+description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计；当需求、领域边界、统一语言或下游影响尚未稳定时使用。
+---
+
+# YSS Stage Decision
+
+`yss-stage-decision` 是由 `yss-product-lifecycle` 调度的上游决策技能空间，负责把需求、产品、商务输入和 DDD 战略设计结果整理成可审查、可版本化、可被下游消费的阶段决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
+
+## 适用边界
+
+- 适用于 `project-instance` 的 Discovery → Spec 入口。
+- `template-source` 只维护本技能、Schema、验证器和合成 Fixture，不生成具体产品领域资产。
+- DDD 工作单元只做子域、限界上下文、Context Map、统一语言、关键场景、事件、核心领域概念候选和业务不变量。
+- Entity、Aggregate、Repository、Java 类、数据库表和 OpenAPI Freeze 留给下游工作单元。
+
+## 执行顺序
+
+1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
+2. 分离事实、决策、假设、约束和未决项；技术事实走 `research`，市场/竞品事实走 `competitive-intelligence`。
+3. 从业务场景、事件、规则、责任人和失败路径识别子域及限界上下文，不从数据库表或调用链直接反推边界。
+4. 为每个上下文建立本地统一语言；为跨上下文关系记录语义上游/下游、业务决策权、技术传输方向和翻译责任。
+5. 记录核心领域概念候选，不提前锁定 Entity 或 Aggregate。
+6. 生成 `domain_strategy` 和 `stage_decision_package`，绑定版本、digest、证据和下游影响映射。
+7. 运行 Schema、引用、语义一致性和传播验证；发现关键冲突时返回 `blocked`，不得生成 `approved` 包。
+
+## 语义方向规则
+
+`semantic_upstream` 是拥有业务规则、决策语义或权威模型的一方；`semantic_downstream` 是消费、适配或依赖该语义的一方。二者不等于 HTTP、事件或数据库的技术方向。每条 Context Map 关系必须独立记录 `transport_direction` 和 `translation_responsibility`；同一对上下文可以存在多条相反方向的语义边。
+
+## 产物与批准
+
+- DDD 资产是事实源，阶段决策包只通过 `domain_strategy_ref` 引用它们。
+- `stage_decision_package` 必须经过 `draft → ready-for-human → approved`；起草者不得自签。
+- 建议门禁为 `gate.domain-strategy-approved` 和 `gate.stage-decision-package-approved`，实际状态由 `yss-product-lifecycle` 维护；阶段包批准引用必须通过 `scripts/verify-approval-record`，不得用不可读路径或聊天确认替代。
+- 下游只能消费批准且版本当前的包；发现语义冲突返回 `drift` / `new_impacts`，不得静默修改上游。
+
+## 结果合同
+
+返回标准 `Workflow Execution Result`，至少包含 `work_unit`、`workflow_reference`、`result`、`evidence_refs`、`changed_artifacts`、`new_impacts`、`stale_candidates`、`next_route` 和 `blocking_signals`。`blocked` 必须包含冲突、责任人、恢复条件和下一工作单元。
+
+## 禁止事项
+
+- 不把阶段包当作第二套领域事实源。
+- 不按数据库、微服务、菜单或 HTTP 调用方向自动划分上下文。
+- 不把同名术语强行合并为全局概念。
+- 不在战略设计阶段生成 Entity、Aggregate、Repository、生产代码或 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`。

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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]); }
+}