create-yss-spec 3.3.8 → 3.4.3

package/template/scripts/lib/lifecycle-transition.mjs

@@ -1,8 +1,15 @@
+// Wire capability marker: profile-local readiness rules are not interchangeable.
+export const SLICE_REPOSITORY_PREPARATION_PROTOCOL = 1;
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { assertWorkUnitUserDecision, assertImplementationDecision } from "./user-decision.mjs";
 import { enforceFrontendDelivery } from "./frontend-delivery-boundary.mjs";
 import { validatePlanSpecEntry } from "./plan-spec-entry.mjs";
+import path from "node:path";
+import { validateApiContractDecision } from "./api-contract-decision.mjs";
+import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
+import { ROOT } from "./lifecycle-registry.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
@@ -28,8 +35,8 @@ const NEXT_ROUTES = deepFreeze({
   "work-unit.plan-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.domain-strategy-design": ["work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.stage-decision": ["work-unit.spec-synthesis"],
-  "work-unit.spec-synthesis": ["work-unit.prototype-design", "work-unit.technical-analysis", REPOSITORY_PREPARATION_WORK_UNIT],
-  "work-unit.prototype-design": ["work-unit.technical-analysis", REPOSITORY_PREPARATION_WORK_UNIT],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design", "work-unit.technical-analysis"],
+  "work-unit.prototype-design": ["work-unit.technical-analysis"],
   "work-unit.technical-analysis": [REPOSITORY_PREPARATION_WORK_UNIT],
   [REPOSITORY_PREPARATION_WORK_UNIT]: [TICKET_DECOMPOSITION_WORK_UNIT],
   [TICKET_DECOMPOSITION_WORK_UNIT]: [IMPLEMENTATION_WORK_UNIT],
@@ -68,6 +75,10 @@ const BLOCKING_SIGNALS = Object.freeze({
   scaffoldVerificationFailed: "scaffold-verification-failed",
   frontendTemplateUnavailable: "frontend-template-unavailable",
   implementationRepositoriesStale: "implementation-repositories-stale",
+  technicalAnalysisRequired: "technical-analysis-required",
+  backendDesignPrerequisitesMissing: "backend-design-prerequisites-missing",
+  legacyScaffoldReconciliationRequired: "legacy-scaffold-reconciliation-required",
+  prematureImplementationDetected: "premature-implementation-detected",
 });
 
 const allowedResult = (evidenceRefs = []) => ({
@@ -106,6 +117,118 @@ function readDecompositionResult(ref, read) {
   }
 }
 
+function artifactBindingReady(binding, exists) {
+  return hasText(binding?.ref) && /^v[1-9][0-9]*$/.test(binding?.version ?? "") && /^sha256:[a-f0-9]{64}$/.test(binding?.digest ?? "") && isReadable(binding.ref, exists);
+}
+
+function approvalHasBinding(approval, expected) {
+  return Array.isArray(approval?.artifact_bindings) && approval.artifact_bindings.some((binding) =>
+    binding?.id === expected.id && binding.version === expected.version && binding.digest === expected.digest);
+}
+
+function loadBoundArtifact(root, binding, idField, versionField) {
+  const file = path.isAbsolute(binding.ref) ? binding.ref : path.resolve(root, binding.ref);
+  const bytes = readFileSync(file);
+  if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== binding.digest) throw new TypeError(`${binding.ref} 原始字节摘要漂移`);
+  const document = parseDocument(bytes.toString("utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(`${binding.ref} 无法解析`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || value.status !== "approved" || value[versionField] !== binding.version || !hasText(value[idField])) throw new TypeError(`${binding.ref} 不是当前批准资产`);
+  return { value, expected: { id: value[idField], version: value[versionField], digest: binding.digest } };
+}
+
+function samePackageBinding(actual, expected, includeImpact = false) {
+  return actual?.ref === expected.ref && actual.version === expected.version && actual.digest === expected.digest
+    && (!includeImpact || actual.impact === expected.impact);
+}
+
+function approvalPackageReady(approval, prerequisites, technical, data, api, root, projectId) {
+  const file = path.isAbsolute(approval.subject_ref) ? approval.subject_ref : path.resolve(root, approval.subject_ref);
+  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) return false;
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (value?.schema_version !== 1 || value?.kind !== "engineering-contract-package" || value?.project_id !== projectId) return false;
+  if (!samePackageBinding(value.technical_design, { ...prerequisites.technical_design, version: technical.value.version })) return false;
+  if (!samePackageBinding(value.data_architecture_decision, { ...prerequisites.data_architecture_decision, version: data.value.decision_version, impact: data.value.impact }, true)) return false;
+  if (!samePackageBinding(value.api_contract_decision, { ...prerequisites.api_contract_decision, version: api.decision.decision_version, impact: api.decision.impact }, true)) return false;
+  if (api.decision.impact === "required") return samePackageBinding(value.frozen_openapi, api.decision.openapi) && value.frozen_openapi.id === api.decision.openapi.id;
+  return !Object.hasOwn(value, "frozen_openapi");
+}
+
+function backendDesignPrerequisitesReady(prerequisites, exists, root, projectId) {
+  const structurallyReady = artifactBindingReady(prerequisites?.technical_design, exists)
+    && artifactBindingReady(prerequisites?.data_architecture_decision, exists)
+    && ["required", "not-applicable"].includes(prerequisites?.data_architecture_decision?.impact)
+    && artifactBindingReady(prerequisites?.api_contract_decision, exists)
+    && ["required", "not-applicable"].includes(prerequisites?.api_contract_decision?.impact)
+    && isReadable(prerequisites?.engineering_contract_approval_ref, exists);
+  if (!structurallyReady) return false;
+  try {
+    const technical = loadBoundArtifact(root, prerequisites.technical_design, "technical_design_id", "version");
+    const data = loadBoundArtifact(root, prerequisites.data_architecture_decision, "decision_id", "decision_version");
+    const api = validateApiContractDecision(prerequisites.api_contract_decision, { root });
+    const approvalFile = path.isAbsolute(prerequisites.engineering_contract_approval_ref)
+      ? prerequisites.engineering_contract_approval_ref
+      : path.resolve(root, prerequisites.engineering_contract_approval_ref);
+    const approval = loadApprovalRecord(approvalFile, 'gate.engineering-contract-approved');
+    validateApprovalRecord(approval, { requireApproved: true, root });
+    if (approval.gate_id !== "gate.engineering-contract-approved" || !approval.approval_scope?.includes(projectId)) return false;
+    if (!approvalHasBinding(approval, technical.expected) || !approvalHasBinding(approval, data.expected)) return false;
+    if (!approvalHasBinding(approval, { id: api.decision.decision_id, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest })) return false;
+    if (api.decision.impact === "required" && !approvalHasBinding(approval, api.decision.openapi)) return false;
+    return approvalPackageReady(approval, prerequisites, technical, data, api, root, projectId);
+  } catch {
+    return false;
+  }
+}
+
+function sameBackendDesignPrerequisites(expected, actual) {
+  return ["technical_design", "data_architecture_decision", "api_contract_decision"].every((key) =>
+    expected?.[key]?.ref === actual?.[key]?.ref
+    && expected?.[key]?.version === actual?.[key]?.version
+    && expected?.[key]?.digest === actual?.[key]?.digest)
+    && expected?.engineering_contract_approval_ref === actual?.engineering_contract_approval_ref;
+}
+
+function validateTechnicalAnalysisCompletion(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), root = ROOT } = {}) {
+  const result = state?.technical_analysis_result;
+  const resultRef = state?.technical_analysis_result_ref;
+  const signals = [];
+  const missing = [];
+  const persisted = readDecompositionResult(resultRef, read);
+  if (!result || result.result_schema !== "workflow-execution-result-v1" || result.work_unit !== "work-unit.technical-analysis" || result.result !== "completed" || result.current_version !== true) {
+    signals.push(BLOCKING_SIGNALS.technicalAnalysisRequired);
+    missing.push("completed current work-unit.technical-analysis result");
+  }
+  if (!isReadable(resultRef, exists) || !persisted || persisted.result_schema !== "workflow-execution-result-v1" || persisted.work_unit !== "work-unit.technical-analysis" || persisted.result !== "completed" || persisted.current_version !== true) {
+    signals.push(BLOCKING_SIGNALS.technicalAnalysisRequired);
+    missing.push("readable persisted technical_analysis_result_ref");
+  }
+  if (result?.context_reconciliation?.status !== "reconciled" || !isReadable(result?.context_reconciliation?.ref, exists)) {
+    signals.push(BLOCKING_SIGNALS.technicalAnalysisRequired);
+    missing.push("reconciled readable technical analysis context");
+  }
+  const evidenceRefs = Array.isArray(result?.evidence_refs) ? result.evidence_refs : [];
+  if (!evidenceRefs.includes(resultRef) || evidenceRefs.some((ref) => !isReadable(ref, exists))) {
+    signals.push(BLOCKING_SIGNALS.technicalAnalysisRequired);
+    missing.push("readable technical analysis evidence including its persisted result");
+  }
+  try {
+    const api = validateApiContractDecision(result?.api_contract_decision, { root: path.resolve(root) });
+    if (!artifactBindingReady(result.api_contract_decision, exists)
+      || !evidenceRefs.includes(result.api_contract_decision.ref)
+      || !persisted?.api_contract_decision
+      || !sameBackendDesignPrerequisites({ api_contract_decision: result.api_contract_decision }, { api_contract_decision: persisted.api_contract_decision })) {
+      throw new TypeError("技术分析执行结果未一致绑定当前 API Contract Decision");
+    }
+    if (api.decision.current_version !== true || api.decision.status !== "approved") throw new TypeError("API Contract Decision 非当前批准版本");
+  } catch (error) {
+    signals.push(BLOCKING_SIGNALS.technicalAnalysisRequired);
+    missing.push(error.message);
+  }
+  return signals.length ? blockedResult(signals, missing, evidenceRefs) : allowedResult(evidenceRefs);
+}
+
 function validateTicketPath(ref) {
   if (!hasText(ref)) return false;
   return /^docs\/\.scratch\/[^/]+\/issues\/[^/]+\.md$/.test(ref);
@@ -132,6 +255,9 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
   }
   const routes = NEXT_ROUTES[currentWorkUnit];
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
+  if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && currentWorkUnit !== "work-unit.technical-analysis") {
+    return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
+  }
   if (nextRoute === null && routes.length === 0) {
     if (decisionState) return validateDecisionBoundary(currentWorkUnit, decisionState, options);
     return allowedResult();
@@ -143,6 +269,10 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     }
     return blockedResult(signals, ["allowed_next_route"]);
   }
