create-yss-spec 3.5.3 → 3.5.5

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

@@ -1,10 +1,19 @@
+import {readingCheckpointsForAsset,checkReadingViews} from './reading-view-bundle.mjs';
 import {readFileSync,withValidationPhase} from './validation-phase.mjs';
 import {safe,hash,schema} from './strategic-handoff-io.mjs';
 import {parseSliceYaml,readSliceContract} from './slice-contract.mjs';
 import {renderSliceContractView,diffSliceContracts} from './slice-contract-views.mjs';
+import {renderReadingMarkdown} from './reading-view-markdown.mjs';
+import {loadLifecyclePresenter} from './lifecycle-presentation.mjs';
+import {readingDiff,renderReadingDiff} from './reading-view-diff.mjs';
+import {adaptReading} from './reading-view-adapters.mjs';
+import {readingViewModel} from './reading-view-model.mjs';
 
 // This is a presentation adapter table, never a lifecycle or approval registry.
 export const contractKinds=Object.freeze({
+ 'domain-strategy':'.template-spec/process/schemas/domain-strategy-reading.schema.json',
+ 'stage-decision-package':'.template-spec/process/schemas/stage-decision-package-reading.schema.json',
+ checkpoint:'.template-spec/process/schemas/lifecycle-checkpoint.schema.json','tracking-migration':null,
  slice:null,plan:null,spec:null,'product-design':null,'prototype-confirmation':null,'visual-baseline':null,
  'technical-design':'.agents/skills/yss-technical-design/references/technical-design.schema.json',
  'api-decision':'.template-spec/process/schemas/api-contract-decision.schema.json',
@@ -17,11 +26,11 @@ export const contractKinds=Object.freeze({
 });
 const object=v=>v&&typeof v==='object'&&!Array.isArray(v);
 const stringify=v=>typeof v==='string'?v:JSON.stringify(v,null,2);
-const metadata=/^(schema_version|kind|digest|sha256|subject_digest|.*_digest|.*_sha256|resolution|basis|inputs|sources|artifact_bindings|current_version)$/;
+const metadata=/^(schema_version|digest|sha256|subject_digest|document_digest|referenced_terms_digest)$/;
 function display(value){
  if(Array.isArray(value))return value.map(display);
  if(!object(value))return value;
- return Object.fromEntries(Object.entries(value).filter(([key])=>!metadata.test(key)).map(([k,v])=>[k,display(v)]));
+ return Object.fromEntries(Object.entries(value).map(([k,v])=>[k,display(v)]));
 }
 function validateKind(kind){if(!Object.hasOwn(contractKinds,kind))throw new TypeError(`未知合同类型 ${kind}；可用：${Object.keys(contractKinds).join(', ')}`);}
 function load(ref,root){
@@ -53,16 +62,17 @@ function declaredBlockers(value,prefix=''){
  return rows;
 }
 function markdown(view){
+ if(['domain-strategy','stage-decision-package','checkpoint','tracking-migration'].includes(view.kind))return renderReadingMarkdown(view);
  const lines=[`# ${view.kind} · ${view.binding.id||view.binding.ref}`,`版本：${view.binding.version||'源资产未声明'}；权威文件：${view.binding.ref}`,`摘要：${view.binding.digest}`,`检查：${view.checks.join('；')}。批准有效性未核验；本视图不授予执行权限。`];
  for(const [name,value]of Object.entries(view.content))if(value!==undefined)lines.push(`## ${name}`,stringify(value));
  if(view.blockers.length)lines.push('## 阻断与未决检查',...view.blockers.map(x=>`- ${x}`));
  return lines.join('\n\n')+'\n';
 }
 export function viewContract(ref,options={}){return withValidationPhase({root:options.root,purpose:'contract-view',slice_id:ref,work_unit_id:options.unit_id,readOnly:true},()=>view(ref,options));}
-function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout='legacy'}={}){
+function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout='legacy',include_reading_model=false}={}){
  validateKind(kind);if(!['review','task','full'].includes(profile))throw new TypeError(`未知阅读档位 ${profile}`);
  if(!['legacy','focused'].includes(task_layout))throw new TypeError(`未知 task layout ${task_layout}`);
- let binding,content,checks=['可读取'],blockers=[],sourceChecks=[];
+ let sourceRaw,binding,content,checks=['可读取'],blockers=[],sourceChecks=[];
  if(kind==='slice'){
   const loaded=readSliceContract(ref,{root,diagnostic:true});binding=loaded.binding;blockers.push(...declaredBlockers(loaded.raw));
   const legacy=renderSliceContractView(ref,{root,unit_id:profile==='task'?unit_id:undefined});
@@ -95,7 +105,7 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout=
    }
   }
  }else{
-  const {bytes,raw}=load(ref,root);binding={ref,id:raw.contract_id||raw.technical_design_id||raw.decision_id||raw.request?.request_id||raw.handoff_id||raw.baseline_id||raw.spec_id||raw.plan_id||raw.id||null,version:raw.contract_version||raw.decision_version||raw.handoff_version||raw.version||null,digest:hash(bytes)};
+  const {bytes,raw}=load(ref,root);sourceRaw=raw;binding={ref,schema_version:raw.schema_version??null,id:raw.contract_id||raw.feature_id||raw.domain_strategy_id||raw.stage_decision_id||raw.technical_design_id||raw.decision_id||raw.request?.request_id||raw.handoff_id||raw.baseline_id||raw.spec_id||raw.plan_id||raw.id||null,version:raw.contract_version||raw.domain_version||raw.package_version||raw.decision_version||raw.handoff_version||raw.version||null,digest:hash(bytes)};
   blockers.push(...declaredBlockers(raw));
   let schemaRef=contractKinds[kind];if(kind==='api-decision'&&raw.schema_version===2)schemaRef='.template-spec/process/schemas/api-contract-decision-v2.schema.json';
   if(kind==='frontend-acceptance'&&[1,3].includes(raw.schema_version))schemaRef=`.template-spec/process/schemas/frontend-delivery-acceptance${raw.schema_version===1?'-v1':'-v3'}.schema.json`;
@@ -103,7 +113,7 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout=
   else checks.push('结构与批准未核验，按资产所有者规则继续');
   sourceChecks=references(raw,root);if(sourceChecks.length)checks.push(`核对 ${sourceChecks.length} 项可识别来源摘要；其余语义由资产所有者核验`);for(const source of sourceChecks)if(!source.current)blockers.push(`来源不可读或过期：${source.ref}`);
   // Unknown business fields remain visible. Only well-known machine metadata is hidden.
-  content=profile==='full'?{权威合同:raw,来源核对:sourceChecks}:display(raw);
+  content=profile==='full'?{权威合同:raw,来源核对:sourceChecks}:adaptReading(kind,display(raw),{root,ref,blockers});
   if(kind==='api-decision'&&raw.schema_version===2&&raw.draft_review){try{const review=load(raw.draft_review.ref,root).raw;content.实际审查记录=profile==='full'?review:display(review);if(review.result!=='approved'||!Array.isArray(review.blocking_findings)||review.blocking_findings.length)blockers.push('OpenAPI Draft Review 实际记录未批准或有阻断');if(review.draft_ref!==raw.openapi?.ref||review.draft_digest!==raw.openapi?.digest)blockers.push('Draft Review 未绑定当前 OpenAPI');}catch(error){blockers.push(error.message);}}
   if(profile==='task'){
    if(raw.work_units){if(!unit_id)throw new TypeError('含工作单元的合同必须指定 --unit');const matches=raw.work_units.filter(x=>x.id===unit_id);if(matches.length!==1)throw new TypeError(`工作单元缺失或不唯一: ${unit_id}`);content.work_units=matches;}
@@ -111,14 +121,19 @@ function view(ref,{root=process.cwd(),kind,profile='review',unit_id,task_layout=
    content.约束分类='保留未分类字段；本视图只允许阅读，执行影响由资产所有者核验。';
   }
  }
- const view={read_only:true,execution_allowed:false,kind,profile,binding,checks,approval_validity:'not-checked',content,blockers};view.markdown=markdown(view);return view;
+ const view={read_only:true,execution_allowed:false,kind,profile,binding,checks,approval_validity:'not-checked',content,blockers};
+ if(['domain-strategy','stage-decision-package','checkpoint'].includes(kind)) {
+  const presenter=loadLifecyclePresenter(root);
+  view.presentation={names:presenter.catalog(content),sources:presenter.sources,warnings:presenter.warnings};
+ }
+ if(include_reading_model&&['domain-strategy','stage-decision-package','checkpoint','tracking-migration'].includes(kind))view.reading_model=readingViewModel(view,sourceRaw);view.markdown=markdown(view);return view;
 }
 export function diffContract(beforeRef,afterRef,{root=process.cwd(),beforeRoot=root,kind}={}){
  validateKind(kind);if(kind==='slice')return diffSliceContracts(beforeRef,afterRef,{root,beforeRoot});
  const before=load(beforeRef,beforeRoot),after=load(afterRef,root),changes=[];
  const walk=(a,b,p)=>{if(JSON.stringify(a)===JSON.stringify(b))return;if(object(a)&&object(b)){for(const key of new Set([...Object.keys(a),...Object.keys(b)]))walk(a[key],b[key],p?`${p}.${key}`:key);}else changes.push({path:p,before:a??null,after:b??null,category:metadata.test(p.split('.').at(-1))?'binding-change':'requires-review'});};
  walk(before.raw,after.raw,'');const source_checks=[...references(before.raw,beforeRoot).map(x=>({...x,side:'before'})),...references(after.raw,root).map(x=>({...x,side:'after'}))];
- return{read_only:true,approval_reusable:false,execution_allowed:false,before:{ref:beforeRef,digest:hash(before.bytes)},after:{ref:afterRef,digest:hash(after.bytes)},bytes_changed:!before.bytes.equals(after.bytes),changes,source_checks,decision_impact:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。'};
+ const result={read_only:true,approval_reusable:false,execution_allowed:false,before:{ref:beforeRef,digest:hash(before.bytes)},after:{ref:afterRef,digest:hash(after.bytes)},bytes_changed:!before.bytes.equals(after.bytes),changes,source_checks,decision_impact:'必须按当前差异和授权延续协议核验；无法读取旧来源时影响未知。',semantic_changes:readingDiff(before.raw,after.raw)};result.markdown=renderReadingDiff(result);return result;
 }
 
 /** Mechanical review material only; original decisions and semantic review remain authoritative. */
@@ -135,6 +150,10 @@ export function prepareContractReview(beforeRef, afterRef, options = {}) {
         return value;
       } catch(error) { gap('SOURCE_UNREADABLE',ref,`${side}: ${error.message}`,'提供可读取的原始资产；不推断历史内容');return null; }
     };
+    for(const checkpoint of readingCheckpointsForAsset(root,afterRef,options.kind)){
+      const reading=checkReadingViews(root,checkpoint);
+      if(reading.blockers.length)gap('READING_VIEWS_STALE',checkpoint,reading.blockers.join('; '),reading.recovery);
+    }
     const before = readView(beforeRef,'before',options.beforeRoot||root), after = readView(afterRef,'after',root);
     if(before?.binding.id && after?.binding.id && before.binding.id!==after.binding.id)gap('IDENTITY_CONFLICT',afterRef,'前后资产 ID 不一致','选择同一资产的前后版本');
     if(before?.binding.version && before.binding.version===after?.binding.version && before.binding.digest!==after.binding.digest)gap('VERSION_CONFLICT',afterRef,'相同版本包含不同字节','形成新候选版本并重新核验');

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

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

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

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

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

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, validationCache } from './validation-phase.mjs';
 import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { pathToFileURL } from 'node:url';
 
 const schemaCache=Symbol('schema-results');
 const validator = String.raw`
@@ -8,6 +9,8 @@ import json
 import sys
 import traceback
 from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
 validators = {}
 results = []
 expected_bytes = int(sys.argv[1])
@@ -23,12 +26,18 @@ for item in jobs:
         key = (item['schemaPath'], item['formatChecker'])
         if key not in validators:
             schema = json.loads(item['schemaText'])
-            validators[key] = Draft202012Validator(schema, format_checker=FormatChecker() if key[1] else None)
+            Draft202012Validator.check_schema(schema)
+            registry = Registry()
+            for resource in item.get('resources', []):
+                contents = json.loads(resource['text'])
+                Draft202012Validator.check_schema(contents)
+                registry = registry.with_resource(resource['uri'], Resource.from_contents(contents, default_specification=DRAFT202012))
+            validators[key] = Draft202012Validator(schema, registry=registry, format_checker=FormatChecker() if key[1] else None)
         errors = list(validators[key].iter_errors(item['value']))
         if item['errorStyle'] == 'verbose':
             message = '\n'.join(str(error) for error in errors)
         else:
-            errors.sort(key=lambda error: list(error.absolute_path))
+            errors.sort(key=lambda error: [str(part) for part in error.absolute_path])
             message = '\n'.join(f"{'.'.join(str(part) for part in error.absolute_path) or '<root>'}: {error.message}" for error in errors)
         results.append({'valid': not errors, 'error': message})
     except Exception:
@@ -36,6 +45,36 @@ for item in jobs:
 json.dump(results, sys.stdout)
 `;
 
