create-yss-spec 3.3.8 → 3.4.3

package/template/scripts/lib/slice-contract-preparation.mjs

@@ -0,0 +1,257 @@
+import {sliceRepositories} from './slice-repositories.mjs';
+import { sliceCheckApplicability } from './slice-applicability.mjs';
+import path from 'node:path';
+import fs from 'node:fs';
+import { stringify } from '../vendor/yaml.mjs';
+import { safe, hash, digest, write } from './strategic-handoff-io.mjs';
+import { compileDefaultImplementationContract, loadCompilerContract } from './implementation-contract-compiler.mjs';
+import { normalizeSliceContract, parseSliceYaml, readSliceSources, resolveSliceBasis, sourceSliceContract, sliceArchitectureEvidence } from './slice-contract.mjs';
+
+const object=value=>value && typeof value==='object' && !Array.isArray(value);
+const same=(a,b)=>digest(a)===digest(b);
+function metadata(text) {
+  const front=/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if(front)return parseSliceYaml(front[1]);
+  return (/^\s*[{[]/.test(text)||/^[A-Za-z_][\w-]*:\s/m.test(text)&&!/^#/m.test(text))?parseSliceYaml(text):{};
+}
+function mergeFacts(left,right,path,report) {
+  if(left===undefined)return structuredClone(right);
+  if(right===undefined)return structuredClone(left);
+  if(object(left)&&object(right))return Object.fromEntries([...new Set([...Object.keys(left),...Object.keys(right)])].map(key=>[key,mergeFacts(left[key],right[key],`${path}.${key}`,report)]));
+  if(!same(left,right))report.blockers.push({field:path,reason:'conflict',before:left,after:right,recovery:'回到来源确认当前事实，不使用最后覆盖'});
+  return structuredClone(left);
+}
+function markdownAcceptance(text) {
+  const rows=text.split('\n'),result={};let active=false;
+  rows.forEach((line,index)=>{
+    if(/^##\s/.test(line))active=/验收/.test(line);
+    if(active&&/^\s*-\s+(?:\[[ xX]\]\s*)?\S/.test(line)) {
+      const id=/(?:AC|SC|验收)[-_][\w-]+/.exec(line)?.[0] || `acceptance-${Object.keys(result).length+1}`;
+      if(result[id])throw new TypeError(`验收 ID 重复: ${id}`);
+      result[id]={source:'ticket',locator:`lines:${index+1}-${index+1}`};
+    }
+  });return result;
+}
+function lifecycleSources(checkpoint,report) {
+  const result={};
+  for(const [artifact,key]of Object.entries({'artifact.spec':'spec','artifact.engineering-baseline':'engineering_baseline','artifact.architecture-review':'architecture_review','artifact.technical-design':'technical_design','artifact.data-architecture':'data_architecture','artifact.state-matrix':'state_matrix','artifact.prototype-deliverable':'prototype_deliverable','artifact.prototype-review':'prototype_review','artifact.prototype-confirmation':'prototype_confirmation','artifact.openapi-freeze-record':'openapi_freeze'})) {
+    const value=checkpoint.artifacts?.[artifact];if(value===undefined)continue;
+    if(typeof value==='string')result[key]={ref:value};
+    else if(object(value)&&typeof value.ref==='string')result[key]=Object.fromEntries(['ref','version','digest','approval_ref'].filter(k=>value[k]!==undefined).map(k=>[k,value[k]]));
+    else report.blockers.push({field:`artifacts.${artifact}`,reason:'上游引用不明确，需选择当前绑定'});
+  }
+  return result;
+}
+/** sources select existing assets; refinements contain ONLY new slice facts, never an approved contract. */
+export function prepareSliceImplementationContract({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refinements={},approved_slice}={}) {
+  const started=performance.now();
+  const report={read_only:true,blockers:[],sources:{},provenance:[],reason_chains:{},checks:[]};
+  const snapshots=new Map();
+  const read=ref=>{if(!snapshots.has(ref))snapshots.set(ref,fs.readFileSync(safe(root,ref)));return snapshots.get(ref);};
+  let contract={schema_version:3,status:'blocked'};
+  try {
+    let ticketText='',ticket={},saved={};
+    try {ticketText=read(ticket_ref).toString('utf8');ticket=metadata(ticketText);}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'basis.ticket',source_ref:ticket_ref,reason:error.message});}
+    if(checkpoint_ref)try {saved=parseSliceYaml(read(checkpoint_ref));}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'checkpoint',source_ref:checkpoint_ref,reason:error.message});}
+    const fromTicket=ticket.slice_implementation || {};
+    const facts=mergeFacts(saved.slice_implementation || {},fromTicket,'slice',report);
+    const input=mergeFacts(facts,refinements,'slice',report);
+    for(const field of ['status','resolution','schema_version','readiness'])if(Object.hasOwn(input,field))report.blockers.push({field,reason:'由编译器生成，不接受调用方指定'});
+    const inputKeys=['contract_id','contract_version','slice_id','sources','scope','applicability','recipe_ids','required_capabilities','conditions','acceptance','verification','work_units','extensions'];
+    for(const field of Object.keys(input))if(!inputKeys.includes(field))report.blockers.push({field,reason:'未知输入字段，禁止静默丢弃'});
+    contract={schema_version:3,contract_id:input.contract_id,contract_version:input.contract_version,slice_id:input.slice_id,status:'blocked'};
+    for(const field of ['contract_id','contract_version','slice_id','scope','applicability','verification','work_units'])if(input[field]===undefined)report.blockers.push({code:'SLICE_INPUT_MISSING',field:`slice.${field}`,reason:'缺少切片必要输入',recovery:'优先从 Ticket / checkpoint 整理；只补缺失的切片细化'});
+    for(const field of ['impacted_areas','allowed_write_paths'])if(input.scope?.[field]===undefined)report.blockers.push({code:'SLICE_INPUT_MISSING',field:`scope.${field}`,reason:'影响与授权范围未确定',responsibility:field==='allowed_write_paths'?'user-decision':'professional-review',recovery:'先确认影响与既有授权范围；不能从目录猜测'});
+
+    const selected=mergeFacts(lifecycleSources(saved,report),mergeFacts(input.sources || {},sources,'sources',report),'sources',report);
+    if(selected.ticket && (typeof selected.ticket==='string'?selected.ticket:selected.ticket.ref)!==ticket_ref)throw new TypeError('Ticket 来源冲突');
+    selected.ticket=selected.ticket || {ref:ticket_ref};
+    if(input.scope?.risk_level){selected.lifecycle_registry??={ref:'docs/process/lifecycle-registry.yaml'};selected.process_tailoring??={ref:'docs/process/harness-process-tailoring.md'};}
+    if(!selected.context&&fs.existsSync(safe(root,'CONTEXT.md',{missing:true})))selected.context={ref:'CONTEXT.md'};
+    const basis={},seen=new Map();
+    for(const [key,value] of Object.entries(selected)) {
+      try {
+      if(typeof value==='string' && Object.hasOwn(selected,value)) {basis[key]=value;continue;}
+      const binding=typeof value==='string'?{ref:value}:value;
+      const bytes=read(binding.ref),rawDigest=hash(bytes);
+      if(binding.digest&&binding.digest!==rawDigest)throw new TypeError(`stale: 来源 ${key}`);
+      const data=metadata(bytes.toString('utf8'));
+      const sourceVersion=data.requirement_version??data.version??data.contract_version;
+      if(binding.version!==undefined&&sourceVersion!==undefined&&String(binding.version)!==String(sourceVersion))throw new TypeError(`来源版本冲突: ${key}`);
+      const version=binding.version||data.requirement_version||data.version||data.contract_version;
+      basis[key]={ref:binding.ref,digest:rawDigest,...(version?{version:String(version)}:{}),...(binding.approval_ref?{approval_ref:binding.approval_ref}:{})};
+      if(seen.has(binding.ref)) {
+        const previous=seen.get(binding.ref);
+        if(!same(basis[key],basis[previous]))throw new TypeError(`来源绑定冲突: ${key}/${previous}`);
+        basis[key]=previous;
+      }else seen.set(binding.ref,key);
+      report.provenance.push({target:`basis.${key}`,source_ref:binding.ref,digest:rawDigest,rule:'original-bytes'});
+      }catch(error){report.blockers.push({code:(error.code==='ENOENT'||/文件不可读/.test(error.message))?'SLICE_SOURCE_UNREADABLE':/冲突/.test(error.message)?'SLICE_SOURCE_CONFLICT':'SLICE_SOURCE_INVALID',field:`basis.${key}`,source_ref:typeof value==='string'?value:value?.ref,reason:error.message,responsibility:'agent',recovery:'补齐当前来源或纠正绑定后重新准备'});}
+    }
+    const extraRequired=[...(input.applicability?.backend?.status==='required'?['technical_design','repository_registration','manifest','backend_repository','maven_wrapper']:[]),...(input.applicability?.frontend?.status==='required'?(input.applicability.frontend.baseline_kind==='existing-ui-baseline'?['existing_ui_baseline','frontend_delivery']:['requirement_freeze','low_fidelity_review','prototype_review','prototype_profile_decision','prototype_deliverable','prototype_deliverable_verification','prototype_confirmation','visual_baseline','state_matrix']):[]),...(input.applicability?.api?[input.applicability.api.status==='required'?'openapi_freeze':'no_api_impact_record']:[])];
+    for(const key of ['spec','ticket','engineering_baseline','implementation_repository','build_architecture_checklist',...extraRequired,...(!input.scope?.risk_level?['architecture_review']:[])])if(!selected[key])report.blockers.push({code:'SLICE_SOURCE_MISSING',field:`basis.${key}`,reason:'缺少必要来源',responsibility:'agent',recovery:'绑定已有当前资产；不能用空文档替代'});
+    contract.basis=basis;
+    if(report.blockers.length){report.checks.push({check:'dependent-compilation',result:'not-executed',reason:'来源或输入存在独立阻断'});throw Object.assign(new Error('依赖未就绪'),{code:'SLICE_DEPENDENCIES_UNAVAILABLE'});}
+    const sourceDoc=key=>basis[key]?metadata(read(resolveSliceBasis({basis},key).ref).toString('utf8')):{};
+    const registration=sourceDoc('implementation_repository'),baseline=sourceDoc('engineering_baseline');
+    const registeredRoot=registration.local_worktree?(registration.project_root&&registration.project_root!=='.'?path.resolve(registration.local_worktree,registration.project_root):registration.local_worktree):undefined;
+    const scope={...(registeredRoot?{project_roots:[registeredRoot]}:{}),...input.scope};
+    // Registration is an upper bound. Never use its allowed_write_paths as slice authorization.
+    if(!input.extensions?.cross_repo?.repository_bindings&&registeredRoot&&scope.project_roots?.some(p=>p!==registeredRoot))throw new TypeError('实施仓库与登记冲突');
+    if(!input.extensions?.cross_repo?.repository_bindings&&registration.allowed_write_paths && scope.allowed_write_paths) {
+      const {withinSlicePath}=helpers;
+      if(scope.allowed_write_paths.some(p=>!registration.allowed_write_paths.some(parent=>withinSlicePath(p,parent))))throw new TypeError('Slice 写范围超出登记');
+    }
+    const applicability=structuredClone(input.applicability);
+    if(scope.risk_level){const calculated=sliceCheckApplicability(scope,sourceDoc('lifecycle_registry'));if(applicability.checks&&!same(applicability.checks,calculated))throw new TypeError('材料适用性与生命周期规则冲突');applicability.checks=calculated;}
+    const architecture_identity=baseline.architecture_identity || registration.architecture_identity;
+    if(baseline.architecture_identity&&registration.architecture_identity&&!same(baseline.architecture_identity,registration.architecture_identity))throw new TypeError('工程基线与登记架构冲突');
+    const bound=key=>basis[key]?resolveSliceBasis({basis},key):undefined;
+    const architecture_evidence=architecture_identity?sliceArchitectureEvidence({basis,resolution:{architecture_identity}},readSliceSources({basis},{root})):undefined;
+    const compilerRules=loadCompilerContract();
+    scope.full_reroute_triggers=[...new Set([...(compilerRules.full_reroute_triggers||[]),...(scope.full_reroute_triggers||[])])];
+    for(const impact of input.extensions?.backend?.component_impacts||[])if(!compilerRules.impact_to_capabilities[impact])throw new TypeError(`未知组件影响: ${impact}`);
+    const componentCapabilities=(input.extensions?.backend?.component_impacts||[]).flatMap(impact=>compilerRules.impact_to_capabilities[impact]||[]);
+    const compileBase={root,slice_id:input.slice_id,conditions:input.conditions||[]};
+    let compiled;
+    if(input.extensions?.cross_repo?.repository_bindings) {
+      const repositories=sliceRepositories({basis,scope,extensions:input.extensions,work_units:input.work_units,resolution:{}},readSliceSources({basis},{root}),{root});
+      const results=Object.entries(repositories).map(([projectRoot,repo])=>{
+        const recipeIds=repo.recipe_refs||(input.recipe_ids||[]).filter(id=>!id.startsWith('backend.')&&!id.startsWith('frontend.')||id.startsWith(`${repo.project.delivery_role}.`));
+        const requiredCapabilities=repo.capability_refs||input.required_capabilities||[];
+        if(recipeIds.some(id=>!(input.recipe_ids||[]).includes(id))||requiredCapabilities.some(id=>!(input.required_capabilities||[]).includes(id)))throw new TypeError('逐仓编译引用不属于切片新增输入');
+        return compileDefaultImplementationContract({...compileBase,recipeIds,requiredCapabilities:[...requiredCapabilities,...(repo.project.delivery_role==='backend'?componentCapabilities:[])],architecture_identity:repo.resolution.architecture_identity,architecture_evidence:repo.resolution.architecture_evidence,technical_design:repo.resolution.technical_design,...(repo.resolution.frontend_delivery?{frontend_delivery:repo.resolution.frontend_delivery}:{}),...(approved_slice?{approved_slice,work_unit_id:input.work_units.find(u=>u.project_root===projectRoot)?.id}:{})});
+      });
+      if(results.some(r=>r.registry_digest!==results[0].registry_digest||r.compiler_contract_digest!==results[0].compiler_contract_digest))throw new TypeError('逐仓编译依据冲突：准备期间来源发生变化');
+      compiled={...results[0],required_capabilities:[...new Set(results.flatMap(r=>r.required_capabilities))],required_skills:[...new Set(results.flatMap(r=>r.required_skills))],recipe_ids:[...new Set(results.flatMap(r=>r.recipe_ids))],readiness_blockers:results.flatMap(r=>r.readiness_blockers||[]),reason_chains:Object.fromEntries(Object.keys(repositories).map((p,i)=>[p,results[i].reason_chains]))};
+      delete compiled.architecture_identity;
+    } else compiled=compileDefaultImplementationContract({...compileBase,recipeIds:input.recipe_ids||[],requiredCapabilities:[...new Set([...(input.required_capabilities||[]),...componentCapabilities])],architecture_identity,architecture_evidence,technical_design:bound('technical_design'),...(bound('frontend_delivery')?{frontend_delivery:{acceptance_ref:bound('frontend_delivery').ref,digest:bound('frontend_delivery').digest}}:{}),...(approved_slice?{approved_slice}:{})});
+    if(compiled.compiler_contract_digest!==digest(compilerRules).slice(7))throw new TypeError('编译规则来源冲突：准备期间发生变化');
+    const resolution=Object.fromEntries(['required_capabilities','required_skills','recipe_ids','conditions','registry_digest','compiler_contract_digest','architecture_identity'].filter(key=>compiled[key]!==undefined).map(key=>[key,compiled[key]]));
+    contract={schema_version:3,ticket_policy:{mode:'frozen-requirements',state_owner:'tracker-or-task-package'},contract_id:input.contract_id,contract_version:input.contract_version,slice_id:input.slice_id,status:'draft',basis,scope,applicability,resolution,acceptance:input.acceptance||markdownAcceptance(ticketText),verification:input.verification,work_units:input.work_units,...(input.extensions?{extensions:input.extensions}:{})};
+    report.reason_chains=compiled.reason_chains;
+    for(const reason of compiled.readiness_blockers||[])report.blockers.push({reason});
+    normalizeSliceContract(contract,{root});
+    report.checks.push({check:'structure-sources-scope-acceptance',result:'pass'});
+    report.provenance.push({target:'resolution',source_ref:'docs/agents/yss-skill-registry.yaml',digest:compiled.registry_digest,rule:'existing-capability-compiler'});
+    for(const field of ['scope','acceptance','verification','work_units','applicability','extensions'])if(contract[field]) {
+      const origins=[];
+      if(saved.slice_implementation?.[field]!==undefined)origins.push({kind:'checkpoint',ref:checkpoint_ref});
+      if(fromTicket[field]!==undefined)origins.push({kind:'ticket-metadata',ref:ticket_ref});
+      if(refinements[field]!==undefined)origins.push({kind:'agent-refinement'});
+      if(field==='scope'&&registeredRoot&&!input.scope?.project_roots)origins.push({kind:'repository-registration',ref:resolveSliceBasis({basis},'implementation_repository').ref});
+      if(field==='scope'&&input.extensions?.cross_repo?.repository_bindings)for(const keys of Object.values(input.extensions.cross_repo.repository_bindings))origins.push({kind:'repository-registration',ref:resolveSliceBasis({basis},keys.implementation_repository).ref});
+      if(field==='acceptance'&&!input.acceptance)origins.push({kind:'ticket-acceptance',ref:ticket_ref});
+      if(field==='applicability'&&scope.risk_level)origins.push({kind:'lifecycle-rule',ref:resolveSliceBasis({basis},'lifecycle_registry').ref});
+      report.provenance.push({target:field,origins,requires_professional_review:true});
+    }
+  }catch(error){if(error.code!=='SLICE_DEPENDENCIES_UNAVAILABLE')report.blockers.push({reason:error.message,recovery:'补齐已确认输入后重新准备；草案不授予执行权限'});report.checks.push({check:'assembly',result:'not-executed',reason:'前置检查未通过'});}
+  for(const [ref,bytes] of snapshots) {
+    try {if(hash(fs.readFileSync(safe(root,ref)))!==hash(bytes))report.blockers.push({field:ref,reason:'生成期间来源变化'});}catch(error){report.blockers.push({field:ref,reason:error.message});}
+    report.sources[ref]=hash(bytes);
+  }
+  report.blockers=report.blockers.map(b=>({code:b.code||(/conflict|冲突/.test(b.reason)?'SLICE_INPUT_CONFLICT':'SLICE_INPUT_INVALID'),field:b.field||'slice',source_ref:b.source_ref||null,responsibility:b.responsibility||(/user.decision|用户决定|实施授权/.test(b.reason)?'user-decision':/conflict|冲突|技术设计|架构/.test(b.reason)?'professional-review':'agent'),recovery:b.recovery||'核对所列来源并补齐细化后重新准备',...b}));
+  report.blockers=report.blockers.filter((b,i,all)=>all.findIndex(x=>x.code===b.code&&x.field===b.field&&x.source_ref===b.source_ref)===i);
+  contract.status=report.blockers.length?'blocked':'ready-for-lifecycle-review';
+  report.metrics={elapsed_ms:Math.round(performance.now()-started),preparation_round:null,additional_human_confirmations:null,reapproval_reasons:[],measurement:'observed-preparation-only; interaction counts not recorded',unique_source_files:snapshots.size,refinement_fields:Object.keys(refinements).length,contract_bytes:Buffer.byteLength(stringify({slice_contract:contract}))};
+  return {slice_contract:contract,report};
+}
+import * as helpers from './slice-contract.mjs';
+
+export function persistSliceDraft(result,ref,{root=process.cwd()}={}) {
+  if(!['draft','blocked','ready-for-lifecycle-review'].includes(result.slice_contract?.status))throw new TypeError('只能保存编译器草案');
+  for(const [source,expected]of Object.entries(result.report?.sources||{}))if(hash(fs.readFileSync(safe(root,source)))!==expected)throw new TypeError(`stale: 保存前来源变化 ${source}`);
+  if(result.slice_contract.status!=='blocked')normalizeSliceContract(result.slice_contract,{root});
+  const bytes=stringify({slice_contract:result.slice_contract});
+  const reportRef=`${ref}.preparation.json`;
+  if(fs.existsSync(safe(root,reportRef,{missing:true})))throw Object.assign(new TypeError('EEXIST: 准备报告目标已存在'),{code:'EEXIST'});
+  write(root,ref,bytes); // wx: never overwrite a draft or approval.
+  write(root,reportRef,JSON.stringify({binding:{ref,digest:hash(bytes)},...result.report},null,2)+'\n');
+  return ref;
+}
+
+/** Explicit, non-destructive migration; no new authorization is inferred. */
+export function migrateSliceContractV2(document,{root=process.cwd(),ticket_ref,sources={},refinements={},...rest}={}) {
+  const old=sourceSliceContract(document);
+  if(old?.schema_version!==2)throw new TypeError('显式迁移只接受 Slice v2');
+  const conflicts=[];
+  const meaningful=value=>value!==undefined&&value!==null&&value!==''&&(!Array.isArray(value)||value.length>0);
+  const compare=(a,b,label)=>{if(meaningful(a)&&meaningful(b)&&!same(a,b))conflicts.push({field:label,reason:'conflict',before:a,after:b});};
+  for(const key of ['required_skills','required_capabilities'])compare(old.common?.[key],old.resolution?.[key],key);
+  compare(old.frontend?.delivery,old.resolution?.frontend_delivery,'frontend_delivery');
+  const constraintKeys=['application_boundary','transaction_boundary','persistence_strategy','aggregate_refs','invariant_refs','state_behavior_refs','gateway_boundary_ref','domain_test_seams','application_test_seams'];
+  for(const key of constraintKeys)compare(old.backend?.[key],old.backend?.tactical_ddd?.[key],`backend.${key}`);
+  if(refinements.contract_version===undefined||refinements.contract_version===String(old.contract_version))conflicts.push({field:'contract_version',reason:'迁移必须指定新版本'});
+  if(old.readiness?.blockers?.length||old.readiness?.stale_inputs?.length)conflicts.push({field:'readiness',reason:'旧合同仍有阻断或过期输入'});
+  const sourceMap=Object.fromEntries(Object.entries(old.lifecycle_refs||{}).filter(([,v])=>typeof v==='string'&&v).map(([k,v])=>[k,{ref:v}]));
+  for(const [key,binding]of Object.entries({...old.resolution?.architecture_evidence,...(old.resolution?.technical_design?{technical_design:old.resolution.technical_design}:{})})) {
+    if(!binding?.ref)continue;
+    if(sourceMap[key]&&sourceMap[key].ref!==binding.ref)conflicts.push({field:`basis.${key}`,reason:'阅读引用与冻结绑定冲突'});
+    sourceMap[key]=binding;
+  }
+  if(sourceMap.openapi_freeze_or_no_impact){sourceMap[old.contract?.api_impact?'openapi_freeze':'no_api_impact_record']=sourceMap.openapi_freeze_or_no_impact;delete sourceMap.openapi_freeze_or_no_impact;}
+  const frontendBinding=old.frontend?.delivery||old.resolution?.frontend_delivery;
+  if(frontendBinding)sourceMap.frontend_delivery={ref:frontendBinding.acceptance_ref,digest:frontendBinding.digest};
+  if(sourceMap.tactical_design&&!sourceMap.technical_design)sourceMap.technical_design=sourceMap.tactical_design;
+  const applicability=Object.fromEntries(['frontend','backend','api','cross_repo'].map(key=>{
+    const required=key==='api'?old.contract?.api_impact:key==='cross_repo'?old.cross_repo?.repositories?.length>1:old[key]?.status==='required';
+    const reason=old.readiness?.not_applicable?.find(x=>x.item===key)?.reason;
+    return [key,required?{status:'required'}:{status:'not-applicable',reason:reason||refinements.applicability?.[key]?.reason}];
+  }));
+  const scopeKeys=['impacted_areas','implementation_path_policy','project_roots','allowed_write_paths','forbidden_patterns','context_plan','doubt_driven_review','human_review_points','full_reroute_triggers','optional_skills','unavailable_skills'];
+  const scope=Object.fromEntries(scopeKeys.filter(k=>old.common?.[k]!==undefined).map(k=>[k,old.common[k]]));
+  const checkUnknown=(value,known,prefix)=>{for(const [key,item]of Object.entries(value||{}))if(meaningful(item)&&!known.includes(key))conflicts.push({field:`${prefix}.${key}`,reason:'未映射约束，禁止静默丢弃'});};
+  checkUnknown(old,['schema_version','contract_id','contract_version','slice_id','status','suggested_owner_role_id','lifecycle_refs','readiness','resolution','common','frontend','backend','contract','cross_repo','work_units'],'root');
+  checkUnknown(old.common,[...scopeKeys,'required_capabilities','required_skills','verification_commands','expected_evidence_files','quality_baseline_ref'],'common');
+  checkUnknown(old.resolution,['schema_version','status','slice_id','architecture_identity','architecture_identity_digest','architecture_evidence','technical_design','frontend_delivery','profile_maturity','readiness_blockers','skill_profiles','recipe_ids','conditions','required_capabilities','required_skills','reason_chains','non_expanding_dependencies','excluded_conditional_dependencies','registry_digest','compiler_contract_digest','compiled_at','freshness'],'resolution');
+  const ticketRef=ticket_ref||old.lifecycle_refs?.ticket;
+  let acceptance=refinements.acceptance;
+  if(!acceptance){try{acceptance=markdownAcceptance(fs.readFileSync(safe(root,ticketRef),'utf8'));}catch(error){conflicts.push({field:'acceptance',reason:error.message});acceptance={};}}
+  const verification={},work_units=[],extensions={};
+  for(const entry of old.work_units||[]) {
+    const unit=entry.work_unit||entry;
+    for(const key of ['allowed_write_paths','verification_commands','expected_evidence'])compare(entry[key],unit[key],`work_units.${entry.id}.${key}`);
+    const projectRoot=unit.project_root||entry.project_root||(scope.project_roots?.length===1?scope.project_roots[0]:undefined);
+    const acceptanceRefs=unit.acceptance_refs||(Object.keys(acceptance).length===1?Object.keys(acceptance):[]);
+    const seams=[...(old.frontend?.component_test_seams||[]),...(old.frontend?.e2e_paths||[]),...(old.backend?.domain_test_seams||old.backend?.tactical_ddd?.domain_test_seams||[]),...(old.backend?.application_test_seams||old.backend?.tactical_ddd?.application_test_seams||[])];
+    const evidence=[...new Set([...(old.common?.expected_evidence_files||[]),...(unit.expected_evidence||[])])];
+    const refs=[];
+    for(const command of new Set([...(old.common?.verification_commands||[]),...(unit.verification_commands||[])])) {
+      const check={command,cwd:projectRoot,expected_evidence:evidence,test_seams:seams,acceptance_refs:acceptanceRefs};
+      const existing=Object.entries(verification).find(([,v])=>same(v,check));
+      const id=existing?.[0]||`verify-${Object.keys(verification).length+1}`;verification[id]=check;refs.push(id);
+    }
+    const allowed=unit.allowed_write_paths||entry.allowed_write_paths;
+    const next={id:entry.id||unit.id,role_id:entry.role_id||unit.role_id,behavior:unit.behavior,primary_skill:unit.primary_skill,tdd_mode:unit.tdd_mode,verification_refs:refs,acceptance_refs:acceptanceRefs};
+    for(const key of ['supporting_skills','controlled_generation','downstream_consumers','convergence_ref','forbidden_patterns'])if(meaningful(unit[key]||entry[key]))next[key]=unit[key]||entry[key];
+    if(allowed&&!same(allowed,scope.allowed_write_paths))next.allowed_write_paths=allowed;
+    if(scope.project_roots?.length>1)next.project_root=projectRoot;
+    work_units.push(next);
+    checkUnknown(unit,['id','behavior','role_id','runtime_id','execution_state','workflow_status','task_package_ref','contract_id','contract_version','architecture_identity','project_root','primary_skill','supporting_skills','tdd_mode','allowed_write_paths','expected_evidence','verification_commands','controlled_generation','acceptance_refs','downstream_consumers','convergence_ref','forbidden_patterns'],'work_unit');
+  }
+  const subset=(value,keys)=>Object.fromEntries(keys.filter(k=>meaningful(value?.[k])).map(k=>[k,value[k]]));
+  if(applicability.frontend.status==='required')extensions.frontend=subset(old.frontend,['visual_baseline_case_ids','component_test_seams','e2e_paths','generated_api_client_ref','implementation_verification_ref']);
+  if(applicability.backend.status==='required') {
+    const constraints={...subset(old.backend,constraintKeys),...subset(old.backend?.tactical_ddd,constraintKeys)};
+    extensions.backend={...subset(old.backend,['affected_layers','component_impacts','seam_deferred']),design_refs:['pointer:/design'],...(Object.keys(constraints).length?{constraints}:{})};
+  }
+  if(applicability.api.status==='required')extensions.api=subset(old.contract,['generated_clients','contract_tests','regeneration_commands']);
+  if(applicability.cross_repo.status==='required')extensions.cross_repo=subset(old.cross_repo,['delivery_order','integration_verification','rollback_order']);
+  for(const [section,data]of Object.entries({frontend:old.frontend,backend:old.backend})) {
+    if(data?.status!=='required')continue;
+    for(const key of ['allowed_write_paths','forbidden_patterns','verification_commands','expected_evidence_files'])if(meaningful(data[key])&&!same(data[key],old.common?.[key]))conflicts.push({field:`${section}.${key}`,reason:'独有约束须显式映射至对应工作单元'});
+  }
+  const knownSub=['status','required_skills','allowed_write_paths','forbidden_patterns','verification_commands','expected_evidence_files'];
+  checkUnknown(old.frontend,[...knownSub,'approved_prototype_ref','state_matrix_ref','visual_baseline_ref','visual_baseline_case_ids','component_test_seams','e2e_paths','generated_api_client_ref','implementation_verification_ref','delivery'],'frontend');
+  checkUnknown(old.backend,[...knownSub,...constraintKeys,'affected_layers','component_impacts','tactical_design_ref','tactical_design_version','tactical_ddd','seam_deferred'],'backend');
+  checkUnknown(old.contract,['api_impact','freeze_ref','no_api_impact_ref','generated_clients','contract_tests','regeneration_commands'],'contract');
+  checkUnknown(old.cross_repo,['repositories','delivery_order','integration_verification','rollback_order'],'cross_repo');
+  const base={contract_id:old.contract_id,slice_id:old.slice_id,scope,applicability,recipe_ids:old.resolution?.recipe_ids,required_capabilities:old.resolution?.required_capabilities,conditions:old.resolution?.conditions,acceptance,verification,work_units,...(Object.keys(extensions).length?{extensions}:{})};
+  const migrated=mergeFacts(base,refinements,'migration', {blockers:conflicts});
+  migrated.contract_version=refinements.contract_version;
+  const result=prepareSliceImplementationContract({root,ticket_ref:ticketRef,sources:mergeFacts(sourceMap,sources,'sources',{blockers:conflicts}),refinements:migrated,...rest});
+  result.report.blockers.push(...conflicts);
+  result.report.migration={from_schema:2,to_schema:3,approval_inherited:false};
+  if(result.report.blockers.length)result.slice_contract.status='blocked';
+  return result;
+}

