create-yss-spec 3.0.0 → 3.1.0

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

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { ROOT } from "./lifecycle-registry.mjs";
+import { loadDigitalHumanRoles } from "./digital-human-roles.mjs";
+import { validateJsonSchema } from "./json-schema.mjs";
+
+export function decisionError(code, detail) {
+  const error = new TypeError(`${code}: ${detail}`);
+  error.code = code;
+  throw error;
+}
+const requireText = (value, label) => {
+  if (typeof value !== "string" || !value.trim()) decisionError("user-decision-missing", label);
+};
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+  ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+export const decisionDigest = (value) => `sha256:${createHash("sha256").update(typeof value === "string" || Buffer.isBuffer(value) ? value : JSON.stringify(canonical(value))).digest("hex")}`;
+export function requestDigest(request) {
+  const { presented_source, ...snapshot } = request;
+  return decisionDigest(snapshot);
+}
+export function decisionIO({ root = ROOT, read = (ref) => readFileSync(ref), ...rest } = {}) {
+  const resolve = (ref) => /^(?:https?:|\w+:\/\/)/.test(ref) ? ref : path.resolve(root, ref);
+  const bytes = (ref) => {
+    requireText(ref, "可读引用");
+    try { return read(resolve(ref)); } catch { decisionError("user-decision-source-unreadable", ref); }
+  };
+  const document = (ref) => {
+    const doc = parseDocument(String(bytes(ref)), { maxAliasCount: 0, uniqueKeys: true });
+    if (doc.errors.length || !doc.toJS()) decisionError("user-decision-source-invalid", ref);
+    return doc.toJS({ maxAliasCount: 0 });
+  };
+  return { root, bytes, document, ...rest };
+}
+
+// A capture preserves original author/time/text/reference. It is evidence, not an identity signature.
+function messageFromSource(source, io, policy) {
+  if (!source || !policy.source_kinds.includes(source.kind)) decisionError("user-decision-source-invalid", "需要原始消息、会话导出或用户确认文件");
+  const raw = io.bytes(source.ref);
+  if (decisionDigest(raw) !== source.digest) decisionError("user-decision-source-changed", source.ref);
+  const parsed = parseDocument(String(raw), { maxAliasCount: 0, uniqueKeys: true });
+  if (parsed.errors.length) decisionError("user-decision-source-invalid", source.ref);
+  const capture = parsed.toJS({ maxAliasCount: 0 });
+  if (capture?.source_kind !== source.kind || !Array.isArray(capture.messages)) decisionError("user-decision-source-invalid", "来源不是原始消息封装");
+  const matches = capture.messages.filter((message) => message.id === source.message_id);
+  if (matches.length !== 1) decisionError("user-decision-source-invalid", "消息 ID 缺失或重复");
+  const message = matches[0];
+  for (const field of ["principal_ref", "original_ref", "sent_at", "text"]) requireText(message[field], `原始消息 ${field}`);
+  if (!Number.isFinite(Date.parse(message.sent_at))) decisionError("user-decision-source-invalid", "原始消息时间无效");
+  return { ...message, _preceding_message: capture.messages[capture.messages.indexOf(message) - 1] };
+}
+
+export function renderDecisionRequest(request) {
+  return [
+    `决定请求 ${request.id} (${requestDigest(request)})`,
+    `提问者：${request.requester_ref}`,
+    ...request.items.flatMap((item) => [
+      `事项 ${item.id} / ${item.boundary}：${item.title}`,
+      `资产：${item.subject.ref}；版本：${item.subject.version}；摘要：${item.subject.digest}`,
+      `依据：${item.basis.map((asset) => `${asset.ref}@${asset.version} (${asset.digest})`).join("；") || "无额外依据"}`,
+      `关键变化：${item.changes}`,
+      `范围：${item.scope.join("；")}`,
+      `风险：${item.risks.join("；") || "已评估，无已知残余风险"}`,
+      `推荐方案：${item.recommendation}`,
+      `批准后动作：${item.next_actions.join("；")}`,
+      `回复负责人：${item.responder_ref}`,
+    ]),
+    "请明确批准、拒绝或提出修改；多事项回复须说明事项，或明确批准以上全部事项。",
+  ].join("\n");
+}
+
+function checkAsset(asset, io) {
+  if (decisionDigest(io.bytes(asset.ref)) !== asset.digest) decisionError("user-decision-stale", asset.ref);
+}
+
+export function validateUserDecision(record, options = {}) {
+  const io = decisionIO(options);
+  const policy = (options.rolesDoc || loadDigitalHumanRoles()).user_decision_policy;
+  validateJsonSchema(record, path.join(ROOT, "docs/process/schemas/user-decision.schema.json"), { label: "用户决定记录" });
+  const { request, responses } = record;
+  const originalRequest = messageFromSource(request.requester_source, io, policy);
+  if (originalRequest.actor_kind !== "biological-human" || originalRequest.principal_ref !== request.requester_ref) decisionError("user-decision-responder-mismatch", "提问者来源不匹配");
+  const presentation = messageFromSource(request.presented_source, io, policy);
+  const presentedFields = request.items.flatMap((item) => [item.title, item.subject.ref, item.subject.version, item.changes, item.recommendation, ...item.scope, ...item.risks, ...item.next_actions, ...item.basis.flatMap((asset) => [asset.ref, asset.version])]);
+  // Preserve equivalent historical presentations without requiring a new templated message.
+  if (presentation.text !== renderDecisionRequest(request) && !presentedFields.every((field) => presentation.text.includes(field))) decisionError("user-decision-presentation-mismatch", "原始展示未覆盖当前资产、版本、变化、风险、范围和后续动作");
+  if (Date.parse(presentation.sent_at) < Date.parse(originalRequest.sent_at)) decisionError("user-decision-source-invalid", "展示时间早于用户请求");
+  const items = new Map();
+  for (const item of request.items) {
+    if (items.has(item.id)) decisionError("user-decision-ambiguous", "事项 ID 重复");
+    items.set(item.id, item);
+    if (item.responder_ref !== request.requester_ref) {
+      const delegated = messageFromSource(item.delegation_source, io, policy);
+      if (delegated.actor_kind !== "biological-human" || delegated.principal_ref !== request.requester_ref || !delegated.text.includes(item.responder_ref) || !delegated.text.includes(item.id)) decisionError("user-decision-delegation-invalid", "负责人须有提问者指向该事项的指定原文");
+      if (Date.parse(delegated.sent_at) > Date.parse(presentation.sent_at)) decisionError("user-decision-delegation-invalid", "须先指定负责人再展示当前请求");
+    }
+  }
+  const outcomes = new Map();
+  const messageIds = new Set();
+  let previousTime = -Infinity;
+  for (const response of responses) {
+    const source = messageFromSource(response.source, io, policy);
+    const identity = `${response.source.ref}#${response.source.message_id}`;
+    if (messageIds.has(identity)) decisionError("user-decision-ambiguous", "回复消息重复");
+    messageIds.add(identity);
+    if (source.reply_to !== presentation.original_ref && source.request_digest !== requestDigest(request) && !(source._preceding_message?.original_ref === presentation.original_ref && source._preceding_message?.text === presentation.text)) decisionError("user-decision-subject-mismatch", "原始回复没有指向当前请求的来源关联");
+    if (source.actor_kind !== "biological-human" || source.principal_ref !== response.principal_ref || source.sent_at !== response.responded_at || source.text !== response.text) decisionError("user-decision-responder-mismatch", "记录与原始回复身份、时间或原文不一致");
+    if (response.request_digest !== requestDigest(request)) decisionError("user-decision-stale", "回复绑定的请求快照已变化");
+    const time = Date.parse(response.responded_at);
+    if (time < Date.parse(presentation.sent_at) || time < previousTime) decisionError("user-decision-source-invalid", "回复须在展示之后并按原始时间排序");
+    previousTime = time;
+    if (response.decision === "approved") {
+      const explicit = source.decision === "approved" && Array.isArray(source.item_ids) && response.item_ids.every((id) => source.item_ids.includes(id));
+      if (!explicit && (!/(同意|批准|确认|接受|可以|好的|^好[。！!\s]*$|\b(?:approve|approved|agree|agreed|accept|yes|ok)\b)/i.test(source.text) || /(不同意|不批准|拒绝|反对|不要|需[要]?修改|请修改|暂不|reject|decline|do not approve|don't approve|disagree)/i.test(source.text))) decisionError("user-decision-ambiguous", "原文不能明确支持批准结论");
+      if (!explicit && response.selection === "explicit-all" && items.size > 1 && !/(全部|所有|\ball\b)/i.test(source.text)) decisionError("user-decision-ambiguous", "批量批准原文必须明确全部事项");
+      if (!explicit && response.selection === "explicit-items" && items.size > 1 && response.item_ids.some((id) => !source.text.includes(id) && !source.text.includes(items.get(id)?.title))) decisionError("user-decision-ambiguous", "原文未指向所选事项");
+    }
+    if (response.selection === "single" && items.size !== 1) decisionError("user-decision-ambiguous", "多事项不能用单项回复");
+    if (items.size > 1 && /^(继续|continue|go ahead)[。.!！\s]*$/i.test(response.text.trim())) decisionError("user-decision-ambiguous", "继续不能解释为批准全部事项");
+    if (response.selection === "explicit-all" && (response.item_ids.length !== items.size || [...items.keys()].some((id) => !response.item_ids.includes(id)))) decisionError("user-decision-ambiguous", "全部批准必须枚举全部事项");
+    for (const id of response.item_ids) {
+      const item = items.get(id);
+      if (!item) decisionError("user-decision-subject-mismatch", id);
+      if (item.responder_ref !== response.principal_ref) decisionError("user-decision-responder-mismatch", id);
+      if (response.decision === "approved" && (response.approved_scope.length === 0 || response.approved_scope.some((scope) => !response.item_ids.some((selected) => items.get(selected)?.scope.includes(scope))))) decisionError("user-decision-scope-mismatch", id);
+      const previous = outcomes.get(id);
+      if (response.decision === "approved" && previous?.decision === "approved") {
+        outcomes.set(id, { ...response, approved_scope: [...new Set([...previous.approved_scope, ...response.approved_scope])] });
+      } else outcomes.set(id, response);
+    }
+  }
+  const validated = [];
+  for (const expected of options.expected || []) {
+    requireText(expected.boundary, "当前决定边界");
+    requireText(expected.subject_ref, "当前资产引用");
+    if (!Array.isArray(expected.scope) || expected.scope.length === 0) decisionError("user-decision-scope-mismatch", "当前批准范围缺失");
+    const matches = request.items.filter((item) => item.boundary === expected.boundary && item.subject.ref === expected.subject_ref && expected.scope.every((scope) => item.scope.includes(scope)));
+    if (matches.length !== 1) decisionError("user-decision-subject-mismatch", expected.boundary);
+    const item = matches[0];
+    checkAsset(item.subject, io);
+    item.basis.forEach((asset) => checkAsset(asset, io));
+    const answer = outcomes.get(item.id);
+    if (!answer) decisionError("user-decision-response-required", item.id);
+    if (answer.decision !== "approved") decisionError("user-decision-not-approved", `${item.id}: ${answer.decision}`);
+    if (!expected.scope.every((scope) => answer.approved_scope.includes(scope))) decisionError("user-decision-scope-mismatch", item.id);
+    validated.push({ item_id: item.id, boundary: expected.boundary, principal_ref: answer.principal_ref, scope: expected.scope });
+  }
+  return { request_id: request.id, validated, outcomes: Object.fromEntries([...outcomes].map(([id, answer]) => [id, answer.decision])) };
+}
+
+export function verifyUserDecisionFile(ref, options = {}) {
+  const io = decisionIO(options);
+  requireText(ref, "user_decision_ref");
+  return validateUserDecision(io.document(ref), options);
+}
+
+export function assertUserDecisionRequirement(requirement, options = {}) {
+  if (!requirement) decisionError("user-decision-response-required", "缺少当前决定及其范围");
+  return verifyUserDecisionFile(requirement.user_decision_ref, { ...options, expected: [requirement] });
+}
+
+export function assertWorkUnitUserDecision(workUnit, state, options = {}) {
+  const policy = (options.rolesDoc || loadDigitalHumanRoles()).user_decision_policy;
+  const boundaries = [...(policy.work_unit_gates?.[workUnit] || []), ...(policy.work_units[workUnit] ? [policy.work_units[workUnit]] : [])];
+  for (const boundary of boundaries) {
+    const notApplicable = state?.user_decision_not_applicable?.find((item) => item.boundary === boundary);
+    // Only existing conditional technical gates may be untriggered; an executed business decision cannot be skipped.
+    if (workUnit === "work-unit.technical-analysis" && notApplicable?.reason?.trim()) continue;
+    const requirement = state?.user_decisions?.find((item) => item.boundary === boundary);
+    if (!requirement) decisionError("user-decision-response-required", boundary);
+    assertUserDecisionRequirement(requirement, options);
+  }
+}
+
+export function assertImplementationDecision(state, options = {}) {
+  const requirement = state?.user_decisions?.find((item) => item.boundary === "implementation-scope");
+  const ticketRef = state?.vertical_slice_ticket_ref;
+  if (!requirement || !requirement.scope?.includes(ticketRef)) decisionError("user-decision-scope-mismatch", "实施范围必须包含当前切片");
+  assertUserDecisionRequirement(requirement, options);
+  const io = decisionIO(options);
+  const manifest = io.document(requirement.subject_ref);
+  const slices = manifest.slices?.filter((slice) => slice.ticket_ref === ticketRef);
+  if (manifest.kind !== "implementation-scope" || slices?.length !== 1) decisionError("user-decision-subject-mismatch", "实施范围清单未绑定当前切片");
+  const slice = slices[0];
+  requireText(state.slice_contract_ref, "当前持久化 Slice 合同引用");
+  if (state.slice_contract_ref !== slice.contract?.ref) decisionError("user-decision-subject-mismatch", "当前合同不在批准清单中");
+  checkAsset(slice.contract, io);
+  const content = io.document(slice.contract.ref);
+  const contract = content.slice_contract || content;
+  if (contract.lifecycle_refs?.ticket !== ticketRef) decisionError("user-decision-subject-mismatch", "持久化合同的切片引用不匹配");
+  for (const [manifestKey, contractKey] of [["repositories", "project_roots"], ["allowed_write_paths", "allowed_write_paths"]]) {
+    if (!Array.isArray(slice[manifestKey]) || slice[manifestKey].length === 0 || JSON.stringify([...slice[manifestKey]].sort()) !== JSON.stringify([...(contract.common?.[contractKey] || [])].sort())) decisionError("user-decision-scope-mismatch", manifestKey);
+  }
+  if (!Array.isArray(slice.baselines) || !slice.baselines.some((asset) => asset.ref === contract.lifecycle_refs?.engineering_baseline)) decisionError("user-decision-scope-mismatch", "工程基线缺失");
+  slice.baselines.forEach((asset) => checkAsset(asset, io));
+}
+
+export function scaffoldDecisionSnapshot(decision) {
+  const { user_confirmation, status, decision_inputs_digest, ...inputs } = decision;
+  return inputs;
+}
+export function assertScaffoldUserDecision(decision, options = {}) {
+  const confirmation = decision.user_confirmation || {};
+  const requirement = { boundary: "scaffold-choice", subject_ref: confirmation.decision_subject_ref, scope: [decision.project_id, decision.confirmed_architecture, decision.decision_inputs_digest], user_decision_ref: confirmation.user_decision_ref };
+  assertUserDecisionRequirement(requirement, options);
+  const io = decisionIO(options);
+  if (decisionDigest(io.document(requirement.subject_ref)) !== decisionDigest(scaffoldDecisionSnapshot(decision))) decisionError("user-decision-stale", "脚手架输入与用户所见快照不一致");
+}

package/template/scripts/strategic-handoff

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { exportBundle, openBundle, importBundle } from './lib/strategic-handoff.mjs';
+try {
+  const {values,positionals}=parseArgs({allowPositionals:true,strict:true,options:{'source-root':{type:'string'},handoff:{type:'string'},output:{type:'string'},zip:{type:'boolean'},previous:{type:'string'},bundle:{type:'string'},'target-root':{type:'string'}}});
+  const [command]=positionals;
+  let result;
+  if(command==='export'&&values['source-root']&&values.handoff&&values.output)result=await exportBundle({sourceRoot:values['source-root'],handoffRef:values.handoff,output:values.output,zip:values.zip,previous:values.previous});
+  else if(command==='verify'&&values.bundle)result=await openBundle(path.resolve(values.bundle),b=>({result:'verified',bundle_id:b.manifest.bundle_id,version:b.manifest.version,bundle_digest:b.manifest.bundle_digest,rules:b.indexes.rules.length,scenarios:b.indexes.scenarios.length}));
+  else if(command==='import'&&values.bundle&&values['target-root'])result=await importBundle({bundle:path.resolve(values.bundle),targetRoot:values['target-root']});
+  else throw new TypeError('用法: strategic-handoff export --source-root <repo> --handoff <relative-file> --output <new-dir> [--zip] [--previous <bundle>] | verify --bundle <dir|zip> | import --bundle <dir|zip> --target-root <repo>');
+  process.stdout.write(`${JSON.stringify(result,null,2)}\n`);
+}catch(error){process.stderr.write(`${JSON.stringify({result:'blocked',error:error.message})}\n`);process.exitCode=1;}

package/template/scripts/sync-strategic-handoff-tools

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Main-template-owned shared handoff implementation; never edits runtime skill projections.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { inspectWorkingTreeScope } from './lib/repository-scope-policy.mjs';
+const root=path.resolve(import.meta.dirname,'..');
+const check=process.argv.includes('--check');
+const targets=['submodules/yss-harness-design-agent','submodules/yss-harness-dev-agent'];
+const shared=['scripts/strategic-handoff','scripts/verify-strategic-handoff-consumption','scripts/verify-strategic-handoff-package-scenarios','scripts/verify-strategic-context-import','scripts/verify-strategic-context-import-scenarios','scripts/lib/context-contract.mjs','docs/process/strategic-handoff-package.md','docs/process/schemas/strategic-design-handoff.schema.json',...readdirSync(path.join(root,'scripts/lib')).filter(x=>x.startsWith('strategic-handoff-')||x==='strategic-handoff.mjs').map(x=>`scripts/lib/${x}`),...readdirSync(path.join(root,'docs/process/schemas')).filter(x=>x.startsWith('strategic-handoff-')).map(x=>`docs/process/schemas/${x}`),...readdirSync(path.join(root,'scripts/fixtures/strategic-handoff')).map(x=>`scripts/fixtures/strategic-handoff/${x}`)];
+let differences=[];
+function sync(source,dest){const bytes=readFileSync(source);if(!existsSync(dest)||!bytes.equals(readFileSync(dest))){differences.push(path.relative(root,dest));if(!check){mkdirSync(path.dirname(dest),{recursive:true});writeFileSync(dest,bytes);}}if(!check&&path.basename(path.dirname(dest))==='scripts'&&!path.extname(dest))chmodSync(dest,0o755);}
+for(const kind of ['domain-strategy','stage-decision-package'])sync(path.join(root,`.agents/skills/yss-stage-decision/references/${kind}.schema.json`),path.join(root,`docs/process/schemas/strategic-handoff-${kind}.schema.json`));
+for(const target of targets){
+ if(!existsSync(path.join(root,target,'.git')))continue;
+ if(!check){const state=inspectWorkingTreeScope(root,{project_root:target,repository_scope:'git-submodule',checkout_state:'attached-branch'});if(!state.writable)throw new Error(`${target}: ${state.violation}`);}
+ for(const ref of new Set(shared))sync(path.join(root,ref),path.join(root,target,ref));
+}
+if(check&&differences.length){process.stderr.write(`交接工具同步漂移: ${differences.join(', ')}\n`);process.exitCode=1;}else process.stdout.write(`战略交接共享工具 ${check?'同步检查通过':`同步 ${differences.length} 文件`}\n`);

package/template/scripts/verify-approval-record

@@ -3,10 +3,11 @@ import { parseArgs } from "node:util";
 import { validateApprovalRecordFile } from "./lib/approval-record.mjs";
 
 try {
-  const { positionals } = parseArgs({ allowPositionals: true, strict: true });
-  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-approval-record <approval-record.yaml>");
-  validateApprovalRecordFile(positionals[0]);
-  process.stdout.write("会签记录校验通过\n");
+  const { positionals, values } = parseArgs({ allowPositionals: true, strict: true, options: { "require-approved": { type: "boolean" }, history: { type: "boolean" } } });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-approval-record [--require-approved | --history] <approval-record.yaml>");
+  if (values.history && values["require-approved"]) throw new TypeError("--history 不能用于当前批准校验");
+  validateApprovalRecordFile(positionals[0], { requireApproved: !values.history });
+  process.stdout.write(!values.history ? "会签及当前用户决定校验通过\n" : "会签记录结构校验通过（不构成放行）\n");
 } catch (error) {
   process.stderr.write(`会签记录校验失败: ${error.message}\n`);
   process.exitCode = 1;

package/template/scripts/verify-business-language-scenarios

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { loadRegistry, renderLifecycleStructure, renderWorkUnits, semanticDigest, validateRegistry } from "./lib/lifecycle-registry.mjs";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const PUBLIC_FILES = [
+  "CONTEXT.md",
+  "docs/templates/spec-template.md",
+  "docs/design/templates/product-overview-design-template.md",
+  "docs/process/harness-executive-blueprint.md",
+  ".agents/skills/yss-stage-decision/SKILL.md",
+];
+const JARGON = ["DDD", "子域", "限界上下文", "Context Map", "统一语言", "不变量", "Strategic Design", "Tactical Design"];
+
+function read(relativePath) {
+  return readFileSync(path.join(ROOT, relativePath), "utf8");
+}
+
+for (const relativePath of PUBLIC_FILES) {
+  const source = read(relativePath);
+  for (const term of JARGON) {
+    assert.equal(source.includes(term), false, `${relativePath} 不应向业务角色展示术语: ${term}`);
+  }
+}
+
+const lifecycle = read(".agents/skills/yss-product-lifecycle/SKILL.md");
+for (const phrase of [
+  "机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发",
+  "业务方案总览",
+  "不成为新的事实源",
+]) assert.match(lifecycle, new RegExp(phrase));
+
+const registry = read("docs/process/lifecycle-registry.yaml");
+for (const stableId of ["work-unit.domain-strategy-design", "artifact.domain-strategy", "gate.domain-strategy-approved"]) {
+  assert.match(registry, new RegExp(`id: ${stableId.replaceAll(".", "\\.")}`));
+}
+for (const displayName of ["业务边界与协作梳理", "业务边界与规则设计", "业务边界与规则确认", "方案决策包"]) {
+  assert.match(registry, new RegExp(displayName));
+}
+
+const registryContract = loadRegistry();
+const withoutPublicPresentation = structuredClone(registryContract);
+for (const collection of ["stages", "gates", "artifacts", "work_units", "evidence"]) {
+  for (const record of withoutPublicPresentation[collection]) {
+    for (const key of Object.keys(record).filter((key) => key.startsWith("public_"))) delete record[key];
+  }
+}
+assert.equal(semanticDigest(registryContract), semanticDigest(withoutPublicPresentation), "public_* 展示字段不得改变稳定 ID 语义摘要");
+const rendered = `${renderLifecycleStructure(registryContract)}${renderWorkUnits(registryContract)}`;
+for (const displayName of ["业务边界与协作梳理", "业务边界与规则设计", "业务边界与规则确认", "方案决策包"]) {
+  assert.match(rendered, new RegExp(displayName));
+}
+const invalidPresentation = structuredClone(registryContract);
+invalidPresentation.artifacts[0].public_name = "";
+assert.throws(() => validateRegistry(invalidPresentation, { baseline: null }), /public_name 必须是非空字符串/);
+
+process.stdout.write("本体业务角色通俗语言场景验证通过\n");

package/template/scripts/verify-context-contract

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { parseContextContract, resolveContextTermRefs } from "./lib/context-contract.mjs";
+
+try {
+  const { values } = parseArgs({ options: { root: { type: "string", default: process.cwd() }, "allowed-context": { type: "string", multiple: true }, "term-ref": { type: "string", multiple: true }, json: { type: "boolean", default: false } }, strict: true });
+  const contract = parseContextContract({ root: values.root, allowedContextIds: values["allowed-context"] });
+  const resolved = resolveContextTermRefs(contract, values["term-ref"] || []);
+  const contextSnapshot = { context_ref: contract.context_ref, context_schema_version: contract.context_schema_version, document_digest: contract.document_digest, referenced_terms_digest: resolved.referenced_terms_digest, term_refs: resolved.terms.map((term) => term.term_ref) };
+  const result = { result: "completed", ...contextSnapshot, context_snapshot: contextSnapshot, process_term_count: contract.process_terms, business_term_count: contract.business_terms.length };
+  process.stdout.write(`${JSON.stringify(result, null, values.json ? 2 : 0)}\n`);
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ result: "blocked", reason_code: error.code || "context-contract-invalid", errors: error.problems || [error.message] }, null, 2)}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-context-contract-scenarios

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const validator = path.join(ROOT, "scripts/verify-context-contract");
+
+function contextSource(rows = [], scopeHeader = "适用业务责任区") {
+  return `---
+context_schema_version: 1
+---
+# 领域上下文
+
+本文档只记录稳定业务语言。
+
+## 流程术语
+
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| Spec | 产品研发规格。 | — |  |
+
+## 业务术语
+
+| 术语 | 含义 | 英文标识 | ${scopeHeader} | 避免 / 备注 |
+|---|---|---|---|---|
+${rows.join("\n")}
+`;
+}
+
+function run(root, ...args) {
+  return spawnSync(process.execPath, [validator, "--root", root, ...args], {
+    cwd: ROOT,
+    encoding: "utf8",
+  });
+}
+
+function expectBlocked(result, pattern, label) {
+  assert.notEqual(result.status, 0, `${label} 应被阻断`);
+  assert.match(`${result.stdout}\n${result.stderr}`, pattern, label);
+}
+
+const sandbox = mkdtempSync(path.join(tmpdir(), "yss-context-contract-"));
+try {
+  const valid = path.join(sandbox, "valid");
+  mkdirSync(valid);
+  writeFileSync(path.join(valid, "CONTEXT.md"), contextSource([
+    "| 供应商 | 提供商品或服务的业务主体。 | Supplier | Global | 避免：`厂商` |",
+    "| 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | ComplianceReview | 避免：`审批结果` |",
+  ]));
+  const validResult = run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json");
+  assert.equal(validResult.status, 0, validResult.stderr);
+  const validOutput = JSON.parse(validResult.stdout);
+  assert.equal(validOutput.result, "completed");
+  assert.match(validOutput.document_digest, /^sha256:[0-9a-f]{64}$/);
+  assert.match(validOutput.referenced_terms_digest, /^sha256:[0-9a-f]{64}$/);
+
+  const legacyHeader = path.join(sandbox, "legacy-header");
+  mkdirSync(legacyHeader);
+  writeFileSync(path.join(legacyHeader, "CONTEXT.md"), contextSource([
+    "| 供应商 | 提供商品或服务的业务主体。 | Supplier | Global |  |",
+  ], "适用限界上下文"));
+  assert.equal(run(legacyHeader, "--term-ref", "Global/Supplier").status, 0, "旧表头应继续兼容读取");
+
+  const lowercase = path.join(sandbox, "lowercase");
+  mkdirSync(lowercase);
+  writeFileSync(path.join(lowercase, "context.md"), contextSource());
+  expectBlocked(run(lowercase), /根目录.*CONTEXT\.md|大小写/, "小写文件名");
+
+  const nested = path.join(sandbox, "nested");
+  mkdirSync(path.join(nested, "contexts/Foo"), { recursive: true });
+  writeFileSync(path.join(nested, "CONTEXT.md"), contextSource());
+  writeFileSync(path.join(nested, "contexts/Foo/CONTEXT.md"), contextSource());
+  expectBlocked(run(nested), /嵌套.*CONTEXT\.md|只允许项目根目录/, "嵌套 CONTEXT.md");
+
+  const mapped = path.join(sandbox, "mapped");
+  mkdirSync(mapped);
+  writeFileSync(path.join(mapped, "CONTEXT.md"), contextSource());
+  writeFileSync(path.join(mapped, "CONTEXT-MAP.md"), "# Context Map\n");
+  expectBlocked(run(mapped), /CONTEXT-MAP\.md.*禁止/, "CONTEXT-MAP.md");
+
+  const duplicate = path.join(sandbox, "duplicate");
+  mkdirSync(duplicate);
+  writeFileSync(path.join(duplicate, "CONTEXT.md"), contextSource([
+    "| 准入决定 | 第一种定义。 | AdmissionDecision | ComplianceReview |  |",
+    "| 准入结论 | 第二种定义。 | AdmissionDecision | ComplianceReview |  |",
+  ]));
+  expectBlocked(run(duplicate, "--allowed-context", "ComplianceReview"), /术语身份重复/, "重复术语身份");
+
+  const unknownContext = path.join(sandbox, "unknown-context");
+  mkdirSync(unknownContext);
+  writeFileSync(path.join(unknownContext, "CONTEXT.md"), contextSource([
+    "| 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | UnknownContext |  |",
+  ]));
+  expectBlocked(run(unknownContext, "--allowed-context", "ComplianceReview"), /未在业务边界与规则设计中登记/, "未知作用域");
+
+  expectBlocked(run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "CONTEXT.md#Supplier"), /术语引用格式非法/, "Markdown 伪锚点");
+  expectBlocked(run(valid, "--allowed-context", "ComplianceReview", "--term-ref", "ComplianceReview/Missing"), /无法解析/, "缺失术语引用");
+
+  process.stdout.write("CONTEXT Contract 场景验证通过\n");
+} finally {
+  rmSync(sandbox, { recursive: true, force: true });
+}

package/template/scripts/verify-context-reconciliation

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { resolveContextTermRefs, verifyContextSnapshot } from "./lib/context-contract.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaPath = path.join(repoRoot, "docs/process/schemas/context-reconciliation.schema.json");
+const pythonValidator = String.raw`
+import json, sys
+from jsonschema import Draft202012Validator
+schema = json.load(open(sys.argv[1], encoding="utf-8"))
+value = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(value), key=lambda error: list(error.absolute_path))
+for error in errors:
+    where = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    print(f"{where}: {error.message}", file=sys.stderr)
+sys.exit(1 if errors else 0)
+`;
+
+function parseFile(file) {
+  const document = parseDocument(readFileSync(file, "utf8"), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+try {
+  const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+  if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-context-reconciliation [--root <repo>] <record.yaml|json>");
+  const root = path.resolve(values.root);
+  const file = path.resolve(positionals[0]);
+  const value = parseFile(file);
+  const schemaResult = spawnSync("python3", ["-c", pythonValidator, schemaPath], { encoding: "utf8", input: JSON.stringify(value) });
+  if (schemaResult.status !== 0) throw new TypeError(`${schemaResult.stdout}${schemaResult.stderr}`.trim());
+  const manifest = parseFile(path.join(root, "yss-project.yaml"));
+  if (value.repository_mode !== manifest.repository_mode) throw new TypeError("repository_mode 必须与根目录 yss-project.yaml 一致");
+  const contract = verifyContextSnapshot(value.context_snapshot, { root });
+  const changedRefs = [...value.changes.added, ...value.changes.updated, ...value.changes.deprecated];
+  resolveContextTermRefs(contract, changedRefs);
+  if (new Set(changedRefs).size !== changedRefs.length) throw new TypeError("changes 中的术语引用不得跨分类重复");
+  if (value.repository_mode === "project-instance" && value.status !== "reconciled") throw new TypeError("project-instance 工作单元只有 status=reconciled 才允许批准或进入下一步");
+  if (value.status === "reconciled" && value.unresolved_terms.length) throw new TypeError("reconciled 不得包含 unresolved_terms");
+  if (value.status === "blocked" && value.unresolved_terms.length === 0) throw new TypeError("blocked 必须说明 unresolved_terms");
+  if (value.status === "not-applicable" && (value.repository_mode !== "template-source" || !value.reason)) throw new TypeError("not-applicable 只适用于 template-source 且必须说明 reason");
+  for (const ref of value.evidence_refs) {
+    if (/^https?:\/\//.test(ref)) continue;
+    const resolved = path.resolve(root, ref);
+    if (!resolved.startsWith(`${root}${path.sep}`) && resolved !== root) throw new TypeError(`evidence_ref 越出仓库: ${ref}`);
+    if (!existsSync(resolved)) throw new TypeError(`evidence_ref 不可读: ${ref}`);
+  }
+  process.stdout.write("Context reconciliation 验证通过\n");
+} catch (error) {
+  process.stderr.write(`Context reconciliation 验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-context-reconciliation-scenarios

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const root = mkdtempSync(path.join(tmpdir(), "yss-context-reconciliation-"));
+mkdirSync(path.join(root, "docs", "evidence"), { recursive: true });
+writeFileSync(path.join(root, "yss-project.yaml"), "schema_version: 1\nrepository_mode: project-instance\n");
+writeFileSync(path.join(root, "CONTEXT.md"), `---
+context_schema_version: 1
+---
+
+# CONTEXT
+
+## 流程术语
+
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| 阶段 | 生命周期阶段 | — | |
+
+## 业务术语
+
+| 术语 | 含义 | 英文标识 | 适用限界上下文 | 避免 / 备注 |
+|---|---|---|---|---|
+| 供应商 | 提供产品或服务的主体 | Supplier | Global | |
+| 准入结论 | 合规审查的准入结果 | AdmissionDecision | ComplianceReview | |
+`);
+
+function run(command, args) {
+  return spawnSync(command, args, { cwd: repoRoot, encoding: "utf8" });
+}
+
+const snapshotResult = run("scripts/verify-context-contract", ["--root", root, "--allowed-context", "ComplianceReview", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json"]);
+if (snapshotResult.status !== 0) throw new Error(snapshotResult.stderr || snapshotResult.stdout);
+const snapshot = JSON.parse(snapshotResult.stdout).context_snapshot;
+
+function record(overrides = {}) {
+  return {
+    schema_version: 1,
+    repository_mode: "project-instance",
+    stage: "stage.discovery",
+    work_unit: "work-unit.domain-strategy-design",
+    status: "reconciled",
+    context_snapshot: snapshot,
+    changes: { added: ["Global/Supplier", "ComplianceReview/AdmissionDecision"], updated: [], deprecated: [] },
+    unresolved_terms: [],
+    evidence_refs: ["CONTEXT.md"],
+    ...overrides,
+  };
+}
+
+function verify(name, value, expectedStatus) {
+  const file = path.join(root, "docs", "evidence", `${name}.json`);
+  writeFileSync(file, JSON.stringify(value, null, 2));
+  const result = run("scripts/verify-context-reconciliation", ["--root", root, file]);
+  if (result.status !== expectedStatus) throw new Error(`${name}: expected ${expectedStatus}, got ${result.status}\n${result.stdout}${result.stderr}`);
+}
+
+verify("valid", record(), 0);
+verify("stale", record({ context_snapshot: { ...snapshot, document_digest: "sha256:stale" } }), 1);
+verify("blocked", record({ status: "blocked", unresolved_terms: [{ term: "准入状态", reason: "英文标识未确认", owner: "product-owner", next_action: "确认命名" }] }), 1);
+verify("missing-term", record({ changes: { added: ["ComplianceReview/Unknown"], updated: [], deprecated: [] } }), 1);
+verify("not-applicable-project", record({ status: "not-applicable", reason: "无术语变化" }), 1);
+writeFileSync(path.join(root, "yss-project.yaml"), "schema_version: 1\nrepository_mode: template-source\n");
+verify("template-source", record({ repository_mode: "template-source", status: "not-applicable", reason: "模板源仅校验 CONTEXT.md 结构", changes: { added: [], updated: [], deprecated: [] } }), 0);
+
+process.stdout.write("Context reconciliation scenarios passed\n");

package/template/scripts/verify-digital-human-roles-scenarios

@@ -39,7 +39,7 @@ function mustFail(doc, pattern, label) {
 validateDefaultDigitalHumanRoles();
 
 const tester = loadDigitalHumanRoles().roles.find((role) => role.id === "role.test-engineer");
-for (const skill of ["code-review", "alibaba-java-code-style", "yss-ui", "yss-page-module-development", "yss-domain", "yss-application", "yss-web-controller", "yss-dto", "mapstruct", "lombok"]) {
+for (const skill of ["code-review", "alibaba-java-code-style", "yss-ui", "yss-ui-business-page-generation", "yss-domain", "yss-application", "yss-web-controller", "yss-dto", "mapstruct", "lombok"]) {
   if (!tester.core_skills.includes(skill)) throw new TypeError(`role.test-engineer 缺少只读专项检查 skill: ${skill}`);
 }
 if (tester.forbidden_skills.includes("yss-ui") || tester.forbidden_skills.includes("alibaba-java-code-style")) {