create-yss-spec 3.3.7 → 3.4.1

package/template/scripts/lib/existing-backend-architecture.mjs

@@ -0,0 +1,139 @@
+import {assertApprovedExecutionContext} from './approved-execution-context.mjs';
+import {createHash} from 'node:crypto';
+import {readFileSync,realpathSync,lstatSync,readdirSync} from 'node:fs';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {parseDocument} from '../vendor/yaml.mjs';
+import {validateApprovalRecord} from './approval-record.mjs';
+
+const sha=bytes=>`sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const stable=x=>Array.isArray(x)?x.map(stable):x&&typeof x==='object'?Object.fromEntries(Object.keys(x).sort().map(k=>[k,stable(x[k])])):x;
+export const existingArchitectureDigest=x=>sha(JSON.stringify(stable(x)));
+const text=x=>typeof x==='string'&&x.trim().length>0;
+const digest=x=>typeof x==='string'&&/^sha256:[a-f0-9]{64}$/.test(x);
+function requireThat(ok,code,message){if(!ok){const e=new TypeError(`${code}: ${message}`);e.code=code;throw e;}}
+function relative(ref){requireThat(text(ref)&&!path.isAbsolute(ref)&&!/[\\\x00-\x1f]/.test(ref)&&ref.split('/').every(x=>x&&x!=='.'&&x!=='..'),'ARCH_PATH','证据路径必须为安全相对路径');return ref;}
+function file(root,ref){relative(ref);let current=realpathSync(root);for(const part of ref.split('/')){current=path.join(current,part);requireThat(!lstatSync(current).isSymbolicLink(),'ARCH_PATH',`不允许 symlink: ${ref}`);}requireThat(lstatSync(current).isFile(),'ARCH_PATH',`不是文件: ${ref}`);return current;}
+function parse(bytes){const doc=parseDocument(String(bytes),{uniqueKeys:true,maxAliasCount:0});requireThat(!doc.errors.length,'ARCH_EVIDENCE_FORMAT',doc.errors[0]?.message);return doc.toJS({maxAliasCount:0});}
+function bound(root,binding){requireThat(binding&&text(binding.ref)&&digest(binding.digest),'ARCH_EVIDENCE_REF','缺少原始证据 ref/digest');const bytes=readFileSync(file(root,binding.ref));requireThat(sha(bytes)===binding.digest,'ARCH_EVIDENCE_STALE',`原始证据已改变: ${binding.ref}`);return parse(bytes);}
+function same(a,b,code,label){requireThat(existingArchitectureDigest(a)===existingArchitectureDigest(b),code,label);}
+const FIELDS=['schema_version','source_kind','architecture_family','architecture_profile','repository_id','project_id','source_digest','build_units_digest'];
+export function validateExistingArchitecture(identity,registry){
+ requireThat(identity?.schema_version===2&&identity.source_kind==='existing-registration','ARCH_SOURCE_UNSUPPORTED','仅支持 existing-registration v2');
+ requireThat(FIELDS.every(k=>identity[k]!==undefined)&&Object.keys(identity).every(k=>FIELDS.includes(k)),'ARCH_IDENTITY_SHAPE','既有身份字段缺失或混入生成事实');
+ const p=registry.existing_project_profiles?.[identity.architecture_profile];
+ requireThat(p&&p.source_kind==='existing-registration'&&p.build_system==='maven'&&p.architecture_family===identity.architecture_family,'ARCH_PROFILE_UNSUPPORTED','未支持的既有工程架构/Profile');
+ requireThat(['domain-driven','layered-mvc'].includes(identity.architecture_family)&&text(identity.repository_id)&&text(identity.project_id)&&digest(identity.source_digest)&&digest(identity.build_units_digest),'ARCH_IDENTITY_SHAPE','既有身份未绑定项目或源码/构建摘要');
+ return p;
+}
+const beneath=(ref,scope)=>scope==='.'||ref===scope||ref.startsWith(`${scope}/`);
+const excluded=ref=>ref.split('/').some(x=>['.git','target','node_modules'].includes(x));
+function listFiles(root,prefix=''){return readdirSync(path.join(root,prefix),{withFileTypes:true}).flatMap(entry=>{const ref=prefix?`${prefix}/${entry.name}`:entry.name;if(excluded(ref))return[];requireThat(!entry.isSymbolicLink(),'ARCH_PATH',`源码中出现 symlink: ${ref}`);return entry.isDirectory()?listFiles(root,ref):[ref];});}
+function inspectMaven(root,units){
+ // Only parses XML; never invokes Maven or executes project-supplied commands.
+ const script=`import json,sys,xml.etree.ElementTree as ET\nout=[]\nfor p in json.load(sys.stdin):\n r=ET.parse(p).getroot(); ns={'m':'http://maven.apache.org/POM/4.0.0'}; q=lambda s:r.find(s,ns)\n aid=q('m:artifactId'); aid=aid if aid is not None else q('artifactId')\n deps=[e.text.strip() for e in r.findall('m:dependencies/m:dependency/m:artifactId',ns)+r.findall('m:profiles/m:profile/m:dependencies/m:dependency/m:artifactId',ns)+r.findall('dependencies/dependency/artifactId') if e.text]\n modules=[e.text.strip() for e in r.findall('.//m:modules/m:module',ns)+r.findall('.//modules/module') if e.text]\n out.append({'artifact_id':aid.text.strip() if aid is not None else '', 'dependencies':deps, 'modules':modules})\nprint(json.dumps(out))`;
+ try{return JSON.parse(execFileSync('python3',['-c',script],{input:JSON.stringify(units.map(u=>file(root,u.pom_ref))),encoding:'utf8',timeout:15000,maxBuffer:2*1024*1024}));}catch(error){requireThat(false,'ARCH_BUILD_INVALID',`无法读取实际 Maven 构建单元: ${error.message}`);}
+}
+export function verifyExistingArchitecture(identity,bindings,{root,registry,execution}={}){
+ const profile=validateExistingArchitecture(identity,registry);
+ requireThat(text(root),'ARCH_EVIDENCE_REF','需要治理 root');
+ const baseline=bound(root,bindings?.engineering_baseline),registration=bound(root,bindings?.repository_registration),manifest=bound(root,bindings?.manifest);
+ for(const [name,record] of Object.entries({baseline,registration,manifest})){
+  same(identity,record.architecture_identity,'ARCH_IDENTITY_CONFLICT',`${name} 架构身份与合同不一致`);
+  requireThat(record.repository_id===identity.repository_id&&record.project_id===identity.project_id,'ARCH_REPOSITORY_CONFLICT',`${name} 仓库/项目不一致`);
+ }
+ requireThat(manifest.kind==='existing-project-observation'&&manifest.schema_version===1,'ARCH_MANIFEST_KIND','需要既有工程观测 manifest，不能冒充脚手架');
+ requireThat(baseline.kind==='existing-engineering-baseline'&&baseline.schema_version===1,'ARCH_BASELINE_KIND','需要既有工程基线');
+ requireThat(registration.status==='current'&&baseline.status==='current','ARCH_EVIDENCE_STALE','登记/工程基线不是 current');
+ requireThat(text(registration.local_worktree)&&text(registration.project_root)&&text(registration.owner)&&text(registration.repository_url),'ARCH_REGISTRATION_MISSING','登记缺根路径、仓库来源或责任人');
+ for(const key of ['engineering_baseline','manifest'])same(registration.architecture_evidence?.[key],bindings[key],'ARCH_EVIDENCE_CONFLICT',`登记未引用当前${key}`);
+ const repositoryRoot=realpathSync(registration.local_worktree);
+ const projectRoot=registration.project_root==='.'?repositoryRoot:path.join(repositoryRoot,relative(registration.project_root));
+ requireThat(realpathSync(projectRoot)===projectRoot,'ARCH_PATH','工程根存在符号链接');
+ const git=(args)=>execFileSync('git',['-C',repositoryRoot,...args],{encoding:'utf8',timeout:15000,maxBuffer:32*1024*1024}).trim();
+ requireThat(git(['rev-parse','--show-toplevel'])===repositoryRoot,'ARCH_REPOSITORY_CONFLICT','登记根不是实际 Git 根');
+ const source=manifest.source;
+ requireThat(source&&/^[a-f0-9]{40}$/.test(source.base_commit)&&Array.isArray(source.files)&&source.files.length&&Array.isArray(source.roots)&&source.roots.length,'ARCH_SOURCE_MISSING','源码基线缺固定提交、文件清单或根范围');
+ requireThat(git(['rev-parse',`${source.base_commit}^{commit}`])===source.base_commit,'ARCH_SOURCE_STALE','固定基础提交不可读');
+ requireThat(git(['remote','get-url','origin'])===registration.repository_url,'ARCH_REPOSITORY_CONFLICT','实际 origin 与登记来源不一致');
+ requireThat(git(['rev-parse','HEAD'])===source.base_commit,'ARCH_SOURCE_STALE','工作树 HEAD 与批准固定输入不一致');
+ same(source,baseline.source,'ARCH_SOURCE_CONFLICT','工程基线与观测的源码范围不一致');
+ requireThat(existingArchitectureDigest(source)===identity.source_digest,'ARCH_SOURCE_STALE','固定源码基线摘要不一致');
+ for(const ref of source.roots)if(ref!=='.')relative(ref);
+ const sourcePaths=source.files.map(x=>x.path);requireThat(new Set(sourcePaths).size===sourcePaths.length,'ARCH_SOURCE_INVALID','源码路径重复');
+ const prefix=registration.project_root==='.'?'':`${registration.project_root}/`;
+ const tree=git(['ls-tree','-r',source.base_commit]).split('\n').filter(Boolean).map(line=>{const [meta,ref]=line.split('\t');return{ref,blob:meta.split(' ')[2],mode:meta.split(' ')[0]};}).filter(x=>x.ref.startsWith(prefix)).map(x=>({...x,path:x.ref.slice(prefix.length)})).filter(x=>!excluded(x.path)&&source.roots.some(scope=>beneath(x.path,scope)));
+ requireThat(tree.every(x=>['100644','100755'].includes(x.mode)),'ARCH_SOURCE_INVALID','源码范围包含 gitlink 或 symlink，需单独登记');
+ same(sourcePaths.slice().sort(),tree.map(x=>x.path).sort(),'ARCH_SOURCE_INCOMPLETE','源码清单未覆盖声明范围的固定提交文件');
+ const treeMap=new Map(tree.map(x=>[x.path,x.blob]));
+ const changes=[];
+ for(const item of source.files){
+  relative(item.path);requireThat(digest(item.sha256),'ARCH_SOURCE_INVALID','源码摘要格式无效');
+  let bytes;
+  try { bytes=readFileSync(file(projectRoot,item.path)); } catch(error) { if(error.code==='ENOENT'){changes.push(item.path);continue;} throw error; }
+  const actual=sha(bytes);const baseBlob=treeMap.get(item.path);
+  requireThat(item.base_blob===baseBlob,'ARCH_SOURCE_STALE',`基础 Git blob 不一致: ${item.path}`);
+  const currentBlob=createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+  if(actual!==item.sha256){changes.push(item.path);continue;}
+  if(currentBlob!==baseBlob)requireThat(source.patches?.some(p=>p.path===item.path&&p.base_blob===baseBlob&&p.sha256===actual),'ARCH_SOURCE_UNDECLARED',`未登记基线补丁: ${item.path}`);
+ }
+ const observed=[...new Set(source.roots.flatMap(scope=>{ const entry=path.join(projectRoot,scope); try { const stat=lstatSync(entry); requireThat(!stat.isSymbolicLink(),'ARCH_PATH',`源码根出现 symlink: ${scope}`); return stat.isDirectory()?listFiles(projectRoot,scope==='.'?'':scope):[scope]; } catch(error) { if(error.code==='ENOENT')return [];throw error; } }))];
+ for(const ref of observed)if(!sourcePaths.includes(ref))changes.push(ref);
+ const units=manifest.build_units;
+ requireThat(Array.isArray(units)&&units.length&&units.every(u=>text(u.id)&&text(u.pom_ref)&&Array.isArray(u.roles)&&Array.isArray(u.depends_on)),'ARCH_BUILD_MISSING','缺少实际构建单元/角色/依赖');
+ same(units,baseline.build_units,'ARCH_BUILD_CONFLICT','三方构建单元映射不一致');
+ requireThat(existingArchitectureDigest(units)===identity.build_units_digest,'ARCH_BUILD_STALE','构建单元摘要不一致');
+ requireThat(new Set(units.map(u=>u.id)).size===units.length,'ARCH_BUILD_CONFLICT','构建单元重复');
+ const inspected=inspectMaven(projectRoot,units);const artifactMap=new Map(inspected.map((m,i)=>[m.artifact_id,units[i].id]));
+ for(const [i,u] of units.entries()){
+  requireThat(sourcePaths.includes(u.pom_ref),'ARCH_BUILD_CONFLICT',`POM未冻结: ${u.pom_ref}`);
+  requireThat(u.artifact_id===inspected[i].artifact_id,'ARCH_BUILD_CONFLICT',`artifactId不一致: ${u.id}`);
+  for(const module of inspected[i].modules){
+   requireThat(!module.includes('${'),'ARCH_BUILD_UNRESOLVED',`Maven module 路径尚未解析: ${u.id}`);
+   const child=path.posix.normalize(path.posix.join(path.posix.dirname(u.pom_ref),module,'pom.xml'));
+   relative(child); requireThat(units.some(unit=>unit.pom_ref===child),'ARCH_BUILD_INCOMPLETE',`实际 reactor 模块未登记: ${child}`);
+  }
+  const deps=[...new Set(inspected[i].dependencies.filter(a=>artifactMap.has(a)).map(a=>artifactMap.get(a)))].sort();
+  same([...u.depends_on].sort(),deps,'ARCH_BUILD_CONFLICT',`实际模块依赖不一致: ${u.id}`);
+ }
+ requireThat(Array.isArray(registration.allowed_write_paths)&&registration.allowed_write_paths.length,'ARCH_REGISTRATION_MISSING','登记缺少允许写范围');
+ for(const ref of registration.allowed_write_paths) if(ref!=='.')relative(ref);
+ requireThat(profile.required_roles.every(role=>units.some(u=>u.roles.includes(role))),'ARCH_BOUNDARY_MISSING','实际构建单元未覆盖架构责任');
+ requireThat(Array.isArray(baseline.boundary_scope)&&baseline.boundary_scope.length,'ARCH_BOUNDARY_MISSING','必须明确既有架构适用源码范围，不能推定整个混合仓同构');
+ baseline.boundary_scope.forEach(relative);
+ for(const unit of units)for(const role of unit.roles){
+  const refs=unit.role_paths?.[role];
+  requireThat(Array.isArray(refs)&&refs.length,'ARCH_BOUNDARY_MISSING',`缺少责任源码映射: ${unit.id}/${role}`);
+  for(const ref of refs){relative(ref);requireThat(sourcePaths.some(p=>beneath(p,ref))&&baseline.boundary_scope.some(scope=>beneath(ref,scope)),'ARCH_BOUNDARY_CONFLICT',`责任源码映射未在已冻结边界内: ${ref}`);}
+ }
+ requireThat(Array.isArray(baseline.verification_commands)&&baseline.verification_commands.length&&Array.isArray(registration.verification_commands),'ARCH_VERIFICATION_MISSING','缺少登记验证命令');
+ same(baseline.verification_commands,registration.verification_commands,'ARCH_VERIFICATION_CONFLICT','验证入口不一致');
+ const review=bound(root,baseline.boundary_review);
+ const rolesFile=path.join(root,'docs/agents/digital-human-roles.yaml');
+ const roles=parse(readFileSync(rolesFile));
+ validateApprovalRecord(review,{rolesDoc:roles,requireApproved:true,root});
+ requireThat(['check.architecture-reviewed','gate.technical-design-approved'].includes(review.gate_id)&&text(baseline.id)&&text(baseline.version),'ARCH_REVIEW_MISSING','需要架构边界审查');
+ const basis=existingArchitectureDigest(Object.fromEntries(Object.entries(baseline).filter(([k])=>k!=='boundary_review')));
+ requireThat(review.artifact_bindings?.some(x=>x.id===baseline.id&&x.version===baseline.version&&x.digest===basis),'ARCH_REVIEW_STALE','架构审查未绑定当前基线');
+ requireThat(text(review.principal_ref)&&review.principal_ref!==baseline.author,'ARCH_REVIEW_INVALID','起草者不能自审');
+ requireThat(text(baseline.author),'ARCH_REVIEW_INVALID','工程基线缺少起草者');
+ requireThat(Array.isArray(review.evidence_refs)&&review.evidence_refs.length,'ARCH_REVIEW_MISSING','缺少可读边界审查证据');
+ review.evidence_refs.forEach(ref=>file(root,ref));
+ requireThat(baseline.databases?.verification&&baseline.databases?.production,'ARCH_DATABASE_MISSING','需分别声明验证与生产数据库状态');
+ for(const [kind,record] of Object.entries(baseline.databases)){
+  requireThat(['declared','verified','unknown','not-applicable'].includes(record.status),'ARCH_DATABASE_INVALID',`${kind} 数据库状态无效`);
+  if(record.status==='verified'){
+   requireThat(text(record.engine)&&text(record.version)&&text(record.environment_id),'ARCH_DATABASE_INVALID','数据库验证未绑定环境和版本');
+   const evidence=bound(root,record.verification);requireThat(evidence.source_digest===identity.source_digest&&evidence.engine===record.engine&&evidence.version===record.version&&evidence.environment_id===record.environment_id,'ARCH_DATABASE_STALE','实库验证与声明/源码不一致');
+   requireThat(Array.isArray(evidence.results)&&evidence.results.length&&evidence.results.every(r=>text(r.command)&&r.exit_code===0&&Number.isFinite(Date.parse(r.executed_at))&&Array.isArray(r.evidence)&&r.evidence.length),'ARCH_DATABASE_UNVERIFIED','不能用数据库声明代替实际执行');
+   evidence.results.forEach(r=>r.evidence.forEach(b=>{requireThat(text(b?.ref)&&digest(b.digest),'ARCH_DATABASE_UNVERIFIED','缺少原始执行日志');requireThat(sha(readFileSync(file(root,b.ref)))===b.digest,'ARCH_DATABASE_STALE','实际执行日志摘要不一致');}));
+  }
+ }
+ if(changes.length){
+  requireThat(execution,'ARCH_SOURCE_STALE',`固定源码改变: ${changes.join(', ')}`);
+  const permission=assertApprovedExecutionContext(execution,{root,architectureIdentity:identity,architectureEvidence:bindings});
+  const allowed=permission.allowed_write_paths.map(x=>{if(path.isAbsolute(x)){const rel=path.relative(projectRoot,x).split(path.sep).join('/');return rel==='.'||rel===''?'.':relative(rel);}return x==='.'?'.':relative(x);});
+  requireThat(changes.every(ref=>allowed.some(scope=>beneath(ref,scope))&&registration.allowed_write_paths.some(scope=>beneath(ref,scope))),'ARCH_SOURCE_OUT_OF_SCOPE','输出增量超出批准写范围');
+ }
+ return {source_kind:'existing-registration',bindings:structuredClone(bindings),project_root:projectRoot,source_digest:identity.source_digest,build_units_digest:identity.build_units_digest,changed_files:[...new Set(changes)].sort(),profile_maturity:profile.maturity};
+}

package/template/scripts/lib/existing-ui-baseline.mjs

@@ -0,0 +1,84 @@
+import { readFileSync, statSync } from 'node:fs';
+import { ensure, hash, digest, read, safe, files, schema, treeDigest } from './strategic-handoff-io.mjs';
+
+// This is an observation bundle, not a prototype or an approval generator.
+export function validateExistingUiBaseline(data, { bundleRoot } = {}) {
+  const errors=[];
+  try {
+    schema(data,'docs/process/schemas/existing-ui-baseline.schema.json');
+    ensure(bundleRoot,'existing-ui-baseline 需要原始 bundleRoot');
+    const consumed=new Set(['existing-ui-baseline.json']);
+    const allFiles=files(bundleRoot);
+    ensure(allFiles.length<=20000&&allFiles.reduce((total,ref)=>total+statSync(safe(bundleRoot,ref)).size,0)<=100*1024*1024,'existing-ui-baseline 文件数量或包大小超限');
+    const bound=binding=>{
+      consumed.add(binding.ref);
+      const bytes=readFileSync(safe(bundleRoot,binding.ref));
+      ensure(bytes.length>0&&hash(bytes)===binding.digest,`existing-ui-baseline 原始证据摘要不一致: ${binding.ref}`);
+      return bytes;
+    };
+    const document=binding=>{bound(binding);return read(safe(bundleRoot,binding.ref));};
+    const source=data.source, manifest=document(source.manifest);
+    ensure(source.digest===treeDigest(bundleRoot,source.root_ref),'existing-ui-baseline 固定源码摘要不一致');
+    bound(source.lock);
+    ensure(source.lock.ref.startsWith(`${source.root_ref}/`),'existing-ui-baseline 锁文件必须属于固定源码');
+    ensure(manifest.schema_version===1&&manifest.kind==='existing-ui-source-observation','existing-ui-baseline 源码观测 manifest 类型无效');
+    for(const key of ['repository_id','project_id','source_commit'])ensure(manifest[key]===source[key],`existing-ui-baseline 源码身份不一致: ${key}`);
+    ensure(manifest.source_digest===source.digest&&Array.isArray(manifest.files),'existing-ui-baseline 源码观测摘要不一致');
+    files(bundleRoot,source.root_ref).forEach(ref=>consumed.add(ref));
+    const actual=files(bundleRoot,source.root_ref).map(ref=>({path:ref.slice(source.root_ref.length+1),digest:hash(readFileSync(safe(bundleRoot,ref)))}));
+    ensure(digest([...manifest.files].sort((a,b)=>a.path.localeCompare(b.path)))===digest(actual.sort((a,b)=>a.path.localeCompare(b.path))),'existing-ui-baseline 观测文件集与实际源码不一致');
+    let routePrefix='';
+    if(data.api_route_mapping) {
+      const mapping=data.api_route_mapping;
+      for(const binding of [mapping.config,mapping.environment])ensure(binding.ref.startsWith(`${source.root_ref}/`)&&actual.some(file=>`${source.root_ref}/${file.path}`===binding.ref),'existing-ui-baseline 代理映射必须绑定固定源码');
+      const config=bound(mapping.config).toString('utf8'),environment=bound(mapping.environment).toString('utf8');
+      // A deliberately narrow existing Vite convention. Unrecognized rewrites need review;
+      // never execute a package's JavaScript to obtain a routing assertion.
+      ensure(/^\s*const apiBase = env\.VITE_API_BASE_URL \|\| ['"]\/api['"]\s*;?\s*$/m.test(config)
+        && /proxy:\s*\{\s*\[apiBase\]:\s*\{\s*target:\s*proxyTarget,\s*changeOrigin:\s*true,\s*rewrite:\s*\(path\)\s*=>\s*path\.replace\(new RegExp\(`\^\$\{apiBase\}`\),\s*''\)\s*\}/.test(config),'existing-ui-baseline 不支持或缺少固定 Vite prefix rewrite');
+      const values=environment.split(/\r?\n/).filter(line=>/^\s*VITE_API_BASE_URL\s*=/.test(line));
+      ensure(values.length===1&&values[0].split('=').slice(1).join('=').trim()===mapping.prefix,'existing-ui-baseline 代理 prefix 与原始环境配置不一致');
+      routePrefix=mapping.prefix;
+    }
+    const build=document(data.build),capture=document(data.capture);
+    const openapi=document(data.openapi);bound(data.replay);
+    ensure(/^3\.1\.[0-9]+$/.test(openapi.openapi)&&openapi.paths,'existing-ui-baseline 需要 OpenAPI 3.1 原始接口');
+    for(const [label,record] of [['build',build],['capture',capture]]) {
+      ensure(record.schema_version===1&&record.source_commit===source.source_commit&&record.source_digest===source.digest,`existing-ui-baseline ${label} 未绑定当前源码`);
+      ensure(record.exit_code===0&&typeof record.command==='string'&&record.command.trim()&&Number.isFinite(Date.parse(record.executed_at)),`existing-ui-baseline ${label} 缺少成功执行记录`);
+      ensure(Array.isArray(record.evidence)&&record.evidence.length,`existing-ui-baseline ${label} 缺少原始日志`);record.evidence.forEach(bound);
+    }
+    ensure(build.lock_digest===source.lock.digest,'existing-ui-baseline 构建锁文件不一致');
+    ensure(build.output?.ref&&build.output.digest===treeDigest(bundleRoot,build.output.ref),'existing-ui-baseline 构建输出不一致');
+    files(bundleRoot,build.output.ref).forEach(ref=>consumed.add(ref));
+    ensure(capture.build_digest===data.build.digest&&capture.openapi_digest===data.openapi.digest,'existing-ui-baseline 截图运行与构建/API 不一致');
+    ensure(capture.ui_change==='none'&&Array.isArray(capture.cases),'existing-ui-baseline 不支持 UI 改动');
+    const ids=new Set();
+    for(const item of data.cases) {
+      ensure(!ids.has(item.case_id),`existing-ui-baseline case_id 重复: ${item.case_id}`);ids.add(item.case_id);
+      for(const ref of item.source_refs)ensure(ref.startsWith(`${source.root_ref}/`)&&actual.some(file=>`${source.root_ref}/${file.path}`===ref),`existing-ui-baseline 用例源码悬空: ${ref}`);
+      bound(item.actions);const api=document(item.api),image=bound(item.image);
+      ensure(image.length<=5*1024*1024,'existing-ui-baseline 单张截图超过 5 MiB');
+      ensure(image.length>=24&&image.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10]))&&image.toString('ascii',12,16)==='IHDR','existing-ui-baseline 截图不是 PNG');
+      ensure(image.readUInt32BE(16)===item.viewport.width&&image.readUInt32BE(20)===item.viewport.height,'existing-ui-baseline 截图与 viewport 不一致');
+      ensure(api.schema_version===1&&api.case_id===item.case_id&&api.openapi_digest===data.openapi.digest&&api.source_digest===source.digest&&api.build_digest===data.build.digest,'existing-ui-baseline API 证据来源不一致');
+      ensure(Array.isArray(api.exchanges)&&api.exchanges.length,'existing-ui-baseline 缺少真实 API 请求/响应');
+      for(const exchange of api.exchanges) {
+        ensure(typeof exchange.operation_id==='string'&&exchange.operation_id&&typeof exchange.method==='string'&&/^https?:\/\//.test(exchange.url)&&Number.isFinite(Date.parse(exchange.executed_at))&&Number.isInteger(exchange.status)&&exchange.status>=100&&exchange.status<=599,'existing-ui-baseline API 交换记录无效');
+        const operation=Object.entries(openapi.paths).flatMap(([route,item])=>Object.entries(item).filter(([method,value])=>value?.operationId===exchange.operation_id&&method.toUpperCase()===exchange.method.toUpperCase()).map(()=>route));
+        ensure(operation.length===1,'existing-ui-baseline API operation 与冻结接口不一致');
+        const routePattern=new RegExp(`^${operation[0].split('/').map(part=>/^\{[^}]+\}$/.test(part)?'[^/]+':part.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')).join('/')}$`);
+        const observedPath=new URL(exchange.url).pathname;
+        ensure(!routePrefix||observedPath.startsWith(`${routePrefix}/`),'existing-ui-baseline API URL 与代理 prefix 不一致');
+        ensure(routePattern.test(routePrefix?observedPath.slice(routePrefix.length):observedPath),'existing-ui-baseline API URL 与冻结接口路径不一致');
+        bound(exchange.request);bound(exchange.response);
+      }
+      const observed=capture.cases.filter(entry=>entry.case_id===item.case_id);
+      ensure(observed.length===1,'existing-ui-baseline 缺少或重复 capture case');
+      for(const key of ['route','state','viewport','source_refs','actions','image','api'])ensure(digest(observed[0][key])===digest(item[key]),`existing-ui-baseline 截图动作绑定不一致: ${item.case_id}/${key}`);
+    }
+    ensure(capture.cases.length===ids.size,'existing-ui-baseline capture 含未登记用例');
+    ensure(allFiles.every(ref=>consumed.has(ref)),'existing-ui-baseline 包含未绑定原始文件');
+  } catch(error) { errors.push(error.message); }
+  return {errors};
+}

