create-yss-spec 3.3.6 → 3.3.7

package/README.md

@@ -2,11 +2,11 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.3.6`。当前固定模板为 `yss-spec-project-template@bf18b7898b030da4406aff92b2a13742c596ff09`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准。
+源码候选版本：`3.3.7`。当前固定模板为 `yss-spec-project-template@857265c065d48198aaa2a8bcece22da5885daf7b`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准。
 
 ## 本版模板能力
 
-本版修复生成型 Skill 锁在 `init`、`attach`、`sync` 最终校验前未自动重建的问题。CLI 会在同一事务内刷新 `skills-lock.json`，再运行项目实例校验；刷新或校验失败仍恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
+本版同步 Handoff v4、领域与阶段决策 v3、前后端交付边界和 committed-source 身份校验。CLI 仍会在同一事务内刷新生成型 `skills-lock.json`，再运行项目实例校验；刷新或校验失败恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
 ## 快速开始
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.3.6",
+  "version": "3.3.7",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/template/instance-runtime.js

@@ -395,13 +395,16 @@ function collectManagedFiles(desiredOperations) {
 }
 
 function buildMetadata(variables, desiredOperations, timestamp = nowIsoString()) {
+  const snapshot = readTemplateSnapshot();
   return {
     metadataSchemaVersion: METADATA_SCHEMA_VERSION,
     templateName: PACKAGE_MANIFEST.name,
     cliVersion: PACKAGE_MANIFEST.version,
     templateVersion: PACKAGE_MANIFEST.version,
     templateSource: TEMPLATE_SOURCE,
-    templateCommit: readTemplateSnapshot().templateCommit,
+    templateCommit: snapshot.templateCommit,
+    templateSourceState: snapshot.sourceState,
+    snapshotHash: snapshot.snapshotHash,
     initializedAt: timestamp,
     lastSyncedAt: timestamp,
     managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
@@ -427,6 +430,7 @@ function writeTemplateMetadata(targetDir, metadata, transaction = null) {
 }
 
 function buildNextSyncMetadata(metadata, syncPlan) {
+  const snapshot = readTemplateSnapshot();
   const nextManagedFiles = { ...(metadata.managedFiles || {}) };
   delete nextManagedFiles["README.md"];
   for (const relativePath of syncPlan.alreadyMissing || []) delete nextManagedFiles[relativePath];
@@ -449,7 +453,9 @@ function buildNextSyncMetadata(metadata, syncPlan) {
     cliVersion: PACKAGE_MANIFEST.version,
     templateVersion: PACKAGE_MANIFEST.version,
     templateSource: TEMPLATE_SOURCE,
-    templateCommit: readTemplateSnapshot().templateCommit,
+    templateCommit: snapshot.templateCommit,
+    templateSourceState: snapshot.sourceState,
+    snapshotHash: snapshot.snapshotHash,
     lastSyncedAt: nowIsoString(),
     managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
     managedFiles: nextManagedFiles,

package/src/validation/snapshot.js

@@ -13,6 +13,13 @@ function validateTemplateSnapshot(snapshot, { manifestHash, treeHash } = {}) {
   if (!/^[0-9a-f]{40}$/.test(snapshot.templateCommit || "")) {
     throw new Error("模板快照必须绑定 40 位不可变 templateCommit");
   }
+  if (!["committed", "working-tree"].includes(snapshot.sourceState)) {
+    throw new Error("模板快照 sourceState 必须为 committed 或 working-tree");
+  }
+  const expectedRef = snapshot.sourceState === "working-tree" ? "working-tree" : snapshot.templateCommit;
+  if (snapshot.requestedRef !== expectedRef) {
+    throw new Error(`模板快照 requestedRef 与 sourceState 不一致，预期 ${expectedRef}`);
+  }
   if (!/^[0-9a-f]{64}$/.test(snapshot.snapshotHash || "")) {
     throw new Error("模板快照必须包含 64 位 snapshotHash");
   }

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "41fb25425928153791f7d92a85eb717f4eb2d546",
+  "source_revision": "e24465921a8a51d8690a1732842274a35b935c9e",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -34,7 +34,9 @@
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "b9fe9d8f5009db0289123155f1662d8d21b34e26928d6728545da7f0c0bb0de1"
+      "upstream_hash": "8752a1ed6903bd20c33e21b521d52bd4f7a0662b1d25e00152b60ba38333c93b"
     }
-  ]
+  ],
+  "source_state": "committed",
+  "source_state_note": "source_revision 与 upstream_hash 均来自已提交设计模板。"
 }

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

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

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

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

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

@@ -2,9 +2,10 @@
 
 ## 顶层结构
 
-机器可读合同使用 `references/domain-strategy.schema.json`。顶层必须包含：
+当前机器可读合同使用 `references/domain-strategy-v3.schema.json`；`references/domain-strategy-v2.schema.json` 仅用于历史读取。顶层必须包含：
 
-- `schema_version: 2`、`domain_strategy_id`、`domain_version`、`status`；
+- `schema_version: 3`、`domain_strategy_id`、`domain_version`、`status`、`traceability_version: 1`；
+- 带稳定 `rule_id` 与证据的 `rule_catalog`；
 - `contexts`、`subdomains`、`relationships`、`scenarios`；
 - `concept_candidates`、`invariants`、`context_snapshot`；
 - `downstream_mapping`、`evidence_refs`、`approval`。
@@ -29,4 +30,4 @@
 
 ## 便携交付的逐条追溯
 
-正式导出要求 `traceability_version: 1`、`rule_catalog`、场景 `rule_refs / critical / success_results` 和不变量 `rule_ref`。已有 v2 文档继续只读兼容；缺稳定规则 ID 或未重新批准时禁止正式导出。具体合同见 `docs/process/strategic-handoff-package.md`，不得由导出器发明业务身份。
+正式导出要求场景 `rule_refs / critical / success_results / evidence_refs` 和不变量 `rule_ref / evidence_refs`。`downstream_mapping` 必须使用稳定 `mapping_id`、来源 ID、消费者能力、影响项、传播规则和证据。已有 v2 文档继续只读兼容；修改或重发须显式迁移为 v3 `draft` 并重新批准。具体合同见 `docs/process/strategic-handoff-package.md`，不得由导出器发明业务身份。

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/domain-strategy-v2-compat.json",
+  "allOf": [
+    {"$ref": "domain-strategy.schema.json"},
+    {"properties": {"schema_version": {"const": 2}}, "required": ["schema_version"]}
+  ]
+}

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/domain-strategy-v3.json",
+  "allOf": [
+    {"$ref": "domain-strategy.schema.json"},
+    {"properties": {"schema_version": {"const": 3}}, "required": ["schema_version"]}
+  ]
+}

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

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://yss.local/schemas/domain-strategy-v2.json",
+  "$id": "https://yss.local/schemas/domain-strategy-current.json",
   "title": "YSS 业务边界与规则设计",
   "type": "object",
   "required": ["schema_version", "domain_strategy_id", "domain_version", "status", "contexts", "subdomains", "relationships", "scenarios", "concept_candidates", "invariants", "context_snapshot", "downstream_mapping", "evidence_refs", "approval"],
   "properties": {
     "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},
+    "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"}, "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}}, "minItems": 1},
+    "schema_version": {"enum": [2, 3]},
     "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"]},
@@ -18,7 +18,7 @@
     "concept_candidates": {"type": "array", "items": {"$ref": "#/$defs/concept"}},
     "invariants": {"type": "array", "items": {"$ref": "#/$defs/invariant"}},
     "context_snapshot": {"$ref": "#/$defs/contextSnapshot"},
-    "downstream_mapping": {"type": "array", "items": {"$ref": "#/$defs/mapping"}},
+    "downstream_mapping": {"type": "array"},
     "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
     "approval": {"$ref": "#/$defs/approval"}
   },
@@ -132,6 +132,20 @@
         "reapproval_condition": {"type": "string", "minLength": 1}
       }
     },
+    "mappingV3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mapping_id", "source_refs", "consumer_capability", "impacts", "propagation", "reapproval_condition", "evidence_refs"],
+      "properties": {
+        "mapping_id": {"type": "string", "pattern": "^mapping\\.[a-z0-9][a-z0-9-]*$"},
+        "source_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^(rule|scenario|invariant)\\.[a-z0-9][a-z0-9-]*$"}},
+        "consumer_capability": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]},
+        "impacts": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "propagation": {"enum": ["direct", "transitive", "not-applicable", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1},
+        "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+      }
+    },
     "approval": {
       "type": "object",
       "required": ["approval_ref", "approver", "persisted_ref", "current_version"],
@@ -142,5 +156,61 @@
         "current_version": {"type": "string", "pattern": "^v[0-9]+$"}
       }
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"schema_version": {"const": 3}}, "required": ["schema_version"]},
+      "then": {
+        "required": ["traceability_version", "rule_catalog"],
+        "properties": {
+          "traceability_version": {"const": 1},
+          "rule_catalog": {
+            "items": {
+              "required": ["evidence_refs"],
+              "properties": {
+                "evidence_refs": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {"type": "string", "minLength": 1}
+                }
+              }
+            }
+          },
+          "scenarios": {
+            "items": {
+              "required": ["rule_refs", "critical", "success_results", "evidence_refs"],
+              "properties": {
+                "evidence_refs": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {"type": "string", "minLength": 1}
+                }
+              }
+            }
+          },
+          "invariants": {
+            "items": {
+              "required": ["rule_ref", "evidence_refs"],
+              "properties": {
+                "evidence_refs": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {"type": "string", "minLength": 1}
+                }
+              }
+            }
+          },
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mappingV3"}}
+        }
+      },
+      "else": {
+        "properties": {
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mapping"}}
+        }
+      }
+    }
+  ]
 }

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

@@ -4,12 +4,12 @@
 
 ## 必须包含
 
-- 问题陈述、目标用户、MVP、非目标、成功标准和可执行的测试 seam；
-- 已确认决策、假设、约束和未决项；
+- 问题陈述、目标用户、MVP、非目标，以及带稳定 ID、来源 ID 和证据的成功标准与可执行测试 seam；
+- 带稳定 ID、来源 ID 和证据的已确认决策、假设、约束，以及有责任人的未决项；
 - `context_snapshot`：只引用根 `CONTEXT.md`，并绑定结构化术语身份、全文摘要和引用集摘要；
 - `domain_strategy_ref`：领域战略合同的稳定 ID、版本、digest 和批准状态；
 - UI/API/Data/Backend/Frontend/跨仓/高风险影响面布尔值；
-- 每个下游消费者的传播方式、重新批准条件、证据引用和批准记录。`approval.approval_ref` 必须指向可读取且通过 `scripts/verify-approval-record` 的 `check.stage-decision-package-approved` 会签记录；`approval.approver` 必须与记录中的 `role_id` 一致。
+- 每个消费者能力的稳定 `mapping_id`、领域来源 ID、传播方式、重新批准条件、证据引用和批准记录。`approval.approval_ref` 必须指向可读取且通过 `scripts/verify-approval-record` 的 `gate.stage-decision-package-approved` 会签记录；`approval.approver` 必须与记录中的 `role_id` 一致。
 
 ## 未决项规则
 
@@ -19,4 +19,4 @@
 
 只有 `approved` 且引用的领域战略为 `approved`、版本当前的阶段包，才可以进入 Spec synthesis。任何领域战略 digest、版本或影响面变化都使阶段包 `stale`，并要求重新评估。
 
-阶段包使用 `schema_version: 2`。旧版字符串路径或 Markdown 锚点只能通过迁移器读取；无法唯一映射到 `<ContextId>/<EnglishIdentifier>` 时返回 `migration-required`，不得猜测。
+新写入阶段包使用 `schema_version: 3`，且只能引用 Domain Strategy v3。v2 仅只读；修改或重新交付须用 `scripts/migrate-contract-v3.mjs` 生成未批准的 `draft` 后补齐来源并重新批准。旧版字符串路径或 Markdown 锚点先通过上下文迁移器读取；无法唯一映射到 `<ContextId>/<EnglishIdentifier>` 时返回 `migration-required`，不得猜测。

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/stage-decision-package-v2-compat.json",
+  "allOf": [
+    {"$ref": "stage-decision-package.schema.json"},
+    {"properties": {"schema_version": {"const": 2}}, "required": ["schema_version"]}
+  ]
+}

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.local/schemas/stage-decision-package-v3.json",
+  "allOf": [
+    {"$ref": "stage-decision-package.schema.json"},
+    {"properties": {"schema_version": {"const": 3}}, "required": ["schema_version"]}
+  ]
+}

package/template/.agents/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-v2.json",
+  "$id": "https://yss.local/schemas/stage-decision-package-current.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", "context_snapshot", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"],
   "properties": {
-    "schema_version": {"const": 2},
+    "schema_version": {"enum": [2, 3]},
     "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"]},
@@ -13,16 +13,16 @@
     "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}},
+    "success_criteria": {"type": "array", "minItems": 1},
+    "test_seams": {"type": "array", "minItems": 1},
+    "confirmed_decisions": {"type": "array", "minItems": 1},
+    "assumptions": {"type": "array"},
+    "constraints": {"type": "array"},
     "unresolved_items": {"type": "array", "items": {"$ref": "#/$defs/unresolved"}},
     "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"}},
+    "downstream_mapping": {"type": "array", "minItems": 1},
     "evidence_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
     "approval": {"$ref": "#/$defs/approval"}
   },
@@ -84,6 +84,31 @@
         "reapproval_condition": {"type": "string", "minLength": 1}
       }
     },
+    "recordV3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "statement", "evidence_refs"],
+      "properties": {
+        "id": {"type": "string", "pattern": "^(success-criterion|test-seam|decision|assumption|constraint)\\.[a-z0-9][a-z0-9-]*$"},
+        "statement": {"type": "string", "minLength": 1},
+        "source_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^(rule|scenario|invariant)\\.[a-z0-9][a-z0-9-]*$"}},
+        "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
+        "status": {"enum": ["confirmed", "candidate", "stale"]}
+      }
+    },
+    "mappingV3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mapping_id", "source_refs", "consumer_capability", "propagation", "reapproval_condition", "evidence_refs"],
+      "properties": {
+        "mapping_id": {"type": "string", "pattern": "^mapping\\.[a-z0-9][a-z0-9-]*$"},
+        "source_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^(rule|scenario|invariant)\\.[a-z0-9][a-z0-9-]*$"}},
+        "consumer_capability": {"enum": ["backend-technical-design", "frontend-engineering-design", "delivery-coordination"]},
+        "propagation": {"enum": ["direct", "transitive", "not-applicable", "stale"]},
+        "reapproval_condition": {"type": "string", "minLength": 1},
+        "evidence_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}}
+      }
+    },
     "approval": {
       "type": "object",
       "required": ["approval_ref", "approver", "persisted_ref", "current_version"],
@@ -94,5 +119,30 @@
         "current_version": {"type": "string", "pattern": "^v[0-9]+$"}
       }
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"schema_version": {"const": 3}}, "required": ["schema_version"]},
+      "then": {
+        "properties": {
+          "success_criteria": {"items": {"$ref": "#/$defs/recordV3"}},
+          "test_seams": {"items": {"$ref": "#/$defs/recordV3"}},
+          "confirmed_decisions": {"items": {"$ref": "#/$defs/recordV3"}},
+          "assumptions": {"items": {"$ref": "#/$defs/recordV3"}},
+          "constraints": {"items": {"$ref": "#/$defs/recordV3"}},
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mappingV3"}}
+        }
+      },
+      "else": {
+        "properties": {
+          "success_criteria": {"items": {"type": "string", "minLength": 1}},
+          "test_seams": {"items": {"type": "string", "minLength": 1}},
+          "confirmed_decisions": {"items": {"type": "string", "minLength": 1}},
+          "assumptions": {"items": {"type": "string", "minLength": 1}},
+          "constraints": {"items": {"type": "string", "minLength": 1}},
+          "downstream_mapping": {"items": {"$ref": "#/$defs/mapping"}}
+        }
+      }
+    }
+  ]
 }

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

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

package/template/.agents/skills/yss-stage-decision/scripts/migrate-contract-v3.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
+
+function blocked(message) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", reason_code: "migration-required", errors: [message] }, null, 2)}\n`);
+  process.exitCode = 1;
+}
+
+function parse(source, label) {
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(`${label} YAML 非法: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} 必须是对象`);
+  return value;
+}
+
+function nextVersion(value) {
+  const matched = String(value ?? "v2").match(/^v(\d+)$/);
+  return `v${Math.max(3, Number(matched?.[1] ?? 2) + 1)}`;
+}
+
+function token(value, fallback) {
+  const normalized = String(value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return normalized || fallback;
+}
+
+function resetApproval(value, version) {
+  value.status = "draft";
+  value.approval = {
+    approval_ref: "migration-required",
+    approver: "unassigned",
+    persisted_ref: value.approval?.persisted_ref || "migration-output-not-persisted",
+    current_version: version
+  };
+}
+
+function migrateDomain(input) {
+  const output = structuredClone(input);
+  if (output.schema_version !== 2) throw new TypeError("Domain Strategy 迁移仅支持 schema_version: 2");
+  const evidence = Array.isArray(output.evidence_refs) && output.evidence_refs.length ? output.evidence_refs : ["migration-required:evidence"];
+  const rules = [];
+  const statementToId = new Map();
+  for (const [scenarioIndex, scenario] of (output.scenarios ?? []).entries()) {
+    scenario.rule_refs = [];
+    for (const [ruleIndex, statement] of (scenario.rules ?? []).entries()) {
+      let ruleId = statementToId.get(statement);
+      if (!ruleId) {
+        ruleId = `rule.${token(scenario.scenario_id?.replace(/^scenario\./, ""), `scenario-${scenarioIndex + 1}`)}-${ruleIndex + 1}`;
+        statementToId.set(statement, ruleId);
+        rules.push({ rule_id: ruleId, statement, responsible_context: scenario.responsible_context, status: "confirmed", evidence_refs: [...evidence] });
+      }
+      scenario.rule_refs.push(ruleId);
+    }
+    scenario.critical = false;
+    scenario.success_results = Array.isArray(scenario.events) && scenario.events.length ? [...scenario.events] : ["migration-required: 补充成功结果"];
+    scenario.evidence_refs = [...evidence];
+  }
+  for (const [index, invariant] of (output.invariants ?? []).entries()) {
+    let ruleId = statementToId.get(invariant.statement);
+    if (!ruleId) {
+      ruleId = `rule.${token(invariant.invariant_id?.replace(/^invariant\./, ""), `invariant-${index + 1}`)}`;
+      statementToId.set(invariant.statement, ruleId);
+      rules.push({ rule_id: ruleId, statement: invariant.statement, responsible_context: invariant.responsible_context, status: "confirmed", evidence_refs: [...evidence] });
+    }
+    invariant.rule_ref = ruleId;
+    invariant.evidence_refs = [...evidence];
+  }
+  const sourceRefs = [...(output.scenarios ?? []).map((item) => item.scenario_id), ...(output.invariants ?? []).map((item) => item.invariant_id)].filter(Boolean);
+  output.downstream_mapping = (output.downstream_mapping ?? []).map((mapping, index) => {
+    const impacts = Array.isArray(mapping.impacts) ? mapping.impacts : ["migration-required"];
+    const isFrontend = impacts.some((item) => /frontend|ui|visual/i.test(item));
+    return {
+      mapping_id: `mapping.${token(mapping.domain_change, `migrated-${index + 1}`)}`,
+      source_refs: sourceRefs.length ? sourceRefs : [rules[0]?.rule_id].filter(Boolean),
+      consumer_capability: isFrontend ? "frontend-engineering-design" : "backend-technical-design",
+      impacts,
+      propagation: mapping.propagation,
+      reapproval_condition: mapping.reapproval_condition,
+      evidence_refs: [...evidence]
+    };
+  });
+  output.schema_version = 3;
+  output.traceability_version = 1;
+  output.rule_catalog = rules;
+  output.domain_version = nextVersion(output.domain_version);
+  resetApproval(output, output.domain_version);
+  return output;
+}
+
+async function migrateStage(input, root) {
+  const output = structuredClone(input);
+  if (output.schema_version !== 2) throw new TypeError("Stage Decision 迁移仅支持 schema_version: 2");
+  const evidence = Array.isArray(output.evidence_refs) && output.evidence_refs.length ? output.evidence_refs : ["migration-required:evidence"];
+  let sourceRefs = [];
+  try {
+    const domainSource = await readFile(resolve(root, output.domain_strategy_ref.persisted_ref), "utf8");
+    const domain = parse(domainSource, "Domain Strategy");
+    sourceRefs = [...(domain.rule_catalog ?? []).map((item) => item.rule_id), ...(domain.scenarios ?? []).map((item) => item.scenario_id), ...(domain.invariants ?? []).map((item) => item.invariant_id)].filter(Boolean);
+  } catch {
+    sourceRefs = [];
+  }
+  const prefixes = { success_criteria: "success-criterion", test_seams: "test-seam", confirmed_decisions: "decision", assumptions: "assumption", constraints: "constraint" };
+  for (const [field, prefix] of Object.entries(prefixes)) {
+    output[field] = (output[field] ?? []).map((statement, index) => ({
+      id: `${prefix}.${token(statement, `migrated-${index + 1}`)}`,
+      statement,
+      source_refs: sourceRefs.slice(0, 1),
+      evidence_refs: [...evidence],
+      status: "candidate"
+    }));
+  }
+  output.downstream_mapping = (output.downstream_mapping ?? []).map((mapping, index) => ({
+    mapping_id: `mapping.${token(mapping.domain_change, `migrated-${index + 1}`)}`,
+    source_refs: sourceRefs.slice(0, 1),
+    consumer_capability: /frontend|ui/i.test(mapping.consumer ?? "") ? "frontend-engineering-design" : /coord/i.test(mapping.consumer ?? "") ? "delivery-coordination" : "backend-technical-design",
+    propagation: mapping.propagation,
+    reapproval_condition: mapping.reapproval_condition,
+    evidence_refs: [...evidence]
+  }));
+  output.schema_version = 3;
+  output.package_version = nextVersion(output.package_version);
+  resetApproval(output, output.package_version);
+  return output;
+}
+
+try {
+  const { values, positionals } = parseArgs({
+    options: { kind: { type: "string" }, root: { type: "string", default: process.cwd() } },
+    allowPositionals: true,
+    strict: true
+  });
+  const file = positionals[0];
+  if (!file || !["domain-strategy", "stage-decision"].includes(values.kind)) throw new TypeError("用法: migrate-contract-v3.mjs <contract.yaml> --kind <domain-strategy|stage-decision> [--root <project-root>]");
+  const value = parse(await readFile(file, "utf8"), "合同");
+  const migrated = values.kind === "domain-strategy" ? migrateDomain(value) : await migrateStage(value, values.root);
+  process.stdout.write(`${JSON.stringify(migrated, null, 2)}\n`);
+} catch (error) {
+  blocked(error.message);
+}