create-yss-spec 3.5.3 → 3.5.4

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

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { assertCheckpointBoundary } from './checkpoint-boundary.mjs';
+import { safeFile, fileBinding, readDocument, digest, orchestrationRef } from './governance-io.mjs';
+
+export const CI_CONFIG='.template-spec/process/project-ci.yaml';
+export const TRACKER='.template-spec/agents/issue-tracker.md';
+export function parseGovernance(bytes, ref) {
+  const source=String(bytes), yaml=ref.endsWith('.md')?source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1]:source;
+  if(yaml===undefined)return null;
+  const doc=parseDocument(yaml,{uniqueKeys:true,maxAliasCount:0});
+  if(doc.errors.length)throw new Error(`${ref}: ${doc.errors[0].message}`);
+  return doc.toJS({maxAliasCount:0});
+}
+export function governanceScope(root) {
+  const identity=readDocument(root,'yss-project.yaml');
+  if(identity?.schema_version!==1||identity.repository_mode!=='project-instance')throw new Error('project-ci 仅适用于 project-instance');
+  const tracker=parseGovernance(fs.readFileSync(safeFile(root,TRACKER)),TRACKER)?.tracker;
+  if(!tracker||!['local-markdown','github','gitlab'].includes(tracker.platform)||typeof tracker.root!=='string')throw new Error('主 tracker 配置无效');
+  const config=fileBinding(root,CI_CONFIG)?readDocument(root,CI_CONFIG):{schema_version:1,provider:'github',branch:'main',additional_paths:[]};
+  if(config.schema_version!==1||config.provider!=='github'||!Array.isArray(config.additional_paths)||config.additional_paths.some(x=>typeof x!=='string'))throw new Error('project-ci 配置无效');
+  const roots=[...new Set([tracker.root.replace(/\/$/,''),...config.additional_paths])].sort();
+  roots.forEach(ref=>safeFile(root,ref));
+  return {roots,config,trackerRoot:tracker.root.replace(/\/$/,'')};
+}
+export function governanceFiles(root, roots) {
+  const result=[];
+  const visit=ref=>{
+    const full=safeFile(root,ref);
+    if(!fs.existsSync(full))return;
+    const st=fs.lstatSync(full);
+    if(st.isDirectory()) for(const name of fs.readdirSync(full).sort())visit(`${ref}/${name}`);
+    else if(st.isFile())result.push(ref);
+    else throw new Error(`治理范围含不支持的文件: ${ref}`);
+  };
+  roots.forEach(visit);return [...new Set(result)].sort();
+}
+const checkpoint=(value,ref)=>/(?:^|\/)checkpoint\.(?:yaml|yml|json)$/.test(ref)||Boolean(value?.repository_mode&&value?.stage&&value?.gates);
+const claimed=value=>Boolean(value&&typeof value==='object'&&(['approved','completed','ready-for-agent','running','paused-human-gate'].includes(value.status)||['active','paused','failed','resolved'].includes(value.workflow_status)||value.result==='completed'||value.decision==='approved'||Object.values(value.gates||{}).some(x=>x?.status==='approved')||Object.values(value.artifacts||{}).some(x=>x?.status==='approved')));
+const identityRefs=new Set(['term_refs','skill_refs','principal_ref','drafter_principal_ref','requester_ref','responder_ref','runtime_instance_ref','original_ref','owner_ref']);
+const fileReference=item=>typeof item==='string'&&!/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(item)&&! /^(?:gate|artifact|work-unit|stage|evidence|check|skill|runtime|role)\.[a-z0-9-]+$/.test(item)&&/[./]/.test(item);
+function references(value, found=new Set()) {
+  if(Array.isArray(value))for(const item of value)references(item,found);
+  else if(value&&typeof value==='object')for(const [key,item] of Object.entries(value)) {
+    if(identityRefs.has(key))continue;
+    if((key==='ref'||key.endsWith('_ref'))&&fileReference(item))found.add(item);
+    else if((key.endsWith('_refs')||key==='inputs')&&Array.isArray(item))for(const ref of item)if(fileReference(ref))found.add(ref);
+    if(item&&typeof item==='object')references(item,found);
+  }
+  return found;
+}
+function bindings(value, output=[]) {
+  if(Array.isArray(value))for(const item of value)bindings(item,output);
+  else if(value&&typeof value==='object') {
+    if(typeof value.ref==='string'&&(value.digest||value.sha256))output.push([value.ref,value.digest||value.sha256]);
+    for(const [key,item] of Object.entries(value)) {
+      if(key.endsWith('_ref')&&typeof item==='string'&&value[key.replace(/_ref$/,'_digest')])output.push([item,value[key.replace(/_ref$/,'_digest')]]);
+      if(item&&typeof item==='object')bindings(item,output);
+    }
+  }
+  return output;
+}
+
+/** Fixed validators only. Checkpoint verification commands are data, never executable input. */
+export function checkProjectGovernance({root,base,checkpointRef,taskRef,recovery=false}={}) {
+  root=fs.realpathSync(root);
+  const report={schema_version:1,kind:'project-governance-verification',read_only:true,execution_authorization:'not-evaluated',status:'passed',checks:[],diagnostics:[],inputs:[],scope:{roots:[],files:[],checkpoints:[],tasks:[],unrecognized:[],missing_capabilities:[]},base:base||null};
+  const observed=new Map();
+  const issue=(code,message,ref,exception=false)=>{report.diagnostics.push({code,message,source_ref:ref,recovery:'修复明确输入或证据后重新运行当前校验'});report.status=exception?'error':report.status==='error'?'error':'failed';};
+  const observe=ref=>{const hash=fileBinding(root,ref);if(observed.has(ref)&&observed.get(ref)!==hash)throw new Error(`INPUT_DRIFT: ${ref}`);observed.set(ref,hash);return hash;};
+  const read=ref=>{if(!observe(ref))throw new Error(`输入不可读: ${ref}`);return fs.readFileSync(safeFile(root,ref));};
+  const run=(id,script,args,refs)=>{
+    const requirements={
+      'scripts/verify-lifecycle-checkpoint':['.template-spec/process/schemas/lifecycle-checkpoint.schema.json'],
+      'scripts/verify-digital-human-task-package':['.template-spec/process/schemas/digital-human-task-package.schema.json','.template-spec/agents/digital-human-roles.yaml'],
+      'scripts/verify-approval-record':['.template-spec/agents/digital-human-roles.yaml']
+    };
+    const missing=[script,...(requirements[script]||[])].filter(ref=>!observe(ref));
+    if(missing.length){report.scope.missing_capabilities.push(...missing);report.checks.push({id,command:[process.execPath,script,...args],input_refs:refs,exit_code:null,status:'unavailable',missing});issue('capability-missing',`缺少适用校验能力 ${missing.join(', ')}，先显式安装对应阶段资产`,script,true);return;}
+    const begin=performance.now(),result=spawnSync(process.execPath,[safeFile(root,script),...args],{cwd:root,encoding:'utf8',maxBuffer:8*1024*1024,timeout:120000});
+    const unavailable=result.error||result.status===null||result.status===2||/ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ModuleNotFoundError/.test(result.stderr||'');
+    report.checks.push({id,command:[process.execPath,script,...args],input_refs:refs,exit_code:result.status,duration_ms:Math.round(performance.now()-begin),stdout:result.stdout||'',stderr:result.stderr||result.error?.message||'',status:result.status===0?'passed':'failed'});
+    if(result.status!==0)issue(unavailable?'capability-unavailable':'validation-failed',`${id}: ${result.error?.message||result.stderr||result.stdout}`,refs[0],Boolean(unavailable));
+  };
+  try {
+    for(const ref of ['yss-project.yaml',TRACKER,CI_CONFIG,'CONTEXT.md','.template-spec/process/harness-profile.yaml','.template-spec/process/checkpoint-boundary.yaml','.template-spec/process/lifecycle-registry.yaml','.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml'])observe(ref);
+    const {roots}=governanceScope(root);report.scope.roots=roots;
+    const registry=readDocument(root,'.template-spec/process/lifecycle-registry.yaml');
+    observe(orchestrationRef(root));
+    const initial=governanceFiles(root,roots);report.scope.files=initial;
+    // Validator code/schema changes invalidate this run too; do not import future Skill validators.
+    const toolFiles=governanceFiles(root,['scripts','.template-spec/process/schemas','.template-spec/agents','.agents/skills/yss-product-lifecycle']);
+    toolFiles.forEach(observe);
+    run('context','scripts/verify-context-contract',['--root',root,'--json'],['CONTEXT.md']);
+    report.recovery = recovery ? {sequence:['context','checkpoint','approval','transition','task-package'],dispatch:false,action:'复核实际任务结果及当前证据后由主控继续',prerequisites:['当前适用检查通过','原任务结果明确']} : null;
+    const queue=checkpointRef?[checkpointRef]:initial.filter(ref=>/\.(?:ya?ml|json|md)$/.test(ref));
+    if(taskRef)queue.push(taskRef);
+    const strictRefs=new Set([checkpointRef,taskRef].filter(Boolean));
+    const seen=new Set(),values=new Map(),claimFiles=new Set(),tickets=[];
+    while(queue.length) {
+      const ref=queue.shift();if(seen.has(ref))continue;seen.add(ref);
+      let bytes,value;
+      try{bytes=read(ref);value=parseGovernance(bytes,ref);}catch(error){issue('input-invalid',error.message,ref,true);continue;}
+      values.set(ref,value);
+      const isCheckpoint=checkpoint(value,ref),isTask=Boolean(value?.task_id&&value?.work_unit_id&&(value?.contract||['active','paused','failed','resolved'].includes(value.workflow_status)));
+      if(isCheckpoint) {
+        report.scope.checkpoints.push(ref);
+        if(value.repository_mode!=='project-instance')issue('checkpoint-identity-mismatch','checkpoint 身份与项目实例不一致',ref);
+        const nextUnit=registry.work_units.find(x=>x.id===value.next_work_unit);
+        if(nextUnit?.scope==='template-source'&&nextUnit.id!=='work-unit.entry-triage')issue('work-unit-scope-invalid','项目实例不得路由模板维护工作单元',ref);
+        for(const id of Object.keys(value.artifacts||{}))if(!registry.artifacts.some(x=>x.id===id))issue('artifact-id-unknown',`未识别生命周期资产 ID: ${id}`,ref);
+        try{assertCheckpointBoundary(value,{root});}catch(error){issue('checkpoint-boundary-invalid',error.message,ref);}
+        run('checkpoint','scripts/verify-lifecycle-checkpoint',[ref],[ref]);
+        if(claimed(value))claimFiles.add(ref);
+        if(value.stage_trace?.completed_work_unit)run('transition','scripts/project-ci-transition',[ref],[ref]);
+        else if(['running','completed'].includes(value.status)&&['resume','orchestrate'].includes(value.mode))issue('transition-origin-missing','当前流转缺少 stage_trace.completed_work_unit，无法核验前后因果',ref);
+        if(recovery&&(value.blockers?.length||['blocked','stale'].includes(value.status)))issue('recovery-blocked','当前 checkpoint 存在阻塞',ref);
+      } else if(isTask) {
+        report.scope.tasks.push(ref);run('task-package','scripts/verify-digital-human-task-package',[ref],[ref]);
+        if(recovery) {
+          const status=value.workflow_status;
+          if(status==='resolved'&&!value.result?.evidence_refs?.length&&!value.verification_results?.length)issue('task-result-unknown','resolved 任务缺少实际结果引用，不能判定完成',ref);
+          if(status!=='resolved')issue('task-not-resolved',`任务状态 ${status||'unknown'}；先核查原任务，禁止重复派发`,ref);
+        }
+      } else if(value?.gate_id&&value?.decision==='approved') {
+        run('approval','scripts/verify-approval-record',['--require-approved',ref],[ref]);
+      } else if(claimed(value)) {
+        // Claimed assets need an owning checkpoint; owner-specific validators are called through it.
+        claimFiles.add(ref);
+      } else report.scope.unrecognized.push(ref);
+      if(/(?:^|\n)Status:\s*ready-for-agent\s*(?:\n|$)/.test(bytes.toString()))tickets.push(ref);
+      if(isCheckpoint||isTask||claimed(value)||value?.gate_id||strictRefs.has(ref)) {
+        for(const dependency of references(value)) {
+          if(!strictRefs.has(dependency)){strictRefs.add(dependency);seen.delete(dependency);}
+          try{read(dependency);if(/\.(?:ya?ml|json|md)$/.test(dependency))queue.push(dependency);}catch(error){issue('reference-unreadable',error.message,ref);}
+        }
+        for(const [target,hash] of bindings(value)) {
+          try{const actual=observe(target);if(actual!==String(hash).replace(/^(?!sha256:)/,'sha256:'))issue('evidence-drift',`摘要不一致: ${target}`,ref);}catch(error){issue('evidence-unreadable',error.message,ref);}
+        }
+      }
+    }
+    if(checkpointRef&&!report.scope.checkpoints.includes(checkpointRef))issue('checkpoint-unrecognized','指定引用不是可识别的 checkpoint',checkpointRef);
+    if(taskRef&&!report.scope.tasks.includes(taskRef))issue('task-unrecognized','指定引用不是可识别的任务包',taskRef);
+    const owned=new Set();
+    const owningQueue=[...report.scope.checkpoints];
+    while(owningQueue.length)for(const dependency of references(values.get(owningQueue.shift())))if(!owned.has(dependency)){owned.add(dependency);owningQueue.push(dependency);}
+    for(const ref of claimFiles)if(!report.scope.checkpoints.includes(ref)) {
+      if(!owned.has(ref))issue('claim-without-checkpoint','已声明完成或批准的资产缺少 checkpoint 归属',ref);
+      else {
+        const asset=values.get(ref),contract=asset?.slice_contract||asset;
+        if(contract?.contract_id&&contract?.work_units)run('slice-contract','scripts/slice-contract',['verify',ref,'--root',root,'--json'],[ref]);
+        else {report.scope.unrecognized.push(ref);report.scope.missing_capabilities.push(ref);issue('asset-validator-missing','当前声称批准或完成的结构化资产缺少已接入的专属校验能力；补齐资产校验适配后重验',ref,true);}
+      }
+    }
+    for(const ref of tickets)if(!owned.has(ref)&&!report.scope.tasks.some(t=>references(values.get(t)).has(ref)))issue('ticket-without-readiness','ready-for-agent Ticket 缺少当前 checkpoint/任务包证据',ref);
+    if(base) {
+      if(!/^[a-fA-F0-9]{40}$/.test(base))throw new Error('--base 必须为完整 40 位 commit');
+      const git=args=>{const r=spawnSync('git',args,{cwd:root,encoding:'utf8',maxBuffer:16*1024*1024});if(r.status!==0)throw new Error(r.stderr||'Git 基线不可读');return r.stdout;};
+      git(['cat-file','-e',`${base}^{commit}`]);
+      const oldFiles=git(['ls-tree','-r','--name-only','-z',base]).split('\0').filter(Boolean);
+      const oldTracker=parseGovernance(git(['show',`${base}:${TRACKER}`]),TRACKER)?.tracker;
+      const oldConfig=oldFiles.includes(CI_CONFIG)?parseGovernance(git(['show',`${base}:${CI_CONFIG}`]),CI_CONFIG):{additional_paths:[]};
+      const oldRoots=[oldTracker?.root?.replace(/\/$/,''),...(oldConfig.additional_paths||[])].filter(Boolean);
+      for(const ref of oldRoots)if(!roots.some(r=>ref===r||ref.startsWith(r+'/')))issue('scope-reduced',`相对基线缩小检查范围: ${ref}`,CI_CONFIG);
+      const oldValues=new Map();
+      const oldRead=ref=>{if(!oldValues.has(ref))oldValues.set(ref,parseGovernance(git(['show',`${base}:${ref}`]),ref));return oldValues.get(ref);};
+      const oldScope=oldFiles.filter(ref=>oldRoots.some(r=>ref===r||ref.startsWith(r+'/'))&&/\.(?:ya?ml|json|md)$/.test(ref));
+      const oldEvidence=new Set(),oldQueue=[];
+      for(const ref of oldScope)if(claimed(oldRead(ref)))oldQueue.push(ref);
+      while(oldQueue.length){const ref=oldQueue.shift();if(oldEvidence.has(ref))continue;oldEvidence.add(ref);if(!observe(ref))issue('approved-evidence-deleted',`基线批准依据已删除: ${ref}`,ref);if(/\.(?:ya?ml|json|md)$/.test(ref)&&oldFiles.includes(ref))for(const dep of references(oldRead(ref)))if(oldFiles.includes(dep))oldQueue.push(dep);}
+      for(const ref of oldScope.filter(ref=>/\.(?:ya?ml|json)$/.test(ref))) {
+        const old=parseGovernance(git(['show',`${base}:${ref}`]),ref);
+        if(!checkpoint(old,ref))continue;
+        if(!observe(ref)){issue('checkpoint-deleted',`基线 checkpoint 已删除: ${ref}`,ref);continue;}
+        const now=values.get(ref);
+        if(!report.scope.checkpoints.includes(ref))issue('checkpoint-unassessed',`基线 checkpoint 不再被识别或检查: ${ref}`,ref);
+        for(const [id,state] of Object.entries(old.gates||{}))if(state.status==='approved'&&!now?.gates?.[id])issue('approval-claim-removed',`基线批准 ${id} 被移除，须保留历史与当前处置`,ref);
+        if(claimed(old))for(const dep of references(old))if(!observe(dep))issue('approved-evidence-deleted',`基线批准依据已删除: ${dep}`,ref);
+      }
+    }
+    if(JSON.stringify(initial)!==JSON.stringify(governanceFiles(root,roots))||JSON.stringify(toolFiles)!==JSON.stringify(governanceFiles(root,['scripts','.template-spec/process/schemas','.template-spec/agents','.agents/skills/yss-product-lifecycle'])))throw new Error('INPUT_DRIFT: 检查范围发生变化');
+    for(const [ref,hash] of observed)if(fileBinding(root,ref)!==hash)throw new Error(`INPUT_DRIFT: ${ref}`);
+  }catch(error){issue('input-or-execution-error',error.message,checkpointRef||null,true);}
+  report.scope.files=[...new Set([...report.scope.files,...observed.keys()].filter(ref=>!ref.startsWith('scripts/')&&!ref.startsWith('.agents/')))].sort();
+  report.inputs=[...observed].sort(([a],[b])=>a.localeCompare(b)).map(([ref,sha256])=>({ref,sha256}));
+  report.input_digest=digest(JSON.stringify(report.inputs));
+  return {report,exitCode:report.status==='passed'?0:report.status==='error'?2:1};
+}

