erdos-problems 0.2.0 → 0.2.2

package/src/commands/number-theory.js

@@ -0,0 +1,304 @@
+import { getProblem } from '../atlas/catalog.js';
+import {
+  buildNumberTheoryStatusSnapshot,
+  getNumberTheoryAtomSnapshot,
+  getNumberTheoryRouteSnapshot,
+  getNumberTheoryTicketSnapshot,
+} from '../runtime/number-theory.js';
+import { readCurrentProblem } from '../runtime/workspace.js';
+
+function resolveNumberTheoryProblem(problemId) {
+  const resolvedId = problemId ?? readCurrentProblem();
+  if (!resolvedId) {
+    return { error: 'Missing problem id and no active problem is selected.' };
+  }
+
+  const problem = getProblem(resolvedId);
+  if (!problem) {
+    return { error: `Unknown problem: ${resolvedId}` };
+  }
+
+  if (problem.cluster !== 'number-theory') {
+    return { error: `Problem ${resolvedId} is not in the number-theory pack.` };
+  }
+
+  return { problem };
+}
+
+function parseArgs(args) {
+  const parsed = {
+    problemId: null,
+    asJson: false,
+    entityId: null,
+  };
+
+  for (const token of args) {
+    if (token === '--json') {
+      parsed.asJson = true;
+      continue;
+    }
+    if (!parsed.problemId) {
+      parsed.problemId = token;
+      continue;
+    }
+    if (!parsed.entityId) {
+      parsed.entityId = token;
+      continue;
+    }
+    return { error: `Unknown number-theory option: ${token}` };
+  }
+
+  return parsed;
+}
+
+function printStatus(snapshot) {
+  console.log(`${snapshot.displayName} number-theory harness`);
+  console.log(`Family role: ${snapshot.familyRole}`);
+  console.log(`Harness profile: ${snapshot.harnessProfile}`);
+  console.log(`Site status: ${snapshot.siteStatus}`);
+  console.log(`Archive mode: ${snapshot.archiveMode ?? '(none)'}`);
+  console.log(`Active route: ${snapshot.activeRoute ?? '(none)'}`);
+  console.log(`Route breakthrough: ${snapshot.routeBreakthrough ? 'yes' : 'no'}`);
+  console.log(`Open problem: ${snapshot.openProblem ? 'yes' : 'no'}`);
+  console.log(`Problem solved: ${snapshot.problemSolved ? 'yes' : 'no'}`);
+  console.log(`Frontier label: ${snapshot.frontierLabel}`);
+  console.log(`Frontier detail: ${snapshot.frontierDetail}`);
+  console.log(`Checkpoint focus: ${snapshot.checkpointFocus ?? '(none)'}`);
+  console.log(`Next honest move: ${snapshot.nextHonestMove}`);
+  console.log(`Route packet present: ${snapshot.routePacketPresent ? 'yes' : 'no'}`);
+  if (snapshot.routePacket?.route_packet_id) {
+    console.log(`Route packet id: ${snapshot.routePacket.route_packet_id}`);
+  }
+  console.log(`Frontier note: ${snapshot.frontierNotePresent ? snapshot.frontierNotePath : '(missing)'}`);
+  console.log(`Route history: ${snapshot.routeHistoryPresent ? snapshot.routeHistoryPath : '(missing)'}`);
+  console.log(`Checkpoint template: ${snapshot.checkpointTemplatePresent ? snapshot.checkpointTemplatePath : '(missing)'}`);
+  console.log(`Report template: ${snapshot.reportTemplatePresent ? snapshot.reportTemplatePath : '(missing)'}`);
+  console.log(`Ops details present: ${snapshot.opsDetailsPresent ? 'yes' : 'no'}`);
+  console.log(`Active ticket: ${snapshot.activeTicketDetail?.ticket_id ?? '(none)'}`);
+  console.log(`Ready atoms: ${snapshot.readyAtomCount}`);
+  if (snapshot.firstReadyAtom) {
+    console.log(`First ready atom: ${snapshot.firstReadyAtom.atom_id} — ${snapshot.firstReadyAtom.title}`);
+  }
+}
+
+function printFrontier(snapshot) {
+  console.log(`${snapshot.displayName} number-theory frontier`);
+  console.log(`Active route: ${snapshot.activeRoute ?? '(none)'}`);
+  console.log(`Frontier label: ${snapshot.frontierLabel}`);
+  console.log(`Frontier detail: ${snapshot.frontierDetail}`);
+  console.log(`Checkpoint focus: ${snapshot.checkpointFocus ?? '(none)'}`);
+  console.log(`Next honest move: ${snapshot.nextHonestMove}`);
+  console.log(`Open problem: ${snapshot.openProblem ? 'yes' : 'no'}`);
+  console.log(`Archive mode: ${snapshot.archiveMode ?? '(none)'}`);
+  console.log(`Frontier note: ${snapshot.frontierNotePresent ? snapshot.frontierNotePath : '(missing)'}`);
+  console.log(`Route history: ${snapshot.routeHistoryPresent ? snapshot.routeHistoryPath : '(missing)'}`);
+}
+
+function printRoutes(snapshot) {
+  console.log(`${snapshot.displayName} number-theory routes`);
+  console.log(`Active route: ${snapshot.activeRoute ?? '(none)'}`);
+  if (!snapshot.opsDetails?.routes?.length) {
+    console.log('Routes: none recorded.');
+    return;
+  }
+  for (const route of snapshot.opsDetails.routes) {
+    const flags = [];
+    if (route.route_id === snapshot.activeRoute) {
+      flags.push('active');
+    }
+    if (route.status) {
+      flags.push(route.status);
+    }
+    console.log(`- ${route.route_id}${flags.length > 0 ? ` [${flags.join(', ')}]` : ''}`);
+    if (route.title) {
+      console.log(`  title: ${route.title}`);
+    }
+    if (route.summary) {
+      console.log(`  summary: ${route.summary}`);
+    }
+    if (route.why_now) {
+      console.log(`  why now: ${route.why_now}`);
+    }
+    if (route.next_move) {
+      console.log(`  next move: ${route.next_move}`);
+    }
+  }
+}
+
+function printTickets(snapshot) {
+  console.log(`${snapshot.displayName} number-theory tickets`);
+  if (!snapshot.opsDetails?.tickets?.length) {
+    console.log('Tickets: none recorded.');
+    return;
+  }
+  console.log(`Active ticket: ${snapshot.activeTicketDetail?.ticket_id ?? '(none)'}`);
+  for (const ticket of snapshot.opsDetails.tickets) {
+    const flags = [];
+    if (ticket.ticket_id === snapshot.activeTicketDetail?.ticket_id) {
+      flags.push('active');
+    }
+    if (ticket.status) {
+      flags.push(ticket.status);
+    }
+    console.log(`- ${ticket.ticket_id}${flags.length > 0 ? ` [${flags.join(', ')}]` : ''}`);
+    if (ticket.title) {
+      console.log(`  title: ${ticket.title}`);
+    }
+    if (ticket.summary) {
+      console.log(`  summary: ${ticket.summary}`);
+    }
+    if (ticket.current_blocker) {
+      console.log(`  blocker: ${ticket.current_blocker}`);
+    }
+    if (ticket.next_move) {
+      console.log(`  next move: ${ticket.next_move}`);
+    }
+  }
+}
+
+function printRouteDetail(snapshot) {
+  const route = snapshot.routeDetail;
+  console.log(`${snapshot.displayName} number-theory route ${snapshot.routeId}`);
+  console.log(`Title: ${route.title ?? snapshot.routeId}`);
+  console.log(`Status: ${route.status ?? '(unknown)'}`);
+  console.log(`Active route: ${route.route_id === snapshot.activeRoute ? 'yes' : 'no'}`);
+  console.log(`Summary: ${route.summary ?? '(none)'}`);
+  console.log(`Why now: ${route.why_now ?? '(none)'}`);
+  console.log(`Next move: ${route.next_move ?? '(none)'}`);
+  if (Array.isArray(route.ticket_ids) && route.ticket_ids.length > 0) {
+    console.log(`Tickets: ${route.ticket_ids.join(', ')}`);
+  }
+}
+
+function printTicketDetail(snapshot) {
+  const ticket = snapshot.ticketDetail;
+  console.log(`${snapshot.displayName} number-theory ticket ${snapshot.ticketId}`);
+  console.log(`Title: ${ticket.title ?? snapshot.ticketId}`);
+  console.log(`Status: ${ticket.status ?? '(unknown)'}`);
+  console.log(`Active ticket: ${ticket.ticket_id === snapshot.activeTicketDetail?.ticket_id ? 'yes' : 'no'}`);
+  console.log(`Summary: ${ticket.summary ?? '(none)'}`);
+  console.log(`Current blocker: ${ticket.current_blocker ?? '(none)'}`);
+  console.log(`Next move: ${ticket.next_move ?? '(none)'}`);
+  if (Array.isArray(ticket.atom_ids) && ticket.atom_ids.length > 0) {
+    console.log(`Atoms: ${ticket.atom_ids.join(', ')}`);
+  }
+}
+
+function printAtomDetail(snapshot) {
+  const atom = snapshot.atomDetail;
+  console.log(`${snapshot.displayName} number-theory atom ${snapshot.atomId}`);
+  console.log(`Title: ${atom.title ?? snapshot.atomId}`);
+  console.log(`Status: ${atom.status ?? '(unknown)'}`);
+  console.log(`Current frontier atom: ${atom.atom_id === snapshot.firstReadyAtom?.atom_id ? 'yes' : 'no'}`);
+  console.log(`Summary: ${atom.summary ?? '(none)'}`);
+  console.log(`Next move: ${atom.next_move ?? '(none)'}`);
+}
+
+export function runNumberTheoryCommand(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === 'help' || subcommand === '--help') {
+    console.log('Usage:');
+    console.log('  erdos number-theory status [<id>] [--json]');
+    console.log('  erdos number-theory frontier [<id>] [--json]');
+    console.log('  erdos number-theory routes [<id>] [--json]');
+    console.log('  erdos number-theory tickets [<id>] [--json]');
+    console.log('  erdos number-theory route <problem-id> <route-id> [--json]');
+    console.log('  erdos number-theory ticket <problem-id> <ticket-id> [--json]');
+    console.log('  erdos number-theory atom <problem-id> <atom-id> [--json]');
+    return 0;
+  }
+
+  if (!['status', 'frontier', 'routes', 'tickets', 'route', 'ticket', 'atom'].includes(subcommand)) {
+    console.error(`Unknown number-theory subcommand: ${subcommand}`);
+    return 1;
+  }
+
+  const parsed = parseArgs(rest);
+  if (parsed.error) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  const { problem, error } = resolveNumberTheoryProblem(parsed.problemId);
+  if (error) {
+    console.error(error);
+    return 1;
+  }
+
+  if (subcommand === 'route') {
+    if (!parsed.entityId) {
+      console.error('Missing route id.');
+      return 1;
+    }
+    const snapshot = getNumberTheoryRouteSnapshot(problem, parsed.entityId);
+    if (!snapshot) {
+      console.error(`Unknown number-theory route: ${parsed.entityId}`);
+      return 1;
+    }
+    if (parsed.asJson) {
+      console.log(JSON.stringify(snapshot, null, 2));
+      return 0;
+    }
+    printRouteDetail(snapshot);
+    return 0;
+  }
+
+  if (subcommand === 'ticket') {
+    if (!parsed.entityId) {
+      console.error('Missing ticket id.');
+      return 1;
+    }
+    const snapshot = getNumberTheoryTicketSnapshot(problem, parsed.entityId);
+    if (!snapshot) {
+      console.error(`Unknown number-theory ticket: ${parsed.entityId}`);
+      return 1;
+    }
+    if (parsed.asJson) {
+      console.log(JSON.stringify(snapshot, null, 2));
+      return 0;
+    }
+    printTicketDetail(snapshot);
+    return 0;
+  }
+
+  if (subcommand === 'atom') {
+    if (!parsed.entityId) {
+      console.error('Missing atom id.');
+      return 1;
+    }
+    const snapshot = getNumberTheoryAtomSnapshot(problem, parsed.entityId);
+    if (!snapshot) {
+      console.error(`Unknown number-theory atom: ${parsed.entityId}`);
+      return 1;
+    }
+    if (parsed.asJson) {
+      console.log(JSON.stringify(snapshot, null, 2));
+      return 0;
+    }
+    printAtomDetail(snapshot);
+    return 0;
+  }
+
+  const snapshot = buildNumberTheoryStatusSnapshot(problem);
+  if (parsed.asJson) {
+    console.log(JSON.stringify(snapshot, null, 2));
+    return 0;
+  }
+
+  if (subcommand === 'frontier') {
+    printFrontier(snapshot);
+    return 0;
+  }
+  if (subcommand === 'routes') {
+    printRoutes(snapshot);
+    return 0;
+  }
+  if (subcommand === 'tickets') {
+    printTickets(snapshot);
+    return 0;
+  }
+
+  printStatus(snapshot);
+  return 0;
+}