package/template/scripts/lib/slice-contract-views.mjs

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import { safe, hash, digest } from './strategic-handoff-io.mjs';
+import { selectSliceWorkUnit, readSliceContract, readSliceSources, sliceAcceptanceText, parseSliceYaml, sourceSliceContract } from './slice-contract.mjs';
+
+function sections(text) {
+  const result={};let name='正文';
+  for(const line of text.split('\n')) {
+    const heading=/^#{1,3}\s+(.+)/.exec(line);
+    if(heading)name=heading[1];
+    else (result[name]??=[]).push(line);
+  }
+  return Object.fromEntries(Object.entries(result).filter(([name])=>!/验收/.test(name)).map(([name,lines])=>[name,lines.join('\n').trim()]));
+}
+export function renderSliceContractView(ref,{root=process.cwd(),unit_id}={}) {
+  const {contract,raw,binding,sources}=readSliceContract(ref,{root,diagnostic:true});
+  if(raw.status==='blocked') {
+    let report;try{report=JSON.parse(fs.readFileSync(safe(root,`${ref}.preparation.json`),'utf8'));if(report.binding.digest!==binding.digest)report=undefined;}catch{}
+    const blockers=report?.blockers||[{code:'SLICE_DIAGNOSTICS_UNAVAILABLE',reason:'未找到绑定当前字节的准备报告，需重新准备'}];
+    return {read_only:true,diagnostic_only:true,binding,status:'blocked',approval_validity:'阻断草案不可批准或执行',blockers,markdown:`# Slice 诊断\n\n${ref} · ${binding.digest}\n\n阻断草案不可批准或执行。\n\n`+blockers.map(b=>`- ${b.code} · ${b.field||'slice'}：${b.reason}；${b.recovery||'重新准备'}`).join('\n')};
+  }
+
+  const displayed=unit_id?selectSliceWorkUnit(contract,unit_id):contract;
+  const task=unit_id?contract.work_units?.filter(u=>u.id===unit_id):null;
+  if(task&&task.length!==1)throw new TypeError(`工作单元缺失或不唯一: ${unit_id}`);
+  const view={ticket_state:raw.ticket_policy?{owner:raw.ticket_policy.state_owner,frozen_status:/^---\r?\n([\s\S]*?)\r?\n---/.test(sources.ticket.text)?parseSliceYaml(/^---\r?\n([\s\S]*?)\r?\n---/.exec(sources.ticket.text)[1]).status||'未记录':'未记录',current_status:'请读取主 tracker 或当前任务包',requirement_version:sources.ticket.version}:{owner:'legacy-ticket'},read_only:true,view_kind:unit_id?'work-unit':'review',binding,status:raw.status,approval_validity:'未核验；本视图不授予执行权限',sources:Object.fromEntries(Object.entries(sources).map(([k,{text,...b}])=>[k,b])),acceptance:raw.schema_version===3?sliceAcceptanceText(raw,sources):{},summary:sources.ticket?sections(sources.ticket.text.replace(/^---\n[\s\S]*?\n---\n/,'')):{说明:'v2 原合同未提供统一摘要来源'},constraints:displayed.common,extensions:{frontend:displayed.frontend,backend:displayed.backend,api:displayed.contract,cross_repo:displayed.cross_repo},...(task?{task:task[0].work_unit||task[0]}:{})};
+  const lines=[`# Slice ${raw.slice_id}`,`权威合同：${ref} · ${raw.contract_version} · ${binding.digest}`,`状态：${raw.status}；${view.approval_validity}`];
+  for(const [name,pattern]of [['交付目标',/目标|构建/],['关键取舍',/取舍/],['风险',/风险/],['待决定事项',/待|决定/]]) { const rows=Object.entries(view.summary).filter(([key])=>pattern.test(key)&&!/^非目标/.test(key));lines.push(`## ${name}`,rows.map(([,text])=>text).filter(Boolean).join('\n')||'未提供说明，需在审查时核实。'); }
+  lines.push('## 实施范围',Object.entries(view.summary).filter(([name])=>/范围|非目标/.test(name)).map(([name,text])=>`${name}：${text}`).join('\n')||'未提供业务范围说明，需核对目标、工作单元与写边界。',`工程：${displayed.common?.project_roots?.join(', ') || '见原合同'}`,`允许写入：${displayed.common?.allowed_write_paths?.join(', ') || '见原合同'}`);
+  lines.push('## 验收',...Object.entries(view.acceptance).map(([id,text])=>`- ${id}: ${text}`));
+  if(raw.ticket_policy)lines.push('## 状态来源',`需求版本：${view.ticket_state.requirement_version}；冻结时状态：${view.ticket_state.frozen_status}。当前执行状态：${view.ticket_state.current_status}。`);
+  if(view.task)lines.push('## 当前任务',`行为：${view.task.behavior}`,`写范围：${view.task.allowed_write_paths.join(', ')}`,`验证：${view.task.verification_commands.join('; ')}`);
+  lines.push('## 执行停止条件','来源或批准过期、越界、缺少证据、验证失败、drift / violation / new_impacts 时停止并回交。','<details><summary>完整工程约束与来源</summary>','', '```json',JSON.stringify({constraints:view.constraints,extensions:view.extensions,task:view.task,sources:view.sources},null,2),'```','</details>');
+  view.markdown=lines.join('\n\n');
+  return view;
+}
+export function diffSliceContracts(beforeRef,afterRef,{root=process.cwd(),beforeRoot=root}={}) {
+  const read=(base,ref)=>{const bytes=fs.readFileSync(safe(base,ref));return{raw:sourceSliceContract(parseSliceYaml(bytes)),binding:{ref,digest:hash(bytes)}};};
+  const before=read(beforeRoot,beforeRef),after=read(root,afterRef),changes=[];
+  function walk(a,b,p) {
+    if(digest(a??null)===digest(b??null)&&((a===undefined)===(b===undefined)))return;
+    if(a&&b&&typeof a==='object'&&typeof b==='object'&&!Array.isArray(a)&&!Array.isArray(b)) {
+      for(const key of new Set([...Object.keys(a),...Object.keys(b)]))walk(a[key],b[key],p?`${p}.${key}`:key);
+    }else changes.push({path:p,before:a??null,after:b??null,category:/^(scope\.(allowed_write_paths|project_roots)|work_units)/.test(p)?'scope':/^acceptance/.test(p)?'acceptance':/^(ticket_policy|basis\.ticket|contract_version|status)/.test(p)?'authorization':'engineering-detail',evidence:{before:before.binding,after:after.binding},decision_impact:'待独立专业审查判定'});
+  }
+  walk(before.raw,after.raw,'');
+  const sourceChecks=[];
+  for(const [label,entry,base]of [['before',before,beforeRoot],['after',after,root]]) {
+    try {if(entry.raw.schema_version!==3)throw new Error('v2 未冻结统一来源快照');readSliceSources(entry.raw,{root:base});sourceChecks.push({side:label,result:'current'});}
+    catch(error){sourceChecks.push({side:label,result:'unknown-or-stale',reason:error.message});}
+  }
+  return {read_only:true,before:before.binding,after:after.binding,bytes_changed:before.binding.digest!==after.binding.digest,category:changes.length?'requires-review':sourceChecks.some(x=>x.result!=='current')?'unknown-or-stale':before.binding.digest===after.binding.digest?'unchanged':'presentation-only',changes,source_checks:sourceChecks,approval_reusable:false,explanation:'字节变化后须重新绑定；用户确认是否延续由现有协议和独立专业审查裁决。'};
+}

