create-yss-spec 3.4.8 → 3.4.10

package/template/scripts/lib/stage-tracking-migration.mjs

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, statSync, openSync, closeSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument, stringify } from '../vendor/yaml.mjs';
+import { TRACKER_REF, STAGE_WORK_UNITS, sha256, safeTrackingPath, readTracking, parseYaml, trackerConfig, isDesign, binding, assertStageTracking, refreshTracking } from './stage-tracking.mjs';
+
+const descriptor = (root, ref) => { const p = safeTrackingPath(root, ref); return existsSync(p) ? { digest: sha256(readFileSync(p)), mode: statSync(p).mode & 0o777 } : null; };
+const json = x => `${JSON.stringify(x, null, 2)}\n`;
+function featureFrom(ref) {
+  const match = /^docs\/\.scratch\/([a-z0-9][a-z0-9-]*)\/[^/]+\.(yaml|json)$/.exec(ref);
+  if (!match) throw new Error('tracking-checkpoint-path-invalid');
+  return match[1];
+}
+function identity(root) {
+  const value = parseYaml(readTracking(root, 'yss-project.yaml'));
+  if (value?.schema_version !== 1 || value.repository_mode !== 'project-instance') throw new Error('stage-tracking-project-instance-required');
+}
+function enabledTracker(bytes) {
+  const match = bytes.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error('tracking-tracker-frontmatter-required');
+  const doc = parseDocument(match[1], { uniqueKeys: true });
+  doc.setIn(['tracker', 'lifecycle_tracking_version'], 1);
+  return `---\n${doc.toString()}---${bytes.slice(match[0].length)}`;
+}
+function definition(item, checkpointRef) {
+  const fields = { kind: item.kind, id: item.id, checkpoint_ref: checkpointRef };
+  return `---\n${stringify(fields)}---\n# ${item.title}\n\n负责人：${item.owner}\n\n${item.scope}\n\n## 验收\n\n${item.acceptance.map(x => `- ${x}`).join('\n')}\n\n当前进度、依赖与完成证据以 ${checkpointRef} 中的 ${item.id} 为准。\n`;
+}
+export function checkTracking(root, checkpointRef) {
+  identity(root);
+  const feature = featureFrom(checkpointRef);
+  const config = trackerConfig(root);
+  if (!existsSync(safeTrackingPath(root, checkpointRef))) return { status: 'missing-checkpoint', feature_id: feature, enabled: config.lifecycle_tracking_version === 1 };
+  const checkpoint = parseYaml(readTracking(root, checkpointRef));
+  try {
+    const result = assertStageTracking(checkpoint, { root, checkpointRef });
+    return { ...result, feature_id: checkpoint.feature_id || feature, enabled: config.lifecycle_tracking_version === 1, migration_required: !checkpoint.stage_tracking };
+  } catch (error) { return { status: 'blocked', feature_id: feature, enabled: config.lifecycle_tracking_version === 1, error: error.message, migration_required: !checkpoint.stage_tracking }; }
+}
+export function planTracking(root, { checkpoint_ref, items = [], refresh = false } = {}) {
+  root = path.resolve(root); identity(root);
+  const feature = featureFrom(checkpoint_ref);
+  trackerConfig(root);
+  const changes = [], observed = {}, gaps = [];
+  function watch(ref) { observed[ref] = descriptor(root, ref); }
+  function change(ref, after) {
+    watch(ref);
+    if (!observed[ref] || sha256(after) !== observed[ref].digest) changes.push({ ref, before: observed[ref], after, after_digest: sha256(after) });
+  }
+  for (const ref of ['yss-project.yaml', 'CONTEXT.md', TRACKER_REF, 'docs/process/lifecycle-registry.yaml', 'docs/process/schemas/stage-tracking.schema.json', 'docs/process/harness-profile.yaml', checkpoint_ref]) watch(ref);
+  const exists = observed[checkpoint_ref] !== null;
+  let checkpoint;
+  if (exists) checkpoint = parseYaml(readTracking(root, checkpoint_ref));
+  else {
+    const template = 'docs/process/templates/lifecycle-checkpoint-template.yaml'; watch(template);
+    checkpoint = parseYaml(readTracking(root, template));
+    checkpoint.feature_id = feature;
+    checkpoint.mode = 'orchestrate'; checkpoint.status = 'running';
+    checkpoint.stage = items[0]?.stage || 'stage.plan';
+    checkpoint.next_work_unit = items[0]?.work_unit || 'work-unit.plan-requirements';
+  }
+  checkpoint.feature_id ??= feature;
+  const design = isDesign(root);
+  checkpoint.stage_tracking ??= { schema_version: 1, feature_id: checkpoint.feature_id, checkpoint_ref, entry_stage: checkpoint.stage,
+    entry: { kind: design ? 'checkpoint' : 'parent-ticket', ref: design ? checkpoint_ref : `docs/.scratch/${feature}/parent-ticket.md` }, items: [] };
+  if (refresh) checkpoint = refreshTracking(root, checkpoint).checkpoint;
+  const tracking = checkpoint.stage_tracking;
+  const ids = new Set(tracking.items.map(x => x.id));
+  for (const seed of items) {
+    if (ids.has(seed.id)) {
+      // Resume never overwrites a live item with an older task definition.
+      const existing = tracking.items.find(x => x.id === seed.id);
+      for (const key of ['title', 'owner', 'scope', 'stage', 'work_unit', 'acceptance', 'dependencies', 'split_reasons']) if (JSON.stringify(seed[key] ?? existing[key]) !== JSON.stringify(existing[key])) throw new Error(`tracking-existing-item-conflict: ${seed.id}.${key}`);
+      continue;
+    }
+    if (seed.progress && seed.progress !== 'pending') throw new Error('tracking-migration-cannot-infer-completion');
+    const item = { id: seed.id, kind: 'stage-work-item', title: seed.title, stage: seed.stage, work_unit: seed.work_unit, owner: seed.owner, scope: seed.scope,
+      acceptance: seed.acceptance, dependencies: seed.dependencies || [], source_refs: (seed.source_refs || []).map(ref => binding(root, typeof ref === 'string' ? ref : ref.ref)),
+      progress: 'pending', split_reasons: seed.split_reasons || [], completion: [] };
+    if (seed.deferred) { item.deferred = seed.deferred; if (!item.split_reasons.includes('cross-stage-deferral')) item.split_reasons.push('cross-stage-deferral'); }
+    tracking.items.push(item); ids.add(item.id);
+  }
+  for (const item of tracking.items) {
+    if (tracking.items.some(other => other.dependencies.includes(item.id)) && !item.split_reasons.includes('blocks-other-work')) item.split_reasons.push('blocks-other-work');
+    if (tracking.items[0]?.owner && item.owner !== tracking.items[0].owner && !item.split_reasons.includes('different-owner')) item.split_reasons.push('different-owner');
+  }
+  if (!tracking.items.length) gaps.push('需要明确当前阶段工作项及负责人、范围和验收条件；不从历史文件推断完成');
+  if (!tracking.items.some(i => i.stage === checkpoint.stage) && ['stage.plan', 'stage.spec-architecture', 'stage.product-design'].includes(checkpoint.stage)) gaps.push('当前阶段缺少工作项');
+  for (const item of tracking.items) {
+    for (const key of ['id', 'title', 'owner', 'scope', 'stage', 'work_unit']) if (typeof item[key] !== 'string' || !item[key].trim()) gaps.push(`${item.id || '?'} 缺少 ${key}`);
+    if (!item.acceptance?.length) gaps.push(`${item.id || '?'} 缺少验收条件`);
+    for (const source of [...item.source_refs, ...item.completion.flatMap(x => x.evidence_refs)]) watch(source.ref);
+    if (item.deferred) watch(item.deferred.decision_ref);
+    if (item.split_reasons?.length && !gaps.length) {
+      const ref = `docs/.scratch/${feature}/work-items/${item.id}.md`;
+      if (!item.definition_ref) {
+        if (descriptor(root, ref)) throw new Error(`tracking-unowned-file-conflict: ${ref}`);
+        item.definition_ref = ref;
+        const content = definition(item, checkpoint_ref);
+        item.definition_digest = sha256(content); change(ref, content);
+      } else watch(item.definition_ref);
+    }
+  }
+  const entryRef = tracking.entry.ref;
+  if (!design) {
+    watch(entryRef);
+    const link = `\n阶段工作进度与证据：${checkpoint_ref}\n`;
+    if (!observed[entryRef]) change(entryRef, `# ${feature}\n\nStatus: needs-triage\n${link}${trackerConfig(root).platform !== 'local-markdown' ? `\npublication: pending\npending_publication_to: ${trackerConfig(root).platform}\n` : ''}`);
+    else if (!readTracking(root, entryRef).includes(checkpoint_ref)) change(entryRef, readTracking(root, entryRef) + link);
+  }
+  const mapRef = `docs/.scratch/${feature}/map.md`; watch(mapRef);
+  if (!observed[mapRef]) change(mapRef, `---\ncheckpoint_ref: ${checkpoint_ref}\n---\n# ${feature}\n\n阶段工作与证据见 ${checkpoint_ref}。\n`);
+  else if (!readTracking(root, mapRef).includes(checkpoint_ref)) change(mapRef, readTracking(root, mapRef) + `\n阶段工作与证据：${checkpoint_ref}\n`);
+  change(checkpoint_ref, checkpoint_ref.endsWith('.json') ? json(checkpoint) : stringify(checkpoint));
+  change(TRACKER_REF, enabledTracker(readTracking(root, TRACKER_REF)));
+  const input = { checkpoint_ref, items, refresh };
+  const payload = { schema_version: 1, root, input, gaps, observed, changes };
+  return { ...payload, plan_id: sha256(JSON.stringify(payload)).slice(7) };
+}
+export function applyTracking(root, plan, { afterWrite } = {}) {
+  root = path.resolve(root); identity(root);
+  if (plan.root !== root || plan.schema_version !== 1 || !/^[a-f0-9]{64}$/.test(plan.plan_id)) throw new Error('tracking-plan-identity-invalid');
+  const { plan_id, ...payload } = plan;
+  if (sha256(JSON.stringify(payload)).slice(7) !== plan_id) throw new Error('tracking-plan-digest-mismatch');
+  const feature = featureFrom(plan.input.checkpoint_ref);
+  const transactionRef = `docs/.scratch/${feature}/verification/stage-tracking-migrations/${plan_id}`;
+  const receiptRef = `${transactionRef}/receipt.json`;
+  if (existsSync(safeTrackingPath(root, receiptRef))) {
+    const receipt = JSON.parse(readTracking(root, receiptRef));
+    if (receipt.plan_id !== plan_id) throw new Error('tracking-receipt-conflict');
+    return { status: 'unchanged', plan_id, receipt_ref: receiptRef };
+  }
+  if (plan.gaps.length) throw new Error(`tracking-migration-needs-info: ${plan.gaps.join('; ')}`);
+  const fresh = planTracking(root, plan.input);
+  if (JSON.stringify(fresh) !== JSON.stringify(plan)) throw new Error('tracking-plan-stale');
+  if (!plan.changes.length) return { status: 'unchanged', plan_id };
+  const transactionPath = safeTrackingPath(root, transactionRef);
+  if (existsSync(transactionPath)) throw new Error(`tracking-transaction-needs-recovery: ${transactionRef}`);
+  mkdirSync(transactionPath, { recursive: true });
+  const backups = plan.changes.map(c => ({ ref: c.ref, before: c.before, bytes: c.before ? readFileSync(safeTrackingPath(root, c.ref)).toString('base64') : null }));
+  writeFileSync(path.join(transactionPath, 'backup.json'), json(backups), { flag: 'wx' });
+  writeFileSync(path.join(transactionPath, 'plan.json'), json(plan), { flag: 'wx' });
+  const written = [], temporary = new Set();
+  try {
+    for (const [ref, before] of Object.entries(plan.observed)) if (JSON.stringify(descriptor(root, ref)) !== JSON.stringify(before)) throw new Error('tracking-concurrent-change');
+    for (const change of plan.changes) {
+      const file = safeTrackingPath(root, change.ref);
+      if (JSON.stringify(descriptor(root, change.ref)) !== JSON.stringify(change.before)) throw new Error('tracking-concurrent-change');
+      mkdirSync(path.dirname(file), { recursive: true });
+      const temp = `${file}.stage-tracking-${plan_id}`;
+      const fd = openSync(temp, 'wx', change.before?.mode || 0o644);
+      temporary.add(temp);
+      try { writeFileSync(fd, change.after); } finally { closeSync(fd); }
+      renameSync(temp, file); temporary.delete(temp); written.push(change);
+      afterWrite?.(change, written.length);
+    }
+    for (const [ref, before] of Object.entries(plan.observed)) {
+      const changed = written.find(x => x.ref === ref);
+      const actual = descriptor(root, ref);
+      if (changed ? actual?.digest !== changed.after_digest : JSON.stringify(actual) !== JSON.stringify(before)) throw new Error('tracking-concurrent-change');
+    }
+    const cp = parseYaml(readTracking(root, plan.input.checkpoint_ref));
+    assertStageTracking(cp, { root, checkpointRef: plan.input.checkpoint_ref });
+    writeFileSync(safeTrackingPath(root, receiptRef), json({ plan_id, status: 'applied', changed_refs: written.map(x => x.ref) }), { flag: 'wx' });
+    return { status: 'applied', plan_id, receipt_ref: receiptRef, changed_refs: written.map(x => x.ref) };
+  } catch (error) {
+    const conflicts = [];
+    for (const temp of temporary) { try { unlinkSync(temp); } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') conflicts.push(temp); } }
+    for (const change of written.reverse()) {
+      if (descriptor(root, change.ref)?.digest !== change.after_digest) { conflicts.push(change.ref); continue; }
+      const backup = backups.find(x => x.ref === change.ref), file = safeTrackingPath(root, change.ref);
+      if (backup.bytes === null) unlinkSync(file); else writeFileSync(file, Buffer.from(backup.bytes, 'base64'), { mode: backup.before.mode });
+    }
+    writeFileSync(path.join(transactionPath, 'failure.json'), json({ error: error.message, recovery_conflicts: conflicts }));
+    throw new Error(`${error.message}; tracking-rollback-${conflicts.length ? `conflict:${conflicts.join(',')}` : 'complete'}`);
+  }
+}

package/template/scripts/lib/stage-tracking.mjs

@@ -0,0 +1,184 @@
+import { readFileSync, existsSync, lstatSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseDocument } from '../vendor/yaml.mjs';
+import { validateJsonSchema } from './json-schema.mjs';
+
+export const TRACKER_REF = 'docs/agents/issue-tracker.md';
+export const STAGE_WORK_UNITS = Object.freeze({
+  'work-unit.plan-opportunity': 'stage.plan',
+  'work-unit.plan-requirements': 'stage.plan',
+  'work-unit.domain-strategy-design': 'stage.plan',
+  'work-unit.stage-decision': 'stage.plan',
+  'work-unit.spec-synthesis': 'stage.spec-architecture',
+  'work-unit.prototype-design': 'stage.product-design',
+});
+export const sha256 = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+export function parseYaml(bytes) {
+  const doc = parseDocument(String(bytes), { uniqueKeys: true });
+  if (doc.errors.length) throw new Error(doc.errors[0].message);
+  return doc.toJS({ maxAliasCount: 0 });
+}
+export function safeTrackingPath(root, ref) {
+  if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || ref.includes('\\') || ref.split('/').some(p => !p || p === '.' || p === '..')) throw new Error(`tracking-path-invalid: ${ref}`);
+  const base = realpathSync(root);
+  let file = base;
+  for (const part of ref.split('/')) {
+    file = path.join(file, part);
+    if (existsSync(file) || (() => { try { lstatSync(file); return true; } catch { return false; } })()) {
+      if (lstatSync(file).isSymbolicLink()) throw new Error(`tracking-symlink-forbidden: ${ref}`);
+    }
+  }
+  return file;
+}
+export const readTracking = (root, ref) => readFileSync(safeTrackingPath(root, ref), 'utf8');
+export const binding = (root, ref) => ({ ref, digest: sha256(readTracking(root, ref)) });
+export function trackerConfig(root) {
+  const bytes = readTracking(root, TRACKER_REF);
+  const match = bytes.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error('tracking-tracker-frontmatter-required');
+  const config = parseYaml(match[1])?.tracker;
+  if (!config || !['local-markdown', 'github', 'gitlab'].includes(config.platform)) throw new Error('tracking-tracker-invalid');
+  if (config.lifecycle_tracking_version !== undefined && config.lifecycle_tracking_version !== 1) throw new Error('tracking-version-unsupported');
+  return config;
+}
+export function trackingProfile(root) {
+  const ref = 'docs/process/harness-profile.yaml';
+  return existsSync(safeTrackingPath(root, ref)) ? parseYaml(readTracking(root, ref)) : null;
+}
+export const isDesign = root => trackingProfile(root)?.profile_id === 'harness.business-ddd-strategy-handoff';
+function current(root, value) {
+  try { return binding(root, value.ref).digest === value.digest; } catch { return false; }
+}
+export function trackingDrift(root, tracking) {
+  const changed = new Set(tracking.items.filter(item => [...item.source_refs, ...item.completion.flatMap(c => c.evidence_refs)].some(b => !current(root, b))).map(item => item.id));
+  let size;
+  do {
+    size = changed.size;
+    for (const item of tracking.items) if (item.dependencies.some(id => changed.has(id))) changed.add(item.id);
+  } while (size !== changed.size);
+  return [...changed];
+}
+export function refreshTracking(root, checkpoint) {
+  const next = structuredClone(checkpoint);
+  const changed = trackingDrift(root, next.stage_tracking);
+  for (const item of next.stage_tracking.items) {
+    if (changed.includes(item.id) && item.progress !== 'cancelled') {
+      item.progress = 'pending';
+      item.recheck_required = true;
+      // Old bindings and evidence remain historical; only explicit re-verification replaces them.
+    }
+  }
+  return { checkpoint: next, stale_item_ids: changed };
+}
+export function assertStageTracking(checkpoint, { root, checkpointRef, currentWorkUnit, nextWorkUnit, transition = false, entering = false, now = new Date() } = {}) {
+  const identity = parseYaml(readTracking(root, 'yss-project.yaml'));
+  if (identity?.schema_version !== 1 || !['template-source', 'project-instance'].includes(identity.repository_mode)) throw new Error('tracking-repository-identity-invalid');
+  const config = trackerConfig(root);
+  const tracking = checkpoint?.stage_tracking;
+  const relevant = STAGE_WORK_UNITS[currentWorkUnit] || STAGE_WORK_UNITS[nextWorkUnit] || ['stage.plan', 'stage.spec-architecture', 'stage.product-design'].includes(checkpoint?.stage);
+  if (!tracking) {
+    if (identity.repository_mode === 'project-instance' && config.lifecycle_tracking_version === 1 && relevant) throw new Error('stage-tracking-required');
+    return { status: 'not-applicable', stale_item_ids: [] };
+  }
+  validateJsonSchema(tracking, path.join(root, 'docs/process/schemas/stage-tracking.schema.json'));
+  const feature = checkpoint.feature_id;
+  if (feature !== tracking.feature_id || typeof feature !== 'string' || !feature.trim()) throw new Error('tracking-feature-mismatch');
+  const location = /^(docs\/\.scratch\/[a-z0-9][a-z0-9-]*\/)[^/]+\.(yaml|json)$/.exec(tracking.checkpoint_ref);
+  if (!location) throw new Error('tracking-checkpoint-path-invalid');
+  const base = location[1];
+  if (!tracking.checkpoint_ref.startsWith(base) || (checkpointRef && tracking.checkpoint_ref !== checkpointRef)) throw new Error('tracking-checkpoint-mismatch');
+  safeTrackingPath(root, tracking.checkpoint_ref);
+  if (isDesign(root)) {
+    if (tracking.entry.kind !== 'checkpoint' || tracking.entry.ref !== tracking.checkpoint_ref) throw new Error('tracking-design-parent-forbidden');
+  } else if (tracking.entry.kind !== 'parent-ticket' || tracking.entry.ref !== `${base}parent-ticket.md`) throw new Error('tracking-parent-required');
+  const entry = readTracking(root, tracking.entry.ref);
+  if (tracking.entry.kind === 'parent-ticket' && !entry.includes(tracking.checkpoint_ref)) throw new Error('tracking-parent-checkpoint-link-required');
+  const registry = parseYaml(readTracking(root, 'docs/process/lifecycle-registry.yaml'));
+  const stages = new Set(registry.stages.map(x => x.id));
+  const units = new Set(registry.work_units.map(x => x.id));
+  if (!stages.has(tracking.entry_stage)) throw new Error('tracking-entry-stage-invalid');
+  const profile = trackingProfile(root);
+  const allowed = profile?.lifecycle?.allowed_work_units ?? profile?.allowed_work_units;
+  const index = new Map();
+  for (const item of tracking.items) {
+    if (index.has(item.id)) throw new Error(`tracking-duplicate-id: ${item.id}`);
+    index.set(item.id, item);
+    if (!stages.has(item.stage) || !units.has(item.work_unit) || STAGE_WORK_UNITS[item.work_unit] !== item.stage) throw new Error(`tracking-stage-work-unit-mismatch: ${item.id}`);
+    if (allowed && !allowed.includes(item.work_unit)) throw new Error(`tracking-profile-work-unit-forbidden: ${item.id}`);
+    if (item.split_reasons.length && !item.definition_ref) throw new Error(`tracking-independent-item-required: ${item.id}`);
+    if (item.definition_ref) {
+      if (item.definition_ref !== `${base}work-items/${item.id}.md`) throw new Error('tracking-definition-path-invalid');
+      const definition = readTracking(root, item.definition_ref);
+      if (!definition.includes(`kind: stage-work-item`) || !definition.includes(`id: ${item.id}\n`) || !definition.includes(tracking.checkpoint_ref) || /ready-for-agent|^Status:|^progress:/m.test(definition)) throw new Error('tracking-definition-invalid');
+      if (item.definition_digest !== sha256(definition)) throw new Error('tracking-definition-drift');
+    }
+    if (item.deferred) {
+      if (!item.split_reasons.includes('cross-stage-deferral') || !item.definition_ref) throw new Error('tracking-deferral-independent-item-required');
+      if (item.progress === 'completed' || item.progress === 'cancelled') throw new Error('tracking-deferred-not-completed');
+      if (!Number.isFinite(Date.parse(item.deferred.resolve_by)) || Date.parse(item.deferred.resolve_by) <= now.getTime()) throw new Error('tracking-deferral-expired');
+      readTracking(root, item.deferred.decision_ref);
+    }
+    if (item.progress === 'cancelled' && !item.cancellation_reason) throw new Error('tracking-cancellation-reason-required');
+    if (item.progress === 'completed') {
+      if (!item.source_refs.length) throw new Error('tracking-completion-source-required');
+      if (item.recheck_required) throw new Error('tracking-recheck-required');
+      for (const criterion of item.acceptance) if (!item.completion.some(c => c.criterion === criterion && c.evidence_refs.length)) throw new Error(`tracking-acceptance-evidence-required: ${item.id}`);
+      for (const c of item.completion) if (!item.acceptance.includes(c.criterion)) throw new Error('tracking-unknown-acceptance-criterion');
+    }
+  }
+  const visited = new Set(), visiting = new Set();
+  function visit(id) {
+    if (visiting.has(id)) throw new Error('tracking-dependency-cycle');
+    if (visited.has(id)) return;
+    const item = index.get(id);
+    if (!item) throw new Error(`tracking-dependency-missing: ${id}`);
+    visiting.add(id); item.dependencies.forEach(visit); visiting.delete(id); visited.add(id);
+  }
+  index.forEach((_, id) => visit(id));
+  for (const item of tracking.items) {
+    if ((item.owner !== tracking.items[0].owner || tracking.items.some(other => other.dependencies.includes(item.id))) && !item.definition_ref) throw new Error(`tracking-independent-item-required: ${item.id}`);
+
+    if (['running', 'completed'].includes(item.progress) && item.dependencies.some(id => index.get(id).progress !== 'completed')) throw new Error(`tracking-dependency-blocked: ${item.id}`);
+  }
+  const stale = trackingDrift(root, tracking);
+  if (stale.some(id => ['running', 'completed'].includes(index.get(id).progress))) throw new Error(`tracking-stale-completion: ${stale.join(',')}`);
+  if (entering && STAGE_WORK_UNITS[nextWorkUnit] && !tracking.items.some(i => i.work_unit === nextWorkUnit)) throw new Error('tracking-entry-work-item-required');
+  if (transition && STAGE_WORK_UNITS[currentWorkUnit]) {
+    const items = tracking.items.filter(i => i.work_unit === currentWorkUnit);
+    if (!items.length) throw new Error('tracking-current-work-item-required');
+    if (items.some(i => !['completed', 'cancelled'].includes(i.progress) && !i.deferred)) throw new Error('tracking-current-work-incomplete');
+    if (STAGE_WORK_UNITS[currentWorkUnit] !== STAGE_WORK_UNITS[nextWorkUnit] && tracking.items.some(i => i.stage === STAGE_WORK_UNITS[currentWorkUnit] && !['completed', 'cancelled'].includes(i.progress) && !i.deferred)) throw new Error('tracking-stage-incomplete');
+  }
+  return { status: 'valid', stale_item_ids: stale };
+}
+export function assertTrackingTransition(currentWorkUnit, nextWorkUnit, state, { root } = {}) {
+  // Persisted checkpoint is authoritative. Inline WER status cannot replace it.
+  if (!STAGE_WORK_UNITS[currentWorkUnit] && !STAGE_WORK_UNITS[nextWorkUnit] && !state?.stage_tracking && !state?.checkpoint_ref) return { status: 'not-applicable', stale_item_ids: [] };
+  const repository = parseYaml(readTracking(root, 'yss-project.yaml'));
+  if (repository.repository_mode === 'template-source' && !state?.stage_tracking) return { status: 'not-applicable', stale_item_ids: [] };
+  if (!state?.checkpoint_ref) {
+    const identity = parseYaml(readTracking(root, 'yss-project.yaml'));
+    if (state?.stage_tracking || (identity.repository_mode === 'project-instance' && trackerConfig(root).lifecycle_tracking_version === 1 && (STAGE_WORK_UNITS[currentWorkUnit] || STAGE_WORK_UNITS[nextWorkUnit]))) throw new Error('tracking-persisted-checkpoint-ref-required');
+    return assertStageTracking(state, { root, currentWorkUnit, nextWorkUnit, transition: true });
+  }
+  const checkpoint = parseYaml(readTracking(root, state.checkpoint_ref));
+  if (state.feature_id && checkpoint.feature_id !== state.feature_id) throw new Error('tracking-feature-mismatch');
+  return assertStageTracking(checkpoint, { root, checkpointRef: state.checkpoint_ref, currentWorkUnit, nextWorkUnit, transition: true });
+}
+
+export function assertTrackingEntry(workUnit, state, { root } = {}) {
+  if (!STAGE_WORK_UNITS[workUnit]) return;
+  const repository = parseYaml(readTracking(root, 'yss-project.yaml'));
+  if (repository.repository_mode === 'template-source') return;
+  const enabled = trackerConfig(root).lifecycle_tracking_version === 1;
+  if (!state?.checkpoint_ref) {
+    if (enabled) throw new Error('tracking-entry-checkpoint-required');
+    return;
+  }
+  const checkpoint = parseYaml(readTracking(root, state.checkpoint_ref));
+  assertStageTracking(checkpoint, { root, checkpointRef: state.checkpoint_ref, nextWorkUnit: workUnit, entering: true });
+  const items = checkpoint.stage_tracking?.items.filter(i => i.work_unit === workUnit) || [];
+  const stale = new Set(checkpoint.stage_tracking ? trackingDrift(root, checkpoint.stage_tracking) : []);
+  if (items.length && !items.some(i => !['blocked', 'cancelled'].includes(i.progress) && !i.deferred && !i.recheck_required && !stale.has(i.id) && i.dependencies.every(id => checkpoint.stage_tracking.items.find(d => d.id === id)?.progress === 'completed'))) throw new Error('tracking-entry-no-runnable-work');
+}