package/src/commands/pull.js

@@ -45,7 +45,7 @@ function inferClusterFromUpstream(upstreamRecord) {
 function parsePullArgs(args) {
   const [kind, value, ...rest] = args;
   if (!['problem', 'artifacts', 'literature'].includes(kind)) {
-    return { error: 'Usage: erdos pull problem|artifacts|literature <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream]' };
+    return { error: 'Usage: erdos pull problem|artifacts|literature <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream] [--json]' };
   }
 
   let destination = null;
@@ -54,6 +54,7 @@ function parsePullArgs(args) {
   let includeCrossref = false;
   let includeOpenAlex = false;
   let refreshUpstream = false;
+  let asJson = false;
 
   for (let index = 0; index < rest.length; index += 1) {
     const token = rest[index];
@@ -85,6 +86,10 @@ function parsePullArgs(args) {
       refreshUpstream = true;
       continue;
     }
+    if (token === '--json') {
+      asJson = true;
+      continue;
+    }
     return { error: `Unknown pull option: ${token}` };
   }
 
@@ -97,6 +102,7 @@ function parsePullArgs(args) {
     includeCrossref,
     includeOpenAlex,
     refreshUpstream,
+    asJson,
   };
 }
 
@@ -530,9 +536,9 @@ export async function runPullCommand(args, options = {}) {
   if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {
     if (!silent) {
       console.log('Usage:');
-      console.log('  erdos pull problem <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream]');
-      console.log('  erdos pull artifacts <id> [--dest <path>] [--refresh-upstream]');
-      console.log('  erdos pull literature <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream]');
+      console.log('  erdos pull problem <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream] [--json]');
+      console.log('  erdos pull artifacts <id> [--dest <path>] [--refresh-upstream] [--json]');
+      console.log('  erdos pull literature <id> [--dest <path>] [--include-site] [--include-public-search] [--include-crossref] [--include-openalex] [--refresh-upstream] [--json]');
     }
     return 0;
   }
@@ -571,6 +577,17 @@ export async function runPullCommand(args, options = {}) {
       ? path.resolve(parsed.destination)
       : getWorkspaceProblemArtifactDir(parsed.problemId);
     const result = writeArtifactsLane(String(parsed.problemId), destination, localProblem, upstreamRecord, snapshot);
+    if (parsed.asJson) {
+      console.log(JSON.stringify({
+        kind: 'artifacts',
+        problemId: String(parsed.problemId),
+        destination,
+        localProblemIncluded: Boolean(localProblem),
+        upstreamRecordIncluded: Boolean(upstreamRecord),
+        artifactsCopied: result.copiedArtifacts?.length ?? result.artifactsCopied ?? 0,
+      }, null, 2));
+      return 0;
+    }
     if (!silent) {
       console.log(`Artifact bundle created: ${destination}`);
       console.log(`Local canonical dossier included: ${localProblem ? 'yes' : 'no'}`);
@@ -594,6 +611,24 @@ export async function runPullCommand(args, options = {}) {
       parsed.includeCrossref,
       parsed.includeOpenAlex,
     );
+    if (parsed.asJson) {
+      console.log(JSON.stringify({
+        kind: 'literature',
+        problemId: String(parsed.problemId),
+        destination,
+        localProblemIncluded: Boolean(localProblem),
+        upstreamRecordIncluded: Boolean(upstreamRecord),
+        includedSiteSnapshot: result.siteStatus.included,
+        siteStatusError: result.siteStatus.error,
+        includedPublicSearch: result.publicSearch.included,
+        publicSearchError: result.publicSearch.error,
+        includedCrossref: result.crossref.included,
+        crossrefError: result.crossref.error,
+        includedOpenAlex: result.openalex.included,
+        openAlexError: result.openalex.error,
+      }, null, 2));
+      return 0;
+    }
     if (!silent) {
       console.log(`Literature bundle created: ${destination}`);
       console.log(`Local dossier context included: ${localProblem ? 'yes' : 'no'}`);
@@ -662,6 +697,23 @@ export async function runPullCommand(args, options = {}) {
     openAlexError: literatureResult.openalex.error,
   });
 
+  if (parsed.asJson) {
+    console.log(JSON.stringify({
+      kind: 'problem',
+      problemId: String(parsed.problemId),
+      destination: rootDestination,
+      artifactsDir: artifactDestination,
+      literatureDir: literatureDestination,
+      localProblemIncluded: Boolean(localProblem),
+      upstreamRecordIncluded: Boolean(upstreamRecord),
+      includedSiteSnapshot: literatureResult.siteStatus.included,
+      includedPublicSearch: literatureResult.publicSearch.included,
+      includedCrossref: literatureResult.crossref.included,
+      includedOpenAlex: literatureResult.openalex.included,
+    }, null, 2));
+    return 0;
+  }
+
   if (!silent) {
     console.log(`Pull bundle created: ${rootDestination}`);
     console.log(`Artifact lane: ${artifactDestination}`);

package/src/commands/workspace.js

@@ -1,10 +1,12 @@
 import { getProblem } from '../atlas/catalog.js';
 import { loadConfig } from '../runtime/config.js';
+import { buildGraphTheoryStatusSnapshot } from '../runtime/graph-theory.js';
+import { buildNumberTheoryStatusSnapshot } from '../runtime/number-theory.js';
 import { buildSunflowerStatusSnapshot } from '../runtime/sunflower.js';
 import { getWorkspaceSummary } from '../runtime/workspace.js';
 
 export function runWorkspaceCommand(args) {
-  const [subcommand] = args;
+  const [subcommand, ...rest] = args;
 
   if (!subcommand || subcommand === 'help' || subcommand === '--help') {
     console.log('Usage:');
@@ -17,8 +19,30 @@ export function runWorkspaceCommand(args) {
     return 1;
   }
 
+  const asJson = rest.includes('--json');
+
   const summary = getWorkspaceSummary();
   const config = loadConfig();
+  if (asJson) {
+    const payload = {
+      ...summary,
+      preferredAgent: config.preferredAgent,
+    };
+    if (summary.activeProblem) {
+      const problem = getProblem(summary.activeProblem);
+      if (problem?.cluster === 'sunflower') {
+        payload.sunflower = buildSunflowerStatusSnapshot(problem);
+      }
+      if (problem?.cluster === 'number-theory') {
+        payload.numberTheory = buildNumberTheoryStatusSnapshot(problem);
+      }
+      if (problem?.cluster === 'graph-theory') {
+        payload.graphTheory = buildGraphTheoryStatusSnapshot(problem);
+      }
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    return 0;
+  }
   console.log(`Workspace root: ${summary.workspaceRoot}`);
   console.log(`State dir: ${summary.stateDir}`);
   console.log(`Initialized: ${summary.hasState ? 'yes' : 'no'}`);
@@ -76,6 +100,36 @@ export function runWorkspaceCommand(args) {
       }
       console.log(`Sunflower compute next: ${sunflower.computeNextAction}`);
     }
+    if (problem?.cluster === 'number-theory') {
+      const numberTheory = buildNumberTheoryStatusSnapshot(problem);
+      console.log(`Number-theory family role: ${numberTheory.familyRole ?? '(none)'}`);
+      console.log(`Number-theory harness profile: ${numberTheory.harnessProfile ?? '(none)'}`);
+      console.log(`Number-theory route: ${numberTheory.activeRoute ?? '(none)'}`);
+      console.log(`Number-theory frontier: ${numberTheory.frontierDetail ?? '(none)'}`);
+      console.log(`Number-theory frontier note: ${numberTheory.frontierNotePath ?? '(none)'}`);
+      console.log(`Number-theory route history: ${numberTheory.routeHistoryPath ?? '(none)'}`);
+      console.log(`Number-theory archive mode: ${numberTheory.archiveMode ?? '(none)'}`);
+      console.log(`Number-theory active ticket: ${numberTheory.activeTicketDetail?.ticket_id ?? '(none)'}`);
+      console.log(`Number-theory ready atoms: ${numberTheory.readyAtomCount}`);
+      if (numberTheory.firstReadyAtom) {
+        console.log(`Number-theory first ready atom: ${numberTheory.firstReadyAtom.atom_id} — ${numberTheory.firstReadyAtom.title}`);
+      }
+    }
+    if (problem?.cluster === 'graph-theory') {
+      const graphTheory = buildGraphTheoryStatusSnapshot(problem);
+      console.log(`Graph-theory family role: ${graphTheory.familyRole ?? '(none)'}`);
+      console.log(`Graph-theory harness profile: ${graphTheory.harnessProfile ?? '(none)'}`);
+      console.log(`Graph-theory route: ${graphTheory.activeRoute ?? '(none)'}`);
+      console.log(`Graph-theory frontier: ${graphTheory.frontierDetail ?? '(none)'}`);
+      console.log(`Graph-theory frontier note: ${graphTheory.frontierNotePath ?? '(none)'}`);
+      console.log(`Graph-theory route history: ${graphTheory.routeHistoryPath ?? '(none)'}`);
+      console.log(`Graph-theory archive mode: ${graphTheory.archiveMode ?? '(none)'}`);
+      console.log(`Graph-theory active ticket: ${graphTheory.activeTicketDetail?.ticket_id ?? '(none)'}`);
+      console.log(`Graph-theory ready atoms: ${graphTheory.readyAtomCount}`);
+      if (graphTheory.firstReadyAtom) {
+        console.log(`Graph-theory first ready atom: ${graphTheory.firstReadyAtom.atom_id} — ${graphTheory.firstReadyAtom.title}`);
+      }
+    }
   }
   return 0;
 }

package/src/runtime/graph-theory.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { getPackProblemDir } from './paths.js';
+
+function readYamlIfPresent(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function getPackFile(problemId, fileName) {
+  return path.join(getPackProblemDir('graph-theory', problemId), fileName);
+}
+
+function normalizeQuestionLedger(rawLedger) {
+  return {
+    openQuestions: rawLedger?.open_questions ?? [],
+    activeRouteNotes: rawLedger?.active_route_notes ?? [],
+    routeBreakthroughs: rawLedger?.route_breakthroughs ?? [],
+    problemSolved: rawLedger?.problem_solved ?? [],
+  };
+}
+
+function parseOpsDetails(problemId) {
+  const opsDetailsPath = getPackFile(problemId, 'OPS_DETAILS.yaml');
+  const payload = readYamlIfPresent(opsDetailsPath);
+  if (!payload) {
+    return null;
+  }
+  return {
+    packetId: payload.packet_id ?? null,
+    summary: payload.summary ?? null,
+    path: opsDetailsPath,
+    routes: payload.routes ?? [],
+    tickets: payload.tickets ?? [],
+    atoms: payload.atoms ?? [],
+  };
+}
+
+function findRouteDetail(opsDetails, routeId) {
+  if (!opsDetails || !Array.isArray(opsDetails.routes)) {
+    return null;
+  }
+  return opsDetails.routes.find((route) => route.route_id === routeId) ?? null;
+}
+
+function firstMatching(items, predicate) {
+  if (!Array.isArray(items)) {
+    return null;
+  }
+  return items.find(predicate) ?? items[0] ?? null;
+}
+
+function resolveArchiveMode(problem) {
+  const siteStatus = String(problem.siteStatus ?? '').toLowerCase();
+  if (siteStatus === 'solved') {
+    return 'method_exemplar';
+  }
+  if (siteStatus === 'proved' || siteStatus === 'proved (lean)') {
+    return 'proof_archive';
+  }
+  if (siteStatus === 'decidable') {
+    return 'decision_archive';
+  }
+  return null;
+}
+
+function solvedLikeSiteStatus(problem) {
+  const siteStatus = String(problem.siteStatus ?? '').toLowerCase();
+  return siteStatus === 'solved' || siteStatus === 'proved' || siteStatus === 'proved (lean)';
+}
+
+export function buildGraphTheoryStatusSnapshot(problem) {
+  const contextPath = getPackFile(problem.problemId, 'context.yaml');
+  const contextMarkdownPath = getPackFile(problem.problemId, 'CONTEXT.md');
+  const routePacketPath = getPackFile(problem.problemId, 'ROUTE_PACKET.yaml');
+  const frontierNotePath = getPackFile(problem.problemId, 'FRONTIER_NOTE.md');
+  const routeHistoryPath = getPackFile(problem.problemId, 'ROUTE_HISTORY.md');
+  const checkpointTemplatePath = getPackFile(problem.problemId, 'CHECKPOINT_TEMPLATE.md');
+  const reportTemplatePath = getPackFile(problem.problemId, 'REPORT_TEMPLATE.md');
+
+  const context = readYamlIfPresent(contextPath) ?? {};
+  const routePacket = readYamlIfPresent(routePacketPath);
+  const opsDetails = parseOpsDetails(problem.problemId);
+
+  const activeRoute =
+    problem.researchState?.active_route
+    ?? context.default_active_route
+    ?? routePacket?.route_id
+    ?? null;
+  const archiveMode = resolveArchiveMode(problem);
+  const problemSolved = typeof problem.researchState?.problem_solved === 'boolean'
+    ? problem.researchState.problem_solved
+    : solvedLikeSiteStatus(problem);
+  const openProblem = typeof problem.researchState?.open_problem === 'boolean'
+    ? problem.researchState.open_problem
+    : String(problem.siteStatus ?? '').toLowerCase() === 'open';
+  const routeBreakthrough = typeof problem.researchState?.route_breakthrough === 'boolean'
+    ? problem.researchState.route_breakthrough
+    : problemSolved;
+
+  const activeRouteDetail = findRouteDetail(opsDetails, activeRoute) ?? firstMatching(opsDetails?.routes, () => true);
+  const activeTicketDetail = firstMatching(
+    opsDetails?.tickets,
+    (ticket) => ticket.status === 'active' && (!activeRoute || ticket.route_id === activeRoute),
+  );
+  const firstReadyAtom = firstMatching(
+    opsDetails?.atoms,
+    (atom) => atom.status === 'ready' && (!activeRoute || atom.route_id === activeRoute),
+  );
+  const readyAtoms = Array.isArray(opsDetails?.atoms)
+    ? opsDetails.atoms.filter((atom) => atom.status === 'ready')
+    : [];
+
+  return {
+    generatedAt: new Date().toISOString(),
+    problemId: problem.problemId,
+    displayName: problem.displayName,
+    title: problem.title,
+    cluster: problem.cluster,
+    familyRole: context.family_role ?? 'graph_theory_pack',
+    harnessProfile: context.harness_profile ?? 'starter_cockpit',
+    activeRoute,
+    routeBreakthrough,
+    problemSolved,
+    openProblem,
+    siteStatus: problem.siteStatus,
+    archiveMode,
+    bootstrapFocus: context.bootstrap_focus ?? null,
+    routeStory: context.route_story ?? routePacket?.frontier_claim ?? problem.shortStatement,
+    frontierLabel: context.frontier_label ?? activeRoute ?? 'graph_theory_frontier',
+    frontierDetail: firstReadyAtom?.summary ?? context.frontier_detail ?? activeRouteDetail?.summary ?? problem.shortStatement,
+    checkpointFocus: context.checkpoint_focus ?? activeRouteDetail?.why_now ?? null,
+    nextHonestMove:
+      firstReadyAtom?.next_move
+      ?? activeTicketDetail?.next_move
+      ?? context.next_honest_move
+      ?? 'Freeze the current graph-theory packet without widening status claims.',
+    relatedCoreProblems: context.related_core_problems ?? [],
+    literatureFocus: context.literature_focus ?? [],
+    artifactFocus: context.artifact_focus ?? [],
+    questionLedger: normalizeQuestionLedger(context.question_ledger),
+    contextPresent: fs.existsSync(contextPath),
+    contextPath,
+    contextMarkdownPath,
+    routePacketPresent: Boolean(routePacket),
+    routePacket,
+    routePacketPath,
+    frontierNotePresent: fs.existsSync(frontierNotePath),
+    frontierNotePath,
+    routeHistoryPresent: fs.existsSync(routeHistoryPath),
+    routeHistoryPath,
+    checkpointTemplatePresent: fs.existsSync(checkpointTemplatePath),
+    checkpointTemplatePath,
+    reportTemplatePresent: fs.existsSync(reportTemplatePath),
+    reportTemplatePath,
+    opsDetailsPresent: Boolean(opsDetails),
+    opsDetailsPath: opsDetails?.path ?? getPackFile(problem.problemId, 'OPS_DETAILS.yaml'),
+    opsDetails,
+    activeRouteDetail,
+    activeTicketDetail,
+    firstReadyAtom,
+    readyAtomCount: readyAtoms.length,
+  };
+}