+// Supply the complete local reference closure; never retrieve schemas over the network.
+function schemaResources(schemaPath) {
+  const resources = new Map(), visited = new Set();
+  function load(file, uri) {
+    const text = readFileSync(file, 'utf8'), schema = JSON.parse(text);
+    const fileURI = pathToFileURL(file).href;
+    for (const id of [uri, fileURI, schema.$id].filter(Boolean)) {
+      if (resources.has(id) && resources.get(id) !== text) throw new TypeError(`JSON_SCHEMA_ID_CONFLICT: ${id}`);
+      resources.set(id, text);
+    }
+    if (visited.has(file)) return;
+    visited.add(file);
+    const base = schema.$id || uri || fileURI;
+    function refs(value) {
+      if (!value || typeof value !== 'object') return;
+      for (const [key, ref] of Object.entries(value)) {
+        if (['$ref', '$dynamicRef'].includes(key) && typeof ref === 'string' && !ref.startsWith('#')) {
+          const resource = ref.split('#')[0], resolved = new URL(resource, base).href;
+          if (resources.has(resolved)) continue;
+          if (/^[a-z][a-z0-9+.-]*:/i.test(resource) || path.isAbsolute(resource)) throw new TypeError(`JSON_SCHEMA_OFFLINE: unregistered schema ${ref}`);
+          load(path.resolve(path.dirname(file), resource), resolved);
+        } else refs(ref);
+      }
+    }
+    refs(schema);
+  }
+  load(schemaPath);
+  return [...resources].map(([uri, text]) => ({ uri, text }));
+}
+
 /** One immutable validation phase, never a cache of successful work units. */
 export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30000 } = {}) {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new TypeError("schema timeoutMs 必须是正整数毫秒数");
@@ -45,7 +84,7 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
     const effectiveSchema = path.resolve(schemaPath);
     if (!existsSync(effectiveSchema)) throw new TypeError(`缺少 ${label}: ${effectiveSchema}`);
     if (!["compact", "verbose"].includes(errorStyle)) throw new TypeError(`未知 schema errorStyle: ${errorStyle}`);
-    return { value, schemaPath: effectiveSchema, schemaText: readFileSync(effectiveSchema, 'utf8'), formatChecker, errorStyle };
+    return { value, schemaPath: effectiveSchema, schemaText: readFileSync(effectiveSchema, 'utf8'), resources: schemaResources(effectiveSchema), formatChecker, errorStyle };
   });
   // readall waits for EOF even after the complete JSON has arrived. A known UTF-8
   // byte frame lets the validator finish when a transport keeps its write end open.
