@unbrained/pm-cli 2026.7.9 → 2026.7.10

package/dist/cli-bundle/chunks/{chunk-UH6VFRV6.js → chunk-J3Z2JMDV.js}

@@ -6,13 +6,13 @@ import {
   deleteItem,
   readSettings,
   toItemRecord
-} from "./chunk-BPJ5NYSJ.js";
+} from "./chunk-F7UA74OZ.js";
 import {
   EXIT_CODE,
   getSettingsPath,
   pathExists,
   resolvePmRoot
-} from "./chunk-2BVD4ZD2.js";
+} from "./chunk-J3FDNQWM.js";
 
 // dist/cli/commands/delete.js
 import path from "node:path";
@@ -52,4 +52,4 @@ async function runDelete(id, options, global2) {
 export {
   runDelete
 };
-//# sourceMappingURL=chunk-UH6VFRV6.js.map
+//# sourceMappingURL=chunk-J3Z2JMDV.js.map

package/dist/cli-bundle/chunks/{chunk-2FKIIQMJ.js → chunk-JDEXIVKQ.js}

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aeca411c-81f3-59f5-a9aa-aec1f3098c77")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cbb6210e-994c-5872-8a50-8301cc4a8d62")}catch(e){}}();
 import {
   collectStaleVectorizationIds
 } from "./chunk-ROGZTCCB.js";
@@ -15,7 +15,7 @@ import {
   resolveContentFieldFilters,
   resolveMissingMetadataFilters,
   runList
-} from "./chunk-TI7QSUFK.js";
+} from "./chunk-6PBZBIS6.js";
 import {
   hasContentFieldFilter,
   itemMatchesContentFilters
@@ -23,21 +23,21 @@ import {
 import {
   collectBlockedByIds,
   computeActionabilityReport
-} from "./chunk-C3YU3TXX.js";
+} from "./chunk-L2SWAZ3S.js";
 import {
   hasMissingMetadataFilter,
   itemMatchesMissingMetadata,
   lifecycleClassifierFromStatusRegistry
-} from "./chunk-J6AD3GWC.js";
+} from "./chunk-JNELC5UO.js";
 import {
   readHistoryEntries
-} from "./chunk-6WCXSC5V.js";
+} from "./chunk-ZGDJA6WI.js";
 import {
   parseIntegerLimit,
   parseLimit,
   parsePriority,
   parseType
-} from "./chunk-6RR4XM5H.js";
+} from "./chunk-UYK26VRP.js";
 import {
   resolveRegisteredSearchProvider,
   resolveRegisteredVectorStoreAdapter
@@ -54,7 +54,7 @@ import {
   resolveSearchCorpusFields,
   resolveSettingsWithSemanticRuntimeDefaults,
   resolveVectorStores
-} from "./chunk-DBV5A7FT.js";
+} from "./chunk-DWGHHSDC.js";
 import {
   splitCommaList
 } from "./chunk-P4SESZGT.js";
@@ -78,8 +78,9 @@ import {
   readSettings,
   resolveIsoOrRelative,
   runActiveOnReadHooks,
+  runActiveServiceOverride,
   toItemRecord
-} from "./chunk-NTOOEVJ4.js";
+} from "./chunk-Y5Q4FEE4.js";
 import {
   CONTEXT_DEPTH_VALUES,
   CONTEXT_SECTION_VALUES,
@@ -102,7 +103,7 @@ import {
   toNonEmptyString,
   toNonEmptyStringOrUndefined,
   weekdayOrderIndex
-} from "./chunk-MFLLULHU.js";
+} from "./chunk-TB2CZJAQ.js";
 
 // dist/cli/commands/activity.js
 import fs from "node:fs/promises";
@@ -1458,6 +1459,264 @@ async function runCalendar(options, global) {
   };
 }
 
