create-yss-spec 3.5.3 → 3.5.5

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

@@ -17,6 +17,10 @@ export function withSourceContextSnapshot(root, action) {
   roots.add(path.resolve(root));
   return sourceContextSnapshots.run(roots, action);
 }
+export function sourceContextRef(root, ref) {
+  return ref === 'CONTEXT.md' && sourceContextSnapshots.getStore()?.has(path.resolve(root))
+    ? 'source-context.snapshot.md' : ref;
+}
 export const ensure = (condition, message) => { if (!condition) throw new TypeError(message); };
 export const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
 export const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
@@ -35,7 +39,7 @@ export function relative(ref) {
 }
 export function safe(root, ref, { missing = false } = {}) {
   relative(ref);
-  if (ref === 'CONTEXT.md' && sourceContextSnapshots.getStore()?.has(path.resolve(root))) ref = 'source-context.snapshot.md';
+  ref = sourceContextRef(root, ref);
   let current = path.resolve(root);
   ensure(!existsSync(current) || !lstatSync(current).isSymbolicLink(), `根目录不能是 symlink: ${root}`);
   for (const part of ref.split('/')) {
@@ -79,7 +83,7 @@ export function archive(command, source, destination) {
 export function sourceApprovalPolicy(source) {
   const roles=structuredClone(source);
   roles.user_decision_policy ||= {gates:[]};
-  ensure(!(roles.user_decision_policy.required_capabilities || []).some(id => id !== 'strategic-decision-reuse-v1'), '接收工具不支持源用户决定策略，请升级工具后验包');
+  ensure(!(roles.user_decision_policy.required_capabilities || []).some(id => !['strategic-decision-reuse-v1','business-ticket-approval-v1'].includes(id)), '接收工具不支持源用户决定策略，请升级工具后验包');
   const policy=roles.gate_policy;
   // Dedicated receivers may predate check_reviews. Mirror source check-review
   // rules into their existing digital review lookup without changing source bytes.

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

@@ -1,3 +1,4 @@
+import { BUSINESS_TICKET_CAPABILITY, checkBusinessTickets, assertBusinessDeferredApprovals } from './business-tickets.mjs';
 import { scopedConsumerCapabilities } from './strategic-handoff-routing.mjs';
 import { existsSync, lstatSync, readFileSync } from './validation-phase.mjs';
 import { mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
@@ -194,8 +195,20 @@ export async function inspectSource(root, handoffRef) {
   const explicitlyReviewed=(gate)=>(roles.gate_policy.digital_human_review||[]).some(rule=>rule.gate===gate)||(roles.gate_policy.dual_digital_human||[]).some(rule=>rule.gate===gate)||(roles.gate_policy.biological_human||[]).includes(gate);
   const terminalGate=currentPlan||explicitlyReviewed('gate.strategic-design-handoff-approved')?'gate.strategic-design-handoff-approved':'gate.stage-decision-package-approved';
   const expectedGates={domain_strategy_ref:currentPlan?'gate.plan-approved':'gate.domain-strategy-approved',stage_decision_package_ref:currentPlan?'gate.plan-approved':'gate.stage-decision-package-approved',spec_ref:'gate.spec-baseline-approved',prototype_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',visual_baseline_ref:currentPlan?'gate.product-design-approved':'gate.user-confirmation',business_ticket_set_ref:currentPlan?'gate.plan-approved':terminalGate,handoff:terminalGate};
+  const setSource=read(safe(root,handoff.source.business_ticket_set_ref.persisted_ref));
+  if(setSource?.kind==='business-ticket-set')ensure(roles.user_decision_policy.required_capabilities?.includes(BUSINESS_TICKET_CAPABILITY),'新业务集合缺少批准策略能力声明');
+  let business;
+  if (roles.user_decision_policy.required_capabilities?.includes(BUSINESS_TICKET_CAPABILITY)) {
+    expectedGates.business_ticket_set_ref=terminalGate;
+    business=checkBusinessTickets({root,setRef:handoff.source.business_ticket_set_ref.persisted_ref,mode:'formal'});
+    ensure(business.status==='passed',`业务 Ticket 未正式化: ${business.diagnostics.map(x=>x.code).join(', ')}`);
+    const setBinding=handoff.source.business_ticket_set_ref,specBinding=handoff.source.spec_ref;
+    ensure(business.id===setBinding.id&&business.version===setBinding.version,'业务集合身份或版本与交接不一致');
+    ensure(business.spec.ref===specBinding.persisted_ref&&business.spec.version===specBinding.version&&business.spec.digest===hash(readFileSync(safe(root,specBinding.persisted_ref))),'业务集合未绑定当前交接 Spec');
+  }
   expectedGates.existing_ui_baseline_ref=expectedGates.prototype_ref;
   const bindings={...handoff.source,handoff:{id:handoff.handoff_id,version:handoff.handoff_version,persisted_ref:handoffRef,status:'approved'}};
+  const businessProofRefs=[];
   for(const [key,ref] of Object.entries(bindings)) {
     const approval=config.approvals[key];
     ensure(approval,`缺少资产批准绑定: ${key}`);
@@ -213,9 +226,11 @@ export async function inspectSource(root, handoffRef) {
     const record=sourceApprovalRecord(read(safe(root,approval.record_ref)),approval.gate_id);
     if(key==='existing_ui_baseline_ref')ensure(record.subject_ref===`${ref.persisted_ref}/${ref.manifest_ref}`,'既有 UI 用户决定必须以当前 manifest 为批准主体');
     await sourceApproval(record,roles,root);
+    businessProofRefs.push(approval.record_ref,record.user_decision_ref,record.continuation_ref,record.decision_reuse_ref);
     ensure(record.gate_id===approval.gate_id,`批准门禁不匹配: ${key}`);
     ensure((record.artifact_bindings || []).some(x=>x.id===(ref.id||ref.baseline_id) && x.version===ref.version && x.digest===actual),`批准记录未绑定当前资产: ${key}`);
   }
+  if(business)assertBusinessDeferredApprovals(business,businessProofRefs);
   if (roles.user_decision_policy.required_capabilities?.includes('strategic-decision-reuse-v1')) {
     const record=sourceApprovalRecord(read(safe(root,config.approvals.handoff.record_ref)),config.approvals.handoff.gate_id);
     const scope=read(safe(root,record.subject_ref));
@@ -233,18 +248,24 @@ export async function inspectSource(root, handoffRef) {
     const receipt=previewFiles(root,config.prototype);
     ensure(uiBaselineCaseIds(handoff).every(id=>receipt.case_ids.includes(id)), '离线验证未覆盖视觉基线 case');
   }
-  return {handoff,config,indexes,strategy,stage};
+  return {handoff,config,indexes,strategy,stage,business};
 }
 
 function collect(root, handoffRef, handoff, config) {
   const collected=new Map(), queue=[handoffRef,'CONTEXT.md','.template-spec/agents/digital-human-roles.yaml',...Object.values(handoff.source).map(x=>x.persisted_ref),...Object.values(config.approvals).map(x=>x.record_ref),...handoff.evidence_and_version_digests,...config.additional_files];
+  const roles=sourceApprovalPolicy(read(safe(root,'.template-spec/agents/digital-human-roles.yaml')));
+  if(roles.user_decision_policy.required_capabilities?.includes(BUSINESS_TICKET_CAPABILITY)) {
+    const report=checkBusinessTickets({root,setRef:handoff.source.business_ticket_set_ref.persisted_ref,mode:'formal'});
+    ensure(report.status==='passed','业务 Ticket 导出前来源已变化');
+    queue.push(...report.inputs.map(item=>item.ref));
+  }
   if(config.prototype)queue.push(config.prototype.preview_root,config.prototype.verification_ref);
   if(config.prototype?.profile==='H2')queue.push(config.prototype.source_root,config.prototype.lock_ref);
   const symbolic=config.reference_map || {};
   const enqueue=ref=> { if(symbolic[ref])queue.push(symbolic[ref]); else if(/^https?:\/\//i.test(ref))return; else if(ref.startsWith('evidence.'))throw new TypeError(`未解析 evidence ID: ${ref}`); else if(ref.includes('/') || /\.(?:md|yaml|json|html|png|txt|log)$/.test(ref))queue.push(ref); };
   function refs(value,key='') {
     if(Array.isArray(value)) { if(key==='evidence_refs') value.forEach(enqueue); else value.forEach(v=>refs(v,key)); }
-    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref','decision_reuse_ref','continuation_ref','plan_continuation_ref','scope_ref','subject_ref','delivery_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
+    else if(value && typeof value==='object') for(const [k,v]of Object.entries(value)) { if(['approval_ref','persisted_ref','user_decision_ref','decision_reuse_ref','continuation_ref','plan_continuation_ref','scope_ref','subject_ref','delivery_ref','review_ref'].includes(k)&&typeof v==='string')enqueue(v); else if(k==='ref'&&typeof v==='string'&&!/^[a-z]+:\/\//i.test(v))enqueue(v); else refs(v,k); }
   }
   let totalBytes = 0;
   while(queue.length) {
@@ -421,7 +442,7 @@ export async function importBundle({bundle,targetRoot}) {
       const equal=actual&&['term','meaning','english_identifier','context_id','forbidden_aliases'].every(key=>own(expected[key],actual[key]));
       terms.push({operation,term_ref:expected.term_ref,expected,current:actual||null,status:operation==='deprecated'?(actual?'pending':'matched'):(equal?'matched':actual?'conflict':'pending')});
     }
-    const rows=[...b.indexes.rules.map(x=>({source_id:x.rule_id,source_digest:x.source_digest,kind:'rule'})),...b.indexes.scenarios.filter(x=>x.critical).map(x=>({source_id:x.scenario_id,source_digest:x.source_digest,kind:'scenario'}))].map(x=>({...x,disposition:'pending',tactical_refs:[],test_seam_refs:[],evidence_refs:[],dependent_slice_refs:[],dependency_status:'unknown'}));
+    const rows=[...b.indexes.rules.map(x=>({source_id:x.rule_id,source_digest:x.source_digest,kind:'rule'})),...b.indexes.scenarios.filter(x=>x.critical).map(x=>({source_id:x.scenario_id,source_digest:x.source_digest,kind:'scenario'})),...(b.business?.tickets||[]).map(x=>({source_id:x.id,source_digest:x.source_digest,kind:'business-ticket',business_ticket_ref:`${rel}/package/payload/files/${x.ref}`}))].map(x=>({...x,disposition:'pending',tactical_refs:[],test_seam_refs:[],evidence_refs:[],dependent_slice_refs:[],dependency_status:'unknown'}));
     mkdirSync(path.dirname(dest),{recursive:true});const stage=mkdtempSync(path.join(path.dirname(dest),'.import-staging-'));
     try {
       cpSync(b.root,path.join(stage,'package'),{recursive:true,errorOnExist:true,force:false});
@@ -452,13 +473,13 @@ export async function importBundle({bundle,targetRoot}) {
         schema(receipt,fromDelivery?'.template-spec/process/schemas/strategic-handoff-import-receipt-v3.schema.json':'.template-spec/process/schemas/strategic-handoff-import-receipt.schema.json');
         write(stage,'import-receipt.json',json(receipt));
         write(stage,'context-reconciliation-draft.json',json({schema_version:2,status:'draft',import_receipt_ref:`${rel}/import-receipt.json`,target_context_digest:context.document_digest,route_ids:selected.map(route=>route.route_id),terms}));
-        write(stage,'upstream-change-impact.json',json({schema_version:2,previous_bundle:b.manifest.previous_bundle,routes:selected.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation'})),policy:'mark-only-known-dependent-contracts-stale; unknown-dependency-or-design-basis-change-blocks-all'}));
+        write(stage,'upstream-change-impact.json',json({schema_version:2,previous_bundle:b.manifest.previous_bundle,...(b.business?{business_ticket_set_ref:`${rel}/package/payload/files/${b.handoff.source.business_ticket_set_ref.persisted_ref}`,business_ticket_status:'requires-current-source-and-dependency-reconciliation',business_ticket_ids:b.business.tickets.map(t=>t.id)}:{}),routes:selected.map(route=>({route_id:route.route_id,capability:route.capability,activation:route.activation,changed_source_ids:[...b.changes.updated,...b.changes.removed],added_source_ids:b.changes.added,status:'requires-lifecycle-reconciliation'})),policy:'mark-only-known-dependent-contracts-stale; unknown-dependency-or-design-basis-change-blocks-all'}));
         const backendRoute=b.handoff.consumer_routes.find(route=>route.capability==='backend-technical-design');
         const frontendRoute=b.handoff.consumer_routes.find(route=>route.capability==='frontend-engineering-design');
         const coordinationRoute=b.handoff.consumer_routes.find(route=>route.capability==='delivery-coordination');
         if(capabilities.includes('backend-technical-design')&&backendRoute.activation!=='not-applicable')write(stage,'backend-technical-traceability-draft.json',json({schema_version:2,route_id:backendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows}));
         if(capabilities.includes('frontend-engineering-design')&&frontendRoute.activation!=='not-applicable'){
-          const preflight={schema_version:b.handoff.schema_version===5?2:1,status:'draft',route_id:frontendRoute.route_id,capability:frontendRoute.capability,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,context_reconciliation_ref:'',...(b.handoff.schema_version===5?{ui_baseline_kind:uiBaselineKind(b.handoff),ui_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}:{visual_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}),source_rule_refs:rows.map(row=>row.source_id),backend_dependency:{mode:backendRoute.activation==='not-applicable'?'not-applicable':'required',route_id:backendRoute.route_id,...(backendRoute.activation==='not-applicable'?{reason:backendRoute.reason,impact_refs:backendRoute.impact_refs,evidence_refs:backendRoute.evidence_refs}:{})},ready_for_agent:false};
+          const preflight={schema_version:b.handoff.schema_version===5?2:1,status:'draft',route_id:frontendRoute.route_id,capability:frontendRoute.capability,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,context_reconciliation_ref:'',...(b.handoff.schema_version===5?{ui_baseline_kind:uiBaselineKind(b.handoff),ui_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}:{visual_baseline_ref:`${rel}/package/payload/files/${uiBaselineRef(b.handoff).persisted_ref}/${uiBaselineRef(b.handoff).manifest_ref}`}),source_rule_refs:rows.filter(row=>row.kind!=='business-ticket').map(row=>row.source_id),backend_dependency:{mode:backendRoute.activation==='not-applicable'?'not-applicable':'required',route_id:backendRoute.route_id,...(backendRoute.activation==='not-applicable'?{reason:backendRoute.reason,impact_refs:backendRoute.impact_refs,evidence_refs:backendRoute.evidence_refs}:{})},ready_for_agent:false};
           schema(preflight,b.handoff.schema_version===5?'.template-spec/process/schemas/frontend-strategic-preflight-v2.schema.json':'.template-spec/process/schemas/frontend-strategic-preflight.schema.json');
           write(stage,'frontend-strategic-preflight-draft.json',json(preflight));write(stage,'frontend-traceability-draft.json',json({schema_version:1,route_id:frontendRoute.route_id,import_receipt_ref:`${rel}/import-receipt.json`,bundle_digest:b.manifest.bundle_digest,rows:rows.map(({tactical_refs,test_seam_refs,...row})=>({...row,frontend_case_refs:[]}))}));
         }

package/template/scripts/lib/structured-assets.mjs

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { parseDocument, YAMLMap, YAMLSeq } from '../vendor/yaml.mjs';
+import { validateJsonSchema } from './json-schema.mjs';
+
+export const TOOL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const ASSET_KINDS = Object.freeze(['checkpoint', 'domain-strategy', 'stage-decision-package', 'task-package', 'approval-record']);
+export const byteDigest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+export const canonicalValue = value => Array.isArray(value) ? value.map(canonicalValue) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonicalValue(value[key])])) : value;
+export const semanticDigest = value => byteDigest(JSON.stringify(canonicalValue(value)));
+export const serializeAsset = value => `${JSON.stringify(canonicalValue(value), null, 2)}\n`;
+const isMap = node => node instanceof YAMLMap;
+const isSeq = node => node instanceof YAMLSeq;
+const isScalar = node => node && Object.hasOwn(node, 'value');
+
+export function assetComments(bytes) {
+  const doc = parseDocument(String(bytes), { uniqueKeys: true }), result = [];
+  function visit(node, location) {
+    if (!node || typeof node !== 'object') return;
+    for (const key of ['comment', 'commentBefore']) if (node[key]) result.push({ location, text: node[key] });
+    if (node.contents) visit(node.contents, '<root>');
+    if (isMap(node)) for (const pair of node.items) { visit(pair.key, `${location}.${pair.key?.value}`); visit(pair.value, `${location}.${pair.key?.value}`); }
+    if (isSeq(node)) node.items.forEach((item, index) => visit(item, `${location}[${index}]`));
+  }
+  visit(doc, '<document>'); return result;
+}
+
+/** JSON syntax is strict; the YAML AST supplies duplicate-key and lossless-type checks. */
+export function parseAsset(bytes, file = 'asset.yaml') {
+  const source = Buffer.isBuffer(bytes) ? new TextDecoder('utf-8', { fatal: true }).decode(bytes) : String(bytes);
+  if (/\.json$/i.test(file)) JSON.parse(source);
+  const doc = parseDocument(source, { uniqueKeys: true, maxAliasCount: 0, intAsBigInt: true });
+  if (doc.errors.length || doc.warnings.length) throw new TypeError(`ASSET_PARSE: ${file}: ${(doc.errors[0] || doc.warnings[0]).message}`);
+  function visit(node) {
+    if (!node) return;
+    if (node.anchor || node.tag) throw new TypeError(`ASSET_TYPE: anchors/tags are unsupported: ${file}`);
+    if (isMap(node)) for (const pair of node.items) {
+      if (!isScalar(pair.key) || typeof pair.key.value !== 'string') throw new TypeError(`ASSET_TYPE: keys must be strings: ${file}`);
+      visit(pair.value);
+    }
+    else if (isSeq(node)) node.items.forEach(visit);
+    else if (isScalar(node)) {
+      if (typeof node.value === 'bigint') {
+        const number = Number(node.value);
+        if (!Number.isSafeInteger(number)) throw new TypeError(`ASSET_TYPE: unsafe integer: ${file}`);
+        node.value = number;
+      }
+      if (typeof node.value === 'number' && !Number.isFinite(node.value)) throw new TypeError(`ASSET_TYPE: non-finite number: ${file}`);
+      if (typeof node.value === 'number' && Number.isInteger(node.value) && !Number.isSafeInteger(node.value)) throw new TypeError(`ASSET_TYPE: unsafe integer: ${file}`);
+    } else throw new TypeError(`ASSET_TYPE: aliases are unsupported: ${file}`);
+  }
+  visit(doc.contents);
+  const value = doc.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`ASSET_TYPE: root must be an object: ${file}`);
+  return value;
+}
+
+export function assetSchema(kind, value, root = TOOL_ROOT) {
+  if (!ASSET_KINDS.includes(kind)) throw new TypeError(`ASSET_KIND: ${kind}`);
+  if (['domain-strategy', 'stage-decision-package'].includes(kind)) {
+    if (![2, 3].includes(value.schema_version)) throw new TypeError('migration-required: unsupported strategy schema_version');
+    const authoring = path.join(root, `.agents/skills/yss-stage-decision/references/${kind}.schema.json`);
+    return fs.existsSync(authoring) ? authoring : path.join(root, `.template-spec/process/schemas/${kind}-reading.schema.json`);
+  }
+  const name = { checkpoint: 'lifecycle-checkpoint', 'task-package': 'digital-human-task-package', 'approval-record': value.kind === 'review-bundle' ? 'review-bundle' : 'approval-record' }[kind];
+  return path.join(root, `.template-spec/process/schemas/${name}.schema.json`);
+}
+
+export function validateAssetStructure(value, kind, { schemaRoot = TOOL_ROOT } = {}) {
+  const schemaPath = assetSchema(kind, value, schemaRoot);
+  validateJsonSchema(value, schemaPath, { cwd: schemaRoot });
+  return { kind, schema_version: value.schema_version, schema: path.relative(schemaRoot, schemaPath), semantic_digest: semanticDigest(value), execution_authorization: 'not-evaluated' };
+}
+
+export function readAsset(file, kind, options = {}) {
+  const bytes = fs.readFileSync(file), value = parseAsset(bytes, file);
+  validateAssetStructure(value, kind, options);
+  return { value, bytes, digest: byteDigest(bytes) };
+}

package/template/scripts/lib/task-package.mjs

@@ -1,4 +1,6 @@
 import { validateReadOnlyIntake } from './read-only-intake.mjs';
+import { parseAsset } from './structured-assets.mjs';
+import { assertAssetTransactionIdle } from './asset-transactions.mjs';
 import { assertTrackingEntry } from './stage-tracking.mjs';
 import { normalizeSliceContract } from './slice-contract.mjs';
 import { assertSliceV3TaskPackage } from './slice-task-package.mjs';
@@ -56,7 +58,7 @@ function assertReadableEvidenceRef(value, field) {
 export function loadTaskPackage(filePath) {
   const sourcePath = path.resolve(filePath);
   if (!existsSync(sourcePath)) fail(`任务包不存在: ${filePath}`);
-  const value = parseYaml(readFileSync(sourcePath, "utf8"), "任务包");
+  const value = parseAsset(readFileSync(sourcePath), sourcePath);
   if (!value || typeof value !== "object" || Array.isArray(value)) fail("任务包必须是对象");
   return { value, sourcePath };
 }
@@ -136,7 +138,7 @@ function validateCommon(value, registry, lifecycle) {
   return workUnit;
 }
 
-function validateContract(value, registry, lifecycle) {
+function validateContract(value, registry, lifecycle, { history = false } = {}) {
   const contract = value.contract;
   const implementationWorkUnit = "work-unit.slice-implementation";
   const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
@@ -160,6 +162,7 @@ function validateContract(value, registry, lifecycle) {
     if (!existsSync(checkpointPath)) fail(`维护 checkpoint 不存在: ${contract.maintenance_ref}`);
     const checkpoint = maintenanceValidators.loadMaintenanceCheckpoint(contract.maintenance_ref);
     maintenanceValidators.validateMaintenanceCheckpoint(checkpoint, {
+      history,
       allowPendingReview: value.execution_state === "Reviewer" && value.workflow_status !== "resolved"
     });
     if (checkpoint.schema_version === 2 && value.execution_state === "Reviewer") {
@@ -204,7 +207,7 @@ function validateContract(value, registry, lifecycle) {
   if (value.execution_state === "Worker") assertImplementationDecision({ slice_contract_ref: contract.slice_contract_ref, vertical_slice_ticket_ref: slice.lifecycle_refs.ticket, user_decisions: value.user_decisions });
 }
 
-export function validateTaskPackage(value, { rolesDoc, lifecycleDoc, root = ROOT, runDir } = {}) {
+function validateTaskPackageInternal(value, { rolesDoc, lifecycleDoc, root = ROOT, runDir, history = false } = {}) {
   validateTaskPackageSchema(value);
   if (value.schema_version === 2) {
     enforceHarnessTaskScope(value, { root });
@@ -220,10 +223,21 @@ export function validateTaskPackage(value, { rolesDoc, lifecycleDoc, root = ROOT
   const registry = rolesDoc || loadDigitalHumanRoles();
   const lifecycle = lifecycleDoc || loadRegistry();
   validateCommon(value, registry, lifecycle);
-  validateContract(value, registry, lifecycle);
+  validateContract(value, registry, lifecycle, { history });
   return value;
 }
 
+export function validateTaskPackage(value, options = {}) {
+  assertAssetTransactionIdle(ROOT);
+  return validateTaskPackageInternal(value, {...options, history:false});
+}
+
+export function validateHistoricalMaintenanceTaskPackage(value) {
+  if(repositoryMode !== 'template-source' || value.schema_version !== 1 || value.contract?.kind !== 'template-maintenance')fail('历史兼容仅适用于模板维护 schema v1 任务包');
+  validateTaskPackageInternal(value, {history:true});
+  return {status:'historical-only',execution_authorization:'not-evaluated'};
+}
+
 export function generateTaskPackageDefaults(roleId, overrides = {}, { rolesDoc } = {}) {
   const defaults = taskPackageDefaults(roleId, rolesDoc || loadDigitalHumanRoles());
   return {

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

@@ -0,0 +1,33 @@
+// Synthetic test sources only; never use for real approval records.
+import {mkdirSync,writeFileSync,readFileSync} from "node:fs";
+import path from "node:path";
+import {decisionDigest,requestDigest,renderDecisionRequest} from "../user-decision.mjs";
+export function buildDecisionFixture(root, { boundary = "gate.spec-baseline-approved", scope = ["feature.demo"], subjectRef, subjectContent = "冻结业务基线 v1\n", extraItems = [] } = {}) {
+  mkdirSync(root, { recursive: true });
+  const write = (name, value) => {
+    const ref = path.join(root, name);
+    writeFileSync(ref, typeof value === "string" ? value : JSON.stringify(value, null, 2));
+    return ref;
+  };
+  const subject = subjectRef || write("subject.md", subjectContent);
+  const capture = (name, principal, actor, sentAt, text, kind = "session-export", replyTo = null) => {
+    const value = { source_kind: kind, messages: [{ id: name, principal_ref: principal, actor_kind: actor, sent_at: sentAt, text, ...(replyTo ? { reply_to: replyTo } : {}), original_ref: `test-only://${name}` }] };
+    const ref = write(`${name}.json`, value);
+    return { kind, ref, digest: decisionDigest(readFileSync(ref)), message_id: name };
+  };
+  const record = { schema_version: 1, kind: "user-decision", request: {
+    id: "request.demo", requester_ref: "person.requester",
+    requester_source: capture("requester", "person.requester", "biological-human", "2026-09-05T01:00:00Z", "请整理可审阅的功能方案。"),
+    items: [{ id: "decision.demo", boundary, title: "确认本次范围", subject: { ref: subject, version: "v1", digest: decisionDigest(readFileSync(subject)) }, basis: [], scope, changes: "新增已列明范围", risks: [], recommendation: "批准上述范围", next_actions: ["进入下一工作单元"], responder_ref: "person.requester" }, ...extraItems],
+  }, responses: [] };
+  const present = () => { record.request.presented_source = capture("presentation", "agent.orchestrator", "digital-human", "2026-09-05T01:02:00Z", renderDecisionRequest(record.request)); };
+  present();
+  const respond = ({ principal = "person.requester", actor = "biological-human", text = "同意", decision = "approved", selection = record.request.items.length === 1 ? "single" : "explicit-all", itemIds = record.request.items.map((item) => item.id), approvedScope = record.request.items.flatMap((item) => item.scope), time = "2026-09-05T01:03:00Z", name = `reply-${record.responses.length}` } = {}) => {
+    record.responses.push({ source: capture(name, principal, actor, time, text, "session-export", JSON.parse(readFileSync(record.request.presented_source.ref, "utf8")).messages[0].original_ref), principal_ref: principal, responded_at: time, text, request_digest: requestDigest(record.request), selection, item_ids: itemIds, decision, approved_scope: approvedScope });
+  };
+  respond({ text: extraItems.length ? "同意以上全部事项" : "同意" });
+  const ref = path.join(root, "decision.json");
+  const save = () => writeFileSync(ref, JSON.stringify(record, null, 2));
+  save();
+  return { record, ref, save, write, capture, present, respond, requirement: { boundary, subject_ref: subject, scope: [...scope], user_decision_ref: ref } };
+}

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

@@ -9,7 +9,7 @@ export function assertApprovalUserDecision(record, roles, options = {}) {
   const policy = roles.user_decision_policy;
   const io = decisionIO(options);
   if (record.continuation_ref) return assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,continuation_ref:record.continuation_ref}, {...options,rolesDoc:roles});
-  if (policy.required_capabilities?.some(id => id !== DECISION_REUSE_CAPABILITY)) fail('接收工具不支持源用户决定策略，请升级');
+  if (policy.required_capabilities?.some(id => ![DECISION_REUSE_CAPABILITY,'business-ticket-approval-v1'].includes(id))) fail('接收工具不支持源用户决定策略，请升级');
   if (!record.decision_reuse_ref) return assertUserDecisionRequirement({boundary:record.gate_id,subject_ref:record.subject_ref,scope:record.approval_scope,user_decision_ref:record.user_decision_ref}, {...options,rolesDoc:roles});
   if (record.gate_id !== 'gate.strategic-design-handoff-approved' || !policy.required_capabilities?.includes(DECISION_REUSE_CAPABILITY)) fail('未登记的复用边界或能力');
   const reuse = io.document(record.decision_reuse_ref);

package/template/scripts/lifecycle-status

@@ -1,14 +1,27 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import path from 'node:path';
+import { checkProjectGovernance } from './lib/project-governance.mjs';
 import { lifecycleStatus } from './lib/lifecycle-status.mjs';
+import { renderLifecycleStatus } from './lib/lifecycle-presentation.mjs';
 
 try {
-  const { values } = parseArgs({ strict: true, options: { root: { type: 'string' }, checkpoint: { type: 'string' }, task: {type: 'string'} } });
+  const { values } = parseArgs({ strict: true, options: { root: { type: 'string' }, checkpoint: { type: 'string' }, task: {type: 'string'}, preflight: {type:'boolean'}, help:{type:'boolean'}, format: {type:'string', default:'json'} } });
+  if (!['json', 'text'].includes(values.format)) throw Error('--format 仅支持 json 或 text');
+  if (values.preflight && values.format === 'text') throw Error('--preflight 使用 JSON 诊断；中文状态阅读请单独调用 --format text');
+  if(values.help)process.stdout.write('用法: scripts/lifecycle-status --root <项目> [--checkpoint <根相对路径>] [--task <任务包>] [--preflight] [--format json|text]\n普通查询不执行预检；--preflight 复验当前证据，仅提供恢复动作，不批准或派发。普通查询退出码保持 0/1；预检 0=通过、1=失败、2=输入或能力异常。\n');
+  else if(values.preflight) {
+    if(!values.checkpoint&&!values.task)throw new Error('--preflight 必须指定 --checkpoint 或 --task');
+    const {report,exitCode}=checkProjectGovernance({root:path.resolve(values.root??'.'),checkpointRef:values.checkpoint,taskRef:values.task,recovery:true});
+    process.stdout.write(JSON.stringify(report,null,2)+'\n');process.exitCode=exitCode;
+  } else {
   const result = lifecycleStatus({ root: path.resolve(values.root ?? '.'), checkpointRef: values.checkpoint, taskPackageRef: values.task });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(values.format === 'text' ? renderLifecycleStatus(result) : `${JSON.stringify(result, null, 2)}\n`);
   if (result.blockers.length) process.exitCode = 1;
+  }
 } catch (error) {
   process.stdout.write(`${JSON.stringify({ schema_version: 1, read_only: true, blockers: [error.message], owner: '未登记', next_action: `核查状态输入：${error.message}`, execution_authorization: 'not-evaluated', verification_scope: [{ id: 'status-input', status: 'failed', refs: [], reason: error.message }], diagnostics: [{ code: 'status-input-invalid', severity: 'error', message: error.message, source_ref: null, owner: '未登记', recovery: '修复输入后重新读取状态' }], next_step: { action_type: 'repair', command: null, input_refs: [], prerequisites: ['提供有效项目根和 checkpoint 引用'] } }, null, 2)}\n`);
-  process.exitCode = 1;
+  process.exitCode = process.argv.includes('--preflight') ? 2 : 1;
 }
+
+process.stdout.on('error',()=>{process.exitCode=process.argv.includes('--preflight')?2:1;});

package/template/scripts/project-ci

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { planProjectCi, applyProjectCi } from './lib/project-ci-install.mjs';
+import { checkProjectGovernance } from './lib/project-governance.mjs';
+
+try {
+  const {values,positionals}=parseArgs({allowPositionals:true,options:{root:{type:'string',default:'.'},provider:{type:'string',default:'github'},branch:{type:'string'},plan:{type:'string'},'additional-path':{type:'string',multiple:true},base:{type:'string'},recover:{type:'boolean'},json:{type:'boolean'},help:{type:'boolean'}}});
+  if(values.help){process.stdout.write('用法: scripts/project-ci plan --provider github --root <项目> [--branch main] [--additional-path <根相对路径>]\n      scripts/project-ci apply --root <项目> --plan <plan.json>\n      scripts/project-ci apply --root <项目> --recover\n      scripts/project-ci check --root <项目> [--base <40位commit>] --json\nplan/check 只读，apply 仅显式管理自身工作流；不改远端或批准。退出码 0=通过/计划完成，1=检查失败/冲突，2=输入/能力/执行异常。\n');}
+  else {
+    if(positionals.length!==1||!['plan','apply','check'].includes(positionals[0]))throw new Error('需要 plan、apply 或 check；参见 --help');
+    const root=path.resolve(values.root);let result;
+    if(positionals[0]==='plan'){result=planProjectCi({root,provider:values.provider,branch:values.branch,additionalPaths:values['additional-path']});if(result.conflicts.length)process.exitCode=1;}
+    if(positionals[0]==='apply'){if(!values.recover&&!values.plan)throw new Error('apply 需要 --plan');result=applyProjectCi({root,recover:values.recover,plan:values.plan?JSON.parse(fs.readFileSync(values.plan,'utf8')):undefined});}
+    if(positionals[0]==='check'){const check=checkProjectGovernance({root,base:values.base});result=check.report;process.exitCode=check.exitCode;}
+    process.stdout.write(JSON.stringify(result,null,2)+'\n');
+  }
+}catch(error){process.stdout.write(JSON.stringify({schema_version:1,status:'error',read_only:process.argv[2]!=='apply',error:error.message})+'\n');process.stderr.write(error.message+'\n');process.exitCode=error.exitCode||2;}
+process.stdout.on('error',error=>{process.stderr.write(`输出失败: ${error.message}\n`);process.exitCode=2;});

package/template/scripts/project-ci-transition

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Loaded only for an actual transition. Stage-selective instances need not install
+// future stage capabilities until a checkpoint claims their transition.
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readDocument, safeFile } from './lib/governance-io.mjs';
+try {
+  if(process.argv.length!==3)throw new Error('需要 checkpoint 根相对路径');
+  const root=process.cwd(),ref=process.argv[2],checkpoint=readDocument(root,ref);
+  const {validateNextRoute}=await import(pathToFileURL(safeFile(root,'scripts/lib/lifecycle-transition.mjs')).href);
+  const result=validateNextRoute(checkpoint.stage_trace?.completed_work_unit,checkpoint.next_work_unit,{...checkpoint,checkpoint_ref:ref},{root});
+  process.stdout.write(JSON.stringify(result)+'\n');if(result.result!=='allowed')process.exitCode=1;
+}catch(error){process.stderr.write(`${error.code||''} ${error.message}\n`);process.exitCode=/MODULE_NOT_FOUND/.test(error.code||'')?2:1;}

package/template/scripts/query-lifecycle-context

@@ -5,6 +5,7 @@ import { queryLifecycleContext } from "./lib/lifecycle-context-query.mjs";
 try {
   const { values } = parseArgs({
     options: {
+      help: {type:'boolean'},
       mode: { type: "string" },
       stage: { type: "string" },
       "work-unit": { type: "string" },
@@ -12,6 +13,8 @@ try {
     },
     strict: true,
   });
+  if(values.help)process.stdout.write('用法: scripts/query-lifecycle-context [--mode route] [--stage stage.plan] [--work-unit work-unit.plan-opportunity] [--include <资产>]\n只读查询，不证明批准；退出码 0=查询完成、1=输入或执行失败。\n');
+  else {
   const result = queryLifecycleContext({
     mode: values.mode,
     stageId: values.stage,
@@ -19,6 +22,7 @@ try {
     include: values.include ?? [],
   });
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
 } catch (error) {
   process.stderr.write(`${error.message}\n`);
   process.exitCode = 1;

package/template/scripts/stage-tracking

@@ -21,5 +21,6 @@ try {
     result = command === 'check' ? checkTracking(root, values.checkpoint) : planTracking(root, { checkpoint_ref: values.checkpoint, items: input, refresh: values.refresh });
     if (result.status === 'blocked' || (result.status === 'missing-checkpoint' && result.enabled)) process.exitCode = 1;
   }
+  if(result.reading_update?.status==='failed')process.exitCode=1;
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }