create-yss-spec 3.5.2 → 3.5.4

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

@@ -1,10 +1,18 @@
+import {readingCheckpointsForAsset,checkReadingViews} from './reading-view-bundle.mjs';
 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';
+import {renderReadingMarkdown} from './reading-view-markdown.mjs';
+import {readingDiff,renderReadingDiff} from './reading-view-diff.mjs';
+import {adaptReading} from './reading-view-adapters.mjs';
+import {readingViewModel} from './reading-view-model.mjs';
 
 // This is a presentation adapter table, never a lifecycle or approval registry.
 export const contractKinds=Object.freeze({
+ 'domain-strategy':'.template-spec/process/schemas/domain-strategy-reading.schema.json',
+ 'stage-decision-package':'.template-spec/process/schemas/stage-decision-package-reading.schema.json',
+ checkpoint:'.template-spec/process/schemas/lifecycle-checkpoint.schema.json','tracking-migration':null,
  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':'.template-spec/process/schemas/api-contract-decision.schema.json',
@@ -17,11 +25,11 @@ export const contractKinds=Object.freeze({
 });
 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)$/;
+const metadata=/^(schema_version|digest|sha256|subject_digest|document_digest|referenced_terms_digest)$/;
 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)]));
+ return Object.fromEntries(Object.entries(value).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){
@@ -53,25 +61,32 @@ function declaredBlockers(value,prefix=''){
  return rows;
 }
 function markdown(view){
+ if(['domain-strategy','stage-decision-package','checkpoint','tracking-migration'].includes(view.kind))return renderReadingMarkdown(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}={}){
+function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout='legacy',include_reading_model=false}={}){
  validateKind(kind);if(!['review','task','full'].includes(profile))throw new TypeError(`未知阅读档位 ${profile}`);
- let binding,content,checks=['可读取'],blockers=[],sourceChecks=[];
+ if(!['legacy','focused'].includes(task_layout))throw new TypeError(`未知 task layout ${task_layout}`);
+ let sourceRaw,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);}
+  if(legacy.diagnostic_only){content={诊断:legacy.blockers,未校验的原合同:loaded.raw};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 reviewKnown=new Set(['schema_version','contract_id','contract_version','slice_id','status','basis','scope','common','lifecycle_refs','applicability','resolution','acceptance','verification','work_units','extensions','ticket_policy']);
+   content.未分类约束=Object.fromEntries(Object.entries(loaded.raw).filter(([key])=>!reviewKnown.has(key)));
+   // Normalization preserves raw v2 common / v3 scope, including nested unknown constraints.
+   content.全局约束=legacy.constraints;
+   content.专项约束=loaded.raw.extensions;content.适用性=loaded.raw.applicability;
    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{
@@ -80,9 +95,16 @@ function view(ref,{root=process.cwd(),kind,profile='review',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)));
+   if(task_layout==='focused' && loaded.raw.schema_version===3){
+    const task=units[0].work_unit||units[0];
+    const ids=new Set([...(task.acceptance_refs||[]),...(task.verification||[]).flatMap(v=>v.acceptance_refs||[])]);
+    content={当前任务:task,验收:Object.fromEntries(Object.entries(legacy.acceptance).filter(([id])=>ids.has(id))),全局约束:{...legacy.constraints,verification_commands:task.verification_commands,expected_evidence_files:task.expected_evidence},专项约束:legacy.extensions,编译约束:loaded.raw.resolution,适用性:loaded.raw.applicability,上游引用:content.上游引用,其他约束:content.其他约束,停止条件:content.停止条件,
+     恢复动作:['读取主 tracker 或当前任务包，核对实际运行结果；运行状态未知时不重复派发','复验当前来源、批准和适用门禁；失效时回交，不能沿用旧完成结论'],
+     完整验收引用:{ref,digest:binding.digest,profile:'full',omitted_acceptance_ids:Object.keys(legacy.acceptance).filter(id=>!ids.has(id))}};
+   }
   }
  }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)};
+  const {bytes,raw}=load(ref,root);sourceRaw=raw;binding={ref,schema_version:raw.schema_version??null,id:raw.contract_id||raw.feature_id||raw.domain_strategy_id||raw.stage_decision_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.domain_version||raw.package_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='.template-spec/process/schemas/api-contract-decision-v2.schema.json';
   if(kind==='frontend-acceptance'&&[1,3].includes(raw.schema_version))schemaRef=`.template-spec/process/schemas/frontend-delivery-acceptance${raw.schema_version===1?'-v1':'-v3'}.schema.json`;
@@ -90,7 +112,7 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id}={}){
   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);
+  content=profile==='full'?{权威合同:raw,来源核对:sourceChecks}:adaptReading(kind,display(raw),{root,ref,blockers});
   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;}
