create-yss-spec 3.5.4 → 3.5.5

package/template/scripts/lib/asset-migration.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safeFile } from './governance-io.mjs';
+import { parseAsset, readAsset, serializeAsset, byteDigest, semanticDigest, assetComments, TOOL_ROOT } from './structured-assets.mjs';
+import { planAssetWrite, applyAssetWrite, assertAssetTransactionIdle } from './asset-transactions.mjs';
+
+export function identifyAsset(value) {
+  if (value.stage_decision_id) return 'stage-decision-package';
+  if (value.domain_strategy_id) return 'domain-strategy';
+  if (value.task_id && value.contract && value.execution_state) return 'task-package';
+  if (value.gate_id && value.decision || value.kind === 'review-bundle') return 'approval-record';
+  if (value.repository_mode && value.stage && value.gates) return 'checkpoint';
+  return null;
+}
+const immutable = key => ['verification', 'result', 'source', 'captures', 'history', 'git_checkpoint'].includes(key);
+function refs(value, out = new Set(), key = '') {
+  if (immutable(key)) return out;
+  if (typeof value === 'string' && /(?:^ref$|_ref$|_refs$|^inputs$)/.test(key) && /\.(yaml|json)$/.test(value)) out.add(value);
+  else if (Array.isArray(value)) value.forEach(v => refs(v, out, key));
+  else if (value && typeof value === 'object') for (const [name, child] of Object.entries(value)) refs(child, out, name);
+  return out;
+}
+function replaceRefs(value, mapping, key = '') {
+  if (immutable(key)) return structuredClone(value);
+  if (typeof value === 'string' && /(?:^ref$|_ref$|_refs$|^inputs$)/.test(key)) return mapping[value] || value;
+  if (Array.isArray(value)) return value.map(v => replaceRefs(v, mapping, key));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, replaceRefs(child, mapping, name)]));
+  return value;
+}
+
+/** Produces reviewable candidates, never approval or a second live checkpoint. */
+export function planAssetMigration(root, checkpointRef, { schemaRoot = TOOL_ROOT } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  const queue = [checkpointRef], sources = {}, candidates = [], blockers = [], currentJson = [];
+  while (queue.length) {
+    const ref = queue.shift(); if (Object.hasOwn(sources, ref)) continue;
+    const file = safeFile(root, ref);
+    if (!fs.existsSync(file)) { blockers.push({ code: 'missing-reference', ref }); continue; }
+    const bytes = fs.readFileSync(file), value = parseAsset(bytes, ref), kind = identifyAsset(value);
+    if (!kind) continue; // Original user messages and other evidence keep their format and bytes.
+    sources[ref] = byteDigest(bytes);
+    // Completed execution packages and old reviews remain immutable evidence.
+    if (kind === 'task-package' && ['resolved', 'failed'].includes(value.workflow_status)) continue;
+    readAsset(file, kind, { schemaRoot });
+    queue.push(...refs(value));
+    if (ref.endsWith('.json')) { currentJson.push({ref,value,kind,bytes}); continue; }
+    const target = ref.replace(/\.yaml$/, '.json');
+    if (fs.existsSync(safeFile(root, target))) { blockers.push({ code: 'target-exists', ref: target }); continue; }
+    const comments = assetComments(bytes);
+    if (comments.length) blockers.push({ code: 'comment-review-required', ref, comments });
+    candidates.push({ source_ref: ref, ref: target, kind, source_digest: byteDigest(bytes), source_semantic_digest: semanticDigest(value), value });
+  }
+  const mapping = Object.fromEntries(candidates.map(c => [c.source_ref, c.ref]));
+  for (const item of currentJson) if (semanticDigest(item.value) !== semanticDigest(replaceRefs(item.value, mapping))) {
+    if (item.kind === 'approval-record') blockers.push({code:'current-json-reference-rebind-required',ref:item.ref,reason:'Issue a new approval record; an existing approval is immutable.'});
+    else candidates.push({source_ref:item.ref,ref:item.ref,kind:item.kind,source_digest:byteDigest(item.bytes),source_semantic_digest:semanticDigest(item.value),value:item.value});
+  }
+  for (const c of candidates) {
+    c.value = replaceRefs(c.value, mapping);
+    if (c.kind === 'approval-record' || ['domain-strategy', 'stage-decision-package'].includes(c.kind) && c.value.status === 'approved') {
+      blockers.push({ code: 'approval-rebind-required', ref: c.ref, reason: 'Candidate bytes do not inherit the source approval; issue independent current evidence.' });
+    }
+  }
+  // Updating digests is mechanical only for direct current bindings, not historical proof.
+  const byTarget = new Map(candidates.map(c => [c.ref, c]));
+  const ordered = candidates.sort((a,b) => ['domain-strategy','approval-record','stage-decision-package','task-package','checkpoint'].indexOf(a.kind) - ['domain-strategy','approval-record','stage-decision-package','task-package','checkpoint'].indexOf(b.kind));
+  function bind(value, key = '') {
+    if (!value || typeof value !== 'object' || immutable(key)) return;
+    if (value.domain_strategy_ref && byTarget.has(value.domain_strategy_ref.persisted_ref)) value.domain_strategy_ref.digest = semanticDigest(byTarget.get(value.domain_strategy_ref.persisted_ref).value);
+    if (typeof value.ref === 'string' && typeof value.digest === 'string' && byTarget.has(value.ref)) value.digest = byteDigest(serializeAsset(byTarget.get(value.ref).value));
+    for (const [name, child] of Object.entries(value)) bind(child, name);
+  }
+  for (const c of ordered) bind(c.value);
+  const payload = { schema_version: 1, kind: 'asset-migration-plan', root, checkpoint_ref: checkpointRef, sources, candidates: ordered, blockers, history_policy: 'preserve-original-bytes', execution_authorization: 'not-granted' };
+  return { ...payload, plan_id: byteDigest(serializeAsset(payload)).slice(7) };
+}
+
+/** Resolutions carry reviewed candidate objects and evidence; they do not bypass semantic validators. */
+export function prepareAssetMigrationWrite(root, plan, resolutions, options = {}) {
+  const { plan_id, ...payload } = plan;
+  if (fs.realpathSync(root) !== plan.root || plan.kind !== 'asset-migration-plan' || plan_id !== byteDigest(serializeAsset(payload)).slice(7)) throw new Error('ASSET_MIGRATION_PLAN_INVALID');
+  for (const [ref, digest] of Object.entries(plan.sources)) if (byteDigest(fs.readFileSync(safeFile(root, ref))) !== digest) throw new Error(`ASSET_MIGRATION_DRIFT: ${ref}`);
+  if (plan.blockers.some(b => ['missing-reference', 'target-exists', 'current-json-reference-rebind-required'].includes(b.code))) throw new Error('ASSET_MIGRATION_BLOCKED: rebuild the plan after resolving missing/conflicting inputs');
+  if (plan.blockers.length && (!resolutions || resolutions.plan_id !== plan_id)) throw new Error('ASSET_MIGRATION_REVIEW_REQUIRED');
+  for (const b of plan.blockers) {
+    const resolution = resolutions.items?.find(r => r.ref === b.ref && r.code === b.code);
+    if (!resolution?.evidence_ref || !resolution.evidence_digest || byteDigest(fs.readFileSync(safeFile(root, resolution.evidence_ref))) !== resolution.evidence_digest) throw new Error(`ASSET_MIGRATION_EVIDENCE_REQUIRED: ${b.ref}`);
+  }
+  const replacements = resolutions?.candidates || [];
+  for (const replacement of replacements) if (!plan.candidates.some(c => c.ref === replacement.ref && c.kind === replacement.kind)) throw new Error('ASSET_MIGRATION_SCOPE_CHANGED');
+  const specs = plan.candidates.map(c => replacements.find(r => r.ref === c.ref) || c);
+  const migration={plan_id:plan.plan_id,sources:plan.sources,source_to_target:Object.fromEntries(plan.candidates.filter(c=>c.source_ref!==c.ref).map(c=>[c.source_ref,c.ref]))};
+  return planAssetWrite(root, specs, {...options,migration});
+}
+
+export function applyAssetMigration(root, plan, resolutions, options = {}) {
+  const writePlan = prepareAssetMigrationWrite(root, plan, resolutions, options);
+  const result = applyAssetWrite(root, writePlan, options);
+  const updated = new Set(writePlan.changes.filter(c => Object.hasOwn(plan.sources,c.ref)).map(c => c.ref));
+  return { ...result, migration_plan_id: plan.plan_id, preserved_sources: Object.keys(plan.sources).filter(ref => !updated.has(ref)), rebound_json_sources: [...updated] };
+}

