create-yss-spec 3.0.1 → 3.1.0

package/template/scripts/lib/approval-record.mjs

@@ -8,6 +8,7 @@ import {
   collectCountersignGateIds
 } from "./digital-human-roles.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
+import { assertUserDecisionRequirement, assertWorkUnitUserDecision, assertImplementationDecision } from "./user-decision.mjs";
 
 const DECISIONS = new Set(["approved", "rejected", "vetoed"]);
 const ACTOR_KINDS = new Set(["digital-human", "biological-human", "orchestrator"]);
@@ -47,7 +48,7 @@ export function resolveApprovalRef(approvalRef, fromFile = ROOT) {
   return path.resolve(path.dirname(fromFile), approvalRef);
 }
 
-export function validateApprovalRecord(record, { rolesDoc, requireApproved = false } = {}) {
+export function validateApprovalRecord(record, { rolesDoc, requireApproved = false, ...decisionOptions } = {}) {
   if (!record || typeof record !== "object" || Array.isArray(record)) fail("会签记录必须是对象");
   if (record.schema_version !== 1) fail("会签记录 schema_version 必须为 1");
   requireString(record.gate_id, "gate_id");
@@ -77,6 +78,7 @@ export function validateApprovalRecord(record, { rolesDoc, requireApproved = fal
   if (rule.bucket === "biological_human") {
     if (record.actor_kind !== "biological-human") fail(`${record.gate_id} 必须由生物人会签`);
     if (record.role_id !== BIOLOGICAL_ROLE_ID) fail(`${record.gate_id} 的 role_id 必须为 ${BIOLOGICAL_ROLE_ID}`);
+    if (requireApproved) assertRecordUserDecision(record, registry, decisionOptions);
     return rule;
   }
 
@@ -91,9 +93,16 @@ export function validateApprovalRecord(record, { rolesDoc, requireApproved = fal
   if (rule.drafter && record.drafter_role_id && record.drafter_role_id !== rule.drafter) {
     fail(`${record.gate_id} drafter_role_id 必须为 ${rule.drafter}`);
   }
+  if (requireApproved) assertRecordUserDecision(record, registry, decisionOptions);
   return rule;
 }
 
+function assertRecordUserDecision(record, registry, options) {
+  if (!registry.user_decision_policy.gates.includes(record.gate_id) && countersignRuleForGate(registry.gate_policy, record.gate_id)?.bucket !== "biological_human") return;
+  const result = assertUserDecisionRequirement({ boundary: record.gate_id, subject_ref: record.subject_ref, scope: record.approval_scope, user_decision_ref: record.user_decision_ref }, { ...options, rolesDoc: registry });
+  if (record.actor_kind === "biological-human" && result.validated.some((item) => item.principal_ref !== record.principal_ref)) fail("user-decision-responder-mismatch: 生物人会签者与原始回复者不一致");
+}
+
 export function validateApprovalRecordFile(filePath, options = {}) {
   return validateApprovalRecord(loadApprovalRecord(filePath), options);
 }
@@ -111,6 +120,11 @@ export function assertApprovedGateHasValidApproval(gateId, gateState, { checkpoi
   if (!existsSync(resolved)) fail(`${gateId} 的 approval_ref 不可读: ${gateState.approval_ref}`);
   const record = loadApprovalRecord(resolved);
   if (record.gate_id !== gateId) fail(`${gateId} 的会签记录 gate_id 不匹配`);
+  if (rolesDoc.user_decision_policy.gates.includes(gateId) || countersignRuleForGate(rolesDoc.gate_policy, gateId)?.bucket === "biological_human") {
+    if (!gateState.subject_ref || gateState.subject_ref !== record.subject_ref || JSON.stringify([...(gateState.approval_scope || [])].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) {
+      fail(`${gateId} user-decision-subject-mismatch: 当前门禁资产与会签范围不匹配`);
+    }
+  }
   validateApprovalRecord(record, { rolesDoc, requireApproved: true });
 }
 
@@ -121,3 +135,20 @@ export function assertCheckpointApprovals(checkpoint, checkpointPath) {
     assertApprovedGateHasValidApproval(gateId, state, { checkpointPath });
   }
 }
+
+// Called on resume/transition as well as completion; drafting while waiting stays allowed.
+export function assertCheckpointUserDecisions(checkpoint) {
+  if (checkpoint.repository_mode !== "project-instance") return;
+  const review = checkpoint.human_review || {};
+  const advancing = ["running", "completed"].includes(checkpoint.status) || (checkpoint.mode === "resume" && checkpoint.status === "routing");
+  if (!advancing) return;
+  const state = { user_decisions: review.user_decisions || [], user_decision_not_applicable: review.not_applicable || [] };
+  const completedUnit = checkpoint.stage_trace?.completed_work_unit;
+  if (completedUnit) assertWorkUnitUserDecision(completedUnit, state);
+  if (checkpoint.next_work_unit === "work-unit.slice-implementation") assertImplementationDecision({ ...review.implementation, ...state });
+  for (const requirement of review.required_decisions || []) assertUserDecisionRequirement(requirement);
+  if (review.external_input) assertUserDecisionRequirement({ ...review.external_input, boundary: "external-input" });
+  if (checkpoint.status === "completed") {
+    if (checkpoint.gates?.["gate.release-ready"]?.status !== "approved") throw new TypeError("user-decision-response-required: 阶段完成须发布就绪裁决");
+  }
+}

package/template/scripts/lib/backend-architecture.mjs

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { loadSkillRegistry } from "./skill-registry.mjs";
+
+export function architectureDigest(value) {
+  const stable = (item) => Array.isArray(item) ? item.map(stable) : item && typeof item === "object"
+    ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, stable(item[key])])) : item;
+  return createHash("sha256").update(JSON.stringify(stable(value))).digest("hex");
+}
+
+export function validateArchitectureIdentity(identity, registry = loadSkillRegistry()) {
+  if (!identity || typeof identity !== "object") throw new TypeError("缺少 architecture_identity；请从工程基线重新编译");
+  const profile = registry.architecture_profiles?.[identity.architecture_profile];
+  if (!profile || identity.architecture_family !== profile.architecture_family || identity.generator_skill !== profile.generator_skill) {
+    throw new TypeError("architecture_identity 的架构族、Profile 或生成器不匹配");
+  }
+  if (identity.verification_database !== "h2" || identity.production_database !== "not-bound") throw new TypeError("脚手架身份必须绑定 H2 验证和 production_database=not-bound");
+  if (!Array.isArray(identity.requested_capabilities) || !Array.isArray(identity.resolved_modules)) throw new TypeError("architecture_identity 缺少模块闭包");
+  if (new Set(identity.requested_capabilities).size !== identity.requested_capabilities.length) throw new TypeError("requested_capabilities 不允许重复");
+  const modules = [...profile.core_modules];
+  for (const capability of identity.requested_capabilities) {
+    const additions = profile.capability_modules[capability];
+    if (!additions) throw new TypeError(`Profile 不支持 capability: ${capability}`);
+    for (const module of additions) if (!modules.includes(module)) modules.push(module);
+  }
+  if (new Set(identity.resolved_modules).size !== identity.resolved_modules.length ||
+      modules.length !== identity.resolved_modules.length || modules.some((module) => !identity.resolved_modules.includes(module))) throw new TypeError("architecture_identity 模块闭包不匹配");
+  if (typeof identity.contract_digest !== "string" || !/^(sha256:)?[a-f0-9]{64}$/.test(identity.contract_digest)) throw new TypeError("architecture_identity 缺少有效 contract_digest");
+  return profile;
+}
+
+export function assertArchitectureAgreement(identity, evidence, registry) {
+  validateArchitectureIdentity(identity, registry);
+  for (const [name, source] of Object.entries(evidence ?? {})) {
+    const actual = source?.architecture_identity ?? source;
+    validateArchitectureIdentity(actual, registry);
+    if (architectureDigest(identity) !== architectureDigest(actual)) throw new TypeError(`stale: ${name} architecture_identity 与合同不一致`);
+  }
+}
+
+export function architectureReady(identity, registry = loadSkillRegistry()) {
+  const profile = validateArchitectureIdentity(identity, registry);
+  return profile.maturity === "supported";
+}

package/template/scripts/lib/context-contract.mjs

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const CONTEXT_FILE = "CONTEXT.md";
+const CONTEXT_MAP_FILE = "CONTEXT-MAP.md";
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]+$/;
+const TERM_REF = /^(Global|[A-Z][A-Za-z0-9]+)\/([A-Z][A-Za-z0-9]+)$/;
+const SKIP_DIRECTORIES = new Set([".git", ".codegraph", ".template-source", "node_modules", "dist", "build"]);
+
+function fail(messages, code = "context-contract-invalid") {
+  const error = new TypeError(messages.join("；"));
+  error.code = code;
+  error.problems = messages;
+  throw error;
+}
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function normalizedSource(source) {
+  return source.replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").replace(/\n*$/, "\n");
+}
+
+function collectContextFiles(root) {
+  const found = [];
+  function visit(directory, relative = "") {
+    if (relative && existsSync(path.join(directory, ".git"))) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRECTORIES.has(entry.name)) visit(entryPath, entryRelative);
+        continue;
+      }
+      if (entry.isFile() && [CONTEXT_FILE, CONTEXT_MAP_FILE, "context.md"].includes(entry.name)) found.push(entryRelative);
+    }
+  }
+  visit(root);
+  return found;
+}
+
+function splitRow(line) {
+  const value = line.trim();
+  if (!value.startsWith("|") || !value.endsWith("|")) return null;
+  return value.slice(1, -1).split("|").map((cell) => cell.trim());
+}
+
+function tableAfterHeading(lines, heading, expectedHeaders, problems) {
+  const headerVariants = Array.isArray(expectedHeaders[0]) ? expectedHeaders : [expectedHeaders];
+  const primaryHeaders = headerVariants[0];
+  const headingIndex = lines.findIndex((line) => line.trim() === heading);
+  if (headingIndex < 0) {
+    problems.push(`缺少 ${heading}`);
+    return [];
+  }
+  let headerIndex = headingIndex + 1;
+  while (headerIndex < lines.length && !lines[headerIndex].trim().startsWith("|") && !lines[headerIndex].trim().startsWith("## ")) headerIndex += 1;
+  const headers = splitRow(lines[headerIndex] || "");
+  if (!headerVariants.some((candidate) => JSON.stringify(headers) === JSON.stringify(candidate))) {
+    problems.push(`${heading} 表头必须是 ${headerVariants.map((candidate) => candidate.join(" | ")).join("；兼容旧项目时也接受 ")}`);
+    return [];
+  }
+  const separator = splitRow(lines[headerIndex + 1] || "");
+  if (!separator || separator.length !== primaryHeaders.length || separator.some((cell) => !/^:?-{3,}:?$/.test(cell))) {
+    problems.push(`${heading} 缺少合法 Markdown 表格分隔行`);
+    return [];
+  }
+  const rows = [];
+  for (let index = headerIndex + 2; index < lines.length; index += 1) {
+    const row = splitRow(lines[index]);
+    if (!row) break;
+    if (row.length !== primaryHeaders.length) {
+      problems.push(`${heading} 第 ${index + 1} 行列数应为 ${primaryHeaders.length}`);
+      continue;
+    }
+    rows.push({ line: index + 1, cells: row });
+  }
+  return rows;
+}
+
+function parseForbiddenAliases(value) {
+  const match = value.match(/(?:^|；)\s*避免[：:]\s*([^；]+)/);
+  if (!match) return [];
+  return match[1].split(/[、,，]/).map((item) => item.trim().replace(/^`|`$/g, "")).filter(Boolean);
+}
+
+function canonicalTerm(term) {
+  return {
+    term_ref: term.term_ref,
+    term: term.term,
+    meaning: term.meaning,
+    english_identifier: term.english_identifier,
+    context_id: term.context_id,
+    forbidden_aliases: [...term.forbidden_aliases].sort(),
+  };
+}
+
+export function parseContextContract({ root = process.cwd(), allowedContextIds } = {}) {
+  const absoluteRoot = path.resolve(root);
+  const contextPath = path.join(absoluteRoot, CONTEXT_FILE);
+  const problems = [];
+  const discovered = collectContextFiles(absoluteRoot);
+  if (!existsSync(contextPath) || !lstatSync(contextPath).isFile()) problems.push(`项目根目录缺少大小写精确的 ${CONTEXT_FILE}`);
+  const nested = discovered.filter((entry) => entry.endsWith(`/${CONTEXT_FILE}`));
+  if (nested.length) problems.push(`只允许项目根目录的 ${CONTEXT_FILE}，发现嵌套文件: ${nested.join(", ")}`);
+  const contextMaps = discovered.filter((entry) => entry === CONTEXT_MAP_FILE || entry.endsWith(`/${CONTEXT_MAP_FILE}`));
+  if (contextMaps.length) problems.push(`${CONTEXT_MAP_FILE} 在 YSS Context Contract 中禁止使用: ${contextMaps.join(", ")}`);
+  if (discovered.includes("context.md")) problems.push(`文件名大小写错误：必须使用根目录 ${CONTEXT_FILE}`);
+  if (problems.length || !existsSync(contextPath)) fail(problems);
+
+  return parseContextSource(readFileSync(contextPath, "utf8"), { allowedContextIds });
+}
+
+export function parseContextSource(text, { allowedContextIds } = {}) {
+  const problems = [];
+  const source = normalizedSource(text);
+  if (!/^---\ncontext_schema_version:\s*1\n---\n/.test(source)) problems.push("CONTEXT.md 顶部必须声明 context_schema_version: 1");
+  const lines = source.split("\n");
+  const processRows = tableAfterHeading(lines, "## 流程术语", ["术语", "含义", "英文标识", "避免 / 备注"], problems);
+  const businessRows = tableAfterHeading(lines, "## 业务术语", [
+    ["术语", "含义", "英文标识", "适用业务责任区", "避免 / 备注"],
+    ["术语", "含义", "英文标识", "适用限界上下文", "避免 / 备注"],
+  ], problems);
+
+  for (const row of processRows) {
+    if (row.cells.some((cell, index) => index < 3 && !cell)) problems.push(`流程术语第 ${row.line} 行存在空必填列`);
+    if (row.cells[2] !== "—") problems.push(`流程术语第 ${row.line} 行英文标识必须为 —`);
+  }
+
+  const terms = [];
+  const identities = new Map();
+  const scopedNames = new Map();
+  const scopedAliases = new Map();
+  const allowed = allowedContextIds ? new Set(allowedContextIds) : null;
+  for (const row of businessRows) {
+    const [term, meaning, englishIdentifier, contextId, notes] = row.cells;
+    if (![term, meaning, englishIdentifier, contextId].every(Boolean)) {
+      problems.push(`业务术语第 ${row.line} 行存在空必填列`);
+      continue;
+    }
+    if (!PASCAL_CASE.test(englishIdentifier)) problems.push(`业务术语第 ${row.line} 行英文标识必须是 PascalCase`);
+    if (contextId !== "Global" && !PASCAL_CASE.test(contextId)) problems.push(`业务术语第 ${row.line} 行适用业务责任区格式非法`);
+    if (allowed && contextId !== "Global" && !allowed.has(contextId)) problems.push(`业务术语 ${contextId}/${englishIdentifier} 的业务责任区未在业务边界与规则设计中登记`);
+    const termRef = `${contextId}/${englishIdentifier}`;
+    if (identities.has(termRef)) problems.push(`术语身份重复: ${termRef}`);
+    const scopedName = `${contextId}/${term}`;
+    if (scopedNames.has(scopedName)) problems.push(`同一作用域中文术语重复: ${scopedName}`);
+    const forbiddenAliases = parseForbiddenAliases(notes);
+    const aliasSet = scopedAliases.get(contextId) || new Set();
+    for (const alias of forbiddenAliases) {
+      if (aliasSet.has(alias) || scopedNames.has(`${contextId}/${alias}`)) problems.push(`同一作用域禁用别名冲突: ${contextId}/${alias}`);
+      aliasSet.add(alias);
+    }
+    scopedAliases.set(contextId, aliasSet);
+    const parsed = { term_ref: termRef, term, meaning, english_identifier: englishIdentifier, context_id: contextId, forbidden_aliases: forbiddenAliases, notes, line: row.line };
+    identities.set(termRef, parsed);
+    scopedNames.set(scopedName, parsed);
+    terms.push(parsed);
+  }
+
+  const globalTerms = terms.filter((term) => term.context_id === "Global");
+  for (const globalTerm of globalTerms) {
+    for (const localTerm of terms.filter((term) => term.context_id !== "Global")) {
+      if (globalTerm.term === localTerm.term || globalTerm.english_identifier === localTerm.english_identifier) problems.push(`Global 术语不得被局部上下文重新定义: ${globalTerm.term_ref} / ${localTerm.term_ref}`);
+    }
+  }
+  if (problems.length) fail(problems);
+  return { context_ref: CONTEXT_FILE, context_schema_version: 1, document_digest: sha256(source), process_terms: processRows.length, business_terms: terms, terms_by_ref: identities };
+}
+
+export function resolveContextTermRefs(contract, termRefs = []) {
+  const problems = [];
+  const resolved = [];
+  for (const termRef of termRefs) {
+    if (typeof termRef !== "string" || !TERM_REF.test(termRef)) {
+      problems.push(`术语引用格式非法: ${String(termRef)}；必须使用 <ContextId>/<EnglishIdentifier>`);
+      continue;
+    }
+    const term = contract.terms_by_ref.get(termRef);
+    if (!term) problems.push(`术语引用无法解析: ${termRef}`);
+    else resolved.push(term);
+  }
+  if (problems.length) fail(problems, "context-reference-invalid");
+  const canonical = resolved.map(canonicalTerm).sort((left, right) => left.term_ref.localeCompare(right.term_ref));
+  return { terms: resolved, referenced_terms_digest: sha256(JSON.stringify(canonical)) };
+}
+
+export function verifyContextSnapshot(snapshot, { root = process.cwd(), allowedContextIds } = {}) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) fail(["context_snapshot 必须是对象"]);
+  if (snapshot.context_ref !== CONTEXT_FILE) fail([`context_snapshot.context_ref 必须精确为 ${CONTEXT_FILE}`]);
+  if (snapshot.context_schema_version !== 1) fail(["context_snapshot.context_schema_version 必须为 1"]);
+  if (!Array.isArray(snapshot.term_refs)) fail(["context_snapshot.term_refs 必须是数组"]);
+  const contract = parseContextContract({ root, allowedContextIds });
+  const resolved = resolveContextTermRefs(contract, snapshot.term_refs);
+  const problems = [];
+  if (snapshot.document_digest !== contract.document_digest) problems.push("context_snapshot.document_digest 与当前 CONTEXT.md 不一致");
+  if (snapshot.referenced_terms_digest !== resolved.referenced_terms_digest) problems.push("context_snapshot.referenced_terms_digest 与引用术语不一致");
+  if (problems.length) fail(problems, "context-snapshot-stale");
+  return { ...contract, ...resolved };
+}

