create-yss-spec 3.0.1 → 3.1.0

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

@@ -0,0 +1,259 @@
+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, archive, ROOT, sourceApprovalPolicy } 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 { 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}`); })();
+
+async function sourceApproval(record, roles, root) {
+  const options={rolesDoc:roles,requireApproved:true,root,read:ref=>readFileSync(safe(root,path.relative(root,ref).split(path.sep).join('/')))};
+  if (roles.user_decision_policy.gates.includes(record.gate_id)) {
+    ensure(existsSync(path.join(ROOT,'scripts/lib/user-decision.mjs')), '接收工具不支持源用户决定策略，请升级工具后验包');
+    const { assertUserDecisionRequirement } = await import('./user-decision.mjs');
+    assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,user_decision_ref:record.user_decision_ref},options);
+  }
+  validateApprovalRecord(record,options);
+}
+
+function snapshot(snapshot, source) {
+  ensure(snapshot?.context_ref === 'CONTEXT.md' && snapshot.context_schema_version === 1, '源 context snapshot 合同无效');
+  const terms = resolveContextTermRefs(source, snapshot.term_refs);
+  ensure(snapshot.document_digest === source.document_digest && snapshot.referenced_terms_digest === terms.referenced_terms_digest, '源 CONTEXT snapshot 摘要过期');
+}
+function checkDelta(handoff, source) {
+  const used = new Set();
+  for (const op of ['added','updated','deprecated']) for (const term of handoff.context_delta[op]) {
+    ensure(!used.has(term.term_ref), '术语增量跨分类重复'); used.add(term.term_ref);
+    ensure(handoff.source_context_snapshot.term_refs.includes(term.term_ref), `源 snapshot 未引用增量术语: ${term.term_ref}`);
+    const actual = source.terms_by_ref.get(term.term_ref);
+    ensure(actual, `源术语不存在: ${term.term_ref}`);
+    for (const key of ['term','meaning','english_identifier','context_id','forbidden_aliases']) ensure(own(actual[key],term[key]), `源术语增量不一致: ${term.term_ref}.${key}`);
+  }
+}
+function localDependency(from, href) {
+  if (!href || /^(?:#|https?:|mailto:|data:)/i.test(href)) return null;
+  ensure(!/^[a-z][a-z0-9+.-]*:/i.test(href), `不支持的资源协议: ${href}`);
+  const clean = decodeURIComponent(href.split(/[?#]/)[0]);
+  ensure(!clean.startsWith('/'), `资源必须使用相对路径: ${href}`);
+  return relative(path.posix.normalize(path.posix.join(path.posix.dirname(from), clean)));
+}
+function documentLinks(ref, bytes) {
+  const text = String(bytes); const result = [];
+  if (/\.md$/i.test(ref)) for (const match of text.matchAll(/!?\[[^\]]*\]\(<?([^\s)>]+)>?(?:\s+[^)]*)?\)/g)) { const p=localDependency(ref,match[1]); if(p)result.push(p); }
+  return result;
+}
+function previewFiles(root, config) {
+  ensure(['H1','H2'].includes(config?.profile), 'package_export.prototype.profile 必须是 H1/H2');
+  const preview = safe(root, config.preview_root);
+  ensure(lstatSync(preview).isDirectory(), 'preview_root 必须为目录');
+  const entry = safe(root, config.entry_ref);
+  ensure(entry.startsWith(`${preview}${path.sep}`), '预览入口必须在 preview_root 内');
+  const included = files(root, config.preview_root);
+  // Structural closure plus an independently captured offline-browser receipt.
+  for (const ref of included.filter(x => /\.(html|css)$/i.test(x))) {
+    const text=readFileSync(safe(root,ref),'utf8');
+    const matches=[...text.matchAll(/(?:src|href)\s*=\s*["']([^"']+)["']/gi), ...text.matchAll(/url\(\s*["']?([^\s)'";]+)["']?\s*\)/gi)];
+    for (const match of matches) {
+      ensure(!/^(?:https?:)?\/\//i.test(match[1]), `离线预览包含远程资源: ${ref}`);
+      const dependency=localDependency(ref,match[1]); if(dependency)ensure(included.includes(dependency),`离线预览资源未打包: ${dependency}`);
+    }
+  }
+  if (config.profile === 'H2') {
+    safe(root,config.lock_ref); const source=safe(root,config.source_root);
+    ensure(lstatSync(source).isDirectory() && config.lock_ref.startsWith(`${config.source_root}/`), 'H2 缺少源码/锁文件');
+    ensure(!files(root,config.source_root).some(x => x.split('/').some(p => ['node_modules','.git'].includes(p))), 'H2 source_root 必须为不含依赖缓存的源码交付目录');
+    ensure(config.source_digest===treeDigest(root,config.source_root), 'H2 源码/锁文件批准摘要已过期');
+  }
+  ensure(config.verification_digest===hash(readFileSync(safe(root,config.verification_ref))), '离线验证记录批准摘要已过期');
+  const receipt=read(safe(root,config.verification_ref));
+  ensure(receipt.network_mode === 'offline' && receipt.exit_code === 0 && nonempty(receipt.command) && nonempty(receipt.executed_at) && Array.isArray(receipt.case_ids) && receipt.case_ids.length && Array.isArray(receipt.evidence_refs) && receipt.evidence_refs.length, '缺少实际离线浏览验证证据');
+  const tree=treeDigest(root,config.preview_root);
+  ensure(receipt.preview_digest===tree, '离线预览验证证据已过期');
+  for(const ref of receipt.evidence_refs)safe(root,ref);
+  return receipt;
+}
+
+export async function inspectSource(root, handoffRef) {
+  const handoff=read(safe(root,handoffRef));
+  schema(handoff,'docs/process/schemas/strategic-design-handoff.schema.json');
+  ensure(handoff.status==='approved', '交接包尚未批准');
+  const config=handoff.package_export;
+  schema(config,'docs/process/schemas/strategic-handoff-export.schema.json');
+  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));
+  const stage=read(safe(root,handoff.source.stage_decision_package_ref.persisted_ref));
+  schema(strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json');
+  schema(stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json');
+  snapshot(strategy.context_snapshot,source); snapshot(stage.context_snapshot,source);
+  ensure(strategy.status==='approved' && stage.status==='approved', '战略合同/方案决策包尚未批准');
+  ensure(strategy.domain_strategy_id===handoff.source.domain_strategy_ref.id && strategy.domain_version===handoff.source.domain_strategy_ref.version, '战略身份/版本不一致');
+  ensure(stage.stage_decision_id===handoff.source.stage_decision_package_ref.id && stage.package_version===handoff.source.stage_decision_package_ref.version, '阶段包身份/版本不一致');
+  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');
+  const indexes=extractTraceability(strategy);
+  const sourceRoles=read(safe(root,'docs/agents/digital-human-roles.yaml'));
+  const roles=sourceApprovalPolicy(sourceRoles);
+  for (const [artifact, version] of [[strategy,strategy.domain_version],[stage,stage.package_version]]) {
+    if(artifact.approval) { const record=read(safe(root,artifact.approval.approval_ref));await sourceApproval(record,roles,root);ensure(artifact.approval.current_version===version,'资产内置批准版本过期'); }
+  }
+  const terminalGate=countersignRuleForGate(roles.gate_policy,'gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
+  const expectedGates={domain_strategy_ref:'gate.domain-strategy-approved',stage_decision_package_ref:'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:'gate.user-confirmation',visual_baseline_ref:'gate.user-confirmation',business_ticket_set_ref:terminalGate,handoff:terminalGate};
+  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));
+    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(key!=='handoff')ensure(ref.digest===actual,`源资产摘要过期: ${key}`);
+    const record=read(safe(root,approval.record_ref));
+    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}`);
+  }
+  const receipt=previewFiles(root,config.prototype);
+  ensure(handoff.source.visual_baseline_ref.case_ids.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 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='') {
+    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'].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); }
+  }
+  while(queue.length) {
+    const ref=symbolic[queue[0]]||queue[0]; queue.shift(); if(/^https?:\/\//i.test(ref))continue; relative(ref);
+    if(collected.has(ref))continue;
+    const full=safe(root,ref),stat=lstatSync(full);
+    if(stat.isDirectory()) { queue.push(...files(root,ref)); continue; }
+    ensure(stat.isFile() && stat.size<=MAX_BYTES,`源文件类型/大小无效: ${ref}`);
+    const bytes=readFileSync(full); collected.set(ref,bytes);
+    ensure(collected.size<=20000 && [...collected.values()].reduce((n,b)=>n+b.length,0)<=MAX_BYTES,'交接包大小超限');
+    if(/\.(yaml|yml|json)$/.test(ref))refs(parse(bytes));
+    queue.push(...documentLinks(ref,bytes));
+  }
+  return collected;
+}
+function materialize(bundleRoot, manifest, destination) {
+  for(const file of manifest.files.filter(x=>x.original_ref))write(destination,file.original_ref,readFileSync(safe(bundleRoot,file.path)));
+}
+export async function openBundle(input, action) {
+  const temp=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); }
+    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),'包清单摘要不一致');
+    const paths=manifest.files.map(x=>x.path);
+    ensure(new Set(paths.map(x=>x.toLowerCase())).size===paths.length,'包文件路径重复');
+    ensure(own([...paths,'manifest.json'].sort(),files(root).sort()),'包文件缺失或存在未登记文件');
+    ensure(manifest.files.length<=20000 && manifest.files.reduce((n,f)=>n+f.size_bytes,0)<=MAX_BYTES,'包大小超限');
+    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);}
+    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(root,manifest,source);
+    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),'规则/场景索引与源资产不一致');
+    const expected=collect(source,manifest.handoff_ref,inspected.handoff,inspected.config);
+    ensure(own([...expected.keys()].sort(),originals.sort()),'源快照闭包不一致');
+    const changes=read(safe(root,'indexes/changes.json'));
+    ensure(own(changes.previous_bundle,manifest.previous_bundle), '版本差异的前版绑定不一致');
+    let previousIndexes;
+    if(manifest.previous_bundle){
+      const previous=read(safe(root,'indexes/previous-manifest.json'));const{bundle_digest:previousDigest,...previousBody}=previous;
+      ensure(previousDigest===digest(previousBody)&&previousDigest===manifest.previous_bundle.digest&&previous.bundle_id===manifest.bundle_id&&previous.version===manifest.previous_bundle.version&&Number(previous.version.slice(1))<Number(manifest.version.slice(1)),'前版清单绑定无效');
+      previousIndexes={};
+      for(const kind of ['rules','scenarios']){const bytes=readFileSync(safe(root,`indexes/previous-${kind}.json`));const priorFile=previous.files.find(x=>x.path===`indexes/${kind}.json`);ensure(priorFile&&priorFile.sha256===hash(bytes)&&priorFile.size_bytes===bytes.length,'前版索引摘要无效');previousIndexes[kind]=parse(bytes);}
+    }
+    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});}
+}
+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}`);}}
+  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);
+  ensure(!existsSync(target) && (!zip||!existsSync(`${target}.zip`)),'输出已存在，禁止覆盖');
+  ensure(target!==root && !root.startsWith(`${target}${path.sep}`),'输出不能覆盖源仓');
+  mkdirSync(path.dirname(target),{recursive:true});
+  ensure(path.resolve(path.dirname(target))===path.dirname(target),'输出路径无效');
+  const staging=mkdtempSync(path.join(path.dirname(target),'.handoff-staging-'));
+  try {
+    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}`;
+      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(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));
+    await openBundle(staging,()=>null);
+    // Recheck every captured source byte before publishing the immutable directory.
+    for(const [ref,bytes]of snapshotFiles)ensure(hash(readFileSync(safe(root,ref)))===hash(bytes),`导出期间源文件变化: ${ref}`);
+    if(zip)archive('pack',staging,`${staging}.zip`);
+    ensure(!existsSync(target),'输出并发冲突');renameSync(staging,target);
+    if(zip)renameSync(`${staging}.zip`,`${target}.zip`);
+    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 importBundle({bundle,targetRoot}) {
+  const target=project(targetRoot);const context=parseContextContract({root:target});
+  return openBundle(bundle,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'));
+      ensure(receipt.bundle_digest===b.manifest.bundle_digest,'同 ID/version 内容冲突');
+      await openBundle(safe(dest,'package'),()=>null);
+      return {result:'already-imported',receipt_ref:`${rel}/import-receipt.json`};
+    }
+    const terms=[];
+    for(const operation of ['added','updated','deprecated'])for(const expected of b.handoff.context_delta[operation]) {
+      const actual=context.terms_by_ref.get(expected.term_ref);
+      const equal=actual&&['term','meaning','english_identifier','context_id','forbidden_aliases'].every(key=>own(expected[key],actual[key]));
+      terms.push({operation,term_ref:expected.term_ref,expected,current:actual||null,status:operation==='deprecated'?(actual?'pending':'matched'):(equal?'matched':actual?'conflict':'pending')});
+    }
+    const rows=[...b.indexes.rules.map(x=>({source_id:x.rule_id,source_digest:x.source_digest,kind:'rule'})),...b.indexes.scenarios.filter(x=>x.critical).map(x=>({source_id:x.scenario_id,source_digest:x.source_digest,kind:'scenario'}))].map(x=>({...x,disposition:'pending',tactical_refs:[],test_seam_refs:[],evidence_refs:[],dependent_slice_refs:[],dependency_status:'unknown'}));
+    mkdirSync(path.dirname(dest),{recursive:true});const stage=mkdtempSync(path.join(path.dirname(dest),'.import-staging-'));
+    try {
+      cpSync(b.root,path.join(stage,'package'),{recursive:true,errorOnExist:true,force:false});
+      const receipt={schema_version:1,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,status:'pending-context-reconciliation'};
+      write(stage,'import-receipt.json',json(receipt));write(stage,'context-reconciliation-draft.json',json({schema_version:1,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,target_context_digest:context.document_digest,terms}));
+      write(stage,'tactical-traceability-draft.json',json({schema_version:1,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows}));
+      write(stage,'upstream-change-impact.json',json({schema_version:1,previous_bundle:b.manifest.previous_bundle,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation',policy:'mark-dependent-tactical-and-slice-contracts-stale; unknown-dependency-blocks-all'}));
+      ensure(!existsSync(dest),'导入并发冲突');renameSync(stage,dest);
+      return {result:'imported-pending-reconciliation',receipt_ref:`${rel}/import-receipt.json`,traceability_ref:`${rel}/tactical-traceability-draft.json`};
+    }finally{rmSync(stage,{recursive:true,force:true});}
+  });
+}

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

@@ -4,6 +4,7 @@ import { parseDocument } from "../vendor/yaml.mjs";
 import { loadDigitalHumanRoles, taskPackageDefaults } from "./digital-human-roles.mjs";
 import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";
 import { loadMaintenanceCheckpoint, validateMaintenanceCheckpoint } from "./maintenance-intensity.mjs";
+import { assertImplementationDecision } from "./user-decision.mjs";
 import { validateNextRoute } from "./lifecycle-transition.mjs";
 import { LEGACY_TASK_PACKAGE_SCHEMA, TASK_PACKAGE_SCHEMA, validateTaskPackageSchema } from "./task-package-schema.mjs";
 
@@ -79,12 +80,18 @@ function validateCommon(value, registry, lifecycle) {
   if (completed) {
     if (!value.result || value.result.result !== "completed") fail("resolved/完成任务必须返回 result=completed 的 Workflow Execution Result");
     if (value.workflow_status !== "resolved") fail("result=completed 的任务包必须处于 resolved 状态");
-    for (const field of ["result_schema", "work_unit", "workflow_reference", "skill", "changed_files", "evidence_refs", "deferred_seams", "drift", "violation", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) {
+    for (const field of ["result_schema", "work_unit", "workflow_reference", "skill", "changed_files", "context_reconciliation", "evidence_refs", "deferred_seams", "drift", "violation", "new_impacts", "stale_candidates", "next_route", "blocking_signals"]) {
       if (value.result[field] === undefined) fail(`result=completed 时 ${field} 不能为空`);
     }
     if (value.result.result_schema !== "workflow-execution-result-v1") fail("result_schema 必须为 workflow-execution-result-v1");
     if (value.result.work_unit !== value.work_unit_id) fail("Workflow Execution Result.work_unit 必须与任务包 work_unit_id 一致");
-    const routeResult = validateNextRoute(value.result.work_unit, value.result.next_route);
+    const reconciliation = value.result.context_reconciliation;
+    const expectedReconciliationStatus = value.contract.kind === "template-maintenance" ? "not-applicable" : "reconciled";
+    if (reconciliation?.status !== expectedReconciliationStatus) fail(`result=completed 时 context_reconciliation.status 必须为 ${expectedReconciliationStatus}`);
+    assertReadableEvidenceRef(reconciliation.ref, "context_reconciliation.ref");
+    if (!value.result.evidence_refs.includes(reconciliation.ref)) fail("context_reconciliation.ref 必须包含在 result.evidence_refs 中");
+    if (expectedReconciliationStatus === "not-applicable" && !reconciliation.reason) fail("template-maintenance 的 context_reconciliation 必须说明 reason");
+    const routeResult = validateNextRoute(value.result.work_unit, value.result.next_route, value.result);
     if (routeResult.result !== "allowed") fail(`Workflow Execution Result next_route 非法: ${routeResult.blocking_signals.join(", ")}`);
     value.expected_evidence_files.forEach((ref) => assertReadableEvidenceRef(ref, "expected_evidence_files"));
     if (value.verification_results.length === 0) fail("已完成任务必须包含 verification_results");
@@ -169,6 +176,7 @@ function validateContract(value, registry, lifecycle) {
   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 不一致");
   for (const allowed of value.allowed_write_paths) if (!sliceUnit.allowed_write_paths.includes(allowed)) fail(`allowed_write_paths 未获 Slice Contract 授权: ${allowed}`);
+  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 });
 }
 
 export function validateTaskPackage(value, { rolesDoc, lifecycleDoc } = {}) {

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

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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";
+
+export function decisionError(code, detail) {
+  const error = new TypeError(`${code}: ${detail}`);
+  error.code = code;
+  throw error;
+}
+const requireText = (value, label) => {
+  if (typeof value !== "string" || !value.trim()) decisionError("user-decision-missing", label);
+};
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+  ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+export const decisionDigest = (value) => `sha256:${createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : JSON.stringify(canonical(value))).digest("hex")}`;
+export function requestDigest(request) {
+  const { presented_source, ...snapshot } = request;
+  return decisionDigest(snapshot);
+}
+export function decisionIO({ root = ROOT, read = (ref) => readFileSync(ref), ...rest } = {}) {
+  const resolve = (ref) => /^(?:https?:|\w+:\/\/)/.test(ref) ? ref : path.resolve(root, ref);
+  const bytes = (ref) => {
+    requireText(ref, "可读引用");
+    try { return read(resolve(ref)); } catch { decisionError("user-decision-source-unreadable", ref); }
+  };
+  const document = (ref) => {
+    const doc = parseDocument(String(bytes(ref)), { maxAliasCount: 0, uniqueKeys: true });
+    if (doc.errors.length || !doc.toJS()) decisionError("user-decision-source-invalid", ref);
+    return doc.toJS({ maxAliasCount: 0 });
+  };
+  return { root, bytes, document, ...rest };
+}
+
+// A capture preserves original author/time/text/reference. It is evidence, not an identity signature.
+function messageFromSource(source, io, policy) {
+  if (!source || !policy.source_kinds.includes(source.kind)) decisionError("user-decision-source-invalid", "需要原始消息、会话导出或用户确认文件");
+  const raw = io.bytes(source.ref);
+  if (decisionDigest(raw) !== source.digest) decisionError("user-decision-source-changed", source.ref);
+  const parsed = parseDocument(String(raw), { maxAliasCount: 0, uniqueKeys: true });
+  if (parsed.errors.length) decisionError("user-decision-source-invalid", source.ref);
+  const capture = parsed.toJS({ maxAliasCount: 0 });
+  if (capture?.source_kind !== source.kind || !Array.isArray(capture.messages)) decisionError("user-decision-source-invalid", "来源不是原始消息封装");
+  const matches = capture.messages.filter((message) => message.id === source.message_id);
+  if (matches.length !== 1) decisionError("user-decision-source-invalid", "消息 ID 缺失或重复");
+  const message = matches[0];
+  for (const field of ["principal_ref", "original_ref", "sent_at", "text"]) requireText(message[field], `原始消息 ${field}`);
+  if (!Number.isFinite(Date.parse(message.sent_at))) decisionError("user-decision-source-invalid", "原始消息时间无效");
+  return { ...message, _preceding_message: capture.messages[capture.messages.indexOf(message) - 1] };
+}
+
+export function renderDecisionRequest(request) {
+  return [
+    `决定请求 ${request.id} (${requestDigest(request)})`,
+    `提问者：${request.requester_ref}`,
+    ...request.items.flatMap((item) => [
+      `事项 ${item.id} / ${item.boundary}：${item.title}`,
+      `资产：${item.subject.ref}；版本：${item.subject.version}；摘要：${item.subject.digest}`,
+      `依据：${item.basis.map((asset) => `${asset.ref}@${asset.version} (${asset.digest})`).join("；") || "无额外依据"}`,
+      `关键变化：${item.changes}`,
+      `范围：${item.scope.join("；")}`,
+      `风险：${item.risks.join("；") || "已评估，无已知残余风险"}`,
+      `推荐方案：${item.recommendation}`,
+      `批准后动作：${item.next_actions.join("；")}`,
+      `回复负责人：${item.responder_ref}`,
+    ]),
+    "请明确批准、拒绝或提出修改；多事项回复须说明事项，或明确批准以上全部事项。",
+  ].join("\n");
+}
+
+function checkAsset(asset, io) {
+  if (decisionDigest(io.bytes(asset.ref)) !== asset.digest) decisionError("user-decision-stale", asset.ref);
+}
+
+export function validateUserDecision(record, options = {}) {
+  const io = decisionIO(options);
+  const policy = (options.rolesDoc || loadDigitalHumanRoles()).user_decision_policy;
+  validateJsonSchema(record, path.join(ROOT, "docs/process/schemas/user-decision.schema.json"), { label: "用户决定记录" });
+  const { request, responses } = record;
+  const originalRequest = messageFromSource(request.requester_source, io, policy);
+  if (originalRequest.actor_kind !== "biological-human" || originalRequest.principal_ref !== request.requester_ref) decisionError("user-decision-responder-mismatch", "提问者来源不匹配");
+  const presentation = messageFromSource(request.presented_source, io, policy);
+  const presentedFields = request.items.flatMap((item) => [item.title, item.subject.ref, item.subject.version, item.changes, item.recommendation, ...item.scope, ...item.risks, ...item.next_actions, ...item.basis.flatMap((asset) => [asset.ref, asset.version])]);
+  // Preserve equivalent historical presentations without requiring a new templated message.
+  if (presentation.text !== renderDecisionRequest(request) && !presentedFields.every((field) => presentation.text.includes(field))) decisionError("user-decision-presentation-mismatch", "原始展示未覆盖当前资产、版本、变化、风险、范围和后续动作");
+  if (Date.parse(presentation.sent_at) < Date.parse(originalRequest.sent_at)) decisionError("user-decision-source-invalid", "展示时间早于用户请求");
+  const items = new Map();
+  for (const item of request.items) {
+    if (items.has(item.id)) decisionError("user-decision-ambiguous", "事项 ID 重复");
+    items.set(item.id, item);
+    if (item.responder_ref !== request.requester_ref) {
+      const delegated = messageFromSource(item.delegation_source, io, policy);
+      if (delegated.actor_kind !== "biological-human" || delegated.principal_ref !== request.requester_ref || !delegated.text.includes(item.responder_ref) || !delegated.text.includes(item.id)) decisionError("user-decision-delegation-invalid", "负责人须有提问者指向该事项的指定原文");
+      if (Date.parse(delegated.sent_at) > Date.parse(presentation.sent_at)) decisionError("user-decision-delegation-invalid", "须先指定负责人再展示当前请求");
+    }
+  }
+  const outcomes = new Map();
+  const messageIds = new Set();
+  let previousTime = -Infinity;
+  for (const response of responses) {
+    const source = messageFromSource(response.source, io, policy);
+    const identity = `${response.source.ref}#${response.source.message_id}`;
+    if (messageIds.has(identity)) decisionError("user-decision-ambiguous", "回复消息重复");
+    messageIds.add(identity);
+    if (source.reply_to !== presentation.original_ref && source.request_digest !== requestDigest(request) && !(source._preceding_message?.original_ref === presentation.original_ref && source._preceding_message?.text === presentation.text)) decisionError("user-decision-subject-mismatch", "原始回复没有指向当前请求的来源关联");
+    if (source.actor_kind !== "biological-human" || source.principal_ref !== response.principal_ref || source.sent_at !== response.responded_at || source.text !== response.text) decisionError("user-decision-responder-mismatch", "记录与原始回复身份、时间或原文不一致");
+    if (response.request_digest !== requestDigest(request)) decisionError("user-decision-stale", "回复绑定的请求快照已变化");
+    const time = Date.parse(response.responded_at);
+    if (time < Date.parse(presentation.sent_at) || time < previousTime) decisionError("user-decision-source-invalid", "回复须在展示之后并按原始时间排序");
+    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));
+      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 && 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", "多事项不能用单项回复");
+    if (items.size > 1 && /^(继续|continue|go ahead)[。.!！\s]*$/i.test(response.text.trim())) decisionError("user-decision-ambiguous", "继续不能解释为批准全部事项");
+    if (response.selection === "explicit-all" && (response.item_ids.length !== items.size || [...items.keys()].some((id) => !response.item_ids.includes(id)))) decisionError("user-decision-ambiguous", "全部批准必须枚举全部事项");
+    for (const id of response.item_ids) {
+      const item = items.get(id);
+      if (!item) decisionError("user-decision-subject-mismatch", id);
+      if (item.responder_ref !== response.principal_ref) decisionError("user-decision-responder-mismatch", id);
+      if (response.decision === "approved" && (response.approved_scope.length === 0 || response.approved_scope.some((scope) => !response.item_ids.some((selected) => items.get(selected)?.scope.includes(scope))))) decisionError("user-decision-scope-mismatch", id);
+      const previous = outcomes.get(id);
+      if (response.decision === "approved" && previous?.decision === "approved") {
+        outcomes.set(id, { ...response, approved_scope: [...new Set([...previous.approved_scope, ...response.approved_scope])] });
+      } else outcomes.set(id, response);
+    }
+  }
+  const validated = [];
+  for (const expected of options.expected || []) {
+    requireText(expected.boundary, "当前决定边界");
+    requireText(expected.subject_ref, "当前资产引用");
+    if (!Array.isArray(expected.scope) || expected.scope.length === 0) decisionError("user-decision-scope-mismatch", "当前批准范围缺失");
+    const matches = request.items.filter((item) => item.boundary === expected.boundary && item.subject.ref === expected.subject_ref && expected.scope.every((scope) => item.scope.includes(scope)));
+    if (matches.length !== 1) decisionError("user-decision-subject-mismatch", expected.boundary);
+    const item = matches[0];
+    checkAsset(item.subject, io);
+    item.basis.forEach((asset) => checkAsset(asset, io));
+    const answer = outcomes.get(item.id);
+    if (!answer) decisionError("user-decision-response-required", item.id);
+    if (answer.decision !== "approved") decisionError("user-decision-not-approved", `${item.id}: ${answer.decision}`);
+    if (!expected.scope.every((scope) => answer.approved_scope.includes(scope))) decisionError("user-decision-scope-mismatch", item.id);
+    validated.push({ item_id: item.id, boundary: expected.boundary, principal_ref: answer.principal_ref, scope: expected.scope });
+  }
+  return { request_id: request.id, validated, outcomes: Object.fromEntries([...outcomes].map(([id, answer]) => [id, answer.decision])) };
+}
+
+export function verifyUserDecisionFile(ref, options = {}) {
+  const io = decisionIO(options);
+  requireText(ref, "user_decision_ref");
+  return validateUserDecision(io.document(ref), options);
+}
+
+export function assertUserDecisionRequirement(requirement, options = {}) {
+  if (!requirement) decisionError("user-decision-response-required", "缺少当前决定及其范围");
+  return verifyUserDecisionFile(requirement.user_decision_ref, { ...options, expected: [requirement] });
+}
+
+export function assertWorkUnitUserDecision(workUnit, state, options = {}) {
+  const policy = (options.rolesDoc || loadDigitalHumanRoles()).user_decision_policy;
+  const boundaries = [...(policy.work_unit_gates?.[workUnit] || []), ...(policy.work_units[workUnit] ? [policy.work_units[workUnit]] : [])];
+  for (const boundary of boundaries) {
+    const notApplicable = state?.user_decision_not_applicable?.find((item) => item.boundary === boundary);
+    // Only existing conditional technical gates may be untriggered; an executed business decision cannot be skipped.
+    if (workUnit === "work-unit.technical-analysis" && notApplicable?.reason?.trim()) continue;
+    const requirement = state?.user_decisions?.find((item) => item.boundary === boundary);
+    if (!requirement) decisionError("user-decision-response-required", boundary);
+    assertUserDecisionRequirement(requirement, options);
+  }
+}
+
+export function assertImplementationDecision(state, options = {}) {
+  const requirement = state?.user_decisions?.find((item) => item.boundary === "implementation-scope");
+  const ticketRef = state?.vertical_slice_ticket_ref;
+  if (!requirement || !requirement.scope?.includes(ticketRef)) decisionError("user-decision-scope-mismatch", "实施范围必须包含当前切片");
+  assertUserDecisionRequirement(requirement, options);
+  const io = decisionIO(options);
+  const manifest = io.document(requirement.subject_ref);
+  const slices = manifest.slices?.filter((slice) => slice.ticket_ref === ticketRef);
+  if (manifest.kind !== "implementation-scope" || slices?.length !== 1) decisionError("user-decision-subject-mismatch", "实施范围清单未绑定当前切片");
+  const slice = slices[0];
+  requireText(state.slice_contract_ref, "当前持久化 Slice 合同引用");
+  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;
+  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);
+  }
+  if (!Array.isArray(slice.baselines) || !slice.baselines.some((asset) => asset.ref === contract.lifecycle_refs?.engineering_baseline)) decisionError("user-decision-scope-mismatch", "工程基线缺失");
+  slice.baselines.forEach((asset) => checkAsset(asset, io));
+}
+
+export function scaffoldDecisionSnapshot(decision) {
+  const { user_confirmation, status, decision_inputs_digest, ...inputs } = decision;
+  return inputs;
+}
+export function assertScaffoldUserDecision(decision, options = {}) {
+  const confirmation = decision.user_confirmation || {};
+  const requirement = { boundary: "scaffold-choice", subject_ref: confirmation.decision_subject_ref, scope: [decision.project_id, decision.confirmed_architecture, decision.decision_inputs_digest], user_decision_ref: confirmation.user_decision_ref };
+  assertUserDecisionRequirement(requirement, options);
+  const io = decisionIO(options);
+  if (decisionDigest(io.document(requirement.subject_ref)) !== decisionDigest(scaffoldDecisionSnapshot(decision))) decisionError("user-decision-stale", "脚手架输入与用户所见快照不一致");
+}