package/template/scripts/lib/asset-transactions.mjs

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { safeFile } from './governance-io.mjs';
+import { parseAsset, readAsset, serializeAsset, byteDigest, semanticDigest, validateAssetStructure, TOOL_ROOT } from './structured-assets.mjs';
+
+const TX = '.yss/asset-transactions';
+const ensure = (ok, message) => { if (!ok) throw new Error(message); };
+const exists = file => fs.existsSync(file);
+const descriptor = file => exists(file) ? { digest: byteDigest(fs.readFileSync(file)), mode: fs.statSync(file).mode & 0o777 } : null;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Adapter for an existing validated writer which also owns Markdown/tracker updates. */
+export function runAssetTransaction(root, changes, action) {
+  root=fs.realpathSync(root);assertAssetTransactionIdle(root);
+  const directory=safeFile(root,TX);fs.mkdirSync(directory,{recursive:true});
+  const lock=safeFile(root,`${TX}/lock`),fd=fs.openSync(lock,'wx');fs.writeFileSync(fd,String(process.pid));fs.fsyncSync(fd);
+  const plan_id=byteDigest(serializeAsset({changes,nonce:randomUUID()})).slice(7),journal_ref=`${TX}/${plan_id}.json`,active=safeFile(root,`${TX}/active.json`);
+  const tx={schema_version:1,root,plan_id,status:'applying',changes,backups:{}};
+  try {
+    ensure(!exists(safeFile(root, `${TX}/recovery.lock`)), 'ASSET_RECOVERY_LOCKED');
+    for(const change of changes){ensure(same(descriptor(safeFile(root,change.ref)),change.before),`ASSET_INPUT_DRIFT: ${change.ref}`);tx.backups[change.ref]=change.before?fs.readFileSync(safeFile(root,change.ref)).toString('base64'):null;}
+    atomic(safeFile(root,journal_ref),serializeAsset(tx));atomic(active,serializeAsset({journal_ref}));
+    const result=action();
+    for(const change of changes)ensure(descriptor(safeFile(root,change.ref))?.digest===change.after_digest,`ASSET_POSTWRITE_DRIFT: ${change.ref}`);
+    tx.status='applied';atomic(safeFile(root,journal_ref),serializeAsset(tx));fs.unlinkSync(active);return result;
+  } catch(error) {
+    if(exists(active)){const recovered=recoverAssetWrite(root,{lockHeld:true});throw new Error(`${error.message}; ${recovered.status}`);}
+    throw error;
+  } finally {fs.closeSync(fd);if(exists(lock))fs.unlinkSync(lock);}
+}
+
+export function assertAssetTransactionIdle(root) {
+  ensure(!exists(safeFile(root, `${TX}/active.json`)), 'ASSET_TRANSACTION_PENDING: recover the unfinished transaction before lifecycle transition');
+}
+
+export function assertCurrentAssetReference(root, ref) {
+  const directory = safeFile(root, TX);
+  if (!exists(directory)) return;
+  for (const name of fs.readdirSync(directory)) {
+    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+    const receipt = parseAsset(fs.readFileSync(path.join(directory, name)), name);
+    if (receipt.status === 'applied' && receipt.migration?.source_to_target?.[ref]) throw new Error(`ASSET_HISTORICAL_ONLY: ${ref}; current=${receipt.migration.source_to_target[ref]}`);
+  }
+}
+
+// The observed closure includes governance, tools and project evidence, but not external checkouts/caches.
+export function observeAssetInputs(root) {
+  const rows = {};
+  function walk(ref) {
+    const file = safeFile(root, ref);
+    if (!exists(file)) return;
+    const st = fs.lstatSync(file);
+    ensure(!st.isSymbolicLink(), `ASSET_SYMLINK: ${ref}`);
+    if (st.isDirectory()) for (const name of fs.readdirSync(file).sort()) {
+      if (['node_modules', '.git', '.codegraph', '__pycache__'].includes(name)) continue;
+      walk(`${ref}/${name}`);
+    }
+    else if (st.isFile()) rows[ref] = descriptor(file);
+  }
+  for (const ref of ['yss-project.yaml', 'CONTEXT.md', 'DESIGN.md', 'AGENTS.md', 'skills-lock.json', '.template-spec', '.agents', 'scripts', 'docs']) walk(ref);
+  return rows;
+}
+
+export function validateAssetSemantics(root, ref, kind) {
+  const file = safeFile(root, ref), { value } = readAsset(file, kind, { schemaRoot: root });
+  let tool, args;
+  if (kind === 'domain-strategy' || kind === 'stage-decision-package') {
+    tool = `.agents/skills/yss-stage-decision/scripts/validate-${kind}.mjs`;
+    args = [file, '--root', root];
+  } else {
+    tool = { checkpoint: 'scripts/verify-lifecycle-checkpoint', 'task-package': 'scripts/verify-digital-human-task-package', 'approval-record': 'scripts/verify-approval-record' }[kind];
+    args = kind === 'approval-record' ? [value.decision === 'approved' || value.kind === 'review-bundle' ? '--require-approved' : '--history', file] : [file];
+  }
+  ensure(exists(safeFile(root, tool)), `ASSET_CONSUMER_MISSING: ${tool}`);
+  const result = spawnSync(process.execPath, [path.join(root, tool), ...args], { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 8 * 1024 * 1024 });
+  ensure(!result.error && result.status === 0, `ASSET_SEMANTIC: ${ref}: ${result.error?.message || result.stderr || result.stdout}`);
+  return { ref, kind, command: [tool, ...args.map(x => x.replaceAll(root, '.'))], exit_code: result.status, output: result.stdout.trim() };
+}
+
+function approvalBindings(root, changes) {
+  for (const change of changes) {
+    const value = parseAsset(change.after, change.ref);
+    // Writers never turn a bare status into an approval. Bound, independently issued evidence is mandatory.
+    const records = change.kind === 'approval-record' ? value.kind === 'review-bundle' ? value.reviews : [value] : [];
+    for (const row of records) if (row.decision === 'approved') {
+      ensure(row.subject_ref && row.subject_digest && row.drafter_principal_ref && row.drafter_principal_ref !== row.principal_ref, 'ASSET_APPROVAL_REBIND_REQUIRED: subject and independent reviewer required');
+      ensure(byteDigest(fs.readFileSync(safeFile(root, row.subject_ref))).replace('sha256:', '') === row.subject_digest.replace('sha256:', ''), 'ASSET_APPROVAL_STALE');
+    }
+    if (['domain-strategy', 'stage-decision-package'].includes(change.kind) && value.status === 'approved') {
+      const approval = parseAsset(fs.readFileSync(safeFile(root, value.approval.approval_ref)), value.approval.approval_ref);
+      const check = change.kind === 'domain-strategy' ? 'check.domain-strategy-approved' : 'check.stage-decision-package-approved';
+      const row = approval.kind === 'review-bundle' ? approval.reviews.find(x => x.gate_id === check) : approval;
+      ensure(row?.subject_ref === change.ref && row.subject_digest?.replace('sha256:', '') === byteDigest(change.after).replace('sha256:', ''), `ASSET_APPROVAL_REBIND_REQUIRED: ${change.ref}`);
+    }
+  }
+}
+
+function overlayVerification(root, observed, changes, { verify = validateAssetSemantics } = {}) {
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'yss-asset-check-'));
+  try {
+    for (const ref of Object.keys(observed)) {
+      const target = safeFile(staging, ref); fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(safeFile(root, ref), target); fs.chmodSync(target, observed[ref].mode);
+    }
+    for (const change of changes) {
+      const target = safeFile(staging, change.ref); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, change.after);
+    }
+    approvalBindings(staging, changes);
+    return changes.map(change => verify(staging, change.ref, change.kind));
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+
+export function planAssetWrite(root, specs, { schemaRoot = TOOL_ROOT, verify, migration } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  ensure(Array.isArray(specs) && specs.length, 'ASSET_EMPTY_PLAN');
+  const observed = observeAssetInputs(root), seen = new Set();
+  const changes = specs.map(({ ref, kind, value }) => {
+    ensure(!seen.has(ref), `ASSET_DUPLICATE_TARGET: ${ref}`); seen.add(ref);
+    ensure(ref.endsWith('.json') && /^(docs\/|\.yss\/)/.test(ref) && !ref.startsWith(`${TX}/`), 'ASSET_WRITE_SCOPE: project JSON assets only');
+    const file = safeFile(root, ref), before = descriptor(file);
+    const legacy = ref.replace(/\.json$/, '.yaml');
+    if (!before && exists(safeFile(root, legacy))) ensure(migration?.source_to_target?.[legacy] === ref, 'ASSET_AMBIGUOUS_AUTHORITY: use plan-migrate');
+    if (kind === 'approval-record' && before) throw new Error('ASSET_IMMUTABLE_APPROVAL: issue a new record');
+    validateAssetStructure(value, kind, { schemaRoot });
+    const after = serializeAsset(value); parseAsset(after, ref);
+    return { ref, kind, before, after, after_digest: byteDigest(after), semantic_digest: semanticDigest(value) };
+  }).filter(change => change.before?.digest !== change.after_digest);
+  for (const change of changes) if (!Object.hasOwn(observed, change.ref)) observed[change.ref] = change.before;
+  const verification = changes.length ? overlayVerification(root, Object.fromEntries(Object.entries(observed).filter(([,v]) => v)), changes, { verify }) : [];
+  const payload = { schema_version: 1, kind: 'asset-write-plan', root, observed, changes, verification, ...(migration ? {migration} : {}), execution_authorization: 'not-granted' };
+  return { ...payload, plan_id: byteDigest(serializeAsset(payload)).slice(7) };
+}
+
+function atomic(file, bytes, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  const fd = fs.openSync(temp, 'wx', mode);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  try { ensure(fs.readFileSync(temp).equals(Buffer.from(bytes)), 'ASSET_TEMP_READBACK'); fs.renameSync(temp, file); const dir = fs.openSync(path.dirname(file), 'r'); try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); } }
+  finally { if (exists(temp)) fs.unlinkSync(temp); }
+}
+
+export function applyAssetWrite(root, plan, { verify, afterWrite } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  const { plan_id, ...payload } = plan;
+  ensure(plan.root === root && plan.kind === 'asset-write-plan' && plan_id === byteDigest(serializeAsset(payload)).slice(7), 'ASSET_PLAN_INVALID');
+  const directory = safeFile(root, TX); fs.mkdirSync(directory, { recursive: true });
+  const lock = safeFile(root, `${TX}/lock`), fd = fs.openSync(lock, 'wx');
+  fs.writeFileSync(fd, String(process.pid));fs.fsyncSync(fd);
+  const active = safeFile(root, `${TX}/active.json`);
+  let transaction;
+  try {
+    ensure(!exists(safeFile(root, `${TX}/recovery.lock`)), 'ASSET_RECOVERY_LOCKED');
+    const current = observeAssetInputs(root);
+    for (const [ref, before] of Object.entries(plan.observed)) ensure(same(descriptor(safeFile(root, ref)), before), `ASSET_INPUT_DRIFT: ${ref}`);
+    ensure(Object.keys(current).every(ref => Object.hasOwn(plan.observed, ref)), 'ASSET_INPUT_DRIFT: new dependency files');
+    if (!plan.changes.length) return { status: 'unchanged', plan_id, changed_refs: [], execution_authorization: 'not-granted' };
+    // Recompute, including schemas and semantics. A plan's recorded successful exit is never trusted.
+    if(plan.migration) for(const [ref,digest] of Object.entries(plan.migration.sources)) ensure(byteDigest(fs.readFileSync(safeFile(root,ref)))===digest,`ASSET_MIGRATION_DRIFT: ${ref}`);
+    const fresh = planAssetWrite(root, plan.changes.map(c => ({ ref: c.ref, kind: c.kind, value: parseAsset(c.after, c.ref) })), { schemaRoot: root, verify, migration:plan.migration });
+    ensure(same(fresh.changes, plan.changes), 'ASSET_PLAN_CHANGED');
+    const journalRef = `${TX}/${plan_id}.json`, journalFile = safeFile(root, journalRef);
+    ensure(!exists(journalFile), 'ASSET_ALREADY_APPLIED: inspect the existing receipt');
+    transaction = { schema_version: 1, plan_id, root, status: 'applying', ...(plan.migration?{migration:plan.migration}:{}), changes: plan.changes, backups: Object.fromEntries(plan.changes.map(c => [c.ref, c.before ? fs.readFileSync(safeFile(root, c.ref)).toString('base64') : null])) };
+    atomic(journalFile, serializeAsset(transaction)); atomic(active, serializeAsset({ journal_ref: journalRef }));
+    for (const change of plan.changes) {
+      ensure(same(descriptor(safeFile(root, change.ref)), change.before), `ASSET_INPUT_DRIFT: ${change.ref}`);
+      atomic(safeFile(root, change.ref), change.after, change.before?.mode ?? 0o644);
+      readAsset(safeFile(root, change.ref), change.kind, { schemaRoot: root });
+      afterWrite?.(change);
+    }
+    for (const [ref, before] of Object.entries(plan.observed)) {
+      const change = plan.changes.find(c => c.ref === ref);
+      ensure(descriptor(safeFile(root, ref))?.digest === (change?.after_digest ?? before?.digest), `ASSET_POSTWRITE_DRIFT: ${ref}`);
+    }
+    ensure(Object.keys(observeAssetInputs(root)).every(ref => Object.hasOwn(plan.observed, ref)), 'ASSET_POSTWRITE_DRIFT: new dependency files');
+    transaction.status = 'applied'; atomic(journalFile, serializeAsset(transaction)); fs.unlinkSync(active);
+    return { status: 'applied', plan_id, changed_refs: plan.changes.map(c => c.ref), receipt_ref: journalRef, execution_authorization: 'not-granted' };
+  } catch (error) {
+    if (transaction && exists(active)) {
+      const result = recoverAssetWrite(root, { lockHeld: true });
+      throw new Error(`${error.message}; ${result.status}: ${result.conflicts.join(',')}`);
+    }
+    throw error;
+  } finally { fs.closeSync(fd); if (exists(lock)) fs.unlinkSync(lock); }
+}
+
+export function recoverAssetWrite(root, { lockHeld = false, recoveryHeld = false } = {}) {
+  root = fs.realpathSync(root);
+  const lock = safeFile(root, `${TX}/lock`);
+  if (!lockHeld && !recoveryHeld) {
+    const guard = safeFile(root, `${TX}/recovery.lock`);
+    fs.mkdirSync(path.dirname(guard), { recursive: true });
+    const fd = fs.openSync(guard, 'wx');
+    try {
+      fs.writeFileSync(fd, String(process.pid)); fs.fsyncSync(fd);
+      return recoverAssetWrite(root, { recoveryHeld: true });
+    } finally { fs.closeSync(fd); fs.unlinkSync(guard); }
+  }
+  if (!lockHeld && exists(lock)) {
+    const pid=Number(fs.readFileSync(lock,'utf8'));ensure(Number.isInteger(pid)&&pid>0,'ASSET_LOCK_INVALID');
+    let live=true;try{process.kill(pid,0);}catch(error){if(error.code==='ESRCH')live=false;else throw error;}
+    ensure(!live,'ASSET_LOCKED: writer is still alive');fs.unlinkSync(lock);
+  }
+  if (!lockHeld) {
+    fs.mkdirSync(path.dirname(lock), { recursive: true });
+    const fd = fs.openSync(lock, 'wx');
+    try {
+      fs.writeFileSync(fd, String(process.pid)); fs.fsyncSync(fd);
+      return recoverAssetWrite(root, { lockHeld: true });
+    } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+  }
+  const active = safeFile(root, `${TX}/active.json`);
+  if (!exists(active)) return { status: 'idle', conflicts: [] };
+  const marker = parseAsset(fs.readFileSync(active), active), journalFile = safeFile(root, marker.journal_ref);
+  ensure(marker.journal_ref.startsWith(`${TX}/`), 'ASSET_JOURNAL_PATH');
+  const tx = parseAsset(fs.readFileSync(journalFile), journalFile);
+  ensure(tx.root === root && ['applying', 'recovery-conflict','applied'].includes(tx.status), 'ASSET_JOURNAL_INVALID');
+  if(tx.status==='applied') {for(const c of tx.changes)ensure(descriptor(safeFile(root,c.ref))?.digest===c.after_digest,'ASSET_RECOVERY_CONFLICT');fs.unlinkSync(active);return{status:'applied',conflicts:[]};}
+  const conflicts = [];
+  for (const change of [...tx.changes].reverse()) {
+    ensure(byteDigest(change.after)===change.after_digest && (change.before===null?tx.backups[change.ref]===null:byteDigest(Buffer.from(tx.backups[change.ref],'base64'))===change.before.digest),'ASSET_JOURNAL_CORRUPT');
+    const file = safeFile(root, change.ref), actual = descriptor(file);
+    if (same(actual, change.before)) continue;
+    if (actual?.digest !== change.after_digest) { conflicts.push(change.ref); continue; }
+    if (tx.backups[change.ref] === null) fs.unlinkSync(file);
+    else atomic(file, Buffer.from(tx.backups[change.ref], 'base64'), change.before.mode);
+  }
+  tx.status = conflicts.length ? 'recovery-conflict' : 'rolled-back'; tx.conflicts = conflicts;
+  atomic(journalFile, serializeAsset(tx)); if (!conflicts.length) fs.unlinkSync(active);
+  return { status: tx.status, conflicts };
+}

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