package/template/scripts/lib/slice-contract.mjs

@@ -0,0 +1,211 @@
+import {validateExistingUiBaseline} from './existing-ui-baseline.mjs';
+import {sliceRepositories} from './slice-repositories.mjs';
+import { sliceCheckApplicability } from './slice-applicability.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { safe, hash, digest, schema } from './strategic-handoff-io.mjs';
+
+const originals = new WeakMap();
+const sourceSnapshots = new WeakMap();
+const nonempty = value => typeof value === 'string' && value.trim();
+const unique = values => [...new Set(values)];
+const fail = message => { throw new TypeError(`slice-contract-invalid: ${message}`); };
+const requireThat = (ok, message) => { if (!ok) fail(message); };
+export const sourceSliceContract = value => originals.get(value) || value?.slice_contract || value;
+export function parseSliceYaml(bytes) {
+  const doc = parseDocument(String(bytes), { uniqueKeys: true, intAsBigInt: true });
+  requireThat(!doc.errors.length, `YAML 无效: ${doc.errors[0]?.message}`);
+  const value = doc.toJS({ maxAliasCount: 0 });
+  const convert = item => {
+    if (typeof item === 'bigint') {
+      requireThat(item <= BigInt(Number.MAX_SAFE_INTEGER) && item >= BigInt(Number.MIN_SAFE_INTEGER), 'YAML 整数超出精确范围，请使用字符串');
+      return Number(item);
+    }
+    if (Array.isArray(item)) return item.map(convert);
+    if (item && typeof item === 'object') return Object.fromEntries(Object.entries(item).map(([k,v]) => [k,convert(v)]));
+    requireThat(typeof item !== 'number' || Number.isFinite(item), 'YAML 非有限数值');
+    return item;
+  };
+  return convert(value);
+}
+export function withinSlicePath(candidate, parent) {
+  if (!nonempty(candidate) || !nonempty(parent)) return false;
+  const rel = path.relative(path.resolve(parent), path.resolve(candidate));
+  return rel === '' || (!path.isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${path.sep}`));
+}
+function safeWritePath(value) {
+  requireThat(nonempty(value) && !path.isAbsolute(value) && !value.split(/[\\/]/).includes('..') && !/[\x00-\x1f*?{}\[\]]/.test(value), `写范围必须为明确的仓库相对路径: ${value}`);
+}
+export function resolveSliceBasis(contract, key, stack = []) {
+  requireThat(!stack.includes(key), `依据别名循环: ${[...stack,key].join(' -> ')}`);
+  const binding = contract.basis?.[key];
+  requireThat(binding !== undefined, `缺少上游依据 ${key}`);
+  return typeof binding === 'string' ? resolveSliceBasis(contract,binding,[...stack,key]) : binding;
+}
+export function readSliceSources(contract, { root = process.cwd() } = {}) {
+  const result = {}, bytesByPath=new Map();
+  for (const key of Object.keys(contract.basis)) {
+    const binding = resolveSliceBasis(contract,key);
+    const file=safe(root,binding.ref);
+    if(!bytesByPath.has(file))bytesByPath.set(file,fs.readFileSync(file));
+    const bytes=bytesByPath.get(file);
+    requireThat(hash(bytes) === binding.digest, `stale: 上游依据 ${key} 原始字节变化`);
+    result[key] = { ...binding, text: bytes.toString('utf8') };
+  }
+  return result;
+}
+export function sliceArchitectureEvidence(contract,sources) {
+  const identity=contract.resolution.architecture_identity;
+  if(!identity)return undefined;
+  const keys=['engineering_baseline','repository_registration','manifest'];
+  if(identity.schema_version!==2)return Object.fromEntries(keys.map(key=>[key,parseSliceYaml(sources[key].text)]));
+  const registration=parseSliceYaml(sources.repository_registration.text);
+  const evidence={repository_registration:resolveSliceBasis(contract,'repository_registration')};
+  for(const key of ['engineering_baseline','manifest']) {
+    const original=registration.architecture_evidence?.[key],bound=resolveSliceBasis(contract,key);
+    requireThat(original?.ref===bound.ref&&original?.digest===bound.digest,`登记与 ${key} 绑定冲突`);
+    evidence[key]=original;
+  }
+  return evidence;
+}
+function requireKeys(value, names, label) {
+  for (const name of names) requireThat(value[name] !== undefined, `${label} 缺少 ${name}`);
+}
+function locate(text, locator) {
+  if(locator.startsWith('pointer:')) {
+    const value=locator.slice(8).split('/').slice(1).reduce((current,key)=>current?.[key.replaceAll('~1','/').replaceAll('~0','~')],parseSliceYaml(text));
+    requireThat(value!==undefined,`定位缺失: ${locator}`);return JSON.stringify(value);
+  }
+  const lines = text.split('\n');
+  const range = /^lines:(\d+)-(\d+)$/.exec(locator);
+  if (range) {
+    const start=Number(range[1]),end=Number(range[2]);
+    requireThat(start>=1&&end>=start&&end<=lines.length,`定位范围无效: ${locator}`);
+    return lines.slice(start-1,end).join('\n');
+  }
+  const body=text.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,'');
+  const matches=body.split('\n').filter(line=>line.includes(locator));
+  requireThat(matches.length===1, `定位缺失或不唯一: ${locator}`);
+  return matches[0];
+}
+export function sliceAcceptanceText(contract, sources) {
+  return Object.fromEntries(Object.entries(contract.acceptance).map(([id,item])=>{
+    requireThat(sources[item.source],`验收 ${id} 来源缺失`);
+    return [id,locate(sources[item.source].text,item.locator)];
+  }));
+}
+/** Validate the authoritative v3 document, then expand inherited facts ONLY in memory. */
+export function normalizeSliceContract(document, options = {}) {
+  const raw = sourceSliceContract(document);
+  requireThat(raw && [2,3].includes(raw.schema_version), 'Slice Implementation Contract schema v1 已停止支持；需要 schema v2 或 v3');
+  if (raw.schema_version === 2) return structuredClone(raw);
+  schema(raw,'docs/process/schemas/slice-implementation-contract-v3.schema.json');
+  const sources=readSliceSources(raw,options), refs=Object.fromEntries(Object.entries(sources).map(([key,item])=>[key,item.ref]));
+  requireKeys(refs,['spec','ticket','engineering_baseline','implementation_repository','build_architecture_checklist'],'依据');
+  if(!raw.applicability.checks)requireKeys(refs,['architecture_review'],'依据');
+  else {
+    requireKeys(refs,['lifecycle_registry','process_tailoring'],'适用性依据');
+    const registry=parseSliceYaml(sources.lifecycle_registry.text),expected=sliceCheckApplicability(raw.scope,registry);
+    requireThat(digest(raw.applicability.checks)===digest(expected),'材料适用性与生命周期规则冲突');
+    if(expected['check.architecture-reviewed'].status==='required')requireKeys(refs,['architecture_review'],'命中检查');
+  }
+  if(raw.ticket_policy)requireThat(nonempty(sources.ticket.version),'冻结 Ticket 缺少需求版本');
+  const extension=raw.extensions || {}, scope=raw.scope, resolution=structuredClone(raw.resolution);
+  if(raw.ticket_policy&&scope.project_roots.length>1)requireThat(extension.cross_repo?.repository_bindings,'新跨仓草案缺少逐仓登记绑定');
+  const repositories=sliceRepositories(raw,sources,options);
+  for (const key of ['frontend','backend','api','cross_repo']) {
+    const item=raw.applicability[key];
+    if (item.status === 'required') requireThat(extension[key],`命中 ${key} 影响但缺少子合同`);
+    else {
+      requireThat(nonempty(item.reason),`${key} 不适用缺少理由`);
+      requireThat(!extension[key],`${key} 不适用时不得保存空子合同`);
+    }
+  }
+  for(const [impact,section]of [['frontend','frontend'],['ui','frontend'],['backend','backend'],['api','api'],['cross-repo','cross_repo']])if(scope.impacted_areas.includes(impact))requireThat(raw.applicability[section].status==='required',`影响面 ${impact} 与适用性冲突`);
+  if(scope.impacted_areas.some(x=>['data','persistence'].includes(x)))requireKeys(refs,['data_architecture'],'数据依据');
+  if (extension.frontend && raw.applicability.frontend.baseline_kind==='existing-ui-baseline') {
+    requireThat(raw.applicability.frontend.ui_change==='none'&&!scope.impacted_areas.includes('ui'),'既有 UI 基线不能承接 UI 变化');
+    requireKeys(refs,['existing_ui_baseline','frontend_delivery'],'既有 UI 依据');
+    const observed=parseSliceYaml(sources.existing_ui_baseline.text);
+    const validation=validateExistingUiBaseline(observed,{bundleRoot:path.dirname(safe(options.root||process.cwd(),sources.existing_ui_baseline.ref))});
+    requireThat(validation.errors.length===0,`既有 UI 基线不可消费: ${validation.errors.join('; ')}`);
+    requireThat(extension.frontend.visual_baseline_case_ids.every(id=>observed.cases.some(c=>c.case_id===id)),'既有 UI 用例未被基线覆盖');
+  } else if (extension.frontend) requireKeys(refs,['requirement_freeze','low_fidelity_review','prototype_review','prototype_profile_decision','prototype_deliverable','prototype_deliverable_verification','prototype_confirmation','visual_baseline','state_matrix'],'前端依据');
+  if (extension.backend) {
+    requireKeys(refs,['technical_design','repository_registration','manifest','backend_repository','maven_wrapper'],'后端依据');
+    requireThat(resolution.architecture_identity||repositories&&Object.values(repositories).some(r=>r.resolution.architecture_identity),'后端缺少架构身份');
+    requireThat(nonempty(sources.technical_design.version),'技术设计缺少版本');
+    for (const selector of extension.backend.design_refs) locate(sources.technical_design.text,selector);
+  }
+  requireKeys(refs,[extension.api?'openapi_freeze':'no_api_impact_record'],'API 依据');
+  requireThat(!refs[extension.api?'no_api_impact_record':'openapi_freeze'],'API 影响结论冲突');
+  for (const p of scope.allowed_write_paths) safeWritePath(p);
+  requireThat(!scope.project_roots.some(p=>/^app\/(backend|frontend)(\/|$)/.test(p)), '禁止 app/backend 或 app/frontend');
+  if (scope.implementation_path_policy !== 'external-repository-native') for(const p of scope.project_roots) requireThat(/^apps\/(backend|frontend)\/[^/]+/.test(p),'Harness 工程必须落入具体 project 目录');
+  sliceAcceptanceText(raw,sources);
+  const unitIds=new Set(), usedChecks=new Set(), covered=new Set();
+  const expected=Object.keys(raw.acceptance);
+  for(const [id,check] of Object.entries(raw.verification)) {
+    requireThat(scope.project_roots.some(p=>withinSlicePath(check.cwd,p)),`验证 ${id} 的 cwd 未登记`);
+    if(check.dependency_roots)requireThat(repositories&&check.dependency_roots.every(p=>repositories[p]),`验证 ${id} 依赖仓库未登记`);
+    requireThat(check.acceptance_refs.length && check.acceptance_refs.every(ref=>expected.includes(ref)),`验证 ${id} 验收引用无效`);
+  }
+  const work_units=raw.work_units.map(unit=>{
+    requireThat(!unitIds.has(unit.id),`工作单元重复: ${unit.id}`);unitIds.add(unit.id);
+    const allowed=unit.allowed_write_paths || scope.allowed_write_paths;
+    for(const p of allowed) { safeWritePath(p);requireThat(scope.allowed_write_paths.some(parent=>withinSlicePath(p,parent)),`任务 ${unit.id} 写范围越界: ${p}`); }
+    const root=unit.project_root || (scope.project_roots.length===1?scope.project_roots[0]:null);
+    requireThat(scope.project_roots.includes(root),`任务 ${unit.id} 必须选择登记的 project_root`);
+    const checks=unique([...Object.keys(raw.verification).filter(id=>raw.verification[id].required_for_all),...unit.verification_refs]);
+    requireThat(checks.every(id=>raw.verification[id]),`任务 ${unit.id} 引用未知验证`);
+    requireThat(checks.every(id=>withinSlicePath(raw.verification[id].cwd,root)),`任务 ${unit.id} 验证执行仓库冲突`);
+    const skills=[unit.primary_skill,...(unit.supporting_skills || [])];
+    requireThat(skills.every(id=>resolution.required_skills.includes(id)),`任务 ${unit.id} Skill 不在冻结闭包内`);
+    requireThat(unit.acceptance_refs.every(id=>expected.includes(id)&&checks.some(k=>raw.verification[k].acceptance_refs.includes(id))),`任务 ${unit.id} 验收没有验证覆盖`);
+    for(const id of unit.acceptance_refs)covered.add(id);
+    for(const id of checks)usedChecks.add(id);
+    if(unit.tdd_mode==='controlled-generation') {
+      requireThat(unit.controlled_generation,'controlled-generation 缺少受控例外');
+      requireKeys(unit.controlled_generation,['exception_reason','generator','generator_inputs','expected_files','verification_commands','behavior_tests_after_generation'],'受控生成');
+    } else requireThat(!unit.controlled_generation,'行为测试不得携带受控生成例外');
+    const work_unit={...unit,allowed_write_paths:allowed,project_root:root,supporting_skills:unit.supporting_skills||[],verification:checks.map(id=>({id,...raw.verification[id]})),verification_commands:checks.map(id=>raw.verification[id].command),expected_evidence:unique(checks.flatMap(id=>raw.verification[id].expected_evidence)),forbidden_patterns:unique([...(scope.forbidden_patterns||[]),...(unit.forbidden_patterns||[])])};
+    return {...work_unit,contract_id:raw.contract_id,contract_version:raw.contract_version,work_unit};
+  });
+  requireThat(expected.every(id=>covered.has(id)), '存在未被工作单元覆盖的验收');
+  requireThat(Object.keys(raw.verification).every(id=>usedChecks.has(id)),'存在未分配的验证要求');
+  if(repositories)for(const id of extension.cross_repo.integration_verification)requireThat(raw.verification[id]?.dependency_roots?.length,'联合验证必须引用有依赖仓库和明确 cwd 的 verification');
+  const allChecks=Object.values(raw.verification);
+  resolution.freshness='current'; // Only after every bound source was read and verified above.
+  if(resolution.architecture_identity) {
+    resolution.architecture_identity_digest=digest(resolution.architecture_identity).slice(7);
+    resolution.architecture_evidence=sliceArchitectureEvidence(raw,sources);
+  }
+  if(refs.technical_design)resolution.technical_design=resolveSliceBasis(raw,'technical_design');
+  if(refs.frontend_delivery)resolution.frontend_delivery={acceptance_ref:refs.frontend_delivery,digest:sources.frontend_delivery.digest};
+  const common={...scope,required_capabilities:resolution.required_capabilities,required_skills:resolution.required_skills,verification_commands:allChecks.map(c=>c.command),expected_evidence_files:unique(allChecks.flatMap(c=>c.expected_evidence)),quality_baseline_ref:refs.engineering_baseline,forbidden_patterns:scope.forbidden_patterns||[],full_reroute_triggers:scope.full_reroute_triggers||[]};
+  const normalized={...structuredClone(raw),...(repositories?{repositories}:{}),common,resolution,lifecycle_refs:{...refs,openapi_freeze_or_no_impact:refs.openapi_freeze||refs.no_api_impact_record},readiness:{blockers:[],stale_inputs:[],not_applicable:Object.entries(raw.applicability).filter(([,a])=>a.status==='not-applicable').map(([item,a])=>({item,reason:a.reason}))},work_units,
+    frontend:extension.frontend?{status:'required',...extension.frontend,approved_prototype_ref:refs.prototype_confirmation,state_matrix_ref:refs.state_matrix,visual_baseline_ref:refs.visual_baseline,...(resolution.frontend_delivery?{delivery:resolution.frontend_delivery}:{})}:{status:'not-applicable'},
+    backend:extension.backend?{status:'required',...extension.backend}:{status:'not-applicable'},
+    contract:{api_impact:!!extension.api,...(extension.api?{freeze_ref:refs.openapi_freeze,...extension.api}:{no_api_impact_ref:refs.no_api_impact_record})},
+    cross_repo:extension.cross_repo?{repositories:scope.project_roots,...extension.cross_repo}:{}
+  };
+  originals.set(normalized,raw);
+  sourceSnapshots.set(normalized,sources);
+  return normalized;
+}
+export function readSliceContract(ref,{root=process.cwd(),diagnostic=false}={}) {
+  const bytes=fs.readFileSync(safe(root,ref)),raw=sourceSliceContract(parseSliceYaml(bytes));
+  const contract=diagnostic&&raw.status==='blocked'?null:normalizeSliceContract(raw,{root});
+  return {contract,raw,sources:structuredClone(sourceSnapshots.get(contract)||{}),binding:{ref,id:raw.contract_id,version:raw.contract_version,digest:hash(bytes)}};
+}
+
+/** Select only after full normalization; original raw identity is retained for approval comparison. */
+export function selectSliceWorkUnit(contract,workUnitId) {
+ if(!contract.repositories)return contract;
+ const unit=contract.work_units.find(u=>u.id===workUnitId);
+ requireThat(unit,'跨仓执行必须选择唯一 work_unit_id');
+ const repo=contract.repositories[unit.project_root];
+ const selected={...contract,backend:repo.project.delivery_role==='backend'?contract.backend:{status:'not-applicable'},frontend:repo.project.delivery_role==='frontend'?{...contract.frontend,...(repo.resolution.frontend_delivery?{delivery:repo.resolution.frontend_delivery}:{})}:{status:'not-applicable'},resolution:{...repo.resolution,freshness:contract.resolution.freshness},common:{...contract.common,project_roots:[unit.project_root],allowed_write_paths:unit.allowed_write_paths},lifecycle_refs:{...contract.lifecycle_refs,...Object.fromEntries(Object.entries(repo.basis).map(([k,v])=>[k,v.ref]))}};
+ originals.set(selected,sourceSliceContract(contract));return selected;
+}

package/template/scripts/lib/slice-repositories.mjs

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import * as lifecycle from './lifecycle-transition.mjs';
+import path from 'node:path';
+import {digest,schema} from './strategic-handoff-io.mjs';
+import {parseSliceYaml,resolveSliceBasis,withinSlicePath,sliceArchitectureEvidence} from './slice-contract.mjs';
+const check=(ok,message)=>{if(!ok)throw new TypeError(`slice-repository-invalid: ${message}`);};
+/** All file facts stay in basis. Repository entries only select those facts. */
+export function sliceRepositories(contract,sources,{root=process.cwd()}={}) {
+ const bindings=contract.extensions?.cross_repo?.repository_bindings;if(!bindings)return null;
+ check(lifecycle.SLICE_REPOSITORY_PREPARATION_PROTOCOL===1&&typeof lifecycle.validateImplementationRepositoriesReady==='function','接收端不支持当前来源的多项目准备协议，不能套用本地默认规则');
+ check(sources.repository_preparation,'缺少多项目准备结果');
+ const preparation=parseSliceYaml(sources.repository_preparation.text);
+ schema(preparation,'docs/process/schemas/implementation-repository-preparation-result.schema.json');
+ const ready=lifecycle.validateImplementationRepositoriesReady({implementation_repository_preparation:preparation,delivery_impacts:Object.fromEntries(['backend','frontend'].map(role=>[role,preparation.projects.some(p=>p.delivery_role===role&&p.status!=='not-applicable')]))},{root,exists:ref=>fs.existsSync(path.resolve(root,ref)),read:ref=>fs.readFileSync(path.resolve(root,ref),'utf8')});
+ check(ready.result!=='blocked',`多项目准备未就绪: ${ready.missing_requirements.join('; ')}`);
+ check(new Set(Object.keys(bindings).map(p=>path.resolve(p))).size===Object.keys(bindings).length,'工程根存在路径别名，不能重复登记');
+ const result={},identities=new Set();
+ for(const [projectRoot,keys]of Object.entries(bindings)) {
+  const references=Object.entries(keys).filter(([name])=>!['recipe_refs','capability_refs'].includes(name));
+  const selected=Object.fromEntries(references.map(([name,key])=>{check(sources[key],`缺少 basis.${key}`);return[name,sources[key]];}));
+  const registration=parseSliceYaml(selected.implementation_repository.text),baseline=parseSliceYaml(selected.engineering_baseline.text);
+  const actual=path.resolve(registration.local_worktree,registration.project_root||'.');
+  check(path.resolve(projectRoot)===actual,'工程根与逐仓登记冲突');
+  const project=preparation.projects.filter(p=>p.project_id===registration.project_id&&p.repository_ref===selected.implementation_repository.ref);
+  check(project.length===1&&project[0].status!=='not-applicable'&&path.resolve(project[0].project_root)===actual,'准备结果没有唯一当前工程');
+  const identityKey=JSON.stringify([registration.repository_id,registration.project_id]);check(!identities.has(identityKey),'同一仓库工程不能重复绑定');identities.add(identityKey);
+  check(registration.status==='current'&&baseline.status==='current','逐仓登记或基线非 current');
+  check(registration.repository_id===baseline.repository_id&&registration.project_id===baseline.project_id,'逐仓基线身份冲突');
+  check(Array.isArray(registration.allowed_write_paths)&&registration.allowed_write_paths.length,'登记缺少写边界');
+  if(project[0].delivery_role==='backend')check(selected.technical_design&&project[0].design_prerequisites.technical_design.digest===selected.technical_design.digest&&project[0].design_prerequisites.technical_design.ref===selected.technical_design.ref,'多项目准备与切片技术设计绑定冲突');
+  const identity=baseline.architecture_identity||registration.architecture_identity;
+  if(baseline.architecture_identity&&registration.architecture_identity)check(digest(baseline.architecture_identity)===digest(registration.architecture_identity),'逐仓架构冲突');
+  const basis=Object.fromEntries(references.map(([name,key])=>[name,resolveSliceBasis(contract,key)]));
+  basis.repository_registration??=basis.implementation_repository;
+  selected.repository_registration??=selected.implementation_repository;
+  const resolution={...contract.resolution};delete resolution.architecture_identity;
+  if(identity){resolution.architecture_identity=identity;resolution.architecture_identity_digest=digest(identity).slice(7);resolution.architecture_evidence=sliceArchitectureEvidence({basis,resolution},selected);}
+  if(basis.technical_design)resolution.technical_design=basis.technical_design;
+  if(basis.frontend_delivery)resolution.frontend_delivery={acceptance_ref:basis.frontend_delivery.ref,digest:basis.frontend_delivery.digest};
+  result[projectRoot]={registration,project:project[0],basis,resolution,recipe_refs:keys.recipe_refs,capability_refs:keys.capability_refs};
+ }
+ check(Object.keys(result).length===contract.scope.project_roots.length&&contract.scope.project_roots.every(p=>result[p]),'多仓绑定必须完整覆盖工程根');
+ for(const key of ['delivery_order','rollback_order'])check(contract.extensions.cross_repo[key].length===Object.keys(result).length&&contract.extensions.cross_repo[key].every(p=>result[p]),`${key} 必须完整且唯一列出工程根`);
+ for(const unit of contract.work_units) {
+  const repo=result[unit.project_root];check(repo,`工作单元 ${unit.id} 未选择唯一工程`);
+  check((unit.allowed_write_paths||contract.scope.allowed_write_paths).every(p=>repo.registration.allowed_write_paths.some(parent=>withinSlicePath(p,parent))),`工作单元 ${unit.id} 超出逐仓登记`);
+ }
+ return result;
+}