ralph-hero-mcp-server 2.5.119 → 2.5.122

package/dist/index.js

@@ -16,6 +16,7 @@ import { FieldOptionCache } from "./lib/cache.js";
 import { createDebugLogger, wrapServerToolWithLogging } from "./lib/debug-logger.js";
 import { toolSuccess, resolveProjectOwner } from "./types.js";
 import { resolveRepoFromProject } from "./lib/helpers.js";
+import { detectOrphanRepoIssues } from "./lib/health.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
@@ -188,7 +189,7 @@ function initGitHubClient(debugLogger) {
  */
 function registerCoreTools(server, client) {
     // Health check tool - comprehensive validation of auth, repo, project, and fields
-    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields", {}, async () => {
+    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields. Also surfaces repo-scope mismatch via the `orphanRepoIssues` field when OPEN issues exist in the repo but are NOT on the configured project board (such issues are invisible to discovery tools like next_actions, list_issues, pipeline_dashboard, project_hygiene). The field is omitted entirely when the board contains every OPEN repo issue. Shape when present: `{ count, repoOpen, boardItems, sample: number[], note }` — `sample` is up to 10 orphan issue numbers (ascending) for diagnostic display.", {}, async () => {
         const checks = {};
         // 1. Auth check (repo token)
         try {
@@ -297,6 +298,26 @@ function registerCoreTools(server, client) {
                 detail: "RALPH_GH_PROJECT_NUMBER not set",
             };
         }
+        // 5. Orphan repo issues check — only runs when both repo and project
+        // access succeeded above. Failures here are non-fatal: orphan detection
+        // is informational and shouldn't downgrade the overall health status,
+        // because the underlying access checks already capture the real failure
+        // mode (broken token, missing project, etc.).
+        let orphanRepoIssues = null;
+        if (checks.repoAccess?.status === "ok" &&
+            checks.projectAccess?.status === "ok" &&
+            client.config.owner &&
+            client.config.repo &&
+            projOwner &&
+            projNum) {
+            try {
+                orphanRepoIssues = await detectOrphanRepoIssues(client, client.config.owner, client.config.repo, projOwner, projNum);
+            }
+            catch (e) {
+                // Non-fatal — log via stderr but don't fail health_check.
+                console.error(`[ralph-hero] Orphan repo issues check failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         // Token source detection — re-derive which env vars resolved
         const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN")
             ? "RALPH_GH_REPO_TOKEN"
@@ -327,6 +348,9 @@ function registerCoreTools(server, client) {
                     ? `Repo operations use ${repoTokenSource}, project operations use ${projectTokenSource}`
                     : `Both repo and project operations use ${repoTokenSource}`,
             },
+            // Omit the field entirely when there are no orphans, per the field's
+            // contract (`null` from `detectOrphanRepoIssues` means "clean board").
+            ...(orphanRepoIssues ? { orphanRepoIssues } : {}),
         });
     });
 }

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/lib/health.js

@@ -0,0 +1,180 @@
+/**
+ * Health-check helpers — pure functions that probe the GitHub API for
+ * configuration drift between the project board and its underlying repo.
+ *
+ * `detectOrphanRepoIssues` compares the set of OPEN issues in the configured
+ * repo against the set of `type=ISSUE` items on the configured project
+ * board. Issues present in the repo but not on the board are "orphans" —
+ * they exist but are structurally invisible to the discovery tools
+ * (`next_actions`, `list_issues`, `pipeline_dashboard`, `project_hygiene`),
+ * which all read from the project board.
+ *
+ * Surfaced via `health_check` so users discover the mismatch without having
+ * to grep `gh issue list` against the board contents by hand.
+ */
+/**
+ * Maximum number of orphan issue numbers to include in the response sample.
+ * The sample is for diagnostic display only; the full set is summarized via `count`.
+ */
+export const ORPHAN_SAMPLE_LIMIT = 10;
+/**
+ * Page size used when paginating repo issues and project items.
+ *
+ * GitHub GraphQL caps `first:` at 100. Most projects fit comfortably in a
+ * handful of pages — pagination is implemented for correctness, not because
+ * every call hits it.
+ */
+const PAGE_SIZE = 100;
+/**
+ * Hard cap on pages walked when enumerating repo issues or project items.
+ * Defensive: prevents a runaway loop on a misconfigured giant repo.
+ */
+const MAX_PAGES = 20;
+/**
+ * Standard explanatory note attached to the orphan-repo-issues warning.
+ * Lifted to a constant so tests can assert against a single canonical string.
+ */
+export const ORPHAN_REPO_ISSUES_NOTE = "Issues exist in the repo that are not on the project board. They are " +
+    "invisible to discovery tools (next_actions, list_issues, pipeline_dashboard, " +
+    "project_hygiene). To make them visible, add them to the project or use " +
+    "'gh issue list' directly.";
+/**
+ * Fetch all OPEN issue numbers in the repo via paginated GraphQL.
+ *
+ * Returns `{ totalCount, numbers }`. `totalCount` is taken from the first
+ * page (it is constant across pages). `numbers` is the union of all
+ * `node.number` values walked.
+ */
+async function fetchRepoOpenIssueNumbers(client, owner, repo) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    while (pages < MAX_PAGES) {
+        const response = await client.query(`query($owner: String!, $repo: String!, $cursor: String, $first: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issues(states: OPEN, first: $first, after: $cursor) {
+            totalCount
+            pageInfo { hasNextPage endCursor }
+            nodes { number }
+          }
+        }
+      }`, { owner, repo, cursor, first: PAGE_SIZE });
+        const page = response.repository?.issues;
+        if (!page)
+            break;
+        if (pages === 0)
+            totalCount = page.totalCount;
+        for (const node of page.nodes)
+            numbers.add(node.number);
+        if (!page.pageInfo.hasNextPage)
+            break;
+        cursor = page.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Fetch all `type=ISSUE` item numbers on the project board via paginated GraphQL.
+ *
+ * The query tries `user(login)` first, then falls back to `organization(login)`
+ * to handle both account types. PRs and DraftIssues are skipped — only true
+ * `Issue`-typed content with a `number` field is collected.
+ */
+async function fetchBoardIssueNumbers(client, projectOwner, projectNumber) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    // The project items query is identical across user/org owner — only the
+    // root selector changes. Build a closure that runs the same shape and
+    // tries both owner types on the first page.
+    const runQuery = async (cur) => {
+        for (const ownerType of ["user", "organization"]) {
+            try {
+                const res = await client.projectQuery(`query($owner: String!, $number: Int!, $cursor: String, $first: Int!) {
+            ${ownerType}(login: $owner) {
+              projectV2(number: $number) {
+                items(first: $first, after: $cursor) {
+                  totalCount
+                  pageInfo { hasNextPage endCursor }
+                  nodes {
+                    type
+                    content {
+                      __typename
+                      ... on Issue { number }
+                    }
+                  }
+                }
+              }
+            }
+          }`, { owner: projectOwner, number: projectNumber, cursor: cur, first: PAGE_SIZE });
+                const proj = res[ownerType]?.projectV2;
+                if (proj)
+                    return proj;
+            }
+            catch {
+                // Try next owner type
+            }
+        }
+        return null;
+    };
+    while (pages < MAX_PAGES) {
+        const proj = await runQuery(cursor);
+        if (!proj || !proj.items)
+            break;
+        if (pages === 0)
+            totalCount = proj.items.totalCount;
+        for (const node of proj.items.nodes) {
+            // Only count Issue-typed content. Type field is "ISSUE" but we double-check
+            // via __typename because draft-issue items can have type=DRAFT_ISSUE and
+            // should never count as repo-issue overlap.
+            if (node.type === "ISSUE" &&
+                node.content?.__typename === "Issue" &&
+                typeof node.content.number === "number") {
+                numbers.add(node.content.number);
+            }
+        }
+        if (!proj.items.pageInfo.hasNextPage)
+            break;
+        cursor = proj.items.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Detect repo issues that are absent from the project board.
+ *
+ * Returns the orphan summary when at least one orphan exists, or `null`
+ * when the board contains every OPEN repo issue.
+ *
+ * Returns `null` (not an empty result) so the `health_check` caller can
+ * omit the field entirely on a clean board — keeping the response tight
+ * for the common no-orphans case.
+ */
+export async function detectOrphanRepoIssues(client, owner, repo, projectOwner, projectNumber) {
+    const [repoSide, boardSide] = await Promise.all([
+        fetchRepoOpenIssueNumbers(client, owner, repo),
+        fetchBoardIssueNumbers(client, projectOwner, projectNumber),
+    ]);
+    // Orphans = OPEN issues in the repo whose number is NOT in the board set.
+    // We compare against the actual numbers walked rather than just totalCount,
+    // because a board may contain issues from OTHER repos (multi-repo project)
+    // — those would inflate `boardItems` but contribute zero to the overlap.
+    const orphanNumbers = [];
+    for (const n of repoSide.numbers) {
+        if (!boardSide.numbers.has(n))
+            orphanNumbers.push(n);
+    }
+    orphanNumbers.sort((a, b) => a - b);
+    if (orphanNumbers.length === 0)
+        return null;
+    return {
+        count: orphanNumbers.length,
+        repoOpen: repoSide.totalCount,
+        boardItems: boardSide.totalCount,
+        sample: orphanNumbers.slice(0, ORPHAN_SAMPLE_LIMIT),
+        note: ORPHAN_REPO_ISSUES_NOTE,
+    };
+}
+//# sourceMappingURL=health.js.map

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.119",
+  "version": "2.5.122",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",