+// dist/sdk/context-relevance.js
+var CONTEXT_RELEVANCE_SIGNAL_NAMES = [
+  "structural",
+  "recency",
+  "activity_density",
+  "graph_proximity",
+  "claim_focus",
+  "priority_pressure",
+  "risk_pressure",
+  "deadline_pressure",
+  "knowledge_density",
+  "author_affinity",
+  "semantic_similarity"
+];
+var CONTEXT_RELEVANCE_SERVICE = "context_relevance";
+var DEFAULT_CONTEXT_RELEVANCE_WEIGHTS = {
+  structural: 0.4,
+  recency: 0.35,
+  activity_density: 0.25,
+  graph_proximity: 0.15,
+  claim_focus: 0.6,
+  priority_pressure: 0.35,
+  risk_pressure: 0.2,
+  deadline_pressure: 0.45,
+  knowledge_density: 0.25,
+  author_affinity: 0.2,
+  semantic_similarity: 0.5
+};
+var JSON_TOKEN_ENCODER = new TextEncoder();
+function assertCandidates(candidates) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (typeof candidate.id !== "string" || candidate.id.trim().length === 0 || ids.has(candidate.id)) {
+      throw new TypeError("Context relevance candidates require unique non-empty ids");
+    }
+    ids.add(candidate.id);
+    for (const [signal, value] of Object.entries(candidate.signals ?? {})) {
+      if (signal === "structural" || !CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal)) {
+        throw new TypeError(`Unknown context relevance signal: ${signal}`);
+      }
+      if (value === void 0)
+        continue;
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new TypeError(`Context relevance signal ${signal} must be a finite number from 0 to 1`);
+      }
+    }
+  }
+}
+function resolveWeights(overrides) {
+  const weights = { ...DEFAULT_CONTEXT_RELEVANCE_WEIGHTS };
+  for (const [signal, weight] of Object.entries(overrides ?? {})) {
+    if (weight !== void 0 && CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal)) {
+      weights[signal] = weight;
+    }
+  }
+  for (const [signal, weight] of Object.entries(weights)) {
+    if (!Number.isFinite(weight) || weight < 0) {
+      throw new TypeError(`Context relevance weight ${signal} must be a finite non-negative number`);
+    }
+  }
+  return weights;
+}
+function defaultScoreContextCandidates(candidates, options = {}) {
+  assertCandidates(candidates);
+  const weights = resolveWeights(options.weights);
+  const denominator = Math.max(candidates.length - 1, 1);
+  const available = /* @__PURE__ */ new Set(["structural"]);
+  for (const candidate of candidates) {
+    for (const [signal, value] of Object.entries(candidate.signals ?? {})) {
+      if (value !== void 0)
+        available.add(signal);
+    }
+  }
+  const availableSignals = CONTEXT_RELEVANCE_SIGNAL_NAMES.filter((signal) => available.has(signal));
+  const scored = candidates.map((candidate, index) => {
+    const signalValues = {
+      structural: candidates.length === 1 ? 1 : 1 - index / denominator,
+      ...candidate.signals
+    };
+    const contributions = {};
+    let weightedScore = 0;
+    let totalWeight = 0;
+    for (const signal of availableSignals) {
+      const value = signalValues[signal];
+      if (value === void 0)
+        continue;
+      const contribution = value * weights[signal];
+      contributions[signal] = contribution;
+      weightedScore += contribution;
+      totalWeight += weights[signal];
+    }
+    return {
+      ...candidate,
+      baseline_rank: index + 1,
+      rank: 0,
+      score: totalWeight === 0 ? 0 : weightedScore / totalWeight,
+      contributions
+    };
+  });
+  scored.sort((left, right) => right.score - left.score || left.baseline_rank - right.baseline_rank);
+  scored.forEach((entry, index) => {
+    entry.rank = index + 1;
+  });
+  return { model: "default-weighted-v1", available_signals: availableSignals, ranked: scored };
+}
+async function scoreContextCandidates(candidates, options = {}) {
+  const defaultReport = defaultScoreContextCandidates(candidates, options);
+  if (!options.scorer)
+    return defaultReport;
+  const customScores = await options.scorer({ candidates, default_report: defaultReport });
+  const scoreById = /* @__PURE__ */ new Map();
+  for (const entry of customScores) {
+    if (scoreById.has(entry.id) || !Number.isFinite(entry.score)) {
+      throw new TypeError("Context relevance scorer must return one finite score for every candidate");
+    }
+    scoreById.set(entry.id, entry.score);
+  }
+  if (scoreById.size !== candidates.length || candidates.some((candidate) => !scoreById.has(candidate.id))) {
+    throw new TypeError("Context relevance scorer must return one finite score for every candidate");
+  }
+  const ranked = defaultReport.ranked.map((entry) => {
+    const score = scoreById.get(entry.id);
+    return { ...entry, score, contributions: { custom: score } };
+  });
+  ranked.sort((left, right) => right.score - left.score || left.baseline_rank - right.baseline_rank);
+  ranked.forEach((entry, index) => {
+    entry.rank = index + 1;
+  });
+  return { model: "custom", available_signals: defaultReport.available_signals, ranked };
+}
+async function scoreContextCandidatesWithActiveExtensions(surface, candidates, options = {}) {
+  const defaultReport = defaultScoreContextCandidates(candidates, options);
+  const override = await runActiveServiceOverride(CONTEXT_RELEVANCE_SERVICE, {
+    surface,
+    candidates,
+    default_report: defaultReport
+  });
+  if (!override.handled) {
+    return override.warnings.length > 0 ? { ...defaultReport, warnings: override.warnings } : defaultReport;
+  }
+  if (!Array.isArray(override.result) || !override.result.every((entry) => typeof entry === "object" && entry !== null && typeof entry.id === "string" && typeof entry.score === "number" && Number.isFinite(entry.score))) {
+    return { ...defaultReport, warnings: [...override.warnings, "extension_context_relevance_invalid_result"] };
+  }
+  try {
+    const report = await scoreContextCandidates(candidates, {
+      ...options,
+      scorer: () => override.result
+    });
+    return override.warnings.length > 0 ? { ...report, warnings: override.warnings } : report;
+  } catch {
+    return { ...defaultReport, warnings: [...override.warnings, "extension_context_relevance_invalid_result"] };
+  }
+}
+var CONTEXT_EVALUATION_METRIC_NAMES = [
+  "ndcg",
+  "reciprocal_rank",
+  "required_recall",
+  "continuity_coverage",
+  "token_budget_adherence"
+];
+function ratioOfPresent(expected, actual) {
+  if (expected.length === 0)
+    return 1;
+  return expected.filter((id) => actual.has(id)).length / expected.length;
+}
+function evaluateContextRanking(input) {
+  if (!Number.isFinite(input.actual_tokens) || input.actual_tokens < 0 || !Number.isFinite(input.token_budget) || input.token_budget <= 0) {
+    throw new TypeError("Context ranking token counts require actual_tokens >= 0 and token_budget > 0");
+  }
+  const judgments = input.judgments ?? {};
+  const gains = input.ranked_ids.map((id) => Math.max(0, judgments[id] ?? 0));
+  const idealGains = Object.values(judgments).map((grade) => Math.max(0, grade)).sort((left, right) => right - left).slice(0, gains.length || 1);
+  const discountedGain = (values) => values.reduce((total, grade, index) => total + (2 ** grade - 1) / Math.log2(index + 2), 0);
+  const ideal = discountedGain(idealGains);
+  const firstRelevant = gains.findIndex((grade) => grade > 0);
+  const actualIds = new Set(input.ranked_ids);
+  const withinBudget = input.actual_tokens <= input.token_budget;
+  return {
+    ndcg: ideal === 0 ? 1 : discountedGain(gains) / ideal,
+    reciprocal_rank: firstRelevant < 0 ? 0 : 1 / (firstRelevant + 1),
+    required_recall: ratioOfPresent(input.required_ids ?? [], actualIds),
+    continuity_coverage: ratioOfPresent(input.continuity_ids ?? [], actualIds),
+    token_budget_adherence: withinBudget ? 1 : input.token_budget / input.actual_tokens,
+    within_token_budget: withinBudget
+  };
+}
+function estimateJsonTokens(value) {
+  return Math.ceil(JSON_TOKEN_ENCODER.encode(JSON.stringify(value)).byteLength / 4);
+}
+function roundEvaluationMetric(value) {
+  return Math.round(value * 1e4) / 1e4;
+}
+function rankingPayloadForScenario(result, surface) {
+  const rankedIds = surface === "context" ? [
+    ...result.high_level ?? [],
+    ...result.low_level ?? [],
+    ...result.blocked_fallback ?? []
+  ].map((item) => item.id) : (result.ready ?? []).map((item) => item.id);
+  const servedIds = new Set(rankedIds);
+  const attribution = (result.ranking?.items ?? []).filter((item) => servedIds.has(item.id)).map((item) => ({ id: item.id, contributions: item.contributions }));
+  return { rankedIds, attribution };
+}
+async function runContextEvaluationScenario(scenario, reader) {
+  if (scenario.id.trim().length === 0 || scenario.rationale.trim().length === 0) {
+    throw new TypeError("Context evaluation scenarios require non-empty id and rationale values");
+  }
+  const result = scenario.surface === "context" ? await reader.context({ ...scenario.options, explainRanking: true }) : await reader.next({ ...scenario.options, explainRanking: true });
+  const { rankedIds, attribution } = rankingPayloadForScenario(result, scenario.surface);
+  const packet = { ...result, ranking: void 0 };
+  const actualTokens = estimateJsonTokens(packet);
+  return {
+    id: scenario.id,
+    surface: scenario.surface,
+    rationale: scenario.rationale,
+    ranked_ids: rankedIds,
+    actual_tokens: actualTokens,
+    metrics: evaluateContextRanking({
+      ranked_ids: rankedIds,
+      judgments: scenario.judgments,
+      required_ids: scenario.required_ids,
+      continuity_ids: scenario.continuity_ids,
+      actual_tokens: actualTokens,
+      token_budget: scenario.token_budget
+    }),
+    attribution
+  };
+}
+function summarizeContextEvaluationReports(reports, thresholds) {
+  if (reports.length === 0) {
+    throw new TypeError("Context evaluation requires at least one scenario report");
+  }
+  const metrics = CONTEXT_EVALUATION_METRIC_NAMES;
+  for (const metric of metrics) {
+    if (!Number.isFinite(thresholds[metric])) {
+      throw new TypeError(`Context evaluation threshold ${metric} must be a finite number`);
+    }
+  }
+  const aggregate = Object.fromEntries(metrics.map((metric) => [
+    metric,
+    roundEvaluationMetric(reports.reduce((total, report) => total + report.metrics[metric], 0) / reports.length)
+  ]));
+  const failures = metrics.filter((metric) => aggregate[metric] < thresholds[metric]).map((metric) => `${metric}:${aggregate[metric]}<${thresholds[metric]}`);
+  return {
+    scenario_count: reports.length,
+    aggregate,
+    scenarios: [...reports],
+    passed: failures.length === 0,
+    failures
+  };
+}
+async function runContextEvaluationCorpus(scenarios, reader, thresholds) {
+  const reports = [];
+  for (const scenario of scenarios) {
+    reports.push(await runContextEvaluationScenario(scenario, reader));
+  }
+  return summarizeContextEvaluationReports(reports, thresholds);
+}
+
 // dist/cli/commands/context.js
 var CONTEXT_OUTPUT_VALUES = ["markdown", "toon", "json"];
 var HIGH_LEVEL_TYPES = /* @__PURE__ */ new Set(["Epic", "Feature"]);
