create-yss-spec 3.5.6 → 3.5.8

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

@@ -1,205 +1,100 @@
-import { assertApprovalUserDecision } from './user-decision-reuse.mjs';
-import { parseAsset, validateAssetStructure } from './structured-assets.mjs';
-import { existsSync, readFileSync } from './validation-phase.mjs';
-import path from "node:path";
-import { parseDocument } from "../vendor/yaml.mjs";
-import {
-  BIOLOGICAL_ROLE_ID,
-  countersignRuleForGate,
-  loadDigitalHumanRoles,
-  collectCountersignGateIds
-} from "./digital-human-roles.mjs";
-import { assertGateChecks } from "./lifecycle-controls.mjs";
-import { ROOT, loadRegistry } from "./lifecycle-registry.mjs";
-import { assertUserDecisionRequirement, assertWorkUnitUserDecision, assertImplementationDecision, decisionIO, decisionDigest } from "./user-decision.mjs";
-
-const DECISIONS = new Set(["approved", "rejected", "vetoed"]);
-const ACTOR_KINDS = new Set(["digital-human", "biological-human", "orchestrator"]);
-
-function fail(message) {
-  throw new TypeError(message);
-}
-
-function requireString(value, field) {
-  if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`);
-}
-
-function yamlFromFile(filePath, label) {
-  let source;
-  try {
-    source = readFileSync(filePath, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
-    throw error;
+import {withValidationPhase, readFileSync} from './validation-phase.mjs';
+import {ROOT, loadRegistry} from './lifecycle-registry.mjs';
+import {loadDigitalHumanRoles, countersignRuleForGate} from './digital-human-roles.mjs';
+import {assertGateChecks} from './lifecycle-controls.mjs';
+import {assertUserDecisionRequirement, assertWorkUnitUserDecision, assertImplementationDecision} from './user-decision.mjs';
+import {validateAssetStructure} from './structured-assets.mjs';
+import {assertCurrentApproval, approvalExpectationFromState} from './approval-current.mjs';
+import {approvalExpectedFromTask} from './review-capabilities.mjs';
+import {approvalIO, readApprovalDocument, reviewBundleRows, loadApprovalRecord, selectApprovalRecord, readApprovalHistory, resolveApprovalRef, approvalError} from './approval-record-io.mjs';
+export {assertCurrentApproval, approvalExpectationFromState, approvalExpectationFromSubject} from './approval-current.mjs';
+export {loadApprovalRecord, selectApprovalRecord, readApprovalHistory, resolveApprovalRef} from './approval-record-io.mjs';
+
+function expectedFor(record, options) {
+  if (options.expected) return Array.isArray(options.expected) ? options.expected.find(row => row.boundary === record.gate_id) : options.expected;
+  if (options.checkpoint) {
+    const state = options.checkpoint.gates?.[record.gate_id] || options.checkpoint.checks?.[record.gate_id];
+    return approvalExpectationFromState(record.gate_id,state,options);
   }
-  const value = parseAsset(source, filePath);
-  validateAssetStructure(value, 'approval-record');
-  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
-  return value;
-}
-
-export function loadApprovalRecord(filePath, gateId) {
-  return selectApprovalRecord(yamlFromFile(filePath, "会签记录"), gateId);
-}
-
-function reviewBundleRows(bundle) {
-  if (bundle?.schema_version !== 1 || bundle.kind !== "review-bundle") fail("组合审查身份无效");
-  for (const field of ["bundle_id", "task_id", "work_unit_id", "review_session_id", "role_id", "runtime_id", "principal_ref"]) requireString(bundle[field], field);
-  if (!/^review-bundle\.[a-z0-9][a-z0-9-]*$/.test(bundle.bundle_id)) fail("组合审查 bundle_id 格式非法");
-  if (!/^work-unit\.[a-z0-9][a-z0-9-]*$/.test(bundle.work_unit_id)) fail("组合审查 work_unit_id 格式非法");
-  if (!Array.isArray(bundle.reviews) || !bundle.reviews.length) fail("组合审查不能为空");
-  if (new Set(bundle.reviews.map(row => row?.gate_id)).size !== bundle.reviews.length) fail("组合审查 gate_id 重复");
-  for (const row of bundle.reviews) {
-    if (!row || typeof row !== "object" || Array.isArray(row)) fail("组合审查结论必须是对象");
-    if (row.role_id !== bundle.role_id || row.runtime_id !== bundle.runtime_id || row.principal_ref !== bundle.principal_ref) fail("组合审查必须来自同一复核角色、运行时和实例");
-    if (row.review_session_id != null && row.review_session_id !== bundle.review_session_id) fail("组合审查 review_session_id 不一致");
+  if (record.schema_version === 2 && record.review_task_ref) {
+    const task = approvalIO(options).document(record.review_task_ref);
+    return approvalExpectedFromTask(task,{...options,read:options.read || readFileSync,boundary:record.gate_id,reviewTaskRef:record.review_task_ref,reviewTaskDigest:record.review_task_digest});
   }
-  return bundle.reviews;
+  return undefined;
 }
-
-export function selectApprovalRecord(record, gateId) {
-  if (record.kind !== 'review-bundle') return record;
-  const selected = reviewBundleRows(record).filter(x => x.gate_id === gateId);
-  if (selected.length !== 1) fail('组合审查缺少当前检查的明确结论');
-  return {
-    ...selected[0],
-    review_bundle_id: record.bundle_id,
-    review_task_id: record.task_id,
-    review_work_unit_id: record.work_unit_id,
-    review_session_id: record.review_session_id
-  };
-}
-
-export function resolveApprovalRef(approvalRef, fromFile = ROOT) {
-  requireString(approvalRef, "approval_ref");
-  if (path.isAbsolute(approvalRef)) return approvalRef;
-  const fromRoot = path.join(ROOT, approvalRef);
-  if (existsSync(fromRoot)) return fromRoot;
-  return path.resolve(path.dirname(fromFile), approvalRef);
-}
-
-export function validateApprovalRecord(record, { rolesDoc, requireApproved = false, ...decisionOptions } = {}) {
-  validateAssetStructure(record, 'approval-record');
-  if (!record || typeof record !== "object" || Array.isArray(record)) fail("会签记录必须是对象");
-  if (record.schema_version !== 1) fail("会签记录 schema_version 必须为 1");
-  requireString(record.gate_id, "gate_id");
-  requireString(record.decision, "decision");
-  if (!DECISIONS.has(record.decision)) fail("decision 必须是 approved、rejected 或 vetoed");
-  requireString(record.actor_kind, "actor_kind");
-  if (!ACTOR_KINDS.has(record.actor_kind)) fail("actor_kind 无效");
-  requireString(record.role_id, "role_id");
-  requireString(record.runtime_id, "runtime_id");
-  requireString(record.principal_ref, "principal_ref");
-
-  const registry = rolesDoc || loadDigitalHumanRoles();
-  const runtimeIds = new Set((registry.runtimes || []).map((runtime) => runtime.id));
-  if (!runtimeIds.has(record.runtime_id)) fail(`未知 runtime_id: ${record.runtime_id}`);
-  if (record.actor_kind === "orchestrator") fail("编排器门禁不使用会签记录关闭");
-
-  if (!requireApproved && loadRegistry().id_policy.deprecated_ids.includes(record.gate_id)) return { bucket: "historical", gate: record.gate_id };
-  let rule = countersignRuleForGate(registry.gate_policy, record.gate_id);
-  const continuationReviewers = registry.gate_policy.continuation_reviews?.[record.gate_id];
-  if (record.continuation_ref && record.actor_kind === 'digital-human' && continuationReviewers) {
-    rule = { bucket: 'digital_human_review', gate: record.gate_id, countersigners: continuationReviewers };
-    if (!record.drafter_principal_ref || record.drafter_principal_ref === record.principal_ref) fail('延续批准必须由独立审查者核验');
-  }
-  if (!rule) fail(`${record.gate_id} 不是会签门禁；evidence_only / orchestrator 门禁不写 approval-record`);
-
-  if (requireApproved && record.decision !== "approved") {
-    fail(`${record.gate_id} 会签 decision 必须为 approved 才能关闭门禁`);
+export function validateApprovalRecord(record, options = {}) {
+  if (options.history === true || options.requireApproved === false) {
+    validateAssetStructure(record,'approval-record');
+    if (record.kind === 'review-bundle') reviewBundleRows(record);
+    return {bucket:'history-only',record,execution_authorization:'not-evaluated'};
   }
-  if (record.decision === "approved" && record.biological_veto === true) {
-    fail(`${record.gate_id} 已被生物人否决，不能标为 approved`);
-  }
-
-  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;
-  }
-
-  if (record.actor_kind !== "digital-human") fail(`${record.gate_id} 必须由数字人会签`);
-  if (!rule.countersigners.includes(record.role_id)) {
-    fail(`${record.gate_id} 会签角色必须是 ${rule.countersigners.join(" / ")}`);
-  }
-  if (rule.drafter && record.role_id === rule.drafter) fail(`${record.gate_id} 起草者不得会签自己`);
-  if (Array.isArray(record.countersigner_role_ids) && rule.drafter && record.countersigner_role_ids.includes(rule.drafter)) {
-    fail(`${record.gate_id} 起草者不得出现在 countersigner_role_ids`);
-  }
-  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;
+  return withValidationPhase({root:options.root || ROOT,purpose:'approval-current',readOnly:true},()=>assertCurrentApproval(record,expectedFor(record,options),options));
 }
-
-function assertRecordUserDecision(record, registry, options) {
-  if (!registry.user_decision_policy.gates.includes(record.gate_id)) return;
-  const result = assertApprovalUserDecision(record, registry, options);
-  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 = {}) {
-  const record = yamlFromFile(filePath, "会签记录");
-  if (record.kind === 'review-bundle') {
-    return reviewBundleRows(record).map(item => {
-      const row = loadApprovalRecord(filePath, item.gate_id);
-      if (options.requireApproved) {
-        if (!row.drafter_principal_ref || row.drafter_principal_ref === row.principal_ref) fail('组合审查必须保留独立身份');
-        const io = decisionIO(options);
-        if (!row.subject_ref || decisionDigest(io.bytes(row.subject_ref)) !== `sha256:${row.subject_digest}`) fail('组合审查主体缺失或已过期');
-      }
-      return validateApprovalRecord(row, options);
-    });
-  }
-  return validateApprovalRecord(record, options);
+  if (options.history === true || options.requireApproved === false) return readApprovalHistory(filePath,options);
+  return withValidationPhase({root:options.root || ROOT,purpose:'approval-current',readOnly:true},()=>{
+    const record = readApprovalDocument(filePath,options);
+    if (record.kind !== 'review-bundle') return assertCurrentApproval(record,expectedFor(record,options),options);
+    return reviewBundleRows(record).map(row=>assertCurrentApproval(loadApprovalRecord(filePath,row.gate_id,options),expectedFor(row,options),options));
+  });
 }
-
-export function assertApprovedGateHasValidApproval(gateId, gateState, { checkpointPath } = {}) {
-  const rolesDoc = loadDigitalHumanRoles();
-  const countersignGates = new Set(collectCountersignGateIds(rolesDoc.gate_policy));
-  if (!countersignGates.has(gateId)) return;
-  if (!gateState || typeof gateState !== "object") fail(`${gateId} 缺少门禁状态`);
-  if (gateState.status !== "approved") return;
-  if (!gateState.approval_ref || !String(gateState.approval_ref).trim()) {
-    fail(`${gateId} 已 approved 但缺少 approval_ref`);
-  }
-  const resolved = resolveApprovalRef(gateState.approval_ref, checkpointPath || ROOT);
-  if (!existsSync(resolved)) fail(`${gateId} 的 approval_ref 不可读: ${gateState.approval_ref}`);
-  const record = loadApprovalRecord(resolved, gateId);
-  if (record.gate_id !== gateId) fail(`${gateId} 的会签记录 gate_id 不匹配`);
-  if (!gateState.subject_ref || gateState.subject_ref !== record.subject_ref || !gateState.approval_scope?.length || JSON.stringify([...gateState.approval_scope].sort()) !== JSON.stringify([...(record.approval_scope || [])].sort())) {
-    fail(`${gateId} user-decision-subject-mismatch: 当前门禁资产与会签范围不匹配`);
-  }
-  validateApprovalRecord(record, { rolesDoc, requireApproved: true });
+export function assertApprovedGateHasValidApproval(gateId,gateState,options = {}) {
+  const rolesDoc=options.rolesDoc || loadDigitalHumanRoles();
+  if (!countersignRuleForGate(rolesDoc.gate_policy,gateId)) return;
+  if (!gateState || typeof gateState !== 'object') approvalError('APPROVAL_CONTEXT_REQUIRED',`${gateId} 缺少门禁状态`);
+  if (gateState.status !== 'approved') return;
+  if (!gateState.approval_ref) approvalError('APPROVAL_REFERENCE_REQUIRED',`${gateId} 已 approved 但缺少 approval_ref`);
+  return withValidationPhase({root:options.root || ROOT,purpose:'approval-helper-current',readOnly:true},()=>{
+    const file=resolveApprovalRef(gateState.approval_ref,options.checkpointPath || ROOT,options);
+    // A gate assertion always consumes current authority. History options only
+    // belong to the separate history reader and cannot weaken this boundary.
+    return assertCurrentApproval(loadApprovalRecord(file,gateId,options),approvalExpectationFromState(gateId,gateState,options),{...options,rolesDoc});
+  });
 }
-
-export function assertCheckpointApprovals(checkpoint, checkpointPath) {
-  const gates = checkpoint?.gates;
-  if (!gates || typeof gates !== "object") return;
-  const known = new Set(loadRegistry().gates.map(gate => gate.id));
-  for (const [gateId, state] of Object.entries(gates)) {
-    if (!known.has(gateId)) fail(`未知或已退役门禁: ${gateId}；历史记录只读，不自动迁移批准`);
-    if (state.status === "approved") assertGateChecks(gateId, checkpoint);
-    assertApprovedGateHasValidApproval(gateId, state, { checkpointPath });
-  }
+export function assertCheckpointApprovals(checkpoint,checkpointPath,options = {}) {
+  const registry=options.registry || loadRegistry(),rolesDoc=options.rolesDoc || loadDigitalHumanRoles();
+  return withValidationPhase({root:options.root || ROOT,purpose:'checkpoint-approvals',readOnly:true},()=>{
+    const known=new Set(registry.gates.map(gate=>gate.id));
+    for (const [gateId,state] of Object.entries(checkpoint?.gates || {})) {
+      if (!known.has(gateId)) approvalError('APPROVAL_CURRENT_INVALID',`未知或已退役门禁: ${gateId}；历史记录只读，不自动迁移批准`);
+      if (state.status === 'approved') assertGateChecks(gateId,checkpoint,{...options,registry,rolesDoc});
+      assertApprovedGateHasValidApproval(gateId,state,{...options,checkpointPath,registry,rolesDoc});
+    }
+  });
 }
 
 // Called on resume/transition as well as completion; drafting while waiting stays allowed.
-export function assertCheckpointUserDecisions(checkpoint) {
+export function assertCheckpointUserDecisions(checkpoint, options = {}) {
   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 (completedUnit) assertWorkUnitUserDecision(completedUnit, state, options);
+  if (checkpoint.next_work_unit === "work-unit.slice-implementation") assertImplementationDecision({ ...review.implementation, ...state }, options);
+  for (const requirement of review.required_decisions || []) assertUserDecisionRequirement(requirement, options);
+  if (review.external_input) assertUserDecisionRequirement({ ...review.external_input, boundary: "external-input" }, options);
   if (checkpoint.status === "completed") {
     if (checkpoint.blockers?.length || Object.values(checkpoint.gates || {}).some(gate => !["approved", "not-applicable"].includes(gate.status))) throw new TypeError("lifecycle-control-blocked: 仍有阻塞或未通过门禁，不可完成");
-    if (checkpoint.gates?.["gate.delivery-accepted"]?.status !== "approved") throw new TypeError("lifecycle-control-blocked: 阶段完成须交付验收，不等于发布授权");
+    const completionGate=loadRegistry().gates.some(gate=>gate.id==="gate.strategic-design-handoff-approved")?"gate.strategic-design-handoff-approved":"gate.delivery-accepted";
+    if (checkpoint.gates?.[completionGate]?.status !== "approved") throw new TypeError("lifecycle-control-blocked: 阶段完成须当前交付或战略交接验收，不等于发布授权");
+  }
+}
+
+// Strategic profiles retain their bounded stage-transition API while using the same current kernel.
+export function assertStrategicWorkUnitDecision(workUnit, state, options = {}) {
+  const roles=options.rolesDoc || loadDigitalHumanRoles();
+  const boundaries=workUnit==='work-unit.strategic-design-handoff' ? ['gate.strategic-design-handoff-approved'] : [...(roles.user_decision_policy.work_unit_gates?.[workUnit] || []), ...(roles.user_decision_policy.work_units?.[workUnit] ? [roles.user_decision_policy.work_units[workUnit]] : [])];
+  for(const boundary of boundaries) {
+    const gate=state.gates?.[boundary];
+    if(gate?.status==='approved') {
+      assertGateChecks(boundary,state,options);
+      assertApprovedGateHasValidApproval(boundary,gate,{...options,rolesDoc:roles});
+    } else if(workUnit==='work-unit.strategic-design-handoff') {
+      approvalError('APPROVAL_CURRENT_INVALID','strategic-gate-migration-required: '+boundary);
+    } else {
+      assertWorkUnitUserDecision(workUnit,{user_decisions:state.user_decisions || state.human_review?.user_decisions || [],user_decision_not_applicable:state.user_decision_not_applicable || state.human_review?.not_applicable || []},{...options,rolesDoc:roles});break;
+    }
   }
 }

package/template/scripts/lib/approved-execution-context.mjs

@@ -1,3 +1,4 @@
+import {approvalExpectationForCheckpoint,approvalExpectationForBoundAsset} from './approval-consumption.mjs';
 import {validateJsonSchemas} from './json-schema.mjs';
 import { assertScopeSlice, assertScopeWorkUnit } from './lifecycle-execution-scope.mjs';
 import { selectSliceWorkUnit, normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
@@ -5,7 +6,7 @@ import path from 'node:path';
 import { readFileSync, inValidationPhase, validationMemo, validationPhaseToken } from './validation-phase.mjs';
 import { ROOT, read, parse, safe, hash, digest, schema } from './strategic-handoff-io.mjs';
 import { countersignRuleForGate } from './digital-human-roles.mjs';
-import { validateApprovalRecord } from './approval-record.mjs';
+import { validateApprovalRecord, loadApprovalRecord } from './approval-record.mjs';
 import { assertImplementationDecision } from './user-decision.mjs';
 import { loadSkillRegistry } from './skill-registry.mjs';
 
@@ -52,7 +53,7 @@ export function verifySliceContractApproval(binding,{root=process.cwd(),contract
     assertImplementationDecision({...review.implementation,user_decisions:review.user_decisions||[]},{...ioFor(root),rolesDoc:roles});
   } else {
     // Historical source profiles that declared this a countersign gate retain their policy.
-    validateApprovalRecord(approval,{...ioFor(root),rolesDoc:roles,requireApproved:true});
+    validateApprovalRecord(approval,{...ioFor(root),rolesDoc:roles,requireApproved:true,expected:approvalExpectationForBoundAsset(gateId,binding,{...ioFor(root),review_package:false})});
     check(approval.gate_id===gateId&&approval.artifact_bindings?.some(item=>item.id===contract.contract_id&&item.version===contract.contract_version&&item.digest===binding.digest),'EXECUTION_APPROVAL_SCOPE','源会签未绑定当前 Slice 的身份、版本和字节');
   }
   if(contract.schema_version===3) verifySliceProfessionalReview(approval,{...binding,id:contract.contract_id,version:contract.contract_version},roles,root);
@@ -144,14 +145,15 @@ function verifySliceProfessionalReview(approval,binding,roles,root) {
     if(!/\.(yaml|yml|json)$/.test(ref))continue;
     const record=read(safe(root,ref));
     const rows=record.kind==='review-bundle'?record.reviews:[record];
-    for(const row of rows || []) {
-      if(row.gate_id!=='check.design-reviewed'||row.subject_ref!==binding.ref)continue;
-      validateApprovalRecord(row,{...ioFor(root),rolesDoc:roles,requireApproved:true});
+    if(!(rows || []).some(row=>row.gate_id==='check.design-reviewed'&&row.subject_ref===binding.ref))continue;
+    // Loading the selected conclusion validates the entire container and carries
+    // its task/session identity into the same current-approval kernel.
+    const row=loadApprovalRecord(safe(root,ref),'check.design-reviewed',ioFor(root));
+      validateApprovalRecord(row,{...ioFor(root),rolesDoc:roles,requireApproved:true,expected:approvalExpectationForCheckpoint('check.design-reviewed',approval.checks?.['check.design-reviewed'],{...ioFor(root),review_package:false})});
       check(row.drafter_principal_ref&&row.principal_ref!==row.drafter_principal_ref,'EXECUTION_REVIEW_NOT_INDEPENDENT','Slice 工程审查必须独立于起草者');
       check(row.subject_digest===binding.digest.slice(7)&&row.artifact_bindings?.some(x=>x.id===binding.id&&x.version===binding.version&&x.digest===binding.digest),'EXECUTION_REVIEW_STALE','Slice 工程审查未绑定当前合同');
       check(Array.isArray(row.findings)&&row.findings.every(x=>x.kind==='suggestion'?!!x.follow_up:['requirement-violation','missing-evidence','important-risk'].includes(x.kind)&&x.status==='resolved'),'EXECUTION_REVIEW_BLOCKED','Slice 工程审查有未关闭问题');
       found=true;
-    }
   }
   check(found,'EXECUTION_REVIEW_REQUIRED','Slice v3 缺少当前合同的独立工程审查');
 }

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

@@ -1,3 +1,4 @@
+import {findApprovalCheckpoint} from './approval-checkpoint-discovery.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -72,7 +73,10 @@ export function validateAssetSemantics(root, ref, kind) {
     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];
+    if(kind==='approval-record') {
+      const current=value.decision==='approved'||value.kind==='review-bundle';
+      args=current&&value.schema_version!==2?['--require-approved','--checkpoint',findApprovalCheckpoint(root,ref),file]:[current?'--require-approved':'--history',file];
+    } else args=[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 });

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

@@ -21,7 +21,7 @@ async function approvedFile(root, binding, gate) {
   if(gate==='gate.slice-contract-approved'){verifySliceContractApproval(binding,{root});return bytes;}
   const record=read(safe(root,binding.approval_ref));
   const roles=sourceApprovalPolicy(read(safe(root,'.template-spec/agents/digital-human-roles.yaml')));
-  await sourceApproval(record,roles,root);
+  await sourceApproval(record,roles,root,binding);
   ensure((Array.isArray(gate)?gate:[gate]).includes(record.gate_id),`交付资产批准门禁不匹配: ${binding.ref}`);
   ensure(record.artifact_bindings?.some(x=>x.id===binding.id&&x.version===binding.version&&x.digest===binding.digest),`批准未绑定当前交付资产: ${binding.ref}`);
   return bytes;

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

@@ -1,3 +1,4 @@
+import {approvalExpectationForBoundAsset} from './approval-consumption.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -124,7 +125,7 @@ function validateBaselineReview(state,{root}) {
     ensure(digest(fs.readFileSync(file(root,input.spec_binding.ref)))===input.spec_binding.digest.replace(/^sha256:/,''),'Spec evidence stale');
     ensure(text(input.spec_binding.approval_ref),'Spec approval record required');
     const approval=parseSliceYaml(fs.readFileSync(file(root,input.spec_binding.approval_ref),'utf8'));
-    validateApprovalRecord(approval,{root,requireApproved:true,rolesDoc:parseSliceYaml(fs.readFileSync(file(root,'.template-spec/agents/digital-human-roles.yaml'),'utf8'))});
+    validateApprovalRecord(approval,{root,requireApproved:true,rolesDoc:parseSliceYaml(fs.readFileSync(file(root,'.template-spec/agents/digital-human-roles.yaml'),'utf8')),expected:approvalExpectationForBoundAsset('gate.spec-baseline-approved',input.spec_binding,{root})});
     ensure(approval.gate_id==='gate.spec-baseline-approved' && approval.artifact_bindings?.some(b=>b.digest.replace(/^sha256:/,'')===input.spec_binding.digest.replace(/^sha256:/,'')),'Spec approval does not bind current baseline');
     ensure(Array.isArray(result.constraint_results)&&result.constraint_results.some(r=>r.axis==='Spec'&&r.status==='passed'&&text(r.evidence_ref)),'Spec acceptance evidence required');
     for(const row of result.constraint_results.filter(r=>r.axis==='Spec')) {

package/template/scripts/lib/backend-scaffold-prerequisites.mjs

@@ -1,3 +1,4 @@
+import {approvalExpectationForBoundAsset} from './approval-consumption.mjs';
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
@@ -103,7 +104,7 @@ export async function validateBackendScaffoldPrerequisites(contract, { contractF
   if (approvalRef !== contract.lifecycle_approval_ref || approvalRef !== contract.approval?.approval_ref) fail("工程合同批准引用与脚手架合同不一致");
   const approvalFile = resolveLocalRef(root, approvalRef, "工程合同批准记录");
   const approval = loadApprovalRecord(approvalFile, 'gate.engineering-contract-approved');
-  validateApprovalRecord(approval, { requireApproved: true, root });
+  validateApprovalRecord(approval, { requireApproved: true, root, expected: approvalExpectationForBoundAsset('gate.engineering-contract-approved',prerequisites.technical_design,{root,scope:[contract.contract_id,contract.project_name]}) });
   if (approval.gate_id !== "gate.engineering-contract-approved") fail("工程合同批准记录 gate_id 必须为 gate.engineering-contract-approved");
   if (!Array.isArray(approval.approval_scope) || !approval.approval_scope.includes(contract.contract_id) || !approval.approval_scope.includes(contract.project_name)) fail("工程合同批准范围未覆盖当前合同和项目");
   requireEngineeringPackage(root, approval, contract, technical, data, api, prerequisites);
@@ -115,7 +116,7 @@ export async function validateBackendScaffoldPrerequisites(contract, { contractF
   }
 
   return {
-    technical_design: { ref: prerequisites.technical_design.ref, version: technical.value.version, digest: prerequisites.technical_design.digest },
+    technical_design: { ref: prerequisites.technical_design.ref, version: technical.value.version, digest: prerequisites.technical_design.digest, ...(prerequisites.technical_design.approval_context ? { approval_context: structuredClone(prerequisites.technical_design.approval_context) } : {}) },
     data_architecture_decision: { ref: prerequisites.data_architecture_decision.ref, version: data.value.decision_version, digest: prerequisites.data_architecture_decision.digest, impact: data.value.impact },
     api_contract_decision: { ref: prerequisites.api_contract_decision.ref, version: api.decision.decision_version, digest: prerequisites.api_contract_decision.digest, impact: api.decision.impact },
     engineering_contract_approval_ref: approvalRef,

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

@@ -1,3 +1,4 @@
+import {approvalExpectationForCheckpoint} from './approval-consumption.mjs';
 import fs from 'node:fs';
 import {businessAuthoringEnabled,businessPath,businessSetRef,checkBusinessTickets,assertBusinessDeferredApprovals} from './business-tickets.mjs';
 import {yamlValue} from './plan-spec-markdown.mjs';
@@ -18,7 +19,7 @@ export function assertBusinessApprovalBasis(root,state,{required=false}={}) {
     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});
+    validateApprovalRecord(record,{root,rolesDoc,requireApproved:true,expected:approvalExpectationForCheckpoint(id,gate,{root})});
     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.

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

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Reject ids that git cannot turn into a ref ("" .. "", trailing ".lock",
+// path separators, unsafe characters) before anything is written.
+const RUN_ID_PATTERN = /^(?!.*\.\.)[a-z0-9][a-z0-9._-]{0,62}$/;
+export const CHECKPOINT_PREFIX = "refs/checkpoints/";
+
+export function validateCheckpointRunId(root, runId, { spawn = spawnSync } = {}) {
+  if (typeof runId !== "string" || !RUN_ID_PATTERN.test(runId) || runId.endsWith(".lock")) {
+    throw new TypeError("run-id 必须安全（小写字母/数字/._-；不得含 .. 或以 .lock 结尾）: " + String(runId));
+  }
+  const reference = CHECKPOINT_PREFIX + runId;
+  const checked = spawn("git", ["-C", root, "check-ref-format", reference], { encoding: "utf8" });
+  if (checked.status !== 0) throw new TypeError("非法 checkpoint 引用: " + reference);
+  return reference;
+}
+
+// Create an immutable checkpoint commit of the current working tree without
+// touching the user's index, working tree, branch or HEAD. A temporary index is
+// populated from the base commit plus the working tree, written to a tree
+// object, wrapped in a commit, and published only as a local
+// refs/checkpoints/<run-id> ref.
+export function commitCheckpoint({ root, runId, message, baseRef = "HEAD", dryRun = false, spawn = spawnSync } = {}) {
+  const reference = validateCheckpointRunId(root, runId, { spawn });
+  const run = (args, options) => {
+    const result = spawn("git", ["-C", root, ...args], { encoding: "utf8", maxBuffer: 128 * 1024 * 1024, ...options });
+    if (result.status !== 0) throw new TypeError((result.stderr || "").trim() || "git " + args.join(" ") + " 执行失败");
+    return result.stdout.trim();
+  };
+  const parent = run(["rev-parse", "--verify", baseRef + "^{commit}"]);
+  const existing = spawn("git", ["-C", root, "rev-parse", "--verify", "--quiet", reference], { encoding: "utf8" });
+  if (dryRun) return { ref: reference, commit: null, tree: null, parent, run_id: runId, dry_run: true, exists: existing.status === 0 };
+  if (existing.status === 0) throw new TypeError("checkpoint 已存在，拒绝覆盖: " + reference);
+  const indexDirectory = mkdtempSync(path.join(os.tmpdir(), "yss-checkpoint-index-"));
+  const indexPath = path.join(indexDirectory, "index");
+  const env = { ...process.env, GIT_INDEX_FILE: indexPath };
+  try {
+    run(["read-tree", baseRef], { env });
+    run(["add", "-A", "--", "."], { env });
+    const tree = run(["write-tree"], { env });
+    const commit = run(["commit-tree", tree, "-p", parent, "-m", message || ("checkpoint " + runId)], { env });
+    run(["update-ref", reference, commit]);
+    return { ref: reference, commit, tree, parent, run_id: runId, dry_run: false, exists: false };
+  } finally {
+    rmSync(indexDirectory, { recursive: true, force: true });
+  }
+}

package/template/scripts/lib/command-runner.mjs

@@ -1,9 +1,25 @@
 import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, rmSync, writeFileSync } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
+import path from "node:path";
+import { assertNodeVersion } from "./runtime-store.mjs";
 import { fileURLToPath } from "node:url";
 
-function killTree(child, signal) {
+const sessionSequences = new WeakMap();
+function runtimeLogs(session, stdoutFile, stderrFile) {
+  if (!session) return { stdoutFile, stderrFile };
+  const sequence = sessionSequences.get(session) || 0;
+  sessionSequences.set(session, sequence + 1);
+  return { stdoutFile: stdoutFile || path.join(session.runDir, `command-${sequence}.stdout`), stderrFile: stderrFile || path.join(session.runDir, `command-${sequence}.stderr`) };
+}
+function recordRuntimeResult(session, result, command, args, files) {
+  if (!session) return result;
+  try { session.recordCommand({ command: JSON.stringify([command, ...args]), ...result, stdout: undefined, stderr: undefined, ...files }); }
+  catch (error) { result.storageError = [result.storageError,error.message].filter(Boolean).join("; "); }
+  return result;
+}
+
+export function killTree(child, signal) {
   if (!child.pid) return;
   try {
     if (process.platform === "win32") spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
@@ -12,9 +28,10 @@ function killTree(child, signal) {
 }
 
 /** Bounded lifetime for external tools; stdout is never mixed with progress. */
-export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 0, signal, stdoutFile, stderrFile, secrets = [], progress = false } = {}) {
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 0, signal, stdoutFile, stderrFile, secrets = [], progress = false, runtimeSession } = {}) {
+  assertNodeVersion();
+  ({ stdoutFile, stderrFile } = runtimeLogs(runtimeSession, stdoutFile, stderrFile));
   if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError("timeoutMs 必须是非负毫秒数");
-  if (signal?.aborted) return Promise.resolve({ status: 1, stdout: "", stderr: "command cancelled", termination: "cancelled", duration_ms: 0 });
   return new Promise(resolve => {
     const started = performance.now();
     const argumentSecrets = args.flatMap(value => { try { const url = new URL(value); return url.password ? [url.password, decodeURIComponent(url.password)] : []; } catch { return []; } });
@@ -22,14 +39,15 @@ export function runCommand(command, args, { cwd, env = process.env, timeoutMs =
     const replacement = secret => secretNames.has(secret) ? `[REDACTED:${secretNames.get(secret)}]` : "[REDACTED]";
     const sensitive = [...secrets, ...argumentSecrets, ...secretNames.keys()].filter(value => typeof value === "string" && value.length > 0).sort((a, b) => b.length - a.length);
     const redact = text => sensitive.reduce((value, secret) => value.replaceAll(secret, replacement(secret)), text);
+    if (signal?.aborted) { resolve(recordRuntimeResult(runtimeSession,{status:1,stdout:"",stderr:"command cancelled",termination:"cancelled",duration_ms:0,actual_exit_code:null,actual_exit_signal:null,actual_exit_code_observed:false},redact(command),args.map(redact),{}));return; }
     if (progress) process.stderr.write(`[开始] ${redact(command + " " + args.join(" "))}\n`);
     for (const file of [stdoutFile, stderrFile]) if (file) writeFileSync(file, "");
     const child = spawn(command, args, { cwd, env, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
-    let termination = null, escalation, timer, errorMessage;
+    let termination = null, escalation, timer, errorMessage, logError, spawnError = false;
     const makeStream = file => {
       const decoder = new StringDecoder("utf8");
       let pending = "", captured = "";
-      const emit = text => { captured += text; if (file) appendFileSync(file, text); };
+      const emit = text => { captured += text; if (file && !logError) try { appendFileSync(file, text); } catch (error) { logError=error.message; } };
       function consume(final = false) {
         let output = "", cursor = 0;
         while (cursor < pending.length) {
@@ -57,7 +75,7 @@ export function runCommand(command, args, { cwd, env = process.env, timeoutMs =
     if (timeoutMs) timer = setTimeout(() => cancel("timeout"), timeoutMs);
     child.stdout.on("data", bytes => stdout.write(bytes));
     child.stderr.on("data", bytes => stderr.write(bytes));
-    child.on("error", error => { errorMessage = redact(error.message); });
+    child.on("error", error => { spawnError = true; errorMessage = redact(error.message); });
     child.on("close", (code, exitSignal) => {
       clearTimeout(timer); clearTimeout(escalation);
       // A group leader can exit before its descendants close redirected streams.
@@ -67,7 +85,13 @@ export function runCommand(command, args, { cwd, env = process.env, timeoutMs =
       const duration_ms = performance.now() - started;
       const status = termination === "timeout" ? 124 : termination ? 1 : code ?? 1;
       if (progress) process.stderr.write(`[${status === 0 ? "完成" : "失败"}] ${command} (${Math.round(duration_ms)}ms, exit=${status}${termination ? `, ${termination}` : ""})\n`);
-      resolve({ status, stdout: stdout.end(), stderr: stderr.end() + (errorMessage || ""), signal: exitSignal, termination, duration_ms });
+      const actual_exit_code_observed = !spawnError && Number.isInteger(code);
+      const result = { status, stdout: stdout.end(), stderr: stderr.end() + (errorMessage || ""), signal: exitSignal, termination, duration_ms,
+        actual_exit_code: actual_exit_code_observed ? code : null,
+        actual_exit_signal: spawnError ? null : exitSignal ?? null,
+        actual_exit_code_observed };
+      if(logError)result.storageError=logError;
+      resolve(recordRuntimeResult(runtimeSession, result, redact(command), args.map(redact), { stdoutFile, stderrFile }));
     });
   });
 }
@@ -75,12 +99,23 @@ export function runCommand(command, args, { cwd, env = process.env, timeoutMs =
 // Synchronous API compatibility for existing generators/cache consumers. The worker
 // owns the process group and streams logs; it never updates project metadata.
 export function runCommandSync(command, args, options = {}) {
+  assertNodeVersion();
+  const { runtimeSession, ...workerOptions } = options;
+  Object.assign(workerOptions, runtimeLogs(runtimeSession, options.stdoutFile, options.stderrFile));
   const result = spawnSync(process.execPath, [fileURLToPath(import.meta.url), "--worker"], {
-    input: JSON.stringify({ command, args, options }), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+    input: JSON.stringify({ command, args, options: workerOptions }), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
     stdio: ["pipe", "pipe", "inherit"], env: options.env ?? process.env,
   });
   if (result.error || result.status !== 0) throw new TypeError(result.error?.message || "command worker failed");
-  return JSON.parse(result.stdout);
+  const value = JSON.parse(result.stdout);
+  if (runtimeSession) {
+    // The worker already redacts output. Redact arguments before registering in the parent.
+    const env = options.env || process.env;
+    const sensitive = [...(options.secrets || []), ...Object.entries(env).filter(([key]) => /(?:PASSWORD|TOKEN|SECRET)$/.test(key) || key === "MAVEN_REPO_USERNAME").map(([, secret]) => secret), ...args.flatMap(arg => { try { const url = new URL(arg); return url.password ? [url.password, decodeURIComponent(url.password)] : []; } catch { return []; } })].filter(secret => typeof secret === "string" && secret.length).sort((a,b) => b.length - a.length);
+    const redact = text => sensitive.reduce((value, secret) => value.replaceAll(secret, "[REDACTED]"), text);
+    return recordRuntimeResult(runtimeSession, value, redact(command), args.map(redact), { stdoutFile: workerOptions.stdoutFile, stderrFile: workerOptions.stderrFile });
+  }
+  return value;
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === "--worker") {