create-yss-spec 3.3.6 → 3.3.8

package/template/.cursor/skills/yss-technical-design/references/technical-design.schema.json

@@ -266,6 +266,12 @@
     "digest": {
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "design_scope": {
+      "enum": [
+        "architecture-specific",
+        "engineering-only"
+      ]
     }
   },
   "required": [
@@ -290,15 +296,31 @@
   "allOf": [
     {
       "if": {
-        "properties": {
-          "architecture": {
+        "allOf": [
+          {
+            "not": {
+              "required": [
+                "design_scope"
+              ],
+              "properties": {
+                "design_scope": {
+                  "const": "engineering-only"
+                }
+              }
+            }
+          },
+          {
             "properties": {
-              "family": {
-                "const": "domain-driven"
+              "architecture": {
+                "properties": {
+                  "family": {
+                    "const": "domain-driven"
+                  }
+                }
               }
             }
           }
-        }
+        ]
       },
       "then": {
         "properties": {
@@ -427,15 +449,31 @@
     },
     {
       "if": {
-        "properties": {
-          "architecture": {
+        "allOf": [
+          {
+            "not": {
+              "required": [
+                "design_scope"
+              ],
+              "properties": {
+                "design_scope": {
+                  "const": "engineering-only"
+                }
+              }
+            }
+          },
+          {
             "properties": {
-              "family": {
-                "const": "layered-mvc"
+              "architecture": {
+                "properties": {
+                  "family": {
+                    "const": "layered-mvc"
+                  }
+                }
               }
             }
           }
-        }
+        ]
       },
       "then": {
         "properties": {
@@ -754,6 +792,246 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "required": [
+          "design_scope"
+        ],
+        "properties": {
+          "design_scope": {
+            "const": "engineering-only"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "design": {
+            "type": "object",
+            "properties": {
+              "scope_reason": {
+                "type": "string",
+                "minLength": 1
+              },
+              "impact_assessment": {
+                "type": "object",
+                "properties": {
+                  "domain_model": {
+                    "const": "none"
+                  },
+                  "business_state": {
+                    "const": "none"
+                  },
+                  "business_rules": {
+                    "const": "none"
+                  },
+                  "business_persistence": {
+                    "const": "none"
+                  },
+                  "schema_migration": {
+                    "const": "none"
+                  },
+                  "ui_change": {
+                    "const": "none"
+                  },
+                  "architecture_boundary_change": {
+                    "const": "none"
+                  }
+                },
+                "required": [
+                  "domain_model",
+                  "business_state",
+                  "business_rules",
+                  "business_persistence",
+                  "schema_migration",
+                  "ui_change",
+                  "architecture_boundary_change"
+                ],
+                "additionalProperties": false
+              },
+              "component_catalog": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "responsibility": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "build_unit_ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "write_paths": {
+                      "type": "array",
+                      "minItems": 1,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "depends_on": {
+                      "type": "array",
+                      "minItems": 0,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "required": [
+                    "component_id",
+                    "responsibility",
+                    "build_unit_ref",
+                    "write_paths",
+                    "depends_on"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "allowed_write_paths": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "read_dependencies": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "digest": {
+                      "type": "string",
+                      "pattern": "^sha256:[a-f0-9]{64}$"
+                    },
+                    "purpose": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "ref",
+                    "digest",
+                    "purpose"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "flow": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "failure_handling": {
+                "type": "string",
+                "minLength": 1
+              },
+              "consistency_policy": {
+                "type": "object",
+                "properties": {
+                  "read_only": {
+                    "const": "read-only"
+                  },
+                  "transaction_boundary": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "concurrency": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "idempotency": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "cross_database_limit": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "timeouts": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "recovery": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "read_only",
+                  "transaction_boundary",
+                  "concurrency",
+                  "idempotency",
+                  "cross_database_limit",
+                  "timeouts",
+                  "recovery"
+                ],
+                "additionalProperties": false
+              },
+              "test_seams": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "seam_id": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "kind": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "subject_ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "assertion": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "seam_id",
+                    "kind",
+                    "subject_ref",
+                    "assertion"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": [
+              "scope_reason",
+              "impact_assessment",
+              "component_catalog",
+              "allowed_write_paths",
+              "read_dependencies",
+              "flow",
+              "failure_handling",
+              "consistency_policy",
+              "test_seams"
+            ],
+            "additionalProperties": false,
+            "title": "既有工程的受控工程技术设计"
+          }
+        }
+      }
     }
   ]
 }

package/template/.cursor/skills/yss-technical-design/scripts/engineering-design.mjs

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import {readFileSync} from 'node:fs';
+import {ensure,read,safe,hash} from '../../../../scripts/lib/strategic-handoff-io.mjs';
+const beneath=(ref,scope)=>ref===scope||ref.startsWith(`${scope}/`);
+export function validateEngineeringDesign(data,{root}) {
+ const registration=read(safe(root,data.architecture.decision_ref));
+ ensure(registration.architecture_identity?.schema_version===2&&registration.architecture_identity.source_kind==='existing-registration','工程设计分支只承接既有工程身份 v2');
+ const binding=registration.architecture_evidence.engineering_baseline;
+ ensure(hash(readFileSync(safe(root,binding.ref)))===binding.digest,'工程设计基线摘要漂移');
+ const baseline=read(safe(root,binding.ref)),design=data.design;
+ ensure(data.inputs.some(x=>x.kind==='engineering'&&x.ref===binding.ref&&x.digest===binding.digest),'工程设计未绑定当前基线输入');
+ ensure(data.inputs.some(x=>x.kind==='api'),'工程设计需当前API或经审查的无API依据');
+ const ids=new Set(design.component_catalog.map(x=>x.component_id));
+ ensure(ids.size===design.component_catalog.length,'工程组件ID重复');
+ const paths=new Set();
+ for(const component of design.component_catalog){
+  const unit=baseline.build_units.find(x=>x.id===component.build_unit_ref);ensure(unit,'工程组件引用未登记的实际构建单元');
+  ensure(component.depends_on.every(id=>ids.has(id)),'工程组件依赖悬空');
+  for(const ref of component.write_paths){
+   ensure(!path.isAbsolute(ref)&&ref.split('/').every(p=>p&&p!=='.'&&p!=='..')&&!ref.includes('\\'),'工程写路径不安全');
+   ensure(registration.allowed_write_paths.some(scope=>beneath(ref,scope)),'工程组件写路径超出登记范围');
+   ensure(!baseline.boundary_scope.some(scope=>beneath(ref,scope)||beneath(scope,ref)),'工程分支不能改已登记业务架构边界');
+   const unitRoot=path.posix.dirname(unit.pom_ref);
+   ensure(unitRoot==='.'||beneath(ref,unitRoot),'工程组件写路径与实际构建单元不符');paths.add(ref);
+  }
+ }
+ ensure(design.allowed_write_paths.length===paths.size&&design.allowed_write_paths.every(ref=>paths.has(ref)),'工程设计写范围与组件闭包不一致');
+ ensure(data.source_items.length&&data.traceability.every(row=>row.disposition==='implemented'),'工程设计必须逐条承接当前范围，不得全标不适用或延期');
+ for(const input of design.read_dependencies)ensure(data.inputs.some(x=>x.ref===input.ref&&x.digest===input.digest),'工程只读依赖未绑定当前输入');
+}

package/template/.cursor/skills/yss-technical-design/scripts/generate-schema.mjs

@@ -10,8 +10,9 @@ const branches = [
 schema.$comment = 'Generated by scripts/generate-schema.mjs from common and specialist schemas. Do not hand-edit.';
 schema.allOf = branches.map(([family, ref]) => {
   const branch = load(ref); delete branch.$id; delete branch.$schema;
-  return { if: { properties: { architecture: { properties: { family: { const: family } } } } }, then: { properties: { design: branch } } };
+  return { if: { allOf: [{ not: { required: ['design_scope'], properties: { design_scope: { const: 'engineering-only' } } } }, { properties: { architecture: { properties: { family: { const: family } } } } }] }, then: { properties: { design: branch } } };
 });
+schema.allOf.push({if:{required:['design_scope'],properties:{design_scope:{const:'engineering-only'}}},then:{properties:{design:load('../references/engineering-design.schema.json')}}});
 const output = fileURLToPath(new URL('../references/technical-design.schema.json', import.meta.url));
 const bytes = `${JSON.stringify(schema, null, 2)}\n`;
 if (process.argv.includes('--check')) {

package/template/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.cursor/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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/.pi/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