@@ -1749,6 +2008,75 @@ function compareCriticalItems(left, right, statusRegistry) {
   const byId = left.id.localeCompare(right.id);
   return byUpdated !== 0 ? byUpdated : byId;
 }
+function normalizedPressure(value, maximum) {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseFloat(value) : Number.NaN;
+  if (!Number.isFinite(parsed))
+    return 0;
+  return 1 - Math.min(Math.max(parsed, 0), maximum) / maximum;
+}
+function resolveDeadlinePressure(deadline, nowMs) {
+  const deadlineMs = typeof deadline === "string" ? Date.parse(deadline) : deadline instanceof Date ? deadline.getTime() : typeof deadline === "number" ? deadline : Number.NaN;
+  if (!Number.isFinite(deadlineMs) || !Number.isFinite(nowMs))
+    return 0;
+  const deadlineDays = (deadlineMs - nowMs) / (24 * 60 * 60 * 1e3);
+  return deadlineDays <= 0 ? 1 : 1 / (1 + deadlineDays / 30);
+}
+function resolveRiskPressure(risk) {
+  const normalized = typeof risk === "string" ? risk.trim().toLowerCase() : void 0;
+  if (normalized === "critical" || normalized === "high")
+    return 1;
+  if (normalized === "medium")
+    return 0.5;
+  return normalized === "low" ? 0.1 : 0;
+}
+function buildItemContextRelevanceCandidate(item, params) {
+  const assignedToAuthor = params.normalizedAuthor !== void 0 && typeof item.assignee === "string" && item.assignee.trim().toLowerCase() === params.normalizedAuthor;
+  const claimFocus = isInProgressStatus(item.status, params.statusRegistry) ? 1 : assignedToAuthor ? 0.75 : 0;
+  const riskPressure = resolveRiskPressure(item.risk);
+  const knowledgeEntries = (item.comments?.length ?? 0) + (item.notes?.length ?? 0) + (item.learnings?.length ?? 0);
+  return {
+    id: item.id,
+    item,
+    signals: {
+      recency: params.itemCount === 1 ? 1 : 1 - params.recencyRank.get(item.id) / params.recencyDenominator,
+      graph_proximity: item.parent ? 0.3 : 0,
+      claim_focus: claimFocus,
+      priority_pressure: normalizedPressure(item.priority, 4),
+      risk_pressure: riskPressure,
+      deadline_pressure: resolveDeadlinePressure(item.deadline, params.nowMs),
+      knowledge_density: Math.min(knowledgeEntries / 5, 1),
+      author_affinity: assignedToAuthor ? 1 : 0
+    }
+  };
+}
+function buildItemContextRelevanceCandidates(items, statusRegistry, now, author) {
+  const recencyOrder = [...items].sort((left, right) => compareTimestampStrings(sortableTimestamp(right.updated_at), sortableTimestamp(left.updated_at)) || left.id.localeCompare(right.id));
+  const recencyRank = new Map(recencyOrder.map((item, index) => [item.id, index]));
+  const recencyDenominator = Math.max(items.length - 1, 1);
+  const normalizedAuthor = author?.trim().toLowerCase();
+  const nowMs = Date.parse(now);
+  return items.map((item) => buildItemContextRelevanceCandidate(item, {
+    statusRegistry,
+    nowMs,
+    normalizedAuthor,
+    recencyRank,
+    recencyDenominator,
+    itemCount: items.length
+  }));
+}
+function toContextRankingSummary(report) {
+  return {
+    model: report.model,
+    available_signals: report.available_signals,
+    items: report.ranked.map((entry) => ({
+      id: entry.id,
+      rank: entry.rank,
+      baseline_rank: entry.baseline_rank,
+      score: entry.score,
+      contributions: entry.contributions
+    }))
+  };
+}
 function completionPct2(closed, total) {
   return total > 0 ? Math.round(closed / total * 100) : 0;
 }
