create-yss-spec 3.3.8 → 3.4.1

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

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

package/template/scripts/strategic-handoff

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

package/template/scripts/verify-openapi-draft-validation-record

@@ -1,144 +1,25 @@
 #!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
-import { parseAllDocuments, parseDocument } from "./vendor/yaml.mjs";
-import { validateJsonSchema } from "./lib/json-schema.mjs";
+import { validateOpenApiDraftValidationRecord } from "./lib/openapi-draft-validation.mjs";
 
 const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(templateRoot, "docs/process/schemas/openapi-draft-validation-record.schema.json");
-const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
-
-function ensure(condition, message) {
-  if (!condition) throw new TypeError(message);
-}
-
-function resolveSafe(root, reference) {
-  ensure(typeof reference === "string" && reference.length > 0, "引用不能为空");
-  ensure(!path.isAbsolute(reference) && !reference.includes("\\") && !reference.split("/").includes(".."), `引用必须位于项目内: ${reference}`);
-  const target = path.resolve(root, reference);
-  ensure(target === root || target.startsWith(`${root}${path.sep}`), `引用越出项目根: ${reference}`);
-  ensure(existsSync(target), `引用不可读取: ${reference}`);
-  ensure(!lstatSync(target).isSymbolicLink(), `引用不能是 symlink: ${reference}`);
-  return target;
-}
-
-function parseOne(file, label) {
-  const source = readFileSync(file, "utf8");
-  const documents = parseAllDocuments(source, { uniqueKeys: true, maxAliasCount: 0 });
-  ensure(documents.length === 1, `${label} 必须是单一 YAML document`);
-  ensure(!documents[0].errors.length, `${label} YAML 无效: ${documents[0].errors[0]?.message}`);
-  return documents[0].toJS({ maxAliasCount: 0 });
-}
-
-function pointer(value, fragment, reference) {
-  if (!fragment || fragment === "#") return value;
-  ensure(fragment.startsWith("#/"), `仅支持 JSON Pointer fragment: ${reference}`);
-  return fragment.slice(2).split("/").reduce((current, part) => {
-    const key = decodeURIComponent(part).replaceAll("~1", "/").replaceAll("~0", "~");
-    ensure(current && Object.hasOwn(current, key), `$ref 无法解析: ${reference}`);
-    return current[key];
-  }, value);
-}
-
-function verifyReferences(rootDocument, draftFile) {
-  const apiRoot = realpathSync(path.dirname(draftFile));
-  const cache = new Map([[realpathSync(draftFile), rootDocument]]);
-  const active = new Set();
-
-  function load(reference, ownerFile) {
-    ensure(!/^[a-z][a-z0-9+.-]*:/i.test(reference) && !path.isAbsolute(reference), `$ref 禁止远程或绝对路径: ${reference}`);
-    const [filePart, fragment = ""] = reference.split("#", 2);
-    const targetFile = filePart ? path.resolve(path.dirname(ownerFile), filePart) : ownerFile;
-    ensure(existsSync(targetFile), `$ref 文件不存在: ${reference}`);
-    const realTarget = realpathSync(targetFile);
-    ensure(realTarget === apiRoot || realTarget.startsWith(`${apiRoot}${path.sep}`), `$ref 越出 feature API 目录: ${reference}`);
-    if (!cache.has(realTarget)) cache.set(realTarget, parseOne(realTarget, `$ref ${reference}`));
-    return { value: pointer(cache.get(realTarget), fragment ? `#${fragment}` : "", reference), file: realTarget };
-  }
-
-  function walk(value, ownerFile) {
-    if (!value || typeof value !== "object") return;
-    if (typeof value.$ref === "string") {
-      const key = `${ownerFile}|${value.$ref}`;
-      if (active.has(key)) return;
-      active.add(key);
-      const resolved = load(value.$ref, ownerFile);
-      walk(resolved.value, resolved.file);
-      active.delete(key);
-    }
-    for (const child of Object.values(value)) walk(child, ownerFile);
-  }
-  walk(rootDocument, realpathSync(draftFile));
-  return (reference, ownerFile = realpathSync(draftFile)) => load(reference, ownerFile);
-}
-
-function verifyOperations(document, resolveReference) {
-  const operationIds = new Set();
-  for (const [route, pathItem] of Object.entries(document.paths ?? {})) {
-    if (!pathItem || typeof pathItem !== "object") continue;
-    const placeholders = [...route.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
-    for (const [method, operation] of Object.entries(pathItem)) {
-      if (!methods.has(method) || !operation || typeof operation !== "object") continue;
-      ensure(typeof operation.operationId === "string" && operation.operationId.length > 0, `${method.toUpperCase()} ${route} 缺少 operationId`);
-      ensure(!operationIds.has(operation.operationId), `operationId 重复: ${operation.operationId}`);
-      operationIds.add(operation.operationId);
-      const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])].map((item) =>
-        typeof item?.$ref === "string" ? resolveReference(item.$ref).value : item
-      );
-      for (const name of placeholders) {
-        const parameter = parameters.find((item) => item?.in === "path" && item?.name === name);
-        ensure(parameter && parameter.required === true, `${method.toUpperCase()} ${route} 缺少 required path parameter: ${name}`);
-      }
-    }
-  }
-}
 
 try {
   const { values, positionals } = parseArgs({
     options: { "allow-template": { type: "boolean" }, root: { type: "string", default: templateRoot } },
     allowPositionals: true,
-    strict: true
+    strict: true,
   });
-  ensure(positionals.length === 1, "用法: scripts/verify-openapi-draft-validation-record [--allow-template] [--root <project>] <record.yaml>");
-  const root = path.resolve(values.root);
-  const recordFile = path.resolve(positionals[0]);
-  const recordDocument = parseDocument(readFileSync(recordFile, "utf8"), { uniqueKeys: true, maxAliasCount: 0 });
-  ensure(!recordDocument.errors.length, `validation record YAML 无效: ${recordDocument.errors[0]?.message}`);
-  const record = recordDocument.toJS({ maxAliasCount: 0 });
-  validateJsonSchema(record, schemaPath, { cwd: templateRoot, label: "OpenAPI Draft validation record schema" });
-
-  if (values["allow-template"]) {
-    ensure(record.template === true, "--allow-template 只接受模板记录");
-    process.stdout.write("OpenAPI Draft validation record 模板验证通过\n");
-    process.exit(0);
-  }
-
-  ensure(record.template === false, "正式 validation record 必须设置 template: false");
-  ensure(record.status === "passed", "正式 validation record 必须达到 status: passed");
-  ensure(record.toolchain.exit_code === 0, "Redocly lint 必须以退出码 0 完成");
-  ensure(Object.values(record.checks).every((result) => result === "passed"), "所有结构与 lint checks 必须为 passed");
-  ensure(record.toolchain.command === `pnpm exec redocly lint ${record.draft.ref}`, "lint command 必须精确指向当前 Draft");
-
-  const draftFile = resolveSafe(root, record.draft.ref);
-  const lockfile = resolveSafe(root, record.toolchain.lockfile_ref);
-  resolveSafe(root, record.toolchain.evidence_ref);
-  const draftBytes = readFileSync(draftFile);
-  const actualDigest = `sha256:${createHash("sha256").update(draftBytes).digest("hex")}`;
-  ensure(actualDigest === record.draft.sha256, `Draft SHA-256 不匹配: record=${record.draft.sha256}, actual=${actualDigest}`);
-  const lock = readFileSync(lockfile, "utf8");
-  const version = record.toolchain.version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const lockedPackage = new RegExp(`['\"]?@redocly/cli@${version}(?:['\":\\s(]|$)`).test(lock)
-    || new RegExp(`['\"]?@redocly/cli['\"]?:[\\s\\S]{0,240}?\\n\\s+version:\\s*['\"]?${version}(?:\\(|['\"\\s]|$)`).test(lock);
-  ensure(lockedPackage, "pnpm lockfile 未绑定记录中的 @redocly/cli 版本");
-
-  const draft = parseOne(draftFile, "OpenAPI Draft");
-  ensure(draft?.openapi === "3.1.0" && record.draft.oas_version === draft.openapi, "OpenAPI Draft 必须为 OAS 3.1.0");
-  const resolveReference = verifyReferences(draft, draftFile);
-  verifyOperations(draft, resolveReference);
-  process.stdout.write(`OpenAPI Draft validation record 验证通过: ${record.draft.sha256}\n`);
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-openapi-draft-validation-record [--allow-template] [--root <project>] <record.yaml>");
+  const result = validateOpenApiDraftValidationRecord(path.resolve(positionals[0]), {
+    root: path.resolve(values.root),
+    allowTemplate: values["allow-template"] === true,
+  });
+  process.stdout.write(result.template
+    ? "OpenAPI Draft validation record 模板验证通过\n"
+    : `OpenAPI Draft validation record 验证通过: ${result.record.draft.sha256}\n`);
 } catch (error) {
   process.stderr.write(`OpenAPI Draft validation record 验证失败: ${error.message}\n`);
   process.exitCode = 1;

package/template/scripts/verify-strategic-context-import

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { parseContextContract } from "./lib/context-contract.mjs";
-import { validateVisualBaseline } from "../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs";
+import { validateHandoffUiBaseline } from "./lib/ui-baseline.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const schemaPath = path.join(repoRoot, "docs/process/schemas/strategic-design-handoff.schema.json");
+const schemaPaths = new Map([
+  [3, "docs/process/schemas/strategic-design-handoff-v3.schema.json"],
+  [4, "docs/process/schemas/strategic-design-handoff-v4.schema.json"],
+  [5, "docs/process/schemas/strategic-design-handoff-v5.schema.json"],
+]);
 const pythonValidator = String.raw`
 import json, sys
 from jsonschema import Draft202012Validator
@@ -33,19 +37,13 @@ try {
   if (positionals.length !== 1 || !values.reconciliation) throw new TypeError("用法: scripts/verify-strategic-context-import --root <target-repo> --reconciliation <record> <handoff.yaml|json>");
   const root = path.resolve(values.root);
   const handoff = parseFile(path.resolve(positionals[0]));
-  if ([1, 2].includes(handoff.schema_version)) throw new TypeError(`migration-required: Strategic Design Handoff v${handoff.schema_version} 是只读历史资产；在途 UI 交接必须升级 v3 并携带 Visual Baseline`);
+  if ([1, 2].includes(handoff.schema_version)) throw new TypeError(`migration-required: Strategic Design Handoff v${handoff.schema_version} 是只读历史资产；修改或重新交付必须升级 Handoff v5 并重新批准`);
+  const schemaRef = schemaPaths.get(handoff.schema_version);
+  if (!schemaRef) throw new TypeError(`migration-required: 未知 Strategic Design Handoff schema_version ${String(handoff.schema_version)}；支持历史 v3/v4 与当前 v5`);
+  const schemaPath = path.join(repoRoot, schemaRef);
   const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(handoff) });
   if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
-  const baselineRef = handoff.source.visual_baseline_ref;
-  const bundleRoot = path.resolve(root, baselineRef.persisted_ref);
-  const manifestPath = path.resolve(bundleRoot, baselineRef.manifest_ref);
-  if (!manifestPath.startsWith(`${bundleRoot}${path.sep}`) || !existsSync(manifestPath)) throw new TypeError("Strategic Design Handoff 的 Visual Baseline manifest 不可读或越界");
-  const baseline = parseFile(manifestPath);
-  const baselineResult = await validateVisualBaseline(baseline, { bundleRoot });
-  if (baselineResult.errors.length) throw new TypeError(`Visual Baseline 无效: ${baselineResult.errors.join("; ")}`);
-  if (baseline.baseline_id !== baselineRef.baseline_id || baseline.version !== baselineRef.version || baseline.bundle.digest !== baselineRef.digest) throw new TypeError("Strategic Design Handoff 的 Visual Baseline 身份、版本或 digest 不一致");
-  const actualCaseIds = baseline.cases.map((item) => item.case_id).sort();
-  if (JSON.stringify(actualCaseIds) !== JSON.stringify([...baselineRef.case_ids].sort())) throw new TypeError("Strategic Design Handoff 的 Visual Baseline case_ids 不一致");
+  await validateHandoffUiBaseline(root, handoff);
   const reconciliationResult = spawnSync(process.execPath, [path.join(repoRoot, "scripts/verify-context-reconciliation"), "--root", root, path.resolve(values.reconciliation)], { cwd: repoRoot, encoding: "utf8" });
   if (reconciliationResult.status !== 0) throw new TypeError(reconciliationResult.stderr.trim());
   const target = parseContextContract({ root });

package/template/skills-lock.json

@@ -18,7 +18,7 @@
       "revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f"
     },
     "iloveZzz/yss-harness-design-agent": {
-      "revision": "b7947298f74510861a36caedda4e77d03df35569"
+      "revision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24"
     },
     "ayghri/i-have-adhd": {
       "revision": "7b9069b39972e269e61bd95c2f66ebb90cac6a02"
@@ -481,7 +481,7 @@
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/prototype-review/SKILL.md",
         "effectiveHash": "df6f131bef0f52a96d307d98ab42d74888a9b72c5508911b5622913b334e8eab",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
+        "sourceRevision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24",
         "upstreamHash": "9206df8b6c555c1af1351e425c5ec99ec2a40263c6861607f1418b9c520873ab",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
@@ -696,36 +696,6 @@
           ".pi/skills"
         ]
       },
-      "yss-antd-design": {
-        "source": "iloveZzz/yss-harness-design-agent",
-        "sourceType": "git-submodule",
-        "skillPath": ".agents/skills/yss-antd-design/SKILL.md",
-        "effectiveHash": "92739eb34352fd70fbb52f4d9d6c6ac09aa02bc0155a4bd812a98cd5f933ff70",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
-        "upstreamHash": "08ce99d45586d5ea19e25fdd9e9a6ede16e66f18992b70b87e0cd23f92343b16",
-        "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
-        "targets": [
-          ".agents/skills",
-          ".codex/skills",
-          ".cursor/skills",
-          ".pi/skills"
-        ]
-      },
-      "yss-antdv-next-design": {
-        "source": "iloveZzz/yss-harness-design-agent",
-        "sourceType": "git-submodule",
-        "skillPath": ".agents/skills/yss-antdv-next-design/SKILL.md",
-        "effectiveHash": "c7c07c5dc3716f578904559473d43d92878aa25a6a45c8827e288f0242d42b75",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
-        "upstreamHash": "2942ed52dd58a38e51f09eb11254809334aeaed08f21cd081f09f35e6647a68c",
-        "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
-        "targets": [
-          ".agents/skills",
-          ".codex/skills",
-          ".cursor/skills",
-          ".pi/skills"
-        ]
-      },
       "yss-api-integration": {
         "source": "iloveZzz/yss-ui",
         "sourceType": "github",
@@ -777,23 +747,11 @@
           ".pi/skills"
         ]
       },
-      "yss-components": {
-        "source": "project",
-        "sourceType": "local",
-        "skillPath": ".agents/skills/yss-components/SKILL.md",
-        "effectiveHash": "37cdd0a21338c3a9dd0c5e11788aa4f522eb1a0777c7311a446c122f6ecbc5f9",
-        "targets": [
-          ".agents/skills",
-          ".codex/skills",
-          ".cursor/skills",
-          ".pi/skills"
-        ]
-      },
       "yss-ddd-scaffold-generator": {
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-ddd-scaffold-generator/SKILL.md",
-        "effectiveHash": "ab1bd70b73a148d57a8e3f88e9a94be57b81f59bbfb81849e6e1dba16bfc7e16",
+        "effectiveHash": "36067afa5f048a3af0420d86e7dc2f9ea1e32d3de1c99dd31eb477ee77f718fa",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -805,9 +763,9 @@
         "source": "iloveZzz/yss-harness-design-agent",
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-design-system/SKILL.md",
-        "effectiveHash": "e69597b8b6a5ce4de5bd40f67630443b8176202f6b028b2ce146a2a1d062816f",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
-        "upstreamHash": "90aaf06b2514353152464a4d032076fa9d5ef56272d8ad526f5544f3c22a2b00",
+        "effectiveHash": "c5c023813042472030cecca187c222257151dd5554655a6bdcdd757bc2a516c7",
+        "sourceRevision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24",
+        "upstreamHash": "c917ecf40a67c52f0fa7894fbdfbf827cc1ed6aff1037be2911377387fede1a0",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
           ".agents/skills",
@@ -880,7 +838,7 @@
         "source": "iloveZzz/yss-ui",
         "sourceType": "github",
         "skillPath": "packages/skills/yss-formily/SKILL.md",
-        "effectiveHash": "63c07b8968b0d61a5ec03b30b85ee725c3adc78ae326b1d137b1a1565f8351d4",
+        "effectiveHash": "78ff1a1b6b720f0c3c85c57d145471ac49b01b4aa2df2f24420863d8ae1764d4",
         "sourceRevision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f",
         "upstreamHash": "f30e312a632c592c9050d00c35c22f2dc032658e6d9fdd6e2b5dc4ac0ea970c8",
         "adaptationRef": "docs/agents/yss-ui-skills-integration.md",
@@ -907,7 +865,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-frontend-scaffold-generator/SKILL.md",
-        "effectiveHash": "2f829e4e2a9cb42e123e8de37fe812bc65eef1308758e077b52f0698de9b68ab",
+        "effectiveHash": "4db10d9240f5ba97312e0afca807b654368dbee0df62396b135e58d1965694d9",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -919,7 +877,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-hook/SKILL.md",
-        "effectiveHash": "77740f75587c2978b72b3651693e4c630aecd62ff757ad50e630a5a4c5b05d49",
+        "effectiveHash": "326e418d71870f0079658e2fd51fba65ab734facd64d194be585bf10bf960422",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -931,7 +889,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-implementation-contract-compiler/SKILL.md",
-        "effectiveHash": "7697e5d2dfc3b2cbf09b56c2bfac3ed63686508173986b5d19512ef4e3192a5b",
+        "effectiveHash": "f4a96ee28a8a9f98d03b8bc264ef1202796b25fcbf0d474a50ee3ec745060fb3",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -943,7 +901,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-layered-mvc-scaffold-generator/SKILL.md",
-        "effectiveHash": "50d0f704326fc523c29f4b728c08148cde372c674b9e8686829bee3e74b66fdc",
+        "effectiveHash": "562cee54e4b83ca014049540b8998149026290f283c2ba2aaec39d37ae88e457",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -955,7 +913,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-mvc-data-analysis-project-initializer/SKILL.md",
-        "effectiveHash": "9066e52ea188f5ec6765bb7fe1096f84577c9b1d1abf90e2fafd7e25d35e1a58",
+        "effectiveHash": "5d8711cc0b7fa5ccacbabc0916c7ef11bb82075db8b08260f08221c0cf91895c",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -975,18 +933,6 @@
           ".pi/skills"
         ]
       },
-      "yss-mvc-scaffold-generator": {
-        "source": "project",
-        "sourceType": "local",
-        "skillPath": ".agents/skills/yss-mvc-scaffold-generator/SKILL.md",
-        "effectiveHash": "0c25a113567f2589e06cbba0e361e1c159f6286beae1ec9d2e27104ef3ef52ad",
-        "targets": [
-          ".agents/skills",
-          ".codex/skills",
-          ".cursor/skills",
-          ".pi/skills"
-        ]
-      },
       "yss-mybatis": {
         "source": "project",
         "sourceType": "local",
@@ -1015,7 +961,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-openapi-governance/SKILL.md",
-        "effectiveHash": "e33980c3964c4749ef900c7c27ee683ad4e5ff285e9adf234bc82687304dee30",
+        "effectiveHash": "39f6b613b91875ec3394fc2e4e6f623f49c3833e30cff3be05cf857f5d192b01",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1027,7 +973,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-product-lifecycle/SKILL.md",
-        "effectiveHash": "1364bc3f4541427a47444dd2e0aa4500ed6cbe6519dfc48efc580a22c3001892",
+        "effectiveHash": "60e4bd2be607b470316330b3e7e5aebe62fe25c1139e34089d8d989166776349",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1039,10 +985,9 @@
         "source": "iloveZzz/yss-harness-design-agent",
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-prototype-stage/SKILL.md",
-        "effectiveHash": "ebfdc89f7feb70ff5995132cbe5574ca680a433115ebe59c342ad6309c5a8ed6",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
-        "upstreamHash": "4bb0ba6cdbbbd1a3b89e97d94a7b0829c9282e21c8ce9e4bfda6e69a8714bc6d",
-        "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
+        "effectiveHash": "8256a1edfeb203f4de27d190210b0ba5593f8f74e0f3655b62b146daff2105a8",
+        "sourceRevision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24",
+        "upstreamHash": "8256a1edfeb203f4de27d190210b0ba5593f8f74e0f3655b62b146daff2105a8",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1105,7 +1050,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-skill-source-index-refresh/SKILL.md",
-        "effectiveHash": "96ff974a0f7b3db8de09680daf9ecada94dd19f608341dcc85a32d40c02591b0",
+        "effectiveHash": "8635080a3322c2f18d3f314aab1aa034a6987b28eeecb3cb0c15767969add09f",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1118,7 +1063,7 @@
         "sourceType": "git-submodule",
         "skillPath": ".agents/skills/yss-stage-decision/SKILL.md",
         "effectiveHash": "ada584c7b996439a47e24153e156c38198f60f3f84250cd37aea6e2a118131aa",
-        "sourceRevision": "b7947298f74510861a36caedda4e77d03df35569",
+        "sourceRevision": "e5cc1b2b9a99297b475551174057dbeb1d5f1a24",
         "upstreamHash": "8752a1ed6903bd20c33e21b521d52bd4f7a0662b1d25e00152b60ba38333c93b",
         "adaptationRef": "docs/agents/strategic-design-skills-integration.md",
         "targets": [
@@ -1132,7 +1077,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-tactical-design/SKILL.md",
-        "effectiveHash": "2ffb26709fd68184e0fe8f724318dc748fc479dcf52af236fe63f49a17540bfa",
+        "effectiveHash": "4229d14cd6a5d354db8e88752f4ce050482421720c95b97506a00df42bc371e3",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1156,7 +1101,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-ui/SKILL.md",
-        "effectiveHash": "3140934bcd219ba05581530e0c4465cf700bd2059f596798975a8145b8e84083",
+        "effectiveHash": "215cc4a7ae029d3b2d92ab849176fe6c45c57f3e452e53217d8fdee3eaf1f106",
         "targets": [
           ".agents/skills",
           ".codex/skills",
@@ -1249,7 +1194,7 @@
         "source": "project",
         "sourceType": "local",
         "skillPath": ".agents/skills/yss-web-controller/SKILL.md",
-        "effectiveHash": "63192f78bcc7fe099cd856552ff2899453c1aeafd17203099694c25d425f4797",
+        "effectiveHash": "6f8082793d3de76eb3cd42a8fa0c62c94361c34f739ceb9601e77d2cf7dfa7e0",
         "targets": [
           ".agents/skills",
           ".codex/skills",

package/template/yss-public-skills.json

@@ -3,13 +3,10 @@
   "repository": "iloveZzz/yss-spec-dev-skills",
   "canonical_root": ".agents/skills",
   "skills": [
-    "yss-antd-design",
-    "yss-antdv-next-design",
     "yss-api-integration",
     "yss-audit-log",
     "yss-application",
     "yss-cache",
-    "yss-components",
     "yss-ddd-scaffold-generator",
     "yss-design-system",
     "yss-distributed-id",
@@ -69,9 +66,6 @@
       "title": "前端",
       "description": "用于 YSS Vue、Formily、页面模块和 UI 实现的技能。",
       "skills": [
-        "yss-antd-design",
-        "yss-antdv-next-design",
-        "yss-components",
         "yss-design-system",
         "yss-formily",
         "yss-formily-schema-generator",