create-yss-spec 3.5.3 → 3.5.5

package/template/scripts/lib/asset-transactions.mjs

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { safeFile } from './governance-io.mjs';
+import { parseAsset, readAsset, serializeAsset, byteDigest, semanticDigest, validateAssetStructure, TOOL_ROOT } from './structured-assets.mjs';
+
+const TX = '.yss/asset-transactions';
+const ensure = (ok, message) => { if (!ok) throw new Error(message); };
+const exists = file => fs.existsSync(file);
+const descriptor = file => exists(file) ? { digest: byteDigest(fs.readFileSync(file)), mode: fs.statSync(file).mode & 0o777 } : null;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Adapter for an existing validated writer which also owns Markdown/tracker updates. */
+export function runAssetTransaction(root, changes, action) {
+  root=fs.realpathSync(root);assertAssetTransactionIdle(root);
+  const directory=safeFile(root,TX);fs.mkdirSync(directory,{recursive:true});
+  const lock=safeFile(root,`${TX}/lock`),fd=fs.openSync(lock,'wx');fs.writeFileSync(fd,String(process.pid));fs.fsyncSync(fd);
+  const plan_id=byteDigest(serializeAsset({changes,nonce:randomUUID()})).slice(7),journal_ref=`${TX}/${plan_id}.json`,active=safeFile(root,`${TX}/active.json`);
+  const tx={schema_version:1,root,plan_id,status:'applying',changes,backups:{}};
+  try {
+    ensure(!exists(safeFile(root, `${TX}/recovery.lock`)), 'ASSET_RECOVERY_LOCKED');
+    for(const change of changes){ensure(same(descriptor(safeFile(root,change.ref)),change.before),`ASSET_INPUT_DRIFT: ${change.ref}`);tx.backups[change.ref]=change.before?fs.readFileSync(safeFile(root,change.ref)).toString('base64'):null;}
+    atomic(safeFile(root,journal_ref),serializeAsset(tx));atomic(active,serializeAsset({journal_ref}));
+    const result=action();
+    for(const change of changes)ensure(descriptor(safeFile(root,change.ref))?.digest===change.after_digest,`ASSET_POSTWRITE_DRIFT: ${change.ref}`);
+    tx.status='applied';atomic(safeFile(root,journal_ref),serializeAsset(tx));fs.unlinkSync(active);return result;
+  } catch(error) {
+    if(exists(active)){const recovered=recoverAssetWrite(root,{lockHeld:true});throw new Error(`${error.message}; ${recovered.status}`);}
+    throw error;
+  } finally {fs.closeSync(fd);if(exists(lock))fs.unlinkSync(lock);}
+}
+
+export function assertAssetTransactionIdle(root) {
+  ensure(!exists(safeFile(root, `${TX}/active.json`)), 'ASSET_TRANSACTION_PENDING: recover the unfinished transaction before lifecycle transition');
+}
+
+export function assertCurrentAssetReference(root, ref) {
+  const directory = safeFile(root, TX);
+  if (!exists(directory)) return;
+  for (const name of fs.readdirSync(directory)) {
+    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+    const receipt = parseAsset(fs.readFileSync(path.join(directory, name)), name);
+    if (receipt.status === 'applied' && receipt.migration?.source_to_target?.[ref]) throw new Error(`ASSET_HISTORICAL_ONLY: ${ref}; current=${receipt.migration.source_to_target[ref]}`);
+  }
+}
+
+// The observed closure includes governance, tools and project evidence, but not external checkouts/caches.
+export function observeAssetInputs(root) {
+  const rows = {};
+  function walk(ref) {
+    const file = safeFile(root, ref);
+    if (!exists(file)) return;
+    const st = fs.lstatSync(file);
+    ensure(!st.isSymbolicLink(), `ASSET_SYMLINK: ${ref}`);
+    if (st.isDirectory()) for (const name of fs.readdirSync(file).sort()) {
+      if (['node_modules', '.git', '.codegraph', '__pycache__'].includes(name)) continue;
+      walk(`${ref}/${name}`);
+    }
+    else if (st.isFile()) rows[ref] = descriptor(file);
+  }
+  for (const ref of ['yss-project.yaml', 'CONTEXT.md', 'DESIGN.md', 'AGENTS.md', 'skills-lock.json', '.template-spec', '.agents', 'scripts', 'docs']) walk(ref);
+  return rows;
+}
+
+export function validateAssetSemantics(root, ref, kind) {
+  const file = safeFile(root, ref), { value } = readAsset(file, kind, { schemaRoot: root });
+  let tool, args;
+  if (kind === 'domain-strategy' || kind === 'stage-decision-package') {
+    tool = `.agents/skills/yss-stage-decision/scripts/validate-${kind}.mjs`;
+    args = [file, '--root', root];
+  } else {
+    tool = { checkpoint: 'scripts/verify-lifecycle-checkpoint', 'task-package': 'scripts/verify-digital-human-task-package', 'approval-record': 'scripts/verify-approval-record' }[kind];
+    args = kind === 'approval-record' ? [value.decision === 'approved' || value.kind === 'review-bundle' ? '--require-approved' : '--history', file] : [file];
+  }
+  ensure(exists(safeFile(root, tool)), `ASSET_CONSUMER_MISSING: ${tool}`);
+  const result = spawnSync(process.execPath, [path.join(root, tool), ...args], { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 8 * 1024 * 1024 });
+  ensure(!result.error && result.status === 0, `ASSET_SEMANTIC: ${ref}: ${result.error?.message || result.stderr || result.stdout}`);
+  return { ref, kind, command: [tool, ...args.map(x => x.replaceAll(root, '.'))], exit_code: result.status, output: result.stdout.trim() };
+}
+
+function approvalBindings(root, changes) {
+  for (const change of changes) {
+    const value = parseAsset(change.after, change.ref);
+    // Writers never turn a bare status into an approval. Bound, independently issued evidence is mandatory.
+    const records = change.kind === 'approval-record' ? value.kind === 'review-bundle' ? value.reviews : [value] : [];
+    for (const row of records) if (row.decision === 'approved') {
+      ensure(row.subject_ref && row.subject_digest && row.drafter_principal_ref && row.drafter_principal_ref !== row.principal_ref, 'ASSET_APPROVAL_REBIND_REQUIRED: subject and independent reviewer required');
+      ensure(byteDigest(fs.readFileSync(safeFile(root, row.subject_ref))).replace('sha256:', '') === row.subject_digest.replace('sha256:', ''), 'ASSET_APPROVAL_STALE');
+    }
+    if (['domain-strategy', 'stage-decision-package'].includes(change.kind) && value.status === 'approved') {
+      const approval = parseAsset(fs.readFileSync(safeFile(root, value.approval.approval_ref)), value.approval.approval_ref);
+      const check = change.kind === 'domain-strategy' ? 'check.domain-strategy-approved' : 'check.stage-decision-package-approved';
+      const row = approval.kind === 'review-bundle' ? approval.reviews.find(x => x.gate_id === check) : approval;
+      ensure(row?.subject_ref === change.ref && row.subject_digest?.replace('sha256:', '') === byteDigest(change.after).replace('sha256:', ''), `ASSET_APPROVAL_REBIND_REQUIRED: ${change.ref}`);
+    }
+  }
+}
+
+function overlayVerification(root, observed, changes, { verify = validateAssetSemantics } = {}) {
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'yss-asset-check-'));
+  try {
+    for (const ref of Object.keys(observed)) {
+      const target = safeFile(staging, ref); fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(safeFile(root, ref), target); fs.chmodSync(target, observed[ref].mode);
+    }
+    for (const change of changes) {
+      const target = safeFile(staging, change.ref); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, change.after);
+    }
+    approvalBindings(staging, changes);
+    return changes.map(change => verify(staging, change.ref, change.kind));
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+export function planAssetWrite(root, specs, { schemaRoot = TOOL_ROOT, verify, migration } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  ensure(Array.isArray(specs) && specs.length, 'ASSET_EMPTY_PLAN');
+  const observed = observeAssetInputs(root), seen = new Set();
+  const changes = specs.map(({ ref, kind, value }) => {
+    ensure(!seen.has(ref), `ASSET_DUPLICATE_TARGET: ${ref}`); seen.add(ref);
+    ensure(ref.endsWith('.json') && /^(docs\/|\.yss\/)/.test(ref) && !ref.startsWith(`${TX}/`), 'ASSET_WRITE_SCOPE: project JSON assets only');
+    const file = safeFile(root, ref), before = descriptor(file);
+    const legacy = ref.replace(/\.json$/, '.yaml');
+    if (!before && exists(safeFile(root, legacy))) ensure(migration?.source_to_target?.[legacy] === ref, 'ASSET_AMBIGUOUS_AUTHORITY: use plan-migrate');
+    if (kind === 'approval-record' && before) throw new Error('ASSET_IMMUTABLE_APPROVAL: issue a new record');
+    validateAssetStructure(value, kind, { schemaRoot });
+    const after = serializeAsset(value); parseAsset(after, ref);
+    return { ref, kind, before, after, after_digest: byteDigest(after), semantic_digest: semanticDigest(value) };
+  }).filter(change => change.before?.digest !== change.after_digest);
+  for (const change of changes) if (!Object.hasOwn(observed, change.ref)) observed[change.ref] = change.before;
+  const verification = changes.length ? overlayVerification(root, Object.fromEntries(Object.entries(observed).filter(([,v]) => v)), changes, { verify }) : [];
+  const payload = { schema_version: 1, kind: 'asset-write-plan', root, observed, changes, verification, ...(migration ? {migration} : {}), execution_authorization: 'not-granted' };
+  return { ...payload, plan_id: byteDigest(serializeAsset(payload)).slice(7) };
+}
+
+function atomic(file, bytes, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temp, 'wx', mode);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  try { ensure(fs.readFileSync(temp).equals(Buffer.from(bytes)), 'ASSET_TEMP_READBACK'); fs.renameSync(temp, file); const dir = fs.openSync(path.dirname(file), 'r'); try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); } }
+  finally { if (exists(temp)) fs.unlinkSync(temp); }
+}
+
+export function applyAssetWrite(root, plan, { verify, afterWrite } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  const { plan_id, ...payload } = plan;
+  ensure(plan.root === root && plan.kind === 'asset-write-plan' && plan_id === byteDigest(serializeAsset(payload)).slice(7), 'ASSET_PLAN_INVALID');
+  const directory = safeFile(root, TX); fs.mkdirSync(directory, { recursive: true });
+  const lock = safeFile(root, `${TX}/lock`), fd = fs.openSync(lock, 'wx');
+  fs.writeFileSync(fd, String(process.pid));fs.fsyncSync(fd);
+  const active = safeFile(root, `${TX}/active.json`);
+  let transaction;
+  try {
+    ensure(!exists(safeFile(root, `${TX}/recovery.lock`)), 'ASSET_RECOVERY_LOCKED');
+    const current = observeAssetInputs(root);
+    for (const [ref, before] of Object.entries(plan.observed)) ensure(same(descriptor(safeFile(root, ref)), before), `ASSET_INPUT_DRIFT: ${ref}`);
+    ensure(Object.keys(current).every(ref => Object.hasOwn(plan.observed, ref)), 'ASSET_INPUT_DRIFT: new dependency files');
+    if (!plan.changes.length) return { status: 'unchanged', plan_id, changed_refs: [], execution_authorization: 'not-granted' };
+    // Recompute, including schemas and semantics. A plan's recorded successful exit is never trusted.
+    if(plan.migration) for(const [ref,digest] of Object.entries(plan.migration.sources)) ensure(byteDigest(fs.readFileSync(safeFile(root,ref)))===digest,`ASSET_MIGRATION_DRIFT: ${ref}`);
+    const fresh = planAssetWrite(root, plan.changes.map(c => ({ ref: c.ref, kind: c.kind, value: parseAsset(c.after, c.ref) })), { schemaRoot: root, verify, migration:plan.migration });
+    ensure(same(fresh.changes, plan.changes), 'ASSET_PLAN_CHANGED');
+    const journalRef = `${TX}/${plan_id}.json`, journalFile = safeFile(root, journalRef);
+    ensure(!exists(journalFile), 'ASSET_ALREADY_APPLIED: inspect the existing receipt');
+    transaction = { schema_version: 1, plan_id, root, status: 'applying', ...(plan.migration?{migration:plan.migration}:{}), changes: plan.changes, backups: Object.fromEntries(plan.changes.map(c => [c.ref, c.before ? fs.readFileSync(safeFile(root, c.ref)).toString('base64') : null])) };
+    atomic(journalFile, serializeAsset(transaction)); atomic(active, serializeAsset({ journal_ref: journalRef }));
+    for (const change of plan.changes) {
+      ensure(same(descriptor(safeFile(root, change.ref)), change.before), `ASSET_INPUT_DRIFT: ${change.ref}`);
+      atomic(safeFile(root, change.ref), change.after, change.before?.mode ?? 0o644);
+      readAsset(safeFile(root, change.ref), change.kind, { schemaRoot: root });
+      afterWrite?.(change);
+    }
+    for (const [ref, before] of Object.entries(plan.observed)) {
+      const change = plan.changes.find(c => c.ref === ref);
+      ensure(descriptor(safeFile(root, ref))?.digest === (change?.after_digest ?? before?.digest), `ASSET_POSTWRITE_DRIFT: ${ref}`);
+    }
+    ensure(Object.keys(observeAssetInputs(root)).every(ref => Object.hasOwn(plan.observed, ref)), 'ASSET_POSTWRITE_DRIFT: new dependency files');
+    transaction.status = 'applied'; atomic(journalFile, serializeAsset(transaction)); fs.unlinkSync(active);
+    return { status: 'applied', plan_id, changed_refs: plan.changes.map(c => c.ref), receipt_ref: journalRef, execution_authorization: 'not-granted' };
+  } catch (error) {
+    if (transaction && exists(active)) {
+      const result = recoverAssetWrite(root, { lockHeld: true });
+      throw new Error(`${error.message}; ${result.status}: ${result.conflicts.join(',')}`);
+    }
+    throw error;
+  } finally { fs.closeSync(fd); if (exists(lock)) fs.unlinkSync(lock); }
+}
+
+export function recoverAssetWrite(root, { lockHeld = false, recoveryHeld = false } = {}) {
+  root = fs.realpathSync(root);
+  const lock = safeFile(root, `${TX}/lock`);
+  if (!lockHeld && !recoveryHeld) {
+    const guard = safeFile(root, `${TX}/recovery.lock`);
+    fs.mkdirSync(path.dirname(guard), { recursive: true });
+    const fd = fs.openSync(guard, 'wx');
+    try {
+      fs.writeFileSync(fd, String(process.pid)); fs.fsyncSync(fd);
+      return recoverAssetWrite(root, { recoveryHeld: true });
+    } finally { fs.closeSync(fd); fs.unlinkSync(guard); }
+  }
+  if (!lockHeld && exists(lock)) {
+    const pid=Number(fs.readFileSync(lock,'utf8'));ensure(Number.isInteger(pid)&&pid>0,'ASSET_LOCK_INVALID');
+    let live=true;try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')live=false;else throw error;}
+    ensure(!live,'ASSET_LOCKED: writer is still alive');fs.unlinkSync(lock);
+  }
+  if (!lockHeld) {
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    const fd = fs.openSync(lock, 'wx');
+    try {
+      fs.writeFileSync(fd, String(process.pid)); fs.fsyncSync(fd);
+      return recoverAssetWrite(root, { lockHeld: true });
+    } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+  }
+  const active = safeFile(root, `${TX}/active.json`);
+  if (!exists(active)) return { status: 'idle', conflicts: [] };
+  const marker = parseAsset(fs.readFileSync(active), active), journalFile = safeFile(root, marker.journal_ref);
+  ensure(marker.journal_ref.startsWith(`${TX}/`), 'ASSET_JOURNAL_PATH');
+  const tx = parseAsset(fs.readFileSync(journalFile), journalFile);
+  ensure(tx.root === root && ['applying', 'recovery-conflict','applied'].includes(tx.status), 'ASSET_JOURNAL_INVALID');
+  if(tx.status==='applied') {for(const c of tx.changes)ensure(descriptor(safeFile(root,c.ref))?.digest===c.after_digest,'ASSET_RECOVERY_CONFLICT');fs.unlinkSync(active);return{status:'applied',conflicts:[]};}
+  const conflicts = [];
+  for (const change of [...tx.changes].reverse()) {
+    ensure(byteDigest(change.after)===change.after_digest && (change.before===null?tx.backups[change.ref]===null:byteDigest(Buffer.from(tx.backups[change.ref],'base64'))===change.before.digest),'ASSET_JOURNAL_CORRUPT');
+    const file = safeFile(root, change.ref), actual = descriptor(file);
+    if (same(actual, change.before)) continue;
+    if (actual?.digest !== change.after_digest) { conflicts.push(change.ref); continue; }
+    if (tx.backups[change.ref] === null) fs.unlinkSync(file);
+    else atomic(file, Buffer.from(tx.backups[change.ref], 'base64'), change.before.mode);
+  }
+  tx.status = conflicts.length ? 'recovery-conflict' : 'rolled-back'; tx.conflicts = conflicts;
+  atomic(journalFile, serializeAsset(tx)); if (!conflicts.length) fs.unlinkSync(active);
+  return { status: tx.status, conflicts };
+}

