phronesis 1.0.0

package/vendor/core/src/guard.js

@@ -0,0 +1,398 @@
+// Context relevance guard — pre-answer recall for owned-context advice/action prompts
+// (core-0019 / T5.2a). The guard brain lives in @phronesis/core: surfaces pass a
+// prompt plus execution context, core detects, emits recall.candidate, composes the
+// in-process retrieval packet, then emits recall.injected. CLI and hooks are glue.
+
+import { createHash } from 'node:crypto';
+import { join, relative, resolve, sep } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { appendEvent } from './event-log.js';
+import { appendAuditEntry } from './hook-executor.js';
+import { resolveInstall } from './install-root.js';
+import { loadSearchIndex } from './search.js';
+
+export const GUARD_ID = 'on_recall_candidate';
+export const GUARD_RULESET_VERSION = 'guard-rules-v2';
+
+const STALE_STATUSES = new Set(['archived', 'superseded']);
+const DEFAULT_LIMIT = 10;
+const DEFAULT_HOPS = 1;
+
+const POSSESSIVE_RE =
+  /\b(my|our|ours|mine|this|that|current|the current|at my company|for my team|for our team|my company|our company)\b/i;
+const ADVICE_RE =
+  /\b(should i|should we|what should i|what should we|what do i do|what do we do|what's next|what is next|can i|can we|can i wait|can we wait|is it safe to|do we|do i|which option|how should i|how should we|need to)\b/i;
+const NAMED_CONTEXT_RE =
+  /\b(tell me about|status of|update on|give me an update on|how's my|how is my|how's our|how is our|what's the status of|what is the status of|where are we on|where are we with)\b/i;
+
+function sha256(s) {
+  return createHash('sha256').update(String(s ?? ''), 'utf8').digest('hex');
+}
+
+function normalizePhrase(s) {
+  return String(s ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function phraseMatchesPrompt(phrase, normalizedPrompt) {
+  const normalized = normalizePhrase(phrase);
+  if (normalized.length < 4) return false;
+  return ` ${normalizedPrompt} `.includes(` ${normalized} `);
+}
+
+function ruleMatches(prompt) {
+  const text = String(prompt ?? '');
+  const rules = [];
+  let confidence = 0;
+
+  if (POSSESSIVE_RE.test(text)) {
+    rules.push('possessive');
+    confidence += 0.65;
+  }
+  if (ADVICE_RE.test(text)) {
+    rules.push('advice-verb');
+    confidence += 0.7;
+  }
+
+  return { rules, confidence };
+}
+
+function shouldCheckNameMatch(prompt) {
+  const text = String(prompt ?? '');
+  const titleLike = /\b[A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+)+\b/.test(text);
+  const slugLike = /\b[a-z0-9]+-[a-z0-9-]+\b/i.test(text);
+  return titleLike || slugLike || NAMED_CONTEXT_RE.test(text);
+}
+
+function objectNameMatch(prompt, docs = []) {
+  const normalizedPrompt = normalizePhrase(prompt);
+  if (!normalizedPrompt) return false;
+  return docs.some((doc) => {
+    const candidates = [doc.name, doc.title].filter(Boolean);
+    return candidates.some((candidate) => phraseMatchesPrompt(candidate, normalizedPrompt));
+  });
+}
+
+function triggerFor(rules, confidence) {
+  return {
+    category: 'owned-context-advice',
+    rules,
+    ruleset_version: GUARD_RULESET_VERSION,
+    confidence,
+  };
+}
+
+export function detectContextRelevance(prompt, docs = []) {
+  const { rules, confidence: baseConfidence } = ruleMatches(prompt);
+  let confidence = baseConfidence;
+  if (objectNameMatch(prompt, docs)) {
+    rules.push('name-match');
+    confidence += 0.8;
+  }
+
+  confidence = Math.min(0.99, Number(confidence.toFixed(2)));
+  const hasNameMatch = rules.includes('name-match');
+  const hasOwnedAdvice = rules.includes('possessive') && rules.includes('advice-verb');
+  return {
+    fired: hasNameMatch || hasOwnedAdvice,
+    confidence,
+    trigger: triggerFor(rules, confidence),
+  };
+}
+
+function parseSkipList(env = {}) {
+  const raw = env.PHRONESIS_SKIP;
+  if (typeof raw !== 'string' || raw.trim() === '') return new Set();
+  return new Set(raw.split(',').map((s) => s.trim()).filter(Boolean));
+}
+
+function isSkipped(env) {
+  const skip = parseSkipList(env);
+  return skip.has(GUARD_ID) || skip.has('context-relevance-guard');
+}
+
+async function auditGuard(installRoot, entry) {
+  await appendAuditEntry(installRoot, {
+    hook: GUARD_ID,
+    kind: 'ambient',
+    classification: 'silent',
+    ...entry,
+  });
+}
+
+function activeResults(results) {
+  return results.filter((r) => !STALE_STATUSES.has(r.status));
+}
+
+function staleResults(results) {
+  return results.filter((r) => STALE_STATUSES.has(r.status));
+}
+
+function activeLinkedNodes(result) {
+  const nodes = result.subgraph?.nodes ?? [];
+  return nodes.filter(
+    (n) =>
+      n.kind === 'object' &&
+      n.path !== result.path &&
+      !STALE_STATUSES.has(n.status),
+  );
+}
+
+function formatSources(result) {
+  const sources = Array.isArray(result.sources) ? result.sources : [];
+  return sources.length ? sources.join(', ') : 'none cited';
+}
+
+function formatRecallPacket({ results, stale, trigger }) {
+  const lines = [
+    'Phronesis recall packet',
+    '',
+    `Trigger: ${trigger.category} (${trigger.rules.join(', ') || 'none'}; ${trigger.ruleset_version})`,
+    '',
+    'Current workspace state:',
+  ];
+
+  for (const r of results) {
+    lines.push(
+      `- ${r.title ?? r.name ?? r.path} (${r.type ?? 'object'}, status: ${r.status ?? 'active'}, exposure: ${r.exposure ?? 'unknown'})`,
+      `  Path: ${r.path}`,
+    );
+    if (r.snippet) lines.push(`  Snippet: ${r.snippet}`);
+    lines.push(`  Sources: ${formatSources(r)}`);
+    const linked = activeLinkedNodes(r);
+    if (linked.length) {
+      lines.push('  Linked context:');
+      for (const n of linked) {
+        lines.push(
+          `  - ${n.title ?? n.name ?? n.path} (${n.type ?? 'object'}, status: ${n.status ?? 'active'}, exposure: ${n.exposure ?? 'unknown'})`,
+          `    Path: ${n.path}`,
+        );
+      }
+    }
+  }
+
+  if (stale.length) {
+    lines.push('', 'Excluded stale diagnostics:');
+    for (const r of stale) {
+      lines.push(`- ${r.path} (status: ${r.status})`);
+    }
+  }
+
+  lines.push(
+    '',
+    'Use this workspace state before answering. Preserve the cited paths and exposure tiers in the response.',
+  );
+  return lines.join('\n');
+}
+
+function formatHonestNegative({ stale = [] } = {}) {
+  const lines = [
+    'No existing compiled/codex state found for this owned-context prompt.',
+    'Say that plainly before answering from general knowledge, and consider capture if this should become workspace state.',
+  ];
+  if (stale.length) {
+    lines.push('', 'Excluded stale diagnostics:');
+    for (const r of stale) lines.push(`- ${r.path} (status: ${r.status})`);
+  }
+  return lines.join('\n');
+}
+
+function normalizeResult({ promptHash, trigger, retrieval, startedAt }) {
+  const current = activeResults(retrieval.results);
+  const stale = staleResults(retrieval.results);
+  const empty = current.length === 0;
+  const packet = empty
+    ? formatHonestNegative({ stale })
+    : formatRecallPacket({ results: current, stale, trigger });
+  return {
+    fired: true,
+    empty_result: empty,
+    packet,
+    result_paths: current.map((r) => r.path),
+    result_count: current.length,
+    prompt_hash: promptHash,
+    trigger,
+    retrieval_latency_ms: retrieval.latency_ms,
+    latency_ms: Math.round(performance.now() - startedAt),
+    excluded_stale_paths: stale.map((r) => r.path),
+  };
+}
+
+async function emitCandidate({ installRoot, session, actor, surface, prompt, promptHash, trigger, confidence, now }) {
+  return appendEvent({
+    installRoot,
+    type: 'recall.candidate',
+    session_id: session,
+    actor,
+    surface,
+    payload: {
+      prompt_hash: promptHash,
+      trigger,
+      query: String(prompt ?? ''),
+      confidence,
+    },
+    now,
+  });
+}
+
+async function emitInjected({ installRoot, session, actor, surface, result, now }) {
+  return appendEvent({
+    installRoot,
+    type: 'recall.injected',
+    session_id: session,
+    actor,
+    surface,
+    payload: {
+      prompt_hash: result.prompt_hash,
+      result_paths: result.result_paths,
+      result_count: result.result_count,
+      empty_result: result.empty_result,
+      latency_ms: result.latency_ms,
+    },
+    now,
+  });
+}
+
+function resolveRoot({ installRoot, dir, cwd }) {
+  if (installRoot) return installRoot;
+  const resolved = resolveInstall({ dir, cwd });
+  if (resolved.error) throw new Error(resolved.error);
+  return resolved.root;
+}
+
+async function readRegisteredDomains(root) {
+  const registry = JSON.parse(await readFile(join(root, '.phronesis', 'registry.json'), 'utf8'));
+  return Array.isArray(registry.domains) ? registry.domains : [];
+}
+
+function domainFromCwd(root, cwd, registered) {
+  if (!cwd) return undefined;
+  const parts = relative(root, resolve(cwd)).split(sep);
+  return parts[0] === 'domains' && registered.includes(parts[1]) ? parts[1] : undefined;
+}
+
+async function guardSearchScope(root, requestedDomain, cwd) {
+  if (requestedDomain !== undefined) return { domain: requestedDomain, allDomains: false };
+  const registered = await readRegisteredDomains(root);
+  const cwdDomain = domainFromCwd(root, cwd, registered);
+  if (cwdDomain) return { domain: cwdDomain, allDomains: false };
+  if (registered.length === 1) return { domain: registered[0], allDomains: false };
+  if (registered.length > 1) return { domain: undefined, allDomains: true };
+  return { domain: undefined, allDomains: false };
+}
+
+function needsIndexForDetection(prompt) {
+  const cheap = ruleMatches(prompt).rules;
+  return (
+    (cheap.includes('possessive') && cheap.includes('advice-verb')) ||
+    shouldCheckNameMatch(prompt)
+  );
+}
+
+function auditErrorFields(err) {
+  return {
+    error: 'guard execution failed',
+    error_name: err?.name || 'Error',
+  };
+}
+
+export async function runContextRelevanceGuard({
+  installRoot,
+  dir,
+  cwd = process.cwd(),
+  prompt,
+  session,
+  surface,
+  actor,
+  domain,
+  env = process.env,
+  now = new Date(),
+  loadIndex = loadSearchIndex,
+} = {}) {
+  const startedAt = performance.now();
+  if (typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('guard prompt is required on stdin');
+  }
+  if (typeof session !== 'string' || session === '') {
+    throw new Error('guard requires --session <id>');
+  }
+  if (typeof surface !== 'string' || surface === '') {
+    throw new Error('guard requires --surface <name>');
+  }
+  if (typeof actor !== 'string' || actor === '') {
+    throw new Error('guard requires --actor <name> or PHRONESIS_ACTOR');
+  }
+
+  const root = resolveRoot({ installRoot, dir, cwd });
+  const promptHash = sha256(prompt);
+
+  if (isSkipped(env)) {
+    await auditGuard(root, {
+      session_id: session,
+      event_type: 'recall.candidate',
+      prompt_hash: promptHash,
+      outcome: 'skipped-kill-switch',
+    });
+    return { fired: false, bypassed: true };
+  }
+
+  if (!needsIndexForDetection(prompt)) return { fired: false };
+
+  const scope = await guardSearchScope(root, domain, cwd);
+  const index = await loadIndex({
+    installRoot: root,
+    cwd,
+    domain: scope.domain,
+    allDomains: scope.allDomains,
+    persist: false,
+  });
+  const detection = detectContextRelevance(prompt, index.scopedDocs);
+  if (!detection.fired) return { fired: false };
+
+  let candidate = null;
+  try {
+    candidate = await emitCandidate({
+      installRoot: root,
+      session,
+      actor,
+      surface,
+      prompt,
+      promptHash,
+      trigger: detection.trigger,
+      confidence: detection.confidence,
+      now,
+    });
+
+    const retrieval = index.query(prompt, { limit: DEFAULT_LIMIT, hops: DEFAULT_HOPS });
+    const result = normalizeResult({
+      promptHash,
+      trigger: detection.trigger,
+      retrieval,
+      startedAt,
+    });
+
+    await emitInjected({
+      installRoot: root,
+      session,
+      actor,
+      surface,
+      result,
+      now,
+    });
+
+    return result;
+  } catch (err) {
+    await auditGuard(root, {
+      session_id: session,
+      event_type: 'recall.candidate',
+      ...(candidate?.id ? { event_id: candidate.id } : {}),
+      prompt_hash: promptHash,
+      outcome: 'failed',
+      ...auditErrorFields(err),
+    });
+    throw err;
+  }
+}