@thebackstoryis/engineering-with-ai 0.2.9

package/src/runtime/palace.mjs

@@ -0,0 +1,362 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { listKnowledge, readKnowledgeDocument } from './knowledge.mjs';
+import { openRuntimeDatabase } from './database.mjs';
+import { runtimePaths } from './paths.mjs';
+
+const markdownExtensions = new Set(['.md', '.markdown']);
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function within(root, target) {
+  const path = relative(root, target);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+}
+
+function normalized(path) {
+  return path.replaceAll('\\', '/');
+}
+
+function titleFromPath(path) {
+  return basename(path, extname(path)).replace(/[-_]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+function stripFrontmatter(content) {
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+}
+
+function parseSections(document) {
+  const content = stripFrontmatter(document.content);
+  const lines = content.split(/\r?\n/);
+  const headings = [];
+  let title = titleFromPath(document.path);
+  let hasTitle = false;
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
+    if (!match) continue;
+    const level = match[1].length;
+    const heading = match[2].replace(/\s+#+\s*$/, '').trim();
+    if (level === 1 && !hasTitle) {
+      title = heading;
+      hasTitle = true;
+    }
+    headings.push({ index, line: index + 1, level, heading });
+  }
+
+  if (!markdownExtensions.has(document.extension) || headings.length === 0) {
+    return {
+      title,
+      hasTitle: !markdownExtensions.has(document.extension),
+      sections: [{ heading: title, headingPath: title, line: 1, body: content }]
+    };
+  }
+
+  const sections = [];
+  const stack = [];
+  if (headings[0].index > 0 && lines.slice(0, headings[0].index).join('\n').trim()) {
+    sections.push({ heading: title, headingPath: title, line: 1, body: lines.slice(0, headings[0].index).join('\n') });
+  }
+  for (let position = 0; position < headings.length; position += 1) {
+    const current = headings[position];
+    const end = headings[position + 1]?.index ?? lines.length;
+    stack.length = current.level - 1;
+    stack[current.level - 1] = current.heading;
+    sections.push({
+      heading: current.heading,
+      headingPath: stack.filter(Boolean).join(' / '),
+      line: current.line,
+      body: lines.slice(current.index + 1, end).join('\n').trim()
+    });
+  }
+  return { title, hasTitle, sections };
+}
+
+function lineFor(content, offset) {
+  return content.slice(0, offset).split(/\r?\n/).length;
+}
+
+function resolveLink(projectRoot, sourcePath, rawTarget) {
+  if (!rawTarget || rawTarget.startsWith('#') || /^(?:https?:|mailto:|tel:|data:)/i.test(rawTarget)) return null;
+  const [pathPart, anchor = ''] = rawTarget.replace(/^<|>$/g, '').split('#', 2);
+  if (!pathPart) return null;
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathPart.split('?')[0]);
+  } catch {
+    decoded = pathPart.split('?')[0];
+  }
+  const specsRoot = runtimePaths(projectRoot).specsRoot;
+  const sourceAbsolute = resolve(specsRoot, sourcePath);
+  let absolute;
+  if (decoded.startsWith('SPECS/')) absolute = resolve(specsRoot, decoded.slice('SPECS/'.length));
+  else if (isAbsolute(decoded)) absolute = resolve(decoded);
+  else absolute = resolve(dirname(sourceAbsolute), decoded);
+
+  if (within(specsRoot, absolute)) {
+    return { kind: 'specs', targetPath: normalized(relative(specsRoot, absolute)), anchor, exists: existsSync(absolute) };
+  }
+  if (within(resolve(projectRoot), absolute)) {
+    return { kind: 'project', targetPath: normalized(relative(projectRoot, absolute)), anchor, exists: existsSync(absolute) };
+  }
+  return { kind: 'absolute-local', targetPath: absolute, anchor, exists: existsSync(absolute) };
+}
+
+function parseLinks(projectRoot, document) {
+  if (!markdownExtensions.has(document.extension)) return [];
+  const links = [];
+  const markdownLink = /!?\[[^\]]*]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
+  for (const match of document.content.matchAll(markdownLink)) {
+    const resolved = resolveLink(projectRoot, document.path, match[1]);
+    if (!resolved) continue;
+    links.push({ ...resolved, sourcePath: document.path, rawTarget: match[1], line: lineFor(document.content, match.index) });
+  }
+  const codeReference = /`((?:SPECS|src|app|tests?|public|config|docs)\/[A-Za-z0-9_.@/\-[\]]+(?::\d+)?)`/g;
+  for (const match of document.content.matchAll(codeReference)) {
+    const rawTarget = match[1].replace(/:\d+$/, '');
+    if (links.some((link) => link.rawTarget === rawTarget && link.line === lineFor(document.content, match.index))) continue;
+    const projectTarget = rawTarget.startsWith('SPECS/')
+      ? resolveLink(projectRoot, document.path, rawTarget)
+      : { kind: 'project', targetPath: rawTarget, anchor: '', exists: existsSync(resolve(projectRoot, rawTarget)) };
+    if (!projectTarget) continue;
+    links.push({ ...projectTarget, sourcePath: document.path, rawTarget, line: lineFor(document.content, match.index) });
+  }
+  return links;
+}
+
+function inventory(projectRoot) {
+  const documents = listKnowledge(projectRoot).documents
+    .map((entry) => readKnowledgeDocument(projectRoot, entry.path))
+    .filter(Boolean)
+    .map((document) => ({ ...document, contentHash: hash(document.content) }));
+  const fingerprint = hash(JSON.stringify(documents.map((document) => [document.path, document.contentHash])));
+  return { documents, fingerprint };
+}
+
+function currentFingerprint(database) {
+  return database.prepare("SELECT value FROM runtime_meta WHERE key = 'palace_source_fingerprint'").get()?.value ?? '';
+}
+
+export function refreshPalaceIndex(projectRoot, options = {}) {
+  const source = inventory(projectRoot);
+  const database = openRuntimeDatabase(projectRoot);
+  try {
+    const indexedDocuments = database.prepare('SELECT COUNT(*) AS count FROM palace_documents').get().count;
+    if (!options.force && currentFingerprint(database) === source.fingerprint && indexedDocuments === source.documents.length) {
+      const latest = database.prepare("SELECT * FROM palace_index_runs WHERE status = 'completed' ORDER BY id DESC LIMIT 1").get();
+      return {
+        schema: 'ewai.palace-index/v1',
+        status: 'current',
+        runId: latest?.id ?? null,
+        documents: indexedDocuments,
+        sections: latest?.section_count ?? 0,
+        links: latest?.link_count ?? 0,
+        fingerprint: source.fingerprint
+      };
+    }
+
+    const run = database.prepare(`
+      INSERT INTO palace_index_runs (status, source_fingerprint)
+      VALUES ('running', ?) RETURNING id
+    `).get(source.fingerprint);
+    let sectionCount = 0;
+    let linkCount = 0;
+    database.exec('BEGIN IMMEDIATE');
+    try {
+      database.exec('DELETE FROM palace_sections_fts; DELETE FROM palace_links; DELETE FROM palace_documents;');
+      const insertDocument = database.prepare(`
+        INSERT INTO palace_documents (
+          path, title, extension, content_hash, content_length, source_mtime, has_title, section_count
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      const insertSection = database.prepare(`
+        INSERT INTO palace_sections_fts (path, title, heading, body, heading_path, line)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `);
+      const insertLink = database.prepare(`
+        INSERT INTO palace_links (
+          source_path, target_path, target_anchor, kind, exists_on_disk, line, raw_target
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `);
+      for (const document of source.documents) {
+        const parsed = parseSections(document);
+        const links = parseLinks(projectRoot, document);
+        insertDocument.run(
+          document.path, parsed.title, document.extension, document.contentHash,
+          document.content.length, document.updatedAt, parsed.hasTitle ? 1 : 0, parsed.sections.length
+        );
+        for (const section of parsed.sections) {
+          insertSection.run(document.path, parsed.title, section.heading, section.body, section.headingPath, section.line);
+          sectionCount += 1;
+        }
+        for (const link of links) {
+          insertLink.run(
+            link.sourcePath, link.targetPath, link.anchor, link.kind,
+            link.exists ? 1 : 0, link.line, link.rawTarget
+          );
+          linkCount += 1;
+        }
+      }
+      database.prepare(`
+        INSERT INTO runtime_meta (key, value, updated_at)
+        VALUES ('palace_source_fingerprint', ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
+      `).run(source.fingerprint);
+      database.prepare(`
+        UPDATE palace_index_runs SET
+          status = 'completed', document_count = ?, section_count = ?, link_count = ?,
+          completed_at = CURRENT_TIMESTAMP, summary = ?
+        WHERE id = ?
+      `).run(source.documents.length, sectionCount, linkCount, 'SPECS Mind Palace index refreshed.', run.id);
+      database.exec('COMMIT');
+    } catch (error) {
+      database.exec('ROLLBACK');
+      database.prepare(`UPDATE palace_index_runs SET status = 'failed', completed_at = CURRENT_TIMESTAMP, summary = ? WHERE id = ?`)
+        .run(error.message, run.id);
+      throw error;
+    }
+    return {
+      schema: 'ewai.palace-index/v1', status: 'completed', runId: run.id,
+      documents: source.documents.length, sections: sectionCount, links: linkCount,
+      fingerprint: source.fingerprint
+    };
+  } finally {
+    database.close();
+  }
+}
+
+export function palaceIndexStatus(projectRoot) {
+  const source = inventory(projectRoot);
+  const database = openRuntimeDatabase(projectRoot);
+  try {
+    const latest = database.prepare("SELECT * FROM palace_index_runs WHERE status = 'completed' ORDER BY id DESC LIMIT 1").get();
+    const counts = database.prepare('SELECT COUNT(*) AS documents, COALESCE(SUM(section_count), 0) AS sections FROM palace_documents').get();
+    if (!latest) return { schema: 'ewai.palace-index-status/v1', status: 'missing', documents: 0, sections: 0 };
+    return {
+      schema: 'ewai.palace-index-status/v1',
+      status: currentFingerprint(database) === source.fingerprint ? 'fresh' : 'stale',
+      runId: latest.id,
+      documents: counts.documents,
+      sections: counts.sections,
+      indexedAt: latest.completed_at
+    };
+  } finally {
+    database.close();
+  }
+}
+
+function ftsQuery(query) {
+  const terms = String(query).normalize('NFKC').match(/[\p{L}\p{N}_-]+/gu) ?? [];
+  return terms.map((term) => `"${term.replaceAll('"', '""')}"*`).join(' OR ');
+}
+
+export function searchPalace(projectRoot, query, options = {}) {
+  const index = refreshPalaceIndex(projectRoot);
+  const expression = ftsQuery(query);
+  if (!expression) return { schema: 'ewai.palace-search/v1', query, index, results: [] };
+  const requestedLimit = Number(options.limit ?? 50);
+  const limit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.floor(requestedLimit) : 50;
+  const database = openRuntimeDatabase(projectRoot);
+  try {
+    const rows = database.prepare(`
+      SELECT path, title, heading, heading_path, CAST(line AS INTEGER) AS line,
+        snippet(palace_sections_fts, 3, '⟦', '⟧', ' … ', 24) AS snippet,
+        bm25(palace_sections_fts, 4.0, 3.0, 2.0, 1.0) AS rank
+      FROM palace_sections_fts
+      WHERE palace_sections_fts MATCH ?
+      ORDER BY rank, path, CAST(line AS INTEGER)
+      LIMIT ?
+    `).all(expression, limit * 3);
+    const seen = new Set();
+    const results = [];
+    for (const row of rows) {
+      if (seen.has(row.path)) continue;
+      seen.add(row.path);
+      results.push(row);
+      if (results.length >= limit) break;
+    }
+    return { schema: 'ewai.palace-search/v1', query, index, results };
+  } finally {
+    database.close();
+  }
+}
+
+function finding(code, severity, path, message, details = {}) {
+  return { code, severity, path, message, details };
+}
+
+export function palaceTidiness(projectRoot) {
+  const index = refreshPalaceIndex(projectRoot);
+  const database = openRuntimeDatabase(projectRoot);
+  try {
+    const documents = database.prepare('SELECT * FROM palace_documents ORDER BY path').all();
+    const findings = [];
+    for (const document of documents) {
+      if (document.content_length === 0) findings.push(finding('empty-document', 'warning', document.path, 'The document is empty.'));
+      if (markdownExtensions.has(document.extension) && !document.has_title) {
+        findings.push(finding('missing-title', 'warning', document.path, 'The Markdown document has no level-one title.'));
+      }
+    }
+    for (const link of database.prepare(`SELECT * FROM palace_links WHERE exists_on_disk = 0 ORDER BY source_path, line`).all()) {
+      findings.push(finding(
+        'broken-internal-link', 'warning', link.source_path,
+        `The reference ${link.raw_target} does not resolve on disk.`,
+        { target: link.target_path, kind: link.kind, line: link.line }
+      ));
+    }
+    for (const group of database.prepare(`
+      SELECT content_hash, GROUP_CONCAT(path, '||') AS paths, COUNT(*) AS count
+      FROM palace_documents WHERE content_length > 0
+      GROUP BY content_hash HAVING COUNT(*) > 1
+    `).all()) {
+      const paths = group.paths.split('||');
+      for (const path of paths) findings.push(finding('duplicate-content', 'notice', path, 'Another Palace document has identical content.', { matches: paths.filter((candidate) => candidate !== path) }));
+    }
+    const linked = new Set();
+    for (const link of database.prepare("SELECT source_path, target_path FROM palace_links WHERE kind = 'specs' AND exists_on_disk = 1").all()) {
+      linked.add(link.source_path);
+      linked.add(link.target_path);
+    }
+    for (const document of documents) {
+      if (!markdownExtensions.has(document.extension) || linked.has(document.path)) continue;
+      if (/(?:^|\/)(?:README|_template)\.md$/i.test(document.path)) continue;
+      findings.push(finding('orphaned-document', 'notice', document.path, 'No other indexed SPECS document links to or from this document.'));
+    }
+
+    const counts = { warning: 0, notice: 0 };
+    for (const item of findings) counts[item.severity] = (counts[item.severity] ?? 0) + 1;
+    return {
+      schema: 'ewai.palace-tidiness/v1',
+      status: counts.warning > 0 || counts.notice > 0 ? 'housekeeping-recommended' : 'tidy',
+      documents: documents.length,
+      sections: index.sections,
+      links: index.links,
+      counts,
+      findings
+    };
+  } finally {
+    database.close();
+  }
+}
+
+export function palaceHousekeeping(projectRoot) {
+  const tidiness = palaceTidiness(projectRoot);
+  const grouped = new Map();
+  for (const item of tidiness.findings) {
+    if (!grouped.has(item.code)) grouped.set(item.code, []);
+    grouped.get(item.code).push(item);
+  }
+  return {
+    schema: 'ewai.palace-housekeeping/v1',
+    status: tidiness.status,
+    requiresApproval: true,
+    changedFiles: 0,
+    groups: [...grouped.entries()].map(([code, findings]) => ({ code, count: findings.length, findings })),
+    guidance: tidiness.status === 'tidy'
+      ? 'The Mind Palace is tidy. A no-op is the correct housekeeping result.'
+      : 'Use $ewai-palace-housekeeping to review these findings with the user before changing canonical SPECS.',
+    tidiness
+  };
+}

package/src/runtime/paths.mjs

@@ -0,0 +1,58 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { projectPaths } from '../paths.mjs';
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export function runtimePaths(projectRoot) {
+  const project = projectPaths(projectRoot);
+  const root = project.projectRoot;
+  const runtimeRoot = project.runtimeRoot;
+  return {
+    projectRoot: root,
+    runtimeRoot,
+    dataRoot: resolve(runtimeRoot, 'data'),
+    databasePath: resolve(runtimeRoot, 'data/pipeline.sqlite'),
+    runtimeStateRoot: resolve(runtimeRoot, 'runtime'),
+    dashboardStatePath: resolve(runtimeRoot, 'runtime/dashboard.json'),
+    checkinStatePath: resolve(runtimeRoot, 'runtime/checkin.json'),
+    guidedDiscoveryDraftPath: resolve(runtimeRoot, 'runtime/guided-discovery.json'),
+    guidedIntentDraftPath: resolve(runtimeRoot, 'runtime/guided-intent.json'),
+    evidenceDepthRoot: resolve(runtimeRoot, 'runtime/evidence-depth'),
+    evidenceDepthPreparationPath: resolve(runtimeRoot, 'runtime/evidence-depth/preparation.json'),
+    prototypeIterationsRoot: resolve(runtimeRoot, 'runtime/prototype-iterations'),
+    prototypeIterationRoot: (slug) => resolve(runtimeRoot, 'runtime/prototype-iterations', slug),
+    prototypePlanPreparationPath: (slug) => resolve(runtimeRoot, 'runtime/prototype-iterations', slug, 'plan-preparation.json'),
+    prototypeCyclePreparationPath: (slug, cycle) => resolve(runtimeRoot, 'runtime/prototype-iterations', slug, `cycle-${cycle}-preparation.json`),
+    phaseContributionsRoot: resolve(runtimeRoot, 'runtime/phase-contributions'),
+    phaseContributionDraftPath: (slug, phase) => resolve(runtimeRoot, 'runtime/phase-contributions', slug, `${phase}.json`),
+    contextPacksRoot: resolve(runtimeRoot, 'runtime/context-packs'),
+    contextPackManifestRoot: resolve(runtimeRoot, 'runtime/context-packs/manifests'),
+    contextPackCacheRoot: resolve(runtimeRoot, 'runtime/context-packs/cache'),
+    starterMaterialisationRoot: resolve(runtimeRoot, 'starter-materialisation'),
+    starterStagingRoot: resolve(runtimeRoot, 'starter-materialisation/staging'),
+    errorReportsRoot: resolve(runtimeRoot, 'error-reports'),
+    errorReportDraftsRoot: resolve(runtimeRoot, 'error-reports/drafts'),
+    errorReportPackagesRoot: resolve(runtimeRoot, 'error-reports/packages'),
+    errorReportReceiptsRoot: resolve(runtimeRoot, 'error-reports/receipts'),
+    errorReportArchiveRoot: resolve(runtimeRoot, 'error-reports/archive'),
+    errorReportAdaptersRoot: resolve(runtimeRoot, 'error-reports/adapters'),
+    errorReportSettingsPath: resolve(runtimeRoot, 'error-reports/settings.json'),
+    teamHubRoot: resolve(runtimeRoot, 'team-hub'),
+    teamHubConnectionPath: resolve(runtimeRoot, 'team-hub/connection.json'),
+    teamHubAttemptsRoot: resolve(runtimeRoot, 'team-hub/attempts'),
+    teamHubAcceptedReceiptPath: resolve(runtimeRoot, 'team-hub/accepted-receipt.json'),
+    teamHubResourcesRoot: resolve(runtimeRoot, 'team-hub/resources'),
+    teamHubResourceCacheRoot: resolve(runtimeRoot, 'team-hub/resources/cache'),
+    teamHubResourceStagingRoot: resolve(runtimeRoot, 'team-hub/resources/staging'),
+    teamHubResourceReceiptsRoot: resolve(runtimeRoot, 'team-hub/resources/receipts'),
+    teamHubResourceInstalledPath: resolve(runtimeRoot, 'team-hub/resources/installed.json'),
+    teamHubManagedPackRoot: resolve(runtimeRoot, 'packs/team-hub'),
+    logRoot: resolve(runtimeRoot, 'logs'),
+    dashboardLogPath: resolve(runtimeRoot, 'logs/dashboard.log'),
+    specsRoot: project.specsRoot,
+    specsRelative: project.specsRelative,
+    intentsRoot: resolve(project.specsRoot, '2.Purpose/intents'),
+    publicRoot: resolve(moduleDir, '../../public')
+  };
+}

package/src/runtime/persona-engagement.mjs

@@ -0,0 +1,255 @@
+import { createHash } from 'node:crypto';
+
+const tierRanks = { project: 4, premium: 3, personal: 2, core: 1 };
+
+function cleanText(value) {
+  return String(value ?? '').trim();
+}
+
+function words(value) {
+  return cleanText(value)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= 4);
+}
+
+function personaHaystack(persona) {
+  return [persona.id, persona.name, persona.category, persona.description, ...(persona.tags ?? []), ...(persona.capabilities ?? [])]
+    .map((value) => cleanText(value).toLowerCase())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function engagementReason(persona, contextLabel, matches) {
+  const concerns = matches.slice(0, 2).join(' and ');
+  return `${persona.name} is engaged to examine ${cleanText(contextLabel).toLowerCase()} through ${concerns || 'its relevant project lens'}.`;
+}
+
+export function selectContextualPersonas(options = {}) {
+  const signals = [...new Set((options.signals ?? []).map(cleanText).filter(Boolean))];
+  const contextText = JSON.stringify(options.context ?? {}).toLowerCase();
+  const catalogue = Array.isArray(options.personaCatalogue) ? options.personaCatalogue : [];
+  const limit = Math.max(1, Math.min(8, Number(options.limit ?? 4)));
+  const ranked = catalogue.map((persona) => {
+    const haystack = personaHaystack(persona);
+    const matchedSignals = [];
+    let score = 0;
+    for (const signal of signals) {
+      const normalised = signal.toLowerCase();
+      const tokenMatches = words(normalised).filter((word) => haystack.includes(word));
+      if (haystack.includes(normalised) || tokenMatches.length) {
+        matchedSignals.push(signal);
+        score += haystack.includes(normalised) ? 6 : tokenMatches.length * 2;
+      }
+    }
+    for (const tag of [...(persona.tags ?? []), ...(persona.capabilities ?? [])]) {
+      if (cleanText(tag).length >= 4 && contextText.includes(cleanText(tag).toLowerCase())) score += 1;
+    }
+    return { persona, score, matchedSignals };
+  }).filter((candidate) => candidate.score > 0)
+    .sort((left, right) => (
+      right.score - left.score
+      || (tierRanks[right.persona.tier] ?? 0) - (tierRanks[left.persona.tier] ?? 0)
+      || cleanText(left.persona.name).localeCompare(cleanText(right.persona.name))
+      || cleanText(left.persona.id).localeCompare(cleanText(right.persona.id))
+    ));
+
+  const selected = [];
+  for (const tier of ['project', 'premium']) {
+    const candidate = ranked.find((item) => item.persona.tier === tier);
+    if (candidate && !selected.includes(candidate)) selected.push(candidate);
+  }
+  for (const candidate of ranked) {
+    if (selected.length >= limit) break;
+    if (!selected.includes(candidate)) selected.push(candidate);
+  }
+
+  return selected.slice(0, limit).map(({ persona, matchedSignals }) => ({
+    id: cleanText(persona.id),
+    name: cleanText(persona.name),
+    tier: cleanText(persona.tier) || 'core',
+    category: cleanText(persona.category),
+    description: cleanText(persona.description).slice(0, 240),
+    matchedSignals,
+    engagementReason: engagementReason(persona, options.contextLabel || 'this context', matchedSignals)
+  }));
+}
+
+const policyStageSignals = Object.freeze({
+  facts: ['policy', 'evidence', 'data', 'privacy', 'security', 'design facts'],
+  evaluation: ['policy', 'evidence', 'security', 'destination', 'environment', 'controls'],
+  review: ['policy review', 'decision', 'evidence', 'security', 'risk'],
+  exception: ['exception', 'scope', 'expiry', 'ownership', 'compensating controls', 'risk'],
+});
+
+export function selectPolicyPersonas(context = {}, personaCatalogue = []) {
+  const stage = cleanText(context.stage || 'facts').toLowerCase();
+  const dimensions = (context.dimensions ?? []).map((dimension) => cleanText(dimension).replaceAll('_', '-')).filter(Boolean);
+  const signals = [...new Set([...(policyStageSignals[stage] ?? policyStageSignals.facts), ...dimensions])];
+  const activePersonas = selectContextualPersonas({
+    contextLabel: `${stage} policy design work`,
+    signals,
+    context: context.context ?? {},
+    personaCatalogue,
+    limit: 4,
+  });
+  const premiumInstalled = personaCatalogue.some((persona) => cleanText(persona.tier) === 'premium');
+  return {
+    schema: 'ewai.policy-persona-engagement/v1',
+    stage,
+    activePersonas,
+    baseline: {
+      standardModelAvailable: true,
+      completeWithoutPremium: true,
+    },
+    premium: {
+      installed: premiumInstalled,
+      reason: premiumInstalled
+        ? 'Installed premium personas may add relevant challenge depth.'
+        : 'The premium persona library is not installed; core policy behaviour remains available.',
+    },
+    authority: {
+      advisory: true,
+      mayConfirmFacts: false,
+      mayApproveReviews: false,
+      mayApproveExceptions: false,
+    },
+  };
+}
+
+const evidenceDepthSignals = Object.freeze({
+  architecture: ['architecture', 'dependency', 'integration', 'evidence', 'archaeology'],
+  data: ['data', 'privacy', 'retention', 'classification', 'evidence'],
+  security: ['security', 'trust boundary', 'identity', 'privacy', 'evidence'],
+  product: ['product', 'user journey', 'outcomes', 'acceptance', 'evidence'],
+  delivery: ['delivery', 'testing', 'release', 'quality', 'evidence'],
+  governance: ['governance', 'policy', 'compliance', 'decision', 'evidence'],
+  operations: ['operations', 'hosting', 'recovery', 'observability', 'evidence'],
+});
+
+export function selectEvidenceDepthPersonas(context = {}, personaCatalogue = []) {
+  const dimension = cleanText(context.dimension || 'architecture').toLowerCase();
+  const gapConditions = (context.gapConditions ?? []).map(cleanText).filter(Boolean);
+  const signals = [...new Set([...(evidenceDepthSignals[dimension] ?? evidenceDepthSignals.architecture), ...gapConditions])];
+  const activePersonas = selectContextualPersonas({
+    contextLabel: `${dimension} evidence-depth investigation`,
+    signals,
+    context: context.context ?? {},
+    personaCatalogue,
+    limit: 4,
+  });
+  const premiumInstalled = personaCatalogue.some((persona) => cleanText(persona.tier) === 'premium');
+  return {
+    schema: 'ewai.evidence-depth-persona-engagement/v1',
+    dimension,
+    activePersonas,
+    baseline: {
+      standardModelAvailable: true,
+      completeWithoutPremium: true,
+    },
+    premium: {
+      installed: premiumInstalled,
+      reason: premiumInstalled
+        ? 'Installed premium personas may add relevant specialist challenge depth.'
+        : 'The premium persona library is not installed; core and project persona capability remains complete.',
+    },
+    authority: {
+      advisory: true,
+      mayDeclareOwnerEvidence: false,
+      maySelectDepth: false,
+      mayApproveGrouping: false,
+    },
+  };
+}
+
+const prototypeStageSignals = Object.freeze({
+  plan: [
+    'product outcomes', 'user journey', 'acceptance', 'information architecture',
+    'decision ownership', 'accessibility', 'prototype plan',
+  ],
+  design: [
+    'rendered viewport', 'visual hierarchy', 'interaction', 'responsive',
+    'accessibility', 'usability', 'prototype critique',
+  ],
+});
+
+function personaAvailability(personaCatalogue) {
+  const counts = Object.fromEntries(['core', 'project', 'personal', 'premium'].map((tier) => [
+    tier,
+    personaCatalogue.filter((persona) => cleanText(persona.tier || 'core') === tier).length,
+  ]));
+  return {
+    standardModel: { available: true },
+    core: { available: counts.core > 0, count: counts.core },
+    project: { available: counts.project > 0, count: counts.project },
+    personal: { available: counts.personal > 0, count: counts.personal },
+    premium: { available: counts.premium > 0, count: counts.premium },
+  };
+}
+
+function prototypeFallback(personaCatalogue, stage, limit) {
+  const preferredIds = stage === 'plan'
+    ? ['project.product-owner', 'ewai.core.end-user']
+    : ['ewai.core.end-user', 'project.product-owner'];
+  const ranked = [...personaCatalogue].sort((left, right) => {
+    const leftPreferred = preferredIds.indexOf(cleanText(left.id));
+    const rightPreferred = preferredIds.indexOf(cleanText(right.id));
+    const leftRank = leftPreferred === -1 ? 100 : leftPreferred;
+    const rightRank = rightPreferred === -1 ? 100 : rightPreferred;
+    return leftRank - rightRank
+      || (tierRanks[right.tier] ?? 0) - (tierRanks[left.tier] ?? 0)
+      || cleanText(left.name).localeCompare(cleanText(right.name));
+  });
+  const baseline = ranked.filter((persona) => ['project', 'core'].includes(cleanText(persona.tier || 'core'))).slice(0, limit);
+  return baseline.map((persona) => ({
+    id: cleanText(persona.id),
+    name: cleanText(persona.name),
+    tier: cleanText(persona.tier) || 'core',
+    category: cleanText(persona.category),
+    description: cleanText(persona.description).slice(0, 240),
+    matchedSignals: ['baseline prototype review'],
+    engagementReason: `${cleanText(persona.name)} is engaged as a baseline ${stage} review perspective because no stronger catalogue match was found.`,
+  }));
+}
+
+export function selectPrototypeReviewPersonas(context = {}, personaCatalogue = []) {
+  const stage = cleanText(context.stage || 'plan').toLowerCase();
+  if (!['plan', 'design'].includes(stage)) throw new Error('Prototype persona engagement stage must be plan or design');
+  const catalogue = Array.isArray(personaCatalogue)
+    ? personaCatalogue.map((persona) => ({ ...persona, tier: cleanText(persona.tier) || 'core' }))
+    : [];
+  const suppliedSignals = (context.signals ?? []).map(cleanText).filter(Boolean);
+  const signals = [...new Set(suppliedSignals.length ? suppliedSignals : (prototypeStageSignals[stage] ?? []))];
+  const limit = Math.max(1, Math.min(8, Number(context.limit ?? 6)));
+  let activePersonas = selectContextualPersonas({
+    contextLabel: stage === 'plan' ? 'prototype plan review' : 'rendered prototype review',
+    signals,
+    context: context.context ?? {},
+    personaCatalogue: catalogue,
+    limit,
+  });
+  if (!activePersonas.length) activePersonas = prototypeFallback(catalogue, stage, limit);
+  const availability = personaAvailability(catalogue);
+  const fingerprintInput = {
+    stage,
+    signals: [...signals].sort(),
+    activePersonas: activePersonas.map(({ id, tier, matchedSignals }) => ({ id, tier, matchedSignals: [...matchedSignals].sort() })).sort((left, right) => left.id.localeCompare(right.id)),
+    availability,
+  };
+  const premiumNotice = availability.premium.available
+    ? 'Installed premium personas are eligible when their specialism matches this stage.'
+    : 'Premium personas are not installed; standard model, core, and project persona review remains complete.';
+  const personalNotice = availability.personal.available
+    ? 'Installed personal personas are eligible when their local perspective matches this stage.'
+    : 'Personal personas are not installed and are optional enrichment.';
+  return {
+    schema: 'ewai.prototype-persona-engagement/v1',
+    stage,
+    selectionFingerprint: `sha256:${createHash('sha256').update(JSON.stringify(fingerprintInput)).digest('hex')}`,
+    activePersonas,
+    availability,
+    baseline: { completeWithoutOptionalPersonas: true },
+    notices: [premiumNotice, personalNotice],
+    authority: { advisory: true, maySelectPrototype: false, mayApproveManualQa: false },
+  };
+}