ralph-hero-mcp-server 2.5.85 → 2.5.87

package/dist/lib/directions.js

@@ -182,6 +182,52 @@ export function detectTreeContinue(item, allItems, config) {
         sib.workflowState !== "Canceled");
     return openSiblings.length > 0;
 }
+/**
+ * Compute a structured note describing which `detectTreeContinue` branch
+ * fired and the supporting evidence. Returns `null` if the candidate is
+ * not actually a tree-continue match (caller should not have called this).
+ *
+ * Two shapes (matching `detectTreeContinue`'s rule order):
+ *   - rule (a): "sibling #NNN closed N day(s) ago"
+ *   - rule (b): "candidate moved N day(s) ago; M open sibling(s)"
+ */
+function buildParentChainNote(item, allItems, config) {
+    const parent = item.parentNumber ?? null;
+    if (parent === null || parent === undefined)
+        return null;
+    const siblings = allItems.filter((other) => other.number !== item.number && other.parentNumber === parent);
+    // Rule (a): find the most-recently-closed sibling within the window
+    // (deterministic: pick the one with the smallest sibling number among
+    // those tied on closedAt, matching the natural source order).
+    let closestSibling = null;
+    for (const sib of siblings) {
+        if (!sib.closedAt)
+            continue;
+        const days = ageDays(sib.closedAt, config.now);
+        if (days > config.treeRecentDoneDays)
+            continue;
+        const dayInt = Math.max(1, Math.floor(days));
+        if (closestSibling === null ||
+            dayInt < closestSibling.days ||
+            (dayInt === closestSibling.days && sib.number < closestSibling.number)) {
+            closestSibling = { number: sib.number, days: dayInt };
+        }
+    }
+    if (closestSibling !== null) {
+        const dayLabel = closestSibling.days === 1 ? "day" : "days";
+        return `sibling #${closestSibling.number} closed ${closestSibling.days} ${dayLabel} ago`;
+    }
+    // Rule (b): candidate-moved branch
+    const candidateDays = Math.max(1, Math.floor(ageDays(item.updatedAt, config.now)));
+    const openSiblings = siblings.filter((sib) => sib.closedAt === null &&
+        sib.workflowState !== "Done" &&
+        sib.workflowState !== "Canceled");
+    if (openSiblings.length === 0)
+        return null;
+    const dayLabel = candidateDays === 1 ? "day" : "days";
+    const sibLabel = openSiblings.length === 1 ? "sibling" : "siblings";
+    return `candidate moved ${candidateDays} ${dayLabel} ago; ${openSiblings.length} open ${sibLabel}`;
+}
 // ---------------------------------------------------------------------------
 // scoreIssue
 // ---------------------------------------------------------------------------
