create-yss-spec 3.4.9 → 3.5.0

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

package/template/scripts/stage-tracking

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { parseYaml } from './lib/stage-tracking.mjs';
+import { checkTracking, planTracking, applyTracking } from './lib/stage-tracking-migration.mjs';
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, strict: true, options: { root: { type: 'string' }, checkpoint: { type: 'string' }, items: { type: 'string' }, plan: { type: 'string' }, refresh: { type: 'boolean', default: false } } });
+  const root = path.resolve(values.root || path.resolve(import.meta.dirname, '..'));
+  const command = positionals[0];
+  if (positionals.length !== 1 || !['check', 'plan', 'apply'].includes(command)) throw new Error('用法: stage-tracking check|plan --root <项目> --checkpoint <相对路径> [--items <yaml>] [--refresh]；apply --root <项目> --plan <json>');
+  let result;
+  if (command === 'apply') {
+    if (!values.plan || values.checkpoint || values.items || values.refresh) throw new Error('apply 只接受 --root 和 --plan');
+    result = applyTracking(root, JSON.parse(readFileSync(values.plan, 'utf8')));
+  } else {
+    if (!values.checkpoint || values.plan) throw new Error('check/plan 需要 --checkpoint');
+    if (command === 'check' && (values.items || values.refresh)) throw new Error('check 不接受写入意图参数');
+    const input = values.items ? parseYaml(readFileSync(values.items, 'utf8')) : [];
+    if (!Array.isArray(input)) throw new Error('--items 必须是工作项数组');
+    result = command === 'check' ? checkTracking(root, values.checkpoint) : planTracking(root, { checkpoint_ref: values.checkpoint, items: input, refresh: values.refresh });
+    if (result.status === 'blocked' || (result.status === 'missing-checkpoint' && result.enabled)) process.exitCode = 1;
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }

package/template/scripts/strategic-consumer-entry

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { openBundle, openDelivery, importBundle } from './lib/strategic-handoff.mjs';
+import { read, safe, ensure, hash, schema, project } from './lib/strategic-handoff-io.mjs';
+import { consumerEntry } from './lib/strategic-handoff-routing.mjs';
+
+try {
+  const { values } = parseArgs({ options: { root: { type: 'string' }, receipt: { type: 'string' }, bundle: { type: 'string' } } });
+  const root = project(values.root);
+  ensure(Boolean(values.receipt) !== Boolean(values.bundle), 'provide-receipt-or-bundle');
+  const inspect = b => {
+    ensure(b.handoff.schema_version === 5, 'design-entry-requires-handoff-v5');
+    const route = b.handoff.consumer_routes.find(item => item.capability === 'backend-technical-design');
+    ensure(route && route.activation !== 'not-applicable', 'backend-consumer-route-not-active');
+    return { ...consumerEntry(root, route.capability, route.entry_work_unit), route_id: route.route_id,
+      bundle_id: b.manifest.bundle_id, version: b.manifest.version, bundle_digest: b.manifest.bundle_digest };
+  };
+  let receiptRef = values.receipt;
+  if (values.bundle) {
+    const input = path.resolve(values.bundle);
+    // Validate the destination route before any import writes.
+    if (existsSync(path.join(input, 'delivery-record.json'))) await openDelivery(input, inspect);
+    else await openBundle(input, inspect);
+    receiptRef = (await importBundle({ bundle: input, targetRoot: root })).receipt_ref;
+  }
+  const receipt = read(safe(root, receiptRef));
+  ensure([2, 3].includes(receipt.schema_version), 'design-entry-receipt-version');
+  schema(receipt, receipt.schema_version === 3 ? 'docs/process/schemas/strategic-handoff-import-receipt-v3.schema.json' : 'docs/process/schemas/strategic-handoff-import-receipt.schema.json');
+  const base = `docs/handoffs/${receipt.bundle_id}/${receipt.version}`;
+  ensure(receiptRef === `${base}/import-receipt.json` && receipt.package_ref === `${base}/package`, 'design-entry-receipt-path');
+  const entry = await openBundle(safe(root, receipt.package_ref), inspect);
+  ensure(entry.bundle_id === receipt.bundle_id && entry.version === receipt.version && entry.bundle_digest === receipt.bundle_digest, 'design-entry-receipt-drift');
+  const route = receipt.routes.find(item => item.capability === entry.capability);
+  ensure(route?.route_id === entry.route_id && route.activation !== 'not-applicable', 'design-entry-receipt-route');
+  if (receipt.schema_version === 3) {
+    ensure(receipt.source_delivery_record_ref === `${base}/source-delivery-record.json`, 'design-entry-delivery-path');
+    const bytes = readFileSync(safe(root, receipt.source_delivery_record_ref));
+    ensure(hash(bytes) === receipt.source_delivery_record_sha256, 'design-entry-delivery-drift');
+    const record = JSON.parse(bytes);
+    ensure(record.bundle_digest === receipt.bundle_digest && record.handoff.id === receipt.bundle_id && record.handoff.version === receipt.version, 'design-entry-delivery-binding');
+  }
+  console.log(JSON.stringify({ result: values.bundle ? 'design-imported' : 'design-inputs-verified', ...entry,
+    import_receipt_ref: receiptRef, next_work_unit: entry.target_work_unit, ready_for_agent: false,
+    stage_verification_required: true, pending: ['target-context-reconciliation', 'engineering-design-and-consumption', 'slice-contract-approval'] }, null, 2));
+} catch (error) { console.error(JSON.stringify({ result: 'blocked', error: error.message, ready_for_agent: false })); process.exitCode = 1; }

