Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Goal Effectiveness Scorecard — weekly time-allocation vs stated goals
* (Human Activity Tracking Phase 8, #2157).
*
* Correlates where a week's tracked time/attention actually went (the Human
* Activity timeline — conversations, meetings, media) against the user's stated
* goals (`data/digital-twin/goals.json`) and produces a weekly scorecard:
*
* - Hours aligned to each goal vs unaligned time.
* - Trend vs prior weeks (aligned share over the last N weeks).
* - Contact-vs-goal alignment (distinct people touched per goal — e.g. tribe
* touch cadence against relationship goals).
*
* Two layers, matching the Phase 6 activity-digest split:
* 1. **Numeric scorecard — always LLM-free, deterministic.** Events map to
* goals via keyword / participant / calendar rules (user-editable, stored
* locally). The rollup is pure arithmetic. This is the artifact rendered on
* the Insights page.
* 2. **Optional LLM narrative (opt-in).** "This week you said X mattered but
* spent 6× more time on Y." Behind the same provider config as the activity
* digest (#2155) — silent until the user configures a provider AND clicks
* Refresh. See AGENTS.md "AI Provider Usage Policy".
*
* The scorecard artifact lives under `data/insights/` alongside the cross-domain
* insights caches. All reads are disk-only; compute is an explicit user action.
*/
import { join } from 'path';
import { atomicWrite, ensureDir, readJSONFile, PATHS } from '../lib/fileUtils.js';
import { createSettingsStore } from '../lib/settingsStore.js';
import { todayInTimezone, localDayRangeUtc } from '../lib/timezone.js';
import { getUserTimezone } from './userTimezone.js';
import { localDayKey, listEvents } from './humanActivity.js';
import * as journal from './brainJournal.js';
import { buildMarkers } from '../lib/markedSection.js';
import { getProviderById, getActiveProvider } from './providers.js';
import { runPromptThroughProvider } from './promptRunner.js';
const GOALS_FILE = join(PATHS.digitalTwin, 'goals.json');
const INSIGHTS_DIR = join(PATHS.data, 'insights');
const SCORECARD_FILE = join(INSIGHTS_DIR, 'goal-scorecard.json');
const RULES_FILE = join(INSIGHTS_DIR, 'goal-scorecard-rules.json');
const SETTINGS_FILE = join(INSIGHTS_DIR, 'goal-scorecard-settings.json');
// Marker pair for the one-line slice spliced into the week-anchor day's Brain
// daily-log entry (checkbox 4 — feed a slice into the digest).
export const SCORECARD_DIGEST_MARKERS = buildMarkers('goal-scorecard');
// How many weeks (including the current one) the trend series spans.
export const TREND_WEEKS = 4;
// Deterministic time-allocation proxy per event kind. The timeline stores real
// durations for calendar/media events; conversations are point-in-time, so a
// small nominal cost keeps them from vanishing from a time-allocation view
// without letting a chatty day dwarf an all-day meeting.
export const NOMINAL_SECONDS = {
'message.sent': 120,
'message.received': 60,
'calendar.event': 1800,
'media.listen': 180,
'media.watch': 600,
default: 300,
};
const DEFAULT_SETTINGS = {
// Opt-in for the LLM narrative + scheduled/digest side effects. When false the
// numeric scorecard still computes on demand (it is LLM-free); only the
// narrative and the Brain digest slice stay silent.
enabled: false,
// Provider/model for the optional narrative. null → numeric scorecard only.
provider: null,
model: null,
// When true (and enabled), computing a scorecard also splices a one-line slice
// into the week-anchor day's Brain daily-log entry.
feedBrainDigest: false,
// ISO day the week starts on (1 = Monday, per ISO-8601).
weekStartsOn: 1,
};
const CLIENT_SETTABLE = ['enabled', 'provider', 'model', 'feedBrainDigest', 'weekStartsOn'];
// Tokens too generic to be useful goal keywords.
const STOPWORDS = new Set([
'the', 'and', 'for', 'with', 'from', 'that', 'this', 'have', 'make', 'made',
'your', 'you', 'get', 'got', 'more', 'less', 'into', 'onto', 'over', 'been',
'about', 'goal', 'goals', 'real', 'another', 'again', 'keep', 'stay', 'remain',
'long', 'possible', 'first', 'finish', 'create', 'creating', 'build', 'buy',
]);
// ─── Pure helpers (exported for unit tests — no I/O) ─────────────────────────
const isoRe = /^\d{4}-\d{2}-\d{2}$/;
const isIso = (d) => typeof d === 'string' && isoRe.test(d);
// Shift a YYYY-MM-DD calendar date by N days (UTC math — a calendar day is not
// an instant, so DST doesn't apply). Returns YYYY-MM-DD.
export function shiftIsoDate(date, days) {
const [y, m, d] = String(date).split('-').map(Number);
const dt = new Date(Date.UTC(y, m - 1, d));
dt.setUTCDate(dt.getUTCDate() + days);
return dt.toISOString().slice(0, 10);
}
// The calendar date (YYYY-MM-DD) of the start of the week containing `dateStr`.
// `weekStartsOn` uses ISO day numbers (1 = Monday … 7 = Sunday); default Monday.
// Operates on the calendar date only, so it is timezone-agnostic.
export function isoWeekStart(dateStr, weekStartsOn = 1) {
if (!isIso(dateStr)) return null;
const [y, m, d] = dateStr.split('-').map(Number);
const dow = new Date(Date.UTC(y, m - 1, d)).getUTCDay(); // 0=Sun … 6=Sat
const isoDow = dow === 0 ? 7 : dow; // 1=Mon … 7=Sun
const start = ((weekStartsOn - 1 + 7) % 7);
const offset = (isoDow - 1 - start + 7) % 7;
return shiftIsoDate(dateStr, -offset);
}
// UTC [start, end) instants bounding a local week that begins on `weekStartIso`.
// Anchors on the source-of-truth local-day range so DST transitions inside the
// week keep their true length (end is the NEXT week's local midnight, not +7×24h).
export function weekRangeUtc(weekStartIso, timezone) {
const startRange = localDayRangeUtc(weekStartIso, timezone);
if (!startRange) return null;
const endRange = localDayRangeUtc(shiftIsoDate(weekStartIso, 7), timezone);
return { start: startRange.start, end: endRange.start };
}
// Extract lowercase keyword tokens from a goal's title/tags/category. Tags and
// category pass through verbatim (already meaningful); title words are split,
// length-filtered, and stopword-filtered so a title like "Buy Estate Property"
// yields ["estate", "property"], not ["buy"].
export function goalKeywords(goal) {
const words = String(goal?.title || '')
.toLowerCase()
.split(/[^a-z0-9]+/)
.filter((w) => w.length >= 4 && !STOPWORDS.has(w));
const tags = Array.isArray(goal?.tags)
? goal.tags.map((t) => String(t).toLowerCase().trim()).filter(Boolean)
: [];
const category = goal?.category ? [String(goal.category).toLowerCase()] : [];
return Array.from(new Set([...words, ...tags, ...category]));
}
// Build the deterministic goal→match ruleset. Each active goal gets a rule with
// derived keywords plus its linked calendars. A per-goal override (keyed by goal
// id) can add keywords, add participant personIds, replace the linked calendars,
// or disable the goal from the scorecard entirely.
//
// Note the real goal shapes (see server/services/identity/goals.js): a goal's
// `linkedActivities` are named tracked activities (`{ activityName, … }`), NOT
// tribe person ids — so their names fold into keywords. `linkedCalendars` are
// `{ subcalendarId, matchPattern }` objects (same shape dailyReview.js reads).
export function buildMappingRules(goals = [], overrides = {}) {
const rules = [];
for (const goal of goals || []) {
if (!goal?.id) continue;
if (goal.status && goal.status !== 'active') continue;
const override = overrides[goal.id] || {};
if (override.enabled === false) continue;
const activityNames = Array.isArray(goal.linkedActivities)
? goal.linkedActivities.map((a) => String(a?.activityName || '').toLowerCase().trim()).filter(Boolean)
: [];
const keywords = Array.from(new Set([
...goalKeywords(goal),
...activityNames,
...((Array.isArray(override.keywords) ? override.keywords : []).map((k) => String(k).toLowerCase().trim()).filter(Boolean)),
]));
// Linked calendars → { subcalendarId, matchPattern } (matchPattern, when
// present, further requires the event title to contain it — like dailyReview).
let subcalendars = Array.isArray(goal.linkedCalendars)
? goal.linkedCalendars
.filter((lc) => lc?.subcalendarId != null)
.map((lc) => ({ subcalendarId: String(lc.subcalendarId), matchPattern: lc.matchPattern ? String(lc.matchPattern).toLowerCase() : null }))
: [];
if (Array.isArray(override.subcalendarIds)) {
// Override supplies plain ids (no per-calendar pattern).
subcalendars = override.subcalendarIds.map((id) => ({ subcalendarId: String(id), matchPattern: null }));
}
rules.push({
id: goal.id,
title: goal.title || '(untitled goal)',
category: goal.category || null,
keywords,
personIds: Array.isArray(override.personIds) ? override.personIds.map(String) : [],
subcalendars,
});
}
return rules;
}
// The searchable text of an event (title + summary + participant names), lowercased.
function eventText(event) {
const parts = [event?.title, event?.summary];
for (const p of event?.participants || []) {
if (p?.name) parts.push(p.name);
}
return parts.filter(Boolean).join(' ').toLowerCase();
}
// The goal ids a single event maps to. An event aligns to a goal when ANY of:
// - a goal keyword appears in the event's text (title/summary/participant name)
// - an event participant's personId is in the goal's linked personIds
// - the event's calendar subcalendarId is in the goal's linked calendars
// Returns a de-duplicated array of goal ids (possibly empty = unaligned).
export function eventGoalMatches(event, rules = []) {
if (!event) return [];
const text = eventText(event);
// Whole-word set for single-token keywords so a short tag/category can't
// substring-match unrelated text ("go" in "going", "art" in "start"). Phrase
// keywords (containing a space) still substring-match against the full text.
const words = new Set(text.split(/[^a-z0-9]+/).filter(Boolean));
const personIds = new Set((event.participants || []).map((p) => p?.personId).filter(Boolean).map(String));
const subcal = event?.metadata?.subcalendarId != null ? String(event.metadata.subcalendarId) : null;
const matched = [];
for (const rule of rules) {
const byKeyword = rule.keywords.some((k) => k && (k.includes(' ') ? text.includes(k) : words.has(k)));
const byPerson = rule.personIds.some((id) => personIds.has(String(id)));
const byCalendar = subcal != null && rule.subcalendars.some((sc) => (
sc.subcalendarId === subcal && (!sc.matchPattern || text.includes(sc.matchPattern))
));
if (byKeyword || byPerson || byCalendar) matched.push(rule.id);
}
return Array.from(new Set(matched));
}
// Deterministic time-allocation weight (seconds) for an event: its real duration
// when present, otherwise the per-kind nominal proxy.
export function eventSeconds(event, nominal = NOMINAL_SECONDS) {
const d = Number(event?.durationS);
if (Number.isFinite(d) && d > 0) return Math.round(d);
return nominal[event?.kind] ?? nominal.default;
}
// Bucket events into local weeks. Returns a Map of weekStartIso → events[].
// Events with an unparseable timestamp are dropped.
export function bucketEventsByWeek(events = [], timezone, weekStartsOn = 1) {
const buckets = new Map();
for (const ev of events || []) {
const day = localDayKey(ev.happenedAt ?? ev.happened_at, timezone);
if (!day) continue;
const wk = isoWeekStart(day, weekStartsOn);
if (!wk) continue;
if (!buckets.has(wk)) buckets.set(wk, []);
buckets.get(wk).push(ev);
}
return buckets;
}
// Lightweight aligned/unaligned/total seconds for a set of events — the unit the
// trend series is built from (no per-goal breakdown).
export function weekTotals(events = [], rules = [], nominal = NOMINAL_SECONDS) {
let aligned = 0;
let unaligned = 0;
for (const ev of events || []) {
const seconds = eventSeconds(ev, nominal);
if (eventGoalMatches(ev, rules).length > 0) aligned += seconds;
else unaligned += seconds;
}
return { alignedSeconds: aligned, unalignedSeconds: unaligned, totalSeconds: aligned + unaligned, eventCount: (events || []).length };
}
const secondsToHours = (s) => Math.round((s / 3600) * 100) / 100;
// A distinct-person key for contact-cadence counting: prefer personId, then
// email, then phone, then name. Returns null when the participant is anonymous.
function contactKey(p) {
if (!p) return null;
return p.personId ? `id:${p.personId}` : p.email ? `email:${p.email}` : p.phone ? `phone:${p.phone}` : p.name ? `name:${p.name}` : null;
}
/**
* Compute the detailed single-week scorecard. Pure — the caller supplies just
* that week's events plus the prior-week totals for the trend series.
*
* @param {object} args
* @param {string} args.weekStart — YYYY-MM-DD (the local week's first day)
* @param {object[]} args.events — timeline events for that week only
* @param {object[]} args.rules — output of buildMappingRules()
* @param {string} [args.timezone]
* @param {Array<{weekStart,alignedSeconds,unalignedSeconds,totalSeconds}>} [args.trend]
* — ascending prior→current weekly totals (current week last).
* @param {object} [args.nominal]
*/
export function computeScorecard({ weekStart, events = [], rules = [], timezone = null, trend = [], nominal = NOMINAL_SECONDS }) {
const perGoal = new Map(rules.map((r) => [r.id, {
id: r.id, title: r.title, category: r.category,
alignedSeconds: 0, eventCount: 0, contacts: new Set(),
}]));
let alignedSeconds = 0;
let unalignedSeconds = 0;
for (const ev of events || []) {
const seconds = eventSeconds(ev, nominal);
const matches = eventGoalMatches(ev, rules);
if (matches.length === 0) {
unalignedSeconds += seconds;
continue;
}
alignedSeconds += seconds;
for (const goalId of matches) {
const g = perGoal.get(goalId);
if (!g) continue;
g.alignedSeconds += seconds;
g.eventCount += 1;
for (const p of ev.participants || []) {
const key = contactKey(p);
if (key) g.contacts.add(key);
}
}
}
const totalSeconds = alignedSeconds + unalignedSeconds;
const goals = Array.from(perGoal.values())
.map((g) => ({
id: g.id,
title: g.title,
category: g.category,
alignedSeconds: g.alignedSeconds,
alignedHours: secondsToHours(g.alignedSeconds),
eventCount: g.eventCount,
contactCount: g.contacts.size,
// Share of ALIGNED time this goal claims (goals can overlap on one event,
// so goal shares need not sum to 1 — this ranks focus, not a partition).
share: alignedSeconds > 0 ? Math.round((g.alignedSeconds / alignedSeconds) * 1000) / 1000 : 0,
}))
.sort((a, b) => b.alignedSeconds - a.alignedSeconds);
// Trend direction: this week's aligned SHARE of total vs the mean aligned
// share of the prior weeks in the series.
const priorWeeks = trend.slice(0, -1);
const priorShares = priorWeeks
.filter((w) => w.totalSeconds > 0)
.map((w) => w.alignedSeconds / w.totalSeconds);
const currentShare = totalSeconds > 0 ? alignedSeconds / totalSeconds : 0;
const priorMean = priorShares.length ? priorShares.reduce((a, b) => a + b, 0) / priorShares.length : null;
let direction = 'flat';
// A zero-activity week has no aligned share to compare — a blank week isn't a
// "decline" in goal alignment, so leave it neutral rather than reporting 'down'.
if (priorMean != null && totalSeconds > 0) {
if (currentShare > priorMean + 0.05) direction = 'up';
else if (currentShare < priorMean - 0.05) direction = 'down';
}
return {
weekStart,
timezone,
generatedAt: new Date().toISOString(),
totals: {
alignedSeconds,
unalignedSeconds,
totalSeconds,
alignedHours: secondsToHours(alignedSeconds),
unalignedHours: secondsToHours(unalignedSeconds),
alignedShare: totalSeconds > 0 ? Math.round(currentShare * 1000) / 1000 : 0,
eventCount: (events || []).length,
},
goals,
trend: trend.map((w) => ({
weekStart: w.weekStart,
alignedSeconds: w.alignedSeconds,
unalignedSeconds: w.unalignedSeconds,
alignedShare: w.totalSeconds > 0 ? Math.round((w.alignedSeconds / w.totalSeconds) * 1000) / 1000 : 0,
})),
trendDirection: direction,
narrative: null,
narrativeGeneratedAt: null,
};
}
// One-line digest slice for the Brain daily/weekly log. Pure — LLM-free.
export function formatScorecardDigestLine(scorecard) {
if (!scorecard?.totals || scorecard.totals.totalSeconds === 0) return null;
const { alignedHours, unalignedHours, alignedShare } = scorecard.totals;
const top = scorecard.goals?.find((g) => g.alignedSeconds > 0);
const topPart = top ? ` Most-aligned: ${top.title} (${top.alignedHours}h).` : '';
const pct = Math.round((alignedShare || 0) * 100);
return `**Goal scorecard (week of ${scorecard.weekStart})** — ${alignedHours}h aligned to goals vs ${unalignedHours}h unaligned (${pct}% goal-aligned).${topPart}`;
}
// ─── Settings / rules I/O ────────────────────────────────────────────────────
// Strict read + serialized PATCH live in the store (#4115): a swallowed
// unreadable file would otherwise write DEFAULT_SETTINGS over the user's
// configured provider/model/week-start on the next settings PATCH.
const settingsStore = createSettingsStore(SETTINGS_FILE, DEFAULT_SETTINGS);
export const getSettings = settingsStore.get;
// Only client-settable keys are honored; managed fields never come from a PUT.
export async function updateSettings(partial = {}) {
return settingsStore.update(Object.fromEntries(CLIENT_SETTABLE.map((key) => [key, partial[key]])));
}
// User-editable per-goal mapping overrides. Shape: { [goalId]: { keywords?,
// personIds?, subcalendarIds?, enabled? } }. Stored locally, never federated.
export async function getRuleOverrides() {
// Strict (#4115): these overrides are hand-authored and never regenerated. An
// unreadable file would present the rules editor with an empty override set,
// and the very next save from that editor would persist the emptiness.
const loaded = await readJSONFile(RULES_FILE, null, { strict: true });
return loaded && typeof loaded === 'object' ? loaded : {};
}
export async function saveRuleOverrides(overrides = {}) {
const clean = overrides && typeof overrides === 'object' ? overrides : {};
await ensureDir(INSIGHTS_DIR);
await atomicWrite(RULES_FILE, clean);
return clean;
}
// Load active goals from digital-twin. Returns [] when the file is missing.
// Strict (#4115): goals are what every event is scored AGAINST. An unreadable
// goals.json yields zero mapping rules, so every hour buckets as unaligned and
// `computeWeeklyScorecard` persists — and splices into the Brain daily log — a
// confident "0% goal-aligned" that is a read failure, not a real week.
async function loadGoals() {
const data = await readJSONFile(GOALS_FILE, null, { strict: true });
return Array.isArray(data?.goals) ? data.goals : [];
}
// The current effective ruleset (goals × user overrides) — powers the rules
// editor UI so the user sees the derived keywords they can extend.
export async function getEffectiveRules() {
const [goals, overrides] = await Promise.all([loadGoals(), getRuleOverrides()]);
return { rules: buildMappingRules(goals, overrides), overrides };
}
// ─── Read path (disk-only) ───────────────────────────────────────────────────
export async function getScorecard() {
// Strict (#4115): `not_computed` is the UI's "click Compute" state. Reporting
// it for a present-but-corrupt artifact tells the user their scorecard was
// never built, when the truth is that we could not read it.
const cached = await readJSONFile(SCORECARD_FILE, null, { strict: true });
if (!cached) return { available: false, reason: 'not_computed' };
return { ...cached, available: true };
}
// ─── Compute (LLM-free) ──────────────────────────────────────────────────────
/**
* Compute (and persist) the weekly goal-effectiveness scorecard. Deterministic
* and LLM-free — safe to call on any user action. Queries the last TREND_WEEKS
* of timeline events once, buckets them, computes the detailed target week plus
* the trend series, persists the artifact, and (opt-in) splices a one-line slice
* into the week-anchor day's Brain daily-log.
*
* @param {object} [opts]
* @param {string} [opts.weekStart] — YYYY-MM-DD; defaults to the current week.
* @returns {Promise<object>} the scorecard artifact (with available: true).
*/
export async function computeWeeklyScorecard({ weekStart } = {}) {
const started = Date.now();
const timezone = await getUserTimezone();
const settings = await getSettings();
const weekStartsOn = Number.isFinite(settings.weekStartsOn) ? settings.weekStartsOn : 1;
const today = todayInTimezone(timezone);
const targetWeek = isIso(weekStart) ? isoWeekStart(weekStart, weekStartsOn) : isoWeekStart(today, weekStartsOn);
const [goals, overrides] = await Promise.all([loadGoals(), getRuleOverrides()]);
const rules = buildMappingRules(goals, overrides);
// Query the whole trend span in one pass: [oldest week start, target week end).
const oldestWeek = shiftIsoDate(targetWeek, -(TREND_WEEKS - 1) * 7);
const span = {
start: weekRangeUtc(oldestWeek, timezone)?.start,
end: weekRangeUtc(targetWeek, timezone)?.end,
};
const EVENT_CAP = 2000;
const events = span.start && span.end
? await listEvents({ from: span.start.toISOString(), to: span.end.toISOString(), limit: EVENT_CAP })
: [];
// listEvents returns newest-first capped at EVENT_CAP — the target (current)
// week is always fully covered, but a very active user could truncate the
// OLDEST trend weeks. Surface it rather than silently under-counting a trend bar.
if (events.length >= EVENT_CAP) {
console.warn(`🎯 Goal scorecard hit the ${EVENT_CAP}-event query cap for ${targetWeek}; oldest trend weeks may under-count`);
}
const buckets = bucketEventsByWeek(events, timezone, weekStartsOn);
const trend = [];
for (let i = TREND_WEEKS - 1; i >= 0; i -= 1) {
const wk = shiftIsoDate(targetWeek, -i * 7);
trend.push({ weekStart: wk, ...weekTotals(buckets.get(wk) || [], rules) });
}
const scorecard = computeScorecard({
weekStart: targetWeek,
events: buckets.get(targetWeek) || [],
rules,
timezone,
trend,
});
await ensureDir(INSIGHTS_DIR);
await atomicWrite(SCORECARD_FILE, scorecard);
if (settings.enabled && settings.feedBrainDigest) {
const line = formatScorecardDigestLine(scorecard);
// Splice into the week-anchor day's daily-log entry. Best-effort — a journal
// failure must not fail the scorecard compute.
await journal.upsertAutoSection(targetWeek, line || '', SCORECARD_DIGEST_MARKERS)
.catch((err) => console.error(`🎯 Goal scorecard digest slice failed for ${targetWeek}: ${err.message}`));
}
console.log(`🎯 Goal scorecard computed for week ${targetWeek}: ${scorecard.totals.alignedHours}h aligned / ${scorecard.totals.unalignedHours}h unaligned (${goals.length} goals, ${events.length} events) in ${Date.now() - started}ms`);
return { ...scorecard, available: true };
}
// ─── Optional LLM narrative (opt-in, user-triggered) ─────────────────────────
// Build the narrative prompt from the numeric scorecard. LLM-free callers never
// reach this.
function buildNarrativePrompt(scorecard) {
const goalLines = (scorecard.goals || [])
.filter((g) => g.alignedSeconds > 0)
.slice(0, 8)
.map((g) => `- ${g.title}${g.category ? ` (${g.category})` : ''}: ${g.alignedHours}h, ${g.eventCount} events, ${g.contactCount} distinct contacts`)
.join('\n');
const trendLine = (scorecard.trend || [])
.map((w) => `${w.weekStart}: ${Math.round((w.alignedShare || 0) * 100)}% aligned`)
.join(' → ');
return [
'You are an accountability coach reviewing how someone spent their week against their stated goals.',
'Below is a deterministic scorecard of tracked time. Write 2–4 sentences, second person ("You spent…"), factual — do not invent activities or goals not listed. Call out the biggest mismatch between stated priority and time spent, if any.',
'Do not add a heading or preamble. Do not use markdown.',
'',
`Week of ${scorecard.weekStart}.`,
`Aligned to goals: ${scorecard.totals.alignedHours}h. Unaligned: ${scorecard.totals.unalignedHours}h (${Math.round((scorecard.totals.alignedShare || 0) * 100)}% aligned).`,
'',
'Time by goal:',
goalLines || '(no time mapped to any goal this week)',
'',
`Aligned-share trend: ${trendLine}`,
].join('\n');
}
/**
* Generate the optional LLM narrative for the current scorecard and persist it
* onto the artifact. User-triggered only (a "Generate narrative" click). The
* numeric scorecard itself is never regenerated here — the narrative is an
* annotation on top of the deterministic artifact.
*
* @param {string} [providerId] — override the configured provider.
* @param {string} [model]
*/
export async function refreshScorecardNarrative(providerId, model) {
// Strict (#4115): this is the base of a read-modify-write — the narrative is
// spliced onto the artifact and the whole thing is written back. A swallowed
// read cannot reach the write (the `!scorecard` guard returns first), but it
// would report `not_computed` for a corrupt artifact and invite a recompute.
const scorecard = await readJSONFile(SCORECARD_FILE, null, { strict: true });
if (!scorecard) return { available: false, reason: 'not_computed' };
if (!scorecard.totals || scorecard.totals.totalSeconds === 0) {
return { available: false, reason: 'no_activity' };
}
const settings = await getSettings();
const resolvedProviderId = providerId || settings.provider;
// Prefer an explicit/configured provider; fall back to the active provider
// (mirrors the cross-domain narrative) so "enabled" alone is enough to run.
const provider = resolvedProviderId
? await getProviderById(resolvedProviderId).catch(() => null)
: await getActiveProvider().catch(() => null);
if (!provider || provider.enabled === false) return { available: false, reason: 'no_provider' };
const selectedModel = model || settings.model || provider.defaultModel;
const providerForCall = provider.headlessArgs?.length
? { ...provider, args: [...(provider.args || []), ...provider.headlessArgs] }
: provider;
const result = await runPromptThroughProvider({
provider: providerForCall,
prompt: buildNarrativePrompt(scorecard),
source: 'goal-scorecard',
model: selectedModel,
}).catch((err) => {
console.error(`🎯 Goal scorecard narrative failed: ${err.message}`);
return null;
});
const text = (result?.text || '').trim();
if (!text) return { available: false, reason: 'generation_failed' };
const updated = { ...scorecard, narrative: text, narrativeGeneratedAt: new Date().toISOString(), narrativeModel: selectedModel };
await ensureDir(INSIGHTS_DIR);
await atomicWrite(SCORECARD_FILE, updated);
console.log(`🎯 Goal scorecard narrative generated (${text.length} chars, model ${selectedModel})`);
return { ...updated, available: true };
}