create-yss-spec 3.4.9 → 3.5.0

package/template/scripts/dispatch-slice-task

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseSliceYaml } from './lib/slice-contract.mjs';
+import { compileSliceTaskPackage } from './lib/slice-task-package.mjs';
+try {
+  const { values } = parseArgs({ options: { root: { type: 'string' }, input: { type: 'string' } } });
+  if (!values.root || !values.input) throw new TypeError('用法: dispatch-slice-task --root <project> --input <task-input.yaml>');
+  const input = parseSliceYaml(readFileSync(values.input));
+  const result = compileSliceTaskPackage(input.binding, { ...input, root: path.resolve(values.root) });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/scripts/lib/api-contract-decision.mjs

@@ -1,4 +1,6 @@
-import { readFileSync } from "node:fs";
+import {readContractSource} from './contract-source.mjs';
+import { readFileSync, withValidationPhase } from "./validation-phase.mjs";
+import { parseSliceYaml } from "./slice-contract.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "../vendor/yaml.mjs";
@@ -15,15 +17,18 @@ const readBound = (root, ref, label) => {
 };
 const requireDigest = (asset, expected) => { if (asset.digest !== expected) fail(`${asset.label}摘要漂移`); };
 
-export function validateApiContractDecision(binding, { root = TEMPLATE_ROOT } = {}) {
+export function validateApiContractDecision(binding, options = {}) {return withValidationPhase({root:options.root||TEMPLATE_ROOT,purpose:'api-decision',slice_id:binding?.ref,readOnly:true},()=>validate(binding,options));}
+function validate(binding, { root = TEMPLATE_ROOT } = {}) {
   if (!binding || !binding.ref || !binding.version || !binding.digest || !["required", "not-applicable"].includes(binding.impact)) fail("缺少 API Contract Decision 当前版本绑定");
   const projectRoot = path.resolve(root);
   const decisionAsset = readBound(projectRoot, binding.ref, "API Contract Decision");
   requireDigest(decisionAsset, binding.digest);
   const document = parseDocument(decisionAsset.bytes.toString("utf8"), { uniqueKeys: true, maxAliasCount: 0 });
   if (document.errors.length) fail(`API Contract Decision 无法解析: ${document.errors[0].message}`);
-  const decision = document.toJS({ maxAliasCount: 0 });
-  validateJsonSchema(decision, SCHEMA, { cwd: TEMPLATE_ROOT, label: "API Contract Decision v1" });
+  const original = parseSliceYaml(decisionAsset.bytes);
+  validateJsonSchema(original, original.schema_version===2?SCHEMA.replace(".schema", "-v2.schema"):SCHEMA, { cwd: TEMPLATE_ROOT, label: "API Contract Decision" });
+  if(original.status!=="approved")fail("API Contract Decision 必须经生命周期批准为 approved");
+  const decision={...structuredClone(original),current_version:true}; // Derived only after schema and current raw binding checks; never persisted.
   if (decision.decision_version !== binding.version || decision.impact !== binding.impact) fail("API Contract Decision 版本或影响结论与合同不一致");
   requireDigest(readBound(projectRoot, decision.assessment_ref, "API 影响评估"), decision.assessment_digest);
   for (const ref of decision.evidence_refs) readBound(projectRoot, ref, "API Decision 证据");
@@ -40,6 +45,12 @@ export function validateApiContractDecision(binding, { root = TEMPLATE_ROOT } =
   const reviewRecord = reviewDocument.toJS({ maxAliasCount: 0 });
   if (reviewRecord?.result !== "approved" || !Array.isArray(reviewRecord.blocking_findings) || reviewRecord.blocking_findings.length > 0) fail("OpenAPI Draft Review 实际记录未批准或仍有阻断项");
   if (reviewRecord.draft_ref !== decision.openapi.ref || reviewRecord.draft_digest !== decision.openapi.digest) fail("OpenAPI Draft Review 实际记录未绑定当前权威 YAML");
+  if (!Array.isArray(reviewRecord.evidence_refs) || !reviewRecord.evidence_refs.length) fail("OpenAPI Draft Review 缺少实际证据");
+  for (const ref of reviewRecord.evidence_refs) readBound(projectRoot, ref, "OpenAPI Draft Review 实际证据");
+  if(original.schema_version===2){
+    decision.draft_review={...decision.draft_review,result:reviewRecord.result,blocking_findings:reviewRecord.blocking_findings,draft_ref:reviewRecord.draft_ref,draft_digest:reviewRecord.draft_digest,evidence_refs:reviewRecord.evidence_refs};
+    decision.freeze={...decision.freeze,draft_ref:decision.openapi.ref,draft_digest:decision.openapi.digest};
+  }
   for (const ref of decision.draft_review.evidence_refs) readBound(projectRoot, ref, "OpenAPI Draft Review 证据");
   const validated = validateOpenApiDraftValidationRecord(validation.file, { root: projectRoot });
   if (validated.record.draft.ref !== decision.openapi.ref || validated.draftDigest !== decision.openapi.digest) fail("OpenAPI Validation 未绑定当前权威 YAML");
@@ -47,3 +58,33 @@ export function validateApiContractDecision(binding, { root = TEMPLATE_ROOT } =
   if (decision.freeze.version !== decision.openapi.version || decision.freeze.draft_ref !== decision.openapi.ref || decision.freeze.draft_digest !== decision.openapi.digest) fail("OpenAPI Freeze 未绑定当前权威 YAML 版本和摘要");
   return { decision, openapi: decision.openapi, binding: { ref: binding.ref, version: binding.version, digest: binding.digest, impact: decision.impact } };
 }
+
+/** Source selectors contain business choices; digests are always derived from original bytes. */
+export function prepareApiContractDecision(input,{root=TEMPLATE_ROOT}={}) {
+ return withValidationPhase({root,purpose:'api-prepare',slice_id:input.decision_id,readOnly:true},()=>{
+  if(input.schema_version!==undefined&&input.schema_version!==2)fail('旧 schema 必须通过显式 migrate 迁移');
+  if(input.kind!==undefined&&input.kind!=='api-contract-decision')fail('来源 kind 与 API 决定冲突');
+  const allowed=new Set(['schema_version','kind','decision_id','decision_version','status','impact','assessment_ref','assessment_digest','evidence_refs','reason','openapi','validation_record','draft_review','freeze']);
+  for(const key of Object.keys(input))if(!allowed.has(key))fail(`未分类约束需人工处理: ${key}`);
+  if(input.status&&input.status!=='draft')fail('准备器不能创建批准身份或更新已批准合同');
+  const result=structuredClone(input);Object.assign(result,{schema_version:2,kind:'api-contract-decision',status:'draft'});
+  const conflicts=[];
+  const bind=(value,label)=>{try{return {...value,...readContractSource(value,{root}).binding};}catch(error){conflicts.push({field:label,source_ref:value.ref,reason:error.message,conflicts:error.conflicts||[],recovery:'核对双方来源并补齐当前文件后重新准备'});return value;}};
+  result.assessment_digest=bind({ref:input.assessment_ref,...(input.assessment_digest?{digest:input.assessment_digest}:{})},'API 影响评估').digest;
+  for(const key of ['openapi','validation_record','draft_review'])if(result[key])result[key]=bind(result[key],key);
+  for(const ref of result.evidence_refs||[])try{readBound(root,ref,'API 决定证据');}catch(error){conflicts.push({field:'evidence_refs',source_ref:ref,reason:error.message,recovery:'补齐当前证据后重新准备'});}
+  if(conflicts.length)throw Object.assign(new TypeError(conflicts.map(item=>`${item.field}: ${item.reason}; 恢复: ${item.recovery}`).join('\n')),{code:'API_SOURCE_CONFLICT',conflicts});
+  validateJsonSchema(result,SCHEMA.replace('.schema','-v2.schema'),{label:'API Contract Decision v2 草案'});
+  return result;
+ });
+}
+export function migrateApiContractDecision(binding,{root=TEMPLATE_ROOT,version}={}) {
+ return withValidationPhase({root,purpose:'api-migrate',slice_id:binding?.ref,readOnly:true},()=>{
+  const validated=validateApiContractDecision(binding,{root}),old=validated.decision;
+  if(old.schema_version!==1)fail('显式迁移只接受 v1');
+  if(!/^v[1-9][0-9]*$/.test(version)||BigInt(version.slice(1))<=BigInt(old.decision_version.slice(1)))fail('迁移必须选择新的递增决定版本');
+  const result=structuredClone(old);result.schema_version=2;result.decision_version=version;result.status='draft';delete result.current_version;
+  if(result.draft_review){result.evidence_refs=[...new Set([...result.evidence_refs,...result.draft_review.evidence_refs])];result.draft_review={ref:result.draft_review.ref,digest:result.draft_review.digest};result.freeze={version:result.freeze.version,frozen_at:result.freeze.frozen_at};}
+  return prepareApiContractDecision(result,{root});
+ });
+}

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

@@ -1,5 +1,5 @@
 import { assertApprovalUserDecision } from './user-decision-reuse.mjs';
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import {

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

@@ -1,12 +1,15 @@
+import {validateJsonSchemas} from './json-schema.mjs';
+import { assertScopeSlice, assertScopeWorkUnit } from './lifecycle-execution-scope.mjs';
 import { selectSliceWorkUnit, normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import path from 'node:path';
-import { readFileSync } from 'node:fs';
+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 { assertImplementationDecision } from './user-decision.mjs';
 import { loadSkillRegistry } from './skill-registry.mjs';
 
+const primeCache=Symbol('approval-schema-prime');
 const contexts=new WeakMap();
 const gateId='gate.slice-contract-approved';
 const check=(ok,code,message)=>{if(!ok){const error=new TypeError(`${code}: ${message}`);error.code=code;throw error;}};
@@ -68,27 +71,52 @@ function executionBasis(verified,{allowCompilerDrift=false}={}) {
   return verified;
 }
 
+function primeApprovalSchemas(binding,root){
+  if(!inValidationPhase())return;
+  validationMemo(primeCache,JSON.stringify([root,binding]),()=>{
+    const jobs=[];
+    const add=(value,ref,formatChecker,errorStyle)=>jobs.push({value,schemaPath:path.join(ROOT,ref),formatChecker,errorStyle});
+    // Speculative shape checks never decide approval or change the original error order.
+    // Original consumers still validate every semantic and authorization rule below.
+    try{
+      const source=parseSliceYaml(readFileSync(safe(root,binding.ref))),raw=source.slice_contract||source;
+      if(raw.schema_version===3)add(raw,'docs/process/schemas/slice-implementation-contract-v3.schema.json',false,'verbose');
+      const approval=read(safe(root,binding.approval_ref));
+      if(approval.gates&&approval.human_review&&!approval.gate_id){
+        add(approval,'docs/process/schemas/lifecycle-checkpoint.schema.json',false,'verbose');
+        for(const requirement of approval.human_review.user_decisions||[])if(requirement.user_decision_ref&&!requirement.continuation_ref){const ref=path.isAbsolute(requirement.user_decision_ref)?path.relative(root,requirement.user_decision_ref):requirement.user_decision_ref;add(read(safe(root,ref)),'docs/process/schemas/user-decision.schema.json',true,'compact');}
+      }
+    }catch{/* The original consumer reports missing or invalid input with its existing code. */}
+    if(jobs.length)validateJsonSchemas(jobs);return true;
+  });
+}
 export function createApprovedExecutionContext(binding,options={}) {
+  primeApprovalSchemas(binding,path.resolve(options.root||process.cwd()));
   const verified=executionBasis(verifySliceContractApproval(binding,options));
-  selectSliceWorkUnit(verified.contract,options.work_unit_id);
+  assertScopeSlice(selectSliceWorkUnit(verified.contract,options.work_unit_id),{root:verified.root});
+  if(!options.readOnly)assertScopeWorkUnit('work-unit.slice-implementation',{root:verified.root});
   const context=Object.freeze({kind:'approved-slice-execution-context'});
-  contexts.set(context,{binding:verified.binding,root:verified.root,work_unit_id:options.work_unit_id,allowCompilerDrift:false});
+  contexts.set(context,{phase:validationPhaseToken(),binding:verified.binding,root:verified.root,work_unit_id:options.work_unit_id,allowCompilerDrift:false,readOnly:options.readOnly===true});
   return context;
 }
 
 /** A prior approved scope may authenticate bounded output while current compiler facts are recomputed. */
 export function createApprovedRecompilationContext(binding,options={}) {
-  const verified=executionBasis(verifySliceContractApproval(binding,options),{allowCompilerDrift:true});
-  selectSliceWorkUnit(verified.contract,options.work_unit_id);
+  const verified=executionBasis(verifySliceContractApproval(binding,options),{allowCompilerDrift:true,readOnly:options.readOnly===true});
+  assertScopeSlice(selectSliceWorkUnit(verified.contract,options.work_unit_id),{root:verified.root});
+  if(!options.readOnly)assertScopeWorkUnit('work-unit.slice-implementation',{root:verified.root});
   const context=Object.freeze({kind:'approved-slice-recompilation-context'});
-  contexts.set(context,{binding:verified.binding,root:verified.root,work_unit_id:options.work_unit_id,allowCompilerDrift:true});
+  contexts.set(context,{phase:validationPhaseToken(),binding:verified.binding,root:verified.root,work_unit_id:options.work_unit_id,allowCompilerDrift:true,readOnly:options.readOnly===true});
   return context;
 }
 
 /** Revalidate original bytes on every boundary; a serialized/caller-invented context is rejected. */
-export function assertApprovedExecutionContext(context,{root=process.cwd(),contract,architectureIdentity,architectureEvidence,technicalDesign,sliceId}={}) {
+export function assertApprovedExecutionContext(context,{root=process.cwd(),contract,architectureIdentity,architectureEvidence,technicalDesign,sliceId,readOnly=false}={}) {
   const saved=contexts.get(context);
   check(saved&&saved.root===path.resolve(root),'EXECUTION_CONTEXT_UNTRUSTED','只允许从当前原始 Slice 与本地批准生成的执行上下文');
+  check(!saved.phase||saved.phase===validationPhaseToken(),'EXECUTION_CONTEXT_EXPIRED','不能跨验证阶段复用批准上下文');
+  check(!saved.readOnly||readOnly,'EXECUTION_CONTEXT_READ_ONLY','只读检查上下文不能执行实现');
+  if(!readOnly)assertScopeWorkUnit('work-unit.slice-implementation',{root});
   const verified=executionBasis(verifySliceContractApproval(saved.binding,{root,contract}),{allowCompilerDrift:saved.allowCompilerDrift});
   const current=selectSliceWorkUnit(verified.contract,saved.work_unit_id),resolution=current.resolution;
   if(sliceId)check(current.slice_id===sliceId,'EXECUTION_SCOPE_CONFLICT','执行上下文属于另一切片');

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

@@ -37,9 +37,9 @@ export function validateArchitectureIdentity(identity, registry = loadSkillRegis
 }
 
 // Existing projects must present original on-disk evidence, not three copies supplied by a caller.
-export function verifyArchitectureEvidence(identity, evidence, { root, registry = loadSkillRegistry(), execution } = {}) {
+export function verifyArchitectureEvidence(identity, evidence, { root, registry = loadSkillRegistry(), execution, readOnly=false } = {}) {
   validateArchitectureIdentity(identity, registry);
-  if (identity.schema_version === 2) return verifyExistingArchitecture(identity, evidence, { root, registry, execution });
+  if (identity.schema_version === 2) return verifyExistingArchitecture(identity, evidence, { root, registry, execution, readOnly });
   if (!evidence?.engineering_baseline || !evidence?.repository_registration || !evidence?.manifest) throw new TypeError("缺少工程基线、仓库登记或 Manifest 架构证据");
   assertArchitectureAgreement(identity, evidence, registry);
   return { source_kind: "scaffold", bindings: evidence };

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

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { inspectBackendDelivery, openBackendDelivery } from './backend-delivery.mjs';
+import { validateBackendReview } from './backend-review.mjs';
+import { read, safe, hash, json, write, ensure, project } from './strategic-handoff-io.mjs';
+import { loadExecutionScope, TERMINAL_REF } from './lifecycle-execution-scope.mjs';
+
+async function inspect(root, record) {
+  project(root);
+  ensure(loadExecutionScope(root)?.scope_id === 'plan-to-backend', '需要 plan-to-backend 职责范围');
+  ensure(record.schema_version === 1 && record.kind === 'backend-delivery-terminal'
+    && record.business_completed === false && record.release_authorized === false, '后端终点不是业务完成或发布批准');
+  for (const name of ['delivery', 'review_state']) {
+    ensure(hash(readFileSync(safe(root, record[name]?.ref))) === record[name].digest, `${name} 原始字节变化`);
+  }
+  const state = read(safe(root, record.review_state.ref));
+  const { delivery } = await inspectBackendDelivery(root, record.delivery.ref);
+  ensure(state.review_input?.scope_kind === 'change' && state.review_input.slice_contract_ref === delivery.slice_contract.ref, '独立审查未绑定交付的 Slice');
+  ensure(validateBackendReview(state, { root }).status === 'passed', '后端交付需要当前独立审查');
+  const commit = execFileSync('git', ['-C', path.resolve(root, state.review_input.project_root), 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  ensure(state.review_input.review_mode === 'committed' && delivery.build.source_commit === commit, '终点需要与当前已提交审查候选一致的真实构建源码提交');
+  ensure(record.downstream && ['owner', 'ticket_ref', 'verification_plan', 'target_version'].every(key => typeof record.downstream[key] === 'string' && record.downstream[key].trim()), '终点缺少下游接收责任和待办');
+  return openBackendDelivery(safe(root, record.bundle_ref), bundle => {
+    ensure(record.bundle_digest === bundle.manifest.bundle_digest && bundle.manifest.delivery_ref === record.delivery.ref, '终点绑定的交付包不一致');
+    // A different valid package must not be used to close the current source.
+    for (const file of bundle.manifest.files) if (file.original_ref) {
+      ensure(hash(readFileSync(safe(root, file.original_ref))) === file.sha256, `包与当前源不同: ${file.original_ref}`);
+    }
+    return { result: 'backend-delivered', delivery_id: delivery.delivery_id, version: delivery.version,
+      bundle_digest: bundle.manifest.bundle_digest, next_work_unit: null, business_completed: false,
+      release_authorized: false, live_service_checked: false, downstream: record.downstream };
+  });
+}
+
+export async function verifyBackendDeliveryTerminal(root) {
+  return inspect(root, read(safe(root, TERMINAL_REF)));
+}
+
+/** This closes only the backend responsibility after real package and review validation. */
+export async function completeBackendDelivery(root, input) {
+  root = path.resolve(root);
+  const record = { ...input, schema_version: 1, kind: 'backend-delivery-terminal', business_completed: false, release_authorized: false };
+  ensure(!existsSync(path.join(root, TERMINAL_REF)), '终点已存在；只能复验，不覆盖旧终点');
+  const result = await inspect(root, record);
+  const bytes = json(record);
+  write(root, TERMINAL_REF, bytes);
+  try { await verifyBackendDeliveryTerminal(root); }
+  catch (error) { if (readFileSync(safe(root, TERMINAL_REF), 'utf8') === bytes) rmSync(safe(root, TERMINAL_REF)); throw error; }
+  return result;
+}

package/template/scripts/lib/backend-platform-provenance.mjs

@@ -1,6 +1,6 @@
 /** Version qualification binds executable sources and generated bytes, not Skill prose. */
 import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { readFileSync, readdirSync, lstatSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');

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

@@ -1,7 +1,7 @@
 import { assertSourceFingerprint } from "./backend-platform-provenance.mjs";
 /** Shared, exact backend platform selection. Catalog entries are maintenance-owned. */
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync } from './validation-phase.mjs';
 import path from "node:path";
 
 const CONTEXT_FILE = "CONTEXT.md";

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

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { resolveContextTermRefs, verifyContextSnapshot } from "./context-contract.mjs";

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

@@ -0,0 +1,22 @@
+import {readFileSync} from './validation-phase.mjs';
+import {safe,hash} from './strategic-handoff-io.mjs';
+import {parseSliceYaml} from './slice-contract.mjs';
+export function contractSourceMetadata(bytes){
+ const text=String(bytes),front=/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+ if(front)return parseSliceYaml(front[1]);
+ return /^\s*[{[]/.test(text)||/^[A-Za-z_][\w-]*:\s/m.test(text)&&!/^#/m.test(text)?parseSliceYaml(text):{};
+}
+/** Reads original bytes; returns derivable facts only. It never selects or approves a source. */
+export function readContractSource(selection,{root=process.cwd(),read=ref=>readFileSync(safe(root,ref))}={}){
+ const selected=typeof selection==='string'?{ref:selection}:selection;
+ if(!selected?.ref)throw new TypeError('来源选择缺少 ref');
+ const bytes=read(selected.ref),digest=hash(bytes),data=contractSourceMetadata(bytes);
+ const observed=data.requirement_version??data.version??data.contract_version??data.decision_version;
+ const conflicts=[];
+ const conflict=(field,before,after)=>conflicts.push({field,source_ref:selected.ref,before,after});
+ if(selected.digest&&selected.digest!==digest)conflict('digest',selected.digest,digest);
+ if(selected.version!==undefined&&observed!==undefined&&String(selected.version)!==String(observed))conflict('version',selected.version,observed);
+ if(conflicts.length){const error=new TypeError(conflicts.map(({field,before,after})=>`${field==='version'?'来源版本冲突':'来源冲突'} ${selected.ref}.${field}: supplied=${before}; observed=${after}; 恢复: 核对双方来源并显式选择当前版本`).join('\n'));Object.assign(error,{code:'SLICE_SOURCE_CONFLICT',...conflicts[0],conflicts});throw error;}
+ const version=selected.version??observed;
+ return {bytes,data,binding:{ref:selected.ref,digest,...(version!==undefined?{version:String(version)}:{}),...(selected.approval_ref?{approval_ref:selected.approval_ref}:{})}};
+}

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

@@ -0,0 +1,109 @@
+import {readFileSync,withValidationPhase} from './validation-phase.mjs';
+import {safe,hash,schema} from './strategic-handoff-io.mjs';
+import {parseSliceYaml,readSliceContract} from './slice-contract.mjs';
+import {renderSliceContractView,diffSliceContracts} from './slice-contract-views.mjs';
+
+// This is a presentation adapter table, never a lifecycle or approval registry.
+export const contractKinds=Object.freeze({
+ slice:null,plan:null,spec:null,'product-design':null,'prototype-confirmation':null,'visual-baseline':null,
+ 'technical-design':'.agents/skills/yss-technical-design/references/technical-design.schema.json',
+ 'api-decision':'docs/process/schemas/api-contract-decision.schema.json',
+ 'data-decision':'docs/process/schemas/data-architecture-decision.schema.json',
+ scaffold:'docs/process/schemas/project-scaffold-contract.schema.json',
+ 'scaffold-decision':'docs/process/schemas/scaffold-architecture-decisions.schema.json',
+ handoff:null,'backend-delivery':'docs/process/schemas/backend-delivery.schema.json',
+ 'frontend-acceptance':'docs/process/schemas/frontend-delivery-acceptance.schema.json',approval:null,'user-decision':'docs/process/schemas/user-decision.schema.json',
+ 'context-reconciliation':'docs/process/schemas/context-reconciliation.schema.json'
+});
+const object=v=>v&&typeof v==='object'&&!Array.isArray(v);
+const stringify=v=>typeof v==='string'?v:JSON.stringify(v,null,2);
+const metadata=/^(schema_version|kind|digest|sha256|subject_digest|.*_digest|.*_sha256|resolution|basis|inputs|sources|artifact_bindings|current_version)$/;
+function display(value){
+ if(Array.isArray(value))return value.map(display);
+ if(!object(value))return value;
+ return Object.fromEntries(Object.entries(value).filter(([key])=>!metadata.test(key)).map(([k,v])=>[k,display(v)]));
+}
+function validateKind(kind){if(!Object.hasOwn(contractKinds,kind))throw new TypeError(`未知合同类型 ${kind}；可用：${Object.keys(contractKinds).join(', ')}`);}
+function load(ref,root){
+ const bytes=readFileSync(safe(root,ref));
+ if(/\.md$/i.test(ref)){
+  const text=bytes.toString('utf8'),front=/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  return{bytes,raw:{...(front?parseSliceYaml(front[1]):{}),正文:front?text.slice(front[0].length):text}};
+ }
+ const raw=parseSliceYaml(bytes);if(!object(raw))throw new TypeError('合同必须是结构化对象或 Markdown 文档');return{bytes,raw};
+}
+function references(value,root,rows=[],seen=new Set()){
+ if(!value||typeof value!=='object')return rows;
+ if(object(value)&&typeof value.ref==='string'&&typeof value.digest==='string'){
+  const key=`${value.ref}\0${value.digest}`;
+  if(!seen.has(key)){seen.add(key);try{rows.push({ref:value.ref,current:hash(readFileSync(safe(root,value.ref)))===value.digest});}catch(error){rows.push({ref:value.ref,current:false,error:error.message});}}
+ }
+ if(object(value))for(const [key,ref]of Object.entries(value))if(key.endsWith('_ref')&&typeof ref==='string'&&typeof value[key.replace(/_ref$/,'_digest')]==='string')references({ref,digest:value[key.replace(/_ref$/,'_digest')]},root,rows,seen);
+ for(const child of Object.values(value))references(child,root,rows,seen);
+ return rows;
+}
+function declaredBlockers(value,prefix=''){
+ if(!value||typeof value!=='object')return[];
+ const rows=[];
+ for(const [key,child]of Object.entries(value)){
+  const field=prefix?`${prefix}.${key}`:key;
+  if(['blockers','blocking_findings','stale_inputs','readiness_blockers'].includes(key)&&Array.isArray(child))for(const item of child)rows.push(`${field}: ${stringify(item)}`);
+  else rows.push(...declaredBlockers(child,field));
+ }
+ return rows;
+}
+function markdown(view){
+ const lines=[`# ${view.kind} · ${view.binding.id||view.binding.ref}`,`版本：${view.binding.version||'源资产未声明'}；权威文件：${view.binding.ref}`,`摘要：${view.binding.digest}`,`检查：${view.checks.join('；')}。批准有效性未核验；本视图不授予执行权限。`];
+ for(const [name,value]of Object.entries(view.content))if(value!==undefined)lines.push(`## ${name}`,stringify(value));
+ if(view.blockers.length)lines.push('## 阻断与未决检查',...view.blockers.map(x=>`- ${x}`));
+ return lines.join('\n\n')+'\n';
+}
+export function viewContract(ref,options={}){return withValidationPhase({root:options.root,purpose:'contract-view',slice_id:ref,work_unit_id:options.unit_id,readOnly:true},()=>view(ref,options));}
+function view(ref,{root=process.cwd(),kind,profile='review',unit_id}={}){
+ validateKind(kind);if(!['review','task','full'].includes(profile))throw new TypeError(`未知阅读档位 ${profile}`);
+ let binding,content,checks=['可读取'],blockers=[],sourceChecks=[];
+ if(kind==='slice'){
+  const loaded=readSliceContract(ref,{root,diagnostic:true});binding=loaded.binding;blockers.push(...declaredBlockers(loaded.raw));
+  const legacy=renderSliceContractView(ref,{root,unit_id:profile==='task'?unit_id:undefined});
+  checks.push('Slice 结构及绑定来源');
+  if(legacy.diagnostic_only){content={诊断:legacy.blockers};blockers=legacy.blockers.map(b=>b.reason);}
+  else if(profile==='full')content={权威合同:loaded.raw,完整视图:legacy};
+  else if(profile==='review'){
+   content={...legacy.summary,验收:legacy.acceptance,实施范围:{工程:loaded.raw.scope?.project_roots||legacy.constraints.project_roots,允许写入:loaded.raw.scope?.allowed_write_paths||legacy.constraints.allowed_write_paths},关键约束:loaded.raw.scope?.forbidden_patterns||legacy.constraints.forbidden_patterns,停止条件:'来源或批准过期、越界、缺证据、验证失败、drift / violation / new_impacts 时停止并回交。'};
+   for(const key of ['risks','risk_acceptance','blockers','pending_decisions','constraints'])if(loaded.raw[key])content[key]=loaded.raw[key];
+   for(const [label,pattern]of [['风险',/风险/],['关键取舍',/取舍/],['待决定事项',/待|决定/],['变化',/变化|变更/]])if(!Object.keys(content).some(k=>pattern.test(k)))content[label]='来源未说明，审阅时核实。';
+   const extensions=loaded.raw.extensions||{};
+   for(const [name,extension]of Object.entries(extensions))for(const [key,value]of Object.entries(extension))if(/risk|constraint|decision|block|exception|unknown/.test(key))content[`${name}.${key}`]=value;
+  }else{
+   if(!unit_id)throw new TypeError('task 视图必须指定 --unit');
+   const units=loaded.contract.work_units.filter(u=>u.id===unit_id);if(units.length!==1)throw new TypeError(`工作单元缺失或不唯一: ${unit_id}`);
+   content={当前任务:units[0].work_unit||units[0],全局约束:legacy.constraints,专项约束:legacy.extensions,编译约束:loaded.raw.resolution,适用性:loaded.raw.applicability,验收:legacy.acceptance,上游引用:Object.fromEntries(Object.entries(loaded.sources).map(([k,v])=>[k,{ref:v.ref,version:v.version}])),停止条件:'来源或批准过期、越界、缺证据、验证失败、drift / violation / new_impacts 时停止并回交。'};
+   const known=new Set(['schema_version','contract_id','contract_version','slice_id','status','basis','scope','applicability','resolution','acceptance','verification','work_units','extensions','ticket_policy']);
+   content.其他约束=Object.fromEntries(Object.entries(loaded.raw).filter(([k])=>!known.has(k)));
+  }
+ }else{
+  const {bytes,raw}=load(ref,root);binding={ref,id:raw.contract_id||raw.technical_design_id||raw.decision_id||raw.request?.request_id||raw.handoff_id||raw.baseline_id||raw.spec_id||raw.plan_id||raw.id||null,version:raw.contract_version||raw.decision_version||raw.handoff_version||raw.version||null,digest:hash(bytes)};
+  blockers.push(...declaredBlockers(raw));
+  let schemaRef=contractKinds[kind];if(kind==='api-decision'&&raw.schema_version===2)schemaRef='docs/process/schemas/api-contract-decision-v2.schema.json';
+  if(kind==='frontend-acceptance'&&[1,3].includes(raw.schema_version))schemaRef=`docs/process/schemas/frontend-delivery-acceptance${raw.schema_version===1?'-v1':'-v3'}.schema.json`;
+  if(schemaRef)try{schema(raw,schemaRef);checks.push('结构校验');}catch(error){blockers.push(error.message);}
+  else checks.push('结构与批准未核验，按资产所有者规则继续');
+  sourceChecks=references(raw,root);if(sourceChecks.length)checks.push(`核对 ${sourceChecks.length} 项可识别来源摘要；其余语义由资产所有者核验`);for(const source of sourceChecks)if(!source.current)blockers.push(`来源不可读或过期：${source.ref}`);
+  // Unknown business fields remain visible. Only well-known machine metadata is hidden.
+  content=profile==='full'?{权威合同:raw,来源核对:sourceChecks}:display(raw);
+  if(kind==='api-decision'&&raw.schema_version===2&&raw.draft_review){try{const review=load(raw.draft_review.ref,root).raw;content.实际审查记录=profile==='full'?review:display(review);if(review.result!=='approved'||!Array.isArray(review.blocking_findings)||review.blocking_findings.length)blockers.push('OpenAPI Draft Review 实际记录未批准或有阻断');if(review.draft_ref!==raw.openapi?.ref||review.draft_digest!==raw.openapi?.digest)blockers.push('Draft Review 未绑定当前 OpenAPI');}catch(error){blockers.push(error.message);}}
+  if(profile==='task'){
+   if(raw.work_units){if(!unit_id)throw new TypeError('含工作单元的合同必须指定 --unit');const matches=raw.work_units.filter(x=>x.id===unit_id);if(matches.length!==1)throw new TypeError(`工作单元缺失或不唯一: ${unit_id}`);content.work_units=matches;}
+   content.机器绑定中的约束=Object.fromEntries(['resolution','basis','inputs','sources','artifact_bindings'].filter(k=>raw[k]!==undefined).map(k=>[k,raw[k]]));
+   content.约束分类='保留未分类字段；本视图只允许阅读，执行影响由资产所有者核验。';
+  }
+ }
+ const view={read_only:true,execution_allowed:false,kind,profile,binding,checks,approval_validity:'not-checked',content,blockers};view.markdown=markdown(view);return view;
+}
+export function diffContract(beforeRef,afterRef,{root=process.cwd(),beforeRoot=root,kind}={}){
+ validateKind(kind);if(kind==='slice')return diffSliceContracts(beforeRef,afterRef,{root,beforeRoot});
+ const before=load(beforeRef,beforeRoot),after=load(afterRef,root),changes=[];
+ const walk=(a,b,p)=>{if(JSON.stringify(a)===JSON.stringify(b))return;if(object(a)&&object(b)){for(const key of new Set([...Object.keys(a),...Object.keys(b)]))walk(a[key],b[key],p?`${p}.${key}`:key);}else changes.push({path:p,before:a??null,after:b??null,category:metadata.test(p.split('.').at(-1))?'binding-change':'requires-review'});};
+ walk(before.raw,after.raw,'');const source_checks=[...references(before.raw,beforeRoot).map(x=>({...x,side:'before'})),...references(after.raw,root).map(x=>({...x,side:'after'}))];
+ return{read_only:true,approval_reusable:false,execution_allowed:false,before:{ref:beforeRef,digest:hash(before.bytes)},after:{ref:afterRef,digest:hash(after.bytes)},bytes_changed:!before.bytes.equals(after.bytes),changes,source_checks,decision_impact:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。'};
+}

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

@@ -1,7 +1,7 @@
 import { normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import { assertExistingSliceStructure, createApprovedExecutionContext, verifySliceContractApproval } from './approved-execution-context.mjs';
 import path from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, withValidationPhase } from './validation-phase.mjs';
 import { ROOT, read, parse, safe, hash, digest, ensure, schema, sourceApprovalPolicy } from './strategic-handoff-io.mjs';
 import { parseContextContract } from './context-contract.mjs';
 import { validateApprovalRecord } from './approval-record.mjs';
@@ -47,7 +47,8 @@ function requireBackendCapability(key) {
 }
 
 /** Read-only: never executes input commands, starts services, unpacks archives or writes receipts. */
-export async function preflightDelivery(input,{stage,root=process.cwd(),work_unit_id}={}) {
+export async function preflightDelivery(input,options={}) {return withValidationPhase({root:path.resolve(options.root||process.cwd(),typeof input?.governance_root==='string'?input.governance_root:'.'),purpose:`delivery-${options.stage}`,slice_id:input?.scope?.slice_id,work_unit_id:options.work_unit_id,readOnly:true,signal:options.signal},()=>preflight(input,options));}
+async function preflight(input,{stage,root=process.cwd(),work_unit_id}={}) {
   try { ensure(STAGES.includes(stage),'未知阶段；必须是 prepare|build|export|accept');schema(input,'docs/process/schemas/delivery-preflight-input.schema.json'); }
   catch(error) { return invalidPreflightInput(error.message); }
   root=path.resolve(root,input.governance_root||'.');