package/template/scripts/verify-context-reconciliation

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
+import {withValidationPhase,validationDependencies} from "./lib/validation-phase.mjs";
 import { parseArgs } from "node:util";
 import { verifyContextReconciliation } from "./lib/context-reconciliation.mjs";
 try {
-  const { values, positionals } = parseArgs({ options: { root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
+  const { values, positionals } = parseArgs({ options: { "validation-dependencies": {type:"boolean",default:false}, root: { type: "string", default: process.cwd() } }, allowPositionals: true, strict: true });
   if (positionals.length !== 1) throw new TypeError("用法: scripts/verify-context-reconciliation [--root <repo>] <record.yaml|json>");
-  verifyContextReconciliation(positionals[0], { root: values.root });
-  process.stdout.write("Context reconciliation 验证通过\n");
+  const result=withValidationPhase({root:values.root,purpose:"context-reconciliation",readOnly:true},()=>{verifyContextReconciliation(positionals[0], { root: values.root });return values["validation-dependencies"]?{result:"verified",validation_dependencies:validationDependencies()}:null;});
+  process.stdout.write(result?JSON.stringify(result)+"\n":"Context reconciliation 验证通过\n");
 } catch (error) {
   process.stderr.write(`Context reconciliation 验证失败: ${error.message}\n`);
   process.exitCode = 1;

package/template/scripts/verify-lifecycle-checkpoint

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { assertStageTracking } from './lib/stage-tracking.mjs';
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
@@ -6,6 +7,7 @@ import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { assertCheckpointApprovals, assertCheckpointUserDecisions } from "./lib/approval-record.mjs";
+import { loadExecutionScope, assertScopeWorkUnit, verifyDeliveryTerminal } from './lib/lifecycle-execution-scope.mjs';
 import { assertPlanCheckpoint } from "./lib/plan-spec-entry.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -32,6 +34,14 @@ try {
   const value = document.toJS({ maxAliasCount: 0 });
   const result = spawnSync("python3", ["-c", validator, schemaPath], { cwd: root, encoding: "utf8", input: JSON.stringify(value) });
   if (result.status !== 0) throw new TypeError(`${result.stdout}${result.stderr}`.trim());
+  if(loadExecutionScope(root)) {
+    if(value.status==='completed') {
+      if(value.next_work_unit!==null)throw new TypeError('后端终点不得继续其他工作单元');
+      verifyDeliveryTerminal(root);
+    } else if(value.next_work_unit) assertScopeWorkUnit(value.next_work_unit,{root,readOnly:value.mode==='audit'||value.mode==='route'});
+    else if(value.mode==='resume'||value.mode==='orchestrate') assertScopeWorkUnit('work-unit.entry-triage',{root});
+  }
+  assertStageTracking(value, { root, checkpointRef: path.relative(root, sourcePath), nextWorkUnit: value.next_work_unit, entering: value.mode === 'resume' || value.mode === 'orchestrate' });
   assertCheckpointApprovals(value, sourcePath);
   assertPlanCheckpoint(value);
   assertCheckpointUserDecisions(value);

package/template/scripts/verify-project-instance

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDocument } from "./vendor/yaml.mjs";
 import { loadRegistry, validateRegistry } from "./lib/lifecycle-registry.mjs";
+import { syncSkills, updateSkillLock } from "./lib/skill-supply-chain.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const identityPath = path.join(root, "yss-project.yaml");
@@ -16,18 +17,18 @@ if (identity?.schema_version !== 1 || identity?.repository_mode !== "project-ins
   throw new TypeError("verify-project-instance 仅适用于合法 project-instance");
 }
 
-const commands = [
-  ["scripts/sync-skills", ["--check"]],
-  ["scripts/update-skill-lock", ["--check"]],
-  ["scripts/verify-context-contract", ["--root", ".", "--json"]],
-];
-for (const [command, args] of commands) {
+const commands = ["scripts/sync-skills", "scripts/update-skill-lock", "scripts/verify-context-contract"];
+for (const command of commands) {
   const executable = path.join(root, command);
   if (!existsSync(executable)) throw new TypeError(`缺少项目实例校验入口: ${command}`);
-  const result = spawnSync(executable, args, { cwd: root, encoding: "utf8" });
-  if (result.status !== 0) {
-    throw new TypeError(result.stderr.trim() || result.stdout.trim() || `${command} 校验失败`);
-  }
+}
+const hashCache = new Map();
+syncSkills({ check: true, hashCache });
+updateSkillLock(["--check"], { hashCache });
+const command = "scripts/verify-context-contract";
+const result = spawnSync(path.join(root, command), ["--root", ".", "--json"], { cwd: root, encoding: "utf8" });
+if (result.status !== 0) {
+  throw new TypeError(result.stderr.trim() || result.stdout.trim() || `${command} 校验失败`);
 }
 validateRegistry(loadRegistry());
 process.stdout.write("项目实例校验通过\n");