create-yss-spec 3.3.6 → 3.3.8

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.8`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
 
 ## 本版模板能力
 
-本版修复生成型 Skill 锁在 `init`、`attach`、`sync` 最终校验前未自动重建的问题。CLI 会在同一事务内刷新 `skills-lock.json`，再运行项目实例校验；刷新或校验失败仍恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
+本版同步 Handoff v5、领域与阶段决策、前后端交付边界和 committed-source 身份校验。CLI 仍会在同一事务内刷新生成型 `skills-lock.json`，再运行项目实例校验；刷新或校验失败恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
 ## 快速开始
 
@@ -25,19 +25,18 @@ npx create-yss-spec@latest \
   --target-dir ./equipment-project
 ```
 
-## 五家族身份保护
+## 四个现行家族与旧实例兼容
 
-CLI 在规划和写入前检查模板家族身份，当前识别：
+CLI 在规划和写入前检查模板家族身份，当前主路线识别：
 
 - `create-yss-spec` / `.yss-template.json`
 - `create-yss-harness-design` / `.yss-harness-design.json`
-- `create-yss-harness-dev` / `.yss-harness-dev.json`
-- repository-local backend / `.yss-harness-backend.json`
-- repository-local frontend / `.yss-harness-frontend.json`
+- `create-yss-harness-backend` / `.yss-harness-backend.json`
+- `create-yss-harness-frontend` / `.yss-harness-frontend.json`
 
 `docs/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
 
-后端/前端专职模板使用各自仓库的 `scripts/instantiate-harness --target <新目录>`，不由本 CLI 做跨家族原地迁移。
+旧 `create-yss-harness-dev` / `.yss-harness-dev.json` 仍会被识别并拒绝跨家族接管；既有实例按原固定版本维护，不再作为新项目入口。战略、后端和前端分别使用专职 CLI，任何家族都不做跨家族原地迁移。
 
 ## CLI 能力
 
@@ -155,17 +154,17 @@ Inspect → Desired State → Policy → Plan → Validate → Transaction → V
 
 ## 使用未发布候选包
 
-从本仓固定提交构建候选包时，先使用 `scripts/sync-template.js` 中的 `DEFAULT_TEMPLATE_REF` 重建模板快照，再打包：
+从本仓构建候选包时，先用明确来源重建模板快照，再打包：
 
 ```bash
