create-yss-spec 3.3.6 → 3.3.8

package/template/.codex/skills/yss-technical-design/scripts/validate-technical-design.mjs

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
+import { validateEngineeringDesign } from './engineering-design.mjs';
+import { createApprovedExecutionContext, assertApprovedExecutionContext } from '../../../../scripts/lib/approved-execution-context.mjs';
+import { verifyArchitectureEvidence } from '../../../../scripts/lib/backend-architecture.mjs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -39,7 +42,8 @@ function validateMvc(design) {
   if (!design.integration_catalog.length) ensure(text(design.integration_not_applicable_reason), '无外部集成必须说明原因');
 }
 
-export function verifyArchitecture(data, root) {
+export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
+  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef});
   const binding = data.architecture;
   const file = safe(root, binding.decision_ref);
   ensure(hash(readFileSync(file)) === binding.decision_digest, '架构来源摘要漂移');
@@ -57,6 +61,10 @@ export function verifyArchitecture(data, root) {
     const entry = record.repositories?.find(item => item.project_id === binding.project_id) ?? record;
     ensure(entry.project_id === binding.project_id && entry.architecture_identity?.architecture_family === binding.family, '技术设计与既有工程登记架构不匹配');
     ensure(!['stale','blocked'].includes(record.status) && !['stale','blocked'].includes(entry.status), '工程登记已失效');
+    if (entry.architecture_identity?.schema_version === 2) {
+      ensure(entry.architecture_evidence?.engineering_baseline && entry.architecture_evidence?.manifest, '既有工程登记缺少原始工程证据引用');
+      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution });
+    }
   }
 }
 
@@ -87,14 +95,14 @@ function validateLocalTraceability(data, root, sliceRef) {
   }
 }
 
-export async function validateTechnicalDesign(data, { root = process.cwd(), sliceRef, legacyDdd = false } = {}) {
+export async function validateTechnicalDesign(data, { root = process.cwd(), sliceRef, legacyDdd = false, readOnly = false, execution } = {}) {
   if (data?.schema_version === 1) {
     ensure(legacyDdd, '旧 v1 合同需要显式 --legacy-ddd，仅按 DDD 兼容读取');
     const errors = validateDdd(data);
     ensure(!errors.length, errors.join('; '));
     if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
     if (data.strategic_handoff || data.strategic_context_import_ref || data.upstream_impact?.source_kind === 'strategic-handoff') {
-      const result = await verifyConsumption(data, { root, sliceRef });
+      const result = await verifyConsumption(data, { root, sliceRef, readOnly });
       ensure(result.result === 'verified', JSON.stringify(result));
     }
     return { result: 'legacy-ddd-read-only', architecture_family: 'domain-driven', status: data.status };
@@ -103,12 +111,13 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
   ensure(data.digest === technicalDigest(data), '技术设计合同摘要不匹配');
   ensure(!['stale','blocked','drift','new_impacts'].includes(data.status), '设计状态不可消费');
   if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
-  verifyArchitecture(data, root);
+  verifyArchitecture(data, root, {execution,sliceRef});
   ensure(data.inputs.some(item => item.kind === 'context' && item.ref === 'CONTEXT.md') && data.inputs.some(item => item.kind === 'spec'), '共同输入缺少根 CONTEXT.md 或 Spec');
   for (const input of data.inputs) ensure(hash(readFileSync(safe(root, input.ref))) === input.digest, `输入摘要漂移: ${input.ref}`);
   for (const ref of data.evidence_refs) safe(root, ref);
   if (data.status === 'approved') ensure(data.evidence_refs.length > 0, '已批准设计缺少评审证据');
-  if (data.architecture.family === 'domain-driven') {
+  if(data.design_scope==='engineering-only')validateEngineeringDesign(data,{root});
+  else if (data.architecture.family === 'domain-driven') {
     const errors = validateDdd(data.design);
     ensure(!errors.length, errors.join('; '));
     ensure(data.design.status === data.status, 'DDD 分支状态与共同合同不一致');
@@ -119,16 +128,19 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
   for (const seam of seams.values()) ensure(ids.has(seam.subject_ref), `测试 seam 设计对象悬空: ${seam.seam_id}`);
   validateLocalTraceability(data, root, sliceRef);
   if (data.strategic_handoff) {
-    const result = await verifyConsumption(data, { root, sliceRef });
+    const result = await verifyConsumption(data, { root, sliceRef, readOnly });
     ensure(result.result === 'verified', JSON.stringify(result));
   }
   return { result: 'ready-for-lifecycle-review', technical_design_id: data.technical_design_id, architecture_family: data.architecture.family, status: data.status, digest: data.digest };
 }
 
 async function main() {
-  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false } } });
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
   ensure(positionals.length === 1, '用法: validate-technical-design.mjs <合同> --root <项目根> [--slice <ID>] [--legacy-ddd]');
-  const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'] });
+  const approvedOptions=['approved-slice','approved-slice-digest','approved-slice-approval'];
+  ensure(!approvedOptions.some(key=>values[key])||approvedOptions.every(key=>values[key]),'执行增量必须完整给出持久化 Slice、字节摘要及本地批准引用');
+  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root}):undefined;
+  const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'], readOnly:values['read-only'], execution });
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => { process.stderr.write(`${JSON.stringify({ result: 'blocked', errors: [error.message] })}\n`); process.exitCode = 1; });

