create-yss-spec 3.5.2 → 3.5.4

package/template/scripts/lib/read-only-intake.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { parse } from '../vendor/yaml.mjs';
+import { runCommand } from './command-runner.mjs';
+
+const ensure = (ok, message) => { if (!ok) throw new TypeError(`read-only-intake: ${message}`); };
+export const digest = value => `sha256:${createHash('sha256').update(value).digest('hex')}`;
+const inside = (root, file) => { const rel = path.relative(root, file); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
+export function intakeEvidencePath(ref, { root, runDir }) {
+  const runtime = ref.startsWith('run:');
+  const base = runtime ? runDir : root;
+  ensure(base && path.isAbsolute(base), '运行证据必须显式提供绝对 run-dir');
+  const relative = runtime ? ref.slice(4) : ref;
+  ensure(relative && !path.isAbsolute(relative) && !relative.split(/[\\/]/).includes('..'), '证据路径越界');
+  const resolvedBase = fs.realpathSync(base), file = path.resolve(base, relative);
+  ensure(inside(path.resolve(base), file) && inside(resolvedBase, fs.realpathSync(file)), '证据符号链接越界');
+  ensure(fs.statSync(file).isFile(), '证据必须为文件');
+  return file;
+}
+// Stream large preserved evidence archives instead of allocating the whole file.
+export function fileDigest(file) {
+  const hash = createHash('sha256'), buffer = Buffer.allocUnsafe(1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  try {
+    let size;
+    while ((size = fs.readSync(fd, buffer, 0, buffer.length, null)) !== 0) hash.update(buffer.subarray(0, size));
+    return `sha256:${hash.digest('hex')}`;
+  } finally { fs.closeSync(fd); }
+}
+/** Final observable repository files, including ignored and untracked files; never follow links. */
+export function intakeSnapshot(root) {
+  const result = spawnSync('git', ['ls-files', '-z', '--cached', '--others'], { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  ensure(result.status === 0, result.stderr || '无法观察仓库');
+  const rows = {};
+  for (const ref of [...new Set(result.stdout.split('\0').filter(Boolean))].sort()) {
+    const file = path.join(root, ref);
+    try {
+      const stat = fs.lstatSync(file);
+      if (stat.isDirectory()) {
+        const nested = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: file, encoding: 'utf8' });
+        ensure(nested.status === 0 && fs.realpathSync(nested.stdout.trim()) === fs.realpathSync(file), `子仓未初始化: ${ref}`);
+        const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: file, encoding: 'utf8' });
+        ensure(nested.status === 0 && head.status === 0, `子仓不可观测: ${ref}`);
+        rows[ref] = { kind: 'gitlink', head: head.stdout.trim(), files: intakeSnapshot(file) };
+      } else rows[ref] = { kind: stat.isSymbolicLink() ? 'link' : 'file', mode: stat.mode, digest: stat.isSymbolicLink() ? digest(fs.readlinkSync(file)) : fileDigest(file) };
+    } catch (error) { if (error.code === 'ENOENT') rows[ref] = null; else throw error; }
+  }
+  const head=spawnSync('git',['rev-parse','--verify','HEAD'],{cwd:root,encoding:'utf8'});
+  const index=spawnSync('git',['ls-files','--stage','-z'],{cwd:root,encoding:'utf8',maxBuffer:16*1024*1024});
+  ensure(index.status===0,'无法观察 Git index');
+  return {git:{head:head.status===0?head.stdout.trim():null,index_digest:digest(index.stdout)},files:rows};
+}
+export function validateReadOnlyIntake(value, { root, runDir, roles, lifecycle }) {
+  const identity = parse(fs.readFileSync(path.join(root, 'yss-project.yaml'), 'utf8'));
+  ensure(identity.schema_version === 1 && ['template-source', 'project-instance'].includes(identity.repository_mode), '仓库身份无效');
+  ensure(value.contract.kind === 'read-only-intake' && value.schema_version === 2 && value.execution_state === 'Explorer' && value.allowed_write_paths.length === 0, '只读合同不授予写权限');
+  ensure(lifecycle.work_units.some(x => x.id === value.work_unit_id) && ['work-unit.entry-triage', 'work-unit.harness-entry'].includes(value.work_unit_id), '只允许已登记分诊入口');
+  ensure(roles.runtimes.some(x => x.id === value.runtime_id), '未知运行时');
+  ensure(value.contract.status === 'issued' || value.workflow_status === 'paused', '过期合同必须暂停');
+  for (const ref of [value.contract.contract_ref, ...value.inputs, ...value.expected_evidence_files]) intakeEvidencePath(ref, { root, runDir });
+  if (value.result) {
+    ensure(value.result.work_unit===value.work_unit_id && value.result.workflow_reference===value.contract.contract_ref,'结果必须绑定原分诊工作单元和合同来源');
+    ensure(!value.result.changed_files?.length && !value.result.changed_artifacts?.length, '只读结果包含变更');
+    ensure(value.result.next_route == null && !value.result.checkpoint_ref, '只读结果不得流转或修改 checkpoint');
+    for (const ref of value.result.evidence_refs || []) intakeEvidencePath(ref, { root, runDir });
+  }
+  const commands = new Set(value.verification_commands);
+  ensure((value.verification_status === 'not-executed') === (value.verification_results.length === 0), '执行状态与实际结果不一致');
+  for (const row of value.verification_results) {
+    ensure(commands.has(row.command) && row.evidence_ref.startsWith('run:'), '运行结果必须绑定声明的命令及真实运行日志');
+    const evidence = fs.readFileSync(intakeEvidencePath(row.evidence_ref, { root, runDir }));
+    ensure(row.evidence_digest === digest(evidence), '运行证据摘要不一致');
+    const record = JSON.parse(evidence);
+    for (const key of ['command','exit_code','duration_ms','executed_at']) ensure(record[key] === row[key], `运行记录 ${key} 不一致`);
+    for (const stream of ['stdout','stderr']) {
+      const ref = row[`${stream}_ref`];
+      ensure(ref?.startsWith('run:'), '运行日志无效');
+      ensure(record[`${stream}_digest`] === digest(fs.readFileSync(intakeEvidencePath(ref, { root, runDir }))), '运行日志摘要不一致');
+    }
+  }
+  if (value.workflow_status === 'resolved' || value.result?.result === 'completed') {
+    ensure(value.workflow_status === 'resolved' && value.result?.result === 'completed', '完成状态不一致');
+    ensure(value.result.evidence_refs?.length && value.result.context_reconciliation?.status === 'not-applicable' && value.result.context_reconciliation?.reason, '只读结论缺少来源或不流转说明');
+    for (const key of ['drift','violation','new_impacts','stale_candidates','blocking_signals','deferred_seams']) ensure(Array.isArray(value.result[key]) && !value.result[key].length, `完成结果 ${key} 必须为空`);
+    ensure(value.verification_results.every(x => x.exit_code === 0) && [...commands].every(c => value.verification_results.some(x => x.command === c)), '实际验证缺失或失败');
+    ensure(value.observation_ref?.startsWith('run:'), '完成结果缺少执行器仓库观测');
+    const observation = JSON.parse(fs.readFileSync(intakeEvidencePath(value.observation_ref, { root, runDir }), 'utf8'));
+    const dispatchedBytes=fs.readFileSync(intakeEvidencePath(observation.task_ref,{root,runDir}));
+    ensure(observation.task_digest===digest(dispatchedBytes),'原派发任务摘要不一致');
+    const dispatched=JSON.parse(dispatchedBytes);
+    for(const key of ['task_id','work_unit_id','actor_id','role_id','runtime_id','contract','inputs','allowed_write_paths','objective','forbidden_actions','expected_outputs','expected_evidence_files','skill_source','downstream_consumers','convergence'])ensure(JSON.stringify(dispatched[key])===JSON.stringify(value[key]),`结果替换原任务 ${key}`);
+    ensure(!dispatched.verification_commands.length || JSON.stringify(dispatched.verification_commands)===JSON.stringify(value.verification_commands),'结果替换验证要求');
+    ensure(observation.kind === 'read-only-intake-observation' && observation.task_id === value.task_id && observation.root === fs.realpathSync(root), '观测身份不匹配');
+    ensure(JSON.stringify(observation.before) === JSON.stringify(observation.after) && JSON.stringify(observation.after) === JSON.stringify(intakeSnapshot(root)), '仓库实际差异与只读声明冲突');
+  }
+  return value;
+}
+/** Runner-owned evidence is outside the repository; the child receives no new repository permissions. */
+export async function observeReadOnlyIntake(task, { root, runDir, command, args = [], timeoutMs = 0 }) {
+  const label = command ? JSON.stringify([command,...args]) : null;
+  ensure(!command || !task.verification_commands.length || task.verification_commands.length===1 && task.verification_commands[0]===label,'执行命令与声明不一致，不得替换要求的验证');
+  root = fs.realpathSync(root);
+  ensure(path.isAbsolute(runDir) && !inside(root, path.resolve(runDir)), '运行目录必须位于仓库外');
+  ensure(!inside(root, fs.realpathSync(path.dirname(runDir))), '运行目录父路径符号链接进入仓库');
+  fs.mkdirSync(runDir, { recursive: false });
+  runDir = fs.realpathSync(runDir);
+  fs.writeFileSync(path.join(runDir,'task.json'),JSON.stringify(task,null,2)+'\n',{flag:'wx'});
+  const before = intakeSnapshot(root), started = new Date().toISOString();
+  const result = command ? await runCommand(command, args, { cwd: root, timeoutMs, stdoutFile: path.join(runDir, 'stdout.log'), stderrFile: path.join(runDir, 'stderr.log') }) : null;
+  const after = intakeSnapshot(root);
+  const observation = { schema_version: 1, kind: 'read-only-intake-observation', task_id: task.task_id, task_ref:'run:task.json', task_digest:digest(fs.readFileSync(path.join(runDir,'task.json'))), root, started_at: started, before, after };
+  fs.writeFileSync(path.join(runDir, 'observation.json'), JSON.stringify(observation, null, 2)+'\n');
+  const changed = JSON.stringify(before) !== JSON.stringify(after);
+  const completed = !changed && (!result || result.status === 0);
+  const output = structuredClone(task);
+  output.observation_ref = 'run:observation.json';
+  output.verification_status = result ? 'executed' : 'not-executed';
+  output.verification_results = [];
+  if (result) {
+    const label = JSON.stringify([command, ...args]);
+    const record = { command: label, exit_code: result.status ?? 1, duration_ms: Math.round(result.duration_ms), executed_at: started, termination: result.termination ?? null, stdout_digest: digest(fs.readFileSync(path.join(runDir,'stdout.log'))), stderr_digest: digest(fs.readFileSync(path.join(runDir,'stderr.log'))) };
+    const bytes = JSON.stringify(record, null, 2)+'\n'; fs.writeFileSync(path.join(runDir, 'execution.json'), bytes);
+    output.verification_commands = [label];
+    output.verification_results = [{command:label,exit_code:record.exit_code,duration_ms:record.duration_ms,executed_at:started,evidence_ref:'run:execution.json',evidence_digest:digest(bytes),stdout_ref:'run:stdout.log',stderr_ref:'run:stderr.log'}];
+  }
+  output.workflow_status = completed ? 'resolved' : 'failed';
+  output.result = { result_schema: 'workflow-execution-result-v1', work_unit: task.work_unit_id, workflow_reference: task.contract.contract_ref, result: completed ? 'completed' : 'failed', skill: 'yss-research', changed_files: [], changed_artifacts: [], evidence_refs: [...task.inputs, 'run:observation.json'], context_reconciliation: {status:'not-applicable',ref:'CONTEXT.md',reason:'只读分诊，不批准资产或流转阶段'}, deferred_seams: [], drift: [], violation: changed ? ['repository-changed'] : [], new_impacts: [], stale_candidates: [], next_route: null, blocking_signals: completed ? [] : ['read-only-intake-failed'] };
+  fs.writeFileSync(path.join(runDir, 'task-result.json'), JSON.stringify(output, null, 2)+'\n');
+  return output;
+}

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`};
+}