ralph-hero-mcp-server 2.5.109 → 2.5.111

package/dist/lib/directions.js

@@ -61,6 +61,13 @@ const STALE_BOOST = -50;
 const LOCK_STALE_BOOST = -100;
 const TREE_CONTINUE_BOOST = -75;
 const PR_REVIEW_REQUIRED_BOOST = -200;
+/**
+ * Boost applied to a Human Needed issue carrying a fresh `## Unblock Request`
+ * comment. Must be more negative than `LOCK_STALE_BOOST` so the unblock
+ * direction outranks any lock-stale entry — these issues are explicitly
+ * waiting for the human's attention.
+ */
+const HUMAN_NEEDED_UNBLOCK_BOOST = -150;
 /**
  * Per-estimate penalty applied when audience === "agent". Larger items
  * cost more (positive score), pushing them down the ranking so agent
@@ -235,7 +242,8 @@ function buildParentChainNote(item, allItems, config) {
  * Score a single dashboard item. Returns the winning kind for this candidate
  * in precedence order:
  *
- *   detectLockStale(item) -> kind: "lock-stale"
+ *   has unblock signal (Human Needed) -> kind: "human-needed-unblock"
+ *   else detectLockStale(item) -> kind: "lock-stale"
  *   else detectTreeContinue(item) -> kind: "tree-continue"
  *   else -> kind: "issue"
  *
@@ -255,6 +263,30 @@ export function scoreIssue(item, allItems, config) {
     // down for "agent" so autonomous loops favor XS/S work).
     const estPenalty = audiencePenalty(item, config.audience);
     score += estPenalty;
+    // Human Needed + fresh `## Unblock Request` comment takes precedence over
+    // every other detection. The signal is computed at the tool boundary.
+    const unblockSignal = item.workflowState === "Human Needed"
+        ? config.unblockSignals?.[item.number]
+        : undefined;
+    if (unblockSignal !== undefined) {
+        score += HUMAN_NEEDED_UNBLOCK_BOOST;
+        tags.push("unblock-requested");
+        if (item.priority === "P0" || item.priority === "P1") {
+            tags.push("high-priority");
+        }
+        if (hasOpenBlockers(item)) {
+            tags.push("blocked");
+        }
+        const signals = {
+            tags: [...tags],
+            unblockRequestAgeDays: unblockSignal.unblockRequestAgeDays,
+            questionCount: unblockSignal.questionCount,
+        };
+        if (estPenalty > 0) {
+            signals.estimateWeight = estPenalty;
+        }
+        return { score, kind: "human-needed-unblock", tags, signals };
+    }
     const lockStale = detectLockStale(item, config);
     const treeContinue = detectTreeContinue(item, allItems, config);
     // Stale boost (non-lock states only)
@@ -398,6 +430,16 @@ export function buildReason(kind, issue, pr, signals, config, linkedIssueNumber
     }
     if (!issue)
         return "Unknown direction";
+    if (kind === "human-needed-unblock") {
+        const days = signals.unblockRequestAgeDays ?? 0;
+        const dayLabel = days === 1 ? "day" : "days";
+        const qCount = signals.questionCount ?? 0;
+        const qLabel = qCount === 1 ? "question" : "questions";
+        if (days === 0) {
+            return `Human Needed — ${qCount} unblock ${qLabel} waiting (posted today)`;
+        }
+        return `Human Needed — ${qCount} unblock ${qLabel} waiting since ${days} ${dayLabel} ago`;
+    }
     if (kind === "lock-stale") {
         const hours = Math.round(ageHours(issue.updatedAt, config.now));
         const days = Math.max(1, Math.floor(hours / 24));
@@ -471,11 +513,16 @@ function toDirectionPR(pr) {
  */
 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).