package/template/scripts/lib/strategic-handoff-consumption.mjs

@@ -1,5 +1,5 @@
 import { uiBaselineSourceKeys, uiBaselineKind } from './ui-baseline.mjs';
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, inValidationPhase, acceptValidationDependencies } from './validation-phase.mjs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { openBundle } from './strategic-handoff.mjs';
@@ -29,8 +29,9 @@ export async function verifyConsumption(data,{root=process.cwd(),sliceRef,consum
     const route=receipt.routes.find(item=>item.capability===capability);
     ensure(route&&route.activation!=='not-applicable'&&binding.route_id===route.route_id,`${capability} 未绑定当前 Handoff v4/v5 route_id`);
   }
-  const result=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,binding.context_reconciliation_ref)],{encoding:'utf8'});
+  const result=spawnSync(process.execPath,[path.join(ROOT,'scripts/verify-context-reconciliation'),'--root',root,safe(root,binding.context_reconciliation_ref),...(inValidationPhase()?['--validation-dependencies']:[])],{encoding:'utf8',timeout:60000,maxBuffer:16*1024*1024});
   ensure(result.status===0,`目标术语对账未通过: ${result.error?.message || result.stderr}`);
+  if(inValidationPhase()){let value;try{value=JSON.parse(result.stdout);}catch{throw new TypeError('VALIDATION_RECEIPT_INVALID: Context 子进程未返回依赖');}acceptValidationDependencies(value.validation_dependencies);}
   const context=parseContextContract({root});
   const parent=safe(root,`docs/handoffs/${receipt.bundle_id}`);
   const versions=readdirSync(parent).filter(x=>/^v[1-9][0-9]*$/.test(x)&&existsSync(path.join(parent,x,'import-receipt.json'))).sort((a,b)=>Number(b.slice(1))-Number(a.slice(1)));
