create-yss-spec 3.0.1 → 3.1.3

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

@@ -1,36 +1,36 @@
 ---
 name: yss-stage-decision
-description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计；当需求、领域边界、统一语言或下游影响尚未稳定时使用。
+description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
 ---
 
 # YSS Stage Decision
 
-`yss-stage-decision` 是由 `yss-product-lifecycle` 调度的上游决策技能空间，负责把需求、产品、商务输入和 DDD 战略设计结果整理成可审查、可版本化、可被下游消费的阶段决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
+`yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、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. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
-3. 从业务场景、事件、规则、责任人和失败路径识别子域及限界上下文，不从数据库表或调用链直接反推边界。
-4. 为每个上下文建立本地统一语言；为跨上下文关系记录语义上游/下游、业务决策权、技术传输方向和翻译责任。
-5. 记录核心领域概念候选，不提前锁定 Entity 或 Aggregate。
-6. 生成 `domain_strategy` 和 `stage_decision_package`，绑定版本、digest、证据和下游影响映射。
-7. 运行 Schema、引用、语义一致性和传播验证；发现关键冲突时返回 `blocked`，不得生成 `approved` 包。
+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` 迁移，歧义引用不得猜测。
 
 ## 语义方向规则
 
-`semantic_upstream` 是拥有业务规则、决策语义或权威模型的一方；`semantic_downstream` 是消费、适配或依赖该语义的一方。二者不等于 HTTP、事件或数据库的技术方向。每条 Context Map 关系必须独立记录 `transport_direction` 和 `translation_responsibility`；同一对上下文可以存在多条相反方向的语义边。
+内部字段 `semantic_upstream` 表示规则提供方，`semantic_downstream` 表示规则使用方。二者不等于 HTTP、消息或数据库的技术方向。每条协作关系必须独立记录 `transport_direction` 和 `translation_responsibility`；同一对业务责任区可以存在多条相反方向的信息关系。
 
 ## 产物与批准
 
-- DDD 资产是事实源，阶段决策包只通过 `domain_strategy_ref` 引用它们。
+- 业务边界与规则设计是本类事实的权威资产，方案决策包只通过内部字段 `domain_strategy_ref` 引用它。两个合同的 `context_snapshot.context_ref` 必须精确为仓库根 `CONTEXT.md`，禁止子目录、`CONTEXT-MAP.md`、绝对路径和 Markdown 伪锚点。
 - 进入 `gate.domain-strategy-approved` 或 `gate.stage-decision-package-approved` 的外部决策证据必须引用通过校验的 `yss-research` `evidence-audited` 研究包；研究包只提供证据，不得直接修改本技能资产或批准门禁。
 - `stage_decision_package` 必须经过 `draft → ready-for-human → approved`；起草者不得自签。
 - 建议门禁为 `gate.domain-strategy-approved` 和 `gate.stage-decision-package-approved`，实际状态由 `yss-product-lifecycle` 维护；阶段包批准引用必须通过 `scripts/verify-approval-record`，不得用不可读路径或聊天确认替代。
@@ -42,10 +42,14 @@ description: 编排 Discovery 到 Spec 入口的阶段决策与 DDD 战略设计
 
 ## 禁止事项
 
-- 不把阶段包当作第二套领域事实源。
+- 不把方案决策包当作第二套业务事实源。
 - 不按数据库、微服务、菜单或 HTTP 调用方向自动划分上下文。
 - 不把同名术语强行合并为全局概念。
