create-yss-spec 3.3.8 → 3.4.1

package/template/scripts/lib/legacy-backend-scaffold-audit.test.mjs

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { auditLegacyBackendScaffold } from "./legacy-backend-scaffold-audit.mjs";
+
+const rawDigest = (value) => createHash("sha256").update(value).digest("hex");
+
+async function fixture(t) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "legacy-scaffold-audit-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const generated = "package com.yss.demo;\n";
+  const source = "demo-service-server/src/main/java/com/yss/demo/package-info.java";
+  await mkdir(path.join(root, path.dirname(source)), { recursive: true });
+  await writeFile(path.join(root, source), generated);
+  const manifest = {
+    schema_version: 3,
+    kind: "backend-scaffold",
+    completion_level: "empty-scaffold-verified",
+    ownership: { generated_files: [{ path: source, owner: "generator", sha256: rawDigest(generated) }] },
+  };
+  await mkdir(path.join(root, ".yss"));
+  await writeFile(path.join(root, ".yss/scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  return { root, source };
+}
+
+test("未修改的历史 v3 机械骨架可进入恢复对账但不会自动批准", async (t) => {
+  const data = await fixture(t);
+  const result = await auditLegacyBackendScaffold(data.root);
+  assert.equal(result.status, "reconcilable");
+  assert.equal(result.ownership_state, "unchanged-mechanical-scaffold");
+  assert.equal(result.premature_implementation, false);
+  assert.deepEqual(result.generated_file_drift, []);
+});
+
+test("额外业务代码保留并标记 premature-implementation-detected", async (t) => {
+  const data = await fixture(t);
+  const controller = "demo-service-server/src/main/java/com/yss/demo/controller/DemoController.java";
+  await mkdir(path.join(data.root, path.dirname(controller)), { recursive: true });
+  await writeFile(path.join(data.root, controller), "class DemoController {}\n");
+  const result = await auditLegacyBackendScaffold(data.root);
+  assert.equal(result.status, "blocked");
+  assert.equal(result.ownership_state, "premature-implementation-detected");
+  assert.equal(result.premature_implementation, true);
+  assert.deepEqual(result.business_files, [controller]);
+});
+
+test("历史生成文件摘要漂移时保持 blocked", async (t) => {
+  const data = await fixture(t);
+  await writeFile(path.join(data.root, data.source), "changed\n");
+  const result = await auditLegacyBackendScaffold(data.root);
+  assert.equal(result.status, "blocked");
+  assert.equal(result.ownership_state, "generated-file-drift");
+  assert.equal(result.generated_file_drift[0].path, data.source);
+});
+
+test("审计器拒绝将 v4 当作历史恢复输入", async (t) => {
+  const data = await fixture(t);
+  const manifestFile = path.join(data.root, ".yss/scaffold-generation.json");
+  await writeFile(manifestFile, JSON.stringify({ schema_version: 4, ownership: { generated_files: [] } }));
+  await assert.rejects(() => auditLegacyBackendScaffold(data.root), /历史 v3/);
+});

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

@@ -1,8 +1,13 @@
+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 +33,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 +73,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 +115,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);
+    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 +253,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 +267,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 +287,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 +334,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 +357,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 +402,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/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/strategic-feedback.mjs

@@ -6,14 +6,14 @@ 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');
+  ensure([2,3].includes(receipt.schema_version),'Consumer Feedback v1 只接受 route-aware Import Receipt v2/v3');
   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 包');
+    ensure([4,5].includes(bundle.handoff.schema_version)&&bundle.manifest.bundle_digest===receipt.bundle_digest,'Consumer Feedback 必须绑定当前 Handoff v4/v5 包');
     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};

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

@@ -24,10 +24,10 @@ 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){
+  if([2,3].includes(receipt.schema_version)){
     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`);
+    ensure(route&&route.activation!=='not-applicable'&&binding.route_id===route.route_id,`${capability} 未绑定当前 Handoff v4/v5 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}`);