@thebackstoryis/engineering-with-ai 0.2.9

package/src/context.mjs

@@ -0,0 +1,210 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  writeFileSync
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import YAML from 'yaml';
+import { projectPaths } from './paths.mjs';
+
+const classifications = new Set(['public', 'internal', 'confidential', 'restricted']);
+const cloudPolicies = new Set(['allowed', 'denied', 'unknown']);
+const ignoredDirectories = new Set([
+  '.git', '.ewai-pipeline', '.idea', '.vscode', 'node_modules', 'vendor', 'dist', 'build'
+]);
+const supportedExtensions = new Set([
+  '.csv', '.doc', '.docx', '.eml', '.htm', '.html', '.ics', '.json', '.log', '.markdown',
+  '.mbox', '.md', '.msg', '.odt', '.ods', '.pdf', '.ppt', '.pptx', '.rtf', '.text', '.tsv',
+  '.txt', '.xls', '.xlsx', '.xml', '.yaml', '.yml',
+  '.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp',
+  '.m4a', '.mp3', '.mp4', '.wav', '.webm'
+]);
+
+function normalized(path) {
+  return path.split(sep).join('/');
+}
+
+function slugify(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'project-context';
+}
+
+function dateStamp(value) {
+  return new Date(value).toISOString().slice(0, 10);
+}
+
+function inside(parent, child) {
+  const path = relative(parent, child);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+}
+
+function scanSource(root, exclusions, maxFiles) {
+  const files = [];
+  const skipped = { symlinks: 0, unsupported: 0, excluded: 0 };
+
+  function walk(directory) {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = resolve(directory, entry.name);
+      const sourceRelative = normalized(relative(root, path));
+      if (exclusions.some((excluded) => sourceRelative === excluded || sourceRelative.startsWith(`${excluded}/`))) {
+        skipped.excluded += 1;
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        skipped.symlinks += 1;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!ignoredDirectories.has(entry.name)) walk(path);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const extension = extname(entry.name).toLowerCase();
+      if (!supportedExtensions.has(extension)) {
+        skipped.unsupported += 1;
+        continue;
+      }
+      if (files.length >= maxFiles) throw new Error(`Context folder exceeds the ${maxFiles} file registration limit; narrow the folder or add exclusions`);
+      const stats = statSync(path);
+      files.push({
+        relativePath: sourceRelative,
+        extension,
+        size: stats.size,
+        modifiedAt: stats.mtime.toISOString()
+      });
+    }
+  }
+
+  walk(root);
+  return { files, skipped };
+}
+
+function inventorySummary(files) {
+  const extensions = {};
+  let totalBytes = 0;
+  for (const file of files) {
+    totalBytes += file.size;
+    extensions[file.extension] = (extensions[file.extension] ?? 0) + 1;
+  }
+  return { fileCount: files.length, totalBytes, extensions };
+}
+
+function readRegistry(path) {
+  if (!existsSync(path)) return { schema: 'ewai.context-source-registry/v1', sources: [] };
+  const registry = YAML.parse(readFileSync(path, 'utf8')) ?? {};
+  registry.schema ??= 'ewai.context-source-registry/v1';
+  registry.sources ??= [];
+  return registry;
+}
+
+export function registerContextSource(projectRoot, sourcePath, options = {}) {
+  if (!options.confirmed) throw new Error('Context registration requires explicit user confirmation');
+  const paths = projectPaths(projectRoot);
+  if (!existsSync(paths.configPath)) throw new Error('Initialize EWAI before registering project context');
+
+  const candidate = resolve(sourcePath);
+  if (!existsSync(candidate) || !lstatSync(candidate).isDirectory()) {
+    throw new Error(`Context source is not a readable folder: ${candidate}`);
+  }
+  const sourceRoot = realpathSync(candidate);
+  const project = realpathSync(paths.projectRoot);
+  if (sourceRoot === project) throw new Error('Choose a dedicated context folder rather than the entire project');
+  if (inside(sourceRoot, project)) throw new Error('Choose a context folder that does not contain the project itself');
+
+  const classification = options.classification ?? 'confidential';
+  if (!classifications.has(classification)) throw new Error(`Unsupported context classification: ${classification}`);
+  const cloudProcessing = options.cloudProcessing ?? 'unknown';
+  if (!cloudPolicies.has(cloudProcessing)) throw new Error(`Unsupported cloud-processing policy: ${cloudProcessing}`);
+
+  const label = String(options.label || basename(sourceRoot)).trim();
+  const slug = slugify(label);
+  const exclusions = (options.exclusions ?? [])
+    .map((item) => normalized(String(item).replace(/^\.\//, '').replace(/\/$/, '')))
+    .filter(Boolean);
+  const registeredAt = new Date(options.now ?? Date.now()).toISOString();
+  const scanned = scanSource(sourceRoot, exclusions, options.maxFiles ?? 10_000);
+  const inventory = inventorySummary(scanned.files);
+  const sourceHash = createHash('sha256').update(`${project}\0${sourceRoot}`).digest('hex').slice(0, 12);
+  const sourceId = `context.${slug}.${sourceHash}`;
+  const inventoryFingerprint = createHash('sha256').update(JSON.stringify(scanned.files)).digest('hex');
+
+  const privateRoot = resolve(paths.runtimeRoot, 'context/sources');
+  const privateManifest = resolve(privateRoot, `${sourceId}.json`);
+  if (existsSync(privateManifest) && !options.force) {
+    throw new Error(`Context source is already registered: ${sourceId}`);
+  }
+  mkdirSync(privateRoot, { recursive: true });
+  writeFileSync(privateManifest, `${JSON.stringify({
+    schema: 'ewai.context-source-private/v1',
+    sourceId,
+    label,
+    sourceRoot,
+    classification,
+    cloudProcessing,
+    exclusions,
+    registeredAt,
+    inventoryFingerprint,
+    files: scanned.files,
+    skipped: scanned.skipped
+  }, null, 2)}\n`, 'utf8');
+
+  const registryPath = resolve(paths.specsRoot, '1.Scope/research/context-sources.yaml');
+  const registry = readRegistry(registryPath);
+  const publicEntry = {
+    id: sourceId,
+    label,
+    classification,
+    cloud_processing: cloudProcessing,
+    status: 'registered',
+    registered_at: registeredAt,
+    inventory: {
+      file_count: inventory.fileCount,
+      total_bytes: inventory.totalBytes,
+      extensions: inventory.extensions
+    },
+    inventory_fingerprint: inventoryFingerprint,
+    review_status: 'pending'
+  };
+  registry.sources = registry.sources.filter((source) => source.id !== sourceId);
+  registry.sources.push(publicEntry);
+  mkdirSync(resolve(paths.specsRoot, '1.Scope/research'), { recursive: true });
+  writeFileSync(registryPath, YAML.stringify(registry, { lineWidth: 0 }), 'utf8');
+
+  const bundleRoot = resolve(
+    paths.specsRoot,
+    '3.Evidence/context-imports',
+    `${dateStamp(registeredAt)}-${slug}-${sourceHash}`
+  );
+  mkdirSync(bundleRoot, { recursive: true });
+  const registrationPath = resolve(bundleRoot, 'source-registration.yaml');
+  writeFileSync(registrationPath, YAML.stringify({
+    schema: 'ewai.context-source-registration/v1',
+    ...publicEntry,
+    private_manifest: `.ewai-pipeline/context/sources/${sourceId}.json`,
+    analysis_status: 'pending'
+  }, { lineWidth: 0 }), 'utf8');
+
+  return {
+    schema: 'ewai.context-register-result/v1',
+    projectRoot: paths.projectRoot,
+    sourceId,
+    label,
+    classification,
+    cloudProcessing,
+    inventory,
+    skipped: scanned.skipped,
+    privateManifest,
+    registryPath,
+    bundleRoot,
+    registrationPath
+  };
+}

package/src/dashboard-preferences.mjs

@@ -0,0 +1,80 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync} from 'node:fs';
+import {dirname,relative,resolve,isAbsolute} from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import YAML from 'yaml';
+import {projectPaths} from './paths.mjs';
+
+export const DASHBOARD_VIEWS=Object.freeze([
+  ['portfolio','Portfolio','Compare work and decisions across several projects.','Across projects and teams'],
+  ['team-hub','Team Hub','Share approved resources and project summaries with your team.','Across projects and teams'],
+  ['rollout','Governed Rollout','Coordinate adoption across organisations or multiple projects.','Across projects and teams'],
+  ['starters','Starters','Inspect and deliberately apply approved starting material.','Project tools'],
+  ['policies','Policy Gates','Inspect organisation policy requirements and their evidence.','Project tools'],
+  ['security','Security Validation','Review configured security checks, findings and decisions.','Project tools'],
+  ['hooks','Hooks','Inspect explicitly configured lifecycle integrations and failures.','Project tools'],
+  ['context-inspector','AI context diagnostics','See which evidence and personas EWAI selects for an AI task.','Deeper analysis'],
+  ['phase-studio','Contributions','Add attributed business or technical evidence to an active delivery.','Deeper analysis'],
+].map(([id,title,description,group])=>Object.freeze({id,title,description,group})));
+
+function fail(message,statusCode=400){const error=new Error(message);error.statusCode=statusCode;error.dashboardPreferenceError=true;throw error;}
+function record(value){return value!==null&&typeof value==='object'&&!Array.isArray(value);}
+function keys(value,allowed){if(!record(value)||Object.keys(value).some(key=>!allowed.includes(key)))fail('Dashboard preferences contain unsupported fields.');}
+export function normaliseDashboardPreferences(value={}){
+  keys(value,['optional_views','sidebar_collapsed']);
+  const optional=value.optional_views===undefined?{}:value.optional_views;keys(optional,DASHBOARD_VIEWS.map(v=>v.id));
+  if(value.sidebar_collapsed!==undefined&&typeof value.sidebar_collapsed!=='boolean')fail('Sidebar preferences must be true or false.');
+  for(const flag of Object.values(optional))if(typeof flag!=='boolean')fail('Dashboard view preferences must be true or false.');
+  return {sidebar_collapsed:value.sidebar_collapsed??false,optional_views:Object.fromEntries(DASHBOARD_VIEWS.map(v=>[v.id,optional[v.id]??false]))};
+}
+export function premiumPersonasActive(premium){return premium?.access==='available'&&premium?.installed===true&&premium?.verified===true;}
+const digest=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
+function safePath(paths){
+  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
+  if(rel.startsWith('..')||isAbsolute(rel))fail('Dashboard preferences require a safe project configuration path.',403);
+  let cursor=parent;
+  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Dashboard preferences cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Dashboard preferences require a safe project configuration path.',403);cursor=next;}
+  const stat=lstatSync(paths.configPath);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Dashboard preferences require a regular, non-symbolic configuration file.',403);
+  if(stat.size>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
+  return stat;
+}
+function snapshot(paths){
+  const stat=safePath(paths);let fd;
+  try{
+    fd=openSync(paths.configPath,constants.O_RDONLY|constants.O_NOFOLLOW);
+    const opened=fstatSync(fd);if(opened.ino!==stat.ino||opened.dev!==stat.dev)fail('Project configuration changed. Reload the settings and try again.',409);
+    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
+    const document=YAML.parseDocument(bytes.toString('utf8'));
+    if(document.errors.length)fail('The project configuration contains invalid YAML. Fix it before editing dashboard preferences.',422);
+    let config;try{config=document.toJS({maxAliasCount:100});}catch{fail('The project configuration cannot be safely read.',422);}
+    if(config?.schema!=='ewai.project/v1'||config?.specs?.root!==paths.specsRelative)fail('The project configuration and SPECS locator must agree before editing dashboard preferences.',422);
+    return {document,preferences:normaliseDashboardPreferences(config.dashboard),digest:digest(bytes),mode:stat.mode&0o777};
+  }finally{if(fd!==undefined)closeSync(fd);}
+}
+function guarded(operation){try{return operation();}catch(error){if(error.dashboardPreferenceError)throw error;fail('Dashboard preferences could not be read or saved. Check the project configuration and file permissions.',409);}}
+function projection(state){return {schema:'ewai.dashboard-preferences/v1',digest:state.digest,preferences:state.preferences,views:DASHBOARD_VIEWS};}
+export function readDashboardPreferences(projectRoot){return guarded(()=>projection(snapshot(projectPaths(projectRoot))));}
+export function saveDashboardPreferences(projectRoot,input){
+  return guarded(()=>{
+    keys(input,['confirmed','expectedDigest','preferences']);
+    if(input.confirmed!==true)fail('Confirm the dashboard preference changes before saving.');
+    if(!/^sha256:[a-f0-9]{64}$/.test(String(input.expectedDigest??'')))fail('Reload dashboard preferences before saving.');
+    if(!record(input.preferences))fail('Provide the dashboard preferences to save.');
+    const preferences=normaliseDashboardPreferences(input.preferences),paths=projectPaths(projectRoot);
+    safePath(paths);const lock=paths.configPath+'.dashboard-preferences.lock';let lockFd,tempFd,temporary;
+    try{
+      try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Dashboard preferences are being edited. Retry after that save finishes.',409);}
+      const before=snapshot(paths);if(before.digest!==input.expectedDigest)fail('Project configuration changed. Reload the settings and try again.',409);
+      before.document.set('dashboard',preferences);const content=before.document.toString();
+      temporary=paths.configPath+'.dashboard-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
+      writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
+      if(snapshot(paths).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.',409);
+      safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
+      return projection(snapshot(paths));
+    }finally{
+      if(tempFd!==undefined)closeSync(tempFd);
+      if(temporary)unlinkSync(temporary);
+      if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}
+    }
+  });
+}

package/src/delivery-artifacts.mjs

@@ -0,0 +1,204 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import { validateDesignSystemReceipt } from './design-system-application.mjs';
+import { policyGateRequirementsForPhase } from './policy-gate-integration.mjs';
+
+const contractPath = fileURLToPath(new URL('../config/delivery-artifacts.yaml', import.meta.url));
+const contract = YAML.parse(readFileSync(contractPath, 'utf8'));
+
+function taskCompletionPaths(deliveryRoot) {
+  const graphPath = resolve(deliveryRoot, 'task-graph.json');
+  if (!existsSync(graphPath)) return ['task-graph.json'];
+  let graph;
+  try {
+    graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  } catch {
+    return ['task-graph.json (valid JSON required)'];
+  }
+  const tasks = Array.isArray(graph.tasks) ? graph.tasks : [];
+  if (!tasks.length) return ['task-graph.json (at least one task required)'];
+  return tasks.flatMap((task, index) => {
+    const configured = String(task.report_path ?? '').trim();
+    const id = String(task.id ?? '').trim();
+    const report = configured || (id ? `tasks/${id}/report.md` : `task-graph.json (task ${index + 1} requires id or report_path)`);
+    const evidence = String(task.evidence_path ?? '').trim()
+      || (id ? `tasks/${id}/evidence.json` : `task-graph.json (task ${index + 1} requires id or evidence_path)`);
+    return [report, evidence];
+  });
+}
+
+function projectRootForDelivery(deliveryRoot) {
+  let candidate = resolve(deliveryRoot);
+  while (dirname(candidate) !== candidate) {
+    if (existsSync(resolve(candidate, '.ewai-pipeline/project.json'))) return candidate;
+    candidate = dirname(candidate);
+  }
+  return null;
+}
+
+export function requiredPhaseArtefacts(deliveryRoot, phaseId, providers = [], cycles = []) {
+  const definition = contract.phases?.[phaseId];
+  if (!definition) return [];
+  const required = [...(definition.required ?? [])];
+  const projectRoot = projectRootForDelivery(deliveryRoot);
+  if (projectRoot && definition.organisation_policy) {
+    const slug = basename(resolve(deliveryRoot));
+    if (policyGateRequirementsForPhase(projectRoot, slug, phaseId).requirements.length) {
+      required.push(...(definition.organisation_policy.required ?? []));
+    }
+  }
+  if (definition.validation_cycles) {
+    required.push(`${phaseId}/validation-cycles.json`);
+    for (const cycle of cycles) {
+      if (cycle.responsePath) required.push(cycle.responsePath);
+      if (cycle.fixPath) required.push(cycle.fixPath);
+    }
+  }
+  if (definition.task_reports) required.push(...taskCompletionPaths(deliveryRoot));
+  return [...new Set(required)];
+}
+
+export function validatePhaseArtefacts(deliveryRoot, phaseId, providers = [], cycles = []) {
+  const required = requiredPhaseArtefacts(deliveryRoot, phaseId, providers, cycles);
+  const root = resolve(deliveryRoot);
+  const missing = required.filter((path) => {
+    if (!path || path.includes('(')) return true;
+    const absolute = resolve(root, path);
+    const rel = relative(root, absolute);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) return true;
+    return !existsSync(absolute) || !statSync(absolute).isFile();
+  });
+  if (missing.length) {
+    const lines = missing.map((path) => `- ${path}`).join('\n');
+    throw new Error(`Phase ${phaseId} is missing canonical delivery artefacts:\n${lines}`);
+  }
+  if (phaseId === 'ui-design') validatePrototypeManifest(root);
+  return required;
+}
+
+export function validatePrototypeManifest(deliveryRoot) {
+  const root = resolve(deliveryRoot);
+  const manifestPath = resolve(root, 'ui-design-assets/prototypes/manifest.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`UI Design prototype manifest is not valid JSON: ${error.message}`);
+  }
+  const errors = [];
+  const statePath = resolve(root, 'delivery-state.json');
+  let requiredContract = '';
+  if (existsSync(statePath)) {
+    try {
+      requiredContract = JSON.parse(readFileSync(statePath, 'utf8'))?.artefactContracts?.prototype ?? '';
+    } catch {
+      errors.push('delivery-state.json must be valid JSON before validating prototype evidence');
+    }
+  }
+  if (!['ewai.prototype-manifest/v1', 'ewai.prototype-manifest/v2', 'ewai.prototype-manifest/v3'].includes(manifest.schema)) {
+    errors.push('schema must be ewai.prototype-manifest/v1, ewai.prototype-manifest/v2 or ewai.prototype-manifest/v3');
+  }
+  if (['ewai.prototype-manifest/v2', 'ewai.prototype-manifest/v3'].includes(requiredContract) && manifest.schema !== requiredContract) {
+    errors.push(`this delivery requires ${requiredContract}; migrate the prototype manifest and link its governed design evidence`);
+  }
+  if (!['selected', 'approved'].includes(String(manifest.status ?? '').trim().toLowerCase())) {
+    errors.push('status must be selected or approved');
+  }
+  const selected = manifest.selected ?? {};
+  for (const key of ['title', 'path', 'decision']) {
+    if (!String(selected[key] ?? '').trim()) errors.push(`selected.${key} is required`);
+  }
+  const prototypePath = resolve(root, String(selected.path ?? ''));
+  const prototypeRoot = resolve(root, 'ui-design-assets/prototypes');
+  const prototypeRelative = relative(prototypeRoot, prototypePath);
+  if (!selected.path || isAbsolute(String(selected.path)) || !prototypeRelative || prototypeRelative.startsWith('..') || isAbsolute(prototypeRelative)) {
+    errors.push('selected.path must identify a file inside ui-design-assets/prototypes');
+  } else if (!existsSync(prototypePath) || !statSync(prototypePath).isFile()) {
+    errors.push(`selected prototype does not exist: ${selected.path}`);
+  } else if (lstatSync(prototypeRoot).isSymbolicLink() || lstatSync(prototypePath).isSymbolicLink()) {
+    errors.push('selected prototype and prototypes directory may not be a symbolic link');
+  } else if (relative(realpathSync(prototypeRoot), realpathSync(prototypePath)).startsWith('..')) {
+    errors.push('selected prototype may not escape the prototypes directory through a symbolic link');
+  } else if (!['.html', '.htm'].includes(extname(prototypePath).toLowerCase())) {
+    errors.push('selected prototype must be an HTML entry point');
+  }
+  const registration = manifest.registration ?? {};
+  if (registration.kind !== 'prototype') errors.push('registration.kind must be prototype');
+  if (registration.status !== 'active') errors.push('registration.status must be active');
+  if (registration.path !== selected.path) errors.push('registration.path must match selected.path');
+  if (['ewai.prototype-manifest/v2', 'ewai.prototype-manifest/v3'].includes(manifest.schema)) {
+    const application = manifest.designSystem ?? {};
+    let receipt = null;
+    try {
+      receipt = validateDesignSystemReceipt(root, application.receiptPath);
+    } catch (error) {
+      errors.push(error.message);
+    }
+    if (!/^sha256:[a-f0-9]{64}$/.test(String(application.receiptDigest ?? ''))) errors.push('designSystem.receiptDigest must be SHA-256');
+    if (!/^sha256:[a-f0-9]{64}$/.test(String(application.effectiveDigest ?? ''))) errors.push('designSystem.effectiveDigest must be SHA-256');
+    if (receipt) {
+      if (receipt.delivery !== basename(root)) errors.push('design-system receipt delivery must match this delivery');
+      if (application.receiptDigest !== receipt.digest) errors.push('designSystem.receiptDigest must match the receipt');
+      if (application.effectiveDigest !== receipt.designSystem.effectiveDigest) errors.push('designSystem.effectiveDigest must match the receipt');
+    }
+  }
+  if (manifest.schema === 'ewai.prototype-manifest/v3') {
+    const reviews = manifest.reviews ?? {};
+    const reviewRoot = resolve(root, 'ui-design-assets/prototype-iterations');
+    const reviewRecords = {};
+    for (const [key, schema, expectedFolder] of [
+      ['plan', 'ewai.prototype-plan-review/v1', 'plans'],
+      ['finalCycle', 'ewai.prototype-cycle-review/v1', 'cycles'],
+    ]) {
+      const link = reviews[key] ?? {};
+      if (!String(link.path ?? '').trim()) {
+        errors.push(`reviews.${key}.path is required`);
+        continue;
+      }
+      if (!/^sha256:[a-f0-9]{64}$/.test(String(link.digest ?? ''))) errors.push(`reviews.${key}.digest must be SHA-256`);
+      const candidate = resolve(root, String(link.path));
+      const expectedRoot = resolve(reviewRoot, expectedFolder);
+      const rel = relative(expectedRoot, candidate);
+      if (isAbsolute(String(link.path)) || !rel || rel.startsWith('..') || isAbsolute(rel)) {
+        errors.push(`reviews.${key}.path must identify immutable evidence inside ui-design-assets/prototype-iterations/${expectedFolder}`);
+        continue;
+      }
+      if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+        errors.push(`reviews.${key}.path does not exist: ${link.path}`);
+        continue;
+      }
+      if (lstatSync(expectedRoot).isSymbolicLink() || lstatSync(candidate).isSymbolicLink()) {
+        errors.push(`reviews.${key}.path and its evidence directory may not be symbolic links`);
+        continue;
+      }
+      try {
+        const record = JSON.parse(readFileSync(candidate, 'utf8'));
+        reviewRecords[key] = record;
+        if (record.schema !== schema) errors.push(`reviews.${key}.path must contain ${schema}`);
+        if (record.contentDigest !== link.digest) errors.push(`reviews.${key}.digest must match the immutable review record`);
+        if (record.deliverySlug && record.deliverySlug !== basename(root)) errors.push(`reviews.${key} delivery must match this delivery`);
+      } catch (error) {
+        errors.push(`reviews.${key}.path must contain valid review JSON: ${error.message}`);
+      }
+    }
+    const plan = reviewRecords.plan;
+    const cycle = reviewRecords.finalCycle;
+    if (cycle) {
+      if (!Number.isInteger(reviews.finalCycle?.cycleNumber) || reviews.finalCycle.cycleNumber < 1 || reviews.finalCycle.cycleNumber > 3) {
+        errors.push('reviews.finalCycle.cycleNumber must be an integer from 1 to 3');
+      } else if (cycle.cycleNumber !== reviews.finalCycle.cycleNumber) {
+        errors.push('reviews.finalCycle.cycleNumber must match the immutable cycle review');
+      }
+      if (plan && cycle.planReviewDigest !== plan.contentDigest) errors.push('the final cycle must reference the linked reviewed plan');
+      if (cycle.prototype?.entryPath !== selected.path) errors.push('the final reviewed cycle must reference selected.path');
+    }
+  }
+  if (errors.length) throw new Error(`UI Design prototype manifest is incomplete:\n- ${errors.join('\n- ')}`);
+  return manifest;
+}
+
+export function deliveryArtefactContract() {
+  return structuredClone(contract);
+}