package/template/scripts/lib/reading-view-adapters.mjs

@@ -0,0 +1,62 @@
+import {readingIdFields} from './reading-view-model.mjs';
+import path from 'node:path';
+import {readFileSync,existsSync} from './validation-phase.mjs';
+import {safe,hash} from './strategic-handoff-io.mjs';
+
+const orders={
+ 'domain-strategy':['contexts','subdomains','relationships','rule_catalog','scenarios','concept_candidates','invariants','downstream_mapping','status'],
+ 'stage-decision-package':['problem_statement','target_users','mvp','non_goals','confirmed_decisions','success_criteria','test_seams','assumptions','constraints','unresolved_items','downstream_mapping'],
+ checkpoint:['stage','status','next_work_unit','blockers','stage_tracking','artifacts','gates','verification','human_review']
+};
+export function adaptReading(kind,raw,{root,ref,blockers}){
+ if(kind==='tracking-migration')return migration(raw,{root,ref,blockers});
+ const order=orders[kind];if(!order)return raw;
+ const inspect=(value,collection)=>{
+  if(!value||typeof value!=='object')return;
+  if(Array.isArray(value)&&readingIdFields[collection]){const key=readingIdFields[collection],ids=value.map(x=>x?.[key]).filter(x=>typeof x==='string');if(new Set(ids).size!==ids.length)blockers.push(`duplicate-stable-id: ${collection}.${key}`);}
+  for(const [key,child]of Object.entries(value))inspect(child,key);
+ };inspect(raw);
+ const content=Object.fromEntries([...order,...Object.keys(raw)].filter((key,index,all)=>Object.hasOwn(raw,key)&&all.indexOf(key)===index).map(key=>[key,raw[key]]));
+ if(kind==='checkpoint')content.状态阅读说明={源声明:'上面的阶段、状态和工作项进度均为源声明，分别保留。',阻塞登记:Array.isArray(raw.blockers)&&!raw.blockers.length?'未登记阻塞；不等于可执行。':'按源记录检查；缺失不等于无阻塞。',未核验:'批准、完整门禁、Ticket 就绪及外部事实未核验；历史验证记录不能替代本次验证。'};
+ return content;
+}
+const LIMIT=2*1024*1024;
+function migration(plan,{root,ref,blockers}){
+ const content={...Object.fromEntries(Object.entries(plan).filter(([k])=>!['root','changes','observed','input','plan_id','schema_version'].includes(k))),plan_id:plan.plan_id,执行结果:'proposed（仅为计划；没有验证执行回执）',changes:[]};
+ try{
+  const {plan_id,...payload}=plan;
+  if(plan.schema_version!==1||!Array.isArray(plan.changes)||hash(JSON.stringify(payload)).slice(7)!==plan_id)throw Error('migration-plan-digest-mismatch');
+  const base=path.posix.dirname(ref),isPersisted=path.posix.basename(ref)==='plan.json';
+  let backups=[];
+  if(isPersisted){
+   for(const name of ['backup.json','receipt.json','failure.json']){
+    const target=`${base}/${name}`,file=safe(root,target,{missing:true});
+    if(!existsSync(file))continue;
+    const bytes=readFileSync(file);if(bytes.length>LIMIT*4)throw Error(`migration-preview-too-large: ${target}`);
+    const value=JSON.parse(bytes);
+    content[name.replace('.json','')+'_ref']=target;
+    if(name==='backup.json'){if(!Array.isArray(value))throw Error('migration-backup-invalid');backups=value;}
+    else if(name==='receipt.json'){if(value.plan_id!==plan_id||value.status!=='applied')throw Error('migration-receipt-conflict');content.执行结果='applied（原事务回执；不表示当前资产仍与历史一致）';content.回执=value;}
+    else {content.执行结果='failed（保留恢复冲突；回执不能覆盖失败记录）';content.失败记录=value;}
+   }
+  }
+  for(const change of plan.changes){
+   safe(root,change.ref,{missing:true});
+   if(typeof change.after!=='string'||Buffer.byteLength(change.after)>LIMIT)throw Error(`migration-preview-too-large-or-invalid: ${change.ref}`);
+   if(hash(change.after)!==change.after_digest)throw Error(`migration-after-digest-mismatch: ${change.ref}`);
+   let before=change.before?'无法比较旧内容：未提供匹配的历史备份；不读取当前文件冒充旧版本。':'原文件不存在（新增）';
+   const matches=backups.filter(row=>row.ref===change.ref);if(matches.length>1)throw Error('migration-backup-duplicate');
+   const backup=matches[0];
+   if(change.before&&backup){
+    if(typeof backup.bytes!=='string'||backup.bytes.length>LIMIT*1.4||!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(backup.bytes))throw Error('migration-backup-base64-invalid');
+    const bytes=Buffer.from(backup.bytes,'base64');
+    if(hash(bytes)!==change.before.digest||backup.before?.digest!==change.before.digest||backup.before?.mode!==change.before.mode)throw Error('migration-backup-digest-mismatch');
+    before=new TextDecoder('utf-8',{fatal:true}).decode(bytes);
+   }
+   content.changes.push({ref:change.ref,before,after:change.after,before_binding:change.before,after_digest:change.after_digest});
+  }
+  content.未展开字段={root:'本机位置不参与业务阅读',observed:'原计划中的事务读集；完整值见权威计划',input:'登记输入保留在原计划；不作为当前进度',恢复数据:'Base64 原备份不写回、不执行；上面仅展示经过摘要核对的 UTF-8 内容'};
+  content.gaps=plan.gaps;
+ }catch(error){blockers.push(error.message);content.诊断=error.message;}
+ return content;
+}

