incremnt 0.8.7 → 0.8.8

package/src/ask-replay.js

@@ -3,7 +3,8 @@ import path from 'node:path';
 
 import {
   AI_PROMPT_VERSIONS,
-  generateAskAnswerAgentic
+  generateAskAnswerAgentic,
+  generateAskAnswerStarterGraph
 } from './openrouter.js';
 import { verifyAskAnswer } from './ask-answer-verifier.js';
 import {
@@ -42,6 +43,22 @@ function invocationNames(invocations) {
   return asArray(invocations).map((invocation) => invocation?.name).filter(Boolean);
 }
 
+function graphToolNames(generationMetadata = {}, testCase = null) {
+  return asArray(
+    generationMetadata.graph?.toolNames
+      ?? generationMetadata.graphToolNames
+      ?? testCase?.expectedStarterGraph?.toolNames
+  );
+}
+
+function graphNodeNames(generationMetadata = {}, testCase = null) {
+  return asArray(
+    generationMetadata.graph?.nodes
+      ?? generationMetadata.graphNodes
+      ?? testCase?.expectedStarterGraph?.nodes
+  );
+}
+
 function askReplayChecks(testCase, context, output, generationMetadata = {}) {
   const assertions = testCase.replayAssertions ?? {};
   const metadata = context?.routedMetadata ?? {};
@@ -104,6 +121,30 @@ function askReplayChecks(testCase, context, output, generationMetadata = {}) {
     });
   }
 
