create-yss-spec 3.3.7 → 3.4.1

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

@@ -1,11 +1,20 @@
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync, readFileSync, mkdirSync, writeFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { validateJsonSchemas } from './json-schema.mjs';
 import { parseDocument } from '../vendor/yaml.mjs';
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+// A v5 package keeps the source glossary as a snapshot, never a nested CONTEXT.md.
+// Only this fixed alias is supported, isolated to the current asynchronous reader.
+const sourceContextSnapshots = new AsyncLocalStorage();
+export function withSourceContextSnapshot(root, action) {
+  const roots = new Set(sourceContextSnapshots.getStore() || []);
+  roots.add(path.resolve(root));
+  return sourceContextSnapshots.run(roots, action);
+}
 export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
 export const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
 export const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
@@ -23,6 +32,7 @@ export function relative(ref) {
 }
 export function safe(root, ref, { missing = false } = {}) {
   relative(ref);
+  if (ref === 'CONTEXT.md' && sourceContextSnapshots.getStore()?.has(path.resolve(root))) ref = 'source-context.snapshot.md';
   let current = path.resolve(root);
   ensure(!existsSync(current) || !lstatSync(current).isSymbolicLink(), `根目录不能是 symlink: ${root}`);
   for (const part of ref.split('/')) {

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

@@ -1,31 +1,44 @@
 import { existsSync, lstatSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
 import path from 'node:path';
 import { tmpdir } from 'node:os';
-import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, schemaBatch, archive, ROOT, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
+import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, schemaBatch, archive, ROOT, sourceApprovalPolicy, withSourceContextSnapshot } from './strategic-handoff-io.mjs';
 import { parseContextSource, parseContextContract, resolveContextTermRefs } from './context-contract.mjs';
 import { countersignRuleForGate } from './digital-human-roles.mjs';
 import { validateApprovalRecord } from './approval-record.mjs';
 import { treeDigest } from './strategic-handoff-io.mjs';
-import { validateVisualBaseline } from '../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs';
+import { uiBaselineKind, uiBaselineRef, uiBaselineCaseIds, hasConsumerRoutes, validateHandoffUiBaseline } from './ui-baseline.mjs';
 import { extractTraceability, compareIndexes } from './strategic-handoff-rules.mjs';
 const MAX_BYTES = 512 * 1024 * 1024;
 const own = (a,b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 const nonempty = x => typeof x === 'string' && x.trim();
 const bytesDigest = (bytes, kind) => kind === 'canonical-json' ? digest(parse(bytes)) : kind === 'sha256-bytes' ? hash(bytes) : (() => { throw new TypeError(`未知摘要算法: ${kind}`); })();
-const HANDOFF_SCHEMAS = new Map([[3,'docs/process/schemas/strategic-design-handoff-v3.schema.json'],[4,'docs/process/schemas/strategic-design-handoff-v4.schema.json']]);
+const HANDOFF_SCHEMAS = new Map([[3,'docs/process/schemas/strategic-design-handoff-v3.schema.json'],[4,'docs/process/schemas/strategic-design-handoff-v4.schema.json'],[5,'docs/process/schemas/strategic-design-handoff-v5.schema.json']]);
 const SOURCE_SCHEMAS = new Map([
   [3,['docs/process/schemas/strategic-handoff-domain-strategy.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package.schema.json']],
   [4,['docs/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
+  [5,['docs/process/schemas/strategic-handoff-domain-strategy-v3.schema.json','docs/process/schemas/strategic-handoff-stage-decision-package-v3.schema.json']],
 ]);
 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);
 }
 
 function validateConsumerRoutes(handoff, stage) {
-  if(handoff.schema_version!==4)return;
+  if(!hasConsumerRoutes(handoff))return;
   const routes=new Map();
   for(const route of handoff.consumer_routes||[]){
     ensure(!routes.has(route.capability),`消费者能力重复: ${route.capability}`);
@@ -128,7 +141,8 @@ export async function inspectSource(root, handoffRef) {
   schema(handoff,versionSchema(handoff?.schema_version,HANDOFF_SCHEMAS,'Strategic Handoff'));
   ensure(handoff.status==='approved', '交接包尚未批准');
   const config=handoff.package_export;
-  schema(config,'docs/process/schemas/strategic-handoff-export.schema.json');
+  schema(config,handoff.schema_version===5?'docs/process/schemas/strategic-handoff-export-v2.schema.json':'docs/process/schemas/strategic-handoff-export.schema.json');
+  if(handoff.schema_version===5)ensure(config.ui_baseline_kind===uiBaselineKind(handoff),'交接与导出 UI 基线类型不一致');
   const source=parseContextSource(readFileSync(safe(root,'CONTEXT.md'),'utf8'));
   snapshot(handoff.source_context_snapshot,source); checkDelta(handoff,source);
   const strategy=read(safe(root,handoff.source.domain_strategy_ref.persisted_ref));
@@ -142,6 +156,7 @@ export async function inspectSource(root, handoffRef) {
   ensure(stage.domain_strategy_ref.domain_strategy_id===strategy.domain_strategy_id && stage.domain_strategy_ref.domain_version===strategy.domain_version && stage.domain_strategy_ref.status==='approved' && stage.domain_strategy_ref.persisted_ref===handoff.source.domain_strategy_ref.persisted_ref && stage.domain_strategy_ref.digest===digest(strategy), '阶段包引用的战略内容不一致');
   ensure(!(stage.unresolved_items || []).some(x=>x.type==='blocker'), '阶段包含 blocker');
   validateConsumerRoutes(handoff,stage);
+  if(uiBaselineKind(handoff)==='existing-ui-baseline')ensure(stage.impact_assessment?.ui===false,'existing-ui-baseline 不支持 UI 影响，返回产品设计');
   const indexes=extractTraceability(strategy);
   const sourceRoles=read(safe(root,'docs/agents/digital-human-roles.yaml'));
   const roles=sourceApprovalPolicy(sourceRoles);
@@ -152,22 +167,24 @@ export async function inspectSource(root, handoffRef) {
   const currentPlan = (roles.gate_policy.dual_digital_human || []).some(rule => rule.gate === 'gate.plan-approved');
   const terminalGate=currentPlan?'gate.plan-approved':countersignRuleForGate(roles.gate_policy,'gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
   const expectedGates={domain_strategy_ref:currentPlan?'gate.plan-approved':'gate.domain-strategy-approved',stage_decision_package_ref:currentPlan?'gate.plan-approved':'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',visual_baseline_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',business_ticket_set_ref:terminalGate,handoff:terminalGate};
+  expectedGates.existing_ui_baseline_ref=expectedGates.prototype_ref;
   const bindings={...handoff.source,handoff:{id:handoff.handoff_id,version:handoff.handoff_version,persisted_ref:handoffRef,status:'approved'}};
   for(const [key,ref] of Object.entries(bindings)) {
     const approval=config.approvals[key];
     ensure(approval,`缺少资产批准绑定: ${key}`);
     ensure(approval.gate_id===expectedGates[key],`资产使用错误批准门禁: ${key}`);
-    const bytes=key==='visual_baseline_ref'?null:readFileSync(safe(root,ref.persisted_ref));
+    const baselineKey=['visual_baseline_ref','existing_ui_baseline_ref'].includes(key);
     let actual;
-    if(key==='visual_baseline_ref') {
-      const baseline=read(safe(root,`${ref.persisted_ref}/${ref.manifest_ref}`));
-      const result=await validateVisualBaseline(baseline,{bundleRoot:safe(root,ref.persisted_ref)});
-      ensure(!result.errors.length,`视觉基线无效: ${result.errors.join('; ')}`);
-      ensure(baseline.baseline_id===ref.baseline_id && baseline.version===ref.version && own([...ref.case_ids].sort(),baseline.cases.map(x=>x.case_id).sort()),'视觉基线身份不一致');
-      actual=baseline.bundle.digest;
-    } else actual=bytesDigest(bytes,approval.digest_kind);
+    if(baselineKey) {
+      const validated=await validateHandoffUiBaseline(root,handoff);actual=validated.digest;
+      if(key==='existing_ui_baseline_ref') {
+        ensure(approval.digest_kind==='sha256-bytes','既有 UI 批准必须绑定 manifest 原字节');
+        ensure(roles.user_decision_policy.gates.includes(expectedGates.existing_ui_baseline_ref),'既有 UI 承接必须使用产品设计真实用户决定策略');
+      }
+    } else actual=bytesDigest(readFileSync(safe(root,ref.persisted_ref)),approval.digest_kind);
     if(key!=='handoff')ensure(ref.digest===actual,`源资产摘要过期: ${key}`);
     const record=read(safe(root,approval.record_ref));
+    if(key==='existing_ui_baseline_ref')ensure(record.subject_ref===`${ref.persisted_ref}/${ref.manifest_ref}`,'既有 UI 用户决定必须以当前 manifest 为批准主体');
     await sourceApproval(record,roles,root);
     ensure(record.gate_id===approval.gate_id,`批准门禁不匹配: ${key}`);
     ensure((record.artifact_bindings || []).some(x=>x.id===(ref.id||ref.baseline_id) && x.version===ref.version && x.digest===actual),`批准记录未绑定当前资产: ${key}`);
@@ -180,19 +197,22 @@ export async function inspectSource(root, handoffRef) {
     ensure(scope.delivery_ref && own(read(safe(root,scope.delivery_ref)),delivery), '交付范围清单未覆盖当前交接内容或风险');
     ensure(scope.assets?.some(asset=>asset.ref===scope.delivery_ref && asset.digest===hash(readFileSync(safe(root,scope.delivery_ref)))), '交接内容快照缺少批准覆盖');
     for (const [key,ref] of Object.entries(handoff.source)) {
-      const file=key==='visual_baseline_ref'?`${ref.persisted_ref}/${ref.manifest_ref}`:ref.persisted_ref;
+      const file=['visual_baseline_ref','existing_ui_baseline_ref'].includes(key)?`${ref.persisted_ref}/${ref.manifest_ref}`:ref.persisted_ref;
       const decisionBoundaries=key==='business_ticket_set_ref'?['gate.spec-baseline-approved',terminalGate]:[expectedGates[key]];
       ensure(scope.assets?.some(asset=>asset.ref===file && asset.version===ref.version && decisionBoundaries.includes(asset.boundary) && asset.digest===hash(readFileSync(safe(root,file)))), `交付范围清单遗漏当前资产: ${key}`);
     }
   }
-  const receipt=previewFiles(root,config.prototype);
-  ensure(handoff.source.visual_baseline_ref.case_ids.every(id=>receipt.case_ids.includes(id)), '离线验证未覆盖视觉基线 case');
+  if(uiBaselineKind(handoff)==='prototype') {
+    const receipt=previewFiles(root,config.prototype);
+    ensure(uiBaselineCaseIds(handoff).every(id=>receipt.case_ids.includes(id)), '离线验证未覆盖视觉基线 case');
+  }
   return {handoff,config,indexes,strategy,stage};
 }
 
 function collect(root, handoffRef, handoff, config) {
-  const collected=new Map(), queue=[handoffRef,'CONTEXT.md','docs/agents/digital-human-roles.yaml',...Object.values(handoff.source).map(x=>x.persisted_ref),...Object.values(config.approvals).map(x=>x.record_ref),...handoff.evidence_and_version_digests,...config.additional_files,config.prototype.preview_root,config.prototype.verification_ref];
-  if(config.prototype.profile==='H2')queue.push(config.prototype.source_root,config.prototype.lock_ref);
+  const collected=new Map(), queue=[handoffRef,'CONTEXT.md','docs/agents/digital-human-roles.yaml',...Object.values(handoff.source).map(x=>x.persisted_ref),...Object.values(config.approvals).map(x=>x.record_ref),...handoff.evidence_and_version_digests,...config.additional_files];
+  if(config.prototype)queue.push(config.prototype.preview_root,config.prototype.verification_ref);
+  if(config.prototype?.profile==='H2')queue.push(config.prototype.source_root,config.prototype.lock_ref);
   const symbolic=config.reference_map || {};
   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='') {
@@ -208,20 +228,23 @@ function collect(root, handoffRef, handoff, config) {
     ensure(stat.isFile() && stat.size<=MAX_BYTES,`源文件类型/大小无效: ${ref}`);
     const bytes=readFileSync(full); collected.set(ref,bytes); totalBytes += bytes.length;
     ensure(collected.size<=20000 && totalBytes<=MAX_BYTES,'交接包大小超限');
-    if(/\.(yaml|yml|json)$/.test(ref))refs(parse(bytes));
-    queue.push(...documentLinks(ref,bytes));
+    const localBaseline=uiBaselineKind(handoff)==='existing-ui-baseline'&&ref.startsWith(`${uiBaselineRef(handoff).persisted_ref}/`);
+    if(!localBaseline&&/\.(yaml|yml|json)$/.test(ref))refs(parse(bytes));
+    // The entire existing UI observation directory was validated as a byte-bound file set.
+    // Its copied source documentation is evidence, not governance dependency instructions.
+    if(!localBaseline)queue.push(...documentLinks(ref,bytes));
   }
   return collected;
 }
 function materialize(captured, manifest, destination) {
   for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,captured.get(file.path));
 }
-export async function openBundle(input, action) {
-  const temp=mkdtempSync(path.join(tmpdir(),'yss-handoff-'));
+export async function openBundle(input, action, {readOnly=false}={}) {
+  const temp=readOnly?null:mkdtempSync(path.join(tmpdir(),'yss-handoff-'));
   try {
     ensure(existsSync(input) && !lstatSync(input).isSymbolicLink(),'交接包不存在或是 symlink');
     let root=path.resolve(input);
-    if(lstatSync(root).isFile()){ root=path.join(temp,'unpacked');mkdirSync(root);archive('unpack',path.resolve(input),root); }
+    if(lstatSync(root).isFile()){ ensure(!readOnly,'readonly-extraction-required: 只读验证需要已展开目录');root=path.join(temp,'unpacked');mkdirSync(root);archive('unpack',path.resolve(input),root); }
     const manifest=read(safe(root,'manifest.json'));
     schema(manifest,'docs/process/schemas/strategic-handoff-package.schema.json');
     const {bundle_digest,...body}=manifest;ensure(bundle_digest===digest(body),'包清单摘要不一致');
@@ -233,7 +256,12 @@ export async function openBundle(input, action) {
     for(const file of manifest.files){const bytes=readFileSync(safe(root,file.path));ensure(bytes.length===file.size_bytes && hash(bytes)===file.sha256,`文件摘要不一致: ${file.path}`);if(file.original_ref)relative(file.original_ref);captured.set(file.path,bytes);}
     const originals=manifest.files.filter(x=>x.original_ref).map(x=>x.original_ref);
     ensure(new Set(originals.map(x=>x.toLowerCase())).size===originals.length,'源路径重复');
-    const source=path.join(temp,'source');mkdirSync(source);materialize(captured,manifest,source);
+    let source;
+    if(readOnly){
+      ensure(manifest.files.filter(file=>file.original_ref).every(file=>file.path===`payload/files/${file.original_ref==='CONTEXT.md'?'source-context.snapshot.md':file.original_ref}`),'readonly-source-layout-required: 原始源布局需要只读文件映射支持');
+      source=safe(root,'payload/files');
+    }else{source=path.join(temp,'source');mkdirSync(source);materialize(captured,manifest,source);}
+    const inspect=async()=>{
     const inspected=await inspectSource(source,manifest.handoff_ref);
     ensure(manifest.bundle_id===inspected.handoff.handoff_id && manifest.version===inspected.handoff.handoff_version,'包身份与源交接不一致');
     ensure(own(read(safe(root,'indexes/rules.json')),inspected.indexes.rules) && own(read(safe(root,'indexes/scenarios.json')),inspected.indexes.scenarios),'规则/场景索引与源资产不一致');
@@ -250,14 +278,16 @@ export async function openBundle(input, action) {
     }
     ensure(own(changes,{previous_bundle:manifest.previous_bundle,...compareIndexes(inspected.indexes,previousIndexes)}),'版本差异与实际索引不一致');
     return await action({root,manifest,...inspected,changes});
-  } finally {rmSync(temp,{recursive:true,force:true});}
+    };
+    return readOnly?await withSourceContextSnapshot(source,inspect):await inspect();
+  } finally {if(temp)rmSync(temp,{recursive:true,force:true});}
 }
 export async function exportBundle({sourceRoot,handoffRef,output,zip=false,previous}) {
   const root=project(sourceRoot); parseContextContract({root}); relative(handoffRef);
   const current=await inspectSource(root,handoffRef);
   let prior=null;
   if(previous)prior=await openBundle(previous, b=>({manifest:b.manifest,indexes:b.indexes,handoff:b.handoff,rulesBytes:readFileSync(safe(b.root,'indexes/rules.json')),scenariosBytes:readFileSync(safe(b.root,'indexes/scenarios.json'))}));
-  if(prior){ensure(prior.manifest.bundle_id===current.handoff.handoff_id,'前版属于不同交接');ensure(Number(current.handoff.handoff_version.slice(1))>Number(prior.manifest.version.slice(1)),'更新必须提升交接版本');for(const[key,ref]of Object.entries(current.handoff.source)){const old=prior.handoff.source[key];if(old.digest!==ref.digest)ensure(old.version!==ref.version,`源资产内容变化必须提升版本: ${key}`);}}
+  if(prior){ensure(prior.manifest.bundle_id===current.handoff.handoff_id,'前版属于不同交接');ensure(Number(current.handoff.handoff_version.slice(1))>Number(prior.manifest.version.slice(1)),'更新必须提升交接版本');for(const[key,ref]of Object.entries(current.handoff.source)){const old=prior.handoff.source[key];if(old&&old.digest!==ref.digest)ensure(old.version!==ref.version,`源资产内容变化必须提升版本: ${key}`);}}
   const previousBundle=prior?{bundle_id:prior.manifest.bundle_id,version:prior.manifest.version,digest:prior.manifest.bundle_digest}:null;
   const snapshotFiles=collect(root,handoffRef,current.handoff,current.config);
   const target=path.resolve(output);
@@ -270,12 +300,13 @@ export async function exportBundle({sourceRoot,handoffRef,output,zip=false,previ
     const entries=[];
     const put=(ref,bytes,original)=>{write(staging,ref,bytes);entries.push({path:ref,sha256:hash(bytes),size_bytes:bytes.length,...(original?{original_ref:original}:{})});};
     for(const [ref,bytes]of [...snapshotFiles].sort(([a],[b])=>a.localeCompare(b))) {
-      const dest=ref===handoffRef?'handoff.yaml':ref==='CONTEXT.md'?'payload/source-context.snapshot.md':`payload/files/${ref}`;
+      const dest=current.handoff.schema_version===5?`payload/files/${ref==='CONTEXT.md'?'source-context.snapshot.md':ref}`:ref===handoffRef?'handoff.yaml':ref==='CONTEXT.md'?'payload/source-context.snapshot.md':`payload/files/${ref}`;
       ensure(!dest.endsWith('/CONTEXT.md'),'只允许源根词汇快照，禁止嵌套 CONTEXT.md');put(dest,bytes,ref);
     }
     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));
@@ -288,9 +319,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'));
@@ -329,8 +419,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'}));
@@ -339,8 +431,8 @@ export async function importBundle({bundle,targetRoot}) {
         const coordinationRoute=b.handoff.consumer_routes.find(route=>route.capability==='delivery-coordination');
         if(capabilities.includes('backend-technical-design')&&backendRoute.activation!=='not-applicable')write(stage,'backend-technical-traceability-draft.json',json({schema_version:2,route_id:backendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows}));
         if(capabilities.includes('frontend-engineering-design')&&frontendRoute.activation!=='not-applicable'){
-          const preflight={schema_version:1,status:'draft',route_id:frontendRoute.route_id,capability:frontendRoute.capability,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,context_reconciliation_ref:'',visual_baseline_ref:`${rel}/package/payload/files/${b.handoff.source.visual_baseline_ref.persisted_ref}/${b.handoff.source.visual_baseline_ref.manifest_ref}`,source_rule_refs:rows.map(row=>row.source_id),backend_dependency:{mode:backendRoute.activation==='not-applicable'?'not-applicable':'required',route_id:backendRoute.route_id,...(backendRoute.activation==='not-applicable'?{reason:backendRoute.reason,impact_refs:backendRoute.impact_refs,evidence_refs:backendRoute.evidence_refs}:{})},ready_for_agent:false};
-          schema(preflight,'docs/process/schemas/frontend-strategic-preflight.schema.json');
+          const preflight={schema_version:b.handoff.schema_version===5?2:1,status:'draft',route_id:frontendRoute.route_id,capability:frontendRoute.capability,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,context_reconciliation_ref:'',...(b.handoff.schema_version===5?{ui_baseline_kind:uiBaselineKind(b.handoff),ui_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}:{visual_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}),source_rule_refs:rows.map(row=>row.source_id),backend_dependency:{mode:backendRoute.activation==='not-applicable'?'not-applicable':'required',route_id:backendRoute.route_id,...(backendRoute.activation==='not-applicable'?{reason:backendRoute.reason,impact_refs:backendRoute.impact_refs,evidence_refs:backendRoute.evidence_refs}:{})},ready_for_agent:false};
+          schema(preflight,b.handoff.schema_version===5?'docs/process/schemas/frontend-strategic-preflight-v2.schema.json':'docs/process/schemas/frontend-strategic-preflight.schema.json');
           write(stage,'frontend-strategic-preflight-draft.json',json(preflight));write(stage,'frontend-traceability-draft.json',json({schema_version:1,route_id:frontendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows:rows.map(({tactical_refs,test_seam_refs,...row})=>({...row,frontend_case_refs:[]}))}));
         }
         if(capabilities.includes('delivery-coordination')&&coordinationRoute.activation!=='not-applicable')write(stage,'consumer-status-index-draft.json',json({schema_version:1,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,routes:b.handoff.consumer_routes.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,consumer_status:route.activation==='not-applicable'?'not-applicable':'pending',receipt_refs:[],acceptance_refs:[],feedback_refs:[]}))}));

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

@@ -179,13 +179,21 @@ function validateContract(value, registry, lifecycle) {
   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 !== 1 || typeof slice.slice_id !== "string" || !slice.lifecycle_refs || !slice.readiness || !Array.isArray(slice.work_units)) fail("Slice Implementation Contract 缺少 schema_version/slice_id/lifecycle_refs/readiness/work_units");
+  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");
   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}`);
   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 || sliceUnit.task_package_ref !== value.work_unit_id) fail("任务包与 Slice Contract work_unit 不一致");
+  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}`);
+  // Older packages used the work-unit ID here; new packages bind a readable dispatch file.
+  if (sliceUnit.task_package_ref !== value.work_unit_id) {
+    const dispatchPath = assertSafeRelativePath(sliceUnit.task_package_ref, "Slice work_unit.task_package_ref");
+    if (!existsSync(dispatchPath)) fail("Slice task_package_ref 不可读");
+    const dispatched = parseDocument(readFileSync(dispatchPath, "utf8")).toJS();
+    for (const field of ["task_id", "work_unit_id", "actor_id", "role_id", "runtime_id"]) if (dispatched?.[field] !== value[field]) fail("Slice task_package_ref 与当前派发身份不一致");
+    if (JSON.stringify(dispatched.contract) !== JSON.stringify(value.contract) || JSON.stringify(dispatched.allowed_write_paths) !== JSON.stringify(value.allowed_write_paths)) fail("Slice task_package_ref 与当前合同或写范围不一致");
+  }
   if (value.execution_state === "Worker") assertImplementationDecision({ slice_contract_ref: contract.slice_contract_ref, vertical_slice_ticket_ref: slice.lifecycle_refs.ticket, user_decisions: value.user_decisions });
 }
 
@@ -223,7 +231,7 @@ export function validateTaskPackageSet(packages, options = {}) {
   packages.forEach((pkg) => validateTaskPackage(pkg, options));
   const slicePackages = packages.filter((pkg) => pkg.contract.kind === "slice-implementation");
   if (slicePackages.length > 0) {
-    const contracts = new Set(slicePackages.map((pkg) => `${pkg.contract.contract_id}@${pkg.contract.contract_version}`));
+    const contracts = new Set(slicePackages.map((pkg) => JSON.stringify([pkg.contract.contract_id, pkg.contract.contract_version])));
     if (contracts.size !== 1) fail("同一切片的任务包必须消费同一 contract_id/contract_version");
     const workers = new Set(slicePackages.filter((pkg) => pkg.execution_state === "Worker").map((pkg) => pkg.actor_id));
     slicePackages.filter((pkg) => pkg.execution_state === "Reviewer").forEach((pkg) => { if (workers.has(pkg.actor_id)) fail("Reviewer 不得与实现者使用同一 actor_id"); });

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

@@ -1,10 +1,11 @@
+import { assertApprovedExecutionContext, approvedExecutionBinding } from './approved-execution-context.mjs';
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { ROOT, read, safe, ensure, hash } from './strategic-handoff-io.mjs';
 
 // The compiler's synchronous boundary reruns the design verifier against current files.
-export function enforceTechnicalDesign(state = {}, { root = ROOT } = {}) {
+export function enforceTechnicalDesign(state = {}, { root = ROOT, execution, readOnly = false } = {}) {
   const binding = state.technical_design;
   const affected = (state.conditions || []).some(value => ['backend-technical-design-impact','tactical-domain','tactical-domain-impact','aggregate-impact','state-machine-impact','invariant-impact','consistency-impact','domain-event-impact','gateway-boundary-impact','persistence-mapping-impact'].includes(value));
   if (!binding && !affected) return;
@@ -13,11 +14,18 @@ export function enforceTechnicalDesign(state = {}, { root = ROOT } = {}) {
   const file = safe(root, binding.ref);
   ensure(hash(readFileSync(file)) === binding.digest, '技术设计绑定摘要漂移');
   const data = read(file);
+  if(data.design_scope==='engineering-only')ensure(!(state.conditions||[]).some(value=>['tactical-domain','tactical-domain-impact','aggregate-impact','state-machine-impact','invariant-impact','domain-event-impact','gateway-boundary-impact','persistence-mapping-impact'].includes(value)),'engineering-only 技术设计不能承接领域模型、业务状态或持久化映射影响');
   ensure(data.status === 'approved' && data.version === binding.version, '技术设计必须为批准且绑定版本');
   const family = data.schema_version === 1 && binding.legacy_ddd === true ? 'domain-driven' : data.architecture?.family;
   ensure(family && family === state.architecture_identity?.architecture_family, '技术设计与实现架构不匹配');
   const args = [path.join(ROOT, '.agents/skills/yss-technical-design/scripts/validate-technical-design.mjs'), file, '--root', root, '--slice', state.slice_id];
   if (binding.legacy_ddd === true) args.push('--legacy-ddd');
+  if(readOnly)args.push('--read-only');
+  if(execution){
+    assertApprovedExecutionContext(execution,{root,technicalDesign:data,architectureIdentity:state.architecture_identity,sliceId:state.slice_id});
+    const approved=approvedExecutionBinding(execution);
+    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 });
   ensure(verified.status === 0, `技术设计不可消费: ${verified.error?.message || verified.stderr}`);
 }

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

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { ensure, read, safe, hash } from './strategic-handoff-io.mjs';
+import { validateVisualBaseline } from '../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs';
+import { validateExistingUiBaseline } from './existing-ui-baseline.mjs';
+
+export function hasConsumerRoutes(handoff) { return [4,5].includes(handoff?.schema_version); }
+export function uiBaselineKind(handoff) {
+  ensure([3,4,5].includes(handoff?.schema_version),'未知 Strategic Handoff schema_version');
+  if(handoff.schema_version<5)return 'prototype';
+  ensure(['prototype','existing-ui-baseline'].includes(handoff.ui_baseline_kind),'未知 ui_baseline_kind');
+  return handoff.ui_baseline_kind;
+}
+export function uiBaselineRef(handoff) {
+  const kind=uiBaselineKind(handoff),ref=handoff.source?.[kind==='prototype'?'visual_baseline_ref':'existing_ui_baseline_ref'];
+  ensure(ref,'缺少 UI 基线引用');return ref;
+}
+export function uiBaselineCaseIds(handoff) { return uiBaselineRef(handoff).case_ids; }
+export function uiBaselineSourceKeys(handoff) { return uiBaselineKind(handoff)==='prototype'?['prototype_ref','visual_baseline_ref']:['existing_ui_baseline_ref']; }
+export async function validateHandoffUiBaseline(root,handoff) {
+  const kind=uiBaselineKind(handoff),ref=uiBaselineRef(handoff),file=safe(root,`${ref.persisted_ref}/${ref.manifest_ref}`),baseline=read(file);
+  const result=kind==='prototype'?await validateVisualBaseline(baseline,{bundleRoot:safe(root,ref.persisted_ref)}):validateExistingUiBaseline(baseline,{bundleRoot:safe(root,ref.persisted_ref)});
+  ensure(!result.errors.length,`UI 基线无效: ${result.errors.join('; ')}`);
+  // The immutable existing manifest records readiness; the caller verifies its current approval chain.
+  ensure((kind==='existing-ui-baseline'||baseline.status==='approved')&&baseline.baseline_id===ref.baseline_id&&baseline.version===ref.version&&JSON.stringify([...ref.case_ids].sort())===JSON.stringify(baseline.cases.map(item=>item.case_id).sort()),'UI 基线身份不一致');
+  return {kind,ref,baseline,digest:kind==='prototype'?baseline.bundle.digest:hash(readFileSync(file))};
+}

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

@@ -113,8 +113,11 @@ export function validateUserDecision(record, options = {}) {
     previousTime = time;
     if (response.decision === "approved") {
       const explicit = source.decision === "approved" && Array.isArray(source.item_ids) && response.item_ids.every((id) => source.item_ids.includes(id));
+      const contextualAll = response.selection === "explicit-all" && items.size > 1
+        && /是否\s*(?:明确)?(?:确认|批准|同意|接受)[^\n]{0,32}(?:以上)?全部\s*(?:\d+|[一二三四五六七八九十]+)?\s*(?:项|事项)/i.test(presentation.text)
+        && /^(?:确认|同意|批准|接受|可以|好的|好|yes|ok)[。.!！\s]*$/i.test(source.text.trim());
       if (!explicit && (!/(同意|批准|确认|接受|可以|好的|^好[。！!\s]*$|\b(?:approve|approved|agree|agreed|accept|yes|ok)\b)/i.test(source.text) || /(不同意|不批准|拒绝|反对|不要|需[要]?修改|请修改|暂不|reject|decline|do not approve|don't approve|disagree)/i.test(source.text))) decisionError("user-decision-ambiguous", "原文不能明确支持批准结论");
-      if (!explicit && response.selection === "explicit-all" && items.size > 1 && !/(全部|所有|\ball\b)/i.test(source.text)) decisionError("user-decision-ambiguous", "批量批准原文必须明确全部事项");
+      if (!explicit && !contextualAll && response.selection === "explicit-all" && items.size > 1 && !/(全部|所有|\ball\b)/i.test(source.text)) decisionError("user-decision-ambiguous", "批量批准原文必须明确全部事项，或直接回复明确询问全部事项的当前展示");
       if (!explicit && response.selection === "explicit-items" && items.size > 1 && response.item_ids.some((id) => !source.text.includes(id) && !source.text.includes(items.get(id)?.title))) decisionError("user-decision-ambiguous", "原文未指向所选事项");
     }
     if (response.selection === "single" && items.size !== 1) decisionError("user-decision-ambiguous", "多事项不能用单项回复");

package/template/scripts/preflight-delivery

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { read } from './lib/strategic-handoff-io.mjs';
+import { preflightDelivery, invalidPreflightInput } from './lib/delivery-preflight.mjs';
+
+let result;
+try {
+  const {values}=parseArgs({options:{input:{type:'string'},stage:{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()});
+} catch(error) { result=invalidPreflightInput(error.message); }
+process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
+process.exitCode=result.exit_code;

package/template/scripts/strategic-handoff

@@ -1,14 +1,31 @@
 #!/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) {
+  const root=path.resolve(values['source-root']),handoff=read(safe(root,values.handoff));
+  const required=handoff.schema_version===5&&handoff.ui_baseline_kind==='existing-ui-baseline';
+  ensure(!required||values['preflight-input'],'preflight-required: 既有 UI 战略导出必须提供 --preflight-input <file>；先按 docs/process/delivery-preflight.md 准备源资产清单并执行 export 阶段只读预检');
+  if(!values['preflight-input'])return;
+  const {preflightDelivery}=await import('./lib/delivery-preflight.mjs');
+  const input=read(path.resolve(values['preflight-input']));
+  ensure(!input.delivery_kind||input.delivery_kind==='strategic-handoff','preflight-scope-conflict: 战略导出只能使用 strategic-handoff 清单');
+  ensure(path.resolve(root,input.governance_root||'.')===root,'preflight-scope-conflict: 预检治理根与导出来源不同');
+  ensure(input.assets?.strategic_handoff?.ref===values.handoff,'preflight-scope-conflict: 预检未绑定本次导出的 handoff 源文件');
+  const result=await preflightDelivery({...input,delivery_kind:'strategic-handoff'},{stage:'export',root});
+  if(result.exit_code!==0){const error=new TypeError('delivery-preflight-blocked: 请按每项 recovery 补证，再从正常导出入口重试');error.preflight=result;throw error;}
+}
 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'}}});
+  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)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> [--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})}\n`);process.exitCode=1;}
+}catch(error){process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message,...(error.preflight?{preflight:error.preflight}:{})})}\n`);process.exitCode=1;}

package/template/scripts/sync-profile-skills

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyProfileSkillSync, loadProfileSyncConfig, planProfileSkillSync, reportProfileSkillSync } from "./lib/profile-skill-sync.mjs";
+import { applyProfileSkillSync, formatProfileSkillSync, loadProfileSyncConfig, planProfileSkillSync, reportProfileSkillSync } from "./lib/profile-skill-sync.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 try {
@@ -30,10 +30,9 @@ try {
   const report = reportProfileSkillSync(result);
   if (json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
   else {
-    process.stdout.write(`profile skills: ${report.profiles.join(", ")}\n`);
-    for (const [status, count] of Object.entries(report.counts)) process.stdout.write(`${status}: ${count}\n`);
-    for (const item of report.changes) process.stdout.write(`${item.profile}: ${item.status}: ${item.path}\n`);
-    for (const item of report.issues) process.stderr.write(`${item.profile}: ${item.status}: ${item.path ?? item.skill ?? item.message}\n`);
+    const output = formatProfileSkillSync(report, modes[0]);
+    process.stdout.write(output.stdout);
+    process.stderr.write(output.stderr);
   }
   if (args.includes("--check") && (plan.changes.length || plan.issues.length)) process.exitCode = 1;
   if (args.includes("--apply") && plan.issues.length) process.exitCode = 1;