+  if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT) {
+    const analysis = validateTechnicalAnalysisCompletion(decisionState, options);
+    if (analysis.result === "blocked") return analysis;
+  }
   if (nextRoute === 'work-unit.spec-synthesis' || currentWorkUnit === 'work-unit.spec-synthesis') {
     const entry = validatePlanSpecEntry(decisionState, options);
     if (entry.result === 'blocked' || nextRoute === 'work-unit.spec-synthesis') return entry;
@@ -159,14 +289,14 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
  * delivery role must resolve to an onboarded existing repository or a freshly
  * generated and verified scaffold. Unaffected roles need an explicit reason.
  */
-export function validateImplementationRepositoriesReady(state, { exists = existsSync } = {}) {
+export function validateImplementationRepositoriesReady(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), root = ROOT } = {}) {
   const preparation = state?.implementation_repository_preparation;
   const impacts = state?.delivery_impacts;
   const signals = [];
   const missing = [];
   const evidenceRefs = Array.isArray(preparation?.evidence_refs) ? preparation.evidence_refs : [];
 
-  if (!preparation || preparation.result !== "completed" || !Array.isArray(preparation.projects)) {
+  if (!preparation || preparation.schema_version !== 2 || preparation.kind !== "implementation-repository-preparation-result" || preparation.result !== "completed" || !Array.isArray(preparation.projects)) {
     return blockedResult([BLOCKING_SIGNALS.repositoryDecisionRequired], ["completed implementation_repository_preparation with projects"]);
   }
   if (preparation.current_version !== true || state?.implementation_repositories_stale === true) {
@@ -206,6 +336,10 @@ export function validateImplementationRepositoriesReady(state, { exists = exists
         signals.push(BLOCKING_SIGNALS.repositoryLocationRequired);
         missing.push(`${project.project_id} repository_ref, project_root and repository_scope`);
       }
+      if (role === "backend" && !backendDesignPrerequisitesReady(project.design_prerequisites, exists, path.resolve(root), project.project_id)) {
+        signals.push(BLOCKING_SIGNALS.backendDesignPrerequisitesMissing);
+        missing.push(`${project.project_id} readable Technical Design, Data Architecture Decision, API Contract Decision and atomic engineering approval bindings`);
+      }
       if (project.status === "existing-and-onboarded") {
         if (project.onboarding_result?.status !== "completed" || !isReadable(project.onboarding_result?.ref, exists)) {
           signals.push(BLOCKING_SIGNALS.repositoryOnboardingIncomplete);
@@ -225,6 +359,22 @@ export function validateImplementationRepositoriesReady(state, { exists = exists
           signals.push(BLOCKING_SIGNALS.scaffoldGenerationIncomplete);
           missing.push(`${project.project_id} readable scaffold manifest`);
         }
+        const manifest = readDecompositionResult(project.scaffold_manifest_ref, read);
+        if (role === "backend" && contract?.schema_version === 4) {
+          if (manifest?.schema_version !== 4 || manifest?.completion_level !== "empty-scaffold-verified" || !sameBackendDesignPrerequisites(project.design_prerequisites, manifest?.design_prerequisites)) {
+            signals.push(BLOCKING_SIGNALS.scaffoldGenerationIncomplete);
+            missing.push(`${project.project_id} v4 Manifest with empty-scaffold-verified and matching design prerequisites`);
+          }
+        }
+        if (role === "backend" && contract?.schema_version === 3) {
+          const legacy = project.legacy_reconciliation;
+          let digestMatches = false;
+          try { digestMatches = legacy?.manifest_digest === `sha256:${createHash("sha256").update(read(project.scaffold_manifest_ref)).digest("hex")}`; } catch {}
+          if (manifest?.schema_version !== 3 || manifest?.completion_level !== "empty-scaffold-verified" || legacy?.status !== "approved" || legacy?.ownership_state !== "unchanged-mechanical-scaffold" || legacy?.premature_implementation !== false || legacy?.manifest_ref !== project.scaffold_manifest_ref || !digestMatches || !isReadable(legacy?.ownership_check_ref, exists) || !isReadable(legacy?.recovery_approval_ref, exists)) {
+            signals.push(legacy?.premature_implementation === true ? BLOCKING_SIGNALS.prematureImplementationDetected : BLOCKING_SIGNALS.legacyScaffoldReconciliationRequired);
+            missing.push(`${project.project_id} approved legacy v3 reconciliation with unchanged mechanical ownership and recovery approval`);
+          }
+        }
         if (project.scaffold_verification?.status !== "passed" || !isReadable(project.scaffold_verification?.ref, exists)) {
           signals.push(BLOCKING_SIGNALS.scaffoldVerificationFailed);
           missing.push(`${project.project_id} readable passed scaffold verification`);
@@ -254,7 +404,7 @@ function validateDecisionBoundary(workUnit, state, options) {
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
-  const repositoryResult = validateImplementationRepositoriesReady(state, { exists });
+  const repositoryResult = validateImplementationRepositoriesReady(state, { exists, read, ...decisionOptions });
   if (repositoryResult.result === "blocked") return repositoryResult;
   const decomposition = state?.ticket_decomposition_result;
   const ticket = state?.vertical_slice_ticket;

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseAllDocuments, parseDocument } from "../vendor/yaml.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+
+const TEMPLATE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const METHODS = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+
+function ensure(condition, message) { if (!condition) throw new TypeError(message); }
+export const openApiDigest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+export function resolveOpenApiRef(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) ensure(parameters.some((item) => item?.in === "path" && item?.name === name && item.required === true), `${method.toUpperCase()} ${route} 缺少 required path parameter: ${name}`);
+    }
+  }
+}
+
+export function validateOpenApiDraftValidationRecord(recordFile, { root = TEMPLATE_ROOT, allowTemplate = false, schemaPath = path.join(TEMPLATE_ROOT, "docs/process/schemas/openapi-draft-validation-record.schema.json") } = {}) {
+  const projectRoot = path.resolve(root);
+  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: TEMPLATE_ROOT, label: "OpenAPI Draft validation record schema" });
+  if (allowTemplate) { ensure(record.template === true, "--allow-template 只接受模板记录"); return { record, template: true }; }
+  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 = resolveOpenApiRef(projectRoot, record.draft.ref);
+  const lockfile = resolveOpenApiRef(projectRoot, record.toolchain.lockfile_ref);
+  resolveOpenApiRef(projectRoot, record.toolchain.evidence_ref);
+  const draftBytes = readFileSync(draftFile);
+  ensure(openApiDigest(draftBytes) === record.draft.sha256, `Draft SHA-256 不匹配: record=${record.draft.sha256}, actual=${openApiDigest(draftBytes)}`);
+  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");
+  verifyOperations(draft, verifyReferences(draft, draftFile));
+  return { record, draft, draftFile, draftDigest: openApiDigest(draftBytes) };
+}

package/template/scripts/lib/plan-spec-entry.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { verifyContextReconciliation } from './context-reconciliation.mjs';
 import { decisionIO, decisionDigest, assertUserDecisionRequirement } from './user-decision.mjs';
-import { validateApprovalRecord } from './approval-record.mjs';
+import { validateApprovalRecord, selectApprovalRecord } from './approval-record.mjs';
 
 const fail = message => { throw new TypeError(`plan-spec-entry-blocked: ${message}`); };
 const text = value => typeof value === 'string' && value.trim().length > 0;
@@ -56,7 +56,7 @@ export function assertPlanSpecEntry(state, options = {}) {
     evidence(gate?.evidence_refs);
     if (review.impacts[impact]) {
       if (gate.status !== 'approved' || !basis.has(gate.approval_ref) || !basis.has(gate.subject_ref)) fail(`命中门禁未批准或未绑定依据: ${gateId}`);
-      const record = io.document(gate.approval_ref);
+      const record = selectApprovalRecord(io.document(gate.approval_ref), gateId);
       if (record.gate_id !== gateId || record.subject_ref !== gate.subject_ref || !gate.approval_scope?.includes(state.feature_id) || JSON.stringify([...(gate.approval_scope || [])].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) fail(`会签资产或范围不匹配: ${gateId}`);
       validateApprovalRecord(record, { ...options, requireApproved: true });
     } else if (gate.status !== 'not-applicable' || !text(gate.reason)) fail(`未命中门禁须有原因和依据: ${gateId}`);
@@ -72,7 +72,7 @@ export function assertPlanSpecEntry(state, options = {}) {
   if (reconciliation.status !== 'reconciled' || reconciliation.repository_mode !== 'project-instance') fail('Context 未调和');
   try { verifyContextReconciliation(path.resolve(io.root, review.context_reconciliation_ref), { root: io.root }); }
   catch (error) { fail(`Context reconciliation 验证失败: ${error.message}\n`); }
-  assertUserDecisionRequirement({ boundary: 'gate.plan-approved', subject_ref: state.plan_review_ref, scope: [state.feature_id], user_decision_ref: state.plan_user_decision_ref }, options);
+  assertUserDecisionRequirement({ boundary: 'gate.plan-approved', subject_ref: state.plan_review_ref, scope: [state.feature_id], user_decision_ref: state.plan_user_decision_ref, continuation_ref: state.plan_continuation_ref }, options);
   return { result: 'allowed', blocking_signals: [], missing_requirements: [], evidence_refs: [state.plan_review_ref, ...basis.keys()], next_work_unit: null };
 }
 

package/template/scripts/lib/scaffold-local-database.mjs

@@ -14,6 +14,7 @@ export function localDatabaseConfiguration(name) {
 
 export function scaffoldArchitectureIdentity(contract, contractDigest) {
   return {
+    ...(contract.platform_configuration ? { platform_configuration: contract.platform_configuration } : {}),
     architecture_family: contract.architecture_family,
     architecture_profile: contract.architecture_profile,
     generator_skill: contract.generator_skill,

package/template/scripts/lib/skill-registry.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
-import { PROJECTION_ROOTS, ROOT } from "./skill-supply-chain.mjs";
+import { nestedSkillPaths, PROJECTION_ROOTS, ROOT, unregisteredNestedSkillPaths } from "./skill-supply-chain.mjs";
 
 export const DEFAULT_REGISTRY = path.join(ROOT, "docs/agents/yss-skill-registry.yaml");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
@@ -217,7 +217,7 @@ function validateCodeReviewRoute(route, resolve) {
   validateFindingDisposition(standards.finding_disposition);
 }
 
-export function validateSkillRegistry(registry, { lock, compilerContract, lifecycleContract, skillSource } = {}) {
+export function validateSkillRegistry(registry, { lock, compilerContract, lifecycleContract, skillSource, externalSkillSource, nestedSkillSources } = {}) {
   if (!registry || typeof registry !== "object" || Array.isArray(registry)) fail("技能路由注册表必须是对象");
   if (registry.schema_version !== 2) fail("schema_version 必须为 2；v1 已停止支持，请迁移 capability、typed dependencies 与 recipes");
   if (registry.registry_id !== "yss.skill-routing") fail("registry_id 必须为 yss.skill-routing");
@@ -315,11 +315,23 @@ export function validateSkillRegistry(registry, { lock, compilerContract, lifecy
   const external = registry.external_skills ?? [];
   if (!Array.isArray(external)) fail("external_skills 必须是数组");
   const externalIds = new Set();
+  const externalSources = new Set();
   for (const skill of external) {
     requireString(skill.id, "external_skills.id");
     requireString(skill.source, `${skill.id}.source`);
     if (externalIds.has(skill.id) || ids.has(skill.id) || aliases.has(skill.id) || platformAliases.has(skill.id)) fail(`external skill 冲突: ${skill.id}`);
+    const canonicalExternalSource = skill.source.startsWith(`${registry.canonical_content_root}/`);
+    if (canonicalExternalSource && externalSources.has(skill.source)) fail(`external skill source 重复: ${skill.source}`);
+    if (externalSkillSource && canonicalExternalSource) {
+      const discovered = frontmatterName(externalSkillSource(skill.source));
+      if (discovered !== skill.id) fail(`${skill.id} 的 external SKILL.md name=${discovered} 与 id 不一致`);
+    }
     externalIds.add(skill.id);
+    externalSources.add(skill.source);
+  }
+  if (nestedSkillSources) {
+    const unregistered = unregisteredNestedSkillPaths(nestedSkillSources, externalSources);
+    if (unregistered.length) fail(`嵌套 SKILL.md 必须登记到 external_skills: ${unregistered.join(", ")}`);
   }
   for (const skill of platform) {
     for (const alias of skill.aliases) {
@@ -523,6 +535,8 @@ export function validateDefaultSkillRegistry() {
     lock,
     compilerContract,
     lifecycleContract: yamlFromFile(LIFECYCLE_CONTRACT, "生命周期编排合同"),
-    skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8")
+    skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8"),
+    externalSkillSource: (source) => readFileSync(path.join(ROOT, source), "utf8"),
+    nestedSkillSources: nestedSkillPaths().map((source) => `.agents/skills/${source}`)
   });
 }

package/template/scripts/lib/skill-supply-chain.mjs

@@ -10,7 +10,8 @@ const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
 export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];
-export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
+export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
+for (const id of ["yss-components", "yss-mvc-scaffold-generator", "yss-backend-scaffold-adapter", "yss-application-layer-reference", "yss-domain-layer-reference", "yss-infrastructure-layer-reference", "yss-web-layer-reference"]) OBSOLETE.add(id);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }
@@ -28,6 +29,16 @@ function treeFiles(directory, prefix = "") {
     return entry.isFile() || entry.isSymbolicLink() ? [[rel, absolute]] : [];
   });
 }
+export function nestedSkillPaths(directory = SOURCE_ROOT) {
+  return treeFiles(directory)
+    .map(([name]) => name)
+    .filter((name) => name.endsWith("/SKILL.md") && name.split("/").length > 2)
+    .sort();
+}
+export function unregisteredNestedSkillPaths(candidates, registeredSources) {
+  const registered = new Set(registeredSources);
+  return candidates.filter((candidate) => !registered.has(candidate)).sort();
+}
 export function treeHash(directory) {
   const digest = createHash("sha256");
   for (const [name, file] of treeFiles(directory).sort(([left], [right]) => left.localeCompare(right))) {

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

@@ -0,0 +1,10 @@
+// Interpret the published lifecycle check, without creating a second gate registry.
+export function sliceCheckApplicability(scope,registry) {
+ if(!['low','medium','high'].includes(scope.risk_level))throw new TypeError('缺少明确风险等级，不能裁剪材料');
+ if(scope.impacted_areas.some(impact=>!['ui','frontend','backend','api','data','persistence','domain','architecture','cross-repo','cross-boundary','high-risk'].includes(impact)))throw new TypeError('未知影响不能裁剪材料，先补影响分析');
+ const check=registry.checks?.find(check=>check.id==='check.architecture-reviewed');
+ // Unknown source rule revisions need an adapter update, never a local default.
+ if(check?.trigger!=='高风险或跨边界变化。')throw new TypeError('不支持当前生命周期架构审查规则');
+ const required=scope.risk_level==='high'||scope.impacted_areas.includes('high-risk')||scope.impacted_areas.some(impact=>['architecture','cross-repo','cross-boundary'].includes(impact))||scope.project_roots.length>1;
+ return {[check.id]:{status:required?'required':'not-applicable',reason:`${check.trigger} 本切片风险 ${scope.risk_level}，影响 ${scope.impacted_areas.join(', ')||'无'}，工程数 ${scope.project_roots.length}。`}};
+}