create-yss-spec 3.4.9 → 3.4.10

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||'.');

package/template/scripts/lib/digital-human-roles.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { loadRegistry, ROOT } from "./lifecycle-registry.mjs";

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

@@ -1,6 +1,7 @@
 import {assertApprovedExecutionContext} from './approved-execution-context.mjs';
 import {createHash} from 'node:crypto';
-import {readFileSync,realpathSync,lstatSync,readdirSync} from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { readFileSync, lstatSync, readdirSync } from './validation-phase.mjs';
 import path from 'node:path';
 import {execFileSync} from 'node:child_process';
 import {parseDocument} from '../vendor/yaml.mjs';
@@ -35,7 +36,7 @@ function inspectMaven(root,units){
  const script=`import json,sys,xml.etree.ElementTree as ET\nout=[]\nfor p in json.load(sys.stdin):\n r=ET.parse(p).getroot(); ns={'m':'http://maven.apache.org/POM/4.0.0'}; q=lambda s:r.find(s,ns)\n aid=q('m:artifactId'); aid=aid if aid is not None else q('artifactId')\n deps=[e.text.strip() for e in r.findall('m:dependencies/m:dependency/m:artifactId',ns)+r.findall('m:profiles/m:profile/m:dependencies/m:dependency/m:artifactId',ns)+r.findall('dependencies/dependency/artifactId') if e.text]\n modules=[e.text.strip() for e in r.findall('.//m:modules/m:module',ns)+r.findall('.//modules/module') if e.text]\n out.append({'artifact_id':aid.text.strip() if aid is not None else '', 'dependencies':deps, 'modules':modules})\nprint(json.dumps(out))`;
  try{return JSON.parse(execFileSync('python3',['-c',script],{input:JSON.stringify(units.map(u=>file(root,u.pom_ref))),encoding:'utf8',timeout:15000,maxBuffer:2*1024*1024}));}catch(error){requireThat(false,'ARCH_BUILD_INVALID',`无法读取实际 Maven 构建单元: ${error.message}`);}
 }