-YSS_SPEC_TEMPLATE_REPO=https://github.com/iloveZzz/yss-spec-project-template.git \
-YSS_SPEC_TEMPLATE_REF=017925706a981aec9eadefd470232bb531acd4d6 \
+YSS_SPEC_TEMPLATE_REPO=/absolute/path/to/yss-spec-project-template \
+YSS_SPEC_TEMPLATE_REF=WORKTREE \
 node scripts/sync-template.js
 
 npm pack --ignore-scripts
 ```
 
-`--ignore-scripts` 仅用于已经显式重建并核对固定快照后的候选打包，不代表 npm 发布。
+`WORKTREE` 仅形成 implementation-ready 候选；固定交付必须改用完整 40 位提交。`--ignore-scripts` 仅用于已经显式重建并核对快照后的候选打包，不代表 npm 发布。
 
 ## 开发验证
 
@@ -173,7 +172,7 @@ npm pack --ignore-scripts
 npm run test:contracts
 npm run test:unit
 npm run test:integration
-YSS_SPEC_TEMPLATE_REF=017925706a981aec9eadefd470232bb531acd4d6 npm test
+YSS_SPEC_TEMPLATE_REPO=/absolute/path/to/yss-spec-project-template YSS_SPEC_TEMPLATE_REF=WORKTREE npm test
 npm pack --dry-run
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.3.6",
+  "version": "3.3.8",
   "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": "b7947298f74510861a36caedda4e77d03df35569",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -14,7 +14,7 @@
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "aa78ef758ad3c515e94fb6b87d4e519f39a38e53bb3c82413d707f7d0f96f58b"
+      "upstream_hash": "4bb0ba6cdbbbd1a3b89e97d94a7b0829c9282e21c8ce9e4bfda6e69a8714bc6d"
     },
     {
       "upstream": "yss-design-system",
@@ -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/implementation-repo-onboarding/SKILL.md

@@ -16,13 +16,13 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 ## Workflow
 
-1. 确认当前仓库是 Harness 仓库，读取 `docs/process/implementation-repo-integration.md`。
+1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `docs/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `docs/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
 5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
 6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
-7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
 
 ## Baseline Checks
 

package/template/.agents/skills/yss-application/SKILL.md

@@ -7,7 +7,7 @@ description: Use when implementing YSS application use cases, transaction bounda
 
 ## 架构分流（先执行）
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。支持的分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有工程分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
 
 以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 

package/template/.agents/skills/yss-application/references/profiles/existing-domain-driven-maven.md

@@ -0,0 +1,5 @@
+# existing-domain-driven-maven
+
+只用于 `source_kind=existing-registration` 且 `architecture_family=domain-driven` 的受支持身份。Application 责任以登记、工程基线、独立观测 manifest 与边界审查的实际 build unit/package 映射为准，不要求生成式 `application` 模块存在。
+
+有批准的 Application 源码写路径时，按实际 use-case seam 组织领域与端口；没有该写路径且技术设计明确为 engineering-only 时，只核验 Web build unit 内的只读 orchestration seam 满足合同，不新建业务 Application、Domain、Gateway 或事务层。任何业务规则、持久化写入、新跨上下文协作或无法解释的责任映射都返回 `new_impacts` 或 `blocked`。

package/template/.agents/skills/yss-application/references/profiles/existing-layered-mvc-maven.md

@@ -0,0 +1,5 @@
+# existing-layered-mvc-maven
+
+只用于 `source_kind=existing-registration` 且 `architecture_family=layered-mvc` 的受支持身份。以登记、工程基线、独立观测 manifest 和边界审查中的实际 service/core/use-case build unit、source root 与 package 映射确定 Application 责任；不得要求模板模块名、数量或生成器 manifest。
+
+有批准的 service/core 写路径时在现有公开用例 seam 内实现编排和事务。若 engineering-only 技术设计没有对应写路径，只核验已批准的只读 orchestration seam，不制造 Domain Gateway、业务 service 或持久化层。Controller 直连 Repository、越界路径或责任无法映射时返回 `blocked`。

package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md

@@ -20,7 +20,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 ## 编译循环
 
 1. 判断 frontend/backend/API/data/domain/cross-repo 影响，并按 [compiler-contract.yaml](references/compiler-contract.yaml) 把 impact 映射为入口 capability；逐项填写 backend `component_impacts`。
-2. 检查工程存在性和核心/长尾 skill 可用性。
+2. 按 `docs/process/delivery-preflight.md` 只读检查当前阶段交付前提，再检查工程存在性和核心/长尾 skill 可用性。既有 Java/Maven 工程按 `docs/process/existing-backend-architecture.md` 加载登记、工程基线、独立观测的原始引用与摘要；不伪填生成器或 H2。
 3. 从 `docs/agents/yss-skill-registry.yaml` 选择一个或多个窄 Recipe，合并 `required_capabilities`；Recipe 不得直接引用 skill。
 4. 由 capability 解析入口 skill，只递归 `context-required`；`context-conditional` 仅在显式 condition 命中时加载，其他依赖类型只进入原因链，不扩张执行上下文。
 5. 按“Recipe 声明顺序 → 依赖拓扑 → skill ID”确定性排序，去重 skill 并保留全部原因；冻结 Registry 与编译器合同 SHA-256。
@@ -37,7 +37,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - 编译器不得输出 `approved`、`ready-for-agent` 或 `completed`。
 - Registry、Slice Contract 或编译器合同 schema v1 一律拒绝并给出迁移到 v2 的提示；不自动升级，不提供旧技能名兼容。
 - `required_capabilities` 与 `required_skills` 必须同时冻结；Registry 或编译器摘要变化后合同立即 `stale`，重新编译后仍须交生命周期重新批准。
-- UI 影响缺少正式原型确认、批准且 digest 当前的 Visual Baseline manifest 或当前切片 `case_id` 时，不得路由页面实现。模型必须先读 manifest 与语义引用，再查看对应 PNG；禁止目录 glob 和图片独立猜义。
+- UI 影响按来源分支核验：新设计保持正式原型确认与 Visual Baseline；无 UI 改动才允许 `existing-ui-baseline` v1，并须当前真实基线确认及 `case_id`。任一来源缺少当前批准或摘要绑定时，不得路由页面实现。模型必须先读 manifest 与语义引用，再查看对应 PNG；禁止目录 glob 和图片独立猜义。
 - Repository/数据模型影响缺少数据架构时，不得路由持久化实现。
 - 后端技术设计由 `yss-technical-design` 先行组织。消费批准且版本当前的 Technical Design Contract，核对其架构与工程基线一致；DDD 才消费聚合、Gateway 等战术字段并路由 `yss-domain`，MVC 消费用例、分层、规则和事务设计并按 Profile 路由。旧 v1 战术合同只按 DDD 显式兼容读取。无相关影响记录带原因的 `not-applicable`。
 - API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。

package/template/.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml

@@ -3,6 +3,10 @@ backend_architecture:
   registry_source: docs/agents/yss-skill-registry.yaml
   identity_schema: docs/process/schemas/backend-architecture-identity.schema.json
   required_evidence: [engineering_baseline, repository_registration, manifest]
+  evidence_loading: original-references-and-raw-sha256
+  existing_identity: {schema_version: 2, source_kind: existing-registration, profiles_source: existing_project_profiles}
+  generated_identity: preserve-original-generator-and-module-closure
+  existing_source_policy: fixed-input-and-approved-bounded-output
   required_identity_surfaces: [resolution, work_unit, execution_result]
   family_recipe_selection: explicit-ddd-or-mvc-no-legacy-alias
   readiness: supported-profile-and-current-identical-evidence

package/template/.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -12,7 +12,12 @@ document_writing:
   gate_and_status_semantics: unchanged
 
 backend_architecture_identity_policy:
-  source: docs/agents/yss-skill-registry.yaml#architecture_profiles
+  source: docs/agents/yss-skill-registry.yaml
+  generated_profiles: architecture_profiles
+  existing_profiles: existing_project_profiles
+  existing_evidence: [repository-registration, engineering-baseline, existing-project-observation]
+  evidence_policy: original-ref-digest-and-current-source-verification
+  delivery_preflight: scripts/preflight-delivery
   schema: docs/process/schemas/backend-architecture-identity.schema.json
   required_surfaces: [engineering-baseline, repository-registration, scaffold-manifest, slice-contract, work-unit, execution-result]
   agreement: exact-identity-and-digest

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

@@ -1,6 +1,6 @@
 ---
 name: yss-prototype-stage
-description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs profile-routed prototype assets before implementation readiness.
+description: Use when a YSS feature has product-design impact on a primary flow, navigation, state, recovery, permission experience, or UI-driven API contract and needs profile-routed prototype assets before implementation readiness, or when handing off a confirmed unchanged existing UI baseline.
 ---
 
 # YSS Prototype Stage
@@ -62,3 +62,12 @@ Design QA 合并 visual、layout、interaction、content、accessibility、cross
 - H1 伪造 lockfile/AntD 段，或 H2 声称已验证生产 YSS/AntDV 真实组件。
 - 重复抄写机器可采集的版本、digest、截图和 console；创建第二份状态机、QA 或 handoff 资产。
 - 把原型源码直接复制进生产，或在原型阶段调用 `yss-ui`。
+
+
+## 既有 UI 的交接入口
+
+现有工程需要跨仓交接且确认 UI、交互、状态和权限体验均无改动时，先读取 `docs/process/existing-ui-baseline.md`，使用独立 `existing-ui-baseline` v1，不进入 H1/H2 原型构建。绑定固定源码、锁文件、实际构建、原始动作、PNG 截图和真实 API 交换证据；可离线审阅不等于可离线运行原型。
+
+通过 `gate.product-design-approved` 的现有用户决定协议确认当前基线 manifest 原字节，Handoff v5 明确声明 `ui_baseline_kind: existing-ui-baseline`。截图、代码可运行或旧原型批准都不能替代该确认；本技能只能准备审阅资产，不代答或批准。发现任何 UI 改动，包括后端行为导致的体验变化，回到上述原型流程；新设计继续保留现有原型与验证要求。
+
+消费者以 `scripts/preflight-delivery` 检查交付前提，再由 `scripts/lib/ui-baseline.mjs` 分派原型与既有基线。前端使用 Strategic Preflight v2 和 Delivery Acceptance v3 的通用 `baseline_case_ids` 承接；通过仅说明输入可核验，不授予写代码权限。

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"]}
+  ]
+}