@@ -1,8 +1,11 @@
 import { readDocument, fileBinding } from './governance-io.mjs';
+import { assertAssetTransactionIdle, assertCurrentAssetReference } from './asset-transactions.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'};
+  assertAssetTransactionIdle(root);
+  if(value.stage_tracking?.checkpoint_ref)assertCurrentAssetReference(root,value.stage_tracking.checkpoint_ref);
   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');

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

@@ -4,6 +4,7 @@ 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';
@@ -120,7 +121,12 @@ 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};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;
+ 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});

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

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

@@ -6,6 +6,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseDocument } from '../vendor/yaml.mjs';
 import { safeTrackingPath, trackingDrift } from './stage-tracking.mjs';
+import { loadLifecyclePresenter } from './lifecycle-presentation.mjs';
 
 const sha = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 function parse(bytes) {
@@ -52,7 +53,7 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   if (value.next_work_unit && !workUnit) issue('unknown-work-unit', `未知下一工作单元: ${value.next_work_unit}`, registryRef, '按注册表核对下一工作单元');
   if (workUnit && workUnit.id !== 'work-unit.entry-triage' && !contract.value.work_unit_routes?.[workUnit.id]) issue('missing-route', `缺少执行路由: ${workUnit.id}`, contractRef, '修复当前合同路由后重验');
   check('stage-and-route', diagnostics.some(x => ['unknown-stage', 'unknown-work-unit', 'missing-route'].includes(x.code)) ? 'failed' : 'passed', [registryRef, contractRef], '仅检查身份与路由存在，不计算完整 frontier');
-  if (value.context_reconciliation?.status === 'blocked') issue('context-blocked', 'Context reconciliation blocked', checkpointRef, '修复词汇对账并执行适用校验');
+  if (value.context_reconciliation?.status === 'blocked') issue('context-blocked', '术语对账受阻', checkpointRef, '修复词汇对账并执行适用校验');
   check('context-reconciliation', value.context_reconciliation?.status === 'blocked' ? 'failed' : 'not-checked', [value.context_reconciliation?.ref].filter(Boolean), '读取登记状态；当前对账内容和摘要仍须由原验证器核验');
   for (const [id, gate] of Object.entries(value.gates ?? {})) {
     if (['blocked', 'stale'].includes(gate?.status)) issue('gate-blocked', `${id}: ${gate.status}`, checkpointRef, '核对受影响依据和当前批准');
@@ -142,7 +143,21 @@ export function lifecycleStatus({ root, checkpointRef, taskPackageRef }) {
   }
   const implementationArtifact=value.artifacts?.['artifact.vertical-slice-ticket'];
   const implementationCoverage=setRef && implementationArtifact?.ref?.endsWith('.md')?summarizeBusinessImplementation({root,setRef,sliceRefs:[implementationArtifact.ref]}):null;
+  const presenter = loadLifecyclePresenter(root);
+  const statusNames = { routing: '正在确定下一步', running: '正在推进', blocked: '受阻', 'paused-human-gate': '等待会签', completed: '记录为已完成，仍需核验' };
+  const readable = text => presenter.text(text, {trace: false}).replace(/: (blocked|stale)$/, (_, status) => status === 'blocked' ? '：受阻' : '：依据已过期，需重新核验');
+  const presentation = {
+    read_only: true, execution_allowed: false, approval_validity: 'not-checked',
+    stage: value.stage ? presenter.label(value.stage, {trace: false}) : '未登记',
+    checkpoint_status: Object.hasOwn(statusNames, value.status) ? statusNames[value.status] : `未识别状态（${value.status ?? '未登记'}）`,
+    work_unit: value.next_work_unit ? presenter.label(value.next_work_unit, {trace: false}) : '未登记',
+    owner: presenter.text(owner, {trace: false}), blockers: blockers.map(readable),
+    expected_output: workUnit ? readable(workUnit.public_output ?? workUnit.output ?? '产出说明未登记') : null,
+    next_action: readable(next_action), sources: presenter.sources, warnings: presenter.warnings,
+    names: presenter.catalog({stage: value.stage, work_unit: value.next_work_unit, owner, gates: value.gates, artifacts: value.artifacts}),
+  };
   return {
+    presentation,
     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,