create-yss-spec 3.3.8 → 3.4.3

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

@@ -0,0 +1,66 @@
+import {enforceHarnessTaskScope} from './harness-execution-scope.mjs';
+import { readFileSync } from 'node:fs';
+import { ROOT, hash, safe, digest } from './strategic-handoff-io.mjs';
+import { normalizeSliceContract, withinSlicePath, parseSliceYaml } from './slice-contract.mjs';
+import { createApprovedExecutionContext, assertApprovedExecutionContext } from './approved-execution-context.mjs';
+import { assertImplementationDecision } from './user-decision.mjs';
+import { taskPackageDefaults, loadDigitalHumanRoles } from './digital-human-roles.mjs';
+import { validateTaskPackageSchema } from './task-package-schema.mjs';
+const fail=message=>{throw new TypeError(message);};
+const equalArrays=(a,b)=>Array.isArray(a)&&a.length===b.length&&a.every((x,i)=>x===b[i]);
+function generateTaskPackageDefaults(roleId,overrides,{rolesDoc}={}) {
+  const defaults=taskPackageDefaults(roleId,rolesDoc||loadDigitalHumanRoles());
+  return {schema_version:1,role_id:roleId,skill_source:{registry_ref:'docs/agents/digital-human-roles.yaml',defaults_ref:`taskPackageDefaults(${roleId})`,core_skills:defaults.core_skills,forbidden_skills:defaults.forbidden_skills},...overrides};
+}
+
+/** Compile dispatch from the approved YAML. Only runtime identity and task ID come from the caller. */
+export function compileSliceTaskPackage(binding,{root=ROOT,work_unit_id,task_id,actor_id,runtime_id,execution_state='Worker',rolesDoc,user_decisions}={}) {
+  const actualRoles=parseSliceYaml(readFileSync(safe(root,'docs/agents/digital-human-roles.yaml')));
+  if(rolesDoc&&digest(rolesDoc)!==digest(actualRoles))fail('调用方不能替换接收端角色能力');
+  rolesDoc=actualRoles;
+  if(!actualRoles.runtimes.some(runtime=>runtime.id===runtime_id))fail('接收端不支持该 runtime_id');
+  const execution=createApprovedExecutionContext(binding,{root,work_unit_id});
+  const {contract}=assertApprovedExecutionContext(execution,{root});
+  if(contract.schema_version!==3)fail('v3 派发编译入口只接受 v3；v2 保留原派发路径');
+  const unit=contract.work_units.find(item=>item.id===work_unit_id);
+  if(!unit)fail('未找到指定 Slice 工作单元');
+  const checkpoint=readSliceDispatchApproval(root,binding.approval_ref);
+  const decisions=user_decisions||checkpoint.human_review?.user_decisions;
+  const output=generateTaskPackageDefaults(unit.role_id,{
+    task_id,work_unit_id,actor_id,runtime_id,execution_state,workflow_status:'not-started',stage_id:'stage.vertical-slice-implementation',
+    contract:{kind:'slice-implementation',contract_id:contract.contract_id,contract_version:contract.contract_version,status:'issued',contract_ref:binding.ref,slice_contract_ref:binding.ref,gate_refs:[binding.approval_ref]},
+    inputs:[binding.ref,...new Set(Object.values(contract.lifecycle_refs))],
+    objective:`${unit.behavior}（执行目录：${unit.project_root}；完整约束读取 ${binding.ref}）`,
+    allowed_write_paths:unit.allowed_write_paths,forbidden_actions:[...unit.work_unit.forbidden_patterns,'来源过期、越界、缺证据、验证失败或新增影响时停止并回交'],
+    expected_outputs:[unit.behavior],expected_evidence_files:unit.work_unit.expected_evidence,verification_commands:unit.work_unit.verification_commands,verification_results:[],
+    downstream_consumers:unit.downstream_consumers||['role.lifecycle-orchestrator'],convergence:{parent_work_unit:'work-unit.slice-implementation',convergence_ref:unit.convergence_ref||binding.approval_ref,conflict_escalation:'返回生命周期主控'},user_decisions:decisions
+  },{rolesDoc});
+  enforceHarnessTaskScope(output,{root});
+  validateTaskPackageSchema(output);
+  assertSliceV3TaskPackage(output,contract,{root});
+  return output;
+}
+function readSliceDispatchApproval(root,ref) {return parseSliceYaml(readFileSync(safe(root,ref)));}
+export function assertSliceV3TaskPackage(value,slice,{root=ROOT}={}) {
+  enforceHarnessTaskScope(value,{root});
+  const contract=value.contract;
+  const current=normalizeSliceContract(slice,{root});
+  const roles=parseSliceYaml(readFileSync(safe(root,'docs/agents/digital-human-roles.yaml'))),defaults=taskPackageDefaults(value.role_id,roles);
+  if(!roles.runtimes.some(runtime=>runtime.id===value.runtime_id)||!defaults.stages.includes(value.stage_id))fail('接收端角色或运行时不支持当前任务');
+  if(!equalArrays(value.skill_source.core_skills,defaults.core_skills)||!equalArrays(value.skill_source.forbidden_skills,defaults.forbidden_skills))fail('任务角色能力与接收端不一致');
+  const unit=current.work_units.find(item=>item.id===value.work_unit_id);
+  if(unit&&[unit.primary_skill,...(unit.supporting_skills||[])].some(skill=>defaults.forbidden_skills.includes(skill)))fail('工作单元使用接收角色禁用 Skill');
+  if(!unit||unit.role_id!==value.role_id||current.contract_id!==contract.contract_id||current.contract_version!==contract.contract_version)fail('任务身份与 Slice v3 不一致');
+  if(!Array.isArray(contract.gate_refs)||contract.gate_refs.length!==1)fail('Slice v3 派发需要唯一批准 checkpoint 引用');
+  const bytes=readFileSync(safe(root,contract.slice_contract_ref));
+  const execution=createApprovedExecutionContext({ref:contract.slice_contract_ref,digest:hash(bytes),id:current.contract_id,version:current.contract_version,approval_ref:contract.gate_refs[0]},{root,work_unit_id:value.work_unit_id});
+  assertApprovedExecutionContext(execution,{root,contract:current});
+  for(const allowed of value.allowed_write_paths)if(!unit.allowed_write_paths.some(parent=>withinSlicePath(allowed,parent)))fail('任务写范围超出 Slice v3');
+  for(const key of ['verification_commands','expected_evidence_files']) {
+    const required=key==='verification_commands'?unit.work_unit.verification_commands:unit.work_unit.expected_evidence;
+    if(!equalArrays(value[key],required))fail(`任务包遗漏或替换 Slice v3 ${key}`);
+  }
+  for(const item of unit.work_unit.forbidden_patterns)if(!value.forbidden_actions.includes(item))fail('任务包遗漏全局约束');
+  if(value.execution_state==='Worker')assertImplementationDecision({slice_contract_ref:contract.slice_contract_ref,vertical_slice_ticket_ref:current.lifecycle_refs.ticket,user_decisions:value.user_decisions},{root});
+  return value;
+}