package/template/scripts/lib/reading-view-bundle.mjs

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {viewContract} from './contract-views.mjs';
+import {readFileSync,existsSync,withValidationPhase,validationDependencies} from './validation-phase.mjs';
+import {safe,hash,ROOT,schema} from './strategic-handoff-io.mjs';
+import {parseSliceYaml} from './slice-contract.mjs';
+import {READING_POLICY,readingPolicy,managedReading,readingLocation} from './reading-view-policy.mjs';
+const json=value=>JSON.stringify(value,null,2)+'\n';
+const BEGIN='<!-- YSS-READING:BEGIN -->',END='<!-- YSS-READING:END -->';
+const kinds={'artifact.domain-strategy':'domain-strategy',domain_strategy:'domain-strategy','domain-strategy':'domain-strategy','artifact.stage-decision-package':'stage-decision-package',stage_decision:'stage-decision-package','stage-decision-package':'stage-decision-package'};
+const bytes=(root,ref)=>{const file=safe(root,ref,{missing:true});return existsSync(file)?readFileSync(file):null;};
+const descriptor=(root,ref)=>{const b=bytes(root,ref);return b===null?null:hash(b);};
+function identity(root){const id=parseSliceYaml(bytes(root,'yss-project.yaml'));if(id?.schema_version!==1||id.repository_mode!=='project-instance')throw Error('reading-project-instance-required');}
+function toolClosure(){
+ const found=new Map();
+ const visit=ref=>{if(found.has(ref))return;const file=safe(ROOT,ref),content=readFileSync(file);found.set(ref,hash(content));
+  if(/\.(mjs|js)$/.test(ref))for(const match of content.toString().matchAll(/(?:from\s*|import\s*)['"](\.[^'"]+)['"]/g))visit(path.posix.normalize(path.posix.join(path.posix.dirname(ref),match[1])));
+ };
+ for(const ref of ['scripts/lib/reading-view-bundle.mjs','scripts/contract'])visit(ref);
+ return Object.fromEntries([...found].sort(([a],[b])=>a.localeCompare(b)));
+}
+function navigation(text){
+ const starts=text.split(BEGIN).length-1,ends=text.split(END).length-1;
+ if(!starts&&!ends)return {manual:text,block:null};
+ if(starts!==1||ends!==1||text.indexOf(END)<text.indexOf(BEGIN))throw Error('reading-navigation-marker-conflict');
+ const a=text.indexOf(BEGIN),b=text.indexOf(END)+END.length;
+ return {manual:text.slice(0,a)+text.slice(b),block:text.slice(a,b),a,b};
+}
+function build(root,checkpoint){
+ return withValidationPhase({root,purpose:'reading-bundle',readOnly:true},()=>{
+  identity(root);readingPolicy(root);
+  if(!bytes(root,'CONTEXT.md'))throw Error('reading-context-required');
+  const loc=readingLocation(checkpoint),raw=parseSliceYaml(bytes(root,checkpoint)),assets=[{ref:checkpoint,kind:'checkpoint'}],seen=new Set();
+  for(const [key,value]of Object.entries(raw.artifacts||{})){
+   const kind=kinds[key];if(!kind)continue;
+   const ref=typeof value==='string'?value:value?.ref;
+   if(!ref){if(['missing','not-applicable'].includes(value?.status))continue;throw Error(`reading-artifact-ref-required: ${key}`);}
+   if(seen.has(kind))throw Error(`reading-artifact-duplicate: ${kind}`);seen.add(kind);assets.push({ref,kind});
+  }
+  const outputs={},diagnostics=[],referenceBindings=[];
+  const bindReferences=(value,key='')=>{
+   if(typeof value==='string'&&(/^(ref|.*_ref|evidence_refs)$/.test(key))&&(/^(docs\/|\.template-spec\/|CONTEXT\.md)/.test(value))){
+    const ref=value.split('#')[0];
+    if(ref.startsWith(loc.directory+'/')||ref===loc.base+'/map.md')throw Error('reading-self-dependency');
+    referenceBindings.push({scope:'project',ref,digest:descriptor(root,ref)});
+   }else if(value&&typeof value==='object')for(const [child,v]of Object.entries(value))bindReferences(v,Array.isArray(value)?key:child);
+  };
+  bindReferences(raw);
+  for(const asset of assets){
+   bindReferences(parseSliceYaml(bytes(root,asset.ref)));
+   const view=viewContract(asset.ref,{root,kind:asset.kind});
+   diagnostics.push(...view.blockers.map(reason=>({ref:asset.ref,reason})));
+   const name=asset.kind==='checkpoint'?'status':asset.kind;
+   outputs[`${loc.directory}/${name}.review.md`]=view.markdown;
+  }
+  const block=[BEGIN,'## 阅读导航','',...Object.keys(outputs).map(ref=>`- [${path.posix.basename(ref)}](./${path.posix.relative(loc.base,ref)})`),'','以上为来源快照；提交审阅或交接前运行 `scripts/contract check-views --checkpoint '+checkpoint+'`。',END].join('\n');
+  const renderer=toolClosure();
+  readFileSync(safe(ROOT,'.template-spec/process/schemas/reading-manifest.schema.json'));
+  const dependencies=validationDependencies().files.map(row=>{
+   const local=path.relative(root,row.file);return !local.startsWith('..')&&!path.isAbsolute(local)?{scope:'project',ref:local,digest:'sha256:'+row.digest}:{scope:'tool',ref:path.relative(ROOT,row.file),digest:'sha256:'+row.digest};
+  }).sort((a,b)=>(a.scope+a.ref).localeCompare(b.scope+b.ref));
+  for(const row of referenceBindings)if(!dependencies.some(item=>item.scope===row.scope&&item.ref===row.ref))dependencies.push(row);
+  // A missing policy is also an input; adding one invalidates the previous package.
+  if(!dependencies.some(row=>row.scope==='project'&&row.ref===READING_POLICY))dependencies.push({scope:'project',ref:READING_POLICY,digest:null});
+  const manifest={schema_version:1,checkpoint_ref:checkpoint,renderer,dependencies,outputs:Object.fromEntries(Object.entries(outputs).map(([ref,text])=>[ref,hash(text)])),navigation:{ref:`${loc.base}/map.md`,block_digest:hash(block)},diagnostics};
+  schema(manifest,'.template-spec/process/schemas/reading-manifest.schema.json');
+  return {loc,outputs,block,manifest};
+ });
+}
+function oldManifest(root,loc){
+ const value=bytes(root,`${loc.directory}/.manifest.json`);if(!value)return null;
+ try{const m=JSON.parse(value);if(m.schema_version!==1||!m.outputs||!m.navigation||typeof m.outputs!=='object')throw Error();
+  for(const ref of Object.keys(m.outputs))if(!new RegExp(`^${loc.directory.replaceAll('.','\\.')}/(?:domain-strategy|stage-decision-package|status)\\.review\\.md$`).test(ref))throw Error();
+  if(m.navigation.ref!==`${loc.base}/map.md`)throw Error();return m;
+ }catch{throw Error('reading-manifest-invalid: preserve files; restore last valid manifest before rebuilding');}
+}
+function changesFor(root,built){
+ const old=oldManifest(root,built.loc),changes=[],mapRef=built.manifest.navigation.ref,mapBytes=bytes(root,mapRef),currentMap=mapBytes?.toString('utf8')||'',nav=navigation(currentMap);
+ for(const [ref,text]of Object.entries(built.outputs)){
+  const before=bytes(root,ref);if(before&&(!old?.outputs[ref]||hash(before)!==old.outputs[ref]))throw Error(`reading-output-conflict: ${ref}`);
+  if(!before||before.toString('utf8')!==text)changes.push({ref,before:before?.toString('base64')??null,after:Buffer.from(text).toString('base64')});
+ }
+ for(const ref of Object.keys(old?.outputs||{}))if(!Object.hasOwn(built.outputs,ref))throw Error(`reading-retired-output-needs-review: ${ref}`);
+ if(nav.block&&(!old||hash(nav.block)!==old.navigation.block_digest))throw Error(`reading-output-conflict: ${mapRef}`);
+ const nextMap=nav.block?currentMap.slice(0,nav.a)+built.block+currentMap.slice(nav.b):currentMap+(currentMap.endsWith('\n')?'':'\n')+'\n'+built.block+'\n';
+ if(nextMap!==currentMap)changes.push({ref:mapRef,before:mapBytes?.toString('base64')??null,after:Buffer.from(nextMap).toString('base64')});
+ const manifestRef=`${built.loc.directory}/.manifest.json`,before=bytes(root,manifestRef),after=json(built.manifest);
+ if(before?.toString('utf8')!==after)changes.push({ref:manifestRef,before:before?.toString('base64')??null,after:Buffer.from(after).toString('base64')});
+ return changes;
+}
+function verifyInputs(root,built){
+ for(const row of built.manifest.dependencies)if(descriptor(row.scope==='project'?root:ROOT,row.ref)!==row.digest)throw Error(`reading-input-drift: ${row.ref}`);
+ if(json(toolClosure())!==json(built.manifest.renderer))throw Error('reading-renderer-drift');
+}
+function atomic(root,ref,value){const file=safe(root,ref,{missing:true});fs.mkdirSync(path.dirname(file),{recursive:true});const tmp=`${file}.tmp-${randomUUID()}`;try{fs.writeFileSync(tmp,value,{flag:'wx',mode:fs.existsSync(file)?fs.statSync(file).mode&0o777:0o644});safe(root,ref,{missing:true});fs.renameSync(tmp,file);}finally{if(fs.existsSync(tmp))fs.unlinkSync(tmp);}}
+function same(root,ref,encoded){const current=bytes(root,ref);return encoded===null?current===null:current!==null&&hash(current)===hash(Buffer.from(encoded,'base64'));}
+function recover(root,loc){
+ const ref=`${loc.directory}/.transaction.json`,content=bytes(root,ref);if(!content)return;
+ const journal=JSON.parse(content);
+ if(journal.schema_version!==1||!Array.isArray(journal.changes))throw Error('reading-recovery-journal-invalid');
+ for(const c of journal.changes){if(![`${loc.base}/map.md`,`${loc.directory}/.manifest.json`,...['domain-strategy','stage-decision-package','status'].map(k=>`${loc.directory}/${k}.review.md`)].includes(c.ref)||!(c.before===null||typeof c.before==='string')||typeof c.after!=='string')throw Error('reading-recovery-journal-invalid');}
+ const conflicts=[];
+ for(const c of [...journal.changes].reverse()){
+  if(same(root,c.ref,c.before))continue;
+  if(!same(root,c.ref,c.after)){conflicts.push(c.ref);continue;}
+  if(c.before===null)fs.unlinkSync(safe(root,c.ref));else atomic(root,c.ref,Buffer.from(c.before,'base64'));
+ }
+ if(conflicts.length)throw Error(`reading-recovery-conflict: ${conflicts.join(', ')}`);
+ fs.unlinkSync(safe(root,ref));
+}
+function locked(root,loc,action){
+ const lockRef=`${loc.directory}/${loc.lock_name||'.lock'}`,file=safe(root,lockRef,{missing:true});fs.mkdirSync(path.dirname(file),{recursive:true});
+ if(fs.existsSync(file)){
+  const old=fs.readFileSync(file);let pid;try{pid=JSON.parse(old).pid;if(!Number.isInteger(pid)||pid<=0)throw Error();}catch{throw Error('reading-lock-invalid');}
+  try{process.kill(pid,0);throw Error('reading-busy');}catch(error){if(error.code!=='ESRCH')throw error;}
+  const recoveryLock=safe(root,`${lockRef}.recovery`,{missing:true});
+  fs.writeFileSync(recoveryLock,String(process.pid),{flag:'wx'});
+  try{if(!fs.existsSync(file)||hash(fs.readFileSync(file))!==hash(old))throw Error('reading-busy');fs.unlinkSync(file);}
+  finally{fs.unlinkSync(recoveryLock);}
+ }
+ const token=json({pid:process.pid,token:randomUUID()});fs.writeFileSync(file,token,{flag:'wx'});
+ try{if(loc.recover!==false)recover(root,loc);return action();}finally{if(fs.existsSync(file)&&fs.readFileSync(file,'utf8')===token)fs.unlinkSync(file);}
+}
+export function renderReadingBundle(root,checkpoint,{afterWrite}={}){
+ root=path.resolve(root);identity(root);const loc=readingLocation(checkpoint);
+ return locked(root,loc,()=>{
+  const built=build(root,checkpoint),changes=changesFor(root,built);verifyInputs(root,built);
+  if(!changes.length)return {status:'unchanged',checkpoint_ref:checkpoint,diagnostics:built.manifest.diagnostics};
+  const journalRef=`${loc.directory}/.transaction.json`;
+  atomic(root,journalRef,json({schema_version:1,changes}));
+  try{
+   for(const [index,c]of changes.entries()){
+    verifyInputs(root,built);if(!same(root,c.ref,c.before))throw Error(`reading-output-conflict: ${c.ref}`);
+    atomic(root,c.ref,Buffer.from(c.after,'base64'));afterWrite?.(c,index+1);
+   }
+   verifyInputs(root,built);
+   for(const c of changes)if(!same(root,c.ref,c.after))throw Error(`reading-output-conflict: ${c.ref}`);
+   fs.unlinkSync(safe(root,journalRef));
+   return {status:'rendered',checkpoint_ref:checkpoint,changed_refs:changes.map(c=>c.ref),diagnostics:built.manifest.diagnostics};
+  }catch(error){try{recover(root,loc);}catch(recovery){throw Error(`${error.message}; ${recovery.message}`);}throw error;}
+ });
+}
+export function checkReadingViews(root,checkpoint,{required=false}={}){
+ identity(root);const enabled=managedReading(root,checkpoint);
+ if(!required&&!enabled)return {status:'manual',read_only:true,execution_allowed:false,blockers:[]};
+ try{
+  const loc=readingLocation(checkpoint);
+  if(bytes(root,`${loc.directory}/.transaction.json`)||bytes(root,`${loc.directory}/.lock`))throw Error('reading-update-incomplete');
+  const expected=build(root,checkpoint),actual=oldManifest(root,loc),reasons=[];
+  if(!actual||json(actual)!==json(expected.manifest))reasons.push('reading-manifest-stale');
+  for(const [ref,digest]of Object.entries(expected.manifest.outputs))if(descriptor(root,ref)!==digest)reasons.push(`reading-output-stale: ${ref}`);
+  if(hash(navigation(bytes(root,expected.manifest.navigation.ref)?.toString('utf8')||'').block||'')!==expected.manifest.navigation.block_digest)reasons.push('reading-navigation-stale');
+  verifyInputs(root,expected);
+  return {status:reasons.length?'stale':'current',read_only:true,execution_allowed:false,approval_validity:'not-checked',blockers:reasons,diagnostics:expected.manifest.diagnostics,recovery:`scripts/contract render --checkpoint ${checkpoint}`};
+ }catch(error){return {status:'stale',read_only:true,execution_allowed:false,blockers:[error.message],recovery:`scripts/contract render --checkpoint ${checkpoint}`};}
+}
+export function planEnableReading(root,checkpoint){
+ identity(root);root=path.resolve(root);const built=build(root,checkpoint),changes=changesFor(root,built),policy=readingPolicy(root);
+ const nextPolicy={...policy,mode:'managed',checkpoints:[...new Set([...policy.checkpoints,checkpoint])].sort()};
+ const payload={schema_version:1,kind:'reading-enable-plan',root,checkpoint_ref:checkpoint,policy_before:descriptor(root,READING_POLICY),policy_after:nextPolicy,dependencies:built.manifest.dependencies,renderer:built.manifest.renderer,outputs_before:Object.fromEntries([...Object.keys(built.outputs),built.manifest.navigation.ref,`${built.loc.directory}/.manifest.json`].map(ref=>[ref,descriptor(root,ref)])),preview:changes.map(c=>({ref:c.ref,before_digest:c.before===null?null:hash(Buffer.from(c.before,'base64')),after:Buffer.from(c.after,'base64').toString('utf8')}))};
+ return {...payload,plan_id:hash(json(payload))};
+}
+function applyEnableReadingLocked(root,plan){
+ const {plan_id,...payload}=plan;if(plan.kind!=='reading-enable-plan'||plan.root!==path.resolve(root)||hash(json(payload))!==plan_id)throw Error('reading-enable-plan-invalid');
+ const policy=readingPolicy(root);
+ if(json(policy)===json(plan.policy_after)&&checkReadingViews(root,plan.checkpoint_ref).status==='current')return {status:'unchanged'};
+ const current=planEnableReading(root,plan.checkpoint_ref);if(json(current)!==json(plan))throw Error('reading-enable-plan-stale');
+ const before=bytes(root,READING_POLICY);atomic(root,READING_POLICY,json(plan.policy_after));
+ try{return {status:'enabled',reading_update:renderReadingBundle(root,plan.checkpoint_ref)};}
+ catch(error){if(descriptor(root,READING_POLICY)===hash(json(plan.policy_after))){if(before===null)fs.unlinkSync(safe(root,READING_POLICY));else atomic(root,READING_POLICY,before);}throw error;}
+}
+export function finalizeReading(root,checkpoint,sourceOperation){
+ try{if(!managedReading(root,checkpoint))return {...sourceOperation,source_operation:sourceOperation.status,reading_update:{status:'manual'}};
+  return {...sourceOperation,source_operation:sourceOperation.status,reading_update:renderReadingBundle(root,checkpoint)};
+ }catch(error){return {...sourceOperation,source_operation:sourceOperation.status,reading_update:{status:'failed',error:error.message,recovery:`scripts/contract render --checkpoint ${checkpoint}`}};}
+}
+export function readingCheckpointsForAsset(root,ref,kind){
+ if(!['domain-strategy','stage-decision-package','checkpoint','tracking-migration'].includes(kind))return [];
+ const policy=readingPolicy(root);if(policy.mode!=='managed')return [];
+ return policy.checkpoints.filter(checkpoint=>ref.startsWith(readingLocation(checkpoint).base+'/'));
+}
+export function assertReadingTransition(root,decisionState,currentWorkUnit){
+ const ref=decisionState?.checkpoint_ref||decisionState?.checkpoint?.ref;
+ if(!ref){const policy=readingPolicy(root);if(policy.mode==='managed'&&policy.checkpoints.length&&['work-unit.plan-requirements','work-unit.domain-strategy-design','work-unit.stage-decision-package','work-unit.spec-synthesis'].includes(currentWorkUnit))throw Error('reading-checkpoint-ref-required');return {status:'not-applicable'};}
+ if(!managedReading(root,ref))return {status:'manual'};
+ const result=checkReadingViews(root,ref);if(result.blockers.length)throw Error(`reading-views-stale: ${result.blockers.join('; ')}`);return result;
+}
+export function saveReadingComparison(root,checkpoint,result){
+ const loc=readingLocation(checkpoint);
+ if(result.blockers?.length||!result.diff||!result.diff.markdown)throw Error('reading-comparison-source-invalid');
+ const report=result.diff.markdown+'\n批准有效性：not-checked；原决定及语义审阅仍按准备结果处理。\n';
+ const id=hash(json({before:result.before,after:result.after,report,renderer:toolClosure()})).slice(7),ref=`${loc.directory}/changes/${id}.md`,file=safe(root,ref,{missing:true});
+ if(fs.existsSync(file)){if(fs.readFileSync(file,'utf8')!==report)throw Error('reading-comparison-conflict');return {ref,digest:hash(report),status:'unchanged'};}
+ fs.mkdirSync(path.dirname(file),{recursive:true});fs.writeFileSync(file,report,{flag:'wx'});return {ref,digest:hash(report),status:'saved'};
+}
+
+export function applyEnableReading(root,plan){
+ identity(root);
+ return locked(root,{base:'.template-spec/process',directory:'.template-spec/process',lock_name:'.reading-enable.lock',recover:false},()=>applyEnableReadingLocked(root,plan));
+}