@@ -2334,8 +2662,10 @@ function resolveContextSubtreeIds(parentScope, fullCorpus) {
   }
   return subtree.ids;
 }
-function resolveContextFocusGroups(listedFrontMatter, allItems, statusRegistry, sectionsIncluded, limit) {
-  const ranked = [...listedFrontMatter].sort((left, right) => compareCriticalItems(left, right, statusRegistry));
+async function resolveContextFocusGroups(listedFrontMatter, allItems, statusRegistry, sectionsIncluded, limit, now, author) {
+  const structural = [...listedFrontMatter].sort((left, right) => compareCriticalItems(left, right, statusRegistry));
+  const ranking = await scoreContextCandidatesWithActiveExtensions("context", buildItemContextRelevanceCandidates(structural, statusRegistry, now, author));
+  const ranked = ranking.ranked.map((entry) => entry.item);
   const activeStatuses = statusRegistry.active_statuses;
   const activeItems = ranked.filter((item) => activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)));
   const blockedItems = ranked.filter((item) => statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(item.status, statusRegistry)));
@@ -2350,7 +2680,8 @@ function resolveContextFocusGroups(listedFrontMatter, allItems, statusRegistry,
     highLevel,
     lowLevel,
     blockedFallback: blockedFallbackUsed ? blockedItems.slice(0, limit).map((item) => toContextFocusItem(item, statusRegistry, focusChildrenByParent)) : [],
-    blockedFallbackUsed
+    blockedFallbackUsed,
+    ranking
   };
 }
 async function buildContextAgenda(options, global, runtime, subtreeIds) {
@@ -2450,9 +2781,9 @@ function maybeAttachEmptyContextSuggestions(result, activeItems, blockedItems) {
 async function runContext(options, global) {
   const runtime = await resolveContextRuntime(options, global);
   const corpus = await loadContextCorpus(options, global, runtime);
-  const focusGroups = resolveContextFocusGroups(corpus.listedFrontMatter, corpus.allItems, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit);
+  const focusGroups = await resolveContextFocusGroups(corpus.listedFrontMatter, corpus.allItems, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), process.env.PM_AUTHOR);
   const agendaContext = await buildContextAgenda(options, global, runtime, corpus.subtreeIds);
-  const warnings = mergeSortedWarnings(corpus.listed.warnings, agendaContext.agenda.warnings);
+  const warnings = mergeSortedWarnings(corpus.listed.warnings, agendaContext.agenda.warnings, focusGroups.ranking.warnings);
   const inProgressCount = countContextStatus(focusGroups.activeItems, normalizeStatusInput("in_progress", runtime.statusRegistry), runtime.statusRegistry);
   const openCount = countContextStatus(focusGroups.activeItems, normalizeStatusInput("open", runtime.statusRegistry), runtime.statusRegistry);
   const sections = await buildOptionalContextSections({
@@ -2510,6 +2841,8 @@ async function runContext(options, global) {
     }
   };
   attachOptionalContextSections(result, sections);
+  if (options.explainRanking === true)
+    result.ranking = toContextRankingSummary(focusGroups.ranking);
   applyContextFocusProjection(result, runtime.focusFields);
   if (warnings.length > 0)
     result.warnings = warnings;
@@ -5293,6 +5626,14 @@ function filterCandidatesByParentScope(candidates, corpus, parentScope) {
   }
   return candidates.filter((item) => subtree.ids.has(item.id.trim().toLowerCase()));
 }
+async function rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now) {
+  const concreteReady = rankedReady.filter((entry) => !hasCompletedDescendants(entry.item, childrenByParent));
+  const structuralReady = concreteReady.length > 0 ? concreteReady : rankedReady;
+  const ranking = await scoreContextCandidatesWithActiveExtensions("next", buildItemContextRelevanceCandidates(structuralReady.map((entry) => entry.item), statusRegistry, now, process.env.PM_AUTHOR));
+  const readyById = new Map(structuralReady.map((entry) => [entry.item.id, entry]));
+  const projectedReady = ranking.ranked.map((entry) => readyById.get(entry.id)).filter((entry) => entry !== void 0);
+  return { projectedReady, ranking, completedContainer: concreteReady.length === 0 };
+}
 async function runNext(options, global) {
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   const settings = await readSettings(pmRoot);
@@ -5310,8 +5651,7 @@ async function runNext(options, global) {
   const childrenByParent = buildChildrenByParent(corpus);
   const rankedReady = rankNextReadyEntries(report.ready, childrenByParent, statusRegistry);
   const rankedBlocked = [...report.blocked].sort((left, right) => compareCriticalItems(left.item, right.item, statusRegistry));
-  const concreteReady = rankedReady.filter((entry) => !hasCompletedDescendants(entry.item, childrenByParent));
-  const projectedReady = concreteReady.length > 0 ? concreteReady : rankedReady;
+  const { projectedReady, ranking: readyRanking, completedContainer } = await rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now);
   const readyRows = projectedReady.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));
   const blockedRows = rankedBlocked.map((entry) => toNextActionableItem(entry, statusRegistry, childrenByParent));
   const recommended = buildNextRecommendation({
@@ -5319,7 +5659,7 @@ async function runNext(options, global) {
     readyRows,
     statusRegistry,
     now,
-    completedContainer: concreteReady.length === 0
+    completedContainer
   });
   const result = {
     output_default: "toon",
@@ -5349,9 +5689,11 @@ async function runNext(options, global) {
       ready_only: readyOnly
     }
   };
-  const warnings = [.../* @__PURE__ */ new Set([...candidatesList.warnings ?? [], ...corpusList.warnings ?? []])].sort((a, b) => a.localeCompare(b));
+  const warnings = [.../* @__PURE__ */ new Set([...candidatesList.warnings ?? [], ...corpusList.warnings ?? [], ...readyRanking.warnings ?? []])].sort((a, b) => a.localeCompare(b));
   if (warnings.length > 0)
     result.warnings = warnings;
+  if (options.explainRanking === true)
+    result.ranking = toContextRankingSummary(readyRanking);
   result.suggestions = buildNextSuggestions(recommended, blockedRows);
   return result;
 }
@@ -5414,6 +5756,16 @@ export {
   renderCalendarMarkdown,
   renderCalendarToon,
   runCalendar,
+  CONTEXT_RELEVANCE_SIGNAL_NAMES,
+  CONTEXT_RELEVANCE_SERVICE,
+  defaultScoreContextCandidates,
+  scoreContextCandidates,
+  scoreContextCandidatesWithActiveExtensions,
+  CONTEXT_EVALUATION_METRIC_NAMES,
+  evaluateContextRanking,
+  runContextEvaluationScenario,
+  summarizeContextEvaluationReports,
+  runContextEvaluationCorpus,
   CONTEXT_OUTPUT_VALUES,
   resolveContextOutputFormat,
   renderContextMarkdown,
@@ -5429,6 +5781,6 @@ export {
   runNext,
   renderNextMarkdown
 };
-//# sourceMappingURL=chunk-2FKIIQMJ.js.map
+//# sourceMappingURL=chunk-JDEXIVKQ.js.map
 
-//# debugId=aeca411c-81f3-59f5-a9aa-aec1f3098c77
+//# debugId=cbb6210e-994c-5872-8a50-8301cc4a8d62