create-yss-spec 3.5.3 → 3.5.4

package/template/scripts/lib/checkpoint-boundary.mjs

@@ -0,0 +1,40 @@
+import { readDocument, fileBinding } from './governance-io.mjs';
+
+/** Validate existing lifecycle context evidence; never grants approval. */
+export function assertCheckpointBoundary(value, {root, history=false}={}) {
+  if(history) return {status:'historical-only',execution_authorization:'not-evaluated'};
+  const canonical='.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const contract=readDocument(root,fileBinding(root,canonical)?canonical:'.template-spec/process/checkpoint-boundary.yaml');
+  const registry=readDocument(root,'.template-spec/process/lifecycle-registry.yaml');
+  const stages=new Set(registry.stages.map(x=>x.id));
+  if(!stages.has(value.stage))throw new Error('checkpoint-boundary: 当前 stage 未登记');
+  if(value.next_work_unit!=null&&!registry.work_units.some(x=>x.id===value.next_work_unit))throw new Error('checkpoint-boundary: next_work_unit 未登记');
+  const required=(v,label)=>{if(typeof v!=='string'||!v.trim())throw new Error(`checkpoint-boundary: 缺少 ${label}`);};
+  const reference=(ref,label)=>{required(ref,label);if(!fileBinding(root,ref))throw new Error(`checkpoint-boundary: 证据不可读 ${label}: ${ref}`);};
+  const boundary=value.phase_boundary;
+  if(boundary!==undefined) {
+    if(!boundary||Array.isArray(boundary)||typeof boundary!=='object')throw new Error('checkpoint-boundary: phase_boundary 必须为对象');
+    for(const key of contract.phase_boundary.evidence.required)required(boundary[key],`phase_boundary.${key}`);
+    if(!contract.phase_boundary.choices.includes(boundary.decision))throw new Error('checkpoint-boundary: decision 非法');
+    for(const key of contract.phase_boundary.evidence.conditional[boundary.decision]||[]) {
+      required(boundary[key],`phase_boundary.${key}`);
+      if(key.endsWith('_ref'))reference(boundary[key],key);
+    }
+    if(boundary.decision==='compact'&&!stages.has(boundary.next_phase))throw new Error('checkpoint-boundary: next_phase 必须为当前阶段 ID');
+  }
+  const atBoundary=['paused-human-gate','completed'].includes(value.status)||['handoff','subagent','compact'].includes(boundary?.decision)||
+    (['orchestrate','resume'].includes(value.mode)&&(value.stage!=='stage.entry-triage'||Boolean(value.stage_trace?.completed_work_unit)));
+  if(atBoundary&&!boundary)throw new Error('checkpoint-boundary: 当前边界缺少 phase_boundary');
+  if(atBoundary&&!value.stage_trace)throw new Error('checkpoint-boundary: 当前边界缺少 stage_trace');
+  if(value.stage_trace!==undefined) {
+    const trace=value.stage_trace;
+    if(!trace||Array.isArray(trace)||typeof trace!=='object')throw new Error('checkpoint-boundary: stage_trace 必须为对象');
+    for(const key of contract.checkpoint_policy.required_stage_trace_fields) {
+      if(key==='stage'){if(!stages.has(trace.stage)||trace.stage!==value.stage)throw new Error('checkpoint-boundary: stage_trace.stage 不一致');}
+      else if(!Array.isArray(trace[key]))throw new Error(`checkpoint-boundary: stage_trace.${key} 必须为数组`);
+    }
+    if(trace.completed_work_unit!==undefined&&!registry.work_units.some(x=>x.id===trace.completed_work_unit))throw new Error('checkpoint-boundary: completed_work_unit 非法');
+    for(const key of ['upstream_refs','artifact_refs'])for(const ref of trace[key])reference(typeof ref==='string'?ref:ref?.ref,key);
+  }
+  return {status:'passed',execution_authorization:'not-evaluated'};
+}

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