package/template/scripts/lib/digital-human-roles.mjs

@@ -197,7 +197,7 @@ function validateSignRule(rule, { actors, gateIds, claimed, field }) {
 }
 
 export function collectCountersignGateIds(policy) {
-  const ids = [];
+  const ids = [...(policy.unlisted_kept_biological || [])];
   for (const bucket of COUNTERSIGN_STRING_BUCKETS) {
     const gates = policy?.[bucket];
     if (Array.isArray(gates)) ids.push(...gates);
@@ -208,7 +208,12 @@ export function collectCountersignGateIds(policy) {
   for (const rule of policy?.dual_digital_human || []) {
     if (rule?.gate) ids.push(rule.gate);
   }
-  return ids;
+  if (policy.default_if_unlisted === "biological-human") {
+    for (const gate of loadRegistry().gates) {
+      if (!(policy.evidence_only || []).includes(gate.id) && !(policy.orchestrator || []).includes(gate.id)) ids.push(gate.id);
+    }
+  }
+  return [...new Set(ids)];
 }
 
 export function countersignRuleForGate(policy, gateId) {
@@ -222,6 +227,10 @@ export function countersignRuleForGate(policy, gateId) {
   if ((policy?.biological_human || []).includes(gateId)) {
     return { bucket: "biological_human", gate: gateId, countersigners: [BIOLOGICAL_ROLE_ID] };
   }
+  if ((policy?.evidence_only || []).includes(gateId) || (policy?.orchestrator || []).includes(gateId)) return null;
+  if (policy?.default_if_unlisted === "biological-human" && loadRegistry().gates.some((gate) => gate.id === gateId)) {
+    return { bucket: "biological_human", gate: gateId, countersigners: [BIOLOGICAL_ROLE_ID] };
+  }
   return null;
 }
 
@@ -323,7 +332,7 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
   }
   const claimed = new Set();
   for (const bucket of STRING_GATE_BUCKETS) {
-    requireStringArray(policy[bucket], `gate_policy.${bucket}`);
+    if (bucket !== "product_digital_human_with_biological_veto" || policy[bucket]?.length !== 0) requireStringArray(policy[bucket], `gate_policy.${bucket}`);
     for (const gate of policy[bucket]) {
       if (!gateIds.has(gate)) fail(`gate_policy.${bucket} 引用了未知门禁: ${gate}`);
       if (claimed.has(gate)) fail(`门禁被多个会签桶重复占用: ${gate}`);
@@ -370,6 +379,15 @@ export function validateDigitalHumanRoles(doc, { skillIds, stageIds, gateIds, ar
     if (claimed.has(gate)) fail(`unlisted_kept_biological 与会签桶重复: ${gate}`);
   }
 
+  const decisions = doc.user_decision_policy;
+  if (decisions?.schema_version !== 1 || decisions.default_responder !== "requester" || decisions.delegate_requires_requester_evidence !== true) fail("缺少统一用户决定策略");
+  requireStringArray(decisions.gates, "user_decision_policy.gates");
+  for (const gate of decisions.gates) if (!gateIds.has(gate)) fail(`用户决定引用未知门禁: ${gate}`);
+  for (const unit of Object.keys(decisions.work_units || {})) if (!workUnitIds.has(unit)) fail(`用户决定引用未知工作单元: ${unit}`);
+  if (!policy.biological_human.includes("gate.user-confirmation")) fail("gate.user-confirmation 必须由真实用户裁决");
+  for (const gate of [...(policy.unlisted_kept_biological || []), ...policy.biological_human]) {
+    if (!decisions.gates.includes(gate)) fail(`${gate} 缺少真实回复要求`);
+  }
   return {
     role_count: doc.roles.length,
     group_count: doc.stage_groups.length,

package/template/scripts/lib/first-slice-architecture.mjs

@@ -0,0 +1,23 @@
+/** 首切片验证的 MVC 适配器；命令执行与报告由统一验证核心持有。 */
+export function mvcFirstSliceProfile(identity) {
+  const application = identity.architecture_profile === "mvc-data-analysis-v1" ? "core" : "service";
+  const dto = identity.architecture_profile === "mvc-data-analysis-v1" ? "client" : "(?:server|client)";
+  return {
+    skills: ["yss-application", "yss-repository", "yss-mybatis", "yss-web-controller", "yss-dto", "yss-exception", "yss-validation", "mapstruct", "lombok", "alibaba-java-code-style"],
+    layers: [application, "repository", "server"],
+    artifacts: [
+      ["application-input", new RegExp(`-${application}/src/main/java/.+/(?:command|query)/.+\\.java$`)],
+      ["application-result", new RegExp(`-${application}/src/main/java/.+/result/.+\\.java$`)],
+      ["application-service", new RegExp(`-${application}/src/main/java/.+/service/.+Service(?:Impl)?\\.java$`)],
+      ["application-test", new RegExp(`-${application}/src/test/java/.+Tests?\\.java$`)],
+      ["repository-po", /-repository\/src\/main\/java\/.+\/po\/.+PO\.java$/],
+      ["repository", /-repository\/src\/main\/java\/.+Repository\.java$/],
+      ["repository-test", /-repository\/src\/test\/java\/.+Tests?\.java$/],
+      ["controller", /-server\/src\/main\/java\/.+Controller\.java$/],
+      ["web-convertor", /-server\/src\/main\/java\/.+WebConvertor\.java$/],
+      ["request", new RegExp(`-${dto}/src/main/java/.+/dto/request/.+Request\\.java$`)],
+      ["response", new RegExp(`-${dto}/src/main/java/.+/dto/response/.+Response\\.java$`)],
+      ["api-test", /-server\/src\/test\/java\/.+Tests?\.java$/]
+    ]
+  };
+}

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { DEFAULT_REGISTRY, loadSkillRegistry } from "./skill-registry.mjs";
 import { ROOT } from "./skill-supply-chain.mjs";
+import { architectureDigest, assertArchitectureAgreement, validateArchitectureIdentity } from "./backend-architecture.mjs";
 
 export const DEFAULT_COMPILER_CONTRACT = path.join(
   ROOT,
@@ -58,7 +59,9 @@ export function compileImplementationContract({
   conditions = [],
   compiledAt = new Date().toISOString(),
   registryDigest,
-  compilerContractDigest
+  compilerContractDigest,
+  architecture_identity,
+  architecture_evidence
 }) {
   assertV2(registry, compilerContract);
   if (!Array.isArray(recipeIds) || !Array.isArray(requiredCapabilities) || !Array.isArray(conditions)) {
@@ -71,6 +74,16 @@ export function compileImplementationContract({
   const knownRecipes = new Map(registry.recipes.map((recipe) => [recipe.id, recipe]));
   for (const recipeId of requestedRecipes) if (!knownRecipes.has(recipeId)) fail(`未知 recipe: ${recipeId}`);
   const orderedRecipes = registry.recipes.filter((recipe) => requestedRecipes.has(recipe.id));
+  const retiredRecipes = new Set(["backend.domain-behavior", "backend.persistence-mybatis", "backend.http-api"]);
+  for (const recipe of orderedRecipes) if (retiredRecipes.has(recipe.id) || recipe.maturity === "deprecated") fail(`deprecated/read-only Recipe ${recipe.id}；必须按架构重新编译`);
+  const architectural = orderedRecipes.some((recipe) => recipe.architecture_family) || requiredCapabilities.some((id) => id.startsWith("layer."));
+  let architectureProfile;
+  if (architectural || architecture_identity) {
+    architectureProfile = validateArchitectureIdentity(architecture_identity, registry);
+    if (!architecture_evidence?.engineering_baseline || !architecture_evidence?.repository_registration || !architecture_evidence?.manifest) fail("缺少工程基线、仓库登记或 Manifest 架构证据");
+    assertArchitectureAgreement(architecture_identity, architecture_evidence, registry);
+    for (const recipe of orderedRecipes) if (recipe.architecture_family && recipe.architecture_family !== architecture_identity.architecture_family) fail(`Recipe ${recipe.id} 与架构族不匹配`);
+  }
 
   const capabilitySources = new Map();
   const orderedCapabilities = [];
@@ -90,6 +103,11 @@ export function compileImplementationContract({
 
   const capabilities = new Map(registry.capabilities.map((capability) => [capability.id, capability]));
   for (const capabilityId of orderedCapabilities) if (!capabilities.has(capabilityId)) fail(`未知 capability: ${capabilityId}`);
+  const dddCapabilities = new Set(["layer.domain", "layer.application", "layer.persistence", "layer.web-adapter"]);
+  for (const id of orderedCapabilities) {
+    const family = capabilities.get(id).architecture_family ?? (dddCapabilities.has(id) ? "domain-driven" : null);
+    if (family && family !== architecture_identity?.architecture_family) fail(`capability ${id} 与 architecture_identity 不匹配`);
+  }
   const knownSkills = new Set(registry.skills.map((skill) => skill.id));
   const conditionSet = new Set(conditions);
   const reasons = new Map();
@@ -142,6 +160,13 @@ export function compileImplementationContract({
   return {
     schema_version: 2,
     status: "draft",
+    ...(architecture_identity ? {
+      architecture_identity: structuredClone(architecture_identity),
+      architecture_identity_digest: architectureDigest(architecture_identity),
+      profile_maturity: architectureProfile.maturity,
+      readiness_blockers: architectureProfile.maturity === "supported" ? [] : ["backend-profile-not-supported"],
+      skill_profiles: Object.fromEntries(orderedSkills.map((skill) => [skill, architecture_identity.architecture_profile]))
+    } : {}),
     recipe_ids: orderedRecipes.map((recipe) => recipe.id),
     conditions: [...conditionSet].sort(),
     required_capabilities: orderedCapabilities,
@@ -171,6 +196,11 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
   const reasons = [];
   if (resolution.registry_digest !== digestDocument(registry)) reasons.push("registry-digest-changed");
   if (resolution.compiler_contract_digest !== digestDocument(compilerContract)) reasons.push("compiler-contract-digest-changed");
+  if (resolution.architecture_identity) {
+    try { validateArchitectureIdentity(resolution.architecture_identity, registry); }
+    catch { reasons.push("architecture-identity-invalid"); }
+    if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-digest-changed");
+  }
   return { freshness: reasons.length ? "stale" : "current", reasons };
 }
 
@@ -183,11 +213,14 @@ export function validateExecutionResult(result, contract, current) {
   const consumed = result.consumed_contract ?? {};
   const resolution = contract.resolution ?? contract;
   const blockers = [];
+  if (resolution.architecture_identity && architectureDigest(result.architecture_identity ?? null) !== resolution.architecture_identity_digest) blockers.push("architecture-identity-mismatch");
+  if (resolution.readiness_blockers?.length) blockers.push(...resolution.readiness_blockers);
   if (consumed.contract_id !== contract.contract_id || consumed.contract_version !== contract.contract_version) blockers.push("contract-version-mismatch");
   if (consumed.registry_digest !== resolution.registry_digest || consumed.compiler_contract_digest !== resolution.compiler_contract_digest) blockers.push("resolution-digest-mismatch");
   if (!Array.isArray(result.verification_results) || !result.verification_results.length) blockers.push("verification-not-executed");
   else for (const item of result.verification_results) {
     if (!item?.command || item.exit_code === undefined || !item.executed_at) blockers.push("verification-result-incomplete");
+    else if (item.exit_code !== 0) blockers.push("verification-failed");
   }
   if (Array.isArray(result.new_impacts) && result.new_impacts.length) blockers.push("new-impacts");
   return { status: blockers.length ? "blocked" : "accepted", blockers: [...new Set(blockers)] };

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

@@ -51,7 +51,10 @@ function canonicalize(value) {
 }
 
 export function semanticProjection(registry) {
-  return COLLECTIONS.flatMap((kind) => registry[kind].map((record) => ({ kind, record: canonicalize(record) })))
+  return COLLECTIONS.flatMap((kind) => registry[kind].map((record) => ({
+    kind,
+    record: canonicalize(Object.fromEntries(Object.entries(record).filter(([key]) => !key.startsWith("public_"))))
+  })))
     .sort((left, right) => left.record.id.localeCompare(right.record.id));
 }
 
@@ -117,6 +120,9 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
       const prefix = collection === "work_units" ? "work-unit." : collection === "evidence" ? "evidence." : `${collection.slice(0, -1)}.`;
       if (!id.startsWith(prefix)) fail(`${id} 与 ${collection} 类型不匹配`);
       if (typeof record.name !== "string" || record.name.length === 0) fail(`${id} 缺少名称`);
+      for (const [key, value] of Object.entries(record).filter(([key]) => key.startsWith("public_"))) {
+        if (typeof value !== "string" || value.trim().length === 0) fail(`${id}.${key} 必须是非空字符串`);
+      }
       ids.set(id, collection);
     }
   }
@@ -143,25 +149,27 @@ export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {})
 }
 
 export function renderLifecycleStructure(registry) {
+  const display = (record, field) => record[`public_${field}`] ?? record[field];
   const lines = [
     "<!-- lifecycle-registry:structure:start -->",
     `> 此结构区由 \`docs/process/lifecycle-registry.yaml\` 生成。当前为 \`${registry.status}\` 模式：它校验结构和派生文档，不改变运行时状态 schema 或人工批准语义。`, "",
     "## 1. 主阶段", "", "| 稳定 ID | 阶段 | 目标 | 退出标准 |", "|---|---|---|---|"
   ];
-  for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${stage.name} | ${stage.goal} | ${stage.exit_criteria} |`);
+  for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${display(stage, "name")} | ${display(stage, "goal")} | ${display(stage, "exit_criteria")} |`);
   lines.push("", "## 2. 生命周期对象", "", "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 \`not-applicable\` 及原因，不生成空文档。", "", "### 2.1 条件门禁", "", "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 前置门禁 | 必须留下的证据 |", "|---|---|---|---|---|---|");
-  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${gate.name} | \`${gate.stage}\` | ${gate.trigger} | ${(gate.requires_gates ?? []).map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
+  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${display(gate, "name")} | \`${gate.stage}\` | ${display(gate, "trigger")} | ${(gate.requires_gates ?? []).map((id) => `\`${id}\``).join("、") || "无"} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
   lines.push("", "### 2.2 生命周期产物", "", "| 稳定 ID | 产物 | 所属阶段 | 触发条件 |", "|---|---|---|---|");
-  for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${artifact.name} | \`${artifact.stage}\` | ${artifact.trigger} |`);
+  for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${display(artifact, "name")} | \`${artifact.stage}\` | ${display(artifact, "trigger")} |`);
   lines.push("", "### 2.3 执行证据", "", "| 稳定 ID | 证据 | 说明 |", "|---|---|---|");
-  for (const evidence of registry.evidence) lines.push(`| \`${evidence.id}\` | ${evidence.name} | ${evidence.description} |`);
+  for (const evidence of registry.evidence) lines.push(`| \`${evidence.id}\` | ${display(evidence, "name")} | ${display(evidence, "description")} |`);
   lines.push("<!-- lifecycle-registry:structure:end -->");
   return `${lines.join("\n")}\n`;
 }
 
 export function renderWorkUnits(registry) {
+  const display = (record, field) => record[`public_${field}`] ?? record[field];
   const lines = ["<!-- lifecycle-registry:work-units:start -->", "> 此表由 `docs/process/lifecycle-registry.yaml` 生成；工作单元按 `scope` 区分模板维护与项目实例流程。", "", "| 稳定 ID | 范围 | 工作单元 | 输入 | 输出 | 完成条件 |", "|---|---|---|---|---|---|"];
-  for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.scope} | ${unit.name} | ${unit.input} | ${unit.output} | ${unit.completion} |`);
+  for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.scope} | ${display(unit, "name")} | ${display(unit, "input")} | ${display(unit, "output")} | ${display(unit, "completion")} |`);
   lines.push("<!-- lifecycle-registry:work-units:end -->");
   return `${lines.join("\n")}\n`;
 }

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

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { parseDocument } from "../vendor/yaml.mjs";
+import { assertWorkUnitUserDecision, assertImplementationDecision } from "./user-decision.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
 const TICKET_DECOMPOSITION_WORK_UNIT = "work-unit.ticket-decomposition";
@@ -110,10 +111,13 @@ function validateTicketReference(ref, trackerKind) {
  * Workflow Execution Result may omit a route; completed results are checked
  * by `validateWorkflowExecutionResult` before this function is called.
  */
-export function validateNextRoute(currentWorkUnit, nextRoute) {
+export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
   const routes = NEXT_ROUTES[currentWorkUnit];
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
-  if (nextRoute === null && routes.length === 0) return allowedResult();
+  if (nextRoute === null && routes.length === 0) {
+    if (decisionState) return validateDecisionBoundary(currentWorkUnit, decisionState, options);
+    return allowedResult();
+  }
   if (!hasText(nextRoute) || !routes.includes(nextRoute)) {
     const signals = [BLOCKING_SIGNALS.invalidRoute];
     if (nextRoute === IMPLEMENTATION_WORK_UNIT && currentWorkUnit !== TICKET_DECOMPOSITION_WORK_UNIT) {
@@ -121,14 +125,19 @@ export function validateNextRoute(currentWorkUnit, nextRoute) {
     }
     return blockedResult(signals, ["allowed_next_route"]);
   }
-  return allowedResult();
+  return decisionState ? validateDecisionBoundary(currentWorkUnit, decisionState, options) : allowedResult();
+}
+
+function validateDecisionBoundary(workUnit, state, options) {
+  try { assertWorkUnitUserDecision(workUnit, state, options); return allowedResult(); }
+  catch (error) { return blockedResult([error.code || "user-decision-invalid"], [error.message]); }
 }
 
 /**
  * Validate that Ticket formalization produced a real, implementable vertical slice.
  * `exists` is injectable so external adapters can resolve their own tracker refs.
  */
-export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8") } = {}) {
+export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
   const decomposition = state?.ticket_decomposition_result;
   const ticket = state?.vertical_slice_ticket;
   const contract = state?.slice_contract;
@@ -233,6 +242,12 @@ export function validateTicketFormalization(state, { exists = existsSync, read =
     missing.push("ticket formalization inputs are current");
   }
 
+  try {
+    assertImplementationDecision(state, { ...decisionOptions, read });
+  } catch (error) {
+    signals.push(error.code || "user-decision-invalid");
+    missing.push(error.message);
+  }
   return signals.length === 0 ? allowedResult(evidenceRefs) : blockedResult(signals, missing, evidenceRefs);
 }
 

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

@@ -0,0 +1,26 @@
+/** 新后端骨架仅提供显式本地验证配置；不绑定生产数据库。 */
+export const VERIFICATION_DATABASE = "h2";
+export const PRODUCTION_DATABASE = "not-bound";
+
+export function assertLocalDatabaseProfile(profiles) {
+  if (profiles?.verification_database !== VERIFICATION_DATABASE || profiles?.production_database !== PRODUCTION_DATABASE || Object.hasOwn(profiles ?? {}, "database")) {
+    throw new Error("新脚手架必须声明 verification_database=h2、production_database=not-bound；旧 database Profile 必须重新批准，不作静默迁移");
+  }
+}
+
+export function localDatabaseConfiguration(name) {
+  return `# 仅通过 scaffold-local 显式启用；不用于生产。\nspring:\n  datasource:\n    url: jdbc:h2:mem:${name.replaceAll("-", "_")};DB_CLOSE_DELAY=-1\n    username: sa\n    password: \"\"\n    driver-class-name: org.h2.Driver\n  sql:\n    init:\n      mode: never\n  cloud:\n    discovery:\n      enabled: false\n    service-registry:\n      auto-registration:\n        enabled: false\n    nacos:\n      discovery:\n        enabled: false\n      config:\n        enabled: false\n  cache:\n    type: none\n`;
+}
+
+export function scaffoldArchitectureIdentity(contract, contractDigest) {
+  return {
+    architecture_family: contract.architecture_family,
+    architecture_profile: contract.architecture_profile,
+    generator_skill: contract.generator_skill,
+    requested_capabilities: contract.module_profile.requested_capabilities,
+    resolved_modules: contract.module_profile.resolved_modules,
+    contract_digest: contractDigest,
+    verification_database: VERIFICATION_DATABASE,
+    production_database: PRODUCTION_DATABASE
+  };
+}