@@ -62,7 +101,7 @@ export function validateJsonSchemas(items, { cwd = process.cwd(), timeoutMs = 30
   };
   // Batch identical jobs once and reuse only deterministic checks within this operation.
   // External references retain the uncached path: their dependency closure is not local here.
-  const keys=jobs.map(job=>JSON.stringify([job.schemaPath,job.schemaText,job.value,job.formatChecker,job.errorStyle,path.resolve(cwd),timeoutMs]));
+  const keys=jobs.map(job=>JSON.stringify([job.schemaPath,job.schemaText,job.resources,job.value,job.formatChecker,job.errorStyle,path.resolve(cwd),timeoutMs]));
   const pending=new Map(),cached=new Map();
   for(let i=0;i<jobs.length;i++){
     if(/"\$(?:ref|dynamicRef)"\s*:\s*"(?!#)/.test(jobs[i].schemaText)){pending.set(`${i}:${keys[i]}`,{job:jobs[i],indices:[i],cache:false});continue;}

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

@@ -5,6 +5,7 @@ import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { ROOT, loadRegistry, semanticDigest, validateRegistry } from "./lifecycle-registry.mjs";
 import { loadSkillRegistry } from "./skill-registry.mjs";
+import { loadLifecyclePresenter } from './lifecycle-presentation.mjs';
 
 const LIFECYCLE_REGISTRY_REF = ".template-spec/process/lifecycle-registry.yaml";
 const ORCHESTRATION_CONTRACT_REF = ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml";
@@ -159,6 +160,12 @@ function querySnapshot({ mode, stageId, workUnitId, include = [] } = {}) {
     },
     skills: selectedSkills(route, skillRegistry),
   };
+  const presenter = loadLifecyclePresenter(ROOT);
+  result.presentation = { read_only: true, execution_allowed: false, approval_validity: 'not-checked',
+    names: presenter.catalog(result.lifecycle), sources: presenter.sources, warnings: presenter.warnings };
+  // Include role and transition references from the requested contract subtrees as well.
+  Object.assign(result.presentation.names, presenter.catalog(result.execution));
+  Object.assign(result.presentation.names, presenter.catalog(presenter.roleIds));
   result.references = [...collectPathReferences(result), LIFECYCLE_REGISTRY_REF, ORCHESTRATION_CONTRACT_REF, SKILL_REGISTRY_REF]
     .filter((value, index, all) => all.indexOf(value) === index)
     .sort();

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

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {readFileSync} from './validation-phase.mjs';
+import {parseDocument} from '../vendor/yaml.mjs';
+import {safe} from './strategic-handoff-io.mjs';
+
+const collections = ['stages', 'gates', 'checks', 'artifacts', 'work_units', 'evidence'];
+const token = /(?<![\w./-])(?:stage|gate|check|artifact|work-unit|evidence|role)\.[a-z0-9][a-z0-9-]*(?![\w./-])/g;
+export const presentationRefs = {
+  registry: '.template-spec/process/lifecycle-registry.yaml',
+  roles: '.template-spec/agents/digital-human-roles.yaml',
+};
+
+/** Names describe identities, never approval, readiness or execution authority. */
+export function createLifecyclePresenter(registry = {}, roles = {}) {
+  const records = [...collections.flatMap(key => registry[key] ?? []), ...(roles.roles ?? []), ...(roles.orchestrator ? [roles.orchestrator] : [])];
+  const byId = new Map(records.filter(record => record && typeof record.id === 'string').map(record => [record.id, record]));
+  const describe = id => {
+    const record = byId.get(id);
+    const name = record?.public_name ?? record?.name;
+    return {id, name: typeof name === 'string' && name.trim() ? name : '名称未识别', known: typeof name === 'string' && !!name.trim()};
+  };
+  const label = (id, {trace = true} = {}) => {
+    const item = describe(id);
+    return item.known && !trace ? item.name : `${item.name}（${id}）`;
+  };
+  const text = (value, options) => String(value).replace(token, id => label(id, options));
+  const catalog = value => {
+    const ids = new Set();
+    const visit = item => {
+      if (typeof item === 'string') for (const id of item.match(token) ?? []) ids.add(id);
+      else if (item && typeof item === 'object') for (const [key, child] of Object.entries(item)) { visit(key); visit(child); }
+    };
+    visit(value);
+    return Object.fromEntries([...ids].sort().map(id => [id, describe(id)]));
+  };
+  return {describe, label, text, catalog, roleIds: records.filter(record => typeof record?.id === 'string' && record.id.startsWith('role.')).map(record => record.id)};
+}
+
+/** Optional presentation sources: legacy instances remain readable when names are unavailable. */
+export function loadLifecyclePresenter(root) {
+  const values = {}, sources = [], warnings = [];
+  for (const [key, ref] of Object.entries(presentationRefs)) {
+    let digest = null;
+    try {
+      const bytes = readFileSync(safe(path.resolve(root), ref));
+      digest = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+      const doc = parseDocument(String(bytes), {uniqueKeys: true, maxAliasCount: 0});
+      if (doc.errors.length) throw Error(doc.errors[0].message);
+      const value = doc.toJS({maxAliasCount: 0});
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error('名称来源须为对象');
+      for (const collection of key === 'registry' ? collections : ['roles']) {
+        if (value[collection] !== undefined && !Array.isArray(value[collection])) throw Error(`${collection} 须为数组`);
+      }
+      values[key] = value;
+    } catch (error) {
+      warnings.push(`名称来源不可用：${ref}；${error.message}`);
+    }
+    sources.push({ref, digest});
+  }
+  return {...createLifecyclePresenter(values.registry, values.roles), sources, warnings};
+}
+
+export function renderLifecycleStatus(result) {
+  const view = result.presentation;
+  if (!view) throw Error('缺少状态阅读信息');
+  return [
+    `当前阶段：${view.stage}。登记状态：${view.checkpoint_status}。`,
+    `当前阻塞：${view.blockers.length ? view.blockers.join('；') : '未登记阻塞；完整就绪与批准仍待核验'}。`,
+    `负责人：${view.owner}。`,
+    `下一项工作：${view.work_unit}。`,
+    ...(view.expected_output ? [`预期产出：${view.expected_output}`] : []),
+    `下一动作：${view.next_action}。`,
+    ...view.warnings,
+    '本次为只读查询，未核验完整批准或执行授权。',
+  ].join('\n') + '\n';
+}