ralph-hero-mcp-server 2.5.73 → 2.5.75

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerProjectTools } from "./tools/project-tools.js";
 import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
 import { registerDashboardTools } from "./tools/dashboard-tools.js";
+import { registerDirectionsTools } from "./tools/directions-tools.js";
 import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
@@ -386,6 +387,8 @@ async function main() {
     registerRelationshipTools(server, client, fieldCache);
     // Dashboard and pipeline visualization tools
     registerDashboardTools(server, client, fieldCache);
+    // Hello directions tool — deterministic ranked action items
+    registerDirectionsTools(server, client, fieldCache);
     // Phase 5: Batch operations
     registerBatchTools(server, client, fieldCache);
     // Project management tools (archive, remove, add, link repo, clear field)

package/dist/lib/directions.js

@@ -0,0 +1,449 @@
+/**
+ * Pure ranker library for the `ralph_hero__hello_directions` MCP tool.
+ *
+ * Computes up to N deterministic directions for a session-briefing
+ * companion. All functions are side-effect free: time is injected via
+ * `RankConfig.now`, no Date.now() / Math.random() are called inside the
+ * module. Inputs are arrays of `DashboardItem` (already fetched + shaped
+ * by `tools/dashboard-tools.ts`) plus an optional list of open PRs.
+ *
+ * Ranking algorithm (lower score wins):
+ *
+ *   score(item) =
+ *       priorityScore(item.priority)       // P0=0, P1=10, P2=20, P3=30, none=99
+ *     + phaseScore(item.workflowState)     // Plan in Review=0, In Review=1, Ready for Plan=2, Research Needed=3
+ *     + staleBoost(item, now)              // -50 if non-lock state with updatedAt > stuckThresholdHours
+ *     + lockStaleBoost(item, now)          // -100 if lock state with updatedAt > lockStaleHours
+ *     + treeContinueBoost(item, allItems)  // -75 if tree-continue criteria match
+ *
+ *   candidates = items
+ *     .filter(actionable phase OR lock-stale)
+ *     .filter(no open trackedIssues blocking)        // unless candidate would be empty
+ *     .sort(by score ascending)
+ *     .promote(tree-continue from top-5 to slot 2 if not slot 1)
+ *     .merge(open PR scores)
+ *     .slice(config.limit)
+ *
+ * Kind precedence per item: lock-stale > tree-continue > issue.
+ * PRs are scored separately and only merged into the final ranking.
+ */
+import { LOCK_STATES, STATE_ORDER } from "./workflow-states.js";
+export const DEFAULT_RANK_CONFIG = {
+    limit: 3,
+    stuckThresholdHours: 48,
+    lockStaleHours: 24,
+    treeRecentDoneDays: 7,
+    prStaleHours: 24,
+};
+// ---------------------------------------------------------------------------
+// Internal scoring constants
+// ---------------------------------------------------------------------------
+const ACTIONABLE_PHASES = new Set([
+    "Plan in Review",
+    "In Review",
+    "Ready for Plan",
+    "Research Needed",
+]);
+const PHASE_RANK = {
+    "Plan in Review": 0,
+    "In Review": 1,
+    "Ready for Plan": 2,
+    "Research Needed": 3,
+};
+const PRIORITY_RANK = {
+    P0: 0,
+    P1: 10,
+    P2: 20,
+    P3: 30,
+};
+const STALE_BOOST = -50;
+const LOCK_STALE_BOOST = -100;
+const TREE_CONTINUE_BOOST = -75;
+const PR_REVIEW_REQUIRED_BOOST = -200;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function priorityScore(p) {
+    if (p === null)
+        return 99;
+    return PRIORITY_RANK[p] ?? 99;
+}
+function phaseScore(state) {
+    if (state === null)
+        return 99;
+    const explicit = PHASE_RANK[state];
+    if (explicit !== undefined)
+        return explicit;
+    // Fallback: for actionable phases not in the explicit table, use their
+    // STATE_ORDER position as a coarse tiebreaker so newly-added states
+    // still rank reasonably without code changes.
+    const idx = STATE_ORDER.indexOf(state);
+    return idx >= 0 ? 50 + idx : 99;
+}
+function ageHours(updatedAt, now) {
+    const t = new Date(updatedAt).getTime();
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, (now.getTime() - t) / HOUR_MS);
+}
+function ageDays(updatedAt, now) {
+    const t = new Date(updatedAt).getTime();
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, (now.getTime() - t) / DAY_MS);
+}
+function hasOpenBlockers(item) {
+    return item.blockedBy.some((b) => b.workflowState !== "Done" && b.workflowState !== "Canceled");
+}
+function isLockState(state) {
+    return state !== null && LOCK_STATES.includes(state);
+}
+// ---------------------------------------------------------------------------
+// Detection helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when the candidate is in a lock state and its updatedAt
+ * timestamp is older than `config.lockStaleHours`. These items are surfaced
+ * as `kind: "lock-stale"` so the user is reminded to unstick them.
+ */
+export function detectLockStale(item, config) {
+    if (!isLockState(item.workflowState))
+        return false;
+    return ageHours(item.updatedAt, config.now) >= config.lockStaleHours;
+}
+/**
+ * Returns true when the candidate participates in an "active tree" — i.e.
+ * something in its sibling group recently moved or it itself moved while
+ * other siblings remain open. False when there is no parent edge or the
+ * parent is closed (CLOSED state means tree is finished).
+ *
+ * Criteria (any one positive):
+ *   (a) A sibling has closedAt within `treeRecentDoneDays`.
+ *   (b) The candidate itself has updatedAt within `treeRecentDoneDays`,
+ *       its parent is open, and at least one other open sibling exists.
+ */
+export function detectTreeContinue(item, allItems, config) {
+    const parent = item.parentNumber ?? null;
+    if (parent === null || parent === undefined)
+        return false;
+    // Parent done -> tree is finished, do not surface.
+    // GitHub raw state arrives as "OPEN" / "CLOSED"; defensively also accept
+    // workflow-state strings.
+    const parentState = item.parentState ?? null;
+    if (parentState === "CLOSED" ||
+        parentState === "Done" ||
+        parentState === "Canceled") {
+        return false;
+    }
+    const siblings = allItems.filter((other) => other.number !== item.number && other.parentNumber === parent);
+    // (a) sibling closed within window
+    for (const sib of siblings) {
+        if (sib.closedAt) {
+            const days = ageDays(sib.closedAt, config.now);
+            if (days <= config.treeRecentDoneDays)
+                return true;
+        }
+    }
+    // (b) candidate moved recently AND has open siblings
+    const candidateRecentlyMoved = ageDays(item.updatedAt, config.now) <= config.treeRecentDoneDays;
+    if (!candidateRecentlyMoved)
+        return false;
+    const openSiblings = siblings.filter((sib) => sib.closedAt === null &&
+        sib.workflowState !== "Done" &&
+        sib.workflowState !== "Canceled");
+    return openSiblings.length > 0;
+}
+// ---------------------------------------------------------------------------
+// scoreIssue
+// ---------------------------------------------------------------------------
+/**
+ * Score a single dashboard item. Returns the winning kind for this candidate
+ * in precedence order:
+ *
+ *   detectLockStale(item) -> kind: "lock-stale"
+ *   else detectTreeContinue(item) -> kind: "tree-continue"
+ *   else -> kind: "issue"
+ *
+ * `tags[]` carries descriptive signals (e.g. "stale", "high-priority",
+ * "blocked") that did NOT win the kind slot but still shape the prose
+ * `reason` rendered by `buildReason`.
+ *
+ * PR ranking is handled separately by `rankDirections` — this function
+ * never returns kind "pr".
+ */
+export function scoreIssue(item, allItems, config) {
+    const tags = [];
+    let score = priorityScore(item.priority) + phaseScore(item.workflowState);
+    const lockStale = detectLockStale(item, config);
+    const treeContinue = detectTreeContinue(item, allItems, config);
+    // Stale boost (non-lock states only)
+    const isStale = !isLockState(item.workflowState) &&
+        ageHours(item.updatedAt, config.now) >= config.stuckThresholdHours;
+    if (isStale) {
+        score += STALE_BOOST;
+        tags.push("stale");
+    }
+    if (lockStale) {
+        score += LOCK_STALE_BOOST;
+        tags.push("stalled");
+    }
+    if (treeContinue) {
+        score += TREE_CONTINUE_BOOST;
+        tags.push("tree");
+    }
+    // Descriptive-only tags
+    if (item.priority === "P0" || item.priority === "P1") {
+        tags.push("high-priority");
+    }
+    if (hasOpenBlockers(item)) {
+        tags.push("blocked");
+    }
+    // Pick winning kind in precedence order
+    let kind;
+    if (lockStale) {
+        kind = "lock-stale";
+    }
+    else if (treeContinue) {
+        kind = "tree-continue";
+    }
+    else {
+        kind = "issue";
+    }
+    return { score, kind, tags };
+}
+function parseIssueNumberFromHeadRef(headRefName) {
+    // Match "GH-42" or "GH-0042" anywhere in the ref.
+    const m = headRefName.match(/GH-0*(\d+)/);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) ? n : null;
+}
+function scorePR(pr, config) {
+    // Drafts are excluded from ranking entirely.
+    if (pr.isDraft)
+        return null;
+    // APPROVED PRs are not surfaced — they are waiting on merge, not user
+    // attention. CHANGES_REQUESTED also skipped (author needs to push fixes,
+    // not the briefing user).
+    if (pr.reviewDecision === "APPROVED")
+        return null;
+    const tags = [];
+    let score = 0;
+    if (pr.reviewDecision === "REVIEW_REQUIRED") {
+        score += PR_REVIEW_REQUIRED_BOOST;
+        tags.push("needs-review");
+    }
+    // Older PRs rank slightly higher (more negative) than fresher ones.
+    // 1 point per hour beyond prStaleHours, capped at -50 to keep them from
+    // dominating REVIEW_REQUIRED items already at -200.
+    if (pr.ageHours > config.prStaleHours) {
+        const extra = Math.min(50, pr.ageHours - config.prStaleHours);
+        score -= extra;
+        tags.push("stale");
+    }
+    // PRs that did not pick up a boost (no review required, fresh) should
+    // not surface — they are work-in-progress noise.
+    if (score === 0)
+        return null;
+    const linkedIssueNumber = parseIssueNumberFromHeadRef(pr.headRefName);
+    return {
+        pr,
+        score,
+        reason: "", // filled in by buildReason at finalization time
+        tags,
+        linkedIssueNumber,
+    };
+}
+// ---------------------------------------------------------------------------
+// buildReason
+// ---------------------------------------------------------------------------
+/**
+ * Render a single-sentence prose reason for a direction. Distinct shapes
+ * per kind so the output reads as natural English rather than
+ * template-y. No trailing period — the consumer wraps the sentence into
+ * a paragraph at presentation time.
+ */
+export function buildReason(kind, issue, pr, tags, config, linkedIssueNumber = null) {
+    if (kind === "pr" && pr) {
+        const days = Math.max(1, Math.floor(pr.ageHours / 24));
+        const dayLabel = days === 1 ? "day" : "days";
+        if (pr.reviewDecision === "REVIEW_REQUIRED") {
+            const linkClause = linkedIssueNumber !== null
+                ? ` (issue #${linkedIssueNumber})`
+                : "";
+            return `PR #${pr.number} needs review${linkClause} — open ${days} ${dayLabel}`;
+        }
+        return `PR #${pr.number} has been open ${days} ${dayLabel} without movement`;
+    }
+    if (!issue)
+        return "Unknown direction";
+    if (kind === "lock-stale") {
+        const hours = Math.round(ageHours(issue.updatedAt, config.now));
+        const days = Math.max(1, Math.floor(hours / 24));
+        const dayLabel = days === 1 ? "day" : "days";
+        return `Stuck in ${issue.workflowState} for ${days} ${dayLabel} — may be blocked`;
+    }
+    if (kind === "tree-continue") {
+        return `#${issue.number} is part of an active tree — keep it moving before starting something new`;
+    }
+    // kind === "issue"
+    const phase = issue.workflowState ?? "Backlog";
+    if (tags.includes("stale")) {
+        const hours = Math.round(ageHours(issue.updatedAt, config.now));
+        const days = Math.max(1, Math.floor(hours / 24));
+        const dayLabel = days === 1 ? "day" : "days";
+        return `${phase} for ${days} ${dayLabel} — likely the most unblocking thing`;
+    }
+    if (issue.priority === "P0") {
+        return `P0 in ${phase} — top of the queue`;
+    }
+    if (issue.priority === "P1") {
+        return `P1 in ${phase} — worth a look`;
+    }
+    return `${phase} — next in line`;
+}
+function isCandidatePhase(state) {
+    if (state === null)
+        return false;
+    return ACTIONABLE_PHASES.has(state);
+}
+function toDirectionIssue(item) {
+    return {
+        number: item.number,
+        title: item.title,
+        workflowState: item.workflowState,
+        priority: item.priority,
+        estimate: item.estimate,
+    };
+}
+function toDirectionPR(pr) {
+    return {
+        number: pr.number,
+        title: pr.title,
+        url: pr.url,
+        ageHours: pr.ageHours,
+        reviewDecision: pr.reviewDecision,
+    };
+}
+/**
+ * Main entry point. Filters, scores, sorts, and slices a candidate set
+ * into up to `config.limit` deterministically-ranked directions.
+ *
+ * Determinism contract: same input + same `config.now` -> byte-identical
+ * output across calls. Achieved by:
+ *   - never reading `Date.now()` inside the lib
+ *   - using stable secondary sort keys (issue number / PR number)
+ *   - never iterating Sets/Maps for ordered work
+ */
+export function rankDirections(items, openPRs, config) {
+    // 1. Score all items first so we know which ones lock-stale (those go in
+    //    the candidate set even if their phase is not actionable).
+    const scored = [];
+    for (const item of items) {
+        const isLockStale = detectLockStale(item, config);
+        const passesPhaseFilter = isCandidatePhase(item.workflowState) || isLockStale;
+        if (!passesPhaseFilter)
+            continue;
+        const { score, kind, tags } = scoreIssue(item, items, config);
+        scored.push({ item, score, kind, tags });
+    }
+    // 2. Drop blocked items unless that would empty the candidate set.
+    const unblocked = scored.filter((s) => !hasOpenBlockers(s.item));
+    let candidates;
+    if (unblocked.length > 0) {
+        candidates = unblocked;
+    }
+    else if (scored.length > 0) {
+        // Surface the blocked candidates so the briefing isn't silent. Tags
+        // already include "blocked" via scoreIssue.
+        candidates = scored;
+    }
+    else {
+        candidates = [];
+    }
+    // 3. Score PRs.
+    const prScored = [];
+    for (const pr of openPRs) {
+        const s = scorePR(pr, config);
+        if (s)
+            prScored.push(s);
+    }
+    const merged = [];
+    for (const c of candidates)
+        merged.push({ kind: "issueRow", payload: c });
+    for (const p of prScored)
+        merged.push({ kind: "prRow", payload: p });
+    merged.sort((a, b) => {
+        const scoreA = a.kind === "issueRow" ? a.payload.score : a.payload.score;
+        const scoreB = b.kind === "issueRow" ? b.payload.score : b.payload.score;
+        if (scoreA !== scoreB)
+            return scoreA - scoreB;
+        // Secondary: PRs before issues at the same score (PRs are usually
+        // higher-urgency action items: "merge or reply" beats "consider").
+        if (a.kind !== b.kind)
+            return a.kind === "prRow" ? -1 : 1;
+        if (a.kind === "issueRow" && b.kind === "issueRow") {
+            return a.payload.item.number - b.payload.item.number;
+        }
+        if (a.kind === "prRow" && b.kind === "prRow") {
+            return a.payload.pr.number - b.payload.pr.number;
+        }
+        return 0;
+    });
+    // 5. Tree-continue promotion: if a tree-continue is anywhere in the
+    //    top 5 of the merged list but not in slot 1, promote it to slot 2.
+    if (merged.length >= 2) {
+        const slot1IsTreeContinue = merged[0].kind === "issueRow" &&
+            merged[0].payload.kind === "tree-continue";
+        if (!slot1IsTreeContinue) {
+            const limitToScan = Math.min(5, merged.length);
+            let treeIdx = -1;
+            for (let i = 1; i < limitToScan; i++) {
+                const e = merged[i];
+                if (e.kind === "issueRow" && e.payload.kind === "tree-continue") {
+                    treeIdx = i;
+                    break;
+                }
+            }
+            if (treeIdx > 1) {
+                const [moved] = merged.splice(treeIdx, 1);
+                merged.splice(1, 0, moved);
+            }
+        }
+    }
+    // 6. Slice to limit and assign rank.
+    const sliced = merged.slice(0, Math.max(0, config.limit));
+    const directions = sliced.map((entry, idx) => {
+        const rank = idx + 1;
+        if (entry.kind === "issueRow") {
+            const c = entry.payload;
+            const reason = buildReason(c.kind, c.item, null, c.tags, config, null);
+            return {
+                rank,
+                kind: c.kind,
+                issue: toDirectionIssue(c.item),
+                pr: null,
+                reason,
+                tags: c.tags,
+                score: c.score,
+            };
+        }
+        // PR row
+        const p = entry.payload;
+        const reason = buildReason("pr", null, p.pr, p.tags, config, p.linkedIssueNumber);
+        return {
+            rank,
+            kind: "pr",
+            issue: null,
+            pr: toDirectionPR(p.pr),
+            reason,
+            tags: p.tags,
+            score: p.score,
+        };
+    });
+    return directions;
+}
+//# sourceMappingURL=directions.js.map