@@ -194,8 +240,10 @@ export function detectTreeContinue(item, allItems, config) {
  *   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`.
+ * "blocked"). `signals` carries the structured per-direction explanation
+ * (staleDays, parentChainNote, estimateWeight, etc.) that skills use to
+ * synthesize prose without rendering the legacy `reason` template
+ * verbatim.
  *
  * PR ranking is handled separately by `rankDirections` — this function
  * never returns kind "pr".
@@ -205,7 +253,8 @@ export function scoreIssue(item, allItems, config) {
     let score = priorityScore(item.priority) + phaseScore(item.workflowState);
     // Audience-aware estimate penalty (no-op for "human"; pushes XL items
     // down for "agent" so autonomous loops favor XS/S work).
-    score += audiencePenalty(item, config.audience);
+    const estPenalty = audiencePenalty(item, config.audience);
+    score += estPenalty;
     const lockStale = detectLockStale(item, config);
     const treeContinue = detectTreeContinue(item, allItems, config);
     // Stale boost (non-lock states only)
@@ -241,7 +290,33 @@ export function scoreIssue(item, allItems, config) {
     else {
         kind = "issue";
     }
-    return { score, kind, tags };
+    // Compute structured signals for skills to synthesize prose. tiedAtScore
+    // is added later by rankDirections after the post-sort pass.
+    const signals = { tags: [...tags] };
+    if (kind === "lock-stale") {
+        const days = Math.max(1, Math.floor(ageHours(item.updatedAt, config.now) / 24));
+        signals.staleDays = days;
+        signals.staleThresholdDays = config.lockStaleHours / 24;
+    }
+    else {
+        // For non-lock items, surface the threshold informationally and
+        // populate staleDays only when the stale tag fired.
+        signals.staleThresholdDays = config.stuckThresholdHours / 24;
+        if (isStale) {
+            const days = Math.max(1, Math.floor(ageHours(item.updatedAt, config.now) / 24));
+            signals.staleDays = days;
+        }
+    }
+    if (estPenalty > 0) {
+        signals.estimateWeight = estPenalty;
+    }
+    if (kind === "tree-continue") {
+        const note = buildParentChainNote(item, allItems, config);
+        if (note !== null) {
+            signals.parentChainNote = note;
+        }
+    }
+    return { score, kind, tags, signals };
 }
 function parseIssueNumberFromHeadRef(headRefName) {
     // Match "GH-42" or "GH-0042" anywhere in the ref.
@@ -279,12 +354,21 @@ function scorePR(pr, config) {
     if (score === 0)
         return null;
     const linkedIssueNumber = parseIssueNumberFromHeadRef(pr.headRefName);
+    const signals = {
+        tags: [...tags],
+        prAgeDays: Math.max(1, Math.floor(pr.ageHours / 24)),
+        prReviewDecision: pr.reviewDecision,
+    };
+    if (linkedIssueNumber !== null) {
+        signals.linkedIssueNumber = linkedIssueNumber;
+    }
     return {
         pr,
         score,
         reason: "", // filled in by buildReason at finalization time
         tags,
         linkedIssueNumber,
+        signals,
     };
 }
 // ---------------------------------------------------------------------------
@@ -295,8 +379,12 @@ function scorePR(pr, config) {
  * 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.
+ *
+ * @deprecated Reason strings are derived from signals for back-compat.
+ * Skills should synthesize prose from signals directly. Removed in 2.7.0.
  */
-export function buildReason(kind, issue, pr, tags, config, linkedIssueNumber = null) {
+export function buildReason(kind, issue, pr, signals, config, linkedIssueNumber = null) {
+    const tags = signals.tags;
     if (kind === "pr" && pr) {
         const days = Math.max(1, Math.floor(pr.ageHours / 24));
         const dayLabel = days === 1 ? "day" : "days";
@@ -390,8 +478,8 @@ export function rankDirections(items, openPRs, config) {
         const passesPhaseFilter = isCandidatePhase(item.workflowState) || isLockStale;
         if (!passesPhaseFilter)
             continue;
-        const { score, kind, tags } = scoreIssue(item, items, config);
-        scored.push({ item, score, kind, tags });
+        const { score, kind, tags, signals } = scoreIssue(item, items, config);
+        scored.push({ item, score, kind, tags, signals });
     }
     // 2. Drop blocked items unless that would empty the candidate set.
     const unblocked = scored.filter((s) => !hasOpenBlockers(s.item));
@@ -459,17 +547,32 @@ export function rankDirections(items, openPRs, config) {
     }
     // 6. Slice to limit and assign rank.
     const sliced = merged.slice(0, Math.max(0, config.limit));
+    // 6a. Compute tied-at-top-score count from the sliced (final) list so the
+    //     tie reflects what the user actually sees. Stamped onto each entry's
+    //     signals only when the count is > 1; omitted otherwise.
+    const tiedCount = sliced.length === 0
+        ? 0
+        : sliced.filter((entry) => {
+            const s = entry.kind === "issueRow" ? entry.payload.score : entry.payload.score;
+            const top = sliced[0].kind === "issueRow" ? sliced[0].payload.score : sliced[0].payload.score;
+            return s === top;
+        }).length;
     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);
+            const signals = { ...c.signals };
+            if (tiedCount > 1 && c.score === sliced[0].payload.score) {
+                signals.tiedAtScore = tiedCount;
+            }
+            const reason = buildReason(c.kind, c.item, null, signals, config, null);
             return {
                 rank,
                 recommended: false,
                 kind: c.kind,
                 issue: toDirectionIssue(c.item),
                 pr: null,
+                signals,
                 reason,
                 tags: c.tags,
                 score: c.score,
@@ -477,13 +580,18 @@ export function rankDirections(items, openPRs, config) {
         }
         // PR row
         const p = entry.payload;
-        const reason = buildReason("pr", null, p.pr, p.tags, config, p.linkedIssueNumber);
+        const signals = { ...p.signals };
+        if (tiedCount > 1 && p.score === sliced[0].payload.score) {
+            signals.tiedAtScore = tiedCount;
+        }
+        const reason = buildReason("pr", null, p.pr, signals, config, p.linkedIssueNumber);
         return {
             rank,
             recommended: false,
             kind: "pr",
             issue: null,
             pr: toDirectionPR(p.pr),
+            signals,
             reason,
             tags: p.tags,
             score: p.score,

package/dist/tools/directions-tools.js

@@ -126,7 +126,7 @@ export function makeRunDirections(client, fieldCache) {
 // ---------------------------------------------------------------------------
 export function registerDirectionsTools(server, client, fieldCache) {
     const runDirections = makeRunDirections(client, fieldCache);
-    server.tool("ralph_hero__hello_directions", "[DEPRECATED — use ralph_hero__next_actions instead. Removed in 2.7.0.] Compute up to N deterministic 'directions' for the hello skill's session briefing.", {
+    server.tool("ralph_hero__hello_directions", "[DEPRECATED — use ralph_hero__next_actions instead. Removed in 2.7.0.] Compute up to N deterministic 'directions' for the hello skill's session briefing. Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0.", {
         owner: z
             .string()
             .optional()
@@ -174,7 +174,7 @@ export function registerDirectionsTools(server, client, fieldCache) {
     }, async (args) => {
         return await runDirections({ ...args, audience: "human" });
     });
-    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Used by the /hello skill picker (interactive) and by headless orchestrators (auto-select recommended). Open PRs must be passed in as a parameter.", {
+    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Used by the /hello skill picker (interactive) and by headless orchestrators (auto-select recommended). Open PRs must be passed in as a parameter. Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0.", {
         owner: z
             .string()
             .optional()

package/package.json

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