package/template/scripts/lib/reading-view-diff.mjs

@@ -0,0 +1,29 @@
+import {readingIdFields} from './reading-view-model.mjs';
+import {renderReadingValue} from './reading-view-markdown.mjs';
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+const identity=(value,pointer)=>{const key=readingIdFields[pointer.split('/').at(-1)]||'id';return object(value)&&typeof value[key]==='string'?key:undefined;};
+const part=value=>String(value).replace(/~/g,'~0').replace(/\//g,'~1');
+const bindings=new Set(['schema_version','digest','subject_digest','document_digest','referenced_terms_digest','ref','context_ref','persisted_ref']);
+const business=new Set(['responsibilities','non_responsibilities','rules','failure_results','success_results','statement','constraints','status','acceptance','progress','scope','preconditions','blockers','owner','deferred']);
+export function readingDiff(before,after){
+ const changes=[];
+ const walk=(a,b,p,category='unclassified')=>{
+  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}/${part(key)}`,bindings.has(key)?'binding-change':business.has(key)?'business-change':category);return;}
+  if(Array.isArray(a)&&Array.isArray(b)&&a.length&&b.length){
+   const key=identity(a[0],p);if(key&&[...a,...b].every(x=>object(x)&&typeof x[key]==='string')){
+    const left=a.map(x=>x[key]),right=b.map(x=>x[key]);
+    if(new Set(left).size!==left.length||new Set(right).size!==right.length){changes.push({path:p,category:'unclassified',diagnostic:'duplicate-stable-id',before:a,after:b});return;}
+    if(JSON.stringify(left)!==JSON.stringify(right))changes.push({path:p,category:'business-change',change:'order-or-membership',before:left,after:right});
+    for(const id of new Set([...left,...right]))walk(a.find(x=>x[key]===id),b.find(x=>x[key]===id),`${p}/@${part(id)}`,category);return;
+   }
+  }
+  changes.push({path:p,category,before:a===undefined?{absent:true}:a,after:b===undefined?{absent:true}:b});
+ };
+ walk(before,after,'');return changes;
+}
+export function renderReadingDiff(result){
+ const changes=result.semantic_changes||result.changes;
+ return ['# 合同差异审阅','本报告不认定语义等价，不授予批准沿用或执行权限。',`旧来源：${result.before.ref}；${result.before.digest}`,`新来源：${result.after.ref}；${result.after.digest}`,
+ ...changes.flatMap(row=>[`## ${row.path||'/'}`,`分类：${row.category}（仍需按实际影响审阅）`,renderReadingValue({before:row.before,after:row.after,...(row.change?{change:row.change}:{})})]),...(!changes.length?[result.bytes_changed?'presentation-change：解析内容相同，原字节不同；原绑定仍需核验。':'没有检测到差异；批准有效性未核验。']:[])].join('\n\n')+'\n';
+}

package/template/scripts/lib/reading-view-markdown.mjs

@@ -0,0 +1,39 @@
+// Presentation only: labels never change identifiers or decision values.
+export const readingLabels=Object.freeze({
+  'domain-strategy':'领域战略审阅','stage-decision-package':'阶段决策审阅',checkpoint:'阶段状态快照','tracking-migration':'跟踪迁移审阅',
+  contexts:'业务责任区',subdomains:'业务板块',relationships:'协作与交接关系',rule_catalog:'业务规则',scenarios:'业务场景',concept_candidates:'关键业务对象候选',invariants:'不可违反的规则',downstream_mapping:'下游传播',context_snapshot:'术语来源',evidence_refs:'证据来源',approval:'批准记录',
+  responsibilities:'负责事项',non_responsibilities:'不负责事项',owner:'负责人',status:'声明状态',statement:'规则内容',responsible_context:'责任区',preconditions:'前提条件',commands:'操作',rules:'适用规则',events:'业务事件',success_results:'成功结果',failure_results:'失败结果',consumers:'消费方',rule_refs:'规则引用',critical:'关键场景',
+  problem_statement:'问题与目标',target_users:'目标用户',mvp:'本期范围',non_goals:'非目标',success_criteria:'成功标准',test_seams:'测试边界',confirmed_decisions:'已确认决定',assumptions:'假设',constraints:'约束',unresolved_items:'未决事项',domain_strategy_ref:'领域战略来源',impact_assessment:'影响面',
+  stage:'当前阶段',next_work_unit:'下一工作单元',blockers:'已登记阻塞',stage_tracking:'阶段工作',items:'工作项',progress:'工作项进度',acceptance:'验收条件',dependencies:'依赖',completion:'完成证据',recheck_required:'需要重新检查',deferred:'延期安排',cancellation_reason:'取消原因',
+  artifacts:'阶段资产',gates:'门禁登记',checks:'检查范围',verification:'验证记录',human_review:'人工审阅',context_reconciliation:'术语对账',ticket_sync:'Ticket 同步',git_checkpoint:'Git 授权记录',rollback:'回滚',
+  changes:'文件变化',before:'修改前',after:'修改后',changed_refs:'变更文件',source_operation:'源操作结果',reading_update:'阅读材料更新',
+  name:'名称',title:'标题',description:'说明',rationale:'依据',scope:'范围',type:'类型',next_action:'下一动作',target_version:'目标版本',semantic_upstream:'规则提供方',semantic_downstream:'规则使用方',business_authority:'业务决策权',transport_direction:'信息方向',translation_responsibility:'口径转换负责人',model_change_impact:'模型变更影响',direction_explanation:'方向说明',
+});
+export const escapeMarkdown=value=>String(value).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/([\\`*_\[\]|])/g,'\\$1');
+const scalar=value=>value===null?'null':String(value);
+function textLines(value,indent=''){
+  return scalar(value).split(/\r?\n/).map((line,index)=>`${index?'\n'+indent+'> ':''}${escapeMarkdown(line)}`).join('');
+}
+export function renderReadingValue(value,depth=0){
+  if(value===null||typeof value!=='object')return textLines(value);
+  const entries=Object.entries(value);
+  if(!entries.length)return Array.isArray(value)?'[]（来源明确为空）':'{}（来源明确为空）';
+  return entries.map(([key,child])=>{
+    if(Array.isArray(value)&&(child===null||typeof child!=='object'))return '- '+textLines(child).replace(/\n/g,'\n  ');
+    const label=Array.isArray(value)?`第 ${Number(key)+1} 项`:escapeMarkdown(readingLabels[key]||key);
+    const rendered=renderReadingValue(child,depth+1).split('\n');
+    return child!==null&&typeof child==='object'&&Object.keys(child).length?`- **${label}**：\n${rendered.map(line=>'  '+line).join('\n')}`:`- **${label}**：${rendered[0]}${rendered.slice(1).map(line=>'\n  '+line).join('')}`;
+  }).join('\n');
+}
+export function renderReadingMarkdown(view){
+  const lines=[`# ${readingLabels[view.kind]||view.kind} · ${escapeMarkdown(view.binding.id||view.binding.ref)}`,
+    `版本：${escapeMarkdown(view.binding.version||'源资产未声明')}；权威文件：${escapeMarkdown(view.binding.ref)}`,
+    `来源 SHA-256：${view.binding.digest}`,
+    '本页为来源快照；当前有效性需重新检查。批准有效性未核验；本视图不授予执行权限。',
+    `检查范围：${view.checks.map(escapeMarkdown).join('；')}`];
+  for(const [key,value]of Object.entries(view.content))if(value!==undefined){
+    lines.push(`## ${readingLabels[key]||escapeMarkdown(key)}`,key==='正文'&&typeof value==='string'?value:renderReadingValue(value));
+  }
+  if(view.blockers.length)lines.push('## 阻断与未决检查',...view.blockers.map(item=>`- ${escapeMarkdown(item)}`));
+  return lines.join('\n\n')+'\n';
+}

package/template/scripts/lib/reading-view-model.mjs

@@ -0,0 +1,13 @@
+export const readingIdFields=Object.freeze({contexts:'context_id',subdomains:'subdomain_id',relationships:'relationship_id',rule_catalog:'rule_id',scenarios:'scenario_id',concept_candidates:'concept_id',invariants:'invariant_id',downstream_mapping:'mapping_id',items:'id'});
+// A lossless presentation index, never another editable contract.
+const pointerPart=key=>String(key).replace(/~/g,'~0').replace(/\//g,'~1');
+export function readingViewModel(view,raw){
+  const locations=[];
+  const walk=(value,pointer)=>{
+    if(value===null||typeof value!=='object'||Object.keys(value).length===0){locations.push({content_pointer:pointer,pointer_kind:'view-content',...(view.kind!=='tracking-migration'&&Object.hasOwn(raw||{},pointer.split('/')[1])?{source_pointer:pointer}:{}),source_ref:view.binding.ref,source_digest:view.binding.digest});return;}
+    for(const [key,child]of Object.entries(value))walk(child,`${pointer}/${pointerPart(key)}`);
+  };
+  walk(view.content,'');
+  return {view_schema_version:1,kind:view.kind,profile:view.profile,binding:view.binding,read_only:true,execution_allowed:false,approval_validity:'not-checked',
+    declared_state:{status:raw?.status??null,stage:raw?.stage??null},checks:view.checks,sections:Object.keys(view.content),diagnostics:view.blockers,source_locations:locations,coverage:{rendered_leaf_count:locations.length,scope:'presented-content; owner verification remains required'}};
+}

package/template/scripts/lib/reading-view-policy.mjs

@@ -0,0 +1,16 @@
+import {existsSync,readFileSync} from './validation-phase.mjs';
+import {safe,schema} from './strategic-handoff-io.mjs';
+import {parseSliceYaml} from './slice-contract.mjs';
+export const READING_POLICY='.template-spec/process/reading-policy.yaml';
+export function readingPolicy(root){
+ const file=safe(root,READING_POLICY,{missing:true});
+ if(!existsSync(file))return {schema_version:1,mode:'manual',checkpoints:[]};
+ const value=parseSliceYaml(readFileSync(file));schema(value,'.template-spec/process/schemas/reading-policy.schema.json');
+ return value;
+}
+export function managedReading(root,checkpoint){const policy=readingPolicy(root);return policy.mode==='managed'&&policy.checkpoints.includes(checkpoint);}
+export function readingLocation(checkpoint){
+ const match=/^docs\/\.scratch\/([a-z0-9][a-z0-9-]*)\/[^/]+\.(yaml|json)$/.exec(checkpoint);
+ if(!match)throw Error('reading-checkpoint-path-invalid');
+ return {feature:match[1],base:`docs/.scratch/${match[1]}`,directory:`docs/.scratch/${match[1]}/reading`};
+}