package/template/scripts/strategic-handoff

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { exportBundle, openBundle, importBundle } from './lib/strategic-handoff.mjs';
+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 [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}));
+  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>');
+  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;}

package/template/scripts/sync-strategic-handoff-tools

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Main-template-owned shared handoff implementation; never edits runtime skill projections.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { inspectWorkingTreeScope } from './lib/repository-scope-policy.mjs';
+const root=path.resolve(import.meta.dirname,'..');
+const check=process.argv.includes('--check');
+const targets=['submodules/yss-harness-design-agent','submodules/yss-harness-dev-agent'];
+const shared=['scripts/strategic-handoff','scripts/verify-strategic-handoff-consumption','scripts/verify-strategic-handoff-package-scenarios','scripts/verify-strategic-context-import','scripts/verify-strategic-context-import-scenarios','scripts/lib/context-contract.mjs','docs/process/strategic-handoff-package.md','docs/process/schemas/strategic-design-handoff.schema.json',...readdirSync(path.join(root,'scripts/lib')).filter(x=>x.startsWith('strategic-handoff-')||x==='strategic-handoff.mjs').map(x=>`scripts/lib/${x}`),...readdirSync(path.join(root,'docs/process/schemas')).filter(x=>x.startsWith('strategic-handoff-')).map(x=>`docs/process/schemas/${x}`),...readdirSync(path.join(root,'scripts/fixtures/strategic-handoff')).map(x=>`scripts/fixtures/strategic-handoff/${x}`)];
+let differences=[];
+function sync(source,dest){const bytes=readFileSync(source);if(!existsSync(dest)||!bytes.equals(readFileSync(dest))){differences.push(path.relative(root,dest));if(!check){mkdirSync(path.dirname(dest),{recursive:true});writeFileSync(dest,bytes);}}if(!check&&path.basename(path.dirname(dest))==='scripts'&&!path.extname(dest))chmodSync(dest,0o755);}
+for(const kind of ['domain-strategy','stage-decision-package'])sync(path.join(root,`.agents/skills/yss-stage-decision/references/${kind}.schema.json`),path.join(root,`docs/process/schemas/strategic-handoff-${kind}.schema.json`));
+for(const target of targets){
+ if(!existsSync(path.join(root,target,'.git')))continue;
+ if(!check){const state=inspectWorkingTreeScope(root,{project_root:target,repository_scope:'git-submodule',checkout_state:'attached-branch'});if(!state.writable)throw new Error(`${target}: ${state.violation}`);}
+ for(const ref of new Set(shared))sync(path.join(root,ref),path.join(root,target,ref));
+}
+if(check&&differences.length){process.stderr.write(`交接工具同步漂移: ${differences.join(', ')}\n`);process.exitCode=1;}else process.stdout.write(`战略交接共享工具 ${check?'同步检查通过':`同步 ${differences.length} 文件`}\n`);

package/template/scripts/verify-approval-record

@@ -3,10 +3,11 @@ import { parseArgs } from "node:util";
 import { validateApprovalRecordFile } from "./lib/approval-record.mjs";
 
 try {
-  const { positionals } = parseArgs({ allowPositionals: true, strict: true });
-  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-approval-record <approval-record.yaml>");
-  validateApprovalRecordFile(positionals[0]);
-  process.stdout.write("会签记录校验通过\n");
+  const { positionals, values } = parseArgs({ allowPositionals: true, strict: true, options: { "require-approved": { type: "boolean" }, history: { type: "boolean" } } });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-approval-record [--require-approved | --history] <approval-record.yaml>");
+  if (values.history && values["require-approved"]) throw new TypeError("--history 不能用于当前批准校验");
+  validateApprovalRecordFile(positionals[0], { requireApproved: !values.history });
+  process.stdout.write(!values.history ? "会签及当前用户决定校验通过\n" : "会签记录结构校验通过（不构成放行）\n");
 } catch (error) {
   process.stderr.write(`会签记录校验失败: ${error.message}\n`);
   process.exitCode = 1;