@@ -84,6 +85,6 @@ export async function verifyConsumption(data,{root=process.cwd(),sliceRef,consum
       }
       const blockedHere=all||(sliceRef?blocked.has(sliceRef):issues.length>0);
       return {result:blockedHere?'blocked':'verified',bundle_digest:current.manifest.bundle_digest,consumed_bundle_digest:receipt.bundle_digest,...(consumer==='frontend'?{frontend_acceptance_digest:digest(data)}:{tactical_digest:digest(data), ...(data.schema_version === 2 ? {technical_design_digest:digest(data)} : {})}),scope:sliceRef||`whole-${consumer}-design`,coverage_complete:[...known.keys()].every(id=>rows.has(id)),block_all:all,blocked_slice_refs:[...blocked].sort(),issues};
-    },{readOnly});
-  },{readOnly});
+    },{readOnly:readOnly||inValidationPhase()});
+  },{readOnly:readOnly||inValidationPhase()});
 }

package/template/scripts/lib/strategic-handoff-io.mjs

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readdirSync, readFileSync, mkdirSync, writeFileSync, realpathSync } from 'node:fs';
+import { mkdirSync, writeFileSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, readFileSync, validationMemo } from './validation-phase.mjs';
 import path from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { spawnSync } from 'node:child_process';
