incremnt 0.5.0 → 0.6.0

package/README.md

@@ -67,6 +67,7 @@ incremnt login --session-file ~/Downloads/session.json
 | `health summary` / `health ai` | Health metrics and AI summary |
 | `training load` | ATL/CTL/TSB and workload context |
 | `ask history` / `ask show --id <id>` | Coach conversation history |
+| `increment-score current` | Latest Increment Score summary with components, drivers, trend, and data-quality flags |
 | `increment-score history` | Historical Increment Score snapshots |
 | `increment-score upload --file <file>` | Upload Increment Score snapshots |
 | `programs propose --file <file>` | Submit a program proposal |
@@ -121,7 +122,7 @@ incremnt login --session-file ~/Downloads/session.json
 
 ## MCP Server
 
-The package includes an [MCP](https://modelcontextprotocol.io) server that exposes the same read queries and program proposal commands as tools for AI assistants like Claude.
+The package includes an [MCP](https://modelcontextprotocol.io) server for AI assistants like Claude and Codex.
 
 Run `incremnt mcp install` to auto-register the server with Claude Desktop, Claude Code, and Codex CLI (see [Setup](#setup) above).
 
@@ -142,7 +143,12 @@ The MCP server uses the same auth session as the CLI — run `incremnt login` fi
 
 ### MCP tool surface
 
-The MCP server exposes the same read/write contract as the CLI command surface, including sessions, programs, cycles, goals, health, training load, ask history/show, Increment Score history/upload, program proposal and share workflows, plus typed coach read tools (e.g. `get_increment_score`).
+The MCP server exposes two tool families:
+
+- Command-shaped tools from the public CLI contract, including sessions, programs, cycles, goals, health, training load, ask history/show, `increment-score-current`, `increment-score-history`, `increment-score-upload`, program proposals, and program shares.
+- Typed coach read tools for agent-native context retrieval, including `get_increment_score`, `get_recent_sessions`, `get_exercise_history`, `get_next_session`, `get_readiness_snapshot`, `get_body_weight_snapshot`, `get_goal_status`, and `get_records`.
+
+`get_increment_score` returns the same privacy-safe score summary as `increment-score current`: score, snapshot timestamp, formula version, data tier, component scores, positive/negative drivers, day-over-day delta, recent trend, and data-quality flags. It does not expose raw HealthKit values.
 
 You can inspect the exact machine-readable contract at any time:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incremnt",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Command-line tool for querying your incremnt strength training data",
   "license": "MIT",
   "type": "module",

package/src/contract.js

@@ -1,4 +1,4 @@
-export const contractVersion = 10;
+export const contractVersion = 11;
 
 export const capabilities = {
   readOnly: false,
@@ -162,6 +162,14 @@ export const commandSchema = [
       { name: 'token', type: 'string', required: true, description: 'Program share token' }
     ]
   },
+  {
+    command: 'increment-score current',
+    id: 'increment-score-current',
+    description: 'Show the latest Increment Score snapshot summary',
+    options: [
+      { name: 'historyDays', type: 'number', required: false, description: 'Recent score history window (default 14, max 60)' }
+    ]
+  },
   {
     command: 'increment-score history',
     id: 'increment-score-history',

package/src/format.js

@@ -689,6 +689,50 @@ function formatIncrementScoreHistory(payload) {
   return lines.join('\n');
 }
 
+function formatIncrementScoreCurrent(payload) {
+  if (!payload?.available) {
+    return 'No Increment Score snapshots found.';
+  }
+
+  const lines = [
+    ` ${chalk.bold('INCREMENT SCORE')}${dimDot()}${chalk.bold(String(payload.score))}${dimDot()}${chalk.dim(payload.dataTier ?? '')}`,
+    ''
+  ];
+
+  if (payload.snapshotAt) lines.push(` Snapshot ${chalk.dim(formatShortDate(payload.snapshotAt))}`);
+  if (payload.formulaVersion) lines.push(` Formula  ${chalk.dim(payload.formulaVersion)}`);
+  if (payload.dayOverDayDelta != null) {
+    const sign = payload.dayOverDayDelta > 0 ? '+' : '';
+    lines.push(` Delta    ${chalk.dim(`${sign}${payload.dayOverDayDelta}`)}`);
+  }
+  if (lines.at(-1) !== '') lines.push('');
+
+  if (payload.components && typeof payload.components === 'object' && Object.keys(payload.components).length > 0) {
+    lines.push(` ${chalk.bold('Components')}`);
+    for (const [name, value] of Object.entries(payload.components)) {
+      lines.push(`   ${name.padEnd(12)} ${chalk.dim(String(value))}`);
+    }
+    lines.push('');
+  }
+
+  const drivers = (label, list) => {
+    if (!Array.isArray(list) || list.length === 0) return;
+    lines.push(` ${chalk.bold(label)}`);
+    for (const text of list.slice(0, 3)) lines.push(`   ${text}`);
+    lines.push('');
+  };
+  drivers('Top positive drivers', payload.topPositiveDrivers);
+  drivers('Top negative drivers', payload.topNegativeDrivers);
+
+  if (Array.isArray(payload.dataQualityNotes) && payload.dataQualityNotes.length > 0) {
+    lines.push(` ${chalk.bold('Data quality')}`);
+    for (const note of payload.dataQualityNotes) lines.push(`   ${note}`);
+  }
+
+  while (lines.at(-1) === '') lines.pop();
+  return lines.join('\n');
+}
+
 function formatIncrementScoreUpload(payload) {
   const inserted = payload?.inserted ?? payload?.count ?? 0;
   return ` Uploaded ${chalk.bold(String(inserted))} Increment Score snapshot${inserted === 1 ? '' : 's'}.`;
@@ -763,6 +807,7 @@ export function formatPretty(command, payload) {
     'programs-propose': formatProposalCreated,
     'programs-proposals': formatProposalsList,
     'proposal-dismiss': formatProposalDismissed,
+    'increment-score-current': formatIncrementScoreCurrent,
     'increment-score-history': formatIncrementScoreHistory,
     'increment-score-upload': formatIncrementScoreUpload
   }[command];

package/src/mcp.js

@@ -8,6 +8,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { commandSchema, writeCommands, writeCommandSchema } from './contract.js';
+import { listCoachReadTools } from './queries.js';
 import { readSessionState } from './state.js';
 import { createTransport } from './transport.js';
 
@@ -26,6 +27,32 @@ function commandShape(cmd) {
   return shape;
 }
 
+function coachToolShape(tool) {
+  const shape = {};
+  const props = tool.inputSchema?.properties ?? {};
+  const required = new Set(tool.inputSchema?.required ?? []);
+
+  for (const [name, schema] of Object.entries(props)) {
+    let field;
+    if (schema.type === 'integer' || schema.type === 'number') {
+      field = z.number();
+    } else if (schema.type === 'boolean') {
+      field = z.boolean();
+    } else if (schema.type === 'array') {
+      field = z.array(z.any());
+    } else if (schema.type === 'object') {
+      field = z.record(z.string(), z.any());
+    } else {
+      field = z.string();
+    }
+    if (!required.has(name)) field = field.optional();
+    if (schema.description) field = field.describe(schema.description);
+    shape[name] = field;
+  }
+
+  return shape;
+}
+
 export function registerMcpTools(server, {
   readSessionStateFn = readSessionState,
   createTransportFn = createTransport
@@ -68,6 +95,41 @@ export function registerMcpTools(server, {
     });
   }
 
+  for (const tool of listCoachReadTools()) {
+    server.tool(tool.name, tool.description, coachToolShape(tool), async (args) => {
+      try {
+        const sessionState = await readSessionStateFn();
+        const transport = await createTransportFn({}, sessionState);
+
+        if (transport.expired) {
+          return {
+            content: [{ type: 'text', text: 'Session expired. Run `incremnt login` to re-authenticate.' }],
+            isError: true
+          };
+        }
+
+        const result = await transport.executeCoachReadTool(tool.name, args);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+
+        if (error && error.code === 'SNAPSHOT_NOT_FOUND') {
+          return {
+            content: [{ type: 'text', text: 'Not logged in. Run `incremnt login` first.' }],
+            isError: true
+          };
+        }
+
+        return {
+          content: [{ type: 'text', text: message }],
+          isError: true
+        };
+      }
+    });
+  }
+
   return server;
 }
 
@@ -88,6 +150,11 @@ export function createSandboxServer() {
       sandbox: true,
       ok: true
     }),
+    executeCoachReadTool: async (toolName) => ({
+      toolName,
+      sandbox: true,
+      ok: true
+    }),
     executeWriteCommand: async (commandId) => ({
       commandId,
       sandbox: true,

package/src/openrouter.js

@@ -24,7 +24,7 @@ const TRACE_DETAIL_METADATA = 'metadata';
 const TRACE_DETAIL_RAW_INTERNAL = 'raw_internal';
 
 export const AI_PROMPT_VERSIONS = Object.freeze({
-  workout: 'workout_v2026_04_24_2',
+  workout: 'workout_v2026_05_06_1',
   cycle: 'cycle_v2026_04_18_1',
   vitals: 'vitals_v2026_04_16_1',
   checkpoint: 'checkpoint_v2026_04_16_1',
@@ -892,7 +892,7 @@ The app already shows PRs, total volume, effort score, exercise breakdown, and p
 Rules:
 - No bullet points, no questions.
 - Be specific — use exact exercise names from the session data. Do not shorten or generalize.
-- Only mention exercises that appear in the current session, the next session list, or the recorded PR list. Never reference skipped or absent exercises by name.
+- Only mention exercises that appear in the current session, the next session list, the recorded PR list, or the plan comparison block. You may name a skipped exercise from plan comparison if it adds insight (e.g. context for the day's shape), but at most one such mention, and never speculate on why it was skipped unless the context states a reason.
 - Do not summarize PRs with a count in workout notes. Name the specific lift or lifts instead.
 - Never use the phrase "rep PR" in a workout note.
 - Do not state a percentage change unless the exact percentage is directly supported by the comparison block.

package/src/queries.js

@@ -1,6 +1,7 @@
 import { coachFactPolicyViolation } from './coach-facts.js';
 import { exerciseAliasMapping } from './exercise-aliases.js';
 import { programPhaseWindowContext, resolveProgramPhase } from './program-phase-resolver.js';
+import { enrichScoreSnapshots } from './score-context.js';
 
 function completionDateForSession(session) {
   return session.completedAt ?? session.summary?.date ?? session.date;
@@ -2883,53 +2884,150 @@ export function getRecords(snapshot, { exercises = [], limit = 15 } = {}) {
   });
 }
 
-export function getIncrementScore(snapshot, { historyDays = 14 } = {}) {
-  const raw = snapshot?.incrementScore;
+function scoreComponentNumber(value) {
+  const num = typeof value === 'number' ? value : value?.score;
+  return typeof num === 'number' && Number.isFinite(num) ? num : null;
+}
+
+function scoreDriverLabels(list, limit = 5) {
+  if (!Array.isArray(list)) return [];
+  return list.slice(0, limit).map((d) => d?.label ?? d?.message ?? d?.id ?? d?.driver).filter(Boolean);
+}
+
+function normalizeScoreHistory(raw) {
   const history = Array.isArray(raw?.history) ? raw.history : Array.isArray(raw) ? raw : [];
   const latest = raw?.latest ?? history[0] ?? null;
+  const first = history[0] ?? null;
+  const sameFirst = latest && first && (
+    (latest.snapshotAt && first.snapshotAt && latest.snapshotAt === first.snapshotAt) ||
+    (latest === first)
+  );
+  const mergedHistory = latest && sameFirst
+    ? [{ ...first, ...latest }, ...history.slice(1)]
+    : latest
+      ? [latest, ...history]
+      : history;
+  return enrichScoreSnapshots(mergedHistory);
+}
+
+export function incrementScoreSummary(snapshot, { historyDays = 14 } = {}) {
+  const raw = snapshot?.incrementScore;
+  const history = normalizeScoreHistory(raw);
+  const latest = history[0] ?? null;
+  const boundedHistoryDays = boundedInteger(historyDays, { defaultValue: 14, min: 1, max: 60 });
 
   if (!latest || typeof latest.score !== 'number') {
-    return coachToolResult('get_increment_score', { historyDays }, {
-      facts: {},
+    return {
+      available: false,
+      score: null,
+      snapshotAt: null,
+      formulaVersion: null,
+      dataTier: null,
+      components: {},
+      topPositiveDrivers: [],
+      topNegativeDrivers: [],
+      dayOverDayDelta: null,
+      recentTrend: [],
+      dataQualityNotes: ['No Increment Score snapshots found.'],
       missingDataFlags: ['no_increment_score']
-    });
+    };
   }
 
   const components = {};
   if (latest.components && typeof latest.components === 'object') {
     for (const [name, value] of Object.entries(latest.components)) {
-      const num = typeof value === 'number' ? value : value?.score;
-      if (typeof num === 'number') components[name] = num;
+      const num = scoreComponentNumber(value);
+      if (num != null) components[name] = num;
     }
   }
 
-  const trimmedHistory = history.slice(0, Math.min(Math.max(Number(historyDays) || 14, 1), 60));
-  const recentScores = trimmedHistory
-    .map((entry) => (typeof entry?.score === 'number' ? entry.score : null))
-    .filter((s) => s != null);
-
+  const trimmedHistory = history.slice(0, boundedHistoryDays);
   const prior = trimmedHistory[1];
   const dayOverDayDelta = (typeof prior?.score === 'number')
     ? latest.score - prior.score
     : null;
 
-  const driverLabels = (list) => {
-    if (!Array.isArray(list)) return [];
-    return list.slice(0, 5).map((d) => d?.label ?? d?.id ?? d?.driver).filter(Boolean);
+  const missingDataFlags = [];
+  const dataQualityNotes = [];
+  if (Object.keys(components).length === 0) {
+    missingDataFlags.push('no_components');
+    dataQualityNotes.push('Component scores are missing for this snapshot.');
+  }
+  if (!latest.dataTier) {
+    missingDataFlags.push('no_data_tier');
+    dataQualityNotes.push('Data tier is missing for this snapshot.');
+  }
+  if (!latest.formulaVersion) {
+    missingDataFlags.push('no_formula_version');
+    dataQualityNotes.push('Formula version is missing for this snapshot.');
+  }
+
+  const recentTrend = trimmedHistory
+    .filter((entry) => typeof entry?.score === 'number')
+    .map((entry) => ({
+      snapshotAt: entry.snapshotAt ?? null,
+      score: entry.score,
+      dataTier: entry.dataTier ?? null,
+      formulaVersion: entry.formulaVersion ?? null
+    }));
+
+  return {
+    available: true,
+    score: latest.score,
+    snapshotAt: latest.snapshotAt ?? null,
+    formulaVersion: latest.formulaVersion ?? null,
+    dataTier: latest.dataTier ?? null,
+    components,
+    topPositiveDrivers: scoreDriverLabels(latest.topPositiveDrivers),
+    topNegativeDrivers: scoreDriverLabels(latest.topNegativeDrivers),
+    dayOverDayDelta,
+    recentTrend,
+    dataQualityNotes,
+    missingDataFlags,
+    scoreBand: latest.scoreBand ?? null,
+    summaryText: latest.summaryText ?? null
   };
+}
+
+export function incrementScoreCurrent(snapshot, options = {}) {
+  return incrementScoreSummary(snapshot, options);
+}
+
+export function incrementScoreHistory(snapshot, options = {}) {
+  const raw = snapshot?.incrementScore;
+  const history = normalizeScoreHistory(raw);
+  const limit = boundedInteger(options.limit, { defaultValue: 200, min: 1, max: 1000 });
+  const from = options.from ? new Date(options.from) : null;
+  const to = options.to ? new Date(options.to) : null;
+  const filtered = history.filter((entry) => {
+    if (!entry?.snapshotAt) return true;
+    const date = new Date(entry.snapshotAt);
+    if (Number.isNaN(date.getTime())) return true;
+    if (from && !Number.isNaN(from.getTime()) && date < from) return false;
+    if (to && !Number.isNaN(to.getTime()) && date > to) return false;
+    return true;
+  });
+
+  return { snapshots: filtered.slice(0, limit) };
+}
+
+export function getIncrementScore(snapshot, { historyDays = 14 } = {}) {
+  const summary = incrementScoreSummary(snapshot, { historyDays });
+
+  if (!summary.available) {
+    return coachToolResult('get_increment_score', { historyDays }, {
+      facts: {},
+      missingDataFlags: summary.missingDataFlags
+    });
+  }
 
   return coachToolResult('get_increment_score', { historyDays }, {
     facts: {
-      score: latest.score,
-      dataTier: latest.dataTier ?? null,
-      components,
-      topPositiveDrivers: driverLabels(latest.topPositiveDrivers),
-      topNegativeDrivers: driverLabels(latest.topNegativeDrivers),
-      dayOverDayDelta,
-      recentScores
+      ...summary,
+      recentScores: summary.recentTrend.map((entry) => entry.score)
     },
-    sourceTimestamp: latest.snapshotAt ?? null,
-    missingDataFlags: Object.keys(components).length === 0 ? ['no_components'] : []
+    sourceTimestamp: summary.snapshotAt,
+    missingDataFlags: summary.missingDataFlags
   });
 }
 
@@ -4308,6 +4406,14 @@ export function executeReadCommand(snapshot, normalizedCommand, options = {}) {
     return { ok: true, payload: trainingLoad(snapshot) };
   }
 
+  if (normalizedCommand === 'increment-score-current') {
+    return { ok: true, payload: incrementScoreCurrent(snapshot, options) };
+  }
+
+  if (normalizedCommand === 'increment-score-history') {
+    return { ok: true, payload: incrementScoreHistory(snapshot, options) };
+  }
+
   if (normalizedCommand === 'ask-history') {
     const conversations = Array.isArray(snapshot.askConversations)
       ? snapshot.askConversations

package/src/remote.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import { readSnapshot } from './local.js';
-import { executeReadCommand } from './queries.js';
+import { executeCoachReadTool as executeLocalCoachReadTool, executeReadCommand } from './queries.js';
 import { resolveServiceUrl } from './service-url.js';
 
 function notImplementedError() {
@@ -41,6 +41,7 @@ const remoteCommandHandlers = {
   'ask-history': executeRemoteRead,
   'ask-show': executeRemoteRead,
   'program-share-fetch': executeRemoteRead,
+  'increment-score-current': executeRemoteRead,
   'increment-score-history': executeRemoteRead
 };
 
@@ -162,6 +163,11 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
       return resolveServiceUrl(baseUrl, `/cli/ask/history/${options.id}`);
     case 'program-share-fetch':
       return resolveServiceUrl(baseUrl, `/program-share/${options.token}`);
+    case 'increment-score-current': {
+      const url = resolveServiceUrl(baseUrl, '/cli/increment-score/current');
+      if (options.historyDays) url.searchParams.set('historyDays', options.historyDays);
+      return url;
+    }
     case 'increment-score-history': {
       const url = resolveServiceUrl(baseUrl, '/mobile/score-snapshots');
       if (options.from) url.searchParams.set('from', options.from);
@@ -198,6 +204,40 @@ function resourceNotFoundMessage(normalizedCommand, options) {
   return 'Requested resource was not found.';
 }
 
+async function executeRemoteCoachReadTool(toolName, input, sessionState) {
+  const baseUrl = sessionState.session?.transport?.baseUrl;
+  if (baseUrl) {
+    const endpoint = resolveServiceUrl(baseUrl, `/cli/coach-tools/${encodeURIComponent(toolName)}`);
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(input ?? {})
+    });
+
+    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 404) {
+      const error = new Error(`Unknown coach read tool: ${toolName}`);
+      error.code = 'REMOTE_NOT_FOUND';
+      throw error;
+    }
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error from incremnt sync service (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    return response.json();
+  }
+
+  const fixturePath = sessionState.session?.transport?.fixturePath;
+  if (!fixturePath) throw notImplementedError();
+  const snapshot = await readSnapshot(fixturePath);
+  return executeLocalCoachReadTool(snapshot, toolName, input);
+}
+
 const remoteWriteCommandHandlers = {
   'programs-propose': async (options, sessionState) => {
     const baseUrl = sessionState.session?.transport?.baseUrl;
@@ -453,6 +493,13 @@ export function createRemoteTransport(sessionState, transportOptions = {}) {
 
       return handler(options, sessionState, normalizedCommand);
     },
+    async executeCoachReadTool(toolName, input = {}) {
+      if (transportOptions.expired) {
+        throw expiredSessionError();
+      }
+
+      return executeRemoteCoachReadTool(toolName, input, sessionState);
+    },
     async executeWriteCommand(normalizedCommand, options = {}) {
       if (transportOptions.expired) {
         throw expiredSessionError();

package/src/score-context.js

@@ -0,0 +1,182 @@
+// Derived context for INCREMNT Score snapshots.
+//
+// These fields are computed at response time from existing snapshot data.
+// They are NOT persisted — pure projections of (current snapshot, previous
+// snapshot) into agent-friendly explanatory shape. See GitHub issue #498.
+
+// Score bands. Inclusive lower bound, exclusive upper bound (except 'peak').
+//   0..40   weak
+//   40..60  developing
+//   60..75  solid
+//   75..90  strong
+//   90..100 peak
+export const SCORE_BANDS = [
+  { name: 'weak', min: 0, max: 40 },
+  { name: 'developing', min: 40, max: 60 },
+  { name: 'solid', min: 60, max: 75 },
+  { name: 'strong', min: 75, max: 90 },
+  { name: 'peak', min: 90, max: 101 }
+];
+
+export function computeScoreBand(score) {
+  if (typeof score !== 'number' || !Number.isFinite(score)) return null;
+  for (const band of SCORE_BANDS) {
+    if (score >= band.min && score < band.max) return band.name;
+  }
+  return null;
+}
+
+// Component-keyed action templates surfaced as `recommendedNextActions` for
+// each top-2 negative driver. Keep these short, imperative, single-line.
+const COMPONENT_ACTIONS = {
+  coverage: 'Add the missing muscle groups to your next session to close coverage gaps.',
+  recovery: 'Prioritise sleep and an easier session to let recovery rebound.',
+  stimulus: 'Push closer to productive weekly volume on your lagging muscle groups.',
+  execution: 'Hit your planned sets and reps with cleaner technique next session.',
+  progression: 'Add a small load or rep increase on your main lifts next session.'
+};
+
+const GENERIC_ACTION = 'Address this driver in your next session to lift the score.';
+
+function actionForDriver(driver) {
+  if (!driver || typeof driver !== 'object') return GENERIC_ACTION;
+  const component = typeof driver.component === 'string' ? driver.component : null;
+  if (component && COMPONENT_ACTIONS[component]) {
+    return COMPONENT_ACTIONS[component];
+  }
+  return GENERIC_ACTION;
+}
+
+function driverDisplayMessage(driver) {
+  if (!driver || typeof driver !== 'object') return null;
+  if (typeof driver.message === 'string' && driver.message.trim()) return driver.message;
+  if (typeof driver.label === 'string' && driver.label.trim()) return driver.label;
+  return null;
+}
+
+export function computeRecommendedNextActions(topNegativeDrivers) {
+  if (!Array.isArray(topNegativeDrivers) || topNegativeDrivers.length === 0) return [];
+  return topNegativeDrivers.slice(0, 2).map((driver) => ({
+    component: typeof driver?.component === 'string' ? driver.component : null,
+    driverMessage: driverDisplayMessage(driver),
+    action: actionForDriver(driver)
+  }));
+}
+
+// Top-2 component movers (by absolute change) between current and previous
+// snapshot. Keys present in either side are considered; missing values
+// treated as 0.
+export function computeDeltaDrivers(currentComponents, previousComponents) {
+  if (
+    !currentComponents || typeof currentComponents !== 'object' ||
+    !previousComponents || typeof previousComponents !== 'object'
+  ) {
+    return [];
+  }
+  const keys = new Set([
+    ...Object.keys(currentComponents),
+    ...Object.keys(previousComponents)
+  ]);
+  const moves = [];
+  for (const key of keys) {
+    const cur = Number(currentComponents[key]);
+    const prev = Number(previousComponents[key]);
+    if (!Number.isFinite(cur) && !Number.isFinite(prev)) continue;
+    const c = Number.isFinite(cur) ? cur : 0;
+    const p = Number.isFinite(prev) ? prev : 0;
+    const delta = c - p;
+    if (delta === 0) continue;
+    moves.push({
+      component: key,
+      previousValue: p,
+      currentValue: c,
+      delta: Number(delta.toFixed(2))
+    });
+  }
+  moves.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+  return moves.slice(0, 2);
+}
+
+function formatDelta(delta) {
+  if (delta === null || delta === undefined) return null;
+  if (delta === 0) return 'flat';
+  return delta > 0 ? `up ${delta}` : `down ${Math.abs(delta)}`;
+}
+
+export function computeSummaryText(enriched) {
+  if (!enriched || typeof enriched.score !== 'number') return null;
+  const parts = [];
+  const bandLabel = enriched.scoreBand ? ` (${enriched.scoreBand})` : '';
+  parts.push(`INCREMNT Score ${enriched.score}${bandLabel}.`);
+
+  if (typeof enriched.previousScore === 'number') {
+    const trend = formatDelta(enriched.delta);
+    if (enriched.comparisonSafe) {
+      parts.push(`${trend === 'flat' ? 'Essentially flat' : `Trend ${trend}`} vs previous ${enriched.previousScore}.`);
+    } else {
+      parts.push(`Previous ${enriched.previousScore} (formula version differs or is unavailable, comparison unsafe).`);
+    }
+  } else {
+    parts.push('No prior snapshot for comparison.');
+  }
+
+  const topNeg = Array.isArray(enriched.topNegativeDrivers) ? enriched.topNegativeDrivers[0] : null;
+  const topNegMessage = driverDisplayMessage(topNeg);
+  if (topNegMessage) {
+    parts.push(`Top drag: ${topNegMessage}.`);
+  }
+
+  const firstAction = Array.isArray(enriched.recommendedNextActions) ? enriched.recommendedNextActions[0] : null;
+  if (firstAction && typeof firstAction.action === 'string') {
+    parts.push(`Next: ${firstAction.action}`);
+  }
+
+  return parts.join(' ');
+}
+
+// Enrich an array of snapshots (newest first, as returned by listScoreSnapshots).
+// Adds derived fields to each snapshot in-place via a shallow copy. Existing
+// fields are preserved; only new fields are added.
+export function enrichScoreSnapshots(snapshots) {
+  if (!Array.isArray(snapshots) || snapshots.length === 0) return [];
+  return snapshots.map((snapshot, index) => {
+    const previous = snapshots[index + 1] ?? null;
+    return enrichScoreSnapshot(snapshot, previous);
+  });
+}
+
+export function enrichScoreSnapshot(current, previous) {
+  if (!current || typeof current !== 'object') return current;
+
+  const previousScore = previous && typeof previous.score === 'number' ? previous.score : null;
+  const delta = previousScore !== null && typeof current.score === 'number'
+    ? current.score - previousScore
+    : null;
+
+  const comparisonSafe = !!(
+    previous &&
+    typeof previous.score === 'number' &&
+    typeof current.formulaVersion === 'string' &&
+    typeof previous.formulaVersion === 'string' &&
+    current.formulaVersion === previous.formulaVersion
+  );
+
+  const deltaDrivers = comparisonSafe
+    ? computeDeltaDrivers(current.components, previous.components)
+    : [];
+
+  const scoreBand = computeScoreBand(current.score);
+  const recommendedNextActions = computeRecommendedNextActions(current.topNegativeDrivers);
+
+  const enriched = {
+    ...current,
+    previousScore,
+    delta,
+    comparisonSafe,
+    deltaDrivers,
+    scoreBand,
+    recommendedNextActions
+  };
+  enriched.summaryText = computeSummaryText(enriched);
+  return enriched;
+}

package/src/summary-evals.js

@@ -18,6 +18,7 @@ import {
   generateVitalsSummary,
   generateWorkoutCoachingSummary
 } from './openrouter.js';
+import { computeScoreBand } from './score-context.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -94,6 +95,8 @@ export function buildSummaryEvalContext(snapshot, testCase) {
         routedMetadata: routed?.metadata ?? null
       };
     }
+    case 'scoreCommentary':
+      return buildScoreCommentaryContext(snapshot, testCase);
     default:
       throw new Error(`Unsupported summary eval surface: ${testCase.surface}`);
   }
@@ -121,6 +124,8 @@ export async function generateSummaryEvalOutputWithMetadata(testCase, context, s
 
   let result;
   switch (testCase.surface) {
+    case 'scoreCommentary':
+      return { output: testCase.output, metadata: {} };
     case 'workout':
       result = await generateWorkoutCoachingSummary(context, { apiKey });
       break;
@@ -166,6 +171,77 @@ function normalizeText(value) {
   return String(value ?? '').trim();
 }
 
+function parseJsonOutput(output) {
+  const normalized = normalizeText(output);
+  if (!normalized) return null;
+  try {
+    return JSON.parse(normalized);
+  } catch {
+    return null;
+  }
+}
+
+function scoreCommentaryPayload(output) {
+  const parsed = parseJsonOutput(output);
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    return parsed;
+  }
+  return { summaryText: normalizeText(output) };
+}
+
+function scoreCommentaryText(output) {
+  const payload = scoreCommentaryPayload(output);
+  const pieces = [
+    payload.headline,
+    payload.subhead,
+    payload.summaryText,
+    payload.scoreBand
+  ];
+  const actions = Array.isArray(payload.recommendedNextActions) ? payload.recommendedNextActions : [];
+  for (const action of actions) {
+    pieces.push(action?.driverMessage, action?.action);
+  }
+  const deltaDrivers = Array.isArray(payload.deltaDrivers) ? payload.deltaDrivers : [];
+  for (const driver of deltaDrivers) {
+    pieces.push(driver?.component);
+  }
+  return pieces.filter(Boolean).join(' ');
+}
+
+function scoreHistoryFromSnapshot(snapshot) {
+  const raw = snapshot?.incrementScore;
+  if (Array.isArray(raw)) return raw;
+
+  const history = Array.isArray(raw?.history) ? raw.history : [];
+  const latest = raw?.latest;
+  if (!latest) return history;
+
+  return [
+    latest,
+    ...history.filter((entry) => {
+      if (!entry) return false;
+      if (latest?.id != null && entry?.id != null) return entry.id !== latest.id;
+      if (latest?.snapshotAt != null && entry?.snapshotAt != null) {
+        return entry.snapshotAt !== latest.snapshotAt;
+      }
+      return entry !== latest;
+    })
+  ];
+}
+
+function buildScoreCommentaryContext(snapshot, testCase) {
+  const history = scoreHistoryFromSnapshot(snapshot);
+  const selector = testCase.selector ?? {};
+  if (selector.snapshotId) {
+    return history.find((entry) => entry.id === selector.snapshotId) ?? null;
+  }
+  if (selector.snapshotAt) {
+    return history.find((entry) => entry.snapshotAt === selector.snapshotAt) ?? null;
+  }
+  const index = Number.isInteger(selector.index) ? selector.index : 0;
+  return history[index] ?? null;
+}
+
 function paragraphCount(text) {
   return normalizeText(text)
     .split(/\n\s*\n/)
@@ -279,6 +355,9 @@ function collectAllowedExerciseNames(surface, context) {
     for (const pr of context.repPrs ?? []) {
       if (pr.exerciseName) names.add(pr.exerciseName);
     }
+    for (const sc of context.planComparison?.setsComparison ?? []) {
+      if (sc.exercise) names.add(sc.exercise);
+    }
   }
 
   if (surface === 'cycle' && context && typeof context === 'object') {
@@ -307,6 +386,16 @@ function collectAllowedExerciseNames(surface, context) {
     }
   }
 
+  if (surface === 'scoreCommentary' && context && typeof context === 'object') {
+    for (const driver of [
+      ...(context.topPositiveDrivers ?? []),
+      ...(context.topNegativeDrivers ?? [])
+    ]) {
+      if (driver?.relatedExerciseName) names.add(driver.relatedExerciseName);
+      if (driver?.exerciseName) names.add(driver.exerciseName);
+    }
+  }
+
   return [...names];
 }
 
@@ -340,6 +429,7 @@ function evaluateExerciseMentions(output, snapshot, context, surface, testCase)
     };
   }
 
+  const outputText = surface === 'scoreCommentary' ? scoreCommentaryText(output) : output;
   const isStored = testCase.source === 'stored';
   const allowed = new Set();
   for (const name of [
@@ -352,7 +442,7 @@ function evaluateExerciseMentions(output, snapshot, context, surface, testCase)
     }
   }
   const allNames = collectAllExerciseNames(snapshot);
-  const normalizedOutput = normalizeExerciseName(output);
+  const normalizedOutput = normalizeExerciseName(outputText);
   const mentions = [];
 
   for (const exerciseName of allNames) {
@@ -453,7 +543,9 @@ function evaluateNoInsight(output, testCase) {
 }
 
 function evaluateShape(output, testCase) {
-  const normalized = normalizeText(output);
+  const normalized = testCase.surface === 'scoreCommentary'
+    ? scoreCommentaryText(output)
+    : normalizeText(output);
   if (normalized === 'NO_INSIGHT') {
     return {
       key: 'shape',
@@ -462,8 +554,8 @@ function evaluateShape(output, testCase) {
     };
   }
 
-  const sentences = sentenceCount(output);
-  const paragraphs = paragraphCount(output);
+  const sentences = sentenceCount(normalized);
+  const paragraphs = paragraphCount(normalized);
   const isStored = testCase.source === 'stored';
   let passed = true;
   const reasons = [];
@@ -527,6 +619,12 @@ function evaluateShape(output, testCase) {
         reasons.push(`Ask-coach answers must be 1-12 sentences, got ${sentences}.`);
       }
       break;
+    case 'scoreCommentary':
+      if (sentences < 1 || sentences > 8) {
+        passed = false;
+        reasons.push(`Score commentary must be 1-8 sentences, got ${sentences}.`);
+      }
+      break;
     default:
       break;
   }
@@ -1124,6 +1222,173 @@ function evaluateAskToolProvenance(output, context, testCase) {
   };
 }
 
+function firstAction(payload) {
+  const actions = Array.isArray(payload?.recommendedNextActions) ? payload.recommendedNextActions : [];
+  return actions.find((action) => typeof action?.action === 'string' && action.action.trim());
+}
+
+function evaluateScoreCommentaryAction(output, context, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_action', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const payload = scoreCommentaryPayload(output);
+  const hasNegativeDrivers = Array.isArray(context?.topNegativeDrivers) && context.topNegativeDrivers.length > 0;
+  const hasAction = Boolean(firstAction(payload));
+  const noTrainingSignal = context?.dataTier === 'noTrainingSignal';
+  const failures = [];
+
+  if (noTrainingSignal && hasAction) {
+    failures.push('No-training-signal score commentary must not include a recommended action.');
+  }
+  if (!noTrainingSignal && hasNegativeDrivers && !hasAction) {
+    failures.push('Score commentary with negative drivers must include a recommended action.');
+  }
+
+  return {
+    key: 'score_commentary_action',
+    passed: failures.length === 0,
+    reason: failures.length === 0
+      ? 'Score commentary action presence matches score state.'
+      : failures.join(' ')
+  };
+}
+
+function driverKeyword(driver) {
+  const text = normalizeText(driver?.message ?? driver?.label ?? driver?.driverMessage ?? driver?.component ?? '');
+  const tokens = text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 4 && !['score', 'sets', 'work', 'this', 'that', 'with', 'from', 'your'].includes(token));
+  return tokens[0] ?? null;
+}
+
+function evaluateScoreCommentarySynthesis(output, context, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_synthesis', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const positives = context?.topPositiveDrivers ?? [];
+  const negatives = context?.topNegativeDrivers ?? [];
+  if (positives.length === 0 || negatives.length === 0) {
+    return {
+      key: 'score_commentary_synthesis',
+      passed: true,
+      reason: 'Mixed-driver synthesis is not required for one-sided commentary.'
+    };
+  }
+
+  const text = scoreCommentaryText(output).toLowerCase();
+  const positiveKeyword = driverKeyword(positives[0]);
+  const negativeKeyword = driverKeyword(negatives[0]);
+  const hasPositive = positiveKeyword ? text.includes(positiveKeyword) : true;
+  const hasNegative = negativeKeyword ? text.includes(negativeKeyword) : true;
+  const hasContrast = /\bbut\b|\bwhile\b|\balthough\b|\bhowever\b/.test(text);
+
+  return {
+    key: 'score_commentary_synthesis',
+    passed: hasPositive && hasNegative && hasContrast,
+    reason: hasPositive && hasNegative && hasContrast
+      ? 'Mixed positive and negative drivers are synthesized.'
+      : 'Mixed-driver commentary must reference both directions with contrast language.'
+  };
+}
+
+function evaluateScoreCommentaryExerciseInvention(output, snapshot, context, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_no_exercise_invention', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const allowedText = [
+    ...(context?.topPositiveDrivers ?? []),
+    ...(context?.topNegativeDrivers ?? [])
+  ].map((driver) => [
+    driver?.message,
+    driver?.label,
+    driver?.relatedExerciseName,
+    driver?.relatedExerciseSlug,
+    driver?.exerciseName
+  ].filter(Boolean).join(' ')).join(' ');
+  const normalizedAllowed = normalizeExerciseName(allowedText);
+  const normalizedOutput = normalizeExerciseName(scoreCommentaryText(output));
+  const invented = [];
+
+  for (const exerciseName of collectAllExerciseNames(snapshot)) {
+    const normalizedName = normalizeExerciseName(exerciseName);
+    if (!normalizedName) continue;
+    const pattern = new RegExp(`(?<!\\S)${escapeRegex(normalizedName)}(?!\\S)`);
+    if (pattern.test(normalizedOutput) && !pattern.test(normalizedAllowed)) {
+      invented.push(exerciseName);
+    }
+  }
+
+  return {
+    key: 'score_commentary_no_exercise_invention',
+    passed: invented.length === 0,
+    reason: invented.length === 0
+      ? 'Score commentary only names exercises present in score drivers.'
+      : `Invented exercise mention(s): ${uniqueStrings(invented).join(', ')}`
+  };
+}
+
+function evaluateScoreCommentaryBand(output, context, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_score_band', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const payload = scoreCommentaryPayload(output);
+  const expected = computeScoreBand(context?.score);
+  const actual = payload.scoreBand ?? null;
+  return {
+    key: 'score_commentary_score_band',
+    passed: actual === expected,
+    reason: actual === expected
+      ? 'Score band matches canonical thresholds.'
+      : `Expected scoreBand ${expected ?? 'null'}, got ${actual ?? 'null'}.`
+  };
+}
+
+function evaluateScoreCommentaryTone(output, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_tone', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const text = scoreCommentaryText(output);
+  const failures = [];
+  if (text.includes('!')) failures.push('exclamation mark');
+  if (/\b(?:great job|awesome|crushing it|amazing work)\b/i.test(text)) failures.push('cheerleading phrase');
+  if (/[\u{1F300}-\u{1FAFF}]/u.test(text)) failures.push('emoji');
+
+  return {
+    key: 'score_commentary_tone',
+    passed: failures.length === 0,
+    reason: failures.length === 0
+      ? 'Score commentary tone is calm and non-cheerleading.'
+      : `Tone violation(s): ${failures.join(', ')}.`
+  };
+}
+
+function evaluateScoreCommentaryLength(output, testCase) {
+  if (testCase.surface !== 'scoreCommentary') {
+    return { key: 'score_commentary_length', passed: true, reason: 'Not score commentary.' };
+  }
+
+  const payload = scoreCommentaryPayload(output);
+  const summary = normalizeText(payload.subhead ?? payload.summaryText);
+  const action = normalizeText(firstAction(payload)?.action);
+  const failures = [];
+  if (summary.length > 140) failures.push(`summaryText/subhead is ${summary.length} chars, expected <= 140.`);
+  if (action && action.length > 140) failures.push(`action is ${action.length} chars, expected <= 140.`);
+
+  return {
+    key: 'score_commentary_length',
+    passed: failures.length === 0,
+    reason: failures.length === 0
+      ? 'Score commentary text fits length bounds.'
+      : failures.join(' ')
+  };
+}
+
 function personaEvalConfig(testCase) {
   if (testCase.personaEval === false) return null;
   if (testCase.personaEval && typeof testCase.personaEval === 'object') {
@@ -1234,6 +1499,12 @@ export function evaluateSummaryOutputFromSnapshot(testCase, snapshot, output) {
     evaluateWorkoutClaims(output, context, testCase),
     evaluateAskClaims(output, snapshot, testCase),
     evaluateAskToolProvenance(output, context, testCase),
+    evaluateScoreCommentaryAction(output, context, testCase),
+    evaluateScoreCommentarySynthesis(output, context, testCase),
+    evaluateScoreCommentaryExerciseInvention(output, snapshot, context, testCase),
+    evaluateScoreCommentaryBand(output, context, testCase),
+    evaluateScoreCommentaryTone(output, testCase),
+    evaluateScoreCommentaryLength(output, testCase),
     evaluatePersonaMotivation(output, context, testCase)
   ];
 
@@ -1269,6 +1540,8 @@ function genericForbiddenPhrasesForSurface(surface) {
       return [];
     case 'ask':
       return [];
+    case 'scoreCommentary':
+      return ['great job', 'awesome', 'crushing it', 'amazing work'];
     default:
       return [];
   }

package/src/sync-service.js

@@ -3,6 +3,7 @@ import { anonymizeAccountId } from './anonymize.js';
 import { capabilities as cliCapabilities, contractVersion, officialCommands } from './contract.js';
 import { executeReadCommand } from './queries.js';
 import { sanitizeHistory, detectSystemPromptLeak, stripXMLTagBlocks } from './prompt-security.js';
+import { enrichScoreSnapshots } from './score-context.js';
 
 const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB
 const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
@@ -783,6 +784,27 @@ function routeRequest(url, method) {
     };
   }
 
+  if (pathname === '/cli/increment-score/current') {
+    return {
+      command: 'increment-score-current',
+      options: {
+        historyDays: url.searchParams.get('historyDays') ?? undefined
+      }
+    };
+  }
+
+  {
+    const coachToolMatch = pathname.match(/^\/cli\/coach-tools\/([^/]+)$/);
+    if (coachToolMatch) {
+      return {
+        command: 'coach-tool',
+        options: {
+          toolName: decodeURIComponent(coachToolMatch[1])
+        }
+      };
+    }
+  }
+
   if (pathname === '/cli/account') {
     return { command: 'delete-account', options: {} };
   }
@@ -2879,7 +2901,8 @@ export function createSyncServiceRequestHandler({
             return;
           }
           try {
-            const snapshots = await listScoreSnapshotsForAccount(account, route.options ?? {});
+            const rawSnapshots = await listScoreSnapshotsForAccount(account, route.options ?? {});
+            const snapshots = enrichScoreSnapshots(rawSnapshots);
             json(response, 200, { snapshots });
             return;
           } catch (error) {
@@ -3476,6 +3499,58 @@ export function createSyncServiceRequestHandler({
       // Parse comma-separated exclude param into a Set for AI context builders
       const parseExclude = (raw) => new Set((raw ?? '').split(',').map((s) => s.trim()).filter(Boolean));
       const aiUser = anonymizeAccountId(account.id);
+      const hydrateIncrementScore = async (limit = 14) => {
+        if (!listScoreSnapshotsForAccount) return;
+        const scoreSnapshots = await listScoreSnapshotsForAccount(account, { limit }) ?? [];
+        if (scoreSnapshots.length > 0) {
+          const enrichedSnapshots = enrichScoreSnapshots(scoreSnapshots);
+          snapshot.incrementScore = {
+            latest: enrichedSnapshots[0],
+            history: enrichedSnapshots
+          };
+        }
+      };
+
+      if (route.command === 'increment-score-current') {
+        if (request.method !== 'GET') {
+          methodNotAllowed(response, 'Use GET for /cli/increment-score/current.');
+          return;
+        }
+
+        try {
+          await hydrateIncrementScore(route.options.historyDays ?? 14);
+          const queries = await import('./queries.js');
+          json(response, 200, queries.incrementScoreCurrent(snapshot, route.options));
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
+
+      if (route.command === 'coach-tool') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /cli/coach-tools/:toolName.');
+          return;
+        }
+
+        try {
+          const body = await readJsonBody(request);
+          const queries = await import('./queries.js');
+          if (!queries.COACH_READ_TOOL_NAMES.includes(route.options.toolName)) {
+            notFound(response, `Unknown coach read tool: ${route.options.toolName}`);
+            return;
+          }
+          if (route.options.toolName === 'get_increment_score') {
+            await hydrateIncrementScore(body?.historyDays ?? 14);
+          }
+          json(response, 200, queries.executeCoachReadTool(snapshot, route.options.toolName, body ?? {}));
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
 
       if (route.command === 'workout-summary-ai') {
         const sessionId = route.options['session-id'];
@@ -4074,9 +4149,10 @@ export function createSyncServiceRequestHandler({
           }
         }
         if (scoreSnapshots.length > 0) {
+          const enrichedSnapshots = enrichScoreSnapshots(scoreSnapshots);
           snapshot.incrementScore = {
-            latest: scoreSnapshots[0],
-            history: scoreSnapshots
+            latest: enrichedSnapshots[0],
+            history: enrichedSnapshots
           };
         }
 

package/src/transport.js

@@ -1,6 +1,6 @@
 import { readSnapshot, resolveSnapshotSource } from './local.js';
 import { createRemoteTransport } from './remote.js';
-import { executeReadCommand } from './queries.js';
+import { executeCoachReadTool, executeReadCommand } from './queries.js';
 import { isSessionExpired } from './state.js';
 
 function prefersLocal(options) {
@@ -33,6 +33,14 @@ function createLocalTransport(snapshotSource) {
 
       return result.payload;
     },
+    async executeCoachReadTool(toolName, input = {}) {
+      if (!snapshotSource) {
+        throw snapshotNotFoundError();
+      }
+
+      const snapshot = await readSnapshot(snapshotSource.path);
+      return executeCoachReadTool(snapshot, toolName, input);
+    },
     async executeWriteCommand() {
       const error = new Error('Write commands require a remote session. Run incremnt login first.');
       error.code = 'WRITE_REQUIRES_REMOTE';