package/template/scripts/lib/frontend-delivery.mjs

@@ -1,3 +1,4 @@
+import { uiBaselineRef, uiBaselineCaseIds, uiBaselineKind, hasConsumerRoutes } from './ui-baseline.mjs';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -6,17 +7,18 @@ import { openBundle } from './strategic-handoff.mjs';
 import { verifyConsumption } from './strategic-handoff-consumption.mjs';
 import { read, safe, ensure, hash, schema, project, ROOT } from './strategic-handoff-io.mjs';
 
-const ACCEPTANCE_SCHEMAS=new Map([[1,'docs/process/schemas/frontend-delivery-acceptance-v1.schema.json'],[2,'docs/process/schemas/frontend-delivery-acceptance.schema.json']]);
+const ACCEPTANCE_SCHEMAS=new Map([[1,'docs/process/schemas/frontend-delivery-acceptance-v1.schema.json'],[2,'docs/process/schemas/frontend-delivery-acceptance.schema.json'],[3,'docs/process/schemas/frontend-delivery-acceptance-v3.schema.json']]);
 
 function acceptanceSchema(version) {
-  ensure(ACCEPTANCE_SCHEMAS.has(version),`Frontend Delivery Acceptance 未知 schema_version: ${String(version)}；支持版本: 1, 2；新接收请迁移到 2`);
+  ensure(ACCEPTANCE_SCHEMAS.has(version),`Frontend Delivery Acceptance 未知 schema_version: ${String(version)}；支持版本: 1, 2, 3；既有 UI 接收请使用 3`);
   return ACCEPTANCE_SCHEMAS.get(version);
 }
 