+    //    the candidate set even if their phase is not actionable). Human
+    //    Needed items also pass the filter when an unblock signal exists for
+    //    them — surfacing them as `human-needed-unblock` directions.
     const scored = [];
     for (const item of items) {
         const isLockStale = detectLockStale(item, config);
-        const passesPhaseFilter = isCandidatePhase(item.workflowState) || isLockStale;
+        const hasUnblockSignal = item.workflowState === "Human Needed" &&
+            config.unblockSignals !== undefined &&
+            config.unblockSignals[item.number] !== undefined;
+        const passesPhaseFilter = isCandidatePhase(item.workflowState) || isLockStale || hasUnblockSignal;
         if (!passesPhaseFilter)
             continue;
         const { score, kind, tags, signals } = scoreIssue(item, items, config);

package/dist/lib/filter-profiles.js

@@ -31,6 +31,9 @@ export const FILTER_PROFILES = {
     "integrator-merge": {
         workflowState: "In Review",
     },
+    "analyst-unblock": {
+        workflowState: "Human Needed",
+    },
 };
 /**
  * Valid profile names, derived from the registry keys.

package/dist/lib/state-resolution.js

@@ -47,6 +47,13 @@ const COMMAND_ALLOWED_STATES = {
     ralph_hero: ["In Review", "Human Needed"],
     ralph_merge: ["Done", "Human Needed"],
     ralph_code_review: ["In Review", "Human Needed"],
+    ralph_unblock: [
+        "Backlog",
+        "Research Needed",
+        "Ready for Plan",
+        "In Progress",
+        "Human Needed",
+    ],
 };
 // --- Helpers ---
 function isSemanticIntent(state) {

package/dist/tools/directions-tools.js

@@ -34,6 +34,121 @@ import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } f
 // Constants
 // ---------------------------------------------------------------------------
 const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+/**
+ * Fetch the most recent comments on a single issue. Returns an empty list on
+ * error (e.g. the issue is private or has been deleted) so the surrounding
+ * ranker continues to produce directions.
+ */
+async function fetchIssueCommentsForUnblock(client, owner, repo, number) {
+    try {
+        const data = await client.query(`query($owner: String!, $repo: String!, $number: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issue(number: $number) {
+            comments(last: 20) {
+              nodes { body createdAt }
+            }
+          }
+        }
+      }`, { owner, repo, number });
+        return data.repository?.issue?.comments?.nodes ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse a list of comments and return the unblock signal for the issue, or
+ * `null` if the issue should NOT produce a `human-needed-unblock` direction.
+ *
+ * Rules (matching plan Phase 4.1):
+ *   1. Find the most recent comment whose body starts with `## Unblock Request`.
+ *      If none exists, return null.
+ *   2. Find the most recent comment whose body starts with `## Escalation`.
+ *      If it exists and is newer than the unblock request, return null
+ *      (the autonomous skill needs to re-run before the human is asked).
+ *   3. Compute `unblockRequestAgeDays` from the unblock request's createdAt.
+ *   4. Compute `questionCount` by counting lines matching `^\d+\.\s` in the
+ *      unblock request body.
+ */
+export function extractUnblockSignal(comments, now) {
+    // Iterate to find the most recent comment of each header kind. Use
+    // string-prefix match because authors may include trailing whitespace
+    // or quote a header in a follow-up comment that we want to ignore.
+    let latestUnblock = null;
+    let latestEscalation = null;
+    for (const c of comments) {
+        if (c.body.startsWith("## Unblock Request")) {
+            if (latestUnblock === null ||
+                new Date(c.createdAt).getTime() >
+                    new Date(latestUnblock.createdAt).getTime()) {
+                latestUnblock = c;
+            }
+        }
+        else if (c.body.startsWith("## Escalation")) {
+            if (latestEscalation === null ||
+                new Date(c.createdAt).getTime() >
+                    new Date(latestEscalation.createdAt).getTime()) {
+                latestEscalation = c;
+            }
+        }
+    }
+    if (latestUnblock === null)
+        return null;
+    // Skip if the most recent escalation is newer than the unblock request.
+    if (latestEscalation !== null) {
+        const escTs = new Date(latestEscalation.createdAt).getTime();
+        const ubTs = new Date(latestUnblock.createdAt).getTime();
+        if (escTs > ubTs)
+            return null;
+    }
+    // Age in whole days, rounded down. Floor at 0 (never negative).
+    const ts = new Date(latestUnblock.createdAt).getTime();
+    const ageMs = Number.isNaN(ts) ? 0 : Math.max(0, now.getTime() - ts);
+    const unblockRequestAgeDays = Math.floor(ageMs / DAY_MS);
+    // Count question lines: `^\d+\.\s` (e.g. "1. ", "2.\t")
+    const questionCount = latestUnblock.body
+        .split("\n")
+        .filter((line) => /^\d+\.\s/.test(line)).length;
+    return { unblockRequestAgeDays, questionCount };
+}
+/**
+ * Parse "owner/repo" into its parts. Returns null on malformed input.
+ */
+function splitOwnerRepo(nameWithOwner) {
+    if (!nameWithOwner)
+        return null;
+    const parts = nameWithOwner.split("/");
+    if (parts.length !== 2)
+        return null;
+    if (!parts[0] || !parts[1])
+        return null;
+    return { owner: parts[0], repo: parts[1] };
+}
+/**
+ * Build the unblock signal map for all Human Needed candidates in `items`.
+ * Skips items that don't carry a parseable repository identifier (we need
+ * `owner/repo` to fetch issue comments via the GitHub repo API).
+ */
+async function buildUnblockSignalMap(client, items, now) {
+    const map = {};
+    const candidates = items.filter((item) => item.workflowState === "Human Needed");
+    if (candidates.length === 0)
+        return map;
+    // Fetch comments per candidate. Sequential to keep rate-limit pressure low —
+    // the candidate set is typically tiny (0-5).
+    for (const item of candidates) {
+        const ownerRepo = splitOwnerRepo(item.repository);
+        if (!ownerRepo)
+            continue;
+        const comments = await fetchIssueCommentsForUnblock(client, ownerRepo.owner, ownerRepo.repo, item.number);
+        const signal = extractUnblockSignal(comments, now);
+        if (signal !== null) {
+            map[item.number] = signal;
+        }
+    }
+    return map;
+}
 // ---------------------------------------------------------------------------
 // Shared schema fragments
 // ---------------------------------------------------------------------------
@@ -81,6 +196,10 @@ export function makeRunDirections(client, fieldCache) {
                 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));
             }
+            // Compute unblock signals for any Human Needed candidates so the
+            // ranker can surface `human-needed-unblock` directions. Comments are
+            // fetched at the boundary; the ranker stays pure.
+            const unblockSignals = await buildUnblockSignalMap(client, allItems, now);
             // Build the RankConfig from args + defaults + injected `now`.
             const config = {
                 limit: args.limit ?? DEFAULT_RANK_CONFIG.limit,
@@ -90,6 +209,7 @@ export function makeRunDirections(client, fieldCache) {
                 prStaleHours: args.prStaleHours ?? DEFAULT_RANK_CONFIG.prStaleHours,
                 audience: args.audience,
                 now,
+                unblockSignals,
             };
             // Compute PR ageHours at the boundary so the lib never reads the wall clock.
             const enrichedPRs = (args.openPRs ?? []).map((pr) => {

package/dist/tools/issue-tools.js

@@ -355,7 +355,6 @@ export function registerIssueTools(server, client, fieldCache) {
                 };
             });
             return toolSuccess({
-                totalCount: itemsResult.totalCount,
                 filteredCount: formattedItems.length,
                 items: formattedItems,
             });

package/package.json

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