package/dist/tools/dashboard-tools.js

@@ -98,6 +98,8 @@ export function toDashboardItems(raw, projectNumber, projectTitle) {
                 number: n.number,
                 workflowState: n.state === "CLOSED" ? "Done" : null,
             })) ?? [],
+            parentNumber: r.content.trackedInIssues?.nodes?.[0]?.number ?? null,
+            parentState: r.content.trackedInIssues?.nodes?.[0]?.state ?? null,
             ...(projectNumber !== undefined ? { projectNumber } : {}),
             ...(projectTitle !== undefined ? { projectTitle } : {}),
             ...(r.content.repository ? { repository: r.content.repository.nameWithOwner } : {}),
@@ -135,6 +137,7 @@ export const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $f
               repository { nameWithOwner name }
               subIssues { totalCount }
               trackedIssues(first: 10) { nodes { number state } }
+              trackedInIssues(first: 3) { nodes { number state closedAt } }
             }
             ... on PullRequest {
               __typename

package/dist/tools/directions-tools.js

@@ -0,0 +1,159 @@
+/**
+ * MCP tool wrapping the pure ranker at `lib/directions.ts`.
+ *
+ * Exposes `ralph_hero__hello_directions`: a single-tool, fixed-shape,
+ * deterministic surface that returns up to N ranked "directions" for the
+ * `hello` skill's session briefing. The skill is responsible for fetching
+ * open PRs (via `gh pr list`) and passing them in as a parameter — the
+ * MCP server does not itself open an Octokit-style PR API surface.
+ *
+ * Behaviour:
+ *   1. Resolve owner + project numbers from args or client config.
+ *   2. For each project, ensure the field cache is populated, then
+ *      paginate `DASHBOARD_ITEMS_QUERY` to gather up to 500 items.
+ *   3. Convert raw items to `DashboardItem[]` via `toDashboardItems`.
+ *   4. Build a `RankConfig` from the args + defaults (with injected `now`).
+ *   5. Compute each PR's `ageHours` at the boundary and call
+ *      `rankDirections(allItems, enrichedPRs, config)`.
+ *   6. Return `{ directions, fetchedAt, totalCandidates }`.
+ *
+ * Determinism: `fetchedAt` is the only time-varying field. Two consecutive
+ * calls on the same board state produce byte-identical `directions[]`
+ * (after stripping `fetchedAt`).
+ */
+import { z } from "zod";
+import { ensureFieldCache } from "../lib/helpers.js";
+import { paginateConnection } from "../lib/pagination.js";
+import { DASHBOARD_ITEMS_QUERY, toDashboardItems, } from "./dashboard-tools.js";
+import { rankDirections, DEFAULT_RANK_CONFIG, } from "../lib/directions.js";
+import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } from "../types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const HOUR_MS = 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Register
+// ---------------------------------------------------------------------------
+export function registerDirectionsTools(server, client, fieldCache) {
+    server.tool("ralph_hero__hello_directions", "Compute up to N deterministic 'directions' for the hello skill's session briefing. Single tool call returns a fixed-shape JSON payload with ranked issue/PR action items. Open PRs must be passed in as a parameter (the MCP server does not fetch them itself).", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to RALPH_GH_OWNER env var."),
+        projectNumbers: z
+            .array(z.coerce.number())
+            .optional()
+            .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
+        limit: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .default(3)
+            .describe("Max directions to return (default: 3)."),
+        stuckThresholdHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(48)
+            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+        lockStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+        treeRecentDoneDays: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(7)
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+        prStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before an open PR is considered stale (default: 24)."),
+        openPRs: z
+            .array(z.object({
+            number: z.number(),
+            title: z.string(),
+            url: z.string(),
+            isDraft: z.boolean(),
+            reviewDecision: z
+                .string()
+                .nullable()
+                .describe("REVIEW_REQUIRED | APPROVED | CHANGES_REQUESTED | null"),
+            headRefName: z.string(),
+            createdAt: z
+                .string()
+                .describe("ISO timestamp from gh pr list"),
+        }))
+            .optional()
+            .default([])
+            .describe("Open PRs gathered by the caller (e.g. via `gh pr list`). Drafts and APPROVED PRs are filtered internally."),
+    }, async (args) => {
+        try {
+            const owner = args.owner || resolveProjectOwner(client.config);
+            if (!owner) {
+                return toolError("owner is required");
+            }
+            const projectNumbers = args.projectNumbers ?? resolveProjectNumbers(client.config);
+            if (projectNumbers.length === 0) {
+                return toolError("No project numbers configured. Set RALPH_GH_PROJECT_NUMBER or RALPH_GH_PROJECT_NUMBERS.");
+            }
+            // Inject `now` at the boundary so the lib remains deterministic.
+            const now = new Date();
+            const allItems = [];
+            for (const pn of projectNumbers) {
+                await ensureFieldCache(client, fieldCache, owner, pn);
+                const projectId = fieldCache.getProjectId(pn);
+                if (!projectId) {
+                    // Defensive: ensureFieldCache succeeded but no projectId.
+                    // Skip this project rather than blowing up the whole call.
+                    continue;
+                }
+                const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+                allItems.push(...toDashboardItems(result.nodes, pn));
+            }
+            // Build the RankConfig from args + defaults + injected `now`.
+            const config = {
+                limit: args.limit ?? DEFAULT_RANK_CONFIG.limit,
+                stuckThresholdHours: args.stuckThresholdHours ?? DEFAULT_RANK_CONFIG.stuckThresholdHours,
+                lockStaleHours: args.lockStaleHours ?? DEFAULT_RANK_CONFIG.lockStaleHours,
+                treeRecentDoneDays: args.treeRecentDoneDays ?? DEFAULT_RANK_CONFIG.treeRecentDoneDays,
+                prStaleHours: args.prStaleHours ?? DEFAULT_RANK_CONFIG.prStaleHours,
+                now,
+            };
+            // Compute PR ageHours at the boundary so the lib never reads the wall clock.
+            const enrichedPRs = (args.openPRs ?? []).map((pr) => {
+                const t = new Date(pr.createdAt).getTime();
+                const ageHours = Number.isNaN(t)
+                    ? 0
+                    : Math.max(0, (now.getTime() - t) / HOUR_MS);
+                return {
+                    number: pr.number,
+                    title: pr.title,
+                    url: pr.url,
+                    isDraft: pr.isDraft,
+                    reviewDecision: pr.reviewDecision,
+                    headRefName: pr.headRefName,
+                    createdAt: pr.createdAt,
+                    ageHours,
+                };
+            });
+            const directions = rankDirections(allItems, enrichedPRs, config);
+            return toolSuccess({
+                directions,
+                fetchedAt: now.toISOString(),
+                totalCandidates: allItems.length,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to compute hello directions: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=directions-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.73",
+  "version": "2.5.75",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",