-export async function verifyFrontendStrategicPreflight({root=process.cwd(),preflightRef,expectedDigest}={}) {
+export async function verifyFrontendStrategicPreflight({root=process.cwd(),preflightRef,expectedDigest,readOnly=false}={}) {
   project(root);
   const file=safe(root,preflightRef),preflight=read(file);
-  schema(preflight,'docs/process/schemas/frontend-strategic-preflight.schema.json');
+  ensure([1,2].includes(preflight.schema_version),'Frontend Strategic Preflight 未知 schema_version');
+  schema(preflight,preflight.schema_version===2?'docs/process/schemas/frontend-strategic-preflight-v2.schema.json':'docs/process/schemas/frontend-strategic-preflight.schema.json');
   const preflightDigest=hash(readFileSync(file));
   if(expectedDigest)ensure(expectedDigest===preflightDigest,'前端战略预检摘要已变化，需重编译合同');
   ensure(preflight.status==='verified','前端战略预检尚未 verified');
@@ -30,19 +32,21 @@ export async function verifyFrontendStrategicPreflight({root=process.cwd(),prefl
   const reconciliation=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,preflight.context_reconciliation_ref)],{encoding:'utf8'});
   ensure(reconciliation.status===0,`前端战略预检 Context Reconciliation 未通过: ${reconciliation.error?.message||reconciliation.stderr}`);
   return openBundle(safe(root,receipt.package_ref),bundle=>{
-    ensure(bundle.handoff.schema_version===4&&bundle.manifest.bundle_digest===receipt.bundle_digest,'前端战略预检必须绑定 Handoff v4 当前包');
+    ensure(hasConsumerRoutes(bundle.handoff)&&bundle.manifest.bundle_digest===receipt.bundle_digest,'前端战略预检必须绑定支持消费者路由的当前交接包');
     const frontendRoute=bundle.handoff.consumer_routes.find(item=>item.route_id===preflight.route_id&&item.capability==='frontend-engineering-design');
     const backendRoute=bundle.handoff.consumer_routes.find(item=>item.capability==='backend-technical-design');
     ensure(frontendRoute&&frontendRoute.activation!=='not-applicable','前端路由未启用');
     const known=[...bundle.indexes.rules.map(item=>item.rule_id),...bundle.indexes.scenarios.filter(item=>item.critical).map(item=>item.scenario_id)].sort();
     ensure(JSON.stringify([...preflight.source_rule_refs].sort())===JSON.stringify(known),'前端战略预检未完整绑定源规则/关键场景');
-    const expectedVisual=`${base}/package/payload/files/${bundle.handoff.source.visual_baseline_ref.persisted_ref}/${bundle.handoff.source.visual_baseline_ref.manifest_ref}`;
-    ensure(preflight.visual_baseline_ref===expectedVisual,'前端战略预检 Visual Baseline 引用不一致');
+    ensure((preflight.schema_version===2)===(bundle.handoff.schema_version===5),'前端预检与 Handoff 协议版本不匹配，禁止降级');
+    if(preflight.schema_version===2)ensure(preflight.ui_baseline_kind===uiBaselineKind(bundle.handoff),'前端预检基线类型不一致');
+    const expectedVisual=`${base}/package/payload/files/${uiBaselineRef(bundle.handoff).persisted_ref}/${uiBaselineRef(bundle.handoff).manifest_ref}`;
+    ensure((preflight.schema_version===2?preflight.ui_baseline_ref:preflight.visual_baseline_ref)===expectedVisual,'前端战略预检 Visual Baseline 引用不一致');
     const expectedMode=backendRoute.activation==='not-applicable'?'not-applicable':'required';
     ensure(preflight.backend_dependency.mode===expectedMode&&preflight.backend_dependency.route_id===backendRoute.route_id,'前端战略预检后端依赖与消费者路由不一致');
     if(expectedMode==='not-applicable')ensure(preflight.backend_dependency.reason===backendRoute.reason&&JSON.stringify(preflight.backend_dependency.impact_refs)===JSON.stringify(backendRoute.impact_refs)&&JSON.stringify(preflight.backend_dependency.evidence_refs)===JSON.stringify(backendRoute.evidence_refs),'backend-not-applicable 依据与战略路由不一致');
-    return {result:'preflight-verified',ready_for_agent:false,preflight_ref:preflightRef,preflight_digest:preflightDigest,strategic_bundle_digest:receipt.bundle_digest,backend_dependency:expectedMode,next_action:'prepare-frontend-engineering-design-draft'};
-  });
+    return {result:'preflight-verified',ready_for_agent:false,preflight_ref:preflightRef,preflight_digest:preflightDigest,strategic_bundle_digest:receipt.bundle_digest,ui_baseline_kind:uiBaselineKind(bundle.handoff),preflight_schema_version:preflight.schema_version,backend_dependency:expectedMode,next_action:'prepare-frontend-engineering-design-draft'};
+  },{readOnly});
 }
 
 function pointer(value, ref) {
@@ -79,8 +83,10 @@ export async function verifyFrontendDelivery({root=process.cwd(),acceptanceRef,s
   const acceptanceDigest=hash(readFileSync(file));
   if(expectedDigest)ensure(expectedDigest===acceptanceDigest,'前端接收记录摘要已变化，需重编译合同');
   ensure(sliceRef&&acceptance.slice_id===sliceRef,'前端接收记录与执行切片不匹配');
-  if(acceptance.schema_version===2) {
+  if(acceptance.schema_version>=2) {
     const preflight=await verifyFrontendStrategicPreflight({root,preflightRef:acceptance.strategic_preflight.ref,expectedDigest:acceptance.strategic_preflight.digest});
+    ensure((acceptance.schema_version===3)===(preflight.preflight_schema_version===2),'前端接收与预检协议版本不匹配，禁止降级');
+    if(acceptance.schema_version===3)ensure(acceptance.ui_baseline_kind===preflight.ui_baseline_kind,'前端接收基线类型不一致');
     ensure(preflight.strategic_bundle_digest===acceptance.strategic_handoff.bundle_digest,'前端接收与战略预检版本不一致');
     if(acceptance.backend_dependency.mode==='not-applicable') {
       ensure(!acceptance.backend_delivery,'backend-not-applicable 不得绑定后端交付收据');
@@ -88,13 +94,14 @@ export async function verifyFrontendDelivery({root=process.cwd(),acceptanceRef,s
       ensure(strategic.result==='verified',`战略承接阻断: ${JSON.stringify(strategic.issues)}`);
       const strategicReceipt=read(safe(root,acceptance.strategic_handoff.import_receipt_ref));
       return openBundle(safe(root,strategicReceipt.package_ref),bundle=>{
-        const visualCases=bundle.handoff.source.visual_baseline_ref.case_ids;
+        ensure(acceptance.schema_version===3||bundle.handoff.schema_version!==5,'Handoff v5 必须使用前端接收 v3');
+        const visualCases=uiBaselineCaseIds(bundle.handoff);
         const sourceIds=new Set([...bundle.indexes.rules.map(item=>item.rule_id),...bundle.indexes.scenarios.filter(item=>item.critical).map(item=>item.scenario_id)]);
         const ids=acceptance.frontend_cases.map(item=>item.case_id);ensure(new Set(ids).size===ids.length,'前端验收用例 ID 重复');
         for(const item of acceptance.frontend_cases){
           ensure(item.operation_ids.length===0,'backend-not-applicable 前端用例不得绑定 operation_ids');
           ensure(item.source_ids.every(id=>sourceIds.has(id)),'前端用例引用未知规则/场景');
-          ensure(item.visual_case_ids.every(id=>visualCases.includes(id)),'前端用例视觉基线悬空');
+          ensure((acceptance.schema_version===3?item.baseline_case_ids:item.visual_case_ids).every(id=>visualCases.includes(id)),'前端用例视觉基线悬空');
           const evidence=readFileSync(safe(root,item.evidence_ref));ensure(evidence.length>0&&hash(evidence)===item.evidence_digest,'前端承接用例说明为空或摘要漂移');
         }
         return {result:'inputs-verified',ready_for_agent:false,slice_id:sliceRef,acceptance_ref:acceptanceRef,acceptance_digest:acceptanceDigest,strategic_bundle_digest:strategic.consumed_bundle_digest,backend_dependency:'not-applicable',next_action:'prepare-or-revalidate-frontend-plan-and-slice-contract'};
@@ -117,12 +124,13 @@ export async function verifyFrontendDelivery({root=process.cwd(),acceptanceRef,s
     const ids=acceptance.frontend_cases.map(item=>item.case_id);
     ensure(new Set(ids).size===ids.length,'前端验收用例 ID 重复');
     await openBundle(safe(backend.source,delivery.strategic_bundle_ref),bundle=>{
-      const visualCases=bundle.handoff.source.visual_baseline_ref.case_ids;
+      ensure(acceptance.schema_version===3||bundle.handoff.schema_version!==5,'Handoff v5 必须使用前端接收 v3');
+      const visualCases=uiBaselineCaseIds(bundle.handoff);
       for(const item of acceptance.frontend_cases) {
-        if(acceptance.schema_version===2)ensure(item.operation_ids.length>0,'有后端依赖时前端用例必须绑定已交付 operation_ids');
+        if(acceptance.schema_version>=2)ensure(item.operation_ids.length>0,'有后端依赖时前端用例必须绑定已交付 operation_ids');
         ensure(item.operation_ids.every(id=>delivery.scope.operation_ids.includes(id)),'前端用例依赖未交付接口');
         ensure(item.source_ids.every(id=>delivery.scope.source_ids.includes(id)),'前端用例依赖未交付规则/场景');
-        ensure(item.visual_case_ids.every(id=>visualCases.includes(id)),'前端用例视觉基线悬空');
+        ensure((acceptance.schema_version===3?item.baseline_case_ids:item.visual_case_ids).every(id=>visualCases.includes(id)),'前端用例视觉基线悬空');
         const evidence=readFileSync(safe(root,item.evidence_ref));
         ensure(evidence.length>0&&hash(evidence)===item.evidence_digest,'前端承接用例说明为空或摘要漂移');
       }

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -1,3 +1,4 @@
+import { createApprovedExecutionContext, createApprovedRecompilationContext, assertApprovedExecutionContext } from './approved-execution-context.mjs';
 import { enforceTechnicalDesign } from './technical-design-boundary.mjs';
 import { enforceHarnessSkillScope } from "./harness-execution-scope.mjs";
 import { createHash } from "node:crypto";
@@ -6,7 +7,7 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { DEFAULT_REGISTRY, loadSkillRegistry } from "./skill-registry.mjs";
 import { ROOT } from "./skill-supply-chain.mjs";
-import { architectureDigest, assertArchitectureAgreement, validateArchitectureIdentity } from "./backend-architecture.mjs";
+import { architectureDigest, assertArchitectureAgreement, validateArchitectureIdentity, verifyArchitectureEvidence } from "./backend-architecture.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
 
 export const DEFAULT_COMPILER_CONTRACT = path.join(
@@ -65,12 +66,14 @@ export function compileImplementationContract({
   compilerContractDigest,
   architecture_identity,
   architecture_evidence,
+  approved_slice,
   root = ROOT,
   slice_id,
   frontend_delivery,
   technical_design
 }) {
   assertV2(registry, compilerContract);
+  const recompilationExecution=approved_slice?createApprovedRecompilationContext(approved_slice,{root}):undefined;
   const deliveryInput = enforceFrontendDelivery({ slice_id, frontend_delivery }, { root });
   if (!Array.isArray(recipeIds) || !Array.isArray(requiredCapabilities) || !Array.isArray(conditions)) {
     fail("recipeIds、requiredCapabilities 与 conditions 必须是数组");
@@ -89,11 +92,11 @@ export function compileImplementationContract({
   if (architectural || architecture_identity) {
     architectureProfile = validateArchitectureIdentity(architecture_identity, registry);
     if (!architecture_evidence?.engineering_baseline || !architecture_evidence?.repository_registration || !architecture_evidence?.manifest) fail("缺少工程基线、仓库登记或 Manifest 架构证据");
-    assertArchitectureAgreement(architecture_identity, architecture_evidence, registry);
+    verifyArchitectureEvidence(architecture_identity, architecture_evidence, { root, registry, execution:recompilationExecution });
     for (const recipe of orderedRecipes) if (recipe.architecture_family && recipe.architecture_family !== architecture_identity.architecture_family) fail(`Recipe ${recipe.id} 与架构族不匹配`);
   }
 
-  enforceTechnicalDesign({ technical_design, conditions, architecture_identity, slice_id }, { root });
+  enforceTechnicalDesign({ technical_design, conditions, architecture_identity, slice_id }, { root, execution:recompilationExecution });
 
   const capabilitySources = new Map();
   const orderedCapabilities = [];
@@ -175,6 +178,7 @@ export function compileImplementationContract({
     ...(architecture_identity ? {
       architecture_identity: structuredClone(architecture_identity),
       architecture_identity_digest: architectureDigest(architecture_identity),
+      ...(architecture_identity.schema_version === 2 ? { architecture_evidence: structuredClone(architecture_evidence) } : {}),
       profile_maturity: architectureProfile.maturity,
       readiness_blockers: architectureProfile.maturity === "supported" ? [] : ["backend-profile-not-supported"],
       skill_profiles: Object.fromEntries(orderedSkills.map((skill) => [skill, architecture_identity.architecture_profile]))
@@ -202,12 +206,17 @@ export function compileDefaultImplementationContract(input = {}) {
   });
 }
 
-export function evaluateContractFreshness(contract, { registry, compilerContract, root = ROOT }) {
+export function evaluateContractFreshness(contract, { registry, compilerContract, root = ROOT, approved_slice, readOnly = false }, execution) {
   assertV2(registry, compilerContract);
   if (contract?.schema_version !== 2) fail("Slice Implementation Contract schema v1 已停止支持；必须重新编译 v2 合同");
   const resolution = contract.resolution ?? contract;
   const reasons = [];
-  try { enforceTechnicalDesign({ ...resolution, slice_id: contract.slice_id ?? resolution.slice_id }, { root }); }
+  let trustedExecution;
+  try {
+    trustedExecution=approved_slice?createApprovedExecutionContext(approved_slice,{root,contract}):execution;
+    if(trustedExecution)assertApprovedExecutionContext(trustedExecution,{root,contract});
+  } catch(error) { reasons.push(error.code||'EXECUTION_APPROVAL_INVALID');trustedExecution=undefined; }
+  try { enforceTechnicalDesign({ ...resolution, slice_id: contract.slice_id ?? resolution.slice_id }, { root,execution:trustedExecution,readOnly }); }
   catch { reasons.push("technical-design-stale-or-unavailable"); }
   try { enforceFrontendDelivery(contract, { root }); }
   catch { reasons.push("frontend-delivery-stale-or-unavailable"); }
@@ -216,6 +225,10 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
   if (resolution.architecture_identity) {
     try { validateArchitectureIdentity(resolution.architecture_identity, registry); }
     catch { reasons.push("architecture-identity-invalid"); }
+    if (resolution.architecture_identity.schema_version === 2) {
+      try { verifyArchitectureEvidence(resolution.architecture_identity, resolution.architecture_evidence, { root, registry, execution:trustedExecution }); }
+      catch (error) { reasons.push(error.code ?? "architecture-evidence-stale-or-unavailable"); }
+    }
     if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-digest-changed");
   }
   return { freshness: reasons.length ? "stale" : "current", reasons };
@@ -225,6 +238,7 @@ export function validateExecutionResult(result, contract, current) {
   if (result?.schema_version !== 2) fail("YSS Skill Execution Result schema v1 已停止支持；请迁移到 v2");
   if (contract?.schema_version !== 2) fail("Slice Implementation Contract schema v1 已停止支持；必须重新编译 v2 合同");
   if (!EXECUTION_STATUSES.has(result.status)) fail(`未知 execution result status: ${result.status}`);
+  if(contract.resolution?.architecture_identity?.schema_version===2&&!current?.approved_slice)return {status:'stale',blockers:['EXECUTION_APPROVAL_REQUIRED']};
   const freshness = evaluateContractFreshness(contract, current);
   if (freshness.freshness === "stale") return { status: "stale", blockers: freshness.reasons };
   const consumed = result.consumed_contract ?? {};

package/template/scripts/lib/json-schema.mjs

@@ -9,7 +9,15 @@ import traceback
 from jsonschema import Draft202012Validator, FormatChecker
 validators = {}
 results = []
-for item in json.load(sys.stdin):
+expected_bytes = int(sys.argv[1])
+payload = sys.stdin.buffer.read(expected_bytes)
+if len(payload) != expected_bytes:
+    raise ValueError(f"JSON_SCHEMA_PROTOCOL: truncated input frame: expected {expected_bytes} bytes, received {len(payload)}")
+try:
+    jobs = json.loads(payload.decode('utf-8'))
+except (UnicodeDecodeError, json.JSONDecodeError) as error:
+    raise ValueError(f"JSON_SCHEMA_PROTOCOL: invalid UTF-8 JSON input frame: {error}") from error
+for item in jobs:
     try:
         key = (item['schemaPath'], item['formatChecker'])
         if key not in validators:
@@ -29,7 +37,8 @@ json.dump(results, sys.stdout)
 `;
 
 /** One immutable validation phase, never a cache of successful work units. */
-export function validateJsonSchemas(items, { cwd = process.cwd() } = {}) {
+export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30000 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new TypeError("schema timeoutMs 必须是正整数毫秒数");
   if (!Array.isArray(items)) throw new TypeError("schema batch 必须是数组");
   if (!items.length) return [];
   const jobs = items.map(({ value, schemaPath, formatChecker = true, errorStyle = "compact", label = "JSON Schema" }) => {
@@ -38,9 +47,15 @@ export function validateJsonSchemas(items, { cwd = process.cwd() } = {}) {
     if (!["compact", "verbose"].includes(errorStyle)) throw new TypeError(`未知 schema errorStyle: ${errorStyle}`);
     return { value, schemaPath: effectiveSchema, formatChecker, errorStyle };
   });
-  const result = spawnSync("python3", ["-c", validator], { cwd, encoding: "utf8", input: JSON.stringify(jobs), maxBuffer: 16 * 1024 * 1024 });
+  // readall waits for EOF even after the complete JSON has arrived. A known UTF-8
+  // byte frame lets the validator finish when a transport keeps its write end open.
+  const input = Buffer.from(JSON.stringify(jobs), "utf8");
+  const result = spawnSync("python3", ["-c", validator, String(input.length)], { cwd, encoding: "utf8", input, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  if (result.error?.code === "ETIMEDOUT") throw new TypeError(`JSON_SCHEMA_TIMEOUT: schema validation exceeded ${timeoutMs}ms`);
   if (result.error || result.status !== 0) throw new TypeError(result.error?.message || `${result.stdout}${result.stderr}`.trim());
-  const results = JSON.parse(result.stdout);
+  let results;
+  try { results = JSON.parse(result.stdout); } catch { throw new TypeError("JSON_SCHEMA_PROTOCOL: validator returned invalid JSON"); }
+  if (!Array.isArray(results) || results.some(item => !item || typeof item.valid !== "boolean" || typeof item.error !== "string")) throw new TypeError("JSON_SCHEMA_PROTOCOL: validator returned invalid result records");
   if (results.length !== jobs.length) throw new TypeError("schema batch 返回数量不匹配");
   return results;
 }

package/template/scripts/lib/legacy-backend-scaffold-audit.mjs

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const normalizedDigest = (value) => String(value ?? "").replace(/^sha256:/, "");
+
+async function collectFiles(root) {
+  const files = [];
+  async function visit(directory) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      if ([".git", "target", "node_modules"].includes(entry.name)) continue;
+      const target = path.join(directory, entry.name);
+      const relative = path.relative(root, target).split(path.sep).join("/");
+      if (entry.isDirectory()) await visit(target);
+      else files.push({ relative, target, symlink: entry.isSymbolicLink() });
+    }
+  }
+  await visit(root);
+  return files;
+}
+
+function isBusinessFile(relative, manifest) {
+  if (relative === manifest.bootstrap_main_source || /(^|\/)package-info\.java$/.test(relative)) return false;
+  return /(^|\/)src\/(main|test)\/java\/.+\.java$/.test(relative)
+    || /(^|\/)src\/main\/resources\/.+\.(sql|xml|ya?ml|properties)$/.test(relative)
+    || /(^|\/)(db|mapper|repository|controller|domain)(\/|$)/i.test(relative)
+    || /(^|\/)(Controller|Repository|Mapper|Aggregate|Entity)\.java$/i.test(relative);
+}
+
+export async function auditLegacyBackendScaffold(projectRoot, { manifestRef = ".yss/scaffold-generation.json" } = {}) {
+  const root = path.resolve(projectRoot);
+  const manifestFile = path.resolve(root, manifestRef);
+  const relativeManifest = path.relative(root, manifestFile);
+  if (relativeManifest.startsWith("..") || path.isAbsolute(relativeManifest)) throw new TypeError("Manifest 必须位于项目根内");
+  const manifestBytes = await readFile(manifestFile).catch(() => { throw new TypeError(`Manifest 不可读取: ${manifestRef}`); });
+  let manifest;
+  try { manifest = JSON.parse(manifestBytes); } catch { throw new TypeError("Manifest 必须是 JSON 对象"); }
+  if (manifest?.schema_version !== 3) throw new TypeError("恢复审计只接受历史 v3 Manifest");
+  if (!Array.isArray(manifest?.ownership?.generated_files)) throw new TypeError("历史 v3 Manifest 缺少 ownership.generated_files");
+
+  const generated = new Map(manifest.ownership.generated_files.map((entry) => [entry.path, entry]));
+  const generatedFileDrift = [];
+  for (const [relative, entry] of generated) {
+    const target = path.resolve(root, relative);
+    const inside = path.relative(root, target);
+    if (inside.startsWith("..") || path.isAbsolute(inside)) {
+      generatedFileDrift.push({ path: relative, reason: "path-outside-project" });
+      continue;
+    }
+    try {
+      const info = await lstat(target);
+      if (!info.isFile()) generatedFileDrift.push({ path: relative, reason: "not-a-regular-file" });
+      else {
+        const actual = sha256(await readFile(target));
+        if (actual !== normalizedDigest(entry.sha256)) generatedFileDrift.push({ path: relative, reason: "digest-drift", expected: normalizedDigest(entry.sha256), actual });
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") generatedFileDrift.push({ path: relative, reason: "missing" });
+      else throw error;
+    }
+  }
+
+  const files = await collectFiles(root);
+  const unownedFiles = files.map((entry) => entry.relative).filter((relative) => relative !== manifestRef && !generated.has(relative));
+  const businessFiles = files
+    .filter((entry) => entry.symlink || (unownedFiles.includes(entry.relative) && isBusinessFile(entry.relative, manifest)))
+    .map((entry) => entry.relative);
+  const premature = businessFiles.length > 0;
+  const state = premature ? "premature-implementation-detected" : generatedFileDrift.length > 0 ? "generated-file-drift" : "unchanged-mechanical-scaffold";
+  return {
+    schema_version: 1,
+    kind: "legacy-backend-scaffold-ownership-audit",
+    status: state === "unchanged-mechanical-scaffold" ? "reconcilable" : "blocked",
+    manifest_ref: manifestRef,
+    manifest_digest: `sha256:${sha256(manifestBytes)}`,
+    manifest_schema_version: 3,
+    ownership_state: state,
+    premature_implementation: premature,
+    generated_file_drift: generatedFileDrift,
+    business_files: businessFiles,
+    unowned_files: unownedFiles,
+    recovery_requirements: state === "unchanged-mechanical-scaffold"
+      ? ["approved-current-technical-design", "data-architecture-decision", "gate.engineering-contract-approved", "recovery-approval"]
+      : ["preserve-all-files", "design-reconciliation", "difference-review", "current-user-approval"],
+  };
+}