-export function verifyExistingArchitecture(identity,bindings,{root,registry,execution}={}){
+export function verifyExistingArchitecture(identity,bindings,{root,registry,execution,readOnly=false}={}){
  const profile=validateExistingArchitecture(identity,registry);
  requireThat(text(root),'ARCH_EVIDENCE_REF','需要治理 root');
  const baseline=bound(root,bindings?.engineering_baseline),registration=bound(root,bindings?.repository_registration),manifest=bound(root,bindings?.manifest);
@@ -132,7 +133,7 @@ export function verifyExistingArchitecture(identity,bindings,{root,registry,exec
  }
  if(changes.length){
   requireThat(execution,'ARCH_SOURCE_STALE',`固定源码改变: ${changes.join(', ')}`);
-  const permission=assertApprovedExecutionContext(execution,{root,architectureIdentity:identity,architectureEvidence:bindings});
+  const permission=assertApprovedExecutionContext(execution,{root,architectureIdentity:identity,architectureEvidence:bindings,readOnly});
   const allowed=permission.allowed_write_paths.map(x=>{if(path.isAbsolute(x)){const rel=path.relative(projectRoot,x).split(path.sep).join('/');return rel==='.'||rel===''?'.':relative(rel);}return x==='.'?'.':relative(x);});
   requireThat(changes.every(ref=>allowed.some(scope=>beneath(ref,scope))&&registration.allowed_write_paths.some(scope=>beneath(ref,scope))),'ARCH_SOURCE_OUT_OF_SCOPE','输出增量超出批准写范围');
  }

package/template/scripts/lib/existing-ui-baseline.mjs

@@ -1,8 +1,10 @@
-import { readFileSync, statSync } from 'node:fs';
+import { statSync } from 'node:fs';
+import { readFileSync, withValidationPhase, inValidationPhase } from './validation-phase.mjs';
 import { ensure, hash, digest, read, safe, files, schema, treeDigest } from './strategic-handoff-io.mjs';
 
 // This is an observation bundle, not a prototype or an approval generator.
-export function validateExistingUiBaseline(data, { bundleRoot } = {}) {
+export function validateExistingUiBaseline(data,options={}) {return inValidationPhase()?validate(data,options):withValidationPhase({root:options.bundleRoot,purpose:'existing-ui-baseline',readOnly:true},()=>validate(data,options));}
+function validate(data, { bundleRoot } = {}) {
   const errors=[];
   try {
     schema(data,'docs/process/schemas/existing-ui-baseline.schema.json');

package/template/scripts/lib/frontend-delivery-boundary.mjs

@@ -1,6 +1,6 @@
 import { normalizeSliceContract, sourceSliceContract, parseSliceYaml } from './slice-contract.mjs';
 import { loadDeliveryProfile } from './harness-execution-scope.mjs';
-import { existsSync } from 'node:fs';
+import { existsSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { ROOT, read, safe, ensure, digest } from './strategic-handoff-io.mjs';

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

@@ -1,5 +1,5 @@
 import { uiBaselineRef, uiBaselineCaseIds, uiBaselineKind, hasConsumerRoutes } from './ui-baseline.mjs';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { openBackendDelivery } from './backend-delivery.mjs';

package/template/scripts/lib/harness-execution-scope.mjs

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs';
+import { loadExecutionScope, assertScopeWorkUnit } from './lifecycle-execution-scope.mjs';
+import { existsSync } from './validation-phase.mjs';
 import path from 'node:path';
 import { ROOT, read, safe, ensure } from './strategic-handoff-io.mjs';
 
@@ -30,6 +31,12 @@ function activeProfile(root) {
 }
 
 export function enforceHarnessTaskScope(task,{root=ROOT}={}) {
+  const scope=loadExecutionScope(root);
+  if(scope) {
+    assertScopeWorkUnit(task.contract?.kind==='slice-implementation'?'work-unit.slice-implementation':task.work_unit_id,{root});
+    ensure(task.role_id!=='role.frontend-engineer','后端职责不允许派发前端实现');
+    ensure(task.allowed_write_paths.every(ref=>!/^apps\/frontend(?:\/|$)/.test(ref)),'禁止写入前端工程');
+  }
   const profile=activeProfile(root);
   if (!profile) return;
   ensure(task.contract?.kind!=='template-maintenance','专职产品项目不得派发模板维护任务');
@@ -41,6 +48,13 @@ export function enforceHarnessTaskScope(task,{root=ROOT}={}) {
 }
 
 export function enforceHarnessSkillScope(skills,registry,{root=ROOT}={}) {
+  if(loadExecutionScope(root)) {
+    assertScopeWorkUnit('work-unit.slice-implementation',{root});
+    for(const id of skills) {
+      const impacts=registry.skills.find(skill=>skill.id===id)?.impacts||[];
+      ensure(!impacts.includes('frontend')||impacts.includes('backend')||impacts.includes('lifecycle'),`后端职责禁止编译生产前端技能: ${id}`);
+    }
+  }
   const profile=activeProfile(root);
   if (!profile) return;
   const side=profile.profile_id==='harness.frontend-delivery'?'frontend':'backend';

package/template/scripts/lib/implementation-contract-compiler.mjs

@@ -5,7 +5,7 @@ import { createApprovedExecutionContext, createApprovedRecompilationContext, ass
 import { enforceTechnicalDesign } from './technical-design-boundary.mjs';
 import { enforceHarnessSkillScope } from "./harness-execution-scope.mjs";
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { DEFAULT_REGISTRY, loadSkillRegistry, resolveSkillForNewUse } from "./skill-registry.mjs";
@@ -276,8 +276,8 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
   const reasons = [];
   let trustedExecution;
   try {
-    trustedExecution=approved_slice?createApprovedExecutionContext(approved_slice,{root,contract:all,work_unit_id}):execution;
-    if(trustedExecution)assertApprovedExecutionContext(trustedExecution,{root,contract});
+    trustedExecution=approved_slice?createApprovedExecutionContext(approved_slice,{root,contract:all,work_unit_id,readOnly}):execution;
+    if(trustedExecution)assertApprovedExecutionContext(trustedExecution,{root,contract,readOnly});
   } catch(error) { reasons.push(error.code||'EXECUTION_APPROVAL_INVALID');trustedExecution=undefined; }
   try { enforceTechnicalDesign({ ...resolution, slice_id: contract.slice_id ?? resolution.slice_id }, { root,execution:trustedExecution,readOnly }); }
   catch { reasons.push("technical-design-stale-or-unavailable"); }
@@ -289,7 +289,7 @@ export function evaluateContractFreshness(contract, { registry, compilerContract
     try { validateArchitectureIdentity(resolution.architecture_identity, registry); }
     catch { reasons.push("architecture-identity-invalid"); }
     if (resolution.architecture_identity.schema_version === 2) {
-      try { verifyArchitectureEvidence(resolution.architecture_identity, resolution.architecture_evidence, { root, registry, execution:trustedExecution }); }
+      try { verifyArchitectureEvidence(resolution.architecture_identity, resolution.architecture_evidence, { root, registry, execution:trustedExecution, readOnly }); }
       catch (error) { reasons.push(error.code ?? "architecture-evidence-stale-or-unavailable"); }
     }
     if (resolution.architecture_identity_digest !== architectureDigest(resolution.architecture_identity)) reasons.push("architecture-identity-digest-changed");

package/template/scripts/lib/json-schema.mjs

@@ -1,7 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, validationCache } from './validation-phase.mjs';
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
+const schemaCache=Symbol('schema-results');
 const validator = String.raw`
 import json
 import sys
@@ -21,8 +22,7 @@ for item in jobs:
     try:
         key = (item['schemaPath'], item['formatChecker'])
         if key not in validators:
-            with open(item['schemaPath'], encoding='utf-8') as source:
-                schema = json.load(source)
+            schema = json.loads(item['schemaText'])
             validators[key] = Draft202012Validator(schema, format_checker=FormatChecker() if key[1] else None)
         errors = list(validators[key].iter_errors(item['value']))
         if item['errorStyle'] == 'verbose':
@@ -45,10 +45,11 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
     const effectiveSchema = path.resolve(schemaPath);
     if (!existsSync(effectiveSchema)) throw new TypeError(`缺少 ${label}: ${effectiveSchema}`);
     if (!["compact", "verbose"].includes(errorStyle)) throw new TypeError(`未知 schema errorStyle: ${errorStyle}`);
-    return { value, schemaPath: effectiveSchema, formatChecker, errorStyle };
+    return { value, schemaPath: effectiveSchema, schemaText: readFileSync(effectiveSchema, 'utf8'), formatChecker, errorStyle };
   });
   // readall waits for EOF even after the complete JSON has arrived. A known UTF-8
   // byte frame lets the validator finish when a transport keeps its write end open.
+  const run = jobs => {
   const input = Buffer.from(JSON.stringify(jobs), "utf8");
   const result = spawnSync("python3", ["-c", validator, String(input.length)], { cwd, encoding: "utf8", input, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
   if (result.error?.code === "ETIMEDOUT") throw new TypeError(`JSON_SCHEMA_TIMEOUT: schema validation exceeded ${timeoutMs}ms`);
@@ -58,6 +59,20 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
   if (!Array.isArray(results) || results.some(item => !item || typeof item.valid !== "boolean" || typeof item.error !== "string")) throw new TypeError("JSON_SCHEMA_PROTOCOL: validator returned invalid result records");
   if (results.length !== jobs.length) throw new TypeError("schema batch 返回数量不匹配");
   return results;
+  };
+  // Batch identical jobs once and reuse only deterministic checks within this operation.
+  // External references retain the uncached path: their dependency closure is not local here.
+  const keys=jobs.map(job=>JSON.stringify([job.schemaPath,job.schemaText,job.value,job.formatChecker,job.errorStyle,path.resolve(cwd),timeoutMs]));
+  const pending=new Map(),cached=new Map();
+  for(let i=0;i<jobs.length;i++){
+    if(/"\$(?:ref|dynamicRef)"\s*:\s*"(?!#)/.test(jobs[i].schemaText)){pending.set(`${i}:${keys[i]}`,{job:jobs[i],indices:[i],cache:false});continue;}
+    const existing=validationCache(schemaCache,keys[i]);
+    if(existing!==undefined)cached.set(i,existing);
+    else {const item=pending.get(keys[i])||{job:jobs[i],indices:[],key:keys[i],cache:true};item.indices.push(i);pending.set(keys[i],item);}
+  }
+  const entries=[...pending.values()],computed=entries.length?run(entries.map(x=>x.job)):[];
+  entries.forEach((entry,index)=>{const result=computed[index];if(entry.cache&&!result.error.includes('Traceback (most recent call last)'))validationCache(schemaCache,entry.key,result);for(const i of entry.indices)cached.set(i,result);});
+  return jobs.map((_,i)=>structuredClone(cached.get(i)));
 }
 
 export function validateJsonSchema(value, schemaPath, options = {}) {

package/template/scripts/lib/lifecycle-context-query.mjs

@@ -1,3 +1,4 @@
+import { loadExecutionScope, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -67,6 +68,8 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
     throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --include 之一");
   }
 
+  const scope = loadExecutionScope();
+  if (workUnitId) assertScopeWorkUnit(workUnitId, { readOnly: true });
   const lifecycle = validateRegistry(loadRegistry());
   const orchestration = loadYaml(ORCHESTRATION_CONTRACT_REF, "生命周期编排合同");
   const skillRegistry = loadSkillRegistry();
@@ -91,7 +94,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   const evidenceIds = new Set([...gates, ...checks].flatMap((gate) => gate.evidence ?? []));
   const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
   const transition = workUnitId ? {
-    next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
+    next: scopedNextRoutes(workUnitId, orchestration.transition_graph?.routes?.[workUnitId] ?? []),
     forbidden_shortcuts: (orchestration.transition_graph?.forbidden_shortcuts ?? [])
       .filter((edge) => edge.from === workUnitId || edge.to === workUnitId),
   } : null;
@@ -129,6 +132,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
       work_unit: workUnit,
     },
     execution: {
+      ...(scope ? { responsibility_scope: scope } : {}),
       mode: mode ? orchestration.modes[mode] : null,
       selected,
       ...(loadPlan ? { plan_checks: lifecycle.stages.find(stage => stage.id === 'stage.plan').spec_entry.required_checks.map(id => ({ id, status: 'pending', evidence_refs: [] })) } : {}),

package/template/scripts/lib/lifecycle-controls.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { parseDocument } from '../vendor/yaml.mjs';

package/template/scripts/lib/lifecycle-execution-scope.mjs

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from './validation-phase.mjs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { safe } from './strategic-handoff-io.mjs';
+import { ROOT } from './lifecycle-registry.mjs';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+export const SCOPE_REF = '.yss-execution-scope.yaml';
+export const TERMINAL_REF = '.yss-backend-delivery.json';
+const read = (root, ref) => {
+  const file = safe(root, ref);
+  const doc = parseDocument(readFileSync(file, 'utf8'), { uniqueKeys: true });
+  if (doc.errors.length) throw new TypeError(doc.errors[0].message);
+  return doc.toJS({ maxAliasCount: 0 });
+};
+const check = (ok, message) => { if (!ok) throw new TypeError(`execution-scope-blocked: ${message}`); };
+
+/** The project opt-in selects a policy; callers cannot supply a replacement policy. */
+export function loadExecutionScope(root = ROOT) {
+  const marker = path.join(root, '.yss-plugin.json');
+  const plugin = existsSync(marker) ? read(root, '.yss-plugin.json') : null;
+  const file = path.join(root, SCOPE_REF);
+  if (!existsSync(file)) {
+    check(!['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin?.plugin), '插件项目缺少职责范围；迁移后才能继续');
+    return null;
+  }
+  const config = read(root, SCOPE_REF), identity = read(root, 'yss-project.yaml');
+  check(identity.schema_version === 1 && identity.repository_mode === 'project-instance', '职责范围仅适用于项目实例');
+  check(config.schema_version === 1 && config.scope_id === 'plan-to-backend'
+    && Object.keys(config).every(key => ['schema_version', 'scope_id'].includes(key)), '未知或被扩大的职责配置');
+  if (plugin) check(['yss-plan-to-backend', 'yss-backend-delivery'].includes(plugin.plugin) && plugin.execution_scope === config.scope_id, '插件与项目职责绑定不一致');
+  const contract = read(root, '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml');
+  const policy = contract.execution_scopes?.[config.scope_id];
+  check(policy?.terminal_work_unit === 'work-unit.backend-delivery' && Array.isArray(policy.allowed_work_units), '匹配版本的主控合同缺少职责策略');
+  return { ...policy, scope_id: config.scope_id };
+}
+
+export function verifyDeliveryTerminal(root = ROOT) {
+  check(existsSync(path.join(root, TERMINAL_REF)), '缺少正式后端交付终点记录');
+  const result = spawnSync(process.execPath, [path.join(root, 'scripts/complete-backend-delivery'), 'verify', '--root', root], {
+    cwd: root, encoding: 'utf8', input: '', timeout: 120000, maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, NODE_OPTIONS: '', NODE_PATH: '' },
+  });
+  check(!result.error && result.status === 0, result.error?.message || result.stderr || '后端交付终点复验失败');
+  return JSON.parse(result.stdout);
+}
+
+export function assertScopeWorkUnit(workUnit, { root = ROOT, readOnly = false } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(workUnit !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return null; }
+  check(scope.allowed_work_units.includes(workUnit), `职责范围不允许 ${workUnit}`);
+  if (existsSync(path.join(root, TERMINAL_REF))) {
+    verifyDeliveryTerminal(root);
+    check(readOnly, '后端交付已完成；不能恢复实现或自动发布');
+  }
+  return scope;
+}
+
+export function scopedNextRoutes(workUnit, routes, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) return routes.filter(id => id !== 'work-unit.backend-delivery');
+  assertScopeWorkUnit(workUnit, { root, readOnly: true });
+  if (existsSync(path.join(root, TERMINAL_REF))) return [];
+  return (scope.route_overrides[workUnit] || routes).filter(id => scope.allowed_work_units.includes(id));
+}
+
+export function assertScopeTransition(current, next, state, { root = ROOT } = {}) {
+  const scope = loadExecutionScope(root);
+  if (!scope) { check(current !== 'work-unit.backend-delivery' && next !== 'work-unit.backend-delivery', '后端终点需要显式职责范围'); return; }
+  if (current === scope.terminal_work_unit && next === null) { verifyDeliveryTerminal(root); return; }
+  assertScopeWorkUnit(current, { root });
+  if (next) assertScopeWorkUnit(next, { root });
+  check(next !== null, '不能把中间阶段声明为后端交付完成');
+  assertScopeImpacts(state, { root });
+}
+
+export function assertScopeImpacts(state, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(state?.delivery_impacts?.frontend !== true, '产品 UI 设计保留，生产前端实现必须交给下游');
+  if (state?.ui_impact === true) {
+    const deferred = state.downstream_frontend;
+    check(deferred && ['owner', 'ticket_ref', 'verification_plan', 'target_version'].every(key => typeof deferred[key] === 'string' && deferred[key].trim()), 'UI 产品须明确下游前端责任、Ticket、验证计划和目标版本');
+  }
+}
+
+export function assertScopeSlice(contract, { root = ROOT } = {}) {
+  if (!loadExecutionScope(root)) return;
+  check(contract.backend?.status === 'required' && contract.frontend?.status === 'not-applicable', '本职责仅允许后端 Slice；产品 UI 设计不能混作前端实现批准');
+  check(!(contract.common?.impacted_areas || []).some(x => ['ui', 'frontend'].includes(x)), 'Slice 仍包含生产前端实现影响');
+  const roles = (contract.work_units || []).map(unit => unit.role_id);
+  check(!roles.includes('role.frontend-engineer'), '禁止派发前端实现');
+}

package/template/scripts/lib/lifecycle-registry.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "../vendor/yaml.mjs";

package/template/scripts/lib/lifecycle-transition.mjs

@@ -1,3 +1,5 @@
+import { assertTrackingTransition } from './stage-tracking.mjs';
+import { assertScopeTransition, assertScopeImpacts, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 // Wire capability marker: profile-local readiness rules are not interchangeable.
 export const SLICE_REPOSITORY_PREPARATION_PROTOCOL = 1;
 import { createHash } from "node:crypto";
@@ -43,7 +45,8 @@ const NEXT_ROUTES = deepFreeze({
   [TICKET_DECOMPOSITION_WORK_UNIT]: [IMPLEMENTATION_WORK_UNIT],
   [IMPLEMENTATION_WORK_UNIT]: ["work-unit.frontend-implementation-verification", "work-unit.code-review"],
   "work-unit.frontend-implementation-verification": ["work-unit.code-review"],
-  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT],
+  "work-unit.code-review": ["work-unit.release-and-retrospective", IMPLEMENTATION_WORK_UNIT, "work-unit.backend-delivery"],
+  "work-unit.backend-delivery": [],
   "work-unit.release-and-retrospective": [],
 });
 
@@ -249,7 +252,11 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
-  if (currentWorkUnit === "work-unit.code-review" && nextRoute === "work-unit.release-and-retrospective") {
+  try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
+  catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
+  try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
+  if (currentWorkUnit === "work-unit.code-review" && ["work-unit.release-and-retrospective", "work-unit.backend-delivery"].includes(nextRoute)) {
     try {
       if (decisionState?.review_input?.scope_kind !== "change") throw new Error("只读基线审计不能关闭实现审查");
       validateBackendReview(decisionState, { root: options.root || ROOT });
@@ -262,7 +269,7 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }
     catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   }
-  const routes = NEXT_ROUTES[currentWorkUnit];
+  const routes = NEXT_ROUTES[currentWorkUnit] && scopedNextRoutes(currentWorkUnit, NEXT_ROUTES[currentWorkUnit], options);
   if (!routes) return blockedResult([BLOCKING_SIGNALS.invalidRoute], ["known_current_work_unit"]);
   if (nextRoute === REPOSITORY_PREPARATION_WORK_UNIT && currentWorkUnit !== "work-unit.technical-analysis") {
     return blockedResult([BLOCKING_SIGNALS.technicalAnalysisRequired], ["work-unit.technical-analysis predecessor"]);
@@ -299,6 +306,8 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
  * generated and verified scaffold. Unaffected roles need an explicit reason.
  */
 export function validateImplementationRepositoriesReady(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), root = ROOT } = {}) {
+  try { assertScopeImpacts(state, { root }); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const preparation = state?.implementation_repository_preparation;
   const impacts = state?.delivery_impacts;
   const signals = [];
@@ -411,6 +420,13 @@ function validateDecisionBoundary(workUnit, state, options) {
  * `exists` is injectable so external adapters can resolve their own tracker refs.
  */
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
+  if ((state?.tracker_kind ?? "local-markdown") === "local-markdown" && state?.vertical_slice_ticket?.ref && isReadable(state.vertical_slice_ticket.ref, exists)) {
+    try {
+      const header = read(state.vertical_slice_ticket.ref).match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const kind = header ? parseDocument(header[1], { uniqueKeys: true }).toJS({ maxAliasCount: 0 })?.kind : null;
+      if (kind === "stage-work-item") return blockedResult(["stage-work-item-not-implementable"], ["vertical-slice-ticket required"]);
+    } catch { return blockedResult(["ticket-content-unreadable"], ["readable vertical slice content"]); }
+  }
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }
   const repositoryResult = validateImplementationRepositoriesReady(state, { exists, read, ...decisionOptions });
@@ -532,6 +548,8 @@ export function validateTicketFormalization(state, { exists = existsSync, read =
  * Validate the complete implementation entry seam after ready-for-agent promotion.
  */
 export function validateImplementationEntry(state, options = {}) {
+  try { assertScopeWorkUnit(IMPLEMENTATION_WORK_UNIT, options); assertScopeImpacts(state, options); }
+  catch (error) { return blockedResult(['execution-scope-blocked'], [error.message]); }
   const ticketResult = validateTicketFormalization(state, options);
   if (ticketResult.result === "blocked") return ticketResult;
   if (state?.predecessor_work_unit !== TICKET_DECOMPOSITION_WORK_UNIT) {

package/template/scripts/lib/openapi-draft-validation.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "./validation-phase.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseAllDocuments, parseDocument } from "../vendor/yaml.mjs";

package/template/scripts/lib/skill-registry.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 { nestedSkillPaths, OBSOLETE, PROJECTION_ROOTS, ROOT, unregisteredNestedSkillPaths } from "./skill-supply-chain.mjs";

package/template/scripts/lib/slice-contract-preparation.mjs

@@ -1,7 +1,8 @@
+import {readContractSource,contractSourceMetadata} from './contract-source.mjs';
 import {sliceRepositories} from './slice-repositories.mjs';
 import { sliceCheckApplicability } from './slice-applicability.mjs';
 import path from 'node:path';
-import fs from 'node:fs';
+import fs, {withValidationPhase} from './validation-phase.mjs';
 import { stringify } from '../vendor/yaml.mjs';
 import { safe, hash, digest, write } from './strategic-handoff-io.mjs';
 import { compileDefaultImplementationContract, digestDocument, loadCompilerContract } from './implementation-contract-compiler.mjs';
@@ -9,11 +10,7 @@ import { normalizeSliceContract, parseSliceYaml, readSliceSources, resolveSliceB
 
 const object=value=>value && typeof value==='object' && !Array.isArray(value);
 const same=(a,b)=>digest(a)===digest(b);
-function metadata(text) {
-  const 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):{};
-}
+const metadata=contractSourceMetadata;
 function mergeFacts(left,right,path,report) {
   if(left===undefined)return structuredClone(right);
   if(right===undefined)return structuredClone(left);
@@ -43,7 +40,15 @@ function lifecycleSources(checkpoint,report) {
   return result;
 }
 /** sources select existing assets; refinements contain ONLY new slice facts, never an approved contract. */
-export function prepareSliceImplementationContract({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refinements={},approved_slice}={}) {
+export function prepareSliceImplementationContract(options={}) {
+ let result;
+ try{return withValidationPhase({root:options.root,purpose:'slice-prepare',slice_id:options.ticket_ref,readOnly:true,signal:options.signal},()=>result=prepare(options));}
+ catch(error){
+  if(!result||!['VALIDATION_INPUT_CHANGED','VALIDATION_CANCELLED'].includes(error.code))throw error;
+  result.slice_contract.status='blocked';result.report.blockers.push({code:error.code==='VALIDATION_INPUT_CHANGED'?'SLICE_INPUT_CONFLICT':error.code,field:'slice',source_ref:null,reason:`${error.message.includes('compiler-contract.yaml')?'编译规则来源冲突':'生成期间来源变化'}: ${error.message}`,responsibility:'professional-review',recovery:'重新读取当前来源并准备新草案'});return result;
+ }
+}
+function prepare({root=process.cwd(),ticket_ref,checkpoint_ref,sources={},refinements={},approved_slice}={}) {
   const started=performance.now();
   const report={read_only:true,blockers:[],sources:{},provenance:[],reason_chains:{},checks:[]};
   const snapshots=new Map();
@@ -52,6 +57,7 @@ export function prepareSliceImplementationContract({root=process.cwd(),ticket_re
   try {
     let ticketText='',ticket={},saved={};
     try {ticketText=read(ticket_ref).toString('utf8');ticket=metadata(ticketText);}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'basis.ticket',source_ref:ticket_ref,reason:error.message});}
+    if (ticket.kind === 'stage-work-item' || /\/work-items\//.test(ticket_ref || '')) report.blockers.push({code:'STAGE_WORK_ITEM_NOT_IMPLEMENTABLE',field:'basis.ticket',reason:'stage-work-item 不能作为实现 Ticket'});
     if(checkpoint_ref)try {saved=parseSliceYaml(read(checkpoint_ref));}catch(error){report.blockers.push({code:'SLICE_SOURCE_UNREADABLE',field:'checkpoint',source_ref:checkpoint_ref,reason:error.message});}
     const fromTicket=ticket.slice_implementation || {};
     const facts=mergeFacts(saved.slice_implementation || {},fromTicket,'slice',report);
@@ -73,13 +79,9 @@ export function prepareSliceImplementationContract({root=process.cwd(),ticket_re
       try {
       if(typeof value==='string' && Object.hasOwn(selected,value)) {basis[key]=value;continue;}
       const binding=typeof value==='string'?{ref:value}:value;
-      const bytes=read(binding.ref),rawDigest=hash(bytes);
-      if(binding.digest&&binding.digest!==rawDigest)throw new TypeError(`stale: 来源 ${key}`);
-      const data=metadata(bytes.toString('utf8'));
-      const sourceVersion=data.requirement_version??data.version??data.contract_version;
-      if(binding.version!==undefined&&sourceVersion!==undefined&&String(binding.version)!==String(sourceVersion))throw new TypeError(`来源版本冲突: ${key}`);
-      const version=binding.version||data.requirement_version||data.version||data.contract_version;
-      basis[key]={ref:binding.ref,digest:rawDigest,...(version?{version:String(version)}:{}),...(binding.approval_ref?{approval_ref:binding.approval_ref}:{})};
+      const source=readContractSource(binding,{root,read});
+      const rawDigest=source.binding.digest;
+      basis[key]=source.binding;
       if(seen.has(binding.ref)) {
         const previous=seen.get(binding.ref);
         if(!same(basis[key],basis[previous]))throw new TypeError(`来源绑定冲突: ${key}/${previous}`);