@@ -1,10 +1,18 @@
+import {readingCheckpointsForAsset,checkReadingViews} from './reading-view-bundle.mjs';
 import {readFileSync,withValidationPhase} from './validation-phase.mjs';
 import {safe,hash,schema} from './strategic-handoff-io.mjs';
 import {parseSliceYaml,readSliceContract} from './slice-contract.mjs';
 import {renderSliceContractView,diffSliceContracts} from './slice-contract-views.mjs';
+import {renderReadingMarkdown} from './reading-view-markdown.mjs';
+import {readingDiff,renderReadingDiff} from './reading-view-diff.mjs';
+import {adaptReading} from './reading-view-adapters.mjs';
+import {readingViewModel} from './reading-view-model.mjs';
 
 // This is a presentation adapter table, never a lifecycle or approval registry.
 export const contractKinds=Object.freeze({
+ 'domain-strategy':'.template-spec/process/schemas/domain-strategy-reading.schema.json',
+ 'stage-decision-package':'.template-spec/process/schemas/stage-decision-package-reading.schema.json',
+ checkpoint:'.template-spec/process/schemas/lifecycle-checkpoint.schema.json','tracking-migration':null,
  slice:null,plan:null,spec:null,'product-design':null,'prototype-confirmation':null,'visual-baseline':null,
  'technical-design':'.agents/skills/yss-technical-design/references/technical-design.schema.json',
  'api-decision':'.template-spec/process/schemas/api-contract-decision.schema.json',
@@ -17,11 +25,11 @@ export const contractKinds=Object.freeze({
 });
 const object=v=>v&&typeof v==='object'&&!Array.isArray(v);
 const stringify=v=>typeof v==='string'?v:JSON.stringify(v,null,2);
-const metadata=/^(schema_version|kind|digest|sha256|subject_digest|.*_digest|.*_sha256|resolution|basis|inputs|sources|artifact_bindings|current_version)$/;
+const metadata=/^(schema_version|digest|sha256|subject_digest|document_digest|referenced_terms_digest)$/;
 function display(value){
  if(Array.isArray(value))return value.map(display);
  if(!object(value))return value;
- return Object.fromEntries(Object.entries(value).filter(([key])=>!metadata.test(key)).map(([k,v])=>[k,display(v)]));
+ return Object.fromEntries(Object.entries(value).map(([k,v])=>[k,display(v)]));
 }
 function validateKind(kind){if(!Object.hasOwn(contractKinds,kind))throw new TypeError(`未知合同类型 ${kind}；可用：${Object.keys(contractKinds).join(', ')}`);}
 function load(ref,root){
@@ -53,16 +61,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 +104,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 +112,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 +120,14 @@ 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(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 +144,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/lifecycle-status.mjs

@@ -1,3 +1,6 @@
+import { businessTicketVersion, businessAuthoringEnabled, businessSetRef, checkBusinessTickets, businessSyncDiagnostics, summarizeBusinessImplementation } from './business-tickets.mjs';
+import { orchestrationRef } from './governance-io.mjs';
+import {checkReadingViews} from './reading-view-bundle.mjs';
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -22,7 +25,7 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   const identity = source(root, 'yss-project.yaml').value;
   if (identity.schema_version !== 1 || identity.repository_mode !== 'project-instance') throw new TypeError('生命周期状态仅适用于 project-instance');
   const registryRef = '.template-spec/process/lifecycle-registry.yaml';
-  const contractRef = '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml';
+  const contractRef = orchestrationRef(root);
   const checkpoint = source(root, checkpointRef), registry = source(root, registryRef), contract = source(root, contractRef);
   const value = checkpoint.value;
   if (value.schema_version !== 1 || value.repository_mode !== 'project-instance') throw new TypeError('checkpoint 身份或版本无效');
@@ -102,6 +105,15 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
       check('task-recovery','passed',[taskPackageRef,...recovery.result_refs],'仅读取任务身份、状态和结果引用；继续前仍须正式验收');
     } catch(error) {issue('task-recovery-invalid',error.message,taskPackageRef,'核对任务身份与实际结果，再执行适用预检');}
   }
+  const setRef=businessSetRef(value);
+  const business = setRef ? checkBusinessTickets({root,setRef,mode:'draft'}) : {status:businessTicketVersion(root)===1?(businessAuthoringEnabled(root)?'missing':'strategic-consumption-not-checked'):'legacy-unassessed',tickets:[],diagnostics:[]};
+  for(const item of business.diagnostics)issue(item.code,item.message,item.source_ref,item.recovery);
+  for(const item of businessSyncDiagnostics(root,setRef,business))issue(item.code,'已声明同步的业务集合引用或摘要过期',item.ref,'重新核对视图引用，不自动修复历史批准');
+  const registered=value.artifacts?.['artifact.business-ticket-set'];
+  const actual=business.inputs?.find(item=>item.ref===setRef)?.digest;
+  if(registered?.digest && registered.digest!==actual)issue('business-sync-stale','业务集合已登记同步但摘要过期',setRef,'重验受影响来源与引用，保留历史批准');
+  if(business.status==='missing'&&!['stage.entry-triage','stage.plan','stage.spec-architecture'].includes(value.stage))issue('business-decomposition-missing','Spec 后业务拆分尚未登记',checkpointRef,'补齐业务草案与覆盖，并回到业务正式化');
+  check('business-decomposition',business.status,[setRef].filter(Boolean),'结构与来源只读检查；不证明批准或实现资格');
   const blockers = [...new Set(diagnostics.filter(x => x.severity === 'error').map(x => x.message))];
   const next_step = {
     action_type: 'verify', work_unit: value.next_work_unit ?? null, cwd: root,
@@ -128,10 +140,14 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
     try { readFileSync(safeTrackingPath(root, script)); next_step.command = ['node', script, checkpointRef]; }
     catch { issue('precheck-unavailable', `预检入口不可读: ${script}`, script, '补齐当前实例工具后执行预检', 'warning'); }
   }
+  const implementationArtifact=value.artifacts?.['artifact.vertical-slice-ticket'];
+  const implementationCoverage=setRef && implementationArtifact?.ref?.endsWith('.md')?summarizeBusinessImplementation({root,setRef,sliceRefs:[implementationArtifact.ref]}):null;
   return {
+    decomposition: {business, implementation: {status:implementationArtifact?'recorded':'not-recorded',recorded_status:implementationArtifact?.status??null,ref:implementationArtifact?.ref??null,coverage:implementationCoverage}, readiness:{status:'not-evaluated',reason:'阶段工作完成不替代批准与实现就绪校验'}},
     schema_version: 1, read_only: true, stage: value.stage, checkpoint_status: value.status,
     work_unit: value.next_work_unit ?? null, owner, blockers, next_action,
     execution_authorization: 'not-evaluated', verification_scope, diagnostics, next_step, recovery,
+    reading_views: checkReadingViews(root,checkpointRef),
     source_digests: { checkpoint: { ref: checkpointRef, digest: checkpoint.digest }, registry: { ref: registryRef, digest: registry.digest }, orchestration: { ref: contractRef, digest: contract.digest }, ...(taskSource?{task:{ref:taskPackageRef,digest:taskSource.digest}}:{}), ...(contractSource?{slice_contract:{ref:task.contract.slice_contract_ref,digest:contractSource.digest}}:{}) },
   };
 }

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

@@ -1,3 +1,6 @@
+import { assertBusinessApprovalBasis } from './business-ticket-lifecycle.mjs';
+import { assertBusinessTicketTransition, assertImplementationTicket } from './business-tickets.mjs';
+import {assertReadingTransition} from './reading-view-bundle.mjs';
 import { assertTrackingTransition } from './stage-tracking.mjs';
 import { assertScopeTransition, assertScopeImpacts, assertScopeWorkUnit, scopedNextRoutes } from './lifecycle-execution-scope.mjs';
 // Wire capability marker: profile-local readiness rules are not interchangeable.
@@ -43,8 +46,9 @@ const NEXT_ROUTES = deepFreeze({
   "work-unit.plan-requirements": ["work-unit.domain-strategy-design", "work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.domain-strategy-design": ["work-unit.stage-decision", "work-unit.spec-synthesis"],
   "work-unit.stage-decision": ["work-unit.spec-synthesis"],
-  "work-unit.spec-synthesis": ["work-unit.prototype-design-v2", "work-unit.technical-analysis"],
-  "work-unit.prototype-design-v2": ["work-unit.technical-analysis"],
+  "work-unit.spec-synthesis": ["work-unit.prototype-design-v2", "work-unit.business-ticket-formalization", "work-unit.technical-analysis"],
+  "work-unit.prototype-design-v2": ["work-unit.business-ticket-formalization", "work-unit.technical-analysis"],
+  "work-unit.business-ticket-formalization": ["work-unit.technical-analysis"],
   "work-unit.technical-analysis": [REPOSITORY_PREPARATION_WORK_UNIT],
   [REPOSITORY_PREPARATION_WORK_UNIT]: [SERVICE_INITIALIZATION_WORK_UNIT, TICKET_DECOMPOSITION_WORK_UNIT],
   [SERVICE_INITIALIZATION_WORK_UNIT]: [REPOSITORY_PREPARATION_WORK_UNIT],
@@ -321,6 +325,10 @@ export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, opt
       }
     } catch (error) { return blockedResult(['maintenance-research-boundary'], [error.message]); }
   }
+  try { assertBusinessTicketTransition(options.root || ROOT, currentWorkUnit, nextRoute, decisionState); assertBusinessApprovalBasis(options.root || ROOT, decisionState, {required:currentWorkUnit === 'work-unit.business-ticket-formalization'}); }
+  catch(error) { return blockedResult(["business-ticket-blocked"],[error.message]); }
+  try { assertReadingTransition(options.root || ROOT, decisionState, currentWorkUnit); }
+  catch(error){ return blockedResult(['reading-views-stale'],[error.message]); }
   try { assertTrackingTransition(currentWorkUnit, nextRoute, decisionState, { root: options.root || ROOT }); }
   catch (error) { return blockedResult(['stage-tracking-blocked'], [error.message]); }
   try { assertScopeTransition(currentWorkUnit, nextRoute, decisionState, options); }
@@ -501,10 +509,11 @@ function validateDecisionBoundary(workUnit, state, options) {
 export function validateTicketFormalization(state, { exists = existsSync, read = (ref) => readFileSync(ref, "utf8"), ...decisionOptions } = {}) {
   if ((state?.tracker_kind ?? "local-markdown") === "local-markdown" && state?.vertical_slice_ticket?.ref && isReadable(state.vertical_slice_ticket.ref, exists)) {
     try {
+      assertImplementationTicket(read(state.vertical_slice_ticket.ref),state.vertical_slice_ticket.ref);
       const header = read(state.vertical_slice_ticket.ref).match(/^---\r?\n([\s\S]*?)\r?\n---/);
       const kind = header ? parseDocument(header[1], { uniqueKeys: true }).toJS({ maxAliasCount: 0 })?.kind : null;
       if (kind === "stage-work-item") return blockedResult(["stage-work-item-not-implementable"], ["vertical-slice-ticket required"]);
-    } catch { return blockedResult(["ticket-content-unreadable"], ["readable vertical slice content"]); }
+    } catch(error) { return blockedResult([error.message.includes("stage-work-item")?"stage-work-item-not-implementable":error.message.includes("business-ticket")?"business-ticket-not-implementable":"ticket-content-unreadable"], [error.message]); }
   }
   try { enforceFrontendDelivery(state, { root: decisionOptions.root, phase: "implementation" }); }
   catch (error) { return blockedResult(["frontend-delivery-blocked"], [error.message]); }