ralph-hero-mcp-server 2.5.122 → 2.5.124

package/dist/lib/dashboard-fetch.js

@@ -186,7 +186,7 @@ export async function fetchDashboardItems(client, fieldCache, projectNumber) {
         catch {
             // Non-fatal — proceed without title.
         }
-        const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+        const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { scanUntilExhausted: true });
         items.push(...toDashboardItems(result.nodes, pn, projectTitle));
     }
     return { items, warnings };

package/dist/lib/pagination.js

@@ -26,19 +26,32 @@ function getNestedValue(obj, path) {
  * @param variables - Variables for the query (cursor will be added/updated automatically)
  * @param connectionPath - Dot-separated path to the connection in the response (e.g., "node.projectV2.items")
  * @param options - Pagination options
- * @returns All accumulated nodes from all pages
+ * @returns All accumulated nodes from all pages, plus a `truncated` flag.
  */
 export async function paginateConnection(executeQuery, query, variables, connectionPath, options = {}) {
     const pageSize = options.pageSize ?? 100;
     const maxItems = options.maxItems ?? Infinity;
+    const scanUntilExhausted = options.scanUntilExhausted ?? false;
+    const until = options.until;
     const allNodes = [];
     let cursor = null;
     let totalCount;
-    while (allNodes.length < maxItems) {
+    let truncated = false;
+    let untilStopped = false;
+    // When scanUntilExhausted is true, ignore the maxItems cap entirely.
+    // Otherwise, use maxItems as the upper bound.
+    const effectiveCap = scanUntilExhausted ? Infinity : maxItems;
+    while (allNodes.length < effectiveCap) {
+        // `first` is bounded by pageSize, but also by remaining capacity when a
+        // finite cap is in play. Under scanUntilExhausted, cap is Infinity so we
+        // always request a full page.
+        const remaining = effectiveCap === Infinity
+            ? pageSize
+            : Math.min(pageSize, effectiveCap - allNodes.length);
         const queryVars = {
             ...variables,
             cursor,
-            first: Math.min(pageSize, maxItems - allNodes.length),
+            first: remaining,
         };
         const response = await executeQuery(query, queryVars);
         const connection = getNestedValue(response, connectionPath);
@@ -48,12 +61,38 @@ export async function paginateConnection(executeQuery, query, variables, connect
         if (connection.totalCount !== undefined) {
             totalCount = connection.totalCount;
         }
-        allNodes.push(...connection.nodes);
+        const pageNodes = connection.nodes;
+        allNodes.push(...pageNodes);
+        // Predicate-based early stop: evaluated AFTER appending the page so the
+        // caller always gets the page that triggered the stop fully included.
+        if (until) {
+            for (const node of pageNodes) {
+                if (!until(node, pageNodes, allNodes)) {
+                    untilStopped = true;
+                    break;
+                }
+            }
+        }
+        if (untilStopped) {
+            break;
+        }
         if (!connection.pageInfo.hasNextPage || !connection.pageInfo.endCursor) {
             break;
         }
+        // Detect cap-without-exhaustion truncation: we filled to maxItems but the
+        // connection still has more pages. Only meaningful when the caller is
+        // using a finite cap and is NOT in scan-until-exhausted mode.
+        if (!scanUntilExhausted &&
+            maxItems !== Infinity &&
+            allNodes.length >= maxItems &&
+            connection.pageInfo.hasNextPage) {
+            truncated = true;
+            const totalSuffix = totalCount !== undefined ? `, totalCount=${totalCount}` : "";
+            console.warn(`paginateConnection: truncated at maxItems=${maxItems} for connectionPath="${connectionPath}"${totalSuffix}; more pages available but not fetched. Pass { scanUntilExhausted: true } to fetch all items.`);
+            break;
+        }
         cursor = connection.pageInfo.endCursor;
     }
-    return { nodes: allNodes, totalCount };
+    return { nodes: allNodes, totalCount, truncated };
 }
 //# sourceMappingURL=pagination.js.map

package/dist/tools/dashboard-tools.js

@@ -20,7 +20,7 @@ export { DASHBOARD_ITEMS_QUERY, toDashboardItems };
 // Register dashboard tools
 // ---------------------------------------------------------------------------
 export function registerDashboardTools(server, client, fieldCache) {
-    server.tool("ralph_hero__pipeline_dashboard", "Generate pipeline status dashboard with issue counts per workflow phase, health indicators, and formatted output. Returns structured data with optional markdown or ASCII rendering. Top-level `boardItems` is the raw count of all project items including PRs (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-phase `count` values reflect that phase's bucket; for `Done` and `Canceled`, the count is bounded by `doneWindowDays` (default 7) and may be smaller than the actual phase membership. Per-iteration `totalIssues` is a distinct concept (iteration-scoped count).", {
+    server.tool("ralph_hero__pipeline_dashboard", "Generate pipeline status dashboard with issue counts per workflow phase, health indicators, and formatted output. Fetches all project items (full project scan, no silent 500-cap) so phase counts reflect every item regardless of board position. Returns structured data with optional markdown or ASCII rendering. Top-level `boardItems` is the raw count of all project items including PRs (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-phase `count` values reflect that phase's bucket; for `Done` and `Canceled`, the count is bounded by `doneWindowDays` (default 7) and may be smaller than the actual phase membership. Per-iteration `totalIssues` is a distinct concept (iteration-scoped count).", {
         owner: z
             .string()
             .optional()

package/dist/tools/directions-tools.js

@@ -244,7 +244,7 @@ export function makeRunDirections(client, fieldCache) {
                     // 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 });
+                const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { scanUntilExhausted: true });
                 allItems.push(...toDashboardItems(result.nodes, pn));
             }
             // Compute unblock signals for any Human Needed candidates so the
@@ -307,7 +307,7 @@ export function makeRunDirections(client, fieldCache) {
 // ---------------------------------------------------------------------------
 export function registerDirectionsTools(server, client, fieldCache) {
     const runDirections = makeRunDirections(client, fieldCache);
-    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`.", {
+    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Fetches all project items (full project scan, no silent 500-cap) so candidate selection covers every item regardless of board position. 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()
             .optional()

package/dist/tools/hygiene-tools.js

@@ -14,7 +14,7 @@ import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } f
 // Register hygiene tools
 // ---------------------------------------------------------------------------
 export function registerHygieneTools(server, client, fieldCache) {
-    server.tool("ralph_hero__project_hygiene", "Generate a project board hygiene report. Identifies archive candidates, stale items, orphaned backlog entries, missing fields, WIP violations, and duplicate candidates. Returns: report with 7 sections + summary stats. Top-level `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-category counts in `summary` (archiveCandidateCount, staleCount, orphanCount, fieldCoveragePercent, wipViolationCount, duplicateCandidateCount) are post-filter and represent distinct buckets.", {
+    server.tool("ralph_hero__project_hygiene", "Generate a project board hygiene report. Identifies archive candidates, stale items, orphaned backlog entries, missing fields, WIP violations, and duplicate candidates. Fetches all project items (full project scan, no silent 500-cap) so hygiene checks cover every item regardless of board position. Returns: report with 7 sections + summary stats. Top-level `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-category counts in `summary` (archiveCandidateCount, staleCount, orphanCount, fieldCoveragePercent, wipViolationCount, duplicateCandidateCount) are post-filter and represent distinct buckets.", {
         owner: z
             .string()
             .optional()

package/dist/tools/issue-tools.js

@@ -24,7 +24,7 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__list_issues
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Returns: number, title, state, workflowState, estimate, priority, iteration, labels, assignees. Use workflowState filter to find issues in a specific phase. Use iteration filter with @current/@next or sprint title. Recovery: if no results, broaden filters or check that issues exist in the project.", {
+    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Fetches all project items (full project scan, no silent 500-cap) and applies filters client-side, so items at any board position are visible regardless of default ordering. Returns: number, title, state, workflowState, estimate, priority, iteration, labels, assignees. Use workflowState filter to find issues in a specific phase. Use iteration filter with @current/@next or sprint title. Recovery: if no results, broaden filters or check that issues exist in the project.", {
         owner: z
             .string()
             .optional()
@@ -186,7 +186,7 @@ export function registerIssueTools(server, client, fieldCache) {
                 }
               }
             }
-          }`, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+          }`, { projectId, first: 100 }, "node.items", { scanUntilExhausted: true });
             // Filter items
             let items = itemsResult.nodes.filter((item) => item.type === "ISSUE" && item.content);
             // Filter by issue state

package/dist/tools/relationship-tools.js

@@ -673,7 +673,7 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__list_groups
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__list_groups", "Discover all parent issues (groups) with sub-issues in a project. Returns parent info with child counts and optional child expansion. " +
+    server.tool("ralph_hero__list_groups", "Discover all parent issues (groups) with sub-issues in a project. Fetches all project items (full project scan, no silent 500-cap) so parents at any board position are visible regardless of default ordering; the internal lookupMap covers all items for child workflow-state resolution. Returns parent info with child counts and optional child expansion. " +
         "Single paginated pass over project items — no per-group API calls needed.", {
         owner: z
             .string()
@@ -760,7 +760,7 @@ export function registerRelationshipTools(server, client, fieldCache) {
                 }
               }
             }
-          }`, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+          }`, { projectId, first: 100 }, "node.items", { scanUntilExhausted: true });
             // Build lookup map: number -> { workflowState, estimate, priority }
             const lookupMap = new Map();
             for (const item of itemsResult.nodes) {

package/dist/tools/trends-tools.js

@@ -19,7 +19,7 @@ import { parseDateMath } from "../lib/date-math.js";
 import { computeTrends } from "../lib/trends.js";
 import { resolveProjectOwner, toolError, toolSuccess } from "../types.js";
 export function registerTrendsTools(server, client, fieldCache) {
-    server.tool("ralph_hero__capture_snapshot", "Capture a single point-in-time snapshot of the project dashboard + metrics and append it to the partitioned JSONL file at ~/.ralph-hero/snapshots/<owner>/<projectNumber>.jsonl. Append-only, schema-versioned. Returns the snapshot row that was written.", {
+    server.tool("ralph_hero__capture_snapshot", "Capture a single point-in-time snapshot of the project dashboard + metrics and append it to the partitioned JSONL file at ~/.ralph-hero/snapshots/<owner>/<projectNumber>.jsonl. Fetches all project items (full project scan, no silent 500-cap) so per-phase WIP and totals reflect every item regardless of board position. Append-only, schema-versioned. Returns the snapshot row that was written.", {
         projectNumber: z
             .number()
             .optional()

package/package.json

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