@@ -98,12 +120,58 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id}={}){
    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;
+ const view={read_only:true,execution_allowed:false,kind,profile,binding,checks,approval_validity:'not-checked',content,blockers};if(include_reading_model&&['domain-strategy','stage-decision-package','checkpoint','tracking-migration'].includes(kind))view.reading_model=readingViewModel(view,sourceRaw);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:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。'};
+ const result={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:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。',semantic_changes:readingDiff(before.raw,after.raw)};result.markdown=renderReadingDiff(result);return result;
+}
+
+/** Mechanical review material only; original decisions and semantic review remain authoritative. */
+export function prepareContractReview(beforeRef, afterRef, options = {}) {
+  const root = options.root || process.cwd();
+  return withValidationPhase({root,purpose:'prepare-contract-review',readOnly:true}, () => {
+    validateKind(options.kind);
+    const gaps = [];
+    const gap = (code, source_ref, reason, recovery) => gaps.push({code,source_ref,reason,recovery});
+    const readView = (ref, side, sourceRoot) => {
+      try {
+        const value = viewContract(ref,{...options,root:sourceRoot,profile:'full'});
+        for(const blocker of value.blockers)gap('SOURCE_INVALID',ref,blocker,'恢复当前权威来源并重新校验');
+        return value;
+      } catch(error) { gap('SOURCE_UNREADABLE',ref,`${side}: ${error.message}`,'提供可读取的原始资产；不推断历史内容');return null; }
+    };
+    for(const checkpoint of readingCheckpointsForAsset(root,afterRef,options.kind)){
+      const reading=checkReadingViews(root,checkpoint);
+      if(reading.blockers.length)gap('READING_VIEWS_STALE',checkpoint,reading.blockers.join('; '),reading.recovery);
+    }
+    const before = readView(beforeRef,'before',options.beforeRoot||root), after = readView(afterRef,'after',root);
+    if(before?.binding.id && after?.binding.id && before.binding.id!==after.binding.id)gap('IDENTITY_CONFLICT',afterRef,'前后资产 ID 不一致','选择同一资产的前后版本');
+    if(before?.binding.version && before.binding.version===after?.binding.version && before.binding.digest!==after.binding.digest)gap('VERSION_CONFLICT',afterRef,'相同版本包含不同字节','形成新候选版本并重新核验');
+    let diff = null;
+    if(before&&after)try{diff=diffContract(beforeRef,afterRef,options);}catch(error){gap('DIFF_UNAVAILABLE',afterRef,error.message,'先修复来源绑定与版本冲突');}
+    let originalDecision = null;
+    if(options.decision_ref) {
+      try {
+        const loaded=load(options.decision_ref,root);
+        schema(loaded.raw,'.template-spec/process/schemas/user-decision.schema.json');
+        originalDecision={ref:options.decision_ref,digest:hash(loaded.bytes),record:loaded.raw};
+        for(const row of references(loaded.raw,root))if(!row.current)gap('DECISION_SOURCE_STALE',row.ref,row.error||'原决定来源摘要不匹配','恢复原决定快照；不得重绑旧回复');
+      }catch(error){gap('DECISION_UNAVAILABLE',options.decision_ref,error.message,'提供有效的原始决定；本材料不能替代用户回复');}
+    }
+    if(!options.decision_ref)gaps.push({code:'DECISION_NOT_PROVIDED',source_ref:null,reason:'未提供原决定，不能判断批准延续',recovery:'需要沿用批准时提供原决定及原始回复来源',blocking:false});
+    return {
+      schema_version:1,kind:'contract-review-preparation',read_only:true,execution_allowed:false,
+      approval_reusable:false,approval_validity:'not-checked',semantic_equivalence:'requires-independent-review',
+      before:before?.binding||null,after:after?.binding||null,original_decision:originalDecision,
+      decision_status:options.decision_ref?(originalDecision?'requires-validation':'missing-or-invalid'):'not-provided',
+      source_views:{before:before?.content||null,after:after?.content||null},diff,gaps,
+      review_required:['business_scope','acceptance','contract_commitments','authorization','risk_acceptance','quality','external_commitments'],
+      next_action:gaps.some(x=>x.blocking!==false)?'repair-source-gaps':'independent-semantic-review',
+      blockers:gaps.filter(x=>x.blocking!==false).map(item=>item.reason)
+    };
+  });
 }

package/template/scripts/lib/execution-evidence.mjs

@@ -0,0 +1,51 @@
+import {readFileSync,existsSync} from './validation-phase.mjs';
+import {safe, hash} from './strategic-handoff-io.mjs';
+
+/** Checks binding, not the truth of arbitrary prose. Owner tests/review remain mandatory. */
+export function executionEvidenceBlockers(result, contract, current) {
+  const blockers=[];
+  if(result.evidence_binding_version!==1)return ['legacy-evidence-binding-missing'];
+  const unit=contract.work_units.find(u=>u.id===result.work_unit_id);
+  if(!unit)return ['work-unit-mismatch'];
+  try {
+    const approved=current.approved_slice;
+    if(!approved || result.consumed_contract?.contract_digest!==approved.digest || hash(readFileSync(safe(current.root,approved.ref)))!==approved.digest)blockers.push('evidence-contract-digest-mismatch');
+    const evidence=result.evidence_files||[];
+    const checks=unit.work_unit.verification;
+    const evidenceRoot=contract.repositories?unit.project_root:current.root;
+    for(const check of checks) {
+      const rows=(result.verification_results||[]).filter(r=>r.verification_id===check.id);
+      if(rows.length!==1){blockers.push('verification-id-missing-or-duplicate');continue;}
+      const row=rows[0];
+      if(row.command!==check.command||row.cwd!==check.cwd||row.exit_code!==0||!Number.isFinite(Date.parse(row.executed_at)))blockers.push('verification-binding-mismatch');
+      if(!Array.isArray(row.acceptance_refs)||row.acceptance_refs.length!==new Set(row.acceptance_refs).size||JSON.stringify([...row.acceptance_refs].sort())!==JSON.stringify([...check.acceptance_refs].sort()))blockers.push('acceptance-evidence-coverage-missing');
+      if(!Array.isArray(row.evidence_refs)||!check.expected_evidence.every(ref=>row.evidence_refs.includes(ref)))blockers.push('verification-evidence-link-missing');
+      const covered=new Set();
+      for(const ref of row.evidence_refs||[]) {
+        const matches=evidence.filter(e=>typeof e==='object'&&e.path===ref&&(!contract.repositories||e.project_root===unit.project_root));
+        if(!matches.length)blockers.push('verification-evidence-link-missing');
+        for(const entry of matches) {
+          if(!check.acceptance_refs.includes(entry.behavior_ref))blockers.push('evidence-behavior-unrelated');
+          else covered.add(entry.behavior_ref);
+          if(hash(readFileSync(safe(evidenceRoot,ref)))!==entry.digest)blockers.push('evidence-digest-mismatch');
+        }
+      }
+      if(check.acceptance_refs.some(id=>!covered.has(id)))blockers.push('acceptance-evidence-coverage-missing');
+    }
+    // Bind declared execution inputs too: changed source bytes cannot reuse an earlier result.
+    if(!Array.isArray(result.source_bindings)||!result.source_bindings.length)blockers.push('execution-source-bindings-missing');
+    for(const entry of result.source_bindings||[]) {
+      const root=entry.project_root||unit.project_root;
+      const allowedRoots=new Set([unit.project_root,...checks.flatMap(check=>check.dependency_roots||[])]);
+      if(!allowedRoots.has(root)||(contract.repositories&&!contract.repositories[root])){blockers.push('execution-source-repository-mismatch');continue;}
+      if(entry.deleted===true) {
+        if(existsSync(safe(root,entry.path,{missing:true})) || entry.digest!==null)blockers.push('execution-source-drift');
+      } else if(hash(readFileSync(safe(root,entry.path)))!==entry.digest)blockers.push('execution-source-drift');
+    }
+    for(const changed of result.changed_files||[]) {
+      const ref=typeof changed==='string'?changed:changed.path;
+      if(!result.source_bindings?.some(b=>b.path===ref&&(b.project_root||unit.project_root)===(typeof changed==='object'&&changed.project_root||unit.project_root)))blockers.push('changed-source-binding-missing');
+    }
+  } catch(error) {blockers.push(`execution-evidence-unreadable: ${error.message}`);}
+  return [...new Set(blockers)];
+}

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

@@ -0,0 +1,274 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+const digest = value => createHash('sha256').update(value).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const fail = message => { throw new Error(message); };
+const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+const present = file => { try { fs.lstatSync(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+const yaml = file => { const doc = parseDocument(fs.readFileSync(file, 'utf8'), {uniqueKeys:true}); if (doc.errors.length) fail('invalid-yaml: ' + file); return doc.toJS({maxAliasCount:0}); };
+const toolDigest = () => digest(fs.readFileSync(import.meta.filename));
+
+// Check every existing component; a candidate is never followed through a link.
+export function safeAssetPath(root, ref) {
+  if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || /[\\\x00-\x1f]/.test(ref) || ref.split('/').some(x => !x || x === '.' || x === '..')) fail('unsafe-path: ' + ref);
+  let file = root;
+  for (const part of ref.split('/')) { file = path.join(file, part); if (present(file) && fs.lstatSync(file).isSymbolicLink()) fail('symlink-refused: ' + ref); }
+  return file;
+}
+function external(root, supplied) {
+  if (!supplied || !path.isAbsolute(supplied)) fail('external-absolute-path-required');
+  let ancestor=path.resolve(supplied), suffix=[];
+  while (!present(ancestor)) { suffix.unshift(path.basename(ancestor)); ancestor=path.dirname(ancestor); }
+  if (fs.lstatSync(ancestor).isSymbolicLink()) fail('external-symlink-refused');
+  const resolved=path.join(fs.realpathSync(ancestor),...suffix);
+  if (inside(root,resolved) || inside(resolved,root)) fail('archive-must-be-outside-project');
+  return resolved;
+}
+function project(root, checkpoint) {
+  root=fs.realpathSync(root);
+  const identity=yaml(safeAssetPath(root,'yss-project.yaml'));
+  if (identity.schema_version!==1 || identity.repository_mode!=='project-instance') fail('project-instance-required');
+  const cp=yaml(safeAssetPath(root,checkpoint));
+  if (cp.schema_version!==1 || cp.repository_mode!=='project-instance' || !/^[a-z0-9][a-z0-9-]*$/.test(cp.feature_id || '')) fail('checkpoint-identity-invalid');
+  const base=`docs/.scratch/${cp.feature_id}`;
+  if (!checkpoint.startsWith(base+'/')) fail('checkpoint-feature-mismatch');
+  return {root,checkpoint,base};
+}
+function tree(root, ref, reportLinks=false) {
+  if(reportLinks) {
+    const parent=path.posix.dirname(ref);if(parent!=='.')safeAssetPath(root,parent);
+    const file=path.join(root,ref);
+    if(present(file)&&fs.lstatSync(file).isSymbolicLink())return {type:'symlink',target:fs.readlinkSync(file)};
+  }
+  const file=safeAssetPath(root,ref);
+  if (!present(file)) return null;
+  const stat=fs.lstatSync(file), mode=stat.mode&0o777;
+  if (stat.isDirectory()) {
+    const entries=fs.readdirSync(file).sort().map(name=>[name,tree(root,ref+'/'+name,reportLinks)]);
+    return {type:'directory',mode,entries,digest:digest(json(entries))};
+  }
+  if (!stat.isFile()) fail('special-file-refused: '+ref);
+  return {type:'file',mode,size:stat.size,digest:digest(fs.readFileSync(file))};
+}
+function same(a,b) { return JSON.stringify(a)===JSON.stringify(b); }
+function remainingMatches(current, expected) {
+  if (!current) return true;
+  if(current.type!=='directory'||expected.type!=='directory')return same(current,expected);
+  return current.mode===expected.mode && current.entries.every(([name,child])=>{
+    const original=expected.entries.find(([n])=>n===name);return original&&remainingMatches(child,original[1]);
+  });
+}
+function flatten(node, ref, output=[]) {
+  if (!node) return output;
+  if(node.type==='symlink')return output;
+  if (node.type==='file') output.push({ref,size:node.size,digest:node.digest,mode:node.mode});
+  else for (const [name,child] of node.entries) flatten(child,ref+'/'+name,output);
+  return output;
+}
+const cacheRefs = base => ['.chrome-profile','.chrome-baseline-profile'].map(n=>`${base}/verification/browser/${n}`);
+const scanExcluded = new Set(['.git','node_modules','.codegraph','.graphify','.codex','.cursor','.pi']);
+const toolSources=new Set(['scripts/feature-assets','scripts/lib/feature-assets.mjs','.template-spec/process/feature-assets.md']);
+function sources(ctx) {
+  const files=[], unknown=[];
+  const metadata=path.join(ctx.root,'.yss-template.json');
+  const managed=present(metadata)?JSON.parse(fs.readFileSync(metadata,'utf8')).managedFiles||{}:{};
+  function walk(dir, relative='') {
+    for (const entry of fs.readdirSync(dir,{withFileTypes:true}).sort((a,b)=>a.name.localeCompare(b.name))) {
+      const ref=relative ? relative+'/'+entry.name : entry.name;
+      if (scanExcluded.has(entry.name) || cacheRefs(ctx.base).some(c=>ref===c||ref.startsWith(c+'/'))) continue;
+      const file=path.join(dir,entry.name);
+      if (entry.isSymbolicLink()) { unknown.push(ref+':symlink'); continue; }
+      if (entry.isDirectory()) { walk(file,ref); continue; }
+      if (!entry.isFile()) { unknown.push(ref+':special'); continue; }
+      if (!/\.(md|ya?ml|json|[cm]?js|ts|tsx|jsx|py|sh|html|toml|txt)$/.test(ref) && path.extname(ref)) continue;
+      if (fs.statSync(file).size>8*1024*1024) { unknown.push(ref+':oversize-text'); continue; }
+      const bytes=fs.readFileSync(file); if (bytes.includes(0)) continue;
+      const hash=digest(bytes);
+      // Unchanged distributed framework files are generic readers, not feature bindings.
+      // Locally edited/new files in these directories must still be scanned.
+      const generic=toolSources.has(ref)||(/^scripts\/|^\.agents\/|^\.template-spec\//.test(ref)&&managed[ref]?.contentHash===hash);
+      files.push({ref,digest:hash,text:generic?'':bytes.toString('utf8')});
+    }
+  }
+  walk(ctx.root); return {files,unknown};
+}
+function references(ctx, ref, scan) {
+  const filename=path.basename(ref), ids=[];
+  if (/\/captures\/[^/]+-question\.yaml$/.test(ref)) {
+    const capture=yaml(safeAssetPath(ctx.root,ref));
+    for (const message of capture.messages||[]) if (message.id) ids.push(message.id);
+  }
+  const incoming=[], producers=[];
+  for (const source of scan.files) {
+    if (source.ref===ref) continue;
+    source.text.split('\n').forEach((line,index)=>{
+      if (line.includes(ref)||line.includes(filename)||ids.some(id=>line.includes(id))) {
+        // A direct write-only summary sink is reproducible output, not a consumer.
+        const writeOnly=filename==='summary.json' && /^\s*(?:await\s+)?(?:fs\.)?writeFile(?:Sync)?\(path\.join\([^\n]+['"]summary\.json['"]\)/.test(line);
+        (writeOnly?producers:incoming).push({ref:source.ref,line:index+1,kind:writeOnly?'producer':'reference'});
+      } else if (/\b(readFile|readFileSync|glob|globSync|readdir|readdirSync)\s*\(/.test(line) && /\$\{|\*\*|\+/.test(line) && (line.includes(ctx.base)||line.includes('verification')||line.includes('docs/'))) {
+        incoming.push({ref:source.ref,line:index+1,kind:'unresolved-dynamic-reference'});
+      }
+    });
+  }
+  return {incoming,producers};
+}
+function classify(ctx,ref) {
+  const relative=ref.slice(ctx.base.length+1), file=safeAssetPath(ctx.root,ref);
+  if (cacheRefs(ctx.base).includes(ref)) return {kind:'browser-cache',action:'delete-cache'};
+  if (relative==='verification/prototype-evidence-draft.yaml' && present(safeAssetPath(ctx.root,ctx.base+'/verification/prototype-evidence.yaml'))) return {kind:'superseded-draft',action:'archive'};
+  if (relative==='plan/stage-items.yaml' && yaml(safeAssetPath(ctx.root,ctx.checkpoint)).stage_tracking?.items?.length) return {kind:'tracking-input',action:'archive'};
+  if (relative==='verification/browser/summary.json' && present(safeAssetPath(ctx.root,ctx.base+'/verification/browser/browser-result.json'))) return {kind:'generated-summary',action:'archive'};
+  if (/^gates\/captures\/[^/]+-question\.yaml$/.test(relative)) {
+    const doc=yaml(file);
+    if (doc.messages?.length && doc.messages.every(m=>m.actor_kind==='digital-human' && typeof m.id==='string' && !m.decision)) return {kind:'detached-question',action:'archive'};
+  }
+  return {kind:/^(gates|handoff|task-packages|verification)\//.test(relative)||/contract|checkpoint|context-reconciliation|domain-strategy|stage-decision/.test(relative)?'protected':'unknown',action:'keep'};
+}
+export function cacheOccupancy(file) {
+  if (!['darwin','linux'].includes(process.platform)) return {status:'unknown',reason:'occupancy-platform-unsupported'};
+  const ps=spawnSync('ps',['-axo','pid=,command='],{encoding:'utf8',maxBuffer:16*1024*1024});
+  if (ps.status!==0) return {status:'unknown',reason:'process-inspection-failed'};
+  const aliases=[file];
+  // macOS /var and /private/var are the same storage but ps retains the spelling.
+  if(file.startsWith('/private/var/'))aliases.push(file.slice('/private'.length));
+  const pids=ps.stdout.split('\n').filter(line=>line.includes('--user-data-dir') && aliases.some(ref=>line.includes(ref))).map(line=>Number(line.trim().split(/\s+/)[0]));
+  if (pids.length) return {status:'busy',pids};
+  // lsof exit 1 with no diagnostic means no open files; failure is never "free".
+  const opened=spawnSync('lsof',['-t','+D',file],{encoding:'utf8',timeout:15000,maxBuffer:1024*1024});
+  if (opened.stdout?.trim()) return {status:'busy',pids:opened.stdout.trim().split(/\s+/).map(Number).filter(Number.isSafeInteger)};
+  if (opened.status===0) return {status:'unknown',reason:'empty-occupancy-result'};
+  if (opened.status!==1 || opened.stderr?.trim() || opened.error) return {status:'unknown',reason:'open-file-inspection-failed'};
+  return {status:'free'};
+}
+export function inspectAssets({root,checkpoint}) {
+  const ctx=project(root,checkpoint), scan=sources(ctx), inventory=tree(ctx.root,ctx.base,true),rows=flatten(inventory,ctx.base);
+  const symlinks=[];function collect(node,ref){if(node.type==='symlink')symlinks.push({ref,target:node.target});else for(const [name,child]of node.entries||[])collect(child,ref+'/'+name);}collect(inventory,ctx.base);
+  const groups=new Map(); for (const row of rows) { const list=groups.get(row.digest)||[]; list.push(row.ref); groups.set(row.digest,list); }
+  const candidates=rows.filter(row=>classify(ctx,row.ref).action==='archive').map(row=>({ref:row.ref,...classify(ctx,row.ref),...references(ctx,row.ref,scan)}));
+  return {schema_version:1,read_only:true,root:ctx.root,checkpoint,files:rows.length,bytes:rows.reduce((sum,row)=>sum+row.size,0),symlinks,duplicates:[...groups.values()].filter(rows=>rows.length>1),categories:rows.map(row=>({...row,...classify(ctx,row.ref)})),candidates,cache_candidates:cacheRefs(ctx.base).filter(ref=>present(safeAssetPath(ctx.root,ref))),scan_unknown:scan.unknown};
+}
+export function planAssets({root,checkpoint,candidates,archiveDir}) {
+  const ctx=project(root,checkpoint), archive=external(ctx.root,archiveDir);
+  if (!candidates?.length) fail('explicit-candidates-required');
+  candidates=[...new Set(candidates)].sort();
+  const scan=sources(ctx), actions=[];
+  for (const ref of candidates) {
+    if (!ref.startsWith(ctx.base+'/') || candidates.some(other=>other!==ref&&ref.startsWith(other+'/'))) fail('candidate-scope-invalid: '+ref);
+    const observed=tree(ctx.root,ref); if (!observed) fail('candidate-missing: '+ref);
+    const classification=classify(ctx,ref), refs=references(ctx,ref,scan);
+    const reasons=[];
+    if (refs.incoming.length) reasons.push('referenced-or-dynamic');
+    if (scan.unknown.length) reasons.push('scan-incomplete');
+    if (classification.action==='archive' && observed.type!=='file') reasons.push('archive-file-required');
+    if (classification.action==='delete-cache' && observed.type!=='directory') reasons.push('cache-directory-required');
+    if (classification.action==='keep') reasons.push(classification.kind);
+    actions.push({ref,...classification,action:reasons.length?'keep':classification.action,reasons,observed,...refs});
+  }
+  const payload={schema_version:1,kind:'feature-assets-plan',root:ctx.root,checkpoint,archive_dir:archive,tool_digest:toolDigest(),scan_digest:digest(json(scan.files.filter(f=>!candidates.includes(f.ref)).map(({ref,digest})=>({ref,digest})))),scan_unknown:scan.unknown,candidates,actions};
+  return {...payload,plan_id:digest(json(payload))};
+}
+function validatePlan(root,plan) {
+  const {plan_id,...payload}=plan;
+  if (plan.kind!=='feature-assets-plan'||plan.schema_version!==1||plan_id!==digest(json(payload))||plan.root!==fs.realpathSync(root)||plan.tool_digest!==toolDigest()) fail('invalid-or-changed-plan');
+  project(root,plan.checkpoint); external(plan.root,plan.archive_dir);
+  for(const item of plan.actions) { safeAssetPath(plan.root,item.ref); if(!plan.candidates.includes(item.ref))fail('invalid-plan-action'); }
+}
+function atomic(file,value) {
+  const temp=file+'.tmp-'+process.pid;
+  const fd=fs.openSync(temp,'wx',0o600);
+  try { fs.writeFileSync(fd,json(value)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  fs.renameSync(temp,file);
+}
+function validateReceipt(receipt,plan) {
+  if(receipt.schema_version!==1 || !Array.isArray(receipt.items) || receipt.items.length!==plan.actions.length)fail('invalid-receipt');
+  for(let i=0;i<plan.actions.length;i++) {
+    if(receipt.items[i].ref!==plan.actions[i].ref||receipt.items[i].action!==plan.actions[i].action)fail('invalid-receipt-action');
+  }
+}
+function lock(dir,fn) {
+  fs.mkdirSync(dir,{recursive:true,mode:0o700}); const file=safeAssetPath(dir,'.lock');
+  if (present(file)) {
+    const pid=Number(fs.readFileSync(file,'utf8'));
+    if(!Number.isSafeInteger(pid)||pid<=0)fail('invalid-transaction-lock');
+    try {process.kill(pid,0); fail('transaction-busy');} catch(e) {if(e.code!=='ESRCH')throw e;}
+    fs.unlinkSync(file);
+  }
+  fs.writeFileSync(file,String(process.pid),{flag:'wx',mode:0o600});
+  try {return fn();} finally {fs.unlinkSync(file);}
+}
+export function applyAssets({root,plan,onProgress=()=>{}}) {
+  validatePlan(root,plan);
+  const dir=plan.archive_dir,receiptFile=path.join(dir,'receipt.json');
+  return lock(dir,()=>{
+    const prior=present(receiptFile)?JSON.parse(fs.readFileSync(safeAssetPath(dir,'receipt.json'))):null;
+    if(prior && (!same(prior.plan,plan)||prior.plan_id!==plan.plan_id))fail('receipt-plan-conflict');
+    if(prior)validateReceipt(prior,plan);
+    if(prior && ['applied','restored'].includes(prior.status))return {...prior,receipt_ref:receiptFile,reused:true};
+    if(!prior) {
+      const expected=planAssets({root,checkpoint:plan.checkpoint,candidates:plan.candidates,archiveDir:plan.archive_dir});
+      if(!same(expected,plan))fail('plan-no-longer-current');
+      if(fs.readdirSync(dir).some(name=>name!=='.lock'))fail('archive-directory-not-owned');
+    }
+    const ctx=project(root,plan.checkpoint), scan=sources(ctx);
+    const scanDigest=digest(json(scan.files.filter(f=>!plan.candidates.includes(f.ref)).map(({ref,digest})=>({ref,digest}))));
+    if(scanDigest!==plan.scan_digest || !same(scan.unknown,plan.scan_unknown))fail('reference-input-drift');
+    const receipt=prior||{schema_version:1,plan_id:plan.plan_id,plan,status:'running',items:plan.actions.map(item=>({ref:item.ref,action:item.action,status:item.action==='keep'?'kept':'pending'}))};
+    const save=()=>atomic(receiptFile,receipt);
+    save();
+    for(const item of receipt.items) {
+      if(['archived','deleted','kept'].includes(item.status))continue;
+      const action=plan.actions.find(a=>a.ref===item.ref), source=safeAssetPath(ctx.root,item.ref), current=tree(ctx.root,item.ref);
+      const backupRef='files/'+item.ref,backup=safeAssetPath(dir,backupRef);
+      if(!current && item.status==='copied' && same(tree(dir,backupRef),action.observed)) {item.status='archived';save();continue;}
+      if(!current && item.status==='deleting') {item.status='deleted';save();continue;}
+      const resumableDelete=item.status==='deleting' && action.action==='delete-cache' && remainingMatches(current,action.observed);
+      if(!same(current,action.observed)&&!resumableDelete)fail('candidate-input-drift: '+item.ref);
+      if(action.action==='delete-cache') {
+        const occupancy=cacheOccupancy(source);
+        if(occupancy.status!=='free') {item.status='retained';item.occupancy=occupancy;save();continue;}
+        item.status='deleting';save();onProgress({event:'before-delete',ref:item.ref});
+        if(!remainingMatches(tree(ctx.root,item.ref),action.observed)||cacheOccupancy(source).status!=='free')fail('cache-became-busy-or-changed');
+        fs.rmSync(source,{recursive:true}); item.status='deleted'; save();
+      } else if(action.action==='archive') {
+        fs.mkdirSync(path.dirname(backup),{recursive:true,mode:0o700});
+        if(!present(backup)) {fs.copyFileSync(source,backup,fs.constants.COPYFILE_EXCL);fs.chmodSync(backup,action.observed.mode);}
+        if(!same(tree(dir,backupRef),action.observed))fail('archive-verification-failed');
+        item.status='copied';save();onProgress({event:'copied',ref:item.ref});
+        if(!same(tree(ctx.root,item.ref),action.observed))fail('archive-source-changed');
+        fs.unlinkSync(source);item.status='archived';save();
+      }
+    }
+    receipt.status=receipt.items.some(i=>i.status==='retained')?'partial':'applied';save();
+    return {...receipt,receipt_ref:receiptFile};
+  });
+}
+export function restoreAssets({root,receiptRef}) {
+  root=fs.realpathSync(root); const file=external(root,receiptRef),dir=path.dirname(file);
+  if(path.basename(file)!=='receipt.json')fail('receipt-path-invalid');
+  return lock(dir,()=>{
+    const receipt=JSON.parse(fs.readFileSync(safeAssetPath(dir,'receipt.json'))),plan=receipt.plan;
+    validatePlan(root,plan); if(plan.archive_dir!==dir || receipt.plan_id!==plan.plan_id)fail('receipt-location-invalid');
+    validateReceipt(receipt,plan);
+    const restores=receipt.items.filter(i=>i.action==='archive'&&['archived','copied','restored'].includes(i.status));
+    for(const item of restores) {
+      const expected=plan.actions.find(a=>a.ref===item.ref)?.observed;
+      if(!expected||!same(tree(dir,'files/'+item.ref),expected))fail('archive-integrity-failed');
+      const current=tree(root,item.ref);if(current&&!same(current,expected))fail('restore-conflict: '+item.ref);
+    }
+    for(const item of restores) {
+      const target=safeAssetPath(root,item.ref),expected=plan.actions.find(a=>a.ref===item.ref).observed;
+      if(!present(target)) {
+        fs.mkdirSync(path.dirname(target),{recursive:true});safeAssetPath(root,item.ref);
+        fs.copyFileSync(safeAssetPath(dir,'files/'+item.ref),target,fs.constants.COPYFILE_EXCL);fs.chmodSync(target,expected.mode);
+        if(!same(tree(root,item.ref),expected))fail('restore-verification-failed');
+      }
+      item.status='restored';atomic(file,receipt);
+    }
+    receipt.status='restored';atomic(file,receipt);return {...receipt,receipt_ref:file};
+  });
+}

package/template/scripts/lib/governance-io.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseDocument } from '../vendor/yaml.mjs';
+
+export const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+export function safeFile(root, ref) {
+  if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || /[\\\x00-\x1f:#?]/.test(ref) || ref.split('/').some(p=>!p||p==='.'||p==='..')) throw new Error(`非法治理引用: ${ref}`);
+  let file=fs.realpathSync(root);
+  for(const part of ref.split('/')) {
+    file=path.join(file,part);
+    try { if(fs.lstatSync(file).isSymbolicLink()) throw new Error(`治理引用禁止符号链接: ${ref}`); }
+    catch(error) { if(error.code!=='ENOENT') throw error; }
+  }
+  return file;
+}
+export function readDocument(root, ref) {
+  const bytes=fs.readFileSync(safeFile(root,ref));
+  const doc=parseDocument(bytes.toString('utf8'),{uniqueKeys:true,maxAliasCount:0});
+  if(doc.errors.length) throw new Error(`${ref}: ${doc.errors[0].message}`);
+  return doc.toJS({maxAliasCount:0});
+}
+export function fileBinding(root, ref) {
+  const file=safeFile(root,ref);
+  try { if(!fs.statSync(file).isFile()) throw new Error(`治理引用不是文件: ${ref}`); return digest(fs.readFileSync(file)); }
+  catch(error) { if(error.code==='ENOENT')return null; throw error; }
+}
+
+export function orchestrationRef(root) {
+  const profileRef='.template-spec/process/harness-profile.yaml';
+  if(!fileBinding(root,profileRef))return '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const profile=readDocument(root,profileRef).profile_id;
+  const owner={
+    'harness.business-ddd-strategy-handoff':'yss-strategic-design',
+    'harness.backend-delivery':'harness-orchestrator',
+    'harness.frontend-delivery':'harness-orchestrator'
+  }[profile];
+  if(!owner)throw new Error(`未知生命周期 profile: ${profile}`);
+  return `.agents/skills/${owner}/references/orchestration-contract.yaml`;
+}

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

@@ -33,7 +33,7 @@ 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});
+    assertScopeWorkUnit(task.contract?.kind==='slice-implementation'?'work-unit.slice-implementation':task.work_unit_id,{root,readOnly:task.contract?.kind==='read-only-intake'});
     ensure(task.role_id!=='role.frontend-engineer','后端职责不允许派发前端实现');
     ensure(task.allowed_write_paths.every(ref=>!/^apps\/frontend(?:\/|$)/.test(ref)),'禁止写入前端工程');
   }

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

@@ -1,4 +1,5 @@
 import { resolveBackendPlatform, resolveComponentCapabilities } from "./backend-platform.mjs";
+import { executionEvidenceBlockers } from './execution-evidence.mjs';
 import { safe } from './strategic-handoff-io.mjs';
 import { selectSliceWorkUnit, normalizeSliceContract, withinSlicePath } from './slice-contract.mjs';
 import { createApprovedExecutionContext, createApprovedRecompilationContext, assertApprovedExecutionContext } from './approved-execution-context.mjs';
@@ -349,6 +350,7 @@ export function validateExecutionResult(result, contract, current) {
     else if (item.exit_code !== 0) blockers.push("verification-failed");
   }
   if(contract.schema_version===3) {
+    blockers.push(...executionEvidenceBlockers(result, contract, {...current, root: current.root || ROOT}));
     const unit=contract.work_units.find(item=>item.id===result.work_unit_id);
     if(!unit)blockers.push('work-unit-mismatch');
     else {

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

@@ -1,6 +1,6 @@
 import { loadExecutionScope, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync, withValidationPhase, validationDependencies } from "./validation-phase.mjs";
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { ROOT, loadRegistry, semanticDigest, validateRegistry } from "./lifecycle-registry.mjs";
@@ -63,11 +63,19 @@ function selectedSkills(route, skillRegistry) {
   return skillRegistry.skills.filter((skill) => ids.has(skill.id));
 }
 
-export function queryLifecycleContext({ mode, stageId, workUnitId, include = [] } = {}) {
+export function queryLifecycleContext(options = {}) {
+  return withValidationPhase({ root: ROOT, purpose: "lifecycle-context-query", readOnly: true }, () => querySnapshot(options));
+}
+
+function querySnapshot({ mode, stageId, workUnitId, include = [] } = {}) {
   if (!mode && !stageId && !workUnitId && include.length === 0) {
     throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --include 之一");
   }
 
+  const identity = loadYaml("yss-project.yaml", "仓库身份");
+  if (identity.schema_version !== 1 || !["template-source", "project-instance"].includes(identity.repository_mode)) {
+    throw new TypeError("仓库身份或版本无效");
+  }
   const scope = loadExecutionScope();
   if (workUnitId) assertScopeWorkUnit(workUnitId, { readOnly: true });
   const lifecycle = validateRegistry(loadRegistry());
@@ -114,9 +122,11 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
       work_unit: workUnitId ?? null,
     },
     sources: {
+      repository_identity: { ref: "yss-project.yaml", sha256: sha256(read("yss-project.yaml")) },
       lifecycle_registry: {
         ref: LIFECYCLE_REGISTRY_REF,
         semantic_sha256: semanticDigest(lifecycle),
+        sha256: sha256(read(LIFECYCLE_REGISTRY_REF)),
         status: lifecycle.status,
       },
       orchestration_contract: {
@@ -152,5 +162,7 @@ export function queryLifecycleContext({ mode, stageId, workUnitId, include = []
   result.references = [...collectPathReferences(result), LIFECYCLE_REGISTRY_REF, ORCHESTRATION_CONTRACT_REF, SKILL_REGISTRY_REF]
     .filter((value, index, all) => all.indexOf(value) === index)
     .sort();
-  return canonicalize(result);
+  result.sources.read_set = validationDependencies().files.map(row=>({ref:path.relative(ROOT,row.file).split(path.sep).join("/"),sha256:row.digest})).sort((a,b)=>a.ref.localeCompare(b.ref,"en"));
+  const canonical = canonicalize(result);
+  return { ...canonical, context_sha256: sha256(JSON.stringify(canonical)) };
 }