package/template/.codex/skills/yss-technical-design/tests/engineering-scenarios.mjs

@@ -0,0 +1,12 @@
+import test from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';import path from 'node:path';
+import {fixture} from '../../../../scripts/fixtures/existing-backend/fixture.mjs';
+import {validateTechnicalDesign,technicalDigest} from '../scripts/validate-technical-design.mjs';
+import {enforceTechnicalDesign} from '../../../../scripts/lib/technical-design-boundary.mjs';
+function design(f){
+ f.write('spec.md','只增加默认关闭的工程诊断；不改业务领域或数据。');f.write('api.json',{openapi:'3.1.0',paths:{'/internal/identity':{get:{operationId:'identity'}}}});
+ const binding=ref=>({ref,version:'v1',digest:f.write(ref,fs.readFileSync(path.join(f.root,ref),'utf8')).digest});
+ const data={schema_version:2,technical_design_id:'technical-design.engineering',version:'v1',status:'ready-for-human',context_ref:'CONTEXT.md',design_scope:'engineering-only',architecture:{family:f.identity.architecture_family,source_kind:'existing-registration',project_id:f.identity.project_id,decision_ref:f.bindings.repository_registration.ref,decision_digest:f.bindings.repository_registration.digest},inputs:[{kind:'context',...f.write('CONTEXT.md','# 业务上下文\n'),version:'v1'},{kind:'spec',...binding('spec.md')},{kind:'api',...binding('api.json')},{kind:'engineering',...f.bindings.engineering_baseline,version:'v1'}],source_items:[{source_id:'scenario.identity',kind:'scenario',critical:true,source_ref:'spec.md'}],traceability:[{source_id:'scenario.identity',disposition:'implemented',tactical_refs:['component.build'],test_seam_refs:['test-seam.ok','test-seam.fail'],evidence_refs:['spec.md'],dependency_status:'known',dependent_slice_refs:['slice.identity'],scenario_tests:[{outcome:'success',seam_ref:'test-seam.ok'},{outcome:'failure',seam_ref:'test-seam.fail'}]}],design:{scope_reason:'仅工程配置',impact_assessment:Object.fromEntries(['domain_model','business_state','business_rules','business_persistence','schema_migration','ui_change','architecture_boundary_change'].map(k=>[k,'none'])),component_catalog:[{component_id:'component.build',responsibility:'工程诊断资源',build_unit_ref:'app',write_paths:['pom.xml'],depends_on:[]}],allowed_write_paths:['pom.xml'],read_dependencies:[{...f.bindings.engineering_baseline,purpose:'固定构建图'}],flow:['核验固定资源','缺失时失败'],failure_handling:'503',consistency_policy:{read_only:'read-only',transaction_boundary:'no write',concurrency:'bounded',idempotency:'read',cross_database_limit:'no atomic claim',timeouts:'5seconds',recovery:'restore original'},test_seams:[{seam_id:'test-seam.ok',kind:'engineering',subject_ref:'component.build',assertion:'当前资源返回身份'},{seam_id:'test-seam.fail',kind:'engineering',subject_ref:'component.build',assertion:'坏资源拒绝'}]},evidence_refs:['spec.md']};data.digest=technicalDigest(data);return data;
+}
+for(const family of ['domain-driven','layered-mvc'])test(`${family} engineering-only preserves real architecture without invented domain models`,async t=>{const f=fixture(family);t.after(f.cleanup);const data=design(f);await validateTechnicalDesign(data,{root:f.root});assert.equal(data.design.aggregate_catalog,undefined);});
+test('engineering branch rejects domain/catalog/path/unit/write-mode/evidence/seam bypasses',async t=>{const f=fixture();t.after(f.cleanup);for(const fault of ['domain','catalog','path','unit','write','api','seam']){const data=design(f);if(fault==='domain')data.design.impact_assessment.domain_model='changed';if(fault==='catalog')data.design.aggregate_catalog=[];if(fault==='path'){data.design.component_catalog[0].write_paths=['src/main/java/application'];data.design.allowed_write_paths=['src/main/java/application'];}if(fault==='unit')data.design.component_catalog[0].build_unit_ref='missing';if(fault==='write')data.design.consistency_policy.read_only='read-write';if(fault==='api')data.inputs=data.inputs.filter(x=>x.kind!=='api');if(fault==='seam')data.traceability[0].scenario_tests=data.traceability[0].scenario_tests.slice(0,1);data.digest=technicalDigest(data);await assert.rejects(()=>validateTechnicalDesign(data,{root:f.root}),undefined,fault);}});
+test('compiler cannot downgrade domain impact to engineering-only',t=>{const f=fixture();t.after(f.cleanup);const data=design(f);data.status='approved';data.digest=technicalDigest(data);const binding={...f.write('technical.json',data),version:'v1'};assert.throws(()=>enforceTechnicalDesign({technical_design:binding,architecture_identity:f.identity,slice_id:'slice.identity',conditions:['aggregate-impact']},{root:f.root}),/engineering|工程/);});