+  if (assertions.graphTools) {
+    const actual = graphToolNames(generationMetadata, generationMetadata.mode === 'live' ? null : testCase);
+    const passed = includesAll(actual, assertions.graphTools);
+    checks.push({
+      key: 'ask_replay_graph_tools',
+      passed,
+      reason: passed
+        ? 'Starter graph tools include all replay requirements.'
+        : `Expected graph tools to include ${assertions.graphTools.join(', ')}; got ${actual.join(', ')}.`
+    });
+  }
+
+  if (assertions.graphNodes) {
+    const actual = graphNodeNames(generationMetadata, generationMetadata.mode === 'live' ? null : testCase);
+    const passed = includesAll(actual, assertions.graphNodes);
+    checks.push({
+      key: 'ask_replay_graph_nodes',
+      passed,
+      reason: passed
+        ? 'Starter graph nodes include all replay requirements.'
+        : `Expected graph nodes to include ${assertions.graphNodes.join(', ')}; got ${actual.join(', ')}.`
+    });
+  }
+
   for (const assertion of asArray(assertions.requiredContextPatterns)) {
     const passed = patternMatches(context?.trainingData, assertion.pattern);
     checks.push({
@@ -164,6 +205,8 @@ function askReplayChecks(testCase, context, output, generationMetadata = {}) {
   if (assertions.promptVersion) {
     const expected = assertions.promptVersion === 'currentAskAgentic'
       ? AI_PROMPT_VERSIONS.askAgentic
+      : assertions.promptVersion === 'currentAskStarterGraph'
+      ? AI_PROMPT_VERSIONS.askStarterGraph
       : assertions.promptVersion;
     const actual = generationMetadata.promptVersion ?? AI_PROMPT_VERSIONS.askAgentic;
     checks.push({
@@ -201,7 +244,8 @@ export async function runAskReplayCase(testCase, {
   live = false,
   apiKey = process.env.OPENROUTER_API_KEY,
   model = null,
-  generateAskAnswerAgenticImpl = generateAskAnswerAgentic
+  generateAskAnswerAgenticImpl = generateAskAnswerAgentic,
+  generateAskAnswerStarterGraphImpl = generateAskAnswerStarterGraph
 } = {}) {
   const snapshot = await loadSummaryEvalSnapshot(testCase);
   const context = buildSummaryEvalContext(snapshot, testCase);
@@ -210,12 +254,27 @@ export async function runAskReplayCase(testCase, {
   let output = testCase.output;
   let generationMetadata = {
     mode: 'stored',
-    promptVersion: AI_PROMPT_VERSIONS.askAgentic
+    promptVersion: testCase.starterPrompt?.family
+      ? AI_PROMPT_VERSIONS.askStarterGraph
+      : AI_PROMPT_VERSIONS.askAgentic
   };
 
   if (live) {
     if (!apiKey) throw new Error('OPENROUTER_API_KEY is required for live Ask replay.');
-    const result = await generateAskAnswerAgenticImpl(context.trainingData, context.question ?? testCase.question, {
+    const question = context.question ?? testCase.question;
+    const starterPrompt = testCase.starterPrompt;
+    const result = starterPrompt?.family
+      ? await generateAskAnswerStarterGraphImpl(context.trainingData, question, {
+        apiKey,
+        model: model ?? context.model,
+        history: context.history ?? [],
+        tone: context.tone,
+        snapshot,
+        starterPrompt,
+        routingMetadata: context.routedMetadata ?? undefined,
+        exclude: testCase.exclude ?? []
+      })
+      : await generateAskAnswerAgenticImpl(context.trainingData, question, {
       apiKey,
       model: model ?? context.model,
       history: context.history ?? [],
@@ -231,6 +290,7 @@ export async function runAskReplayCase(testCase, {
       promptVersion: result.promptVersion,
       promptSurface: result.promptSurface,
       toolInvocations: result.toolInvocations ?? [],
+      graph: result.graph,
       langfuseTraceId: result.langfuseTraceId,
       langfuseObservationId: result.langfuseObservationId
     };
@@ -267,6 +327,9 @@ export async function runAskReplayCase(testCase, {
     requiredTools: context.routedMetadata?.evidencePlan?.requiredTools ?? [],
     routedTools: context.routedMetadata?.evidencePlan?.executedTools ?? [],
     agenticTools: invocationNames(generationMetadata.toolInvocations),
+    graphTools: graphToolNames(generationMetadata, testCase),
+    graphNodes: graphNodeNames(generationMetadata, testCase),
+    starterPrompt: testCase.starterPrompt ?? null,
     executedTools: context.routedMetadata?.evidencePlan?.executedTools ?? [],
     answerVerification,
     output,
@@ -333,6 +396,9 @@ export function formatAskReplayMarkdown(report) {
     if (result.mode === 'live') {
       lines.push(`Agentic tools: ${result.agenticTools.join(', ') || 'none'}`);
     }
+    if (result.graphTools.length > 0) {
+      lines.push(`Graph tools: ${result.graphTools.join(', ')}`);
+    }
     lines.push('');
     lines.push(result.output);
     lines.push('');

package/src/ask-starter-prompts.js

@@ -0,0 +1,206 @@
+export const STARTER_PROMPT_FAMILIES = Object.freeze([
+  'recent_session_review',
+  'lift_progress',
+  'pr_review',
+  'training_review',
+  'next_session_prep',
+  'plan_creation',
+  'evergreen_strength',
+  'muscle_coverage',
+  'consistency_review',
+  'comeback_review',
+  'score_review'
+]);
+
+export const STARTER_GRAPH_VERSION = 'ask_starter_langgraph_v1';
+
+const STARTER_PROMPT_FAMILY_SET = new Set(STARTER_PROMPT_FAMILIES);
+const CONTEXT_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+const MAX_CONTEXT_FIELDS = 10;
+const MAX_CONTEXT_VALUE_CHARS = 200;
+
+export function starterWorkflowEnabled(env = process.env) {
+  return ['1', 'true', 'yes', 'on'].includes(String(env.ASK_STARTER_LANGGRAPH_ENABLED ?? '').trim().toLowerCase());
+}
+
+export function normalizeStarterPrompt(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+
+  const family = typeof raw.family === 'string' ? raw.family.trim() : '';
+  if (!STARTER_PROMPT_FAMILY_SET.has(family)) return null;
+
+  const question = typeof raw.question === 'string' ? raw.question.trim() : '';
+  if (!question || question.length > 500) return null;
+
+  const context = normalizeStarterPromptContext(raw.context);
+  return {
+    family,
+    question,
+    ...(Object.keys(context).length > 0 ? { context } : {})
+  };
+}
+
+export function isSupportedStarterPrompt(starterPrompt) {
+  return Boolean(starterPrompt && STARTER_PROMPT_FAMILY_SET.has(starterPrompt.family));
+}
+
+export function starterGraphFallbackReason(error) {
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  if (/timeout|abort/i.test(message)) return 'timeout';
+  if (/unsupported/i.test(message)) return 'unsupported';
+  if (/invalid/i.test(message)) return 'invalid_output';
+  return 'error';
+}
+
+export function starterPromptToolPlan(starterPrompt) {
+  if (!isSupportedStarterPrompt(starterPrompt)) return [];
+
+  const exercise = starterPrompt.context?.exerciseName
+    ?? starterPrompt.context?.exercise
+    ?? null;
+  const exerciseParams = exercise ? { exercises: [exercise] } : {};
+
+  switch (starterPrompt.family) {
+  case 'lift_progress':
+    return [
+      { name: 'get_exercise_history', params: { ...exerciseParams, limit: 8, recencyCutoffDays: 90 } },
+      { name: 'get_exercise_progress_summary', params: { ...exerciseParams, limit: 12 } },
+      { name: 'get_records', params: { ...exerciseParams, limit: exercise ? 5 : 15 } }
+    ];
+  case 'pr_review':
+  case 'evergreen_strength':
+    return [
+      { name: 'get_records', params: { ...exerciseParams, limit: exercise ? 5 : 15 } },
+      { name: 'get_exercise_progress_summary', params: { ...exerciseParams, limit: 10 } }
+    ];
+  case 'recent_session_review':
+    return [
+      { name: 'get_recent_sessions', params: { limit: 1, includeStale: true, recencyCutoffDays: 30 } },
+      { name: 'compare_session_to_observations', params: { observationLimit: 5, includeOutcomeHistory: true } },
+      { name: 'get_next_session', params: { historyLimit: 6, recencyCutoffDays: 90 } }
+    ];
+  case 'training_review':
+  case 'consistency_review':
+  case 'comeback_review':
+    return [
+      { name: 'get_recent_sessions', params: { limit: 8, includeStale: true, recencyCutoffDays: 60 } },
+      { name: 'get_weekly_volume', params: {} },
+      { name: 'get_records', params: { limit: 15 } },
+      { name: 'get_readiness_snapshot', params: { recentDays: 14 } },
+      { name: 'get_body_weight_snapshot', params: { recentDays: 30 } },
+      ...(isStarterScoreQuestion(starterPrompt) ? [{ name: 'get_increment_score', params: { historyDays: 21 } }] : [])
+    ];
+  case 'score_review':
+    return [
+      { name: 'get_increment_score', params: { historyDays: 21 } },
+      { name: 'get_recent_sessions', params: { limit: 4, includeStale: true, recencyCutoffDays: 30 } }
+    ];
+  case 'next_session_prep':
+    return [
+      { name: 'get_next_session', params: { historyLimit: 8, recencyCutoffDays: 90 } },
+      { name: 'get_recent_sessions', params: { limit: 3, includeStale: true, recencyCutoffDays: 45 } },
+      { name: 'get_exercise_history', params: { limit: 8, recencyCutoffDays: 90 } }
+    ];
+  case 'plan_creation':
+    return [
+      { name: 'get_training_profile', params: {} },
+      { name: 'get_recent_sessions', params: { limit: 8, includeStale: true, recencyCutoffDays: 90 } },
+      { name: 'get_program_progress', params: { limitExercises: 10 } }
+    ];
+  case 'muscle_coverage':
+    return [
+      { name: 'get_muscle_volume_trend', params: { weeks: 4 } },
+      { name: 'get_recent_sessions', params: { limit: 8, includeStale: true, recencyCutoffDays: 60 } }
+    ];
+  default:
+    return [];
+  }
+}
+
+function isStarterScoreQuestion(starterPrompt) {
+  return /\b(?:increment\s+)?score\b/i.test(String(starterPrompt?.question ?? ''));
+}
+
+export function starterPromptAnswerContract(starterPrompt) {
+  switch (starterPrompt?.family) {
+  case 'lift_progress':
+    return 'Answer with the lift trend, the evidence, and what to do on the next exposure.';
+  case 'recent_session_review':
+    return 'Answer with one win, one watch item if supported, and the next move.';
+  case 'training_review':
+  case 'consistency_review':
+  case 'comeback_review':
+    return 'Answer with the broad trend, the main driver, and the decision question or next action.';
+  case 'score_review':
+    return 'Explain the current 7-day Score in plain training language: what helped, what held it back, and whether the trend is improving. Do not dump raw sub-scores or tool output.';
+  case 'next_session_prep':
+    return 'Answer with expected work for the next session and what to watch.';
+  case 'plan_creation':
+    return 'Draft a concise plan answer and append exactly one trailing <program_draft>{JSON}</program_draft> block if the evidence supports a valid draft. The draft JSON may only use countable reps from 1-30; do not include timed holds, seconds, distance, duration, or extra set keys. Never apply the plan.';
+  case 'evergreen_strength':
+  case 'pr_review':
+    return 'Answer with the relevant record or PR evidence and what it means now.';
+  case 'muscle_coverage':
+    return 'Answer from effective-set muscle data, naming the main under-trained areas and the next adjustment.';
+  default:
+    return 'Answer the tapped starter prompt using only the supplied training evidence.';
+  }
+}
+
+export function starterPromptStructuredIntentHint(starterPrompt) {
+  switch (starterPrompt?.family) {
+  case 'lift_progress':
+  case 'pr_review':
+  case 'evergreen_strength':
+    return { route: 'exercise_progress_summary' };
+  case 'recent_session_review':
+    return { route: 'recent_session' };
+  case 'training_review':
+  case 'consistency_review':
+  case 'comeback_review':
+    return { route: 'progress_review' };
+  case 'score_review':
+    return { route: 'score' };
+  case 'next_session_prep':
+    return { route: 'next_session' };
+  case 'plan_creation':
+    return { route: 'program_design', requestedAction: 'draft_plan' };
+  case 'muscle_coverage':
+    return { route: 'volume' };
+  default:
+    return null;
+  }
+}
+
+export function applyStarterPromptStructuredIntentHint(routingMetadata, starterPrompt) {
+  if (!routingMetadata || typeof routingMetadata !== 'object') return routingMetadata;
+  const hint = starterPromptStructuredIntentHint(starterPrompt);
+  if (!hint) return routingMetadata;
+
+  const currentRoute = routingMetadata.intent?.route ?? routingMetadata.route;
+  const shouldApplyRoute = !currentRoute || currentRoute === 'general';
+  const intent = {
+    ...(routingMetadata.intent ?? {}),
+    ...(shouldApplyRoute ? { route: hint.route } : {}),
+    ...(hint.requestedAction && !routingMetadata.intent?.requestedAction ? { requestedAction: hint.requestedAction } : {})
+  };
+  return {
+    ...routingMetadata,
+    ...(shouldApplyRoute ? { route: hint.route } : {}),
+    intent
+  };
+}
+
+function normalizeStarterPromptContext(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const context = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (Object.keys(context).length >= MAX_CONTEXT_FIELDS) break;
+    if (!CONTEXT_KEY_RE.test(key)) continue;
+    if (!['string', 'number', 'boolean'].includes(typeof value)) continue;
+    const text = String(value).trim();
+    if (!text || text.length > MAX_CONTEXT_VALUE_CHARS) continue;
+    context[key] = text;
+  }
+  return context;
+}

package/src/auth.js

@@ -362,6 +362,32 @@ export async function refreshRemoteSession(baseUrl, token, previousSession = nul
   });
 }
 
+export async function refreshRemoteContractMetadata(baseUrl, token, previousSession = null) {
+  const remoteContract = await fetchRemoteContract(baseUrl, token);
+  const checkedAt = new Date().toISOString();
+
+  return writeSessionState({
+    version: previousSession?.version ?? 1,
+    mode: 'remote',
+    account: previousSession?.account ?? null,
+    auth: previousSession?.auth ?? {
+      accessToken: token,
+      refreshToken: null,
+      expiresAt: null
+    },
+    sync: {
+      ...(previousSession?.sync ?? {}),
+      contractCheckedAt: checkedAt
+    },
+    transport: {
+      ...(previousSession?.transport ?? {}),
+      baseUrl,
+      contractVersion: remoteContract.contractVersion,
+      capabilities: remoteContract.capabilities ?? null
+    }
+  });
+}
+
 export async function createRemoteAgentToken(baseUrl, bearerToken, {
   name,
   access = 'read',

package/src/coach-advice.js

@@ -0,0 +1,32 @@
+import { sanitizeCoachAdviceCandidate } from './ask-coach.js';
+
+function collapseBlankLines(text) {
+  return String(text ?? '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function extractCoachAdvice(rawText) {
+  const text = String(rawText ?? '');
+  const match = text.match(/<coach_advice>\s*([\s\S]*?)\s*<\/coach_advice>/i);
+  if (!match) {
+    return { answerText: text.trim(), coachAdvice: null };
+  }
+
+  const answerText = collapseBlankLines(text.replace(match[0], ''));
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch (err) {
+    console.warn('askCoach: <coach_advice> JSON parse failed - dropping advice:', err.message);
+    return { answerText, coachAdvice: null };
+  }
+
+  const coachAdvice = sanitizeCoachAdviceCandidate(parsed);
+  if (!coachAdvice) {
+    console.warn('askCoach: <coach_advice> payload failed validation - dropping advice');
+    return { answerText, coachAdvice: null };
+  }
+
+  return { answerText, coachAdvice };
+}

package/src/coach-facts.js

@@ -1,5 +1,17 @@
 export const COACH_FACT_KINDS = Object.freeze(['preference', 'constraint', 'injury', 'goal_signal', 'tone']);
 
+export const COACH_FACT_PRESENTATION = Object.freeze([
+  { kind: 'goal_signal', key: 'goals', title: 'Goals', kindTitle: 'Goal' },
+  { kind: 'constraint', key: 'constraints', title: 'Constraints', kindTitle: 'Constraint' },
+  { kind: 'injury', key: 'injuries', title: 'Injuries', kindTitle: 'Injury' },
+  { kind: 'preference', key: 'preferences', title: 'Preferences', kindTitle: 'Preference' },
+  { kind: 'tone', key: 'tone', title: 'Tone', kindTitle: 'Tone' }
+]);
+
+const COACH_FACT_GROUP_KEYS = Object.freeze(
+  Object.fromEntries(COACH_FACT_PRESENTATION.map((section) => [section.kind, section.key]))
+);
+
 const COACH_FACT_KIND_SET = new Set(COACH_FACT_KINDS);
 
 const PROMPT_INJECTION_PATTERNS = [
@@ -22,6 +34,51 @@ const EPHEMERAL_PATTERNS = [
   /\b(current|currently|latest|recent)\s+(?:best|e1rm|1rm|volume|pr|record|session|workout)\b/i
 ];
 
+const EPHEMERAL_RESPONSE_REQUEST_PATTERNS = [
+  /\b(?:i\s+want|i\s+asked\s+for|i\s+ask\s+for|i(?:'d| would)?\s+like|wants|asked for|asks for|would like)\b.{0,80}\b(right now|for this answer|current answer)\b/i,
+  /\b(?:i\s+want|i\s+asked\s+for|i\s+ask\s+for|i(?:'d| would)?\s+like|wants|asked for|asks for|would like)\b.{0,80}\b(latest|recent|last|current|today|this week|this month|past|six[-\s]?month|\d+\s+(?:days|weeks|months|years))\b.{0,80}\b(coaching\s+)?(read|take|answer|response|summary|breakdown|overview|feedback)\b/i,
+  /\b(?:i\s+want|i\s+asked\s+for|i\s+ask\s+for|i(?:'d| would)?\s+like|wants|asked for|asks for|would like)\b.{0,80}\b(coaching\s+)?(read|take|answer|response|summary|breakdown|overview|feedback)\b.{0,80}\b(latest|recent|last|current|today|this week|this month|past|six[-\s]?month|\d+\s+(?:days|weeks|months|years))\b/i,
+  /\bnot just\b.{0,60}\b(latest|recent|last|cards?|session|workout)\b/i,
+  /\b(last|past)\s+(?:\d+\s+)?(?:days|weeks|months|years)\b.{0,80}\b(read|take|answer|response|summary|breakdown|overview|feedback)\b/i,
+  /\b(?:i\s+want|i\s+asked\s+for|i\s+ask\s+for|i(?:'d| would)?\s+like|wants|asked for|asks for|would like)\b.{0,80}\b(guidance|feedback|recommendation|what to do next|progress checks?|progress updates?|evidence explained|session highlights explained)\b/i,
+  /\b(?:i\s+want|i\s+asked\s+for|i\s+ask\s+for|i(?:'d| would)?\s+like|wants|asked for|asks for|would like)\b.{0,80}\b(brand[-\s]?new plan|plan from scratch|program draft|plan artifact|changeset)\b/i
+];
+
+const DURABLE_GOAL_PATTERNS = [
+  /\b(?:lose|gain|build|improve|increase|maintain|cut|bulk)\b.{0,80}\b(?:weight|muscle|strength|bench|squat|deadlift|press|pull[-\s]?up|fitness|conditioning|mobility|body fat|hypertrophy)\b/i,
+  /\b(?:weight|muscle|strength|bench|squat|deadlift|press|pull[-\s]?up|fitness|conditioning|mobility|body fat|hypertrophy)\b.{0,80}\b(?:goal|target|priority|focus)\b/i,
+  /\b(?:goal|target|priority|focus)\b.{0,80}\b(?:lose|gain|build|improve|increase|maintain|cut|bulk)\b/i,
+  /\b(?:bench|squat|deadlift|press|pull[-\s]?up|strength|muscle|weight)\b.{0,80}\bprogress\b/i,
+  /\bprioriti[sz]e\b.{0,80}\b(?:shoulder[-\s]?friendly|pressing|pulling|strength|hypertrophy|muscle|mobility)\b/i
+];
+
+const ASK_INTENT_ONLY_PATTERNS = [
+  /\b(?:what should i do next|what do i do next|what are my goals|what's my goal|explain this|check my progress|how am i progressing|what evidence matters|what matters here)\b/i,
+  /\b(?:recommendation|recommend|feedback|guidance|advice)\b.{0,60}\b(?:what to do next|next|now|today|this week|for this)\b/i
+];
+
+const FIRST_PERSON_DURABLE_SIGNAL_PATTERNS = [
+  /\bmy goal is\b/i,
+  /\bi want to\b.{0,100}\b(?:lose|gain|build|improve|increase|maintain|cut|bulk|avoid)\b/i,
+  /\bi(?:'d| would)? prefer\b/i,
+  /\bi want to avoid\b/i,
+  /\bi can only\b/i,
+  /\bi only have\b/i,
+  /\bwork sometimes cuts\b/i,
+  /\b(?:my|the)\s+(?:shoulder|knee|elbow|hip|back|wrist|ankle|neck)\s+(?:hurts|aches|is sore|is injured)\b/i,
+  /\bi can(?:['’]t|not)\b.{0,80}\bbecause\b/i,
+  /\bbe concise\b/i,
+  /\bdon(?:['’]t| not)\s+be\s+demeaning\b/i
+];
+
+const REMOVAL_INTENT_PATTERNS = [
+  /\b(?:remove|delete|clear)\s+(?:that|this|my)?\s*(?:goal|memory|fact|preference|constraint|injury|tone)\b/i,
+  /\bforget\s+(?:that|this|my)?\b/i,
+  /\bi don(?:['’]t| not)\s+want\b.{0,120}\bas\s+a\s+goal\s+anymore\b/i,
+  /\bthat(?:['’]s| is)\s+not\s+true\s+anymore\b/i,
+  /\bno\s+longer\s+(?:true|a goal|relevant)\b/i
+];
+
 export function normalizeCoachFactText(value) {
   return String(value ?? '').replace(/\s+/g, ' ').trim();
 }
@@ -57,9 +114,87 @@ export function coachFactPolicyViolation(candidate) {
   if (PROMPT_INJECTION_PATTERNS.some((pattern) => pattern.test(fact))) return 'prompt_injection';
   if (DERIVED_TRAINING_PATTERNS.some((pattern) => pattern.test(fact))) return 'derived_training_fact';
   if (EPHEMERAL_PATTERNS.some((pattern) => pattern.test(fact))) return 'ephemeral_fact';
+  if (EPHEMERAL_RESPONSE_REQUEST_PATTERNS.some((pattern) => pattern.test(fact))) return 'ephemeral_response_request';
+  if (kind === 'goal_signal' && !DURABLE_GOAL_PATTERNS.some((pattern) => pattern.test(fact))) return 'non_durable_goal_signal';
+  return null;
+}
+
+export function coachFactPersistenceDecision(candidate) {
+  const reason = coachFactPolicyViolation(candidate);
+  return { persist: !reason, reason };
+}
+
+export function coachFactRetrievalViolation(candidate) {
+  const reason = coachFactPolicyViolation(candidate);
+  if (reason) return reason;
   return null;
 }
 
+export function shouldAttemptCoachFactExtraction(currentUserText, { sourceSurface = 'ask' } = {}) {
+  const text = normalizeCoachFactText(currentUserText);
+  if (!text) return { shouldAttempt: false, skippedReason: 'empty_user_turn' };
+  if (detectCoachFactRemovalIntent(text).isRemovalIntent) {
+    return { shouldAttempt: false, skippedReason: 'memory_removal_request' };
+  }
+  if (EPHEMERAL_RESPONSE_REQUEST_PATTERNS.some((pattern) => pattern.test(text))) {
+    return { shouldAttempt: false, skippedReason: 'ephemeral_response_request' };
+  }
+  if (ASK_INTENT_ONLY_PATTERNS.some((pattern) => pattern.test(text))) {
+    return { shouldAttempt: false, skippedReason: 'ask_intent_only' };
+  }
+  if (!FIRST_PERSON_DURABLE_SIGNAL_PATTERNS.some((pattern) => pattern.test(text))) {
+    return { shouldAttempt: false, skippedReason: 'no_durable_first_person_signal' };
+  }
+  return { shouldAttempt: true, sourceSurface };
+}
+
+export function detectCoachFactRemovalIntent(currentUserText) {
+  const text = normalizeCoachFactText(currentUserText);
+  if (!text) return { isRemovalIntent: false, text: '' };
+  const isRemovalIntent = REMOVAL_INTENT_PATTERNS.some((pattern) => pattern.test(text));
+  const kindPreference = /\bgoal\b/i.test(text)
+    ? 'goal_signal'
+    : /\bconstraint\b/i.test(text)
+      ? 'constraint'
+      : /\binjur(?:y|ies)\b/i.test(text)
+        ? 'injury'
+        : /\btone|concise|demeaning|style\b/i.test(text)
+          ? 'tone'
+          : /\bprefer|preference\b/i.test(text)
+            ? 'preference'
+            : null;
+  return { isRemovalIntent, text, kindPreference };
+}
+
+export function coachFactRemovalMatches(currentUserText, facts, { limit = 3 } = {}) {
+  const intent = detectCoachFactRemovalIntent(currentUserText);
+  if (!intent.isRemovalIntent) return [];
+  const requestTokens = new Set(intent.text.toLowerCase().match(/[a-z0-9]{4,}/g) ?? []);
+  const stopTokens = new Set(['remove', 'delete', 'clear', 'forget', 'that', 'this', 'goal', 'memory', 'fact', 'anymore', 'longer', 'true', 'want']);
+  const usefulRequestTokens = [...requestTokens].filter((token) => !stopTokens.has(token));
+  const scored = [];
+  for (const row of Array.isArray(facts) ? facts : []) {
+    const kind = normalizeCoachFactKind(row?.kind);
+    const fact = normalizeCoachFactText(row?.fact);
+    const id = String(row?.id ?? '').trim();
+    if (!id || !fact || !isCoachFactKind(kind) || row?.supersededAt || row?.superseded_at) continue;
+    const factTokens = new Set(fact.toLowerCase().match(/[a-z0-9]{4,}/g) ?? []);
+    const overlap = usefulRequestTokens.filter((token) => factTokens.has(token)).length;
+    const quoted = [...String(intent.text).matchAll(/["“”']([^"“”']{3,80})["“”']/g)]
+      .some((match) => fact.toLowerCase().includes(String(match[1]).toLowerCase()));
+    const kindScore = intent.kindPreference && intent.kindPreference === kind ? 2 : 0;
+    const score = (quoted ? 10 : 0) + overlap + kindScore;
+    const hasContentTarget = usefulRequestTokens.length > 0 || /["“”']([^"“”']{3,80})["“”']/.test(intent.text);
+    if ((hasContentTarget && (quoted || overlap > 0)) || (!hasContentTarget && kindScore > 0)) {
+      scored.push({ row, score });
+    }
+  }
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .slice(0, Math.max(1, Math.min(Number(limit) || 3, 10)))
+    .map((item) => item.row);
+}
+
 export function normalizeCoachFactCandidate(candidate) {
   if (!candidate || typeof candidate !== 'object') return null;
   const normalized = {
@@ -74,6 +209,60 @@ export function normalizeCoachFactCandidate(candidate) {
   };
 }
 
+export function evaluateCoachFactCandidates(candidates, { limit = 3 } = {}) {
+  const proposed = Array.isArray(candidates) ? candidates : [];
+  const accepted = [];
+  const rejected = [];
+
+  for (const candidate of proposed) {
+    const normalized = {
+      kind: normalizeCoachFactKind(candidate?.kind),
+      fact: normalizeCoachFactText(candidate?.fact),
+      confidence: Number(candidate?.confidence ?? 0.7)
+    };
+    const reason = coachFactPolicyViolation(normalized);
+    if (reason) {
+      rejected.push({
+        kind: isCoachFactKind(normalized.kind) ? normalized.kind : 'unknown',
+        reason
+      });
+      continue;
+    }
+    accepted.push({
+      ...normalized,
+      confidence: Number.isFinite(normalized.confidence) ? Math.max(0, Math.min(1, normalized.confidence)) : 0.7
+    });
+  }
+
+  const facts = dedupeCoachFactCandidates(accepted, { limit });
+  const rejectionReasonCounts = rejected.reduce((counts, item) => {
+    counts[item.reason] = (counts[item.reason] ?? 0) + 1;
+    return counts;
+  }, {});
+  const acceptedKindCounts = facts.reduce((counts, item) => {
+    counts[item.kind] = (counts[item.kind] ?? 0) + 1;
+    return counts;
+  }, {});
+  const rejectedKindCounts = rejected.reduce((counts, item) => {
+    const kind = isCoachFactKind(item.kind) ? item.kind : 'unknown';
+    counts[kind] = (counts[kind] ?? 0) + 1;
+    return counts;
+  }, {});
+
+  return {
+    facts,
+    telemetry: {
+      proposedFactCount: proposed.length,
+      acceptedFactCount: facts.length,
+      rejectedFactCount: rejected.length,
+      acceptedKinds: acceptedKindCounts,
+      rejectedKinds: rejectedKindCounts,
+      rejectionReasons: rejectionReasonCounts,
+      rejectedFacts: rejected
+    }
+  };
+}
+
 export function coachFactConflictKey(candidate) {
   const kind = normalizeCoachFactKind(candidate?.kind);
   const fact = normalizeCoachFactText(candidate?.fact).toLowerCase();
@@ -111,3 +300,28 @@ export function dedupeCoachFactCandidates(candidates, { limit = 3 } = {}) {
     .sort((a, b) => b.confidence - a.confidence)
     .slice(0, limit);
 }
+
+export function coachFactsResponsePayload(facts) {
+  const rows = Array.isArray(facts) ? facts : [];
+  const grouped = Object.fromEntries(COACH_FACT_PRESENTATION.map((section) => [section.key, []]));
+  for (const fact of rows) {
+    const groupKey = COACH_FACT_GROUP_KEYS[fact?.kind];
+    if (groupKey) grouped[groupKey].push(fact);
+  }
+
+  return {
+    facts: rows,
+    grouped,
+    sections: COACH_FACT_PRESENTATION.map((section) => ({
+      key: section.key,
+      kind: section.kind,
+      title: section.title,
+      facts: grouped[section.key] ?? []
+    })),
+    availableKinds: COACH_FACT_PRESENTATION.map((section) => ({
+      kind: section.kind,
+      title: section.kindTitle,
+      sectionTitle: section.title
+    }))
+  };
+}