ralph-hero-mcp-server 2.5.120 → 2.5.123

package/dist/lib/directions.js

@@ -1,5 +1,5 @@
 /**
- * Pure ranker library for the `ralph_hero__hello_directions` MCP tool.
+ * Pure ranker library for the `ralph_hero__next_actions` MCP tool.
  *
  * Computes up to N deterministic directions for a session-briefing
  * companion. All functions are side-effect free: time is injected via

package/dist/tools/directions-tools.js

@@ -1,13 +1,10 @@
 /**
  * MCP tools wrapping the pure ranker at `lib/directions.ts`.
  *
- * Exposes two tools that share a single implementation:
- *   - `ralph_hero__next_actions` (current name; accepts `audience` param)
- *   - `ralph_hero__hello_directions` (DEPRECATED alias; fixed at audience="human")
- *
- * Both return a fixed-shape JSON payload with up to N ranked "directions"
- * for the `hello` skill's session briefing. Open PRs are fetched internally
- * via the configured GitHub token's `repo` scope; callers no longer pass an
+ * Exposes `ralph_hero__next_actions` — accepts `audience` param and returns
+ * a fixed-shape JSON payload with up to N ranked "directions" for the
+ * `hello` skill's session briefing. Open PRs are fetched internally via the
+ * configured GitHub token's `repo` scope; callers no longer pass an
  * `openPRs` argument.
  *
  * Behaviour:
@@ -222,11 +219,8 @@ export async function fetchOpenPRs(client, repos) {
     return out;
 }
 // ---------------------------------------------------------------------------
-// Shared implementation — extracted so both `hello_directions` (deprecated)
-// and `next_actions` (current) can route through the same code path. Also
-// exported so the deprecated `pick_actionable_issue` wrapper in
-// `issue-tools.ts` can delegate without duplicating the data-fetch +
-// scoring pipeline.
+// Shared implementation — extracted so the `next_actions` tool can route
+// through a single code path.
 // ---------------------------------------------------------------------------
 export function makeRunDirections(client, fieldCache) {
     return async function runDirections(args) {
@@ -313,49 +307,6 @@ 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. Open PRs are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items). 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. Returns `{ directions, fetchedAt, boardItems }` where `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools); the returned `directions` array is bounded by `limit`.", {
-        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, unit: hours). Pulls from STUCK_THRESHOLD_HOURS in src/lib/thresholds.ts."),
-        lockStaleHours: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(24)
-            .describe("Hours before a lock-state issue is considered stalled (default: 24, unit: hours). Pulls from LOCK_STALE_HOURS in src/lib/thresholds.ts."),
-        treeRecentDoneDays: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(7)
-            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7, unit: days). Pulls from RECENT_WINDOW_DAYS in src/lib/thresholds.ts."),
-        prStaleHours: z
-            .number()
-            .nonnegative()
-            .optional()
-            .default(24)
-            .describe("Hours before an open PR is considered stale (default: 24, unit: hours). Pulls from PR_STALE_HOURS in src/lib/thresholds.ts."),
-    }, 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 are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items) — callers no longer pass an `openPRs` argument. 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. When `audience='agent'` and no items are in actionable phases (Plan in Review, In Review, Ready for Plan, Research Needed) or otherwise surfacing (lock-stale, unblock-requested), the picker falls back to Backlog and null-state items so autopilot can drive triage. Fallback items receive a fixed score penalty so they never outrank actionable items when those exist; the fallback never fires for `audience='human'`. Returns `{ directions, fetchedAt, boardItems }` where `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools); the returned `directions` array is bounded by `limit`.", {
         owner: z
             .string()

package/dist/tools/issue-tools.js

@@ -10,7 +10,6 @@ import { detectGroup } from "../lib/group-detection.js";
 import { detectPipelinePosition, OVERSIZED_ESTIMATES, } from "../lib/pipeline-detection.js";
 import { isValidState, isParentGateState, VALID_STATES, LOCK_STATES, TERMINAL_STATES, WORKFLOW_STATE_TO_STATUS, } from "../lib/workflow-states.js";
 import { buildBatchMutationQuery } from "./batch-tools.js";
-import { makeRunDirections } from "./directions-tools.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
@@ -1184,157 +1183,6 @@ export function registerIssueTools(server, client, fieldCache) {
             return toolError(`Failed to create comment: ${message}`);
         }
     });
-    // -------------------------------------------------------------------------
-    // ralph_hero__pick_actionable_issue [DEPRECATED]
-    //
-    // Thin wrapper that delegates to the shared `runDirections` helper from
-    // `directions-tools.ts` (audience="agent"). Preserves the legacy
-    // `{ found, issue, group, alternatives }` shape so existing callers
-    // (justfile recipes, hero/team allowlists) keep working until removal in
-    // 2.7.0. Same backwards-compat pattern as `hello_directions` from Phase 2.
-    //
-    // Migration: callers should switch to
-    //   ralph_hero__next_actions(limit=1, audience="agent")
-    // and consume the rank-1 (recommended) entry directly.
-    // -------------------------------------------------------------------------
-    const runDirections = makeRunDirections(client, fieldCache);
-    server.tool("ralph_hero__pick_actionable_issue", "[DEPRECATED — use ralph_hero__next_actions(limit=1, audience='agent') instead. Removed in 2.7.0.] Find the highest-priority issue matching a workflow state that is not blocked or locked. Returns: found, issue (with number, title, workflowState, estimate, priority, group context), alternatives count. Used by dispatch loop to find work for idle teammates.", {
-        owner: z
-            .string()
-            .optional()
-            .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
-        repo: z
-            .string()
-            .optional()
-            .describe("Repository name. Defaults to GITHUB_REPO env var"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        workflowState: z
-            .string()
-            .optional()
-            .describe("Target workflow state (e.g., 'Research Needed', 'Ready for Plan'). Optional — when omitted, the rank-1 (recommended) direction across all actionable phases is returned (same as next_actions(limit=1, audience='agent'))."),
-        maxEstimate: z
-            .string()
-            .optional()
-            .default("S")
-            .describe("Maximum estimate to include (XS, S, M, L, XL). Default: S"),
-    }, async (args) => {
-        try {
-            // Validate workflow state (only when provided — wrapper allows
-            // omission so it can mirror next_actions(limit=1, audience='agent')).
-            if (args.workflowState !== undefined && !isValidState(args.workflowState)) {
-                return toolError(`Unknown workflow state '${args.workflowState}'. ` +
-                    `Valid states: ${VALID_STATES.join(", ")}. ` +
-                    `Recovery: retry with a valid state name. ` +
-                    `Common states for dispatch: 'Research Needed' (for researchers), ` +
-                    `'Ready for Plan' (for planners), 'Plan in Review' (for reviewers).`);
-            }
-            // Validate estimate
-            const validEstimates = ["XS", "S", "M", "L", "XL"];
-            const maxEstimate = args.maxEstimate || "S";
-            if (!validEstimates.includes(maxEstimate)) {
-                return toolError(`Unknown estimate '${maxEstimate}'. ` +
-                    `Valid estimates: ${validEstimates.join(", ")}. ` +
-                    `Recovery: retry with a valid estimate or omit for default (S).`);
-            }
-            const { owner, repo } = resolveFullConfig(client, args);
-            // Delegate to the shared ranker with audience="agent". Use a
-            // generous limit so we have enough entries to filter by
-            // workflowState + maxEstimate while still finding the highest
-            // priority candidate. The ranker uses priority + audience-aware
-            // estimate penalty as the dominant ordering signal, which matches
-            // the legacy P0 -> P3 sort.
-            const directionsResult = await runDirections({
-                owner,
-                projectNumbers: args.projectNumber !== undefined ? [args.projectNumber] : undefined,
-                limit: 50,
-                audience: "agent",
-            });
-            if (directionsResult.isError) {
-                // Surface the underlying error verbatim so callers see the same
-                // recovery hints they would from next_actions.
-                return directionsResult;
-            }
-            const payload = JSON.parse(directionsResult.content[0].text);
-            // Restrict to plain "issue" directions — exclude PRs (kind="pr"),
-            // lock-stale items (kind="lock-stale"), and tree-continue picks
-            // (kind="tree-continue") since legacy semantics returned a single
-            // ready-to-claim issue.
-            let issueDirections = payload.directions.filter((d) => d.kind === "issue" && d.issue !== null);
-            // Apply legacy filters: workflowState (if provided) and maxEstimate.
-            if (args.workflowState !== undefined) {
-                issueDirections = issueDirections.filter((d) => d.issue.workflowState === args.workflowState);
-            }
-            const maxIdx = validEstimates.indexOf(maxEstimate);
-            issueDirections = issueDirections.filter((d) => {
-                const est = d.issue.estimate;
-                if (!est)
-                    return true;
-                const estIdx = validEstimates.indexOf(est);
-                if (estIdx < 0)
-                    return true;
-                return estIdx <= maxIdx;
-            });
-            // Drop blocked items (legacy behavior). The ranker already strips
-            // these unless that would empty the candidate set; the "blocked"
-            // tag still rides along when it kept them as a fallback.
-            issueDirections = issueDirections.filter((d) => !d.tags.includes("blocked"));
-            if (issueDirections.length === 0) {
-                return toolSuccess({
-                    found: false,
-                    issue: null,
-                    alternatives: 0,
-                });
-            }
-            const best = issueDirections[0].issue;
-            const issueNumber = best.number;
-            // Detect group context for the picked issue (best-effort).
-            let group = null;
-            try {
-                const groupResult = await detectGroup(client, owner, repo, issueNumber);
-                group = {
-                    isGroup: groupResult.isGroup,
-                    primary: {
-                        number: groupResult.groupPrimary.number,
-                        title: groupResult.groupPrimary.title,
-                    },
-                    members: groupResult.groupTickets.map((t) => ({
-                        number: t.number,
-                        title: t.title,
-                        state: t.state,
-                        order: t.order,
-                    })),
-                    totalTickets: groupResult.totalTickets,
-                };
-            }
-            catch {
-                // Group detection is best-effort
-                group = null;
-            }
-            return toolSuccess({
-                found: true,
-                issue: {
-                    number: issueNumber,
-                    title: best.title,
-                    // Body is not fetched by the ranker's data pipeline — kept
-                    // empty for backward compat. Callers needing the body should
-                    // chain a `get_issue` call (or migrate to `next_actions`).
-                    description: "",
-                    workflowState: best.workflowState,
-                    estimate: best.estimate || null,
-                    priority: best.priority || null,
-                    isLocked: false,
-                    blockedBy: [],
-                },
-                group,
-                alternatives: issueDirections.length - 1,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to pick actionable issue: ${message}`);
-        }
-    });
 }
 function getFieldValue(item, fieldName) {
     const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName &&

package/package.json

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