package/template/.codex/skills/yss-web-controller/SKILL.md

@@ -7,7 +7,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 
 ## 架构分流（先执行）
 
-读取当前合同的 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/.codex/skills/yss-web-controller/references/profiles/existing-domain-driven-maven.md

@@ -0,0 +1,5 @@
+# existing-domain-driven-maven
+
+只用于 `source_kind=existing-registration` 且 `architecture_family=domain-driven` 的受支持身份。先核验登记、工程基线、独立观测 manifest 和边界审查的当前摘要，再以工程基线中的实际 build unit、source root、package 与 architecture responsibility 映射确定 Web 落点；不得要求模板模块名、数量或生成器 manifest。
+
+Controller 只暴露冻结接口并调用合同指定的 Application 或 engineering-only orchestration seam。若批准合同将只读工程探针放在实际 Web build unit 内且没有 Application 源码写路径，保持该边界，不为满足生成式目录结构新建模块、聚合、Gateway 或业务服务。请求参数、Result 包装、错误脱敏、允许路径和真实 Maven/JAR 验证仍按共用规则执行。实际映射不清、越出登记源码根或改变业务架构时返回 `blocked`。

package/template/.codex/skills/yss-web-controller/references/profiles/existing-layered-mvc-maven.md

@@ -0,0 +1,5 @@
+# existing-layered-mvc-maven
+
+只用于 `source_kind=existing-registration` 且 `architecture_family=layered-mvc` 的受支持身份。以登记、工程基线、独立观测 manifest 与边界审查中的实际 build unit、source root、package 和 responsibility 映射确定 Controller/server 落点；模块名和数量可以与模板不同，不补造生成器或脚手架合同。
+
+Controller 只调用已登记的 service/use-case seam，保持公开 DTO、私有 DTO、错误脱敏和事务责任的实际映射。批准合同若只允许现有 build unit 内的 engineering-only seam，不得为套用生成式结构新建 client/server/service 模块。映射不清、Controller 直连 Repository、越界路径或业务架构变化均返回 `blocked`。

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