package/template/scripts/lib/strategic-feedback.mjs

@@ -6,14 +6,14 @@ export async function verifyConsumerFeedback({root=process.cwd(),feedbackRef}={}
   project(root);const file=safe(root,feedbackRef),feedback=read(file);
   schema(feedback,'docs/process/schemas/strategic-consumer-feedback.schema.json');
   const receipt=read(safe(root,feedback.import_receipt_ref));
-  ensure(receipt.schema_version===2,'Consumer Feedback v1 只接受 Handoff v4 的 Import Receipt v2');
+  ensure([2,3].includes(receipt.schema_version),'Consumer Feedback v1 只接受 route-aware Import Receipt v2/v3');
   const base=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
   ensure(feedback.import_receipt_ref===`${base}/import-receipt.json`&&receipt.package_ref===`${base}/package`,'Consumer Feedback 导入收据路径无效');
   ensure(feedback.bundle.id===receipt.bundle_id&&feedback.bundle.version===receipt.version&&feedback.bundle.digest===receipt.bundle_digest,'Consumer Feedback 绑定的 bundle 身份或摘要不一致');
   const route=receipt.routes.find(item=>item.route_id===feedback.route_id);ensure(route&&route.activation!=='not-applicable','Consumer Feedback route_id 未被当前消费者激活');
   for(const ref of feedback.evidence_refs)ensure(readFileSync(safe(root,ref)).length>0,`Consumer Feedback evidence 为空: ${ref}`);
   return openBundle(safe(root,receipt.package_ref),bundle=>{
-    ensure(bundle.handoff.schema_version===4&&bundle.manifest.bundle_digest===receipt.bundle_digest,'Consumer Feedback 必须绑定当前 Handoff v4 包');
+    ensure([4,5].includes(bundle.handoff.schema_version)&&bundle.manifest.bundle_digest===receipt.bundle_digest,'Consumer Feedback 必须绑定当前 Handoff v4/v5 包');
     const source=[...bundle.indexes.rules.map(item=>({id:item.rule_id,digest:item.source_digest})),...bundle.indexes.scenarios.map(item=>({id:item.scenario_id,digest:item.source_digest}))].find(item=>item.id===feedback.source.id);
     ensure(source&&source.digest===feedback.source.digest,'Consumer Feedback source ID 或摘要不是当前包内容');
     return {result:'feedback-verified',feedback_ref:feedbackRef,feedback_digest:hash(readFileSync(file)),severity:feedback.severity,route_id:feedback.route_id,bundle_digest:receipt.bundle_digest};

package/template/scripts/lib/strategic-handoff-consumption.mjs

@@ -24,10 +24,10 @@ export async function verifyConsumption(data,{root=process.cwd(),sliceRef,consum
   const expectedBase=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
   ensure(binding.import_receipt_ref===`${expectedBase}/import-receipt.json` && receipt.package_ref===`${expectedBase}/package`,'导入收据路径与包身份不一致');
   ensure(binding.bundle_digest===receipt.bundle_digest,'战术绑定与导入收据摘要不一致');
-  if(receipt.schema_version===2){
+  if([2,3].includes(receipt.schema_version)){
     const capability=consumer==='frontend'?'frontend-engineering-design':'backend-technical-design';
     const route=receipt.routes.find(item=>item.capability===capability);
-    ensure(route&&route.activation!=='not-applicable'&&binding.route_id===route.route_id,`${capability} 未绑定当前 Handoff v4 route_id`);
+    ensure(route&&route.activation!=='not-applicable'&&binding.route_id===route.route_id,`${capability} 未绑定当前 Handoff v4/v5 route_id`);
   }
   const result=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,binding.context_reconciliation_ref)],{encoding:'utf8'});
   ensure(result.status===0,`目标术语对账未通过: ${result.error?.message || result.stderr}`);

package/template/scripts/lib/strategic-handoff.mjs

@@ -20,6 +20,18 @@ const SOURCE_SCHEMAS = new Map([
 ]);
 const CAPABILITIES=['backend-technical-design','frontend-engineering-design','delivery-coordination'];
 
+function deliveryReadme(handoff) {
+  const sources=Object.entries(handoff.source).sort(([a],[b])=>a.localeCompare(b)).map(([key,value])=>`- \`${key}\`: \`${value.persisted_ref}\` (${value.version}, ${value.digest})`);
+  const routes=handoff.consumer_routes.map(route=>`- \`${route.capability}\`: \`${route.activation}\` (${route.route_id})`);
+  const questions=handoff.tactical_design_questions.length?handoff.tactical_design_questions.map((_,index)=>`- tactical-design-question-${index+1}`).join('\n'):'- 无';
+  const deferred=handoff.deferred_decisions_and_ownership.length?handoff.deferred_decisions_and_ownership.map(item=>`- ${item.decision_id||item.id||'deferred-decision'} / ${item.owner||'owner-unset'}`).join('\n'):'- 无';
+  return `# 战略交接快照包\n\n此目录是由 Handoff v5 确定性生成的不可变研发交付件。业务正文保留在 \`payload/\`，本页只提供接收导航。\n\n## 范围\n\n- Handoff: \`${handoff.handoff_id}\`\n- Version: \`${handoff.handoff_version}\`\n- Schema: \`5\`\n\n## 来源资产\n\n${sources.join('\n')}\n\n## 消费者路线\n\n${routes.join('\n')}\n\n## 待决问题索引\n\n${questions}\n\n## 延期决定索引\n\n${deferred}\n\n## 接收命令\n\n\`\`\`bash\nscripts/strategic-handoff import --bundle <delivery-dir> --target-root <implementation-repository>\n\`\`\`\n`;
+}
+
+function isDeliveryDirectory(input) {
+  return existsSync(input) && lstatSync(input).isDirectory() && existsSync(path.join(input,'delivery-record.json'));
+}
+
 function versionSchema(version, schemas, label) {
   ensure(schemas.has(version), `${label} 未知 schema_version: ${String(version)}；支持版本: ${[...schemas.keys()].join(', ')}；请使用显式迁移器升级`);
   return schemas.get(version);
@@ -63,6 +75,17 @@ export async function sourceApproval(record, roles, root) {
     const { assertApprovalUserDecision } = await import('./user-decision-reuse.mjs');
     assertApprovalUserDecision(record, roles, options);
   }
+  // Older dedicated receivers retain their own lifecycle policy. Normalize only
+  // this already-verified source approval, without granting local capabilities.
+  if (record.continuation_ref) {
+    ensure(roles.user_decision_policy.gates.includes(record.gate_id), '未登记的源延续批准边界');
+    const reviewers = roles.gate_policy.continuation_reviews?.[record.gate_id];
+    ensure(reviewers?.includes(record.role_id) && record.drafter_principal_ref && record.drafter_principal_ref !== record.principal_ref, '源授权延续缺少独立审查身份');
+    options.rolesDoc = structuredClone(roles);
+    const policy = options.rolesDoc.gate_policy;
+    policy.dual_digital_human = (policy.dual_digital_human || []).filter(x => x.gate !== record.gate_id);
+    policy.digital_human_review = [...(policy.digital_human_review || []).filter(x => x.gate !== record.gate_id), { gate: record.gate_id, countersigners: reviewers }];
+  }
   validateApprovalRecord(record,options);
 }
 
@@ -205,7 +228,7 @@ function collect(root, handoffRef, handoff, config) {
   const enqueue=ref=> { if(symbolic[ref])queue.push(symbolic[ref]); else if(/^https?:\/\//i.test(ref))return; else if(ref.startsWith('evidence.'))throw new TypeError(`未解析 evidence ID: ${ref}`); else if(ref.includes('/') || /\.(?:md|yaml|json|html|png|txt|log)$/.test(ref))queue.push(ref); };
   function refs(value,key='') {
     if(Array.isArray(value)) { if(key==='evidence_refs') value.forEach(enqueue); else value.forEach(v=>refs(v,key)); }
-    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref','decision_reuse_ref','scope_ref','subject_ref','delivery_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
+    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref','decision_reuse_ref','continuation_ref','plan_continuation_ref','scope_ref','subject_ref','delivery_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
   }
   let totalBytes = 0;
   while(queue.length) {
@@ -294,6 +317,7 @@ export async function exportBundle({sourceRoot,handoffRef,output,zip=false,previ
     put('indexes/rules.json',Buffer.from(json(current.indexes.rules)));
     put('indexes/scenarios.json',Buffer.from(json(current.indexes.scenarios)));
     put('indexes/changes.json',Buffer.from(json({previous_bundle:previousBundle,...compareIndexes(current.indexes,prior?.indexes)})));
+    if(current.handoff.schema_version===5)put('README.md',Buffer.from(deliveryReadme(current.handoff)));
     if(prior){put('indexes/previous-manifest.json',Buffer.from(json(prior.manifest)));put('indexes/previous-rules.json',prior.rulesBytes);put('indexes/previous-scenarios.json',prior.scenariosBytes);}
     const body={schema_version:1,bundle_id:current.handoff.handoff_id,version:current.handoff.handoff_version,handoff_ref:handoffRef,previous_bundle:previousBundle,files:entries.sort((a,b)=>a.path.localeCompare(b.path))};
     const manifest={...body,bundle_digest:digest(body)};write(staging,'manifest.json',json(manifest));
@@ -306,9 +330,68 @@ export async function exportBundle({sourceRoot,handoffRef,output,zip=false,previ
     return {result:'exported',bundle_id:manifest.bundle_id,version:manifest.version,bundle_digest:manifest.bundle_digest,output:target,...(zip?{zip:`${target}.zip`,zip_sha256:hash(readFileSync(`${target}.zip`))}:{})};
   } finally {rmSync(staging,{recursive:true,force:true});rmSync(`${staging}.zip`,{force:true});}
 }
+
+export async function openDelivery(input, action) {
+  const root=path.resolve(input);
+  ensure(isDeliveryDirectory(root),'交付目录缺少 delivery-record.json');
+  ensure(!lstatSync(root).isSymbolicLink(),'交付目录不能是 symlink');
+  const recordBytes=readFileSync(safe(root,'delivery-record.json'));
+  const record=parse(recordBytes);schema(record,'docs/process/schemas/strategic-handoff-delivery.schema.json');
+  const verification=read(safe(root,record.verification_ref));schema(verification,'docs/process/schemas/strategic-handoff-delivery-verification.schema.json');
+  const packageRoot=safe(root,record.package_ref);
+  ensure(lstatSync(packageRoot).isDirectory()&&!lstatSync(packageRoot).isSymbolicLink(),'package_ref 必须指向普通目录');
+  if(record.zip){const archiveRef=safe(root,record.zip.ref);ensure(lstatSync(archiveRef).isFile()&&hash(readFileSync(archiveRef))===record.zip.sha256,'ZIP 摘要不一致');}
+  else ensure(!existsSync(path.join(root,'package.zip')),'未登记的 package.zip');
+  const allowed=new Set(['delivery-record.json','verification.json',...(record.zip?['package.zip']:[])]);
+  for(const ref of files(root))ensure(ref.startsWith('package/')||allowed.has(ref),`交付目录存在未登记文件: ${ref}`);
+  return openBundle(packageRoot,async bundle=>{
+    ensure(record.handoff.id===bundle.manifest.bundle_id&&record.handoff.version===bundle.manifest.version&&record.handoff.schema_version===bundle.handoff.schema_version,'delivery record 的 Handoff 身份不一致');
+    ensure(record.bundle_digest===bundle.manifest.bundle_digest&&record.manifest_ref==='package/manifest.json','delivery record 的包摘要或清单引用不一致');
+    ensure(verification.bundle_digest===bundle.manifest.bundle_digest&&verification.package_ref===record.package_ref&&verification.manifest_ref===record.manifest_ref&&verification.exit_code===0&&verification.result==='verified','delivery verification 与包不一致');
+    const handoffEntry=bundle.manifest.files.find(file=>file.original_ref===record.handoff.ref);
+    ensure(handoffEntry&&handoffEntry.sha256===record.handoff.sha256,'delivery record 的 Handoff 源摘要不一致');
+    const sourceAssets=Object.entries(bundle.handoff.source).sort(([a],[b])=>a.localeCompare(b)).map(([sourceKey,value])=>({source_key:sourceKey,id:value.id||value.baseline_id,version:value.version,ref:value.persisted_ref,digest:value.digest}));
+    ensure(own(sourceAssets,record.source_assets),'delivery record 的来源资产不一致');
+    ensure(own(bundle.handoff.consumer_routes.map(({route_id,capability,activation})=>({route_id,capability,activation})),record.consumer_routes),'delivery record 的消费者路由不一致');
+    const previous=bundle.manifest.previous_bundle?{handoff_id:bundle.manifest.previous_bundle.bundle_id,version:bundle.manifest.previous_bundle.version,bundle_digest:bundle.manifest.previous_bundle.digest}:null;
+    ensure(own(previous,record.previous_delivery),'delivery record 的上一版本身份不一致');
+    return action({...bundle,deliveryRoot:root,packageRoot,record,recordBytes,verification});
+  });
+}
+
+export async function finalizeDelivery({sourceRoot,handoffRef,zip=false,previous}) {
+  const root=project(sourceRoot);parseContextContract({root});relative(handoffRef);
+  const current=await inspectSource(root,handoffRef);
+  ensure(current.handoff.schema_version===5,'migration-required: v3/v4 只允许历史 verify/import；修改或重新交付必须迁移到 Handoff v5 并重新批准');
+  const delivery=path.join(root,'docs/deliveries/strategic',current.handoff.handoff_id,current.handoff.handoff_version);
+  const parent=path.dirname(delivery);mkdirSync(parent,{recursive:true});
+  let previousPackage=previous;
+  if(previous&&isDeliveryDirectory(path.resolve(previous)))previousPackage=await openDelivery(path.resolve(previous),value=>value.packageRoot);
+  const stage=mkdtempSync(path.join(parent,'.delivery-staging-'));
+  try {
+    const exported=await exportBundle({sourceRoot:root,handoffRef,output:path.join(stage,'package'),zip,previous:previousPackage});
+    const handoffEntry=await openBundle(path.join(stage,'package'),bundle=>bundle.manifest.files.find(file=>file.original_ref===handoffRef));
+    ensure(handoffEntry,'交付包缺少 Handoff 源文件');
+    const verification={schema_version:1,kind:'strategic-delivery-verification-v1',result:'verified',command:`scripts/strategic-handoff verify --bundle docs/deliveries/strategic/${current.handoff.handoff_id}/${current.handoff.handoff_version}`,exit_code:0,executed_at:new Date().toISOString(),package_ref:'package',manifest_ref:'package/manifest.json',bundle_digest:exported.bundle_digest};
+    schema(verification,'docs/process/schemas/strategic-handoff-delivery-verification.schema.json');write(stage,'verification.json',json(verification));
+    const sourceAssets=Object.entries(current.handoff.source).sort(([a],[b])=>a.localeCompare(b)).map(([sourceKey,value])=>({source_key:sourceKey,id:value.id||value.baseline_id,version:value.version,ref:value.persisted_ref,digest:value.digest}));
+    const previousDelivery=await openBundle(path.join(stage,'package'),bundle=>bundle.manifest.previous_bundle?{handoff_id:bundle.manifest.previous_bundle.bundle_id,version:bundle.manifest.previous_bundle.version,bundle_digest:bundle.manifest.previous_bundle.digest}:null);
+    const record={schema_version:1,kind:'strategic-handoff-delivery-v1',status:'packaged',handoff:{id:current.handoff.handoff_id,version:current.handoff.handoff_version,ref:handoffRef,sha256:handoffEntry.sha256,schema_version:5},source_assets:sourceAssets,package_ref:'package',manifest_ref:'package/manifest.json',bundle_digest:exported.bundle_digest,verification_ref:'verification.json',consumer_routes:current.handoff.consumer_routes.map(({route_id,capability,activation})=>({route_id,capability,activation})),...(zip?{zip:{ref:'package.zip',sha256:exported.zip_sha256}}:{}),previous_delivery:previousDelivery};
+    schema(record,'docs/process/schemas/strategic-handoff-delivery.schema.json');write(stage,'delivery-record.json',json(record));
+    await openDelivery(stage,()=>null);
+    if(existsSync(delivery)){
+      const existing=await openDelivery(delivery,value=>value.record);
+      ensure(existing.bundle_digest===record.bundle_digest&&existing.handoff.sha256===record.handoff.sha256,'delivery-version-conflict: 同 Handoff ID/version 已存在不同内容；请提升 handoff_version 并重新批准');
+      return {result:'already-packaged',handoff_id:record.handoff.id,version:record.handoff.version,bundle_digest:record.bundle_digest,delivery};
+    }
+    renameSync(stage,delivery);
+    return {result:'packaged',handoff_id:record.handoff.id,version:record.handoff.version,bundle_digest:record.bundle_digest,delivery,...(zip?{zip:path.join(delivery,'package.zip'),zip_sha256:record.zip.sha256}:{})};
+  } finally {rmSync(stage,{recursive:true,force:true});}
+}
 export async function importBundle({bundle,targetRoot}) {
   const target=project(targetRoot);const context=parseContextContract({root:target});
-  return openBundle(bundle,async b=>{
+  const open=isDeliveryDirectory(path.resolve(bundle))?action=>openDelivery(path.resolve(bundle),action):action=>openBundle(bundle,action);
+  return open(async b=>{
     const rel=`docs/handoffs/${b.manifest.bundle_id}/${b.manifest.version}`,dest=safe(target,rel,{missing:true});
     if(existsSync(dest)) {
       const receipt=read(safe(dest,'import-receipt.json'));
@@ -347,8 +430,10 @@ export async function importBundle({bundle,targetRoot}) {
           if(route.activation!=='not-applicable'&&route.capability==='delivery-coordination')artifactRefs.push(`${rel}/consumer-status-index-draft.json`);
           return {route_id:route.route_id,capability:route.capability,activation:route.activation,artifact_refs:artifactRefs};
         });
-        receipt={schema_version:2,bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,package_ref:`${rel}/package`,target_context_digest:context.document_digest,target_profile_id:profile?.profile_id||'yss-full-lifecycle',selected_consumer_capabilities:capabilities,routes:routeRecords,status:'pending-context-reconciliation'};
-        schema(receipt,'docs/process/schemas/strategic-handoff-import-receipt.schema.json');
+        const fromDelivery=Boolean(b.recordBytes);
+        if(fromDelivery)write(stage,'source-delivery-record.json',b.recordBytes);
+        receipt={schema_version:fromDelivery?3:2,bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,package_ref:`${rel}/package`,...(fromDelivery?{source_delivery_record_ref:`${rel}/source-delivery-record.json`,source_delivery_record_sha256:hash(b.recordBytes),ready_for_agent:false}:{}),target_context_digest:context.document_digest,target_profile_id:profile?.profile_id||'yss-full-lifecycle',selected_consumer_capabilities:capabilities,routes:routeRecords,status:'pending-context-reconciliation'};
+        schema(receipt,fromDelivery?'docs/process/schemas/strategic-handoff-import-receipt-v3.schema.json':'docs/process/schemas/strategic-handoff-import-receipt.schema.json');
         write(stage,'import-receipt.json',json(receipt));
         write(stage,'context-reconciliation-draft.json',json({schema_version:2,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,target_context_digest:context.document_digest,route_ids:selected.map(route=>route.route_id),terms}));
         write(stage,'upstream-change-impact.json',json({schema_version:2,previous_bundle:b.manifest.previous_bundle,routes:selected.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation'})),policy:'mark-only-known-dependent-contracts-stale; unknown-dependency-or-design-basis-change-blocks-all'}));

package/template/scripts/lib/task-package.mjs

@@ -1,3 +1,6 @@
+import { normalizeSliceContract } from './slice-contract.mjs';
+import { assertSliceV3TaskPackage } from './slice-task-package.mjs';
+export { compileSliceTaskPackage, assertSliceV3TaskPackage } from './slice-task-package.mjs';
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
@@ -178,11 +181,12 @@ function validateContract(value, registry, lifecycle) {
   const contractPath = assertSafeRelativePath(contract.slice_contract_ref, "contract.slice_contract_ref");
   if (!existsSync(contractPath)) fail(`Slice Implementation Contract 不存在: ${contract.slice_contract_ref}`);
   const document = parseYaml(readFileSync(contractPath, "utf8"), "Slice Implementation Contract");
-  const slice = document.slice_contract || document;
-  if (slice.schema_version !== 2 || typeof slice.slice_id !== "string" || !slice.lifecycle_refs || !slice.readiness || !Array.isArray(slice.work_units)) fail("Slice Implementation Contract 需要 schema v2 及 slice_id/lifecycle_refs/readiness/work_units");
+  const slice = normalizeSliceContract(document,{root:ROOT});
+  if (![2,3].includes(slice.schema_version) || typeof slice.slice_id !== "string" || !slice.lifecycle_refs || !slice.readiness || !Array.isArray(slice.work_units)) fail("Slice Implementation Contract 需要 schema v2 及 slice_id/lifecycle_refs/readiness/work_units");
   if (slice.contract_id !== contract.contract_id || slice.contract_version !== contract.contract_version || slice.status !== "approved") fail("Slice Contract 必须是当前 approved 版本");
   const sliceUnit = slice.work_units.find((item) => item && item.id === value.work_unit_id);
   if (!sliceUnit) fail(`Slice Implementation Contract 缺少 work_unit_id: ${value.work_unit_id}`);
+  if(slice.schema_version===3)return assertSliceV3TaskPackage(value,slice,{root:ROOT});
   for (const field of ["role_id", "runtime_id", "task_package_ref", "contract_id", "contract_version", "allowed_write_paths"]) if (sliceUnit[field] === undefined) fail(`Slice Contract work_unit 缺少 ${field}`);
   if (sliceUnit.role_id !== value.role_id || sliceUnit.runtime_id !== value.runtime_id || sliceUnit.contract_id !== contract.contract_id || sliceUnit.contract_version !== contract.contract_version) fail("任务包与 Slice Contract work_unit 不一致");
   for (const allowed of value.allowed_write_paths) if (!sliceUnit.allowed_write_paths.includes(allowed)) fail(`allowed_write_paths 未获 Slice Contract 授权: ${allowed}`);

package/template/scripts/lib/technical-design-boundary.mjs

@@ -24,6 +24,7 @@ export function enforceTechnicalDesign(state = {}, { root = ROOT, execution, rea
   if(execution){
     assertApprovedExecutionContext(execution,{root,technicalDesign:data,architectureIdentity:state.architecture_identity,sliceId:state.slice_id});
     const approved=approvedExecutionBinding(execution);
+    if(approved.work_unit_id)args.push('--work-unit',approved.work_unit_id);
     args.push('--approved-slice',approved.ref,'--approved-slice-digest',approved.digest,'--approved-slice-approval',approved.approval_ref);
   }
   const verified = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 2 * 1024 * 1024 });

package/template/scripts/lib/user-decision-reuse.mjs

@@ -8,6 +8,7 @@ const sameSet = (a,b) => Array.isArray(a) && Array.isArray(b) && a.length === ne
 export function assertApprovalUserDecision(record, roles, options = {}) {
   const policy = roles.user_decision_policy;
   const io = decisionIO(options);
+  if (record.continuation_ref) return assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,continuation_ref:record.continuation_ref}, {...options,rolesDoc:roles});
   if (policy.required_capabilities?.some(id => id !== DECISION_REUSE_CAPABILITY)) fail('接收工具不支持源用户决定策略，请升级');
   if (!record.decision_reuse_ref) return assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,user_decision_ref:record.user_decision_ref}, {...options,rolesDoc:roles});
   if (record.gate_id !== 'gate.strategic-design-handoff-approved' || !policy.required_capabilities?.includes(DECISION_REUSE_CAPABILITY)) fail('未登记的复用边界或能力');

package/template/scripts/lib/user-decision.mjs

@@ -1,3 +1,4 @@
+import { normalizeSliceContract } from './slice-contract.mjs';
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -5,6 +6,7 @@ import { parseDocument } from "../vendor/yaml.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
 import { loadDigitalHumanRoles } from "./digital-human-roles.mjs";
 import { validateJsonSchema } from "./json-schema.mjs";
+import { assertDecisionContinuation } from './decision-continuation.mjs';
 
 export function decisionError(code, detail) {
   const error = new TypeError(`${code}: ${detail}`);
@@ -161,6 +163,7 @@ export function verifyUserDecisionFile(ref, options = {}) {
 
 export function assertUserDecisionRequirement(requirement, options = {}) {
   if (!requirement) decisionError("user-decision-response-required", "缺少当前决定及其范围");
+  if (requirement.continuation_ref) return assertDecisionContinuation(requirement, options.rolesDoc || loadDigitalHumanRoles(), options);
   return verifyUserDecisionFile(requirement.user_decision_ref, { ...options, expected: [requirement] });
 }
 
@@ -191,7 +194,7 @@ export function assertImplementationDecision(state, options = {}) {
   if (state.slice_contract_ref !== slice.contract?.ref) decisionError("user-decision-subject-mismatch", "当前合同不在批准清单中");
   checkAsset(slice.contract, io);
   const content = io.document(slice.contract.ref);
-  const contract = content.slice_contract || content;
+  const contract = content.slice_contract?.schema_version === 3 || content.schema_version === 3 ? normalizeSliceContract(content, { root: options.root || ROOT }) : content.slice_contract || content;
   if (contract.lifecycle_refs?.ticket !== ticketRef) decisionError("user-decision-subject-mismatch", "持久化合同的切片引用不匹配");
   for (const [manifestKey, contractKey] of [["repositories", "project_roots"], ["allowed_write_paths", "allowed_write_paths"]]) {
     if (!Array.isArray(slice[manifestKey]) || slice[manifestKey].length === 0 || JSON.stringify([...slice[manifestKey]].sort()) !== JSON.stringify([...(contract.common?.[contractKey] || [])].sort())) decisionError("user-decision-scope-mismatch", manifestKey);

package/template/scripts/preflight-delivery

@@ -6,9 +6,9 @@ import { preflightDelivery, invalidPreflightInput } from './lib/delivery-preflig
 
 let result;
 try {
-  const {values}=parseArgs({options:{input:{type:'string'},stage:{type:'string'},json:{type:'boolean'}},strict:true});
+  const {values}=parseArgs({options:{input:{type:'string'},stage:{type:'string'},'work-unit':{type:'string'},json:{type:'boolean'}},strict:true});
   if(!values.input||!values.stage) throw new TypeError('必须提供 --input <file> 和 --stage prepare|build|export|accept');
-  result=await preflightDelivery(read(path.resolve(values.input)),{stage:values.stage,root:process.cwd()});
+  result=await preflightDelivery(read(path.resolve(values.input)),{stage:values.stage,root:process.cwd(),work_unit_id:values['work-unit']});
 } catch(error) { result=invalidPreflightInput(error.message); }
 process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
 process.exitCode=result.exit_code;

package/template/scripts/slice-contract

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { prepareSliceImplementationContract, migrateSliceContractV2, persistSliceDraft } from './lib/slice-contract-preparation.mjs';
+import { renderSliceContractView, diffSliceContracts } from './lib/slice-contract-views.mjs';
+import { parseSliceYaml, readSliceContract } from './lib/slice-contract.mjs';
+
+try {
+  const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
+  for(let i=0;i<args.length;i++) {
+    if(args[i]==='--json'){options.json=true;continue;}
+    if(args[i].startsWith('--')) {
+      const key=args[i].slice(2);if(!['root','input','output','unit','before-root'].includes(key)||!args[i+1])throw new Error(`未知或缺值参数 ${args[i]}`);
+      options[key]=args[++i];
+    }else positional.push(args[i]);
+  }
+  const root=path.resolve(options.root||process.cwd());
+  let result;
+  if(mode==='prepare'||mode==='migrate') {
+    const input=options.input?parseSliceYaml(fs.readFileSync(path.resolve(root,options.input))):{};
+    if(mode==='prepare')result=prepareSliceImplementationContract({...input,root,ticket_ref:positional[0]});
+    else result=migrateSliceContractV2(readSliceContract(positional[0],{root}).raw,{...input,root});
+    if(options.output)persistSliceDraft(result,options.output,{root});
+    if(result.report.blockers.length)process.exitCode=1;
+  }else if(mode==='view')result=renderSliceContractView(positional[0],{root,unit_id:options.unit});
+  else if(mode==='diff')result=diffSliceContracts(positional[0],positional[1],{root,beforeRoot:options['before-root']?path.resolve(options['before-root']):root});
+  else if(mode==='verify')result={read_only:true,approval_validity:'not-checked',...readSliceContract(positional[0],{root}).binding};
+  else throw new Error('用法: scripts/slice-contract prepare <ticket> --input <补充.yaml> --output <新合同.yaml> | migrate <v2.yaml> --input <补充.yaml> --output <新合同.yaml> | view <合同.yaml> [--unit <id>] | diff <旧合同> <新合同> | verify <合同> [--root <项目根>]');
+  process.stdout.write(options.json||!result.markdown?`${JSON.stringify(result,null,2)}\n`:`${result.markdown}\n`);
+}catch(error){process.stderr.write(`${error.message}\n`);process.exitCode=1;}

package/template/scripts/strategic-handoff

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import path from 'node:path';
-import { exportBundle, openBundle, importBundle } from './lib/strategic-handoff.mjs';
+import { existsSync } from 'node:fs';
+import { exportBundle, finalizeDelivery, openBundle, openDelivery, importBundle } from './lib/strategic-handoff.mjs';
 import { read, safe, ensure } from './lib/strategic-handoff-io.mjs';
 
 async function preflightExport(values) {
@@ -21,9 +22,10 @@ try {
   const {values,positionals}=parseArgs({allowPositionals:true,strict:true,options:{'source-root':{type:'string'},handoff:{type:'string'},output:{type:'string'},zip:{type:'boolean'},previous:{type:'string'},bundle:{type:'string'},'target-root':{type:'string'},'preflight-input':{type:'string'}}});
   const [command]=positionals;
   let result;
-  if(command==='export'&&values['source-root']&&values.handoff&&values.output){await preflightExport(values);result=await exportBundle({sourceRoot:values['source-root'],handoffRef:values.handoff,output:values.output,zip:values.zip,previous:values.previous});}
-  else if(command==='verify'&&values.bundle)result=await openBundle(path.resolve(values.bundle),b=>({result:'verified',bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,rules:b.indexes.rules.length,scenarios:b.indexes.scenarios.length}));
+  if(command==='finalize'&&values['source-root']&&values.handoff){await preflightExport(values);result=await finalizeDelivery({sourceRoot:values['source-root'],handoffRef:values.handoff,zip:values.zip,previous:values.previous});}
+  else if(command==='export'&&values['source-root']&&values.handoff&&values.output){const sourceRoot=path.resolve(values['source-root']),handoff=read(safe(sourceRoot,values.handoff));ensure(handoff.schema_version===5,'migration-required: v3/v4 不再创建新 export；请迁移到 Handoff v5、重新批准并使用 finalize');await preflightExport(values);result=await exportBundle({sourceRoot:sourceRoot,handoffRef:values.handoff,output:values.output,zip:values.zip,previous:values.previous});}
+  else if(command==='verify'&&values.bundle){const input=path.resolve(values.bundle),action=b=>({result:'verified',bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,rules:b.indexes.rules.length,scenarios:b.indexes.scenarios.length});result=existsSync(path.join(input,'delivery-record.json'))?await openDelivery(input,action):await openBundle(input,action);}
   else if(command==='import'&&values.bundle&&values['target-root'])result=await importBundle({bundle:path.resolve(values.bundle),targetRoot:values['target-root']});
-  else throw new TypeError('用法: strategic-handoff export --source-root <repo> --handoff <relative-file> --output <new-dir> [--preflight-input <file>] [--zip] [--previous <bundle>] | verify --bundle <dir|zip> | import --bundle <dir|zip> --target-root <repo>');
+  else throw new TypeError('用法: strategic-handoff finalize --source-root <repo> --handoff <relative-file> [--preflight-input <file>] [--previous <delivery-or-package>] [--zip] | verify --bundle <delivery-dir|package-dir|zip> | import --bundle <delivery-dir|package-dir|zip> --target-root <repo>');
   process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
 }catch(error){process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message,...(error.preflight?{preflight:error.preflight}:{})})}\n`);process.exitCode=1;}

package/template/scripts/verify-backend-platform-matrix

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Maintenance-only candidate verification. Never updates the supported catalog or approvals.
+import { assertResumableCandidate } from "./lib/backend-platform-provenance.mjs";
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadBackendPlatforms, assertJavaPlatform, platformDigest } from "./lib/backend-platform.mjs";
+import { ScaffoldGenerator, parseArgs as dddArgs } from "../.agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs";
+import { generate, validateContract as validateMvcContract, parseArgs as mvcArgs } from "../.agents/skills/yss-layered-mvc-scaffold-generator/scripts/generate_scaffold.mjs";
+import { run } from "../.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs";
+
+const { values } = parseArgs({ options: { "evidence-dir": { type: "string" }, inputs: { type: "string" }, resume: { type: "boolean", default: false } }, strict: true });
+if (!values["evidence-dir"]) throw new Error("--evidence-dir is required; optional --inputs points to real approved contracts and candidate catalog");
+const evidence = path.resolve(values["evidence-dir"]);
+await mkdir(evidence, { recursive: true });
+const input = values.inputs ? JSON.parse(await readFile(path.resolve(values.inputs), "utf8")) : {};
+const inputRoot = values.inputs ? path.dirname(path.resolve(values.inputs)) : process.cwd();
+const catalog = input.catalog_ref ? JSON.parse(await readFile(path.resolve(inputRoot, input.catalog_ref), "utf8")) : loadBackendPlatforms();
+if (catalog.schema_version !== 1 || catalog.kind !== "backend-platform-catalog" || !Array.isArray(catalog.compatibility) || platformDigest(catalog.profiles) !== platformDigest(loadBackendPlatforms().profiles)) throw new Error("candidate input must preserve the maintained platform profiles; only supply actual YSS combinations");
+const keys = new Set();
+for (const item of input.combinations ?? []) {
+  const key = `${item.profile_id}:${item.spring_boot_version}:${item.architecture_family}`;
+  if (keys.has(key) || !catalog.profiles.some(p => p.id === item.profile_id && p.spring_boot_version === item.spring_boot_version) || !["domain-driven", "layered-mvc"].includes(item.architecture_family)) throw new Error("duplicate or unknown exact matrix combination");
+  keys.add(key);
+}
+const rows = [];
+for (const profile of loadBackendPlatforms().profiles) for (const family of ["domain-driven", "layered-mvc"]) {
+  const row = { profile_id: profile.id, spring_boot_version: profile.spring_boot_version, java_version: profile.java_version, architecture_family: family, status: "blocked", blockers: [], commands: [], executed_at: new Date().toISOString() };
+  const configuration = input.combinations?.find(item => item.profile_id === profile.id && item.spring_boot_version === profile.spring_boot_version && item.architecture_family === family);
+  for (const key of ["YSS_MAVEN_REPOSITORY_URL", "MAVEN_REPO_USERNAME", "MAVEN_REPO_PASSWORD"]) if (!process.env[key]) row.blockers.push(`missing environment: ${key}`);
+  if (!configuration?.contract_ref) row.blockers.push("missing real approved scaffold contract/YSS compatibility coordinates");
+  const javaHome = input.java_homes?.[String(profile.java_version)];
+  if (!javaHome) row.blockers.push(`missing explicit java_homes.${profile.java_version}`);
+  else {
+    try { const result = spawnSync(path.join(javaHome, "bin/java"), ["-version"], { encoding: "utf8" }); if (result.status !== 0) throw new Error("java -version failed"); assertJavaPlatform(`${result.stdout}\n${result.stderr}`, { java_version: profile.java_version }); row.java_preflight = "passed"; }
+    catch (error) {
+      row.blockers.push(`JDK preflight: ${error.message}`);
+    }
+  }
+  if (!row.blockers.length) {
+    const dir = path.join(evidence, `${profile.id}-${profile.spring_boot_version}-${family}-${Date.now()}`); await mkdir(dir, { recursive: true });
+    try {
+      const contractFile = path.resolve(inputRoot, configuration.contract_ref);
+      const contractBytes = await readFile(contractFile);
+      const contract = JSON.parse(contractBytes);
+      if (contract.architecture_family !== family || contract.platform_configuration?.profile_id !== profile.id || contract.platform_configuration?.spring_boot_version !== profile.spring_boot_version) throw new Error("matrix/contract identity mismatch");
+      const c = contract.maven_coordinates;
+      const pairs = { "project-name": contract.project_name, "base-package": contract.base_package, "output-dir": contract.target_output_dir, "contract-file": contractFile, "contract-id": contract.contract_id, "contract-version": contract.contract_version, "approval-ref": contract.lifecycle_approval_ref, "compiler-draft-ref": contract.compiler_draft_ref, "persisted-ref": contract.persisted_ref, "group-id": c.group_id, "project-version": c.project_version, "parent-group-id": c.parent.group_id, "parent-artifact-id": c.parent.artifact_id, "parent-version": c.parent.version, "yss-components-version": c.yss_components_version };
+      const args = Object.entries(pairs).flatMap(([key, value]) => [`--${key}`, String(value)]);
+      const platformOptions = { catalog, root: inputRoot, candidate: true };
+      if (values.resume) {
+        // Revalidate current approval/design sources without invoking any generation writes.
+        if (family === "domain-driven") await new ScaffoldGenerator(dddArgs(args), platformOptions).validateContractMetadata();
+        else await validateMvcContract(mvcArgs(args), "yss-layered-mvc-scaffold-generator", "layered-mvc-service", platformOptions);
+        assertResumableCandidate(path.join(contract.target_output_dir, contract.project_name), contract, contractBytes);
+      } else if (family === "domain-driven") await new ScaffoldGenerator(dddArgs(args), platformOptions).generate();
+      else await generate(mvcArgs(args), { platformOptions });
+      const report = await run(path.join(contract.target_output_dir, contract.project_name), dir, { ...process.env, JAVA_HOME: javaHome }, { timeoutMs: 180000, platformOptions });
+      await writeFile(path.join(dir, "scaffold-verification.json"), JSON.stringify(report, null, 2));
+      Object.assign(row, report, { evidence_ref: path.join(dir, "scaffold-verification.json") });
+    } catch (error) { row.blockers.push(error.message); }
+  }
+  rows.push(row);
+}
+const report = { schema_version: 1, kind: "backend-platform-matrix", generated_at: new Date().toISOString(), status: rows.every(row => row.status === "passed") ? "passed" : "blocked", combinations: rows };
+await writeFile(path.join(evidence, "platform-matrix.json"), JSON.stringify(report, null, 2));
+process.stdout.write(`${report.status}: ${path.join(evidence, "platform-matrix.json")}\n`);
+if (report.status !== "passed") process.exitCode = 1;