create-yss-spec 3.5.3 → 3.5.5

package/template/scripts/lib/project-ci-install.mjs

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { safeFile, fileBinding, readDocument, digest } from './governance-io.mjs';
+import { CI_CONFIG, TRACKER, governanceScope } from './project-governance.mjs';
+
+export const CI_WORKFLOW='.github/workflows/yss-governance.yml';
+export const CI_RECEIPT='.template-spec/process/project-ci-install.json';
+export const CI_JOURNAL='.template-spec/process/.project-ci-transaction.json';
+const conflict=message=>{const error=new Error(message);error.exitCode=1;throw error;};
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(k=>[k,canonical(value[k])])):value;
+const encode=value=>JSON.stringify(canonical(value),null,2)+'\n';
+const hashObject=value=>digest(encode(value));
+function workflow(branch) {
+  return `# Managed by scripts/project-ci; edit through an explicit plan/apply.\nname: YSS project governance\non:\n  pull_request:\n  push:\n    branches: [${JSON.stringify(branch)}]\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  governance:\n    name: YSS governance\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n          persist-credentials: false\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '24'\n      - uses: actions/setup-python@v5\n        with:\n          python-version: '3.12'\n      - run: python -m pip install jsonschema==4.23.0\n      - name: Check current governance evidence\n        env:\n          BASE_SHA: \${{ github.event.pull_request.base.sha }}\n        shell: bash\n        run: |\n          if [[ -n "$BASE_SHA" ]]; then\n            node scripts/project-ci check --root . --base "$BASE_SHA" --json > "$RUNNER_TEMP/yss-governance.json"\n          else\n            node scripts/project-ci check --root . --json > "$RUNNER_TEMP/yss-governance.json"\n          fi\n      - uses: actions/upload-artifact@v4\n        if: always()\n        with:\n          name: yss-governance\n          path: \${{ runner.temp }}/yss-governance.json\n          if-no-files-found: error\n`;
+}
+function configuration(branch,additionalPaths) {
+  if(typeof branch!=='string'||!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch)||branch.includes('..')||branch.includes('//')||branch.endsWith('/')||branch.endsWith('.lock'))throw new Error('目标分支无效');
+  return {schema_version:1,provider:'github',branch,additional_paths:[...new Set(additionalPaths)].sort()};
+}
+function outputs(config) {
+  const items=[{ref:CI_WORKFLOW,content:workflow(config.branch)},{ref:CI_CONFIG,content:encode(config)}];
+  const receipt={schema_version:1,kind:'project-ci-installation',managed:Object.fromEntries(items.map(x=>[x.ref,digest(x.content)]))};
+  return [...items,{ref:CI_RECEIPT,content:encode(receipt)}].map(x=>({...x,sha256:digest(x.content)}));
+}
+export function planProjectCi({root,provider='github',branch,additionalPaths}={}) {
+  root=fs.realpathSync(root);
+  if(provider!=='github')throw new Error('首版仅支持 --provider github');
+  const scope=governanceScope(root);
+  const config=configuration(branch??scope.config.branch??'main',additionalPaths??scope.config.additional_paths);
+  config.additional_paths.forEach(ref=>safeFile(root,ref));
+  const owned=fileBinding(root,CI_RECEIPT)?readDocument(root,CI_RECEIPT):null;
+  if(owned&&(owned.schema_version!==1||owned.kind!=='project-ci-installation'||!owned.managed))throw new Error('CI 托管凭据无效');
+  const expected=outputs(config),conflicts=[];
+  const inputs=[...new Set(['yss-project.yaml',TRACKER,CI_CONFIG,CI_RECEIPT,CI_WORKFLOW,CI_JOURNAL])].sort().map(ref=>({ref,sha256:fileBinding(root,ref)}));
+  for(const item of expected) {
+    const current=fileBinding(root,item.ref);
+    if(item.ref===CI_RECEIPT)continue;
+    if(current&&(!owned||owned.managed[item.ref]!==current))conflicts.push({ref:item.ref,reason:'已有人工文件或托管输出已被修改'});
+    if(!current&&owned?.managed[item.ref])conflicts.push({ref:item.ref,reason:'托管文件缺失，先恢复或显式处理'});
+  }
+  if(fileBinding(root,CI_JOURNAL))conflicts.push({ref:CI_JOURNAL,reason:'存在未完成事务，运行 apply --recover'});
+  const implementation=['project-ci-install.mjs','project-governance.mjs','governance-io.mjs'].map(ref=>({ref,sha256:digest(fs.readFileSync(new URL(ref,import.meta.url)))}));
+  const plan={schema_version:1,kind:'project-ci-plan',root,provider,branch:config.branch,additional_paths:config.additional_paths,roots:[...new Set([scope.trackerRoot,...config.additional_paths])],inputs,implementation,outputs:expected,conflicts,execution_authorization:'not-evaluated'};
+  return {...plan,plan_digest:hashObject(plan)};
+}
+function atomicWrite(root,ref,bytes) {
+  const target=safeFile(root,ref);fs.mkdirSync(path.dirname(target),{recursive:true});
+  const temporary=`${target}.tmp-${randomUUID()}`;
+  try{fs.writeFileSync(temporary,bytes,{flag:'wx'});fs.renameSync(temporary,target);}finally{if(fs.existsSync(temporary))fs.unlinkSync(temporary);}
+}
+export function recoverProjectCi(root) {
+  root=fs.realpathSync(root);
+  governanceScope(root);
+  const journal=readDocument(root,CI_JOURNAL);
+  if(journal.schema_version!==1||journal.kind!=='project-ci-transaction'||!Array.isArray(journal.files)||journal.files.length!==3||new Set(journal.files.map(x=>x.ref)).size!==3||journal.files.some(x=>![CI_WORKFLOW,CI_CONFIG,CI_RECEIPT].includes(x.ref)))throw new Error('CI 恢复日志无效');
+  for(const item of journal.files) {
+    const old=item.before===null?null:Buffer.from(item.before,'base64');
+    if((old===null?null:digest(old))!==item.before_digest)throw new Error(`恢复备份摘要不一致: ${item.ref}`);
+    const current=fileBinding(root,item.ref);
+    if(current!==item.after_digest&&current!==item.before_digest)conflict(`恢复冲突，保留后续修改: ${item.ref}`);
+  }
+  for(const item of [...journal.files].reverse())if(fileBinding(root,item.ref)!==item.before_digest) {
+    if(item.before===null)fs.unlinkSync(safeFile(root,item.ref));else atomicWrite(root,item.ref,Buffer.from(item.before,'base64'));
+  }
+  fs.unlinkSync(safeFile(root,CI_JOURNAL));return {status:'recovered',remote_changed:false};
+}
+export function applyProjectCi({root,plan,recover=false}={}) {
+  root=fs.realpathSync(root);
+  if(recover)return recoverProjectCi(root);
+  const {plan_digest,...body}=plan||{};
+  if(plan_digest!==hashObject(body)||plan.schema_version!==1||plan.provider!=='github'||plan.kind!=='project-ci-plan'||plan.root!==root||plan.conflicts.length)throw new Error('CI 计划无效、根不匹配或存在冲突');
+  const intended=outputs(configuration(plan.branch,plan.additional_paths));
+  if(encode(intended)!==encode(plan.outputs))throw new Error('CI 计划输出被替换');
+  if(fileBinding(root,CI_JOURNAL))throw new Error('存在未完成事务，先运行 apply --recover');
+  const currentScope=governanceScope(root);
+  if(intended.every(x=>fileBinding(root,x.ref)===x.sha256)) {
+    const unchanged=plan.inputs.filter(x=>![CI_CONFIG,CI_RECEIPT,CI_WORKFLOW].includes(x.ref)).every(x=>fileBinding(root,x.ref)===x.sha256);
+    const sameCode=plan.implementation.every(x=>['project-ci-install.mjs','project-governance.mjs','governance-io.mjs'].includes(x.ref)&&digest(fs.readFileSync(new URL(x.ref,import.meta.url)))===x.sha256);
+    if(!unchanged||!sameCode||!plan.roots.includes(currentScope.trackerRoot))conflict('CI 计划输入已变化，请重新 plan');
+    return {status:'unchanged',remote_changed:false};
+  }
+  const current=planProjectCi({root,provider:plan.provider,branch:plan.branch,additionalPaths:plan.additional_paths});
+  if(current.plan_digest!==plan.plan_digest)conflict('CI 计划输入已变化，请重新 plan');
+  const journal={schema_version:1,kind:'project-ci-transaction',plan_digest,files:intended.map(x=>{const hash=fileBinding(root,x.ref);return {ref:x.ref,before:hash?fs.readFileSync(safeFile(root,x.ref)).toString('base64'):null,before_digest:hash,after_digest:x.sha256};})};
+  const journalFile=safeFile(root,CI_JOURNAL);fs.mkdirSync(path.dirname(journalFile),{recursive:true});
+  fs.writeFileSync(journalFile,encode(journal),{flag:'wx'});
+  try {
+    for(const item of intended) {
+      const before=journal.files.find(x=>x.ref===item.ref).before_digest;
+      if(fileBinding(root,item.ref)!==before)throw new Error(`并发修改: ${item.ref}`);
+      atomicWrite(root,item.ref,item.content);
+    }
+    if(!intended.every(x=>fileBinding(root,x.ref)===x.sha256))throw new Error('CI 写入后并发变化');
+    fs.unlinkSync(journalFile);
+  }catch(error){try{recoverProjectCi(root);}catch(recovery){throw new Error(`${error.message}; ${recovery.message}`);}throw error;}
+  return {status:'applied',files:intended.map(x=>x.ref),remote_changed:false};
+}

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,202 @@
+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});
+   bindReferences(view.presentation);
+   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';
+}