-- 不在战略设计阶段生成 Entity、Aggregate、Repository、生产代码或 API 契约。
+- 不在业务方案设计阶段生成技术模型、生产代码或 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`。
+
+## 战略交接快照包
+
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。

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

@@ -1,26 +1,32 @@
-# DDD 战略设计合同
+# 业务边界与规则设计合同
 
 ## 顶层结构
 
 机器可读合同使用 `references/domain-strategy.schema.json`。顶层必须包含：
 
-- `schema_version`、`domain_strategy_id`、`domain_version`、`status`；
+- `schema_version: 2`、`domain_strategy_id`、`domain_version`、`status`；
 - `contexts`、`subdomains`、`relationships`、`scenarios`；
-- `concept_candidates`、`invariants`、`terminology_refs`；
+- `concept_candidates`、`invariants`、`context_snapshot`；
 - `downstream_mapping`、`evidence_refs`、`approval`。
 
-## 上下文
+## 业务责任区
 
-每个上下文声明 `context_id`、职责边界、非职责、子域分类、模型所有者、关键场景和本地词汇引用。`context_id` 是稳定身份，不得使用代码模块、数据库 schema 或菜单路径替代。
+每个业务责任区声明内部 `context_id`、职责边界、非职责、业务板块分类、责任人、关键场景和本地词汇引用。`context_id` 是稳定身份，由 Agent 维护；不得使用代码模块、数据库 schema 或菜单路径替代。
+
+`context_snapshot.context_ref` 固定为 `CONTEXT.md`，`term_refs` 使用 `<ContextId>/<EnglishIdentifier>` 或 `Global/<EnglishIdentifier>`；同时记录完整文档 `document_digest` 与引用术语集 `referenced_terms_digest`。v1 `terminology_refs` 只读并进入迁移检查，只有唯一映射时才可确定性迁移。
 
 ## 关系
 
-关系必须声明 `relationship_pattern`、`semantic_upstream`、`semantic_downstream`、`business_authority`、`model_change_impact`、`transport_direction` 和 `translation_responsibility`。语义方向与技术方向可以不同；关系模式只能使用合同中列出的 DDD 模式。
+协作关系必须声明内部字段 `relationship_pattern`、`semantic_upstream`、`semantic_downstream`、`business_authority`、`model_change_impact`、`transport_direction` 和 `translation_responsibility`。业务人员只需确认协作方式、规则提供方和使用方、业务决策权、信息方向与口径转换负责人；Agent 再映射到合同允许值。
+
+## 待确认的关键业务对象
+
+使用内部类型 `domain_concept_candidate` 表达待确认的关键业务对象，记录识别特征、生命周期、不可违反规则引用、可能的技术映射和置信度。不得在该合同中直接批准技术模型。
 
-## 核心概念
+## 方案决策包
 
-使用 `domain_concept_candidate` 表达战略阶段的核心概念候选，记录身份特征、生命周期、不变量引用、可能的战术角色和置信度。不得在该合同中把概念直接批准为 Entity 或 Aggregate Root。
+方案决策包应通过内部字段 `domain_strategy_ref` 引用本合同的当前版本和 digest，并使用 `domain_to_downstream_mapping` 描述业务变化对 Spec、设计、API、数据、Ticket 和测试 seam 的传播。
 
-## 阶段决策包
+## 便携交付的逐条追溯
 
-阶段包应通过 `domain_strategy_ref` 引用 DDD 合同的当前版本和 digest，并使用 `domain_to_downstream_mapping` 描述领域变化对 Spec、设计、API、数据、Ticket 和测试 seam 的传播。
+正式导出要求 `traceability_version: 1`、`rule_catalog`、场景 `rule_refs / critical / success_results` 和不变量 `rule_ref`。已有 v2 文档继续只读兼容；缺稳定规则 ID 或未重新批准时禁止正式导出。具体合同见 `docs/process/strategic-handoff-package.md`，不得由导出器发明业务身份。

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

@@ -1,11 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://yss.local/schemas/domain-strategy-v1.json",
-  "title": "YSS DDD Strategic Design",
+  "$id": "https://yss.local/schemas/domain-strategy-v2.json",
+  "title": "YSS 业务边界与规则设计",
   "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"],
+  "required": ["schema_version", "domain_strategy_id", "domain_version", "status", "contexts", "subdomains", "relationships", "scenarios", "concept_candidates", "invariants", "context_snapshot", "downstream_mapping", "evidence_refs", "approval"],
   "properties": {
-    "schema_version": {"const": 1},
+    "traceability_version": {"const": 1},
+    "rule_catalog": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["rule_id", "statement", "responsible_context", "status"], "properties": {"rule_id": {"type": "string", "pattern": "^rule\\.[a-z0-9][a-z0-9-]*$"}, "statement": {"type": "string", "minLength": 1}, "responsible_context": {"type": "string", "minLength": 1}, "status": {"const": "confirmed"}}}, "minItems": 1},
+    "schema_version": {"const": 2},
     "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"]},
@@ -15,12 +17,24 @@
     "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}},
+    "context_snapshot": {"$ref": "#/$defs/contextSnapshot"},
     "downstream_mapping": {"type": "array", "items": {"$ref": "#/$defs/mapping"}},
     "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
     "approval": {"$ref": "#/$defs/approval"}
   },
   "$defs": {
+    "contextSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["context_ref", "context_schema_version", "document_digest", "referenced_terms_digest", "term_refs"],
+      "properties": {
+        "context_ref": {"const": "CONTEXT.md"},
+        "context_schema_version": {"const": 1},
+        "document_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "referenced_terms_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "term_refs": {"type": "array", "items": {"type": "string", "pattern": "^(Global|[A-Z][A-Za-z0-9]+)/[A-Z][A-Za-z0-9]+$"}, "uniqueItems": true}
+      }
+    },
     "context": {
       "type": "object",
       "required": ["context_id", "name", "responsibilities", "non_responsibilities", "subdomain_type", "owner", "status"],
@@ -66,6 +80,9 @@
       "type": "object",
       "required": ["scenario_id", "actor", "preconditions", "commands", "rules", "events", "failure_results", "responsible_context", "consumers", "status"],
       "properties": {
+        "rule_refs": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1},
+        "critical": {"type": "boolean"},
+        "success_results": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1},
         "scenario_id": {"type": "string", "pattern": "^scenario\\.[a-z0-9][a-z0-9-]*$"},
         "actor": {"type": "string", "minLength": 1},
         "preconditions": {"type": "array", "items": {"type": "string"}},
@@ -97,6 +114,7 @@
       "type": "object",
       "required": ["invariant_id", "statement", "responsible_context", "scenario_refs", "verification_method"],
       "properties": {
+        "rule_ref": {"type": "string", "minLength": 1},
         "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]+$"},

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

@@ -1,11 +1,12 @@
-# 阶段决策包合同
+# 方案决策包合同
 
-`stage_decision_package` 是 Discovery、需求/产品/商务决策与 DDD 战略设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制领域模型事实。
+内部对象 `stage_decision_package` 是 Discovery、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
 
 ## 必须包含
 
 - 问题陈述、目标用户、MVP、非目标、成功标准和可执行的测试 seam；
 - 已确认决策、假设、约束和未决项；
+- `context_snapshot`：只引用根 `CONTEXT.md`，并绑定结构化术语身份、全文摘要和引用集摘要；
 - `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` 一致。
@@ -17,3 +18,5 @@
 ## 下游消费规则
 
 只有 `approved` 且引用的领域战略为 `approved`、版本当前的阶段包，才可以进入 Spec synthesis。任何领域战略 digest、版本或影响面变化都使阶段包 `stale`，并要求重新评估。
+
+阶段包使用 `schema_version: 2`。旧版字符串路径或 Markdown 锚点只能通过迁移器读取；无法唯一映射到 `<ContextId>/<EnglishIdentifier>` 时返回 `migration-required`，不得猜测。

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

@@ -1,11 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://yss.local/schemas/stage-decision-package-v1.json",
+  "$id": "https://yss.local/schemas/stage-decision-package-v2.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"],
+  "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"],
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"const": 2},
     "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"]},
@@ -19,7 +19,7 @@
     "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}},
+    "context_snapshot": {"$ref": "#/$defs/contextSnapshot"},
     "domain_strategy_ref": {"$ref": "#/$defs/domainRef"},
     "impact_assessment": {"$ref": "#/$defs/impact"},
     "downstream_mapping": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/mapping"}},
@@ -27,6 +27,18 @@
     "approval": {"$ref": "#/$defs/approval"}
   },
   "$defs": {
+    "contextSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["context_ref", "context_schema_version", "document_digest", "referenced_terms_digest", "term_refs"],
+      "properties": {
+        "context_ref": {"const": "CONTEXT.md"},
+        "context_schema_version": {"const": 1},
+        "document_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "referenced_terms_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+        "term_refs": {"type": "array", "items": {"type": "string", "pattern": "^(Global|[A-Z][A-Za-z0-9]+)/[A-Z][A-Za-z0-9]+$"}, "uniqueItems": true}
+      }
+    },
     "unresolved": {
       "type": "object",
       "required": ["item", "type", "owner", "next_action", "target_version"],

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

@@ -3,7 +3,7 @@
 验证分为结构、引用和语义三层：
 
 1. **结构**：Schema 版本、稳定 ID、状态枚举、必填字段、条件字段和证据格式。
-2. **引用**：上下文端点、场景、不变量、术语和下游资产引用必须可解析。
+2. **引用**：上下文端点、场景、不变量、`context_snapshot.term_refs` 和下游资产引用必须可解析；`context_ref` 必须精确为根 `CONTEXT.md`，双摘要必须与当前内容一致。
 3. **语义**：禁止关系自环、未知上下文、未批准 Shared Kernel、未解释的语义/技术方向差异、职责重叠、无责任人的不变量和跨上下文直接共享实体。
 
 以下情况必须 `blocked`：关键规则所有权未知、关键术语冲突、上下文边界未定、关键失败场景缺失、事件语义无法解释、领域专家确认缺失。

package/template/.pi/skills/yss-stage-decision/scripts/migrate-context-references.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+import { parseContextContract, resolveContextTermRefs } from "../../../../scripts/lib/context-contract.mjs";
+
+function migrationRequired(message) {
+  const error = new TypeError(`migration-required: ${message}`);
+  error.code = "migration-required";
+  throw error;
+}
+
+function migrateReference(reference, context) {
+  if (typeof reference !== "string") migrationRequired(`术语引用必须是字符串: ${String(reference)}`);
+  const scoped = reference.match(/^contexts\/([A-Z][A-Za-z0-9]+)\/CONTEXT\.md#([A-Z][A-Za-z0-9]+)$/);
+  if (scoped) {
+    const termRef = `${scoped[1]}/${scoped[2]}`;
+    if (!context.terms_by_ref.has(termRef)) migrationRequired(`旧引用无法唯一定位根 CONTEXT.md 术语: ${reference}`);
+    return termRef;
+  }
+  const root = reference.match(/^CONTEXT\.md#([A-Z][A-Za-z0-9]+)$/);
+  if (root) {
+    const matches = context.business_terms.filter((term) => term.english_identifier === root[1]);
+    if (matches.length !== 1) migrationRequired(`旧引用无法唯一定位根 CONTEXT.md 术语: ${reference}`);
+    return matches[0].term_ref;
+  }
+  migrationRequired(`旧引用无法唯一定位根 CONTEXT.md 术语: ${reference}`);
+}
+
+try {
+  const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+  const file = positionals[0];
+  if (!file) migrationRequired("用法: migrate-context-references.mjs <contract.yaml> [--root <project-root>]");
+  const source = await readFile(file, "utf8");
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) migrationRequired(`YAML 非法: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) migrationRequired("合同必须是对象");
+  if (value.schema_version !== 1) migrationRequired("只迁移 schema_version: 1 合同");
+  if (!Array.isArray(value.terminology_refs)) migrationRequired("v1 合同缺少 terminology_refs");
+
+  const context = parseContextContract({ root: values.root });
+  const termRefs = [...new Set(value.terminology_refs.map((reference) => migrateReference(reference, context)))].sort();
+  const resolved = resolveContextTermRefs(context, termRefs);
+  const migrated = {
+    ...value,
+    schema_version: 2,
+    context_snapshot: {
+      context_ref: "CONTEXT.md",
+      context_schema_version: 1,
+      document_digest: context.document_digest,
+      referenced_terms_digest: resolved.referenced_terms_digest,
+      term_refs: termRefs,
+    },
+  };
+  delete migrated.terminology_refs;
+  process.stdout.write(`${JSON.stringify(migrated, null, 2)}\n`);
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", reason_code: error.code || "migration-required", errors: [error.message] }, null, 2)}\n`);
+  process.exitCode = 1;
+}

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

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import process from "node:process";
+import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecordFile } from "../../../../scripts/lib/approval-record.mjs";
+import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.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"];
+import { extractTraceability } from "../../../../scripts/lib/strategic-handoff-rules.mjs";
+
+const required = ["schema_version", "domain_strategy_id", "domain_version", "status", "contexts", "subdomains", "relationships", "scenarios", "concept_candidates", "invariants", "context_snapshot", "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-]*$/,
@@ -43,11 +47,13 @@ function requireArray(object, field, path, errors, min = 0, itemKind = "string")
   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) {
+function validate(data, contextRoot) {
   const errors = [];
+  if (data?.traceability_version !== undefined) { try { extractTraceability(data); } catch(error) { errors.push(error.message); } }
   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 !== 1) errors.push("schema_version 必须为 1");
+  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
   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 非法");
@@ -128,7 +134,11 @@ function validate(data) {
     for (const reference of invariant?.scenario_refs ?? []) if (!scenarioIds.includes(reference)) errors.push(`${path}.scenario_refs 引用了未声明场景: ${reference}`);
   }
 
-  requireArray(data, "terminology_refs", "root", errors, 0);
+  try {
+    verifyContextSnapshot(data.context_snapshot, { root: contextRoot, allowedContextIds: contextIds });
+  } catch (error) {
+    errors.push(...(error.problems ?? [error.message]));
+  }
   requireArray(data, "evidence_refs", "root", errors, 1);
   const mappings = list(data.downstream_mapping) ? data.downstream_mapping : [];
   for (const [index, mapping] of mappings.entries()) {
@@ -153,15 +163,16 @@ function validate(data) {
   return errors;
 }
 
-const file = process.argv[2];
-if (!file) fail(["用法: validate-domain-strategy.mjs <contract.yaml>"]);
+const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+const file = positionals[0];
+if (!file) fail(["用法: validate-domain-strategy.mjs <contract.yaml> [--root <project-root>]"]);
 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 }));