@@ -9,6 +10,7 @@ import { parseDocument } from '../vendor/yaml.mjs';
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 // A v5 package keeps the source glossary as a snapshot, never a nested CONTEXT.md.
 // Only this fixed alias is supported, isolated to the current asynchronous reader.
+const parseCache=Symbol('handoff-yaml');
 const sourceContextSnapshots = new AsyncLocalStorage();
 export function withSourceContextSnapshot(root, action) {
   const roots = new Set(sourceContextSnapshots.getStore() || []);
@@ -20,7 +22,8 @@ export const canonical = value => Array.isArray(value) ? value.map(canonical) :
 export const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 export const digest = value => hash(JSON.stringify(canonical(value)));
 export const json = value => `${JSON.stringify(canonical(value), null, 2)}\n`;
-export function parse(bytes) {
+export function parse(bytes) {return validationMemo(parseCache,String(bytes),()=>parseFresh(bytes));}
+function parseFresh(bytes) {
   const doc = parseDocument(String(bytes), { uniqueKeys: true, maxAliasCount: 0 });
   ensure(!doc.errors.length, `YAML/JSON 无效: ${doc.errors[0]?.message}`);
   return doc.toJS({ maxAliasCount: 0 });

package/template/scripts/lib/strategic-handoff-routing.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from './validation-phase.mjs';
+import path from 'node:path';
+import { read, safe, ensure } from './strategic-handoff-io.mjs';
+
+// Wire work-unit IDs belong to the immutable source package. Only target routing is adapted.
+export function consumerEntry(root, capability, sourceWorkUnit) {
+  const scope = existsSync(path.join(root, '.yss-execution-scope.yaml')) ? read(safe(root, '.yss-execution-scope.yaml')) : null;
+  const profile = existsSync(path.join(root, 'docs/process/harness-profile.yaml')) ? read(safe(root, 'docs/process/harness-profile.yaml')) : null;
+  const contractRef = scope || !profile ? '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml' : '.agents/skills/harness-orchestrator/references/orchestration-contract.yaml';
+  const contract = read(safe(root, contractRef));
+  const target = scope?.scope_id || profile?.profile_id || 'yss-full-lifecycle';
+  const policy = contract.consumer_entry_routes?.[target]?.[capability];
+  ensure(policy && policy.source_work_unit === sourceWorkUnit, `consumer-entry-unmapped: ${target}/${capability}/${sourceWorkUnit}`);
+  const registry = read(safe(root, 'docs/process/lifecycle-registry.yaml'));
+  ensure(registry.work_units.some(unit => unit.id === policy.target_work_unit), 'consumer-entry-unknown-target');
+  if (scope) {
+    ensure(scope.schema_version === 1, 'consumer-entry-invalid-scope');
+    ensure(contract.execution_scopes?.[scope.scope_id]?.allowed_work_units?.includes(policy.target_work_unit), 'consumer-entry-outside-scope');
+  }
+  if (profile) ensure(profile.lifecycle.allowed_work_units.includes(policy.target_work_unit), 'consumer-entry-outside-profile');
+  return { capability, source_work_unit: sourceWorkUnit, target_work_unit: policy.target_work_unit, target_profile: target };
+}
+
+export function scopedConsumerCapabilities(root, fallback) {
+  if (!existsSync(path.join(root, '.yss-execution-scope.yaml'))) return fallback;
+  const scope = read(safe(root, '.yss-execution-scope.yaml'));
+  const contract = read(safe(root, '.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml'));
+  const capabilities = contract.execution_scopes?.[scope.scope_id]?.consumer_capabilities;
+  ensure(scope.schema_version === 1 && Array.isArray(capabilities) && capabilities.length, 'consumer-scope-capabilities-missing');
+  return capabilities;
+}

package/template/scripts/lib/strategic-handoff.mjs

@@ -1,4 +1,6 @@
-import { existsSync, lstatSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
+import { scopedConsumerCapabilities } from './strategic-handoff-routing.mjs';
+import { existsSync, lstatSync, readFileSync } from './validation-phase.mjs';
+import { mkdirSync, mkdtempSync, renameSync, rmSync, cpSync } from 'node:fs';
 import path from 'node:path';
 import { tmpdir } from 'node:os';
 import { ensure, canonical, digest, hash, json, parse, read, safe, relative, files, write, project, schema, schemaBatch, archive, ROOT, sourceApprovalPolicy, withSourceContextSnapshot } from './strategic-handoff-io.mjs';
@@ -432,7 +434,7 @@ export async function importBundle({bundle,targetRoot}) {
       }else{
         const profileRef=path.join(target,'docs/process/harness-profile.yaml');
         const profile=existsSync(profileRef)?read(profileRef):null;
-        const capabilities=profile?.handoff?.consumer_capabilities||CAPABILITIES;
+        const capabilities=scopedConsumerCapabilities(target,profile?.handoff?.consumer_capabilities||CAPABILITIES);
         ensure(Array.isArray(capabilities)&&capabilities.length&&capabilities.every(capability=>CAPABILITIES.includes(capability)),'目标 profile 未声明受支持的消费者能力');
         const selected=b.handoff.consumer_routes.filter(route=>capabilities.includes(route.capability));
         ensure(selected.length===capabilities.length,'目标 profile 的消费者能力在 Handoff v4 中缺失');

package/template/scripts/lib/task-package.mjs

@@ -1,3 +1,4 @@
+import { assertTrackingEntry } from './stage-tracking.mjs';
 import { normalizeSliceContract } from './slice-contract.mjs';
 import { assertSliceV3TaskPackage } from './slice-task-package.mjs';
 export { compileSliceTaskPackage, assertSliceV3TaskPackage } from './slice-task-package.mjs';
@@ -68,6 +69,7 @@ function validateSkillSource(value, registry) {
 }
 
 function validateCommon(value, registry, lifecycle) {
+  if (value.allowed_write_paths?.length && value.contract.kind === "lifecycle-work-unit") assertTrackingEntry(value.work_unit_id, value, { root: ROOT });
   if (value.work_unit_id === 'work-unit.spec-synthesis') assertPlanSpecEntry(value);
   const workUnit = lifecycle.work_units.find((item) => item.id === value.work_unit_id);
   if (!workUnit && value.contract.kind !== "slice-implementation") fail(`未知 work_unit_id: ${value.work_unit_id}`);

package/template/scripts/lib/technical-design-boundary.mjs

@@ -1,6 +1,6 @@
 import { assertApprovedExecutionContext, approvedExecutionBinding } from './approved-execution-context.mjs';
 import path from 'node:path';
-import { readFileSync } from 'node:fs';
+import { readFileSync, inValidationPhase, acceptValidationDependencies } from './validation-phase.mjs';
 import { spawnSync } from 'node:child_process';
 import { ROOT, read, safe, ensure, hash } from './strategic-handoff-io.mjs';
 
@@ -22,11 +22,13 @@ export function enforceTechnicalDesign(state = {}, { root = ROOT, execution, rea
   if (binding.legacy_ddd === true) args.push('--legacy-ddd');
   if(readOnly)args.push('--read-only');
   if(execution){
-    assertApprovedExecutionContext(execution,{root,technicalDesign:data,architectureIdentity:state.architecture_identity,sliceId:state.slice_id});
+    assertApprovedExecutionContext(execution,{root,technicalDesign:data,architectureIdentity:state.architecture_identity,sliceId:state.slice_id,readOnly});
     const approved=approvedExecutionBinding(execution);
     if(approved.work_unit_id)args.push('--work-unit',approved.work_unit_id);
     args.push('--approved-slice',approved.ref,'--approved-slice-digest',approved.digest,'--approved-slice-approval',approved.approval_ref);
   }
+  if(inValidationPhase())args.push('--validation-dependencies');
   const verified = spawnSync(process.execPath, args, { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 2 * 1024 * 1024 });
   ensure(verified.status === 0, `技术设计不可消费: ${verified.error?.message || verified.stderr}`);
+  if(inValidationPhase()){let output;try{output=JSON.parse(verified.stdout);}catch{throw new TypeError('VALIDATION_RECEIPT_INVALID: 技术设计子进程未返回依赖');}const dependencies=output.validation_dependencies;const required=[file,...(execution?[path.resolve(root,approvedExecutionBinding(execution).ref),path.resolve(root,approvedExecutionBinding(execution).approval_ref),path.resolve(root,'docs/agents/digital-human-roles.yaml')]:[])];ensure(required.every(ref=>dependencies?.files?.some(row=>row.file===ref)),'VALIDATION_RECEIPT_INVALID: 技术设计依赖报告缺少必要原始资产');acceptValidationDependencies(dependencies);}
 }

package/template/scripts/lib/ui-baseline.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync } from './validation-phase.mjs';
 import { ensure, read, safe, hash } from './strategic-handoff-io.mjs';
 import { validateVisualBaseline } from '../../.agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs';
 import { validateExistingUiBaseline } from './existing-ui-baseline.mjs';

package/template/scripts/lib/user-decision.mjs

@@ -1,6 +1,6 @@
 import { normalizeSliceContract } from './slice-contract.mjs';
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";

package/template/scripts/lib/validation-phase.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {AsyncLocalStorage} from 'node:async_hooks';
+
+// Only a live local call owns these snapshots. Neither receipts nor cache data confer approval.
+const phases=new AsyncLocalStorage();
+const checksum=bytes=>createHash('sha256').update(bytes).digest('hex');
+const filename=value=>path.resolve(value instanceof URL?fileURLToPath(value):value);
+const error=(code,detail)=>Object.assign(new TypeError(`${code}: ${detail}`),{code});
+const current=()=>{const phase=phases.getStore();if(phase&&!phase.active)throw error('VALIDATION_PHASE_EXPIRED','验证阶段已经结束');if(phase?.signal?.aborted)throw error('VALIDATION_CANCELLED','验证阶段已取消');return phase;};
+const statShape=stat=>({type:stat.isSymbolicLink()?'link':stat.isDirectory()?'directory':stat.isFile()?'file':'other',mode:Number(stat.mode),ino:String(stat.ino),dev:String(stat.dev)});
+function observe(file,kind,read){const phase=current();if(!phase)return read();const key=`${kind}\0${file}`;if(!phase.observations.has(key))phase.observations.set(key,{file,kind,value:read()});return phase.observations.get(key).value;}
+function pathIdentity(file){let part=path.parse(file).root;for(const name of path.relative(part,file).split(path.sep).filter(Boolean)){part=path.join(part,name);const nameRef=part;observe(nameRef,'stat',()=>{try{return statShape(fs.lstatSync(nameRef));}catch(e){if(e.code==='ENOENT')return null;throw e;}});}}
+export function readFileSync(file,options){
+ const phase=current();if(!phase||typeof file==='number'||(typeof options==='object'&&options?.flag&&options.flag!=='r'))return fs.readFileSync(file,options);
+ const ref=filename(file);pathIdentity(ref);
+ if(!phase.files.has(ref))phase.files.set(ref,Buffer.from(fs.readFileSync(ref)));
+ const bytes=phase.files.get(ref),encoding=typeof options==='string'?options:options?.encoding;
+ return encoding?bytes.toString(encoding):Buffer.from(bytes);
+}
+export async function readFile(file,options){return readFileSync(file,options);}
+export async function readdir(file,options){return readdirSync(file,options);}
+export function existsSync(file){const phase=current();if(!phase||typeof file==='number')return fs.existsSync(file);const ref=filename(file);pathIdentity(ref);return observe(ref,'exists',()=>fs.existsSync(ref));}
+export function lstatSync(file,options){const result=fs.lstatSync(file,options);const phase=current();if(phase&&result){const ref=filename(file);observe(ref,'stat',()=>statShape(result));}return result;}
+export function readdirSync(file,options){
+ const result=fs.readdirSync(file,options),phase=current();
+ if(phase){const ref=filename(file);pathIdentity(ref);
+  // Record the enumeration actually returned to the consumer, not a second read.
+  const encoding=typeof options==='string'?options:options?.encoding||'utf8';
+  const names=result.map(entry=>{const name=typeof entry==='string'||Buffer.isBuffer(entry)?entry:entry.name;return Buffer.isBuffer(name)?name.toString():Buffer.from(name,encoding==='buffer'?'utf8':encoding).toString();}).sort();
+  const recorded=observe(ref,'directory',()=>names);
+  if(JSON.stringify(recorded)!==JSON.stringify(names))throw error('VALIDATION_INPUT_CHANGED',ref);
+ }
+ return result;
+}
+function actualObservation(row){if(row.kind==='exists')return fs.existsSync(row.file);if(row.kind==='directory')return fs.readdirSync(row.file).sort();if(row.kind==='stat'){try{return statShape(fs.lstatSync(row.file));}catch(e){if(e.code==='ENOENT')return null;throw e;}}throw error('VALIDATION_RECEIPT_INVALID','未知依赖类型');}
+function receipt(phase){return{schema_version:1,files:[...phase.files].map(([file,bytes])=>({file,digest:checksum(bytes)})),observations:[...phase.observations.values()]};}
+function checkReceipt(value){
+ if(value?.schema_version!==1||!Array.isArray(value.files)||!Array.isArray(value.observations))throw error('VALIDATION_RECEIPT_INVALID','缺少受控校验进程的依赖');
+ for(const row of value.files){if(!path.isAbsolute(row.file)||!/^[a-f0-9]{64}$/.test(row.digest))throw error('VALIDATION_RECEIPT_INVALID','非法文件依赖');try{if(checksum(fs.readFileSync(row.file))!==row.digest)throw Error('changed');}catch{throw error('VALIDATION_INPUT_CHANGED',row.file);}}
+ for(const row of value.observations){if(!path.isAbsolute(row.file))throw error('VALIDATION_RECEIPT_INVALID','非法路径依赖');try{if(JSON.stringify(actualObservation(row))!==JSON.stringify(row.value))throw Error('changed');}catch{throw error('VALIDATION_INPUT_CHANGED',row.file);}}
+}
+function mergedReceipt(phase){
+ const files=new Map(),observations=new Map();
+ for(const part of [receipt(phase),...phase.children]){
+  if(part?.schema_version!==1||!Array.isArray(part.files)||!Array.isArray(part.observations))throw error('VALIDATION_RECEIPT_INVALID','缺少受控校验进程的依赖');
+  for(const row of part.files){if(typeof row.file!=='string'||!path.isAbsolute(row.file)||!/^[a-f0-9]{64}$/.test(row.digest))throw error('VALIDATION_RECEIPT_INVALID','非法文件依赖');if(files.has(row.file)&&files.get(row.file).digest!==row.digest)throw error('VALIDATION_INPUT_CHANGED',row.file);files.set(row.file,row);}
+  for(const row of part.observations){if(typeof row.file!=='string'||!path.isAbsolute(row.file)||!['stat','exists','directory'].includes(row.kind))throw error('VALIDATION_RECEIPT_INVALID','非法路径依赖');const key=`${row.kind}\0${row.file}`;if(observations.has(key)&&JSON.stringify(observations.get(key).value)!==JSON.stringify(row.value))throw error('VALIDATION_INPUT_CHANGED',row.file);observations.set(key,row);}
+ }
+ return{schema_version:1,files:[...files.values()],observations:[...observations.values()]};
+}
+export function acceptValidationDependencies(value){
+ const phase=current();if(!phase)throw error('VALIDATION_PHASE_REQUIRED','子进程依赖必须交回本次验证阶段');
+ // Compare parent/child observations now; verify their union against disk before returning.
+ phase.children.push(structuredClone(value));mergedReceipt(phase);
+}
+export function validationDependencies(){const phase=current();if(!phase)throw error('VALIDATION_PHASE_REQUIRED','没有活动阶段');return structuredClone(mergedReceipt(phase));}
+export function validationCache(namespace,key,...values){const phase=current();if(!phase)return undefined;const cache=phase.memo.get(namespace)||new Map();phase.memo.set(namespace,cache);if(values.length)cache.set(key,structuredClone(values[0]));return structuredClone(cache.get(key));}
+export function validationMemo(namespace,key,compute){const phase=current();if(!phase)return compute();const cache=phase.memo.get(namespace)||new Map();phase.memo.set(namespace,cache);if(!cache.has(key))cache.set(key,structuredClone(compute()));return structuredClone(cache.get(key));}
+export function validationPhaseToken(){return current()?.token;}
+export function inValidationPhase(){return !!current();}
+export function withValidationPhase(binding,action){
+ const parent=current(),identity=JSON.stringify({root:path.resolve(binding.root||process.cwd()),purpose:binding.purpose,unit:binding.work_unit_id||null,slice:binding.slice_id||null,readOnly:binding.readOnly===true});
+ if(binding.signal?.aborted)throw error('VALIDATION_CANCELLED','验证阶段已取消');
+ if(parent?.identity===identity&&(!binding.signal||binding.signal===parent.signal))return action();
+ const phase={identity,token:Object.freeze({}),active:true,files:new Map(),observations:new Map(),memo:new Map(),children:[],signal:binding.signal};
+ const finish=value=>{try{current();const dependencies=mergedReceipt(phase);checkReceipt(dependencies);if(parent){parent.children.push(dependencies);mergedReceipt(parent);}return value;}finally{phase.active=false;}};
+ return phases.run(phase,()=>{try{const value=action();if(value&&typeof value.then==='function')return value.then(finish,error=>{phase.active=false;throw error;});return finish(value);}catch(error){phase.active=false;throw error;}});
+}
+export default {...fs,readFileSync,existsSync,lstatSync,readdirSync};