@unbrained/pm-cli 2026.7.8 → 2026.7.10

package/dist/cli/commands/context.d.ts

@@ -3,6 +3,7 @@ import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js"
 import type { ContextDepth, ContextSectionName, ContextSettings, ItemFrontMatter, ItemStatus } from "../../types/index.js";
 import { type CalendarRow } from "./calendar.js";
 import { type CompactActivityEntry } from "./activity.js";
+import { type ContextRelevanceCandidate, type ContextRelevanceContributions, type ContextRelevanceReport, type ContextRelevanceSignalName } from "../../sdk/context-relevance.js";
 export declare const CONTEXT_OUTPUT_VALUES: readonly ["markdown", "toon", "json"];
 /**
  * Restricts context output format values accepted by command, SDK, and storage contracts.
@@ -32,6 +33,7 @@ export interface ContextOptions {
     activityLimit?: string;
     staleThreshold?: string;
     parent?: string;
+    explainRanking?: boolean;
     [key: string]: unknown;
 }
 /**
@@ -221,6 +223,19 @@ export interface ContextResult {
     /** Focus-row field subset requested via --fields; null/omitted means full rows. */
     focus_fields?: string[];
     warnings?: string[];
+    ranking?: ContextRankingSummary;
+}
+/** Compact explainability envelope shared by context and next JSON results. */
+export interface ContextRankingSummary {
+    model: string;
+    available_signals: ContextRelevanceSignalName[];
+    items: Array<{
+        id: string;
+        rank: number;
+        baseline_rank: number;
+        score: number;
+        contributions: ContextRelevanceContributions;
+    }>;
 }
 /**
  * Parses the comma-separated `--fields` value into a validated, de-duplicated
@@ -281,6 +296,14 @@ declare function normalizedParentId(value: unknown): string | null;
  * `pm next`) recommend work in the exact same sequence as `pm context`.
  */
 export declare function compareCriticalItems(left: ItemFrontMatter, right: ItemFrontMatter, statusRegistry: RuntimeStatusRegistry): number;
+/**
+ * Derives the metadata signals currently available on compact item rows. More
+ * expensive history/index/semantic signals can be added by an extension scorer
+ * without changing the public candidate contract.
+ */
+export declare function buildItemContextRelevanceCandidates(items: readonly ItemFrontMatter[], statusRegistry: RuntimeStatusRegistry, now: string, author: string | undefined): ContextRelevanceCandidate<ItemFrontMatter>[];
+/** Project a full scorer report onto the low-token command explanation shape. */
+export declare function toContextRankingSummary<TItem>(report: ContextRelevanceReport<TItem>): ContextRankingSummary;
 declare function completionPct(closed: number, total: number): number;
 /**
  * Indexes items by their parent id, yielding a parent→direct-children map used by

package/dist/cli/commands/context.js

@@ -4,10 +4,10 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!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]="d3d46914-7405-5ff8-9b6b-1fb5b466274b")}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]="4b85e6bf-047c-5f60-8b77-afe386ba8a10")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { compareTimestampStrings } from "../../core/shared/time.js";
+import { compareTimestampStrings, nowIso } from "../../core/shared/time.js";
 import { isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput } from "../../core/item/status.js";
 import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { resolvePmRoot } from "../../core/store/paths.js";
@@ -17,6 +17,7 @@ import { parseIntegerLimit } from "../shared-parsers.js";
 import { runCalendar } from "./calendar.js";
 import { runList } from "./list.js";
 import { runActivity } from "./activity.js";
+import { scoreContextCandidatesWithActiveExtensions, } from "../../sdk/context-relevance.js";
 // ---------------------------------------------------------------------------
 // Output format
 // ---------------------------------------------------------------------------
@@ -369,6 +370,89 @@ export 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 * 1000);
+    return deadlineDays <= 0 ? 1 : 1 / (1 + deadlineDays / 30);
+}
+function resolveRiskPressure(risk) {
+    const normalized = typeof risk === "string" ? risk.trim().toLowerCase() : undefined;
+    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 !== undefined &&
+        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,
+        },
+    };
+}
+/**
+ * Derives the metadata signals currently available on compact item rows. More
+ * expensive history/index/semantic signals can be added by an extension scorer
+ * without changing the public candidate contract.
+ */
+export 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,
+    }));
+}
+/** Project a full scorer report onto the low-token command explanation shape. */
+export 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 completionPct(closed, total) {
     return total > 0 ? Math.round((closed / total) * 100) : 0;
 }
@@ -1055,8 +1139,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)));
@@ -1080,6 +1166,7 @@ function resolveContextFocusGroups(listedFrontMatter, allItems, statusRegistry,
             ? blockedItems.slice(0, limit).map((item) => toContextFocusItem(item, statusRegistry, focusChildrenByParent))
             : [],
         blockedFallbackUsed,
+        ranking,
     };
 }
 async function buildContextAgenda(options, global, runtime, subtreeIds) {
@@ -1186,9 +1273,9 @@ function maybeAttachEmptyContextSuggestions(result, activeItems, blockedItems) {
 export 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({
@@ -1246,6 +1333,8 @@ export 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;
@@ -1253,4 +1342,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=d3d46914-7405-5ff8-9b6b-1fb5b466274b
+//# debugId=4b85e6bf-047c-5f60-8b77-afe386ba8a10