create-yss-spec 3.3.4 → 3.3.7

package/template/scripts/lib/profile-skill-sync.mjs

@@ -0,0 +1,336 @@
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function safe(root, relative, label = "path") {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative)) fail(`${label} 必须是仓库相对路径`);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  if (resolved === resolvedRoot || !resolved.startsWith(`${resolvedRoot}${path.sep}`)) fail(`${label} 越界: ${relative}`);
+  return resolved;
+}
+
+function files(directory, prefix = "") {
+  if (!existsSync(directory)) return new Map();
+  const info = lstatSync(directory);
+  if (!info.isDirectory()) fail(`技能源必须是目录: ${directory}`);
+  const result = new Map();
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) fail(`跨仓同步不接受符号链接: ${path.join(directory, entry.name)}`);
+    const absolute = path.join(directory, entry.name);
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      for (const item of files(absolute, relative)) result.set(...item);
+    } else if (entry.isFile()) result.set(relative, readFileSync(absolute));
+  }
+  return result;
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function sameTree(left, right) {
+  if (left.size !== right.size) return false;
+  for (const [name, content] of left) if (!right.get(name)?.equals(content)) return false;
+  return true;
+}
+
+function treeDigest(tree) {
+  const hash = createHash("sha256");
+  for (const [name, content] of [...tree.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+    hash.update(name);
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function patchedSource(root, profile, item) {
+  const source = safe(root, item.source ?? `.agents/skills/${item.id}`, "source");
+  const patchFile = safe(root, item.patch, "patch");
+  const sourceFiles = files(source);
+  const actualBaseline = treeDigest(sourceFiles);
+  if (actualBaseline !== item.source_tree_sha256) {
+    fail(`${profile}/${item.id} 适配基线冲突: 上游树预期 ${item.source_tree_sha256}，实际 ${actualBaseline}`);
+  }
+  const temporary = mkdtempSync(path.join(tmpdir(), "profile-skill-patch-"));
+  try {
+    for (const [name, content] of sourceFiles) {
+      const target = safe(temporary, name, "patch source file");
+      mkdirSync(path.dirname(target), { recursive: true });
+      writeFileSync(target, content);
+    }
+    const applied = spawnSync("git", ["apply", "--binary", "--whitespace=nowarn", patchFile], {
+      cwd: temporary,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (applied.status !== 0) fail(`${profile}/${item.id} 补丁无法重放: ${applied.stderr.trim()}`);
+    return files(temporary);
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function gitDirty(profileRoot, relativePaths) {
+  if (!relativePaths.length) return new Set();
+  const result = spawnSync("git", ["-C", profileRoot, "status", "--porcelain=v1", "--untracked-files=all", "--", ...relativePaths], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) fail(`无法读取目标工作树状态: ${result.stderr.trim()}`);
+  return new Set(result.stdout.split("\n").filter(Boolean).map((line) => line.slice(3).replace(/^"|"$/g, "")));
+}
+
+function dirtyMatch(dirty, relative) {
+  return [...dirty].some((entry) => entry === relative || entry.startsWith(`${relative}/`) || relative.startsWith(`${entry}/`));
+}
+
+function transformedSource(root, profile, item) {
+  const source = safe(root, item.source ?? `.agents/skills/${item.id}`, "source");
+  const sourceFiles = files(source);
+  const desired = item.files?.length
+    ? new Map(item.files.map((name) => {
+      if (!sourceFiles.has(name)) fail(`${profile}/${item.id} 适配源文件不存在: ${name}`);
+      return [name, sourceFiles.get(name)];
+    }))
+    : sourceFiles;
+  for (const replacement of item.replacements ?? []) {
+    const current = desired.get(replacement.file);
+    if (!current) fail(`${profile}/${item.id} 适配文件不存在: ${replacement.file}`);
+    const before = current.toString("utf8");
+    const count = before.split(replacement.from).length - 1;
+    const expected = replacement.count ?? 1;
+    if (count !== expected) fail(`${profile}/${item.id} 适配基线冲突: ${replacement.file} 中预期 ${expected} 处片段，实际 ${count} 处`);
+    desired.set(replacement.file, Buffer.from(before.split(replacement.from).join(replacement.to)));
+  }
+  return desired;
+}
+
+function compareTree(profile, id, targetRelative, current, desired, classification, changes) {
+  const names = new Set([...current.keys(), ...desired.keys()]);
+  for (const name of [...names].sort()) {
+    const before = current.get(name);
+    const after = desired.get(name);
+    if (before && after && before.equals(after)) continue;
+    changes.push({
+      profile,
+      skill: id,
+      classification,
+      status: before ? (after ? "updated" : "retired") : "added",
+      path: `${targetRelative}/${name}`,
+      before_sha256: before ? digest(before) : null,
+      after_sha256: after ? digest(after) : null,
+      content: after ?? null,
+    });
+  }
+}
+
+export function loadProfileSyncConfig(root, configPath = ".template-source/profile-skill-sync.json") {
+  const absolute = safe(root, configPath, "config");
+  const config = JSON.parse(readFileSync(absolute, "utf8"));
+  if (config.schema_version !== 1 || !config.profiles || typeof config.profiles !== "object") fail("profile skill sync 配置必须是 schema v1");
+  return config;
+}
+
+export function planProfileSkillSync({ root, config, selectedProfiles, dirtyProvider = gitDirty }) {
+  const names = selectedProfiles?.length ? selectedProfiles : Object.keys(config.profiles);
+  const canonicalRoot = safe(root, config.canonical_root ?? ".agents/skills", "canonical_root");
+  const changes = [];
+  const classifications = [];
+  const issues = [];
+  for (const profile of names) {
+    const definition = config.profiles[profile];
+    if (!definition) fail(`未知 profile: ${profile}`);
+    const profileRoot = safe(root, definition.target, `${profile}.target`);
+    if (!existsSync(path.join(profileRoot, "yss-project.yaml"))) issues.push({ profile, status: "missing_dependency", path: `${definition.target}/yss-project.yaml` });
+    const classified = new Map();
+    for (const [classification, items] of [
+      ["exact", (definition.exact ?? []).map(({ id }) => id)],
+      ["adapted", (definition.adapted ?? []).map(({ id }) => id)],
+      ["retired", definition.retired ?? []],
+      ["local-only", definition.local_only ?? []],
+      ["excluded", definition.excluded ?? []],
+      ["upstream", definition.upstream ?? []],
+    ]) {
+      for (const id of items) {
+        if (classified.has(id)) fail(`${profile}/${id} 同时声明为 ${classified.get(id)} 和 ${classification}，违反单向来源规则`);
+        classified.set(id, classification);
+      }
+    }
+    if (definition.upstream_manifest) {
+      const manifestPath = safe(root, definition.upstream_manifest, "upstream manifest");
+      if (!existsSync(manifestPath)) issues.push({ profile, status: "missing_dependency", path: definition.upstream_manifest });
+      else {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        const declared = [...(definition.upstream ?? [])].sort();
+        const manifestIds = (manifest.skills ?? []).map(({ canonical }) => canonical).sort();
+        if (JSON.stringify(declared) !== JSON.stringify(manifestIds) || manifest.source_root !== ".agents/skills") {
+          issues.push({ profile, status: "adaptation_conflict", path: definition.upstream_manifest, message: "上游清单与 profile 单向来源声明不一致" });
+        }
+      }
+    }
+
+    for (const item of definition.exact ?? []) {
+      const sourceRelative = item.source ?? `.agents/skills/${item.id}`;
+      const targetRelative = item.target ?? `.agents/skills/${item.id}`;
+      const source = safe(root, sourceRelative, "source");
+      if (!existsSync(source)) {
+        issues.push({ profile, skill: item.id, status: "missing_dependency", path: sourceRelative });
+        continue;
+      }
+      compareTree(profile, item.id, targetRelative, files(safe(profileRoot, targetRelative, "target")), files(source), "exact", changes);
+      classifications.push({ profile, skill: item.id, classification: "exact" });
+    }
+
+    for (const item of definition.adapted ?? []) {
+      classifications.push({ profile, skill: item.id, classification: "adapted" });
+      if (item.strategy === "profile-owned") {
+        const targetRelative = item.target ?? `.agents/skills/${item.id}`;
+        const skillFile = safe(profileRoot, `${targetRelative}/SKILL.md`, "adapted target");
+        if (!existsSync(skillFile)) issues.push({ profile, skill: item.id, status: "missing_dependency", path: `${definition.target}/${targetRelative}/SKILL.md` });
+        else {
+          const content = readFileSync(skillFile, "utf8");
+          for (const marker of item.required_markers ?? []) if (!content.includes(marker)) issues.push({ profile, skill: item.id, status: "adaptation_conflict", path: `${definition.target}/${targetRelative}/SKILL.md`, marker });
+        }
+        continue;
+      }
+      const targetRelative = item.target ?? `.agents/skills/${item.id}`;
+      let desired;
+      try {
+        const sourceRelative = item.source ?? `.agents/skills/${item.id}`;
+        if (!existsSync(safe(root, sourceRelative, "source"))) {
+          issues.push({ profile, skill: item.id, status: "missing_dependency", path: sourceRelative });
+          continue;
+        }
+        if (item.strategy === "replace") desired = transformedSource(root, profile, item);
+        else if (item.strategy === "patch") {
+          if (!item.patch || !existsSync(safe(root, item.patch, "patch"))) {
+            issues.push({ profile, skill: item.id, status: "missing_dependency", path: item.patch ?? "patch" });
+            continue;
+          }
+          desired = patchedSource(root, profile, item);
+        } else fail(`${profile}/${item.id} 未知适配策略`);
+      } catch (error) {
+        issues.push({ profile, skill: item.id, status: "adaptation_conflict", message: error.message });
+        continue;
+      }
+      const targetFiles = files(safe(profileRoot, targetRelative, "target"));
+      const current = item.files?.length ? new Map(item.files.filter((name) => targetFiles.has(name)).map((name) => [name, targetFiles.get(name)])) : targetFiles;
+      compareTree(profile, item.id, targetRelative, current, desired, "adapted", changes);
+    }
+
+    for (const item of definition.assets ?? []) {
+      const source = safe(root, item.source, "asset source");
+      const target = safe(profileRoot, item.target ?? item.source, "asset target");
+      if (!existsSync(source)) {
+        issues.push({ profile, status: "missing_dependency", path: item.source });
+        continue;
+      }
+      const before = existsSync(target) ? readFileSync(target) : null;
+      const after = readFileSync(source);
+      if (!before?.equals(after)) changes.push({ profile, classification: "exact", status: before ? "updated" : "added", path: item.target ?? item.source, before_sha256: before ? digest(before) : null, after_sha256: digest(after), content: after });
+    }
+
+    for (const id of definition.retired ?? []) {
+      classifications.push({ profile, skill: id, classification: "retired" });
+      const targetRelative = `.agents/skills/${id}`;
+      const current = files(safe(profileRoot, targetRelative, "retired target"));
+      for (const [name, content] of current) changes.push({ profile, skill: id, classification: "retired", status: "retired", path: `${targetRelative}/${name}`, before_sha256: digest(content), after_sha256: null, content: null });
+    }
+    for (const id of definition.local_only ?? []) classifications.push({ profile, skill: id, classification: "local-only" });
+    for (const id of definition.excluded ?? []) classifications.push({ profile, skill: id, classification: "excluded" });
+    for (const id of definition.upstream ?? []) classifications.push({ profile, skill: id, classification: "upstream" });
+
+    const targetSkillRoot = safe(profileRoot, ".agents/skills", "profile skill root");
+    if (existsSync(targetSkillRoot)) {
+      for (const entry of readdirSync(targetSkillRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || classified.has(entry.name)) continue;
+        const sourceSkill = path.join(canonicalRoot, entry.name);
+        if (!existsSync(sourceSkill) || !lstatSync(sourceSkill).isDirectory()) continue;
+        if (!sameTree(files(sourceSkill), files(path.join(targetSkillRoot, entry.name)))) {
+          issues.push({
+            profile,
+            skill: entry.name,
+            status: "unregistered_difference",
+            path: `${definition.target}/.agents/skills/${entry.name}`,
+            message: "同名 Skill 内容不同但未登记同步分类",
+          });
+        }
+      }
+    }
+
+    const changedPaths = [...new Set(changes.filter((item) => item.profile === profile).map((item) => item.path))];
+    const dirty = dirtyProvider(profileRoot, changedPaths);
+    for (const change of changes.filter((item) => item.profile === profile && dirtyMatch(dirty, item.path))) {
+      issues.push({ profile, skill: change.skill, status: "adaptation_conflict", path: `${definition.target}/${change.path}`, message: "目标含未提交改动" });
+    }
+  }
+  return { schema_version: 1, profiles: names, changes, classifications, issues };
+}
+
+export function applyProfileSkillSync({ root, config, plan, write = writeFileSync, remove = rmSync }) {
+  if (plan.issues.length) fail(`同步预检失败，共 ${plan.issues.length} 项问题`);
+  const snapshots = new Map();
+  const touched = [];
+  try {
+    for (const change of plan.changes) {
+      const profileRoot = safe(root, config.profiles[change.profile].target, "profile target");
+      const target = safe(profileRoot, change.path, "change target");
+      const current = existsSync(target) ? readFileSync(target) : null;
+      const currentHash = current ? digest(current) : null;
+      if (currentHash !== change.before_sha256) fail(`目标在预览后发生变化: ${change.profile}/${change.path}`);
+      snapshots.set(target, current);
+      touched.push(target);
+      if (change.content === null) remove(target, { force: true });
+      else {
+        mkdirSync(path.dirname(target), { recursive: true });
+        write(target, change.content);
+      }
+    }
+    for (const profile of plan.profiles) {
+      const profileRoot = safe(root, config.profiles[profile].target, "profile target");
+      for (const id of config.profiles[profile].retired ?? []) {
+        const retiredRoot = safe(profileRoot, `.agents/skills/${id}`, "retired skill");
+        if (!existsSync(retiredRoot)) continue;
+        if (!lstatSync(retiredRoot).isDirectory()) fail(`退役 Skill 目标不是目录: ${retiredRoot}`);
+        if (files(retiredRoot).size) fail(`退役 Skill 在预览后出现未纳管文件: ${retiredRoot}`);
+        remove(retiredRoot, { recursive: true, force: true });
+      }
+    }
+  } catch (error) {
+    for (const target of touched.reverse()) {
+      const before = snapshots.get(target);
+      if (before === null) remove(target, { force: true });
+      else {
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, before);
+      }
+    }
+    throw error;
+  }
+  return { ...plan, applied: plan.changes.length };
+}
+
+export function reportProfileSkillSync(plan) {
+  const counts = {};
+  for (const item of [...plan.changes, ...plan.issues]) counts[item.status] = (counts[item.status] ?? 0) + 1;
+  return { ...plan, changes: plan.changes.map(({ content, ...item }) => item), counts };
+}

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

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { openBundle } from './strategic-handoff.mjs';
+import { read, safe, ensure, hash, schema, project } from './strategic-handoff-io.mjs';
+
+export async function verifyConsumerFeedback({root=process.cwd(),feedbackRef}={}) {
+  project(root);const file=safe(root,feedbackRef),feedback=read(file);
+  schema(feedback,'docs/process/schemas/strategic-consumer-feedback.schema.json');
+  const receipt=read(safe(root,feedback.import_receipt_ref));
+  ensure(receipt.schema_version===2,'Consumer Feedback v1 只接受 Handoff v4 的 Import Receipt v2');
+  const base=`docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
+  ensure(feedback.import_receipt_ref===`${base}/import-receipt.json`&&receipt.package_ref===`${base}/package`,'Consumer Feedback 导入收据路径无效');
+  ensure(feedback.bundle.id===receipt.bundle_id&&feedback.bundle.version===receipt.version&&feedback.bundle.digest===receipt.bundle_digest,'Consumer Feedback 绑定的 bundle 身份或摘要不一致');
+  const route=receipt.routes.find(item=>item.route_id===feedback.route_id);ensure(route&&route.activation!=='not-applicable','Consumer Feedback route_id 未被当前消费者激活');
+  for(const ref of feedback.evidence_refs)ensure(readFileSync(safe(root,ref)).length>0,`Consumer Feedback evidence 为空: ${ref}`);
+  return openBundle(safe(root,receipt.package_ref),bundle=>{
+    ensure(bundle.handoff.schema_version===4&&bundle.manifest.bundle_digest===receipt.bundle_digest,'Consumer Feedback 必须绑定当前 Handoff v4 包');
+    const source=[...bundle.indexes.rules.map(item=>({id:item.rule_id,digest:item.source_digest})),...bundle.indexes.scenarios.map(item=>({id:item.scenario_id,digest:item.source_digest}))].find(item=>item.id===feedback.source.id);
+    ensure(source&&source.digest===feedback.source.digest,'Consumer Feedback source ID 或摘要不是当前包内容');
+    return {result:'feedback-verified',feedback_ref:feedbackRef,feedback_digest:hash(readFileSync(file)),severity:feedback.severity,route_id:feedback.route_id,bundle_digest:receipt.bundle_digest};
+  });
+}
+
+export async function verifyFeedbackAdjudication({root=process.cwd(),adjudicationRef}={}) {
+  project(root);const file=safe(root,adjudicationRef),adjudication=read(file);
+  schema(adjudication,'docs/process/schemas/strategic-feedback-adjudication.schema.json');
+  const feedbackFile=safe(root,adjudication.feedback.ref);ensure(hash(readFileSync(feedbackFile))===adjudication.feedback.digest,'Feedback Adjudication 绑定的 feedback digest 已失效');
+  const verified=await verifyConsumerFeedback({root,feedbackRef:adjudication.feedback.ref});
+  for(const ref of adjudication.evidence_refs)ensure(readFileSync(safe(root,ref)).length>0,`Feedback Adjudication evidence 为空: ${ref}`);
+  if(adjudication.approval_ref)ensure(readFileSync(safe(root,adjudication.approval_ref)).length>0,'Feedback Adjudication approval_ref 为空');
+  if(adjudication.decision==='amend')return {result:'blocked',decision:'amend',requires_new_handoff:true,invalidated_bundle_digest:verified.bundle_digest,next_work_unit:adjudication.return_work_unit,target_version:adjudication.target_version};
+  if(adjudication.decision==='defer'&&verified.severity==='blocking')return {result:'blocked',decision:'defer',requires_new_handoff:false,next_work_unit:adjudication.return_work_unit,target_version:adjudication.target_version};
+  return {result:'adjudicated',decision:adjudication.decision,may_continue:true,bundle_digest:verified.bundle_digest,target_version:adjudication.target_version};
+}

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

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

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

@@ -66,6 +66,7 @@ export function archive(command, source, destination) {
 export function sourceApprovalPolicy(source) {
   const roles=structuredClone(source);
   roles.user_decision_policy ||= {gates:[]};
+  ensure(!(roles.user_decision_policy.required_capabilities || []).some(id => id !== 'strategic-decision-reuse-v1'), '接收工具不支持源用户决定策略，请升级工具后验包');
   const policy=roles.gate_policy;
   for(const gate of policy.product_digital_human_with_biological_veto || []) {
     if(!(policy.biological_human||[]).includes(gate) && !(policy.digital_human_review||[]).some(x=>x.gate===gate) && !(policy.dual_digital_human||[]).some(x=>x.gate===gate)) {

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

@@ -12,13 +12,55 @@ 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 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']],
+]);
+const CAPABILITIES=['backend-technical-design','frontend-engineering-design','delivery-coordination'];
+
+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;
+  const routes=new Map();
+  for(const route of handoff.consumer_routes||[]){
+    ensure(!routes.has(route.capability),`消费者能力重复: ${route.capability}`);
+    ensure(![...routes.values()].some(item=>item.route_id===route.route_id),`消费者 route_id 重复: ${route.route_id}`);
+    routes.set(route.capability,route);
+  }
+  ensure(CAPABILITIES.every(capability=>routes.has(capability)),'Handoff v4 必须完整声明 backend、frontend 与 coordination 三条消费者路由');
+  const impact=stage.impact_assessment||{};
+  const mappingByCapability=new Map();
+  for(const mapping of stage.downstream_mapping||[]){
+    ensure(CAPABILITIES.includes(mapping.consumer_capability),`未知消费者能力: ${mapping.consumer_capability}`);
+    const values=mappingByCapability.get(mapping.consumer_capability)||[];values.push(mapping);mappingByCapability.set(mapping.consumer_capability,values);
+  }
+  const expected=(capability,required)=>required?'required':(mappingByCapability.get(capability)||[]).some(mapping=>mapping.propagation!=='not-applicable')?'optional':'not-applicable';
+  const backend=routes.get('backend-technical-design'),frontend=routes.get('frontend-engineering-design'),coordination=routes.get('delivery-coordination');
+  const backendActive=Boolean(impact.backend||impact.api||impact.data),frontendActive=Boolean(impact.frontend||impact.ui);
+  ensure(backend.activation===expected(backend.capability,backendActive),'backend 消费者路由与批准的 Backend/API/Data 影响矩阵不一致');
+  ensure(frontend.activation===expected(frontend.capability,frontendActive),'frontend 消费者路由与批准的 Frontend/UI 影响矩阵不一致');
+  ensure(coordination.activation===((backend.activation!=='not-applicable'||frontend.activation!=='not-applicable')?'required':'not-applicable'),'coordination 消费者路由与交付影响不一致');
+  const activeBackend=backend.activation!=='not-applicable';
+  ensure(own(frontend.dependencies,activeBackend?[backend.route_id]:[]),'frontend 路由依赖与 backend 路由不一致');
+  ensure(own(coordination.dependencies,[...(backend.activation!=='not-applicable'?[backend.route_id]:[]),...(frontend.activation!=='not-applicable'?[frontend.route_id]:[])]),'coordination 路由依赖与消费者路由不一致');
+  for(const route of routes.values())for(const dependency of route.dependencies)ensure([...routes.values()].some(item=>item.route_id===dependency),`消费者路由依赖悬空: ${dependency}`);
+  for(const [capability,mappings] of mappingByCapability)for(const mapping of mappings){
+    const route=routes.get(capability);
+    ensure(mapping.propagation==='not-applicable'?route.activation==='not-applicable':route.activation!=='not-applicable',`downstream mapping 与消费者路由影响不一致: ${mapping.mapping_id}`);
+  }
+}
 
 export 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);
+    const { assertApprovalUserDecision } = await import('./user-decision-reuse.mjs');
+    assertApprovalUserDecision(record, roles, options);
   }
   validateApprovalRecord(record,options);
 }
@@ -83,7 +125,7 @@ function previewFiles(root, config) {
 
 export async function inspectSource(root, handoffRef) {
   const handoff=read(safe(root,handoffRef));
-  schema(handoff,'docs/process/schemas/strategic-design-handoff.schema.json');
+  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');
@@ -91,13 +133,15 @@ export async function inspectSource(root, handoffRef) {
   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));
-  schemaBatch([[strategy,'docs/process/schemas/strategic-handoff-domain-strategy.schema.json'],[stage,'docs/process/schemas/strategic-handoff-stage-decision-package.schema.json']]);
+  const [strategySchema,stageSchema]=versionSchema(handoff.schema_version,SOURCE_SCHEMAS,'Strategic Handoff source');
+  schemaBatch([[strategy,strategySchema],[stage,stageSchema]]);
   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');
+  validateConsumerRoutes(handoff,stage);
   const indexes=extractTraceability(strategy);
   const sourceRoles=read(safe(root,'docs/agents/digital-human-roles.yaml'));
   const roles=sourceApprovalPolicy(sourceRoles);
@@ -128,6 +172,19 @@ export async function inspectSource(root, handoffRef) {
     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}`);
   }
+  if (roles.user_decision_policy.required_capabilities?.includes('strategic-decision-reuse-v1')) {
+    const record=read(safe(root,config.approvals.handoff.record_ref));
+    const scope=read(safe(root,record.subject_ref));
+    ensure(scope.kind==='strategic-delivery-scope' && scope.schema_version===1, '交接必须绑定独立的交付范围清单');
+    const {package_export,status,...delivery}=handoff;
+    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 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');
   return {handoff,config,indexes,strategy,stage};
@@ -140,7 +197,7 @@ function collect(root, handoffRef, handoff, config) {
   const enqueue=ref=> { if(symbolic[ref])queue.push(symbolic[ref]); else if(/^https?:\/\//i.test(ref))return; else if(ref.startsWith('evidence.'))throw new TypeError(`未解析 evidence ID: ${ref}`); else if(ref.includes('/') || /\.(?:md|yaml|json|html|png|txt|log)$/.test(ref))queue.push(ref); };
   function refs(value,key='') {
     if(Array.isArray(value)) { if(key==='evidence_refs') value.forEach(enqueue); else value.forEach(v=>refs(v,key)); }
-    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
+    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref','decision_reuse_ref','scope_ref','subject_ref','delivery_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
   }
   let totalBytes = 0;
   while(queue.length) {
@@ -251,12 +308,46 @@ export async function importBundle({bundle,targetRoot}) {
     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'}));
+      let receipt;
+      if(b.handoff.schema_version===3){
+        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'}));
+      }else{
+        const profileRef=path.join(target,'docs/process/harness-profile.yaml');
+        const profile=existsSync(profileRef)?read(profileRef):null;
+        const capabilities=profile?.handoff?.consumer_capabilities||CAPABILITIES;
+        ensure(Array.isArray(capabilities)&&capabilities.length&&capabilities.every(capability=>CAPABILITIES.includes(capability)),'目标 profile 未声明受支持的消费者能力');
+        const selected=b.handoff.consumer_routes.filter(route=>capabilities.includes(route.capability));
+        ensure(selected.length===capabilities.length,'目标 profile 的消费者能力在 Handoff v4 中缺失');
+        const commonRefs=[`${rel}/context-reconciliation-draft.json`,`${rel}/upstream-change-impact.json`];
+        const routeRecords=selected.map(route=>{
+          const artifactRefs=[...commonRefs];
+          if(route.activation!=='not-applicable'&&route.capability==='backend-technical-design')artifactRefs.push(`${rel}/backend-technical-traceability-draft.json`);
+          if(route.activation!=='not-applicable'&&route.capability==='frontend-engineering-design')artifactRefs.push(`${rel}/frontend-strategic-preflight-draft.json`,`${rel}/frontend-traceability-draft.json`);
+          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');
+        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'}));
+        const backendRoute=b.handoff.consumer_routes.find(route=>route.capability==='backend-technical-design');
+        const frontendRoute=b.handoff.consumer_routes.find(route=>route.capability==='frontend-engineering-design');
+        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');
+          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:[]}))}));
+      }
       ensure(!existsSync(dest),'导入并发冲突');renameSync(stage,dest);
-      return {result:'imported-pending-reconciliation',receipt_ref:`${rel}/import-receipt.json`,traceability_ref:`${rel}/tactical-traceability-draft.json`};
+      const traceabilityRef=b.handoff.schema_version===3?`${rel}/tactical-traceability-draft.json`:receipt.routes.find(route=>route.capability==='backend-technical-design')?.artifact_refs.find(ref=>ref.endsWith('backend-technical-traceability-draft.json'))||receipt.routes.find(route=>route.capability==='frontend-engineering-design')?.artifact_refs.find(ref=>ref.endsWith('frontend-traceability-draft.json'));
+      return {result:'imported-pending-reconciliation',receipt_ref:`${rel}/import-receipt.json`,...(traceabilityRef?{traceability_ref:traceabilityRef}:{})};
     }finally{rmSync(stage,{recursive:true,force:true});}
   });
 }

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

@@ -0,0 +1,38 @@
+import { assertUserDecisionRequirement, decisionIO, decisionDigest, decisionError } from './user-decision.mjs';
+
+export const DECISION_REUSE_CAPABILITY = 'strategic-decision-reuse-v1';
+const fail = detail => decisionError('user-decision-reuse-invalid', detail);
+const sameSet = (a,b) => Array.isArray(a) && Array.isArray(b) && a.length === new Set(a).size && b.length === new Set(b).size && JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+
+// A reuse record is a coverage proof, never a new reply or a substitute for one.
+export function assertApprovalUserDecision(record, roles, options = {}) {
+  const policy = roles.user_decision_policy;
+  const io = decisionIO(options);
+  if (policy.required_capabilities?.some(id => id !== DECISION_REUSE_CAPABILITY)) fail('接收工具不支持源用户决定策略，请升级');
+  if (!record.decision_reuse_ref) return assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,user_decision_ref:record.user_decision_ref}, {...options,rolesDoc:roles});
+  if (record.gate_id !== 'gate.strategic-design-handoff-approved' || !policy.required_capabilities?.includes(DECISION_REUSE_CAPABILITY)) fail('未登记的复用边界或能力');
+  const reuse = io.document(record.decision_reuse_ref);
+  if (reuse.schema_version !== 1 || reuse.kind !== DECISION_REUSE_CAPABILITY || reuse.target_gate !== record.gate_id || reuse.scope_ref !== record.subject_ref || !sameSet(reuse.scope, record.approval_scope)) fail('目标边界、资产或范围不匹配');
+  const manifest = io.document(reuse.scope_ref);
+  if (manifest.schema_version !== 1 || manifest.kind !== 'strategic-delivery-scope' || !Array.isArray(manifest.assets) || !manifest.assets.length || !Array.isArray(manifest.risks) || !Array.isArray(manifest.conditions)) fail('交付范围清单不完整');
+  if (!Array.isArray(reuse.requirements) || !reuse.requirements.length) fail('缺少原决定');
+  const approved = [];
+  for (const requirement of reuse.requirements) {
+    const result = assertUserDecisionRequirement(requirement,{...options,rolesDoc:roles});
+    const source = io.document(requirement.user_decision_ref);
+    for (const item of source.request.items.filter(item => result.validated.some(v => v.item_id === item.id))) approved.push({item, requirement});
+  }
+  const identities = new Set();
+  for (const asset of manifest.assets) {
+    if (!asset.ref || !asset.version || !asset.boundary || !Array.isArray(asset.scope) || !asset.scope.length || identities.has(`${asset.boundary}:${asset.ref}`)) fail('资产缺少身份、专业边界、范围或重复');
+    identities.add(`${asset.boundary}:${asset.ref}`);
+    if (decisionDigest(io.bytes(asset.ref)) !== asset.digest) fail(`资产已变化: ${asset.ref}`);
+    const covering = approved.filter(({item,requirement}) => item.boundary === asset.boundary && asset.scope.every(s => requirement.scope.includes(s)) && [item.subject,...item.basis].some(a => a.ref === asset.ref && a.version === asset.version && a.digest === asset.digest));
+    if (!covering.length) fail(`没有原决定覆盖: ${asset.ref} / ${asset.boundary}`);
+  }
+  const coveredScope = new Set(manifest.assets.flatMap(asset => asset.scope));
+  if (!reuse.scope.length || reuse.scope.some(s => !coveredScope.has(s))) fail('交付范围超出资产批准范围');
+  for (const risk of manifest.risks) if (!approved.some(({item}) => item.risks.includes(risk))) fail(`新增未接受风险: ${risk}`);
+  for (const condition of manifest.conditions) if (!approved.some(({item}) => item.next_actions.includes(condition))) fail(`新增授权条件: ${condition}`);
+  return {reused:true,manifest,validated:approved.map(({item})=>({item_id:item.id,principal_ref:item.responder_ref}))};
+}

package/template/scripts/strategic-feedback

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { verifyConsumerFeedback, verifyFeedbackAdjudication } from './lib/strategic-feedback.mjs';
+
+try{
+  const [command,...args]=process.argv.slice(2);const {values,positionals}=parseArgs({args,options:{root:{type:'string',default:process.cwd()}},allowPositionals:true,strict:true});
+  if(positionals.length!==1||!['verify-feedback','verify-adjudication'].includes(command))throw new TypeError('用法: scripts/strategic-feedback <verify-feedback|verify-adjudication> --root <target> <contract.json>');
+  const result=command==='verify-feedback'?await verifyConsumerFeedback({root:values.root,feedbackRef:positionals[0]}):await verifyFeedbackAdjudication({root:values.root,adjudicationRef:positionals[0]});
+  process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
+}catch(error){process.stderr.write(`${error.message}\n`);process.exitCode=1;}