package/template/scripts/lib/business-ticket-lifecycle.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import {businessAuthoringEnabled,businessPath,businessSetRef,checkBusinessTickets,assertBusinessDeferredApprovals} from './business-tickets.mjs';
+import {yamlValue} from './plan-spec-markdown.mjs';
+import {loadApprovalRecord,validateApprovalRecord} from './approval-record.mjs';
+
+// Reuse existing approval protocols; this function creates no approval boundary.
+export function assertBusinessApprovalBasis(root,state,{required=false}={}) {
+  if(!businessAuthoringEnabled(root))return;
+  if(state?.checkpoint_ref)state=yamlValue(fs.readFileSync(businessPath(root,state.checkpoint_ref),'utf8'));
+  if(!required)return;
+  const report=checkBusinessTickets({root,setRef:businessSetRef(state),mode:'formal'});
+  if(report.status!=='passed')throw Error(`BUSINESS_FORMALIZATION_BLOCKED: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+  const rolesDoc=yamlValue(fs.readFileSync(businessPath(root,'.template-spec/agents/digital-human-roles.yaml'),'utf8'));
+  const proofRefs=[];
+  for(const id of ['gate.spec-baseline-approved','gate.product-design-approved']) {
+    const gate=state.gates?.[id];
+    if(id==='gate.product-design-approved'&&gate?.status==='not-applicable'&&gate.reason?.trim()&&gate.evidence_refs?.length){for(const ref of gate.evidence_refs)fs.readFileSync(businessPath(root,ref));continue;}
+    if(gate?.status!=='approved'||!gate.approval_ref)throw Error(`BUSINESS_APPROVAL_REQUIRED: ${id}`);
+    const record=loadApprovalRecord(businessPath(root,gate.approval_ref),id);
+    if(record.gate_id!==id||record.subject_ref!==gate.subject_ref||!gate.approval_scope?.length||JSON.stringify([...gate.approval_scope].sort())!==JSON.stringify([...(record.approval_scope||[])].sort()))throw Error(`BUSINESS_APPROVAL_SCOPE_MISMATCH: ${id}`);
+    validateApprovalRecord(record,{root,rolesDoc,requireApproved:true});
+    if(id==='gate.spec-baseline-approved'&&record.subject_ref!==report.spec.ref) {
+      // Existing approvals may cover a review package instead of the Spec itself.
+      // Its signed bytes, rather than a mutable checkpoint label, bind the baseline.
+      let subject;
+      try {subject=yamlValue(fs.readFileSync(businessPath(root,record.subject_ref),'utf8'));}
+      catch {throw Error('BUSINESS_SPEC_APPROVAL_MISMATCH: 批准主体不是当前 Spec 或可核验审阅包');}
+      const bindings=[...(Array.isArray(subject?.basis)?subject.basis:[]),...(Array.isArray(subject?.assets)?subject.assets:[])];
+      if(!bindings.some(x=>(x.ref||x.persisted_ref)===report.spec.ref&&String(x.digest).replace(/^sha256:/,'')===report.spec.digest.slice(7)))throw Error('BUSINESS_SPEC_APPROVAL_MISMATCH');
+    }
+    proofRefs.push(gate.approval_ref,record.user_decision_ref,record.continuation_ref);
+  }
+  assertBusinessDeferredApprovals(report,proofRefs);
+}

package/template/scripts/lib/business-tickets.mjs

@@ -0,0 +1,273 @@
+import nativeFs from 'node:fs';
+import {readFileSync,existsSync,lstatSync} from './validation-phase.mjs';
+const fs={...nativeFs,readFileSync,existsSync,lstatSync};
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseContent, yamlValue, ids as sourceIds } from './plan-spec-markdown.mjs';
+import { fileURLToPath } from 'node:url';
+import { validateJsonSchemas } from './json-schema.mjs';
+import { sourceContextRef, withSourceContextSnapshot } from './strategic-handoff-io.mjs';
+
+export const BUSINESS_TICKET_PROTOCOL = 1;
+export const BUSINESS_TICKET_CAPABILITY = 'business-ticket-approval-v1';
+const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const nonempty = value => typeof value === 'string' && Boolean(value.trim());
+const list = value => Array.isArray(value) && value.every(nonempty);
+const fail = message => { throw new Error(message); };
+export function businessPath(root, ref) {
+  if (!nonempty(ref) || path.isAbsolute(ref) || ref.includes('\\') || ref.split('/').some(x => !x || x === '.' || x === '..')) fail(`BUSINESS_PATH_INVALID: ${ref}`);
+  ref = sourceContextRef(root, ref);
+  let file = fs.realpathSync(root);
+  for (const part of ref.split('/')) {
+    file = path.join(file, part);
+    try { if (fs.lstatSync(file).isSymbolicLink()) fail(`BUSINESS_SYMLINK_FORBIDDEN: ${ref}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return file;
+}
+export function ticketMetadata(text) {
+  const match = String(text).match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if(match)return yamlValue(match[1]);
+  try {const data=yamlValue(String(text));return data&&typeof data==='object'&&!Array.isArray(data)?data:{};}catch{return {};}
+}
+export function businessTicketVersion(root) {
+  const identity = businessPath(root, 'yss-project.yaml');
+  if (fs.existsSync(identity) && yamlValue(fs.readFileSync(identity,'utf8'))?.repository_mode === 'template-source') return null;
+  const ref = '.template-spec/agents/issue-tracker.md';
+  const file = businessPath(root, ref);
+  if (!fs.existsSync(file)) return null;
+  const value = ticketMetadata(fs.readFileSync(file, 'utf8'))?.tracker?.business_ticket_version;
+  if (value !== undefined && value !== 1) fail('BUSINESS_TICKET_VERSION_UNSUPPORTED');
+  return value ?? null;
+}
+export function businessAuthoringEnabled(root) {
+  if(businessTicketVersion(root)!==1)return false;
+  const profile=businessPath(root,'.template-spec/process/harness-profile.yaml');
+  const id=fs.existsSync(profile)?yamlValue(fs.readFileSync(profile,'utf8'))?.profile_id:null;
+  return !['harness.backend-delivery','harness.frontend-delivery'].includes(id);
+}
+export function assertImplementationTicket(text, ref = '') {
+  const kind = ticketMetadata(text)?.kind;
+  if (kind === 'stage-work-item' || /(^|\/)work-items\//.test(ref)) fail('stage-work-item 不能作为实现 Ticket');
+  if (['business-ticket', 'business-ticket-set'].includes(kind) || /(^|\/)business-tickets\//.test(ref)) fail('business-ticket-not-implementable: 业务 Ticket 不能作为实现 Slice');
+}
+
+/** Structural evidence only. Business semantics and approval remain with lifecycle reviewers. */
+export function checkBusinessTickets({root, setRef, mode = 'draft', reviewRef} = {}) {
+  // Imported v5 sources retain root-relative bindings inside the immutable payload.
+  const imported=typeof setRef==='string'&&setRef.match(/^(docs\/handoffs\/[^/]+\/v[1-9][0-9]*\/package\/payload\/files\/)(.+)$/);
+  if(imported) {
+    const prefix=imported[1], sourceRoot=businessPath(root,prefix.slice(0,-1));
+    const result=withSourceContextSnapshot(sourceRoot,()=>checkBusinessTickets({root:sourceRoot,setRef:imported[2],mode,reviewRef:reviewRef?.startsWith(prefix)?reviewRef.slice(prefix.length):reviewRef}));
+    const mapped=ref=>typeof ref==='string'?prefix+(ref==='CONTEXT.md'?'source-context.snapshot.md':ref):ref;
+    result.inputs=result.inputs.map(x=>({...x,ref:mapped(x.ref)}));
+    result.diagnostics=result.diagnostics.map(x=>({...x,source_ref:mapped(x.source_ref)}));
+    result.tickets=result.tickets.map(x=>({...x,ref:mapped(x.ref)}));
+    if(result.spec)result.spec={...result.spec,ref:mapped(result.spec.ref)};
+    if(result.semantic_review)result.semantic_review={...result.semantic_review,ref:mapped(result.semantic_review.ref)};
+    return result;
+  }
+  const report = {schema_version:1, read_only:true, execution_authorization:'not-evaluated', mode, status:'passed', diagnostics:[], inputs:[], tickets:[], uncovered:[], unassessed:['business-granularity','semantic-fidelity','approval-validity']};
+  const observed = new Map();
+  const schemaInputs = [];
+  const schemaPath = fileURLToPath(new URL('../../.template-spec/process/schemas/business-tickets-v1.schema.json',import.meta.url));
+  const issue = (code, message, ref = setRef, locator = null) => report.diagnostics.push({code,message,source_ref:ref,locator,recovery:'核对来源、补齐引用或重新审查当前业务 Ticket 集'});
+  const read = ref => {
+    const bytes = fs.readFileSync(businessPath(root,ref)), digest = hash(bytes);
+    if (observed.has(ref) && observed.get(ref) !== digest) fail(`INPUT_DRIFT: ${ref}`);
+    observed.set(ref,digest); return bytes.toString('utf8');
+  };
+  const binding = value => {
+    if (!value || !nonempty(value.ref) || !/^v[1-9][0-9]*$/.test(value.version ?? '') || !/^sha256:[a-f0-9]{64}$/.test(value.digest ?? '')) fail('BINDING_INVALID: 需要 ref/version/digest');
+    const text = read(value.ref);
+    if (observed.get(value.ref) !== value.digest) issue('SOURCE_STALE','来源原始字节已变化',value.ref);
+    return text;
+  };
+  try {
+    if (!['draft','formal'].includes(mode)) fail('MODE_INVALID');
+    const set = yamlValue(read(setRef));
+    schemaInputs.push({value:set,schemaPath,label:setRef});
+    if (set?.schema_version !== 1 || set.kind !== 'business-ticket-set' || !nonempty(set.id) || !/^v[1-9][0-9]*$/.test(set.version ?? '') || !['draft','ready-for-human'].includes(set.status)) fail('BUSINESS_SET_INVALID');
+    report.id=set.id; report.version=set.version; report.spec=set.spec; report.coverage_deferred=set.coverage_deferred ?? [];
+    const spec = parseContent(binding(set.spec),set.spec.ref);
+    if (!spec.supported) issue('SPEC_FORMAT_UNASSESSED','Spec 需显式采用 plan-spec-v1；旧格式不推断覆盖',set.spec.ref);
+    const entries = spec.entries.filter(x => ['FR','NFR','AC'].includes(x.kind));
+    const ids = new Set();
+    for (const entry of entries) {
+      if (ids.has(entry.id)) issue('DUPLICATE_ID',`Spec ID 重复: ${entry.id}`,set.spec.ref,entry.position.start.line);
+      ids.add(entry.id);
+    }
+    if (!entries.some(x => x.kind === 'FR') || !entries.some(x => x.kind === 'AC')) issue('SPEC_COVERAGE_UNASSESSED','缺少可机械读取的 FR/AC',set.spec.ref);
+    if (!Array.isArray(set.tickets) || !set.tickets.length) fail('BUSINESS_TICKETS_REQUIRED');
+    const tickets = new Map(), covered = new Set(), seenPaths = new Set();
+    for (const entry of set.tickets) {
+      const text = binding(entry), ticket = ticketMetadata(text);
+      schemaInputs.push({value:ticket,schemaPath,label:entry.ref});
+      if (tickets.has(entry.id) || seenPaths.has(entry.ref)) issue('DUPLICATE_ID',`Ticket ID 或路径重复: ${entry.id}`,entry.ref);
+      seenPaths.add(entry.ref);
+      if (ticket.schema_version !== 1 || ticket.kind !== 'business-ticket' || !/^BT-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ticket.id ?? '') || ticket.id !== entry.id || ticket.version !== entry.version) issue('BUSINESS_TICKET_INVALID','类型、稳定 ID 或版本不匹配',entry.ref);
+      if (!['draft','ready-for-human'].includes(ticket.status)) issue('BUSINESS_READINESS_FORBIDDEN','业务票不得声明实现就绪',entry.ref);
+      if (!entry.ref.startsWith(`${path.posix.dirname(setRef)}/business-tickets/`) || !entry.ref.endsWith('.md')) issue('BUSINESS_TICKET_LOCATION','业务票需独立放在 business-tickets/',entry.ref);
+      if (['ref','version','digest'].some(key=>ticket.spec?.[key]!==set.spec?.[key])) issue('SPEC_BINDING_MISMATCH','票据与集合的 Spec 依据不一致',entry.ref);
+      for (const field of ['requirement_refs','acceptance_refs','dependencies']) if (!list(ticket[field])) issue('REQUIRED_FIELD',`缺少 ${field}`,entry.ref);
+      if (!ticket.requirement_refs?.length || !ticket.acceptance_refs?.length) issue('COVERAGE_REQUIRED','需要需求与验收引用',entry.ref);
+      for (const [field, pattern] of [['requirement_refs',/^(FR|NFR)-/],['acceptance_refs',/^AC-/]]) {
+        for (const id of Array.isArray(ticket[field]) ? ticket[field] : []) {
+          if (!ids.has(id) || !pattern.test(id)) issue('DANGLING_REFERENCE',`无效引用 ${id}`,entry.ref);
+          else covered.add(id);
+        }
+      }
+      for(const ac of Array.isArray(ticket.acceptance_refs)?ticket.acceptance_refs:[]) {
+        const requirementIds=sourceIds(entries.find(x=>x.id===ac)?.fields?.['需求引用'],['FR','NFR']);
+        if(!requirementIds.length || requirementIds.some(id=>!ticket.requirement_refs?.includes(id)))issue('AC_REQUIREMENT_MISMATCH',`验收 ${ac} 与本票需求来源不一致`,entry.ref,ac);
+      }
+      for (const source of ticket.source_refs ?? []) {
+        const sourceText = binding(source);
+        if (source.locator) {
+          let found;
+          if (/\.(yaml|yml|json)$/.test(source.ref)) {
+            const ids=[];
+            const walk=value=>{if(Array.isArray(value))value.forEach(walk);else if(value&&typeof value==='object')for(const [key,item]of Object.entries(value)){if((key==='id'||key.endsWith('_id'))&&typeof item==='string')ids.push(item);else walk(item);}};
+            walk(yamlValue(sourceText));found=source.locator_kind!=='heading'&&ids.filter(x=>x===source.locator).length===1;
+          } else {const parsed=parseContent(sourceText,source.ref);found=(source.locator_kind==='heading'?parsed.headings:parsed.locators).filter(x=>x.value===source.locator).length===1;}
+          if(!found)issue('DANGLING_REFERENCE',`来源定位缺失或不唯一: ${source.locator}`,source.ref,source.locator);
+        }
+      }
+      for (const heading of ['业务结果','范围','非目标','验收','风险']) if (!new RegExp(`^## ${heading}\\s*$`,'m').test(text)) issue('REQUIRED_SECTION',`缺少 ${heading}`,entry.ref);
+      for (const question of ticket.open_questions ?? []) {
+        if (![question.id,question.question,question.owner,question.resolve_by].every(nonempty) || typeof question.blocking !== 'boolean') issue('QUESTION_INCOMPLETE','未决项需问题、责任人、时点及阻断判断',entry.ref);
+        if (mode === 'formal' && question.blocking) issue('OPEN_BLOCKER',question.question,entry.ref);
+      }
+      if (mode === 'formal' && ticket.status !== 'ready-for-human') issue('TICKET_DRAFT','正式化仍有草案票',entry.ref);
+      tickets.set(entry.id,ticket);
+      report.tickets.push({id:entry.id,ref:entry.ref,version:entry.version,source_digest:entry.digest,source_refs:ticket.source_refs,requirement_refs:ticket.requirement_refs,acceptance_refs:ticket.acceptance_refs,dependencies:ticket.dependencies});
+    }
+    const visiting = new Set(), visited = new Set();
+    const visit = id => {
+      if (visiting.has(id)) { issue('DEPENDENCY_CYCLE',`依赖环包含 ${id}`); return; }
+      if (visited.has(id)) return;
+      visiting.add(id);
+      for (const dep of tickets.get(id)?.dependencies ?? []) {
+        if (!tickets.has(dep)) issue('DANGLING_DEPENDENCY',`${id} 依赖未知票 ${dep}`);
+        else visit(dep);
+      }
+      visiting.delete(id); visited.add(id);
+    };
+    tickets.forEach((_,id)=>visit(id));
+    const deferred = new Set();
+    for (const item of set.coverage_deferred ?? []) {
+      if (!ids.has(item.id) || deferred.has(item.id) || covered.has(item.id)) issue('DEFERRED_COVERAGE_INVALID',`延期引用无效或重复: ${item.id}`);
+      if (!['reason','risk','owner','target_version','followup_ticket_ref','verification_plan'].every(k=>nonempty(item[k]))) issue('DEFERRED_INCOMPLETE',`延期缺少责任或处理计划: ${item.id}`);
+      if (mode === 'formal') {
+        if (!item.decision) issue('DEFERRED_DECISION_REQUIRED',`延期缺少既有决定绑定: ${item.id}`);
+        else binding(item.decision);
+      }
+      deferred.add(item.id);
+    }
+    report.uncovered = [...ids].filter(id=>!covered.has(id)&&!deferred.has(id));
+    for (const id of report.uncovered) issue('COVERAGE_MISSING',`未覆盖 ${id}`,set.spec.ref,id);
+    if (mode === 'formal') {
+      if (set.status !== 'ready-for-human') issue('SET_DRAFT','业务集合尚未正式化');
+      const review = yamlValue(read(reviewRef || set.review_ref));
+      schemaInputs.push({value:review,schemaPath,label:reviewRef || set.review_ref});
+      if (review.kind !== 'business-ticket-review' || review.schema_version !== 1 || review.result !== 'passed' || review.subject_ref !== setRef || review.subject_digest !== observed.get(setRef) || !nonempty(review.reviewer) || !nonempty(review.drafter) || review.reviewer === review.drafter || !Array.isArray(review.evidence) || !review.evidence.length) issue('REVIEW_REQUIRED','需要独立且绑定当前集合的专业审查');
+      for (const ref of review.evidence ?? []) binding(ref);
+      report.semantic_review={status:'recorded',ref:reviewRef||set.review_ref,result:review.result,subject_digest:review.subject_digest};
+      report.unassessed = ['approval-validity','semantic-review-truth'];
+    }
+  } catch (error) { issue(error.message.split(':')[0],error.message); }
+  try { validateJsonSchemas(schemaInputs).forEach((result,index)=>{if(!result.valid)issue('SCHEMA_INVALID',result.error,schemaInputs[index].label);}); }
+  catch(error) {issue('SCHEMA_UNAVAILABLE',error.message);}
+  for (const [ref,digest] of observed) {
+    try { if (hash(fs.readFileSync(businessPath(root,ref))) !== digest) issue('INPUT_DRIFT','读取期间来源变化',ref); }
+    catch { issue('INPUT_DRIFT','读取期间来源消失',ref); }
+  }
+  report.inputs = [...observed].map(([ref,digest])=>({ref,digest}));
+  report.status = report.diagnostics.length ? 'blocked' : 'passed';
+  return report;
+}
+
+export function businessSetRef(state) { return state?.artifacts?.['artifact.business-ticket-set']?.ref || state?.business_ticket_set_ref; }
+export function assertBusinessTicketTransition(root, current, next, state = {}) {
+  if (!businessAuthoringEnabled(root)) return;
+  if (state.checkpoint_ref) state=yamlValue(fs.readFileSync(businessPath(root,state.checkpoint_ref),'utf8'));
+  const spec = current === 'work-unit.spec-synthesis';
+  const design = ['work-unit.prototype-design','work-unit.prototype-design-v2'].includes(current);
+  const formal = current === 'work-unit.business-ticket-formalization';
+  if (!spec && !design && !formal) return;
+  if ((spec || design) && next === 'work-unit.technical-analysis') fail('BUSINESS_FORMALIZATION_REQUIRED');
+  const report = checkBusinessTickets({root,setRef:businessSetRef(state),mode:formal?'formal':'draft'});
+  if (report.status !== 'passed') fail(`business-ticket-blocked: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+}
+
+export function assertSliceBusinessSources({root,ticketText,setBinding,acceptance,specBinding}) {
+  const ticket = ticketMetadata(ticketText);
+  if (businessTicketVersion(root) !== 1 && !ticket.business_ticket_refs && !setBinding) return;
+  if(ticket.kind!=='vertical-slice-ticket')fail('IMPLEMENTATION_TICKET_KIND_REQUIRED');
+  if(ticket.business_ticket_set_ref && ticket.business_ticket_set_ref!==setBinding?.ref)fail('BUSINESS_SET_REFERENCE_MISMATCH');
+  if (!setBinding?.ref || !setBinding.digest) fail('BUSINESS_SET_BINDING_REQUIRED');
+  const bytes = fs.readFileSync(businessPath(root,setBinding.ref));
+  if (hash(bytes) !== setBinding.digest) fail('BUSINESS_SET_STALE');
+  const result = checkBusinessTickets({root,setRef:setBinding.ref,mode:'formal'});
+  if (result.status !== 'passed') fail(`BUSINESS_SOURCE_BLOCKED: ${result.diagnostics.map(x=>x.code).join(', ')}`);
+  if (!list(ticket.business_ticket_refs) || !ticket.business_ticket_refs.length || ticket.business_ticket_refs.some(id=>!result.tickets.some(t=>t.id===id))) fail('BUSINESS_TICKET_REFERENCE_REQUIRED');
+  const selected=result.tickets.filter(t=>ticket.business_ticket_refs.includes(t.id));
+  const allowed=new Set(selected.flatMap(t=>t.acceptance_refs));
+  if (!list(ticket.acceptance_refs) || !ticket.acceptance_refs.length || ticket.acceptance_refs.some(id=>!allowed.has(id))) fail('BUSINESS_ACCEPTANCE_REFERENCE_REQUIRED');
+  if(acceptance) {
+    if(!specBinding || ['ref','digest'].some(key=>result.spec[key]!==specBinding[key]))fail('BUSINESS_SPEC_BINDING_MISMATCH');
+    for(const item of Object.values(acceptance))if(item.source!=='spec'||!ticket.acceptance_refs.includes(item.locator))fail('BUSINESS_ACCEPTANCE_SOURCE_MISMATCH');
+    if(ticket.acceptance_refs.some(id=>!Object.values(acceptance).some(item=>item.locator===id)))fail('BUSINESS_ACCEPTANCE_UNCOVERED');
+  }
+}
+
+export function assertBusinessCheckpoint(root,state) {
+  if (!businessAuthoringEnabled(root)) return;
+  const stage=state.stage;
+  const pastSpec=['stage.product-design','stage.system-data-engineering','stage.ticket-formalization','stage.vertical-slice-implementation','stage.verification-release-retrospective'].includes(stage);
+  // Design uses ticket-formalization for business drafting, while the full
+  // lifecycle uses that stage for engineering Slices. Entering the business
+  // work unit must remain possible with drafts; its exit requires formal proof.
+  const finalized=['work-unit.technical-analysis','work-unit.strategic-design-handoff','work-unit.implementation-repository-preparation','work-unit.ticket-decomposition','work-unit.slice-implementation'].includes(state.next_work_unit) || ['stage.system-data-engineering','stage.vertical-slice-implementation','stage.verification-release-retrospective'].includes(stage) || (stage==='stage.ticket-formalization'&&state.next_work_unit!=='work-unit.business-ticket-formalization');
+  const artifact=state.artifacts?.['artifact.business-ticket-set'];
+  const completedSpec=['work-unit.prototype-design','work-unit.prototype-design-v2','work-unit.business-ticket-formalization'].includes(state.next_work_unit)||state.stage_trace?.completed_work_unit==='work-unit.spec-synthesis'||(stage==='stage.spec-architecture'&&['completed','paused-human-gate'].includes(state.status));
+  if(!pastSpec && !finalized && !artifact?.ref && !completedSpec)return;
+  const report=checkBusinessTickets({root,setRef:businessSetRef(state),mode:finalized?'formal':'draft'});
+  if(report.status!=='passed')fail(`BUSINESS_CHECKPOINT_BLOCKED: ${report.diagnostics.map(x=>x.code).join(', ')}`);
+  if(artifact?.digest && report.inputs.find(x=>x.ref===artifact.ref)?.digest!==artifact.digest)fail('BUSINESS_SYNC_STALE');
+  const sync=businessSyncDiagnostics(root,businessSetRef(state),report);if(sync.length)fail('BUSINESS_SYNC_STALE: '+sync.map(x=>x.ref).join(', '));
+}
+
+// Only inspect explicit synchronization declarations in the two feature views.
+export function businessSyncDiagnostics(root,setRef,report) {
+  if(!setRef)return [];
+  const digest=report.inputs?.find(x=>x.ref===setRef)?.digest,diagnostics=[];
+  for(const name of ['map.md','parent-ticket.md']) {
+    const ref=path.posix.join(path.posix.dirname(setRef),name),file=businessPath(root,ref);
+    if(!fs.existsSync(file))continue;
+    const m=ticketMetadata(fs.readFileSync(file,'utf8'));
+    if(m.business_ticket_set_ref && (m.business_ticket_set_ref!==setRef||m.business_ticket_set_digest!==digest))diagnostics.push({code:'BUSINESS_SYNC_STALE',ref});
+  }
+  return diagnostics;
+}
+
+export function assertBusinessDeferredApprovals(report,verifiedRefs) {
+  for(const item of report.coverage_deferred||[])if(!verifiedRefs.includes(item.decision?.ref))fail(`BUSINESS_DEFERRED_APPROVAL_UNBOUND: ${item.id}`);
+}
+
+export function summarizeBusinessImplementation({root,setRef,sliceRefs=[]}) {
+  const business=checkBusinessTickets({root,setRef,mode:'formal'});
+  const result={status:'not-recorded',execution_authorization:'not-evaluated',implementation_completion:'not-evaluated',tickets:[],diagnostics:[]};
+  if(business.status!=='passed'){result.status='blocked';result.diagnostics=business.diagnostics;return result;}
+  const mapped=new Map(business.tickets.map(t=>[t.id,new Map()]));
+  for(const ref of [...new Set(sliceRefs)])try {
+    const text=fs.readFileSync(businessPath(root,ref),'utf8');assertImplementationTicket(text,ref);const ticket=ticketMetadata(text);
+    if(ticket.kind!=='vertical-slice-ticket'||ticket.business_ticket_set_ref!==setRef||!list(ticket.business_ticket_refs)||!ticket.business_ticket_refs.length||!list(ticket.acceptance_refs)||!ticket.acceptance_refs.length)fail('SLICE_BUSINESS_BINDING_INVALID');
+    const allowed=new Set(business.tickets.filter(t=>ticket.business_ticket_refs.includes(t.id)).flatMap(t=>t.acceptance_refs));
+    if(ticket.business_ticket_refs.some(id=>!mapped.has(id))||ticket.acceptance_refs.some(id=>!allowed.has(id)))fail('SLICE_COVERAGE_INVALID');
+    for(const id of ticket.business_ticket_refs)for(const ac of ticket.acceptance_refs)if(business.tickets.find(t=>t.id===id).acceptance_refs.includes(ac)){const rows=mapped.get(id);rows.set(ac,[...(rows.get(ac)||[]),ref]);}
+  }catch(error){result.diagnostics.push({code:'SLICE_MAPPING_INVALID',source_ref:ref,message:error.message});}
+  result.tickets=business.tickets.map(t=>({id:t.id,acceptance_mappings:Object.fromEntries(mapped.get(t.id)),unmapped_acceptance:t.acceptance_refs.filter(ac=>!mapped.get(t.id).has(ac))}));
+  result.status=result.diagnostics.length?'blocked':!sliceRefs.length?'not-recorded':result.tickets.some(t=>t.unmapped_acceptance.length)?'partial':'covered';
+  return result;
+}

package/template/scripts/lib/checkpoint-boundary.mjs

@@ -0,0 +1,43 @@
+import { readDocument, fileBinding } from './governance-io.mjs';
+import { assertAssetTransactionIdle, assertCurrentAssetReference } from './asset-transactions.mjs';
+
+/** Validate existing lifecycle context evidence; never grants approval. */
+export function assertCheckpointBoundary(value, {root, history=false}={}) {
+  if(history) return {status:'historical-only',execution_authorization:'not-evaluated'};
+  assertAssetTransactionIdle(root);
+  if(value.stage_tracking?.checkpoint_ref)assertCurrentAssetReference(root,value.stage_tracking.checkpoint_ref);
+  const canonical='.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const contract=readDocument(root,fileBinding(root,canonical)?canonical:'.template-spec/process/checkpoint-boundary.yaml');
+  const registry=readDocument(root,'.template-spec/process/lifecycle-registry.yaml');
+  const stages=new Set(registry.stages.map(x=>x.id));
+  if(!stages.has(value.stage))throw new Error('checkpoint-boundary: 当前 stage 未登记');
+  if(value.next_work_unit!=null&&!registry.work_units.some(x=>x.id===value.next_work_unit))throw new Error('checkpoint-boundary: next_work_unit 未登记');
+  const required=(v,label)=>{if(typeof v!=='string'||!v.trim())throw new Error(`checkpoint-boundary: 缺少 ${label}`);};
+  const reference=(ref,label)=>{required(ref,label);if(!fileBinding(root,ref))throw new Error(`checkpoint-boundary: 证据不可读 ${label}: ${ref}`);};
+  const boundary=value.phase_boundary;
+  if(boundary!==undefined) {
+    if(!boundary||Array.isArray(boundary)||typeof boundary!=='object')throw new Error('checkpoint-boundary: phase_boundary 必须为对象');
+    for(const key of contract.phase_boundary.evidence.required)required(boundary[key],`phase_boundary.${key}`);
+    if(!contract.phase_boundary.choices.includes(boundary.decision))throw new Error('checkpoint-boundary: decision 非法');
+    for(const key of contract.phase_boundary.evidence.conditional[boundary.decision]||[]) {
+      required(boundary[key],`phase_boundary.${key}`);
+      if(key.endsWith('_ref'))reference(boundary[key],key);
+    }
+    if(boundary.decision==='compact'&&!stages.has(boundary.next_phase))throw new Error('checkpoint-boundary: next_phase 必须为当前阶段 ID');
+  }
+  const atBoundary=['paused-human-gate','completed'].includes(value.status)||['handoff','subagent','compact'].includes(boundary?.decision)||
+    (['orchestrate','resume'].includes(value.mode)&&(value.stage!=='stage.entry-triage'||Boolean(value.stage_trace?.completed_work_unit)));
+  if(atBoundary&&!boundary)throw new Error('checkpoint-boundary: 当前边界缺少 phase_boundary');
+  if(atBoundary&&!value.stage_trace)throw new Error('checkpoint-boundary: 当前边界缺少 stage_trace');
+  if(value.stage_trace!==undefined) {
+    const trace=value.stage_trace;
+    if(!trace||Array.isArray(trace)||typeof trace!=='object')throw new Error('checkpoint-boundary: stage_trace 必须为对象');
+    for(const key of contract.checkpoint_policy.required_stage_trace_fields) {
+      if(key==='stage'){if(!stages.has(trace.stage)||trace.stage!==value.stage)throw new Error('checkpoint-boundary: stage_trace.stage 不一致');}
+      else if(!Array.isArray(trace[key]))throw new Error(`checkpoint-boundary: stage_trace.${key} 必须为数组`);
+    }
+    if(trace.completed_work_unit!==undefined&&!registry.work_units.some(x=>x.id===trace.completed_work_unit))throw new Error('checkpoint-boundary: completed_work_unit 非法');
+    for(const key of ['upstream_refs','artifact_refs'])for(const ref of trace[key])reference(typeof ref==='string'?ref:ref?.ref,key);
+  }
+  return {status:'passed',execution_authorization:'not-evaluated'};
+}