@xera-ai/core 0.3.0 → 0.4.1

package/src/bin-internal/graph-record.ts

@@ -0,0 +1,287 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { appendEvents } from '../graph/store';
+import type {
+  Classification,
+  ClassificationDisputedPayload,
+  EdgeDiscoveredPayload,
+  Event,
+  PomPromotedPayload,
+  RunClassifiedPayload,
+  RunCompletedPayload,
+  TicketFetchedPayload,
+} from '../graph/types';
+import { SCHEMA_VERSION } from '../graph/types';
+import { ulid } from '../graph/ulid';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+function sha1(s: string): string {
+  return createHash('sha1').update(s).digest('hex');
+}
+function scenarioId(ticket: string, name: string): string {
+  return sha1(`${ticket}:${name.trim().toLowerCase().replace(/\s+/g, ' ')}`);
+}
+function pomId(filePath: string): string {
+  return sha1(basename(filePath));
+}
+function makeEvent<T extends Event['type']>(
+  actor: string,
+  type: T,
+  payload: Extract<Event, { type: T }>['payload'],
+): Event {
+  return {
+    event_id: ulid(),
+    schema_version: SCHEMA_VERSION,
+    ts: nowIso(),
+    actor,
+    type,
+    payload,
+  } as Event;
+}
+
+interface StoryFrontmatter {
+  ticketId: string;
+  summary: string;
+  storyHash: string;
+  acceptanceCriteria?: string[];
+  linked_issues?: Array<{
+    ticketId: string;
+    relation: 'blocks' | 'duplicates' | 'relates' | 'supersedes';
+  }>;
+}
+
+function readStoryFrontmatter(repoRoot: string, ticket: string): StoryFrontmatter | null {
+  const path = join(repoRoot, '.xera', ticket, 'story.md');
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, 'utf8');
+  const m = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  return parseYaml(m[1]!) as StoryFrontmatter;
+}
+
+function readGraphInput(repoRoot: string, ticket: string): { modifiesAreas: string[] } {
+  const path = join(repoRoot, '.xera', ticket, 'graph-input.json');
+  if (!existsSync(path)) return { modifiesAreas: [] };
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return { modifiesAreas: [] };
+  }
+}
+
+export async function recordFetch(repoRoot: string, ticket: string): Promise<number> {
+  const fm = readStoryFrontmatter(repoRoot, ticket);
+  if (!fm) {
+    console.error(`[graph-record fetch] story.md not found for ${ticket}`);
+    return 1;
+  }
+  const { modifiesAreas } = readGraphInput(repoRoot, ticket);
+  const events: Event[] = [];
+  const fetchedPayload: TicketFetchedPayload = {
+    ticketId: fm.ticketId,
+    summary: fm.summary,
+    ac: fm.acceptanceCriteria ?? [],
+    jiraLinks: fm.linked_issues ?? [],
+    storyHash: fm.storyHash,
+    modifiesAreas,
+  };
+  events.push(makeEvent('xera-fetch', 'ticket.fetched', fetchedPayload));
+  for (const link of fm.linked_issues ?? []) {
+    const p: EdgeDiscoveredPayload = {
+      kind: 'jira-linked',
+      from: fm.ticketId,
+      to: link.ticketId,
+      source: `jira:${link.relation}`,
+    };
+    events.push(makeEvent('xera-fetch', 'edge.discovered', p));
+  }
+  for (const area of modifiesAreas) {
+    const p: EdgeDiscoveredPayload = {
+      kind: 'modifies',
+      from: fm.ticketId,
+      to: area,
+      source: 'extract-areas',
+    };
+    events.push(makeEvent('xera-fetch', 'edge.discovered', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-fetch', ticketId: ticket });
+  return 0;
+}
+
+async function recordScript(repoRoot: string, ticket: string): Promise<number> {
+  const { recordScriptImpl } = await import('./graph-record-script');
+  return recordScriptImpl(repoRoot, ticket);
+}
+
+async function recordExec(repoRoot: string, ticket: string, runId: string): Promise<number> {
+  const reporterPath = join(repoRoot, '.xera', ticket, 'runs', runId, 'reporter.json');
+  if (!existsSync(reporterPath)) {
+    console.error(`[graph-record exec] reporter.json missing`);
+    return 1;
+  }
+  const data = JSON.parse(readFileSync(reporterPath, 'utf8')) as {
+    scenarios: Array<{ name: string; status: 'pass' | 'fail'; runtime: number; traceId?: string }>;
+  };
+  const events: Event[] = [];
+  for (const s of data.scenarios) {
+    const p: RunCompletedPayload = {
+      scenarioId: scenarioId(ticket, s.name),
+      ticketId: ticket,
+      runId,
+      status: s.status,
+      runtime: s.runtime,
+    };
+    if (s.traceId) p.traceId = s.traceId;
+    events.push(makeEvent('xera-exec', 'run.completed', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-exec', ticketId: ticket });
+  return 0;
+}
+
+async function recordClassify(repoRoot: string, ticket: string, runId: string): Promise<number> {
+  const classifyPath = join(repoRoot, '.xera', ticket, 'runs', runId, 'classifier-output.json');
+  if (!existsSync(classifyPath)) {
+    console.error(`[graph-record classify] classifier-output.json missing`);
+    return 1;
+  }
+  const data = JSON.parse(readFileSync(classifyPath, 'utf8')) as {
+    scenarios: Array<{ name: string; class: string; confidence: 'low' | 'medium' | 'high' }>;
+  };
+  const events: Event[] = [];
+  for (const s of data.scenarios) {
+    const p: RunClassifiedPayload = {
+      scenarioId: scenarioId(ticket, s.name),
+      runId,
+      classification: s.class as RunClassifiedPayload['classification'],
+      confidence: s.confidence,
+    };
+    events.push(makeEvent('xera-report', 'run.classified', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-report', ticketId: ticket });
+  return 0;
+}
+
+async function recordPromote(repoRoot: string, args: Map<string, string>): Promise<number> {
+  const from = args.get('--from');
+  const to = args.get('--to');
+  const pomIdArg = args.get('--pom-id');
+  if (!from || !to) {
+    console.error(`[graph-record promote] --from and --to required`);
+    return 1;
+  }
+  const id = pomIdArg ?? pomId(from);
+  const p: PomPromotedPayload = { pomId: id, fromPath: from, toPath: to };
+  const e = makeEvent('xera-promote', 'pom.promoted', p);
+  appendEvents(repoRoot, [e], { skill: 'xera-promote', ticketId: 'shared' });
+  return 0;
+}
+
+function parseFlags(args: string[]): Map<string, string> {
+  const m = new Map<string, string>();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i]!.startsWith('--')) {
+      m.set(args[i]!, args[i + 1] ?? '');
+      i++;
+    }
+  }
+  return m;
+}
+
+export async function graphRecordCmd(argv: string[]): Promise<number> {
+  const [action, ...rest] = argv;
+  if (!action) {
+    console.error(
+      `Usage: xera-internal graph-record <fetch|script|exec|classify|promote|dispute> [args]`,
+    );
+    return 1;
+  }
+  const repoRoot = process.cwd();
+  switch (action) {
+    case 'fetch': {
+      const ticket = rest[0];
+      if (!ticket) {
+        console.error('ticket required');
+        return 1;
+      }
+      return recordFetch(repoRoot, ticket);
+    }
+    case 'script': {
+      const ticket = rest[0];
+      if (!ticket) {
+        console.error('ticket required');
+        return 1;
+      }
+      return recordScript(repoRoot, ticket);
+    }
+    case 'exec': {
+      const ticket = rest[0];
+      const flags = parseFlags(rest);
+      const runId = flags.get('--run-id');
+      if (!ticket || !runId) {
+        console.error('ticket + --run-id required');
+        return 1;
+      }
+      return recordExec(repoRoot, ticket, runId);
+    }
+    case 'classify': {
+      const ticket = rest[0];
+      const flags = parseFlags(rest);
+      const runId = flags.get('--run-id');
+      if (!ticket || !runId) {
+        console.error('ticket + --run-id required');
+        return 1;
+      }
+      return recordClassify(repoRoot, ticket, runId);
+    }
+    case 'promote': {
+      return recordPromote(repoRoot, parseFlags(rest));
+    }
+    case 'dispute': {
+      const flags = parseFlags(rest);
+      const runId = flags.get('--run-id');
+      const scenarioIdArg = flags.get('--scenario-id');
+      const from = flags.get('--from');
+      const to = flags.get('--to');
+      const actor = flags.get('--actor');
+      const reason = flags.get('--reason');
+      if (!runId || !scenarioIdArg || !from || !to || !actor) {
+        console.error(
+          '[graph-record dispute] required: --run-id --scenario-id --from --to --actor [--reason]',
+        );
+        return 1;
+      }
+      const validClass = [
+        'REAL_BUG',
+        'TEST_BUG',
+        'SELECTOR_DRIFT',
+        'FLAKY',
+        'PASS',
+        'TEST_OUTDATED',
+      ];
+      if (!validClass.includes(from) || !validClass.includes(to)) {
+        console.error(
+          `[graph-record dispute] --from and --to must be one of: ${validClass.join(', ')}`,
+        );
+        return 1;
+      }
+      const payload: ClassificationDisputedPayload = {
+        runId,
+        scenarioId: scenarioIdArg,
+        originalClassification: from as Classification,
+        disputedTo: to as Classification,
+        qaActor: actor,
+      };
+      if (reason) payload.qaReason = reason;
+      const e = makeEvent('xera-report', 'classification.disputed', payload);
+      appendEvents(repoRoot, [e], { skill: 'xera-report', ticketId: scenarioIdArg.slice(0, 12) });
+      return 0;
+    }
+    default:
+      console.error(`Unknown action: ${action}`);
+      return 1;
+  }
+}

package/src/bin-internal/graph-snapshot.ts

@@ -0,0 +1,23 @@
+import { deriveSnapshot, isSnapshotStale, loadAllEvents, writeSnapshot } from '../graph/store';
+
+export async function graphSnapshotCmd(argv: string[]): Promise<number> {
+  const check = argv.includes('--check');
+  const noRebuild = argv.includes('--no-rebuild');
+  const repoRoot = process.cwd();
+  const stale = isSnapshotStale(repoRoot);
+  if (check) {
+    if (!stale) return 0;
+    if (noRebuild) {
+      console.error('[graph-snapshot] stale');
+      return 1;
+    }
+    // fall through to rebuild
+  }
+  const events = loadAllEvents(repoRoot);
+  const snap = deriveSnapshot(events);
+  writeSnapshot(repoRoot, snap);
+  if (check && stale) {
+    console.log(`[graph-snapshot] rebuilt (${events.length} events)`);
+  }
+  return 0;
+}

package/src/bin-internal/heal-prepare.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { scrubFreeText } from '@xera-ai/web';
 import { unzipSync } from 'fflate';

package/src/bin-internal/index.ts

@@ -4,6 +4,11 @@ import { evalPrepareCmd } from './eval-prepare';
 import { evalReportCmd } from './eval-report';
 import { execCmd } from './exec';
 import { fetchCmd } from './fetch';
+import { graphBackfillCmd } from './graph-backfill';
+import { graphEnrichCmd } from './graph-enrich';
+import { graphQueryCmd } from './graph-query';
+import { graphRecordCmd } from './graph-record';
+import { graphSnapshotCmd } from './graph-snapshot';
 import { healPrepareCmd } from './heal-prepare';
 import { lintCmd } from './lint';
 import { normalizeCmd } from './normalize';
@@ -23,6 +28,11 @@ const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
   'eval-report': evalReportCmd,
   exec: execCmd,
   fetch: fetchCmd,
+  'graph-backfill': graphBackfillCmd,
+  'graph-enrich': graphEnrichCmd,
+  'graph-query': graphQueryCmd,
+  'graph-record': graphRecordCmd,
+  'graph-snapshot': graphSnapshotCmd,
   'heal-prepare': healPrepareCmd,
   lint: lintCmd,
   normalize: normalizeCmd,

package/src/bin-internal/report.ts

@@ -1,8 +1,11 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveArtifactPaths } from '../artifact/paths';
 import { aggregateScenarios } from '../classifier/aggregate';
 import type { ScenarioClassification } from '../classifier/types';
+import type { OutdatedDecision } from '../graph/classify';
+import { enhanceClassification } from '../graph/classify';
+import { deriveSnapshot, loadAllEvents } from '../graph/store';
 import { buildJiraComment } from '../reporter/jira-comment';
 import { writeStatusFromClassification } from '../reporter/status-writer';
 
@@ -23,20 +26,75 @@ export async function reportCmd(argv: string[]): Promise<number> {
   const input = JSON.parse(readFileSync(inputArg.slice('--input='.length), 'utf8')) as ReportInput;
 
   const aggregated = aggregateScenarios(input.scenarios);
+
+  // v0.6.1: TEST_OUTDATED enhancement.
+  // The /xera-report skill writes outdated-decisions.json BEFORE invoking this subcommand,
+  // containing { [scenarioId]: { classification, confidence, evidence } } for every
+  // failing scenario the skill ran the LLM on. We use those decisions directly via
+  // an injected resolver — no Claude call here.
+  const decisionsPath = join(paths.ticketDir, 'runs', input.runId, 'outdated-decisions.json');
+  const decisions: Record<string, OutdatedDecision> = existsSync(decisionsPath)
+    ? (JSON.parse(readFileSync(decisionsPath, 'utf8')) as Record<string, OutdatedDecision>)
+    : {};
+
+  const graph = deriveSnapshot(loadAllEvents(process.cwd()));
+
+  // Build a lookup: normalized name → scenarioId (graph node id) for this ticket.
+  // This mirrors how graph-record-script.ts stores scenarios using sha1(ticket:name),
+  // but here we look up by the stored node id so both sha1-keyed and stub-keyed graphs work.
+  const normalizeScenarioName = (name: string) => name.trim().toLowerCase().replace(/\s+/g, ' ');
+
+  const scenarioIdByName: Record<string, string> = {};
+  for (const [id, node] of Object.entries(graph.scenarios)) {
+    if (node.ticketId === ticket) {
+      scenarioIdByName[normalizeScenarioName(node.name)] = id;
+    }
+  }
+
+  const enhancedScenarios: ScenarioClassification[] = await Promise.all(
+    aggregated.scenarios.map(async (s) => {
+      if (s.outcome !== 'FAIL') return s;
+      const scenarioId = scenarioIdByName[normalizeScenarioName(s.name)];
+      if (!scenarioId) return s;
+      const decision = decisions[scenarioId];
+      const decideOutdated = async (): Promise<OutdatedDecision> =>
+        decision ?? {
+          classification: 'BUG' as const,
+          confidence: 0,
+          evidence: { reasoning: 'no LLM decision' },
+        };
+      const enhanced = await enhanceClassification(
+        { scenarioId, traceClassification: s.class },
+        graph,
+        decideOutdated,
+      );
+      if (enhanced.classification !== s.class) {
+        return {
+          ...s,
+          class: enhanced.classification,
+          rationale: `${s.rationale} | TEST_OUTDATED override (conf ${enhanced.confidence})`,
+        };
+      }
+      return s;
+    }),
+  );
+
+  const reAggregated = aggregateScenarios(enhancedScenarios);
+
   const ts = new Date().toISOString();
   writeStatusFromClassification(paths.statusPath, {
     ticket,
     runTs: ts,
-    classification: aggregated,
+    classification: reAggregated,
     scenarioCounts: input.scenarioCounts,
   });
 
   const md = buildJiraComment({
     ticket,
     runId: input.runId,
-    overall: aggregated.overall,
-    overallConfidence: aggregated.overallConfidence,
-    scenarios: aggregated.scenarios,
+    overall: reAggregated.overall,
+    overallConfidence: reAggregated.overallConfidence,
+    scenarios: reAggregated.scenarios,
     xeraVersion: '0.1.0',
     promptsVersion: '1.0.0',
   });

package/src/bin-internal/verify-prompts.ts

@@ -10,6 +10,9 @@ const IN_SCOPE_PROMPTS = [
   'feature-from-story.md',
   'script-from-feature.md',
   'heal-locator.md',
+  'extract-areas.md',
+  'similarity-match.md',
+  'classify-outdated.md',
 ] as const;
 
 const REQUIRED_SECTION_HEADING = '## Handling untrusted input';

package/src/classifier/aggregate.ts

@@ -2,6 +2,7 @@ import type { ClassifyOutput, Confidence, ScenarioClassification } from './types
 
 const CLASS_PRIORITY: Array<ClassifyOutput['overall']> = [
   'REAL_BUG',
+  'TEST_OUTDATED',
   'TEST_BUG',
   'SELECTOR_DRIFT',
   'FLAKY',

package/src/config/schema.ts

@@ -19,12 +19,12 @@ const WebSchema = z
       message: 'baseUrl must have at least one environment',
     }),
     defaultEnv: z.string(),
-    auth: AuthSchema.default({}),
+    auth: AuthSchema.prefault({}),
     testData: z
       .object({
         users: z.record(z.string(), z.object({ fromAuth: z.string() })).default({}),
       })
-      .default({ users: {} }),
+      .prefault({}),
   })
   .refine((w) => w.baseUrl[w.defaultEnv] !== undefined, {
     message: 'defaultEnv must exist in baseUrl map',
@@ -51,9 +51,9 @@ const AISchema = z
         lint: z.number().int().min(0).max(5).default(2),
         validateFeature: z.number().int().min(0).max(5).default(2),
       })
-      .default({}),
+      .prefault({}),
   })
-  .default({});
+  .prefault({});
 
 const ReportingSchema = z
   .object({
@@ -64,10 +64,10 @@ const ReportingSchema = z
         onPass: z.string().nullable().default(null),
         onFail: z.string().nullable().default(null),
       })
-      .default({}),
+      .prefault({}),
     artifactLinks: z.enum(['git', 'local']).default('git'),
   })
