incremnt 0.8.0 → 0.8.2

package/src/ask-coach.js

@@ -399,6 +399,32 @@ function requestedActionForRoute(route, question, { isFollowUp = false, carriedP
   return byRoute[route] ?? 'answer_training_question';
 }
 
+export const ASK_RESPONSE_PROFILES = Object.freeze({
+  expansive: 'expansive',
+  defensive: 'defensive',
+  structured: 'structured'
+});
+
+function responseProfileForAskIntent(route, requestedAction, question) {
+  if (route === 'program_design' || requestedAction === 'draft_plan') return ASK_RESPONSE_PROFILES.structured;
+  const text = String(question ?? '').toLowerCase();
+  if (
+    requestedAction === 'recommend_action' ||
+    requestedAction === 'recommend_next_session' ||
+    requestedAction === 'explain_cause' ||
+    /\b(should|can i|safe|increase|decrease|deload|swap|change|adjust)\b/.test(text) ||
+    /\b(what should i do|do next|next session|up next)\b/.test(text) ||
+    /\b(did i hit|hit target|below target|missed?|failed?|why did i fail)\b/.test(text) ||
+    // Decision questions phrased without an imperative verb still want a crisp
+    // recommendation, not an expansive dashboard.
+    /\b(too heavy|too light|too much|too easy|ready to|time to|worth|good idea|enough|move up|add weight|bump up|push (?:harder|up)|stall(?:ing|ed)?|plateau(?:ing|ed)?)\b/.test(text) ||
+    /\bam i ready\b/.test(text)
+  ) {
+    return ASK_RESPONSE_PROFILES.defensive;
+  }
+  return ASK_RESPONSE_PROFILES.expansive;
+}
+
 function confidenceForIntent({ rawRoute, route, namedExercises, question, previousRoute, isFollowUp }) {
   let confidence = 0.72;
   if (route !== 'general') confidence += 0.1;
@@ -456,6 +482,8 @@ function classifyAskIntentWithPrevious(snapshot, question, { previousIntent = nu
     : current.namedExercises;
   const sessionLabel = current.sessionLabel ?? (carriedPreviousTopic ? previous?.sessionLabel ?? null : null);
   const sessionReference = current.sessionReference ?? (carriedPreviousTopic ? previous?.sessionReference ?? null : null);
+  const requestedAction = requestedActionForRoute(route, question, { isFollowUp, carriedPreviousTopic });
+  const responseProfile = responseProfileForAskIntent(route, requestedAction, question);
   return {
     route,
     effectiveRoute: route === 'exercise_progress' && namedExercises.length === 0 ? 'general' : route,
@@ -476,7 +504,8 @@ function classifyAskIntentWithPrevious(snapshot, question, { previousIntent = nu
       sessionReference
     },
     timeframe: since ? { since } : null,
-    requestedAction: requestedActionForRoute(route, question, { isFollowUp, carriedPreviousTopic }),
+    requestedAction,
+    responseProfile,
     isFollowUp,
     previousRoute: previous?.route ?? null,
     ambiguityFlags: ambiguityFlagsForIntent({
@@ -623,6 +652,10 @@ const ASK_ROUTE_REQUIRED_TOOLS = Object.freeze({
   program_design: ['get_recent_sessions', 'get_goal_status']
 });
 
+function requiredToolsForAskRoute(route) {
+  return ASK_ROUTE_REQUIRED_TOOLS[route] ?? ASK_ROUTE_REQUIRED_TOOLS.general;
+}
+
 function askObservationCheckPlan({ exclude = new Set(), route } = {}) {
   if (exclude.has('coach_observations')) return [];
   const checks = [
@@ -727,7 +760,7 @@ export function planAskEvidence(snapshot, question, {
   const since = intent.timeframe?.since ?? null;
   const effectiveRoute = route === 'exercise_progress' && namedExerciseItems.length === 0 ? 'general' : route;
   const fallbackRoute = effectiveRoute === route ? null : effectiveRoute;
-  const requiredTools = ASK_ROUTE_REQUIRED_TOOLS[effectiveRoute] ?? ASK_ROUTE_REQUIRED_TOOLS.general;
+  const requiredTools = requiredToolsForAskRoute(effectiveRoute);
   const observationChecks = askObservationCheckPlan({
     exclude,
     route: effectiveRoute
@@ -857,11 +890,17 @@ function buildIncrementScoreAskContext(snapshot, { exclude = new Set(), today =
     lines.push('Increment Score: no snapshots available yet.');
   } else {
     const delta = incrementScore.facts.dayOverDayDelta;
-    const trend = !Number.isFinite(delta) ? 'unknown' : delta > 0 ? 'up' : delta < 0 ? 'down' : 'flat';
-    lines.push(`Increment Score: ${Math.round(incrementScore.facts.score)}, day-over-day trend ${trend}.`);
+    const scoreParts = [`Increment Score: ${Math.round(incrementScore.facts.score)}`];
+    if (Number.isFinite(delta)) {
+      const trend = delta > 0 ? 'up' : delta < 0 ? 'down' : 'flat';
+      scoreParts.push(`day-over-day trend ${trend}`);
+    }
+    lines.push(`${scoreParts.join(', ')}.`);
     // Direction word, not a raw daily-score list the model can dump back verbatim.
+    // Only steer on the multi-day trend when every point shares the current
+    // formula version; a formula change makes "rising/falling" a cross-ruler lie.
     const recentScores = (incrementScore.facts.recentScores ?? []).filter((s) => typeof s === 'number');
-    if (recentScores.length > 1) {
+    if (incrementScore.facts.trendComparable && recentScores.length > 1) {
       const span = recentScores[0] - recentScores[recentScores.length - 1];
       const weekTrend = span > 2 ? 'rising' : span < -2 ? 'falling' : 'steady';
       lines.push(`Recent score trend (newest first): ${weekTrend}.`);
@@ -883,6 +922,12 @@ function formatRepDelta(delta) {
   return `${delta > 0 ? '+' : ''}${delta}`;
 }
 
+function setWorkUnits(set) {
+  const reps = Number(set?.reps ?? 0);
+  const weight = Number(set?.weight ?? 0);
+  return (weight > 0 ? weight : 1) * reps;
+}
+
 function formatComparableSetDelta(exercise) {
   const previous = exercise?.previousComparableSession;
   if (!previous || !Array.isArray(exercise?.sets) || !Array.isArray(previous.sets)) return null;
@@ -891,15 +936,46 @@ function formatComparableSetDelta(exercise) {
   const comparableCount = Math.min(currentSets.length, previousSets.length);
   if (comparableCount === 0) return null;
 
-  const sameLoad = currentSets.slice(0, comparableCount).every((set, index) => set.weight === previousSets[index].weight);
-  if (!sameLoad) return null;
-
-  const repDeltas = currentSets
-    .slice(0, comparableCount)
-    .map((set, index) => formatRepDelta(set.reps - previousSets[index].reps));
+  const currentOverlap = currentSets.slice(0, comparableCount);
+  const previousOverlap = previousSets.slice(0, comparableCount);
+  const sameLoad = currentOverlap.every((set, index) => Number(set.weight) === Number(previousOverlap[index].weight));
+  const repDeltas = currentOverlap.map((set, index) => formatRepDelta(Number(set.reps) - Number(previousOverlap[index].reps)));
   if (repDeltas.some((delta) => delta == null)) return null;
 
-  return `vs previous ${previous.label} on ${previous.date}: same load, reps ${repDeltas.join(', ')}`;
+  const currentTotalReps = currentSets.reduce((sum, set) => sum + Number(set.reps ?? 0), 0);
+  const previousTotalReps = previousSets.reduce((sum, set) => sum + Number(set.reps ?? 0), 0);
+  const currentTotalWork = currentSets.reduce((sum, set) => sum + setWorkUnits(set), 0);
+  const previousTotalWork = previousSets.reduce((sum, set) => sum + setWorkUnits(set), 0);
+  const topCurrent = currentSets[0] ?? {};
+  const topPrevious = previousSets[0] ?? {};
+  const topLoadDelta = Number(topCurrent.weight ?? 0) - Number(topPrevious.weight ?? 0);
+  const topRepDelta = Number(topCurrent.reps ?? 0) - Number(topPrevious.reps ?? 0);
+  const averageCurrentOverlap = currentOverlap.reduce((sum, set) => sum + Number(set.reps ?? 0), 0) / comparableCount;
+  const averagePreviousOverlap = previousOverlap.reduce((sum, set) => sum + Number(set.reps ?? 0), 0) / comparableCount;
+  const averageRepDelta = averageCurrentOverlap - averagePreviousOverlap;
+  // Only flag a regression when the session actually did LESS total work. Without
+  // this gate, adding a set (more total reps) or going heavier for slightly fewer
+  // reps per set — both textbook progression — tripped the average/top-rep
+  // branches and mislabeled a better session "regression".
+  const didLessTotalWork = currentTotalWork < previousTotalWork;
+  const regressionFlag = didLessTotalWork
+    && (averageRepDelta <= -2 || topRepDelta <= -3 || (topLoadDelta > 0 && topRepDelta <= -2));
+
+  const details = [];
+  if (sameLoad) {
+    details.push(`same load, reps ${repDeltas.join(', ')}`);
+  } else {
+    const loadDeltas = currentOverlap.map((set, index) => formatSignedDelta(Number(set.weight ?? 0) - Number(previousOverlap[index].weight ?? 0), 'kg'));
+    details.push(`load/reps by overlapping set ${loadDeltas.map((load, index) => `${load ?? '0.0kg'} and reps ${repDeltas[index]}`).join('; ')}`);
+  }
+  if (currentSets.length !== previousSets.length || currentTotalReps !== previousTotalReps) {
+    details.push(`total reps ${currentTotalReps} vs ${previousTotalReps}${currentSets.length !== previousSets.length ? ` across ${currentSets.length} vs ${previousSets.length} sets` : ''}`);
+  }
+  if (regressionFlag) {
+    details.push('regression flag: reps dropped sharply despite the load/set context');
+  }
+
+  return `vs previous ${previous.label} on ${previous.date}: ${details.join('; ')}`;
 }
 
 function appendUserNotesForSession(lines, session) {
@@ -1174,6 +1250,169 @@ function buildRecordsAskContext(snapshot, namedExercises, { exclude = new Set(),
   return { context: lines.join('\n'), sections: ['header', 'records'], tools: [recordsTool], provenance: [coachToolProvenance('records', recordsTool)] };
 }
 
+function appendIncrementScoreEvidence(lines, incrementScore) {
+  lines.push('');
+  lines.push('Increment Score evidence:');
+  if (incrementScore.facts?.score == null) {
+    lines.push('  No Increment Score snapshot is available.');
+    return;
+  }
+  const facts = incrementScore.facts;
+  const delta = facts.dayOverDayDelta;
+  const scoreParts = [`Current score: ${Math.round(facts.score)}/100`];
+  if (Number.isFinite(delta)) {
+    const trend = delta > 0 ? 'up' : delta < 0 ? 'down' : 'flat';
+    scoreParts.push(`day-over-day ${trend}`);
+  }
+  lines.push(`  ${scoreParts.join('; ')}.`);
+  if (facts.summaryText) lines.push(`  Summary: ${facts.summaryText}`);
+  if ((facts.topPositiveDrivers ?? []).length > 0) {
+    lines.push(`  Top positive drivers: ${facts.topPositiveDrivers.join('; ')}.`);
+  }
+  if ((facts.topNegativeDrivers ?? []).length > 0) {
+    lines.push(`  Top negative drivers: ${facts.topNegativeDrivers.join('; ')}.`);
+  }
+}
+
+function formatRecentPrDelta(pr) {
+  if (!pr || pr.priorBest == null) {
+    return ' (first logged record for this lift)';
+  }
+  const sign = pr.delta >= 0 ? '+' : '';
+  const priorDate = validDateOnlyString(pr.priorBest.date) ?? 'unknown date';
+  const kindLabel = pr.kind === 'load_pr'
+    ? 'load PR — heavier bar than the prior best'
+    : 'rep PR — more reps at the same or lighter bar than the prior best (load looks flat but strength rose)';
+  return ` (${sign}${pr.delta.toFixed(1)} kg vs prior best ${pr.priorBest.e1rm.toFixed(1)} kg from ${priorDate}; ${kindLabel})`;
+}
+
+function appendRecordEvidence(lines, records, { windowStart = null, today = new Date() } = {}) {
+  lines.push('');
+  lines.push('Best estimated 1RM records:');
+  if (records.rows.length === 0) {
+    lines.push('  No weighted completed sets found.');
+    return;
+  }
+  const todayIso = dateOnlyString(today);
+  for (const record of records.rows) {
+    const recordDate = validDateOnlyString(record.date);
+    const inWindow = windowStart && recordDate != null && recordDate >= windowStart && recordDate <= todayIso;
+    lines.push(`  ${inWindow ? '★ ' : ''}${record.name}: ${record.e1rm.toFixed(1)} kg (${recordDate ?? 'unknown date'})`);
+  }
+}
+
+function appendBodyWeightEvidence(lines, bodyWeight, exclude) {
+  lines.push('');
+  if (exclude.has('bodyWeight')) {
+    lines.push('Body weight sharing is disabled for AI Coach.');
+  } else if (bodyWeight.facts.latestBodyWeightKg != null) {
+    const source = bodyWeight.facts.latestBodyWeightDate
+      ? `latest reading ${bodyWeight.facts.latestBodyWeightDate}`
+      : 'profile';
+    lines.push(`Body weight: ${bodyWeight.facts.latestBodyWeightKg.toFixed(1)} kg (${source}).`);
+    if (bodyWeight.facts.trendKg != null) {
+      const trend = bodyWeight.facts.trendKg >= 0 ? `+${bodyWeight.facts.trendKg.toFixed(1)}` : bodyWeight.facts.trendKg.toFixed(1);
+      lines.push(`Body weight trend, last ${bodyWeight.facts.recentDays} days: ${trend} kg across ${bodyWeight.facts.readingCount} readings.`);
+    }
+  } else {
+    lines.push('No body weight is available in the exported profile or HealthKit body-mass readings.');
+  }
+}
+
+function appendGoalStatusEvidence(lines, goalStatus) {
+  if (goalStatus.rows.length === 0) return;
+  lines.push('');
+  lines.push('Goal status:');
+  for (const goal of goalStatus.rows) {
+    const progress = goal.progressPercent != null ? `${goal.progressPercent}%` : 'unknown progress';
+    lines.push(`  ${goal.exerciseName}: ${progress}`);
+  }
+}
+
+function appendExpansiveEvidenceContextBeforeExcludeNote(lines, snapshot, {
+  exclude = new Set(),
+  today = new Date(),
+  namedExercises = [],
+  existingSections = []
+} = {}) {
+  const sections = new Set(existingSections);
+  const note = buildExcludeNote(exclude);
+  const noteAtEnd = note && lines.at(-1) === note;
+  if (noteAtEnd) {
+    lines.pop();
+    if (lines.at(-1) === '') lines.pop();
+  }
+
+  const tools = [];
+  const provenance = [];
+  const addedSections = [];
+  const addTool = (section, tool) => {
+    tools.push(tool);
+    provenance.push(coachToolProvenance(section, tool));
+    addedSections.push(section);
+  };
+
+  if (!sections.has('increment_score')) {
+    const incrementScore = executeCoachReadTool(snapshot, 'get_increment_score', { historyDays: 21 });
+    appendIncrementScoreEvidence(lines, incrementScore);
+    addTool('increment_score', incrementScore);
+  }
+
+  if (!sections.has('weekly_volume')) {
+    const weeklyVolume = executeCoachReadTool(snapshot, 'get_weekly_volume', { today });
+    lines.push('');
+    lines.push(`This week strength volume: ${weeklyVolume.facts.currentWeekVolume} kg across ${weeklyVolume.facts.currentWeekSessionCount} session${weeklyVolume.facts.currentWeekSessionCount === 1 ? '' : 's'}.`);
+    lines.push(`Previous week strength volume: ${weeklyVolume.facts.previousWeekVolume} kg across ${weeklyVolume.facts.previousWeekSessionCount} session${weeklyVolume.facts.previousWeekSessionCount === 1 ? '' : 's'}.`);
+    if (weeklyVolume.facts.deltaPct != null) {
+      lines.push(`Week-over-week strength volume change: ${weeklyVolume.facts.deltaPct >= 0 ? '+' : ''}${weeklyVolume.facts.deltaPct}%.`);
+    }
+    addTool('weekly_volume', weeklyVolume);
+  }
+
+  if (!sections.has('records')) {
+    const records = executeCoachReadTool(snapshot, 'get_records', {
+      exercises: namedExercises,
+      limit: namedExercises.length > 0 ? Math.max(5, namedExercises.length) : 10,
+      today
+    });
+    appendRecordEvidence(lines, records, { today });
+    addTool('records', records);
+  }
+
+  if (!sections.has('body_weight')) {
+    const bodyWeight = executeCoachReadTool(snapshot, 'get_body_weight_snapshot', {
+      recentDays: 30,
+      exclude: [...exclude],
+      today
+    });
+    appendBodyWeightEvidence(lines, bodyWeight, exclude);
+    addTool('body_weight', bodyWeight);
+  }
+
+  if (!sections.has('readiness')) {
+    const readiness = executeCoachReadTool(snapshot, 'get_readiness_snapshot', {
+      recentDays: 14,
+      exclude: [...exclude],
+      today
+    });
+    appendReadinessSummary(lines, readiness);
+    addTool('readiness', readiness);
+  }
+
+  if (!sections.has('goal_status')) {
+    const goalStatus = executeCoachReadTool(snapshot, 'get_goal_status', { limit: 5 });
+    appendGoalStatusEvidence(lines, goalStatus);
+    addTool('goal_status', goalStatus);
+  }
+
+  if (noteAtEnd) {
+    lines.push('');
+    lines.push(note);
+  }
+
+  return { sections: addedSections, tools, provenance };
+}
+
 function rowMatchesSetHint(row, hint) {
   const exercise = (row?.exercises ?? []).find((candidate) => canonicalExerciseName(candidate.name) === hint.exerciseCanonical);
   if (!exercise) return false;
@@ -1428,9 +1667,17 @@ function buildProgressReviewAskContext(snapshot, { exclude = new Set(), since =
   // Records, flagging which were set inside the review window (recent PRs).
   if (records.rows.length > 0) {
     lines.push('');
+    const recentRecords = records.facts.recentRecords ?? [];
     if (recentRecordCount > 0) {
-      const names = recentRecordNames.join(', ');
-      lines.push(`Recent all-time estimated 1RM PR count in review window: ${recentRecordCount}. Mention this count explicitly in broad progress reviews. Exercises: ${names}.`);
+      lines.push(`Recent all-time estimated 1RM PR count in review window: ${recentRecordCount}. Mention this count explicitly in broad progress reviews.`);
+      if (recentRecords.length > 0) {
+        lines.push('Recent PRs (compared to the prior best, so a rep PR at the same bar weight is not mistaken for a stall):');
+        for (const pr of recentRecords) {
+          lines.push(`  ${pr.name}: ${pr.e1rm.toFixed(1)} kg e1RM on ${validDateOnlyString(pr.date) ?? 'unknown date'}${formatRecentPrDelta(pr)}.`);
+        }
+      } else {
+        lines.push(`Exercises: ${recentRecordNames.join(', ')}.`);
+      }
     }
     lines.push('Best estimated 1RM records (★ = set within review window):');
     for (const record of records.rows) {
@@ -1533,9 +1780,17 @@ function buildGeneralAskContext(snapshot, { exclude = new Set(), today = new Dat
   };
 }
 
-function askToolMetadata(tools = [], provenance = []) {
+function missingDataFlagsForRequiredTools(tools = [], requiredToolNames = []) {
+  const required = new Set(requiredToolNames ?? []);
+  const scopedTools = required.size > 0
+    ? tools.filter((tool) => required.has(tool.toolName))
+    : tools;
+  return uniqueArray(scopedTools.flatMap((tool) => tool.missingDataFlags ?? []));
+}
+
+function askToolMetadata(tools = [], provenance = [], { requiredTools = [] } = {}) {
   const sourceTimestamps = tools.map((tool) => tool.sourceTimestamp).filter(Boolean).sort();
-  const missingDataFlags = uniqueArray(tools.flatMap((tool) => tool.missingDataFlags ?? []));
+  const missingDataFlags = missingDataFlagsForRequiredTools(tools, requiredTools);
   const noteSourceIds = uniqueArray(tools.flatMap((tool) => tool.facts?.noteSourceIds ?? []));
   return {
     toolsUsed: tools.map((tool) => tool.toolName),
@@ -1583,7 +1838,7 @@ function contextBundleFromParts({
   sessionObservationComparisons = []
 }) {
   const evidenceUsed = evidenceUsedFromProvenance(provenance);
-  const missingDataFlags = uniqueArray(tools.flatMap((tool) => tool.missingDataFlags ?? []));
+  const missingDataFlags = missingDataFlagsForRequiredTools(tools, evidencePlan?.requiredTools ?? []);
   return {
     intent,
     evidencePlan,
@@ -1778,6 +2033,8 @@ export function sanitizeAskAnswerVerificationReceipt(value) {
     ...(Number.isFinite(value.retryCount) ? { retryCount: value.retryCount } : {}),
     ...(typeof value.repaired === 'boolean' ? { repaired: value.repaired } : {}),
     ...(typeof value.fallback === 'boolean' ? { fallback: value.fallback } : {}),
+    ...(typeof value.degraded === 'boolean' ? { degraded: value.degraded } : {}),
+    ...(Number.isFinite(value.redactedCount) ? { redactedCount: value.redactedCount } : {}),
     ...(Number.isFinite(value.blockingFailureCount) ? { blockingFailureCount: value.blockingFailureCount } : {}),
     ...(Number.isFinite(value.advisoryFailureCount) ? { advisoryFailureCount: value.advisoryFailureCount } : {}),
     ...(Array.isArray(value.failureKeys) ? { failureKeys } : {})
@@ -1830,6 +2087,7 @@ function appendCoachObservationsContextBeforeExcludeNote(lines, observations, ex
   const section = [
     '',
     'Coach observations (derived from training data, not user-stated facts).',
+    'These are durable longer-window patterns, not automatic verdicts about the current session.',
     'Each observation separates Facts (raw pattern in the data), Interpretation (what we infer),',
     'and Recommendation (suggested user action). Treat Facts as load-bearing; treat Interpretation',
     'as a hypothesis the user may contradict; Recommendation is a default, not a directive.'
@@ -1888,6 +2146,7 @@ function appendSessionObservationComparisonsBeforeExcludeNote(lines, comparisons
   lines.push('');
   lines.push('Session-to-observation evidence:');
   lines.push('Use this raw session evidence when reconciling the current workout against durable Coach observations.');
+  lines.push('Only call an observation a current-session finding when direction is not "not_comparable"; direction=not_comparable means frame it as a longer-running pattern only.');
   lines.push('Instruction: a single session can qualify a durable multi-week observation, but should not erase it unless the longer-window evidence changes.');
   for (const comparison of usable) {
     lines.push(`- observation-id=${comparison.observationId}; session-id=${comparison.sessionId ?? 'unknown'}; evidence=${comparison.evidenceType}; direction=${comparison.direction ?? 'unknown'}`);
@@ -2310,8 +2569,8 @@ export function askObservationFollowUpContext(snapshot, question, observation, {
   appendExcludeNote(lines, exclude);
   const includedFacts = rankedCoachFactsForAsk(snapshot, question, 'general', { facts: coachFacts });
   const includedCoachFactIds = appendCoachFactsContextBeforeExcludeNote(lines, includedFacts, exclude);
-  const toolMetadata = askToolMetadata(tools, provenance);
   const finalizedEvidencePlan = finalizeEvidencePlan(evidencePlan, tools);
+  const toolMetadata = askToolMetadata(tools, provenance, { requiredTools: finalizedEvidencePlan.requiredTools });
   const context = lines.join('\n');
   const includedSections = [
     'header',
@@ -2326,6 +2585,7 @@ export function askObservationFollowUpContext(snapshot, question, observation, {
   const intentMetadata = {
     route: 'coach_observation_followup',
     effectiveRoute: 'coach_observation_followup',
+    responseProfile: ASK_RESPONSE_PROFILES.structured,
     confidence: 0.86,
     entities: {
       exercises: exercises.map((exercise) => ({
@@ -2361,6 +2621,7 @@ export function askObservationFollowUpContext(snapshot, question, observation, {
       route: 'coach_observation_followup',
       effectiveRoute: 'coach_observation_followup',
       fallbackRoute: null,
+      responseProfile: ASK_RESPONSE_PROFILES.structured,
       intent: intentMetadata,
       namedExercises: exercises.map((exercise) => exercise.canonical),
       namedExerciseLabels: exercises.map((exercise) => exercise.displayName),
@@ -2427,6 +2688,7 @@ export function askMissingObservationFollowUpContext(snapshot, _question, reques
   const intentMetadata = {
     route: 'coach_observation_followup',
     effectiveRoute: 'coach_observation_followup_missing',
+    responseProfile: ASK_RESPONSE_PROFILES.structured,
     confidence: 0.5,
     entities: { exercises: [] },
     timeframe: null,
@@ -2452,6 +2714,7 @@ export function askMissingObservationFollowUpContext(snapshot, _question, reques
       route: 'coach_observation_followup',
       effectiveRoute: 'coach_observation_followup_missing',
       fallbackRoute: null,
+      responseProfile: ASK_RESPONSE_PROFILES.structured,
       intent: intentMetadata,
       namedExercises: [],
       namedExerciseLabels: [],
@@ -2475,12 +2738,19 @@ export function askMissingObservationFollowUpContext(snapshot, _question, reques
   };
 }
 
-export function askRoutedContext(snapshot, question, { exclude = new Set(), coachFacts = null, coachObservations = null, history = [], today = new Date() } = {}) {
+export function askRoutedContext(snapshot, question, { exclude = new Set(), coachFacts = null, coachObservations = null, history = [], today = new Date(), responseProfileOverride = null } = {}) {
   const contextSnapshot = Array.isArray(coachObservations)
     ? { ...snapshot, coachObservations }
     : snapshot;
   const evidencePlan = planAskEvidence(contextSnapshot, question, { exclude, history, today });
   const { route, effectiveRoute, fallbackRoute, namedExercises, namedExerciseLabels, sessionLabel = null, sessionReference = null, since = null } = evidencePlan;
+  // Surfaces that share this context builder but must stay terse (e.g. the weekly
+  // check-in, which runs under WEEKLY_CHECKIN_PROMPT) can force a profile so the
+  // expansive evidence merge and score headline do not bleed in under a
+  // tight-reply prompt.
+  const responseProfile = responseProfileOverride
+    ?? evidencePlan.intent?.responseProfile
+    ?? ASK_RESPONSE_PROFILES.expansive;
   const namedExerciseItems = namedExercises.map((canonical, index) => ({
     canonical,
     displayName: namedExerciseLabels[index] ?? canonical
@@ -2529,10 +2799,27 @@ export function askRoutedContext(snapshot, question, { exclude = new Set(), coac
   } else {
     built = buildGeneralAskContext(contextSnapshot, { exclude, today });
   }
+  const factLines = built.context.split('\n');
+  const expansiveEvidence = responseProfile === ASK_RESPONSE_PROFILES.expansive
+    ? appendExpansiveEvidenceContextBeforeExcludeNote(factLines, contextSnapshot, {
+        exclude,
+        today,
+        namedExercises: namedExerciseItems,
+        existingSections: built.sections
+      })
+    : { sections: [], tools: [], provenance: [] };
+  built = {
+    ...built,
+    context: factLines.join('\n'),
+    sections: [...built.sections, ...expansiveEvidence.sections],
+    tools: [...(built.tools ?? []), ...expansiveEvidence.tools],
+    provenance: [...(built.provenance ?? []), ...expansiveEvidence.provenance]
+  };
+
   const tools = [...(built.tools ?? [])];
   const provenance = [...(built.provenance ?? [])];
 
-  const factLines = built.context.split('\n');
+  factLines.splice(0, factLines.length, ...built.context.split('\n'));
   const includedFacts = rankedCoachFactsForAsk(snapshot, question, effectiveRoute, { facts: coachFacts });
   const includedCoachFactIds = appendCoachFactsContextBeforeExcludeNote(factLines, includedFacts, exclude);
   const shouldIncludeCoachObservations = !exclude.has('coach_observations');
@@ -2578,8 +2865,8 @@ export function askRoutedContext(snapshot, question, { exclude = new Set(), coac
       ...(sessionObservationComparisons.length > 0 ? ['session_observation_comparisons'] : [])
     ]
   };
-  const toolMetadata = askToolMetadata(tools, provenance);
   const finalizedEvidencePlan = finalizeEvidencePlan(evidencePlan, tools);
+  const toolMetadata = askToolMetadata(tools, provenance, { requiredTools: finalizedEvidencePlan.requiredTools });
   const intent = {
     ...evidencePlan.intent,
     effectiveRoute
@@ -2601,6 +2888,7 @@ export function askRoutedContext(snapshot, question, { exclude = new Set(), coac
       route,
       effectiveRoute,
       fallbackRoute,
+      responseProfile,
       intent,
       namedExercises,
       namedExerciseLabels,

package/src/format.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { commandSchema, writeCommandSchema } from './contract.js';
+import { agentCommandSchema, commandSchema, writeCommandSchema } from './contract.js';
 
 const shortMonths = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const shortDays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
@@ -869,6 +869,9 @@ export function formatHelp(opts = {}) {
     cmd('login --session-file <file>', 'Import session file'),
     cmd('logout', 'Clear session'),
     '',
+    header('AGENT TOKENS'),
+    ...agentCommandSchema.map((c) => cmd(c.usage ?? c.command, c.description)),
+    '',
     header('OTHER'),
     cmd('browse', 'Interactive Ink browser'),
     cmd('tui', 'Alias for browse'),