+      const errors = validate(document.toJS({ maxAliasCount: 0 }), values.root);
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }

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

@@ -3,10 +3,12 @@ import { readFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import process from "node:process";
+import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecordFile } from "../../../../scripts/lib/approval-record.mjs";
+import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.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 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-]*$/;
 
 function fail(errors) {
@@ -20,16 +22,17 @@ function requireArray(object, field, path, errors, min = 0) { requireField(objec
 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) {
+async function validate(data, contextRoot) {
   const errors = [];
   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 !== 1) errors.push("schema_version 必须为 1");
+  if (data.schema_version !== 2) errors.push("schema_version 必须为 2");
   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);
+  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);
 
   const unresolved = Array.isArray(data.unresolved_items) ? data.unresolved_items : [];
   for (const [index, item] of unresolved.entries()) {
@@ -41,13 +44,14 @@ async function validate(data) {
   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");
+  let strategy;
   if (nonEmpty(domainRef.persisted_ref)) {
     try {
-      const strategySource = await readFile(resolve(process.cwd(), domainRef.persisted_ref), "utf8");
+      const strategySource = await readFile(resolve(contextRoot, 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 });
+        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 与实际文件不一致");
@@ -55,6 +59,12 @@ async function validate(data) {
       }
     } catch (error) { errors.push(`domain_strategy_ref.persisted_ref 无法读取: ${error.message}`); }
   }
+  try {
+    const contextIds = Array.isArray(strategy?.contexts) ? strategy.contexts.map((item) => item?.context_id).filter(Boolean) : [];
+    verifyContextSnapshot(data.context_snapshot, { root: contextRoot, allowedContextIds: contextIds });
+  } catch (error) {
+    errors.push(...(error.problems ?? [error.message]));
+  }
 
   const impact = data.impact_assessment ?? {};
   for (const field of ["ui", "api", "data", "backend", "frontend", "cross_repo", "high_risk"]) {
@@ -84,15 +94,16 @@ async function validate(data) {
   return errors;
 }
 
-const file = process.argv[2];
-if (!file) fail(["用法: validate-stage-decision-package.mjs <package.yaml>"]);
+const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+const file = positionals[0];
+if (!file) fail(["用法: validate-stage-decision-package.mjs <package.yaml> [--root <project-root>]"]);
 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 }));
+      const errors = await validate(document.toJS({ maxAliasCount: 0 }), values.root);
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }

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

@@ -12,4 +12,4 @@ countersigner_role_ids:
 evidence_refs:
   - evidence.domain-strategy-review.supplier
 biological_veto: false
-notes: DDD 战略设计由需求经理起草，产品经理独立会签。
+notes: 业务边界与规则设计由需求经理起草，产品经理独立会签。

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

@@ -12,4 +12,4 @@ countersigner_role_ids:
 evidence_refs:
   - evidence.stage-decision-package.supplier
 biological_veto: false
-notes: 阶段决策包由需求经理起草，产品经理独立会签。
+notes: 方案决策包由需求经理起草，产品经理独立会签。

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

@@ -1,6 +1,6 @@
-schema_version: 1
+schema_version: 2
 stage_decision_id: stage-decision.supplier-admission
-package_version: v1
+package_version: v2
 status: approved
 problem_statement: 合规准入决定分散，采购无法稳定判断当前有效资格。
 target_users: [采购专员、合规专员]
@@ -17,13 +17,18 @@ unresolved_items:
     owner: role.product-manager
     next_action: 在 Spec synthesis 前完成数据盘点
     target_version: 2026-Q4
-terminology_refs: [CONTEXT.md#SupplierAdmission]
+context_snapshot:
+  context_ref: CONTEXT.md
+  context_schema_version: 1
+  document_digest: <document-digest>
+  referenced_terms_digest: <referenced-terms-digest>
+  term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 domain_strategy_ref:
   domain_strategy_id: domain-strategy.supplier-admission
-  domain_version: v1
-  digest: sha256:a1a4df23fdb59ab8b4433cedba8271c8a7f11bc8a38abe675d3c7b645d51d7a1
+  domain_version: v2
+  digest: <domain-strategy-digest>
   status: approved
-  persisted_ref: .agents/skills/yss-stage-decision/tests/fixtures/valid-supplier-domain.yaml
+  persisted_ref: domain-strategy.yaml
 impact_assessment:
   ui: true
   api: true
@@ -46,4 +51,4 @@ 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: v1
+  current_version: v2

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

@@ -1,6 +1,6 @@
-schema_version: 1
+schema_version: 2
 domain_strategy_id: domain-strategy.supplier-admission
-domain_version: v1
+domain_version: v2
 status: approved
 contexts:
   - context_id: SupplierManagement
@@ -94,7 +94,12 @@ invariants:
     responsible_context: ComplianceReview
     scenario_refs: [scenario.admission-expires]
     verification_method: 领域场景测试和事件版本校验
-terminology_refs: [contexts/SupplierManagement/CONTEXT.md, contexts/ComplianceReview/CONTEXT.md]
+context_snapshot:
+  context_ref: CONTEXT.md
+  context_schema_version: 1
+  document_digest: <document-digest>
+  referenced_terms_digest: <referenced-terms-digest>
+  term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 downstream_mapping:
   - domain_change: admission-decision-validity
     impacts: [spec, openapi, procurement-acceptance-tests]
@@ -105,4 +110,4 @@ 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: v1
+  current_version: v2