-  .default({});
+  .prefault({});
 
 export const XeraConfigSchema = z.object({
   jira: JiraSchema,

package/src/graph/classify.ts

@@ -0,0 +1,126 @@
+import type { Classification, ScenarioNode, Snapshot, TicketNode } from './types';
+
+export interface ClassifyInput {
+  scenarioId: string;
+  traceClassification: Classification;
+}
+
+export interface CandidateEvidence {
+  ticketId: string;
+  summary: string;
+  modifiedArea: string;
+  relevantAcRef?: string;
+}
+
+export interface ClassifyEvidence {
+  candidateTickets?: CandidateEvidence[];
+  reasoning?: string;
+  expectedByTest?: string;
+  actualInApp?: string;
+  proposedAction?: 'regenerate-scenario' | 'review-and-decide';
+}
+
+export interface ClassifyOutput {
+  classification: Classification;
+  confidence: number;
+  evidence?: ClassifyEvidence;
+}
+
+export interface OutdatedDecision {
+  classification: 'TEST_OUTDATED' | 'BUG' | 'AMBIGUOUS';
+  confidence: number;
+  evidence: {
+    reasoning: string;
+    expectedByTest?: string;
+    actualInApp?: string;
+    relevantAcRef?: string;
+  };
+}
+
+export type DecideOutdated = (args: {
+  scenario: ScenarioNode;
+  candidates: TicketNode[];
+}) => Promise<OutdatedDecision>;
+
+const DEFAULT_THRESHOLD = 0.7;
+const SHORT_CIRCUIT: Classification[] = ['FLAKY', 'PASS'];
+
+export function findCandidateTickets(graph: Snapshot, scenario: ScenarioNode): TicketNode[] {
+  const poms = graph.edges
+    .filter((e) => e.kind === 'uses' && e.from === scenario.id)
+    .map((e) => e.to);
+  if (poms.length === 0) return [];
+
+  const areas = graph.edges
+    .filter((e) => e.kind === 'covers' && poms.includes(e.from))
+    .map((e) => e.to);
+  if (areas.length === 0) return [];
+
+  const ticketIds = graph.edges
+    .filter((e) => e.kind === 'modifies' && areas.includes(e.to))
+    .map((e) => e.from);
+
+  const seen = new Set<string>();
+  const out: TicketNode[] = [];
+  for (const id of ticketIds) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (id === scenario.ticketId) continue;
+    const t = graph.tickets[id];
+    if (!t) continue;
+    if (t.fetchedAt <= scenario.generatedAt) continue;
+    out.push(t);
+  }
+  return out;
+}
+
+export async function enhanceClassification(
+  input: ClassifyInput,
+  graph: Snapshot,
+  decideOutdated: DecideOutdated,
+  options: { threshold?: number } = {},
+): Promise<ClassifyOutput> {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  if (SHORT_CIRCUIT.includes(input.traceClassification)) {
+    return { classification: input.traceClassification, confidence: 1 };
+  }
+
+  const scenario = graph.scenarios[input.scenarioId];
+  if (!scenario) return { classification: input.traceClassification, confidence: 1 };
+
+  const candidates = findCandidateTickets(graph, scenario);
+  if (candidates.length === 0) {
+    return { classification: input.traceClassification, confidence: 1 };
+  }
+
+  const candidateEvidence: CandidateEvidence[] = candidates.map((t) => {
+    const area = graph.edges.find((e) => e.kind === 'modifies' && e.from === t.id)?.to ?? '';
+    const ev: CandidateEvidence = { ticketId: t.id, summary: t.summary, modifiedArea: area };
+    if (t.ac[0]) ev.relevantAcRef = t.ac[0];
+    return ev;
+  });
+
+  const decision = await decideOutdated({ scenario, candidates });
+
+  if (decision.classification === 'TEST_OUTDATED' && decision.confidence >= threshold) {
+    const evidence: ClassifyEvidence = {
+      candidateTickets: candidateEvidence,
+      reasoning: decision.evidence.reasoning,
+      proposedAction: 'regenerate-scenario',
+    };
+    if (decision.evidence.expectedByTest)
+      evidence.expectedByTest = decision.evidence.expectedByTest;
+    if (decision.evidence.actualInApp) evidence.actualInApp = decision.evidence.actualInApp;
+    return {
+      classification: 'TEST_OUTDATED',
+      confidence: decision.confidence,
+      evidence,
+    };
+  }
+
+  return {
+    classification: input.traceClassification,
+    confidence: 1,
+    evidence: { candidateTickets: candidateEvidence },
+  };
+}

package/src/graph/cost.ts

@@ -0,0 +1,59 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { graphPaths } from './paths';
+
+export interface LlmCallLog {
+  ts?: string;
+  skill: string;
+  prompt: string;
+  tokensIn: number;
+  tokensOut: number;
+  model: string;
+  costUsd: number;
+}
+
+export function logLlmCall(repoRoot: string, call: LlmCallLog): void {
+  const paths = graphPaths(repoRoot);
+  mkdirSync(dirname(paths.costLog), { recursive: true });
+  const record = {
+    ts: call.ts ?? new Date().toISOString(),
+    skill: call.skill,
+    prompt: call.prompt,
+    tokens_in: call.tokensIn,
+    tokens_out: call.tokensOut,
+    model: call.model,
+    cost_estimate_usd: call.costUsd,
+  };
+  appendFileSync(paths.costLog, `${JSON.stringify(record)}\n`);
+}
+
+export interface CostSummary {
+  totalCalls: number;
+  totalUsd: number;
+  bySkill: Record<string, { calls: number; usd: number }>;
+  windowDays: number;
+}
+
+export function summarizeCost(repoRoot: string, daysBack: number): CostSummary {
+  const paths = graphPaths(repoRoot);
+  const result: CostSummary = { totalCalls: 0, totalUsd: 0, bySkill: {}, windowDays: daysBack };
+  if (!existsSync(paths.costLog)) return result;
+  const cutoff = Date.now() - daysBack * 86400 * 1000;
+  for (const line of readFileSync(paths.costLog, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let row: { ts: string; skill: string; cost_estimate_usd: number };
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (Date.parse(row.ts) < cutoff) continue;
+    result.totalCalls++;
+    result.totalUsd += row.cost_estimate_usd;
+    if (!result.bySkill[row.skill]) result.bySkill[row.skill] = { calls: 0, usd: 0 };
+    const s = result.bySkill[row.skill]!;
+    s.calls++;
+    s.usd += row.cost_estimate_usd;
+  }
+  return result;
+}