ralph-hero-mcp-server 1.1.2 → 1.2.0

package/dist/github-client.js

@@ -30,7 +30,8 @@ export function createGitHubClient(clientConfig) {
         },
     });
     // Create a separate graphql instance for project operations if a different token is configured
-    const hasProjectToken = clientConfig.projectToken && clientConfig.projectToken !== clientConfig.token;
+    const hasProjectToken = clientConfig.projectToken &&
+        clientConfig.projectToken !== clientConfig.token;
     const projectGraphqlWithAuth = hasProjectToken
         ? graphql.defaults({
             headers: {
@@ -55,7 +56,8 @@ export function createGitHubClient(clientConfig) {
                 const insertPos = fullQuery.indexOf("{", fullQuery.indexOf(match[0])) + 1;
                 fullQuery =
                     fullQuery.slice(0, insertPos) +
-                        "\n  " + RATE_LIMIT_FRAGMENT +
+                        "\n  " +
+                        RATE_LIMIT_FRAGMENT +
                         fullQuery.slice(insertPos);
             }
         }
@@ -77,7 +79,7 @@ export function createGitHubClient(clientConfig) {
                 "status" in error &&
                 error.status === 403) {
                 const retryAfter = error && typeof error === "object" && "headers" in error
-                    ? (error.headers?.["retry-after"])
+                    ? error.headers?.["retry-after"]
                     : undefined;
                 if (retryAfter) {
                     const waitMs = parseInt(retryAfter, 10) * 1000;

package/dist/index.js

@@ -27,8 +27,7 @@ function resolveEnv(name) {
 }
 function initGitHubClient() {
     // Repo token: for repository operations (issues, PRs, comments)
-    const repoToken = resolveEnv("RALPH_GH_REPO_TOKEN") ||
-        resolveEnv("RALPH_HERO_GITHUB_TOKEN");
+    const repoToken = resolveEnv("RALPH_GH_REPO_TOKEN") || resolveEnv("RALPH_HERO_GITHUB_TOKEN");
     // Project token: for Projects V2 operations (fields, workflow state)
     // Falls back to repo token if not set
     const projectToken = resolveEnv("RALPH_GH_PROJECT_TOKEN") || repoToken;
@@ -63,7 +62,9 @@ function initGitHubClient() {
             "Project-level tools (workflow state, field updates) will not work.\n" +
             "Run /ralph-setup to configure your GitHub Project.");
     }
-    const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN") ? "RALPH_GH_REPO_TOKEN" : "RALPH_HERO_GITHUB_TOKEN";
+    const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN")
+        ? "RALPH_GH_REPO_TOKEN"
+        : "RALPH_HERO_GITHUB_TOKEN";
     console.error(`[ralph-hero] Repo token: ${repoTokenSource}`);
     if (projectToken !== repoToken) {
         console.error(`[ralph-hero] Project token: RALPH_GH_PROJECT_TOKEN (separate)`);
@@ -91,7 +92,10 @@ function registerCoreTools(server, client) {
             checks.auth = { status: "ok", detail: `Authenticated as ${login}` };
         }
         catch (e) {
-            checks.auth = { status: "fail", detail: `Auth failed: ${e instanceof Error ? e.message : String(e)}` };
+            checks.auth = {
+                status: "fail",
+                detail: `Auth failed: ${e instanceof Error ? e.message : String(e)}`,
+            };
         }
         // 2. Repo access check
         if (client.config.owner && client.config.repo) {
@@ -99,14 +103,23 @@ function registerCoreTools(server, client) {
                 await client.query(`query($owner: String!, $repo: String!) {
               repository(owner: $owner, name: $repo) { nameWithOwner }
             }`, { owner: client.config.owner, repo: client.config.repo });
-                checks.repoAccess = { status: "ok", detail: `${client.config.owner}/${client.config.repo}` };
+                checks.repoAccess = {
+                    status: "ok",
+                    detail: `${client.config.owner}/${client.config.repo}`,
+                };
             }
             catch (e) {
-                checks.repoAccess = { status: "fail", detail: `Cannot access repo: ${e instanceof Error ? e.message : String(e)}. Token may lack 'repo' scope or org access.` };
+                checks.repoAccess = {
+                    status: "fail",
+                    detail: `Cannot access repo: ${e instanceof Error ? e.message : String(e)}. Token may lack 'repo' scope or org access.`,
+                };
             }
         }
         else {
-            checks.repoAccess = { status: "skip", detail: "RALPH_GH_OWNER/RALPH_GH_REPO not set" };
+            checks.repoAccess = {
+                status: "skip",
+                detail: "RALPH_GH_OWNER/RALPH_GH_REPO not set",
+            };
         }
         // 3. Project access check (uses project token + project owner)
         const projOwner = resolveProjectOwner(client.config);
@@ -139,28 +152,46 @@ function registerCoreTools(server, client) {
                     }
                 }
                 if (project) {
-                    checks.projectAccess = { status: "ok", detail: `${project.title} (#${projNum})` };
+                    checks.projectAccess = {
+                        status: "ok",
+                        detail: `${project.title} (#${projNum})`,
+                    };
                     // 4. Required fields check
                     const requiredFields = ["Workflow State", "Priority", "Estimate"];
                     const fieldNames = project.fields.nodes.map((f) => f.name);
                     const missing = requiredFields.filter((f) => !fieldNames.includes(f));
                     if (missing.length === 0) {
-                        checks.requiredFields = { status: "ok", detail: "All required fields present" };
+                        checks.requiredFields = {
+                            status: "ok",
+                            detail: "All required fields present",
+                        };
                     }
                     else {
-                        checks.requiredFields = { status: "fail", detail: `Missing fields: ${missing.join(", ")}. Run /ralph-setup.` };
+                        checks.requiredFields = {
+                            status: "fail",
+                            detail: `Missing fields: ${missing.join(", ")}. Run /ralph-setup.`,
+                        };
                     }
                 }
                 else {
-                    checks.projectAccess = { status: "fail", detail: `Project #${projNum} not found for owner "${projOwner}". Check RALPH_GH_PROJECT_OWNER.` };
+                    checks.projectAccess = {
+                        status: "fail",
+                        detail: `Project #${projNum} not found for owner "${projOwner}". Check RALPH_GH_PROJECT_OWNER.`,
+                    };
                 }
             }
             catch (e) {
-                checks.projectAccess = { status: "fail", detail: `Project access failed: ${e instanceof Error ? e.message : String(e)}. Token may lack 'project' scope.` };
+                checks.projectAccess = {
+                    status: "fail",
+                    detail: `Project access failed: ${e instanceof Error ? e.message : String(e)}. Token may lack 'project' scope.`,
+                };
             }
         }
         else {
-            checks.projectAccess = { status: "skip", detail: "RALPH_GH_PROJECT_NUMBER not set" };
+            checks.projectAccess = {
+                status: "skip",
+                detail: "RALPH_GH_PROJECT_NUMBER not set",
+            };
         }
         // Summary
         const allOk = Object.values(checks).every((c) => c.status === "ok" || c.status === "skip");
@@ -172,8 +203,10 @@ function registerCoreTools(server, client) {
                 repo: client.config.repo || "(not set)",
                 projectOwner: resolveProjectOwner(client.config) || "(not set)",
                 projectNumber: client.config.projectNumber || "(not set)",
-                tokenMode: client.config.projectToken && client.config.projectToken !== client.config.token
-                    ? "dual-token" : "single-token",
+                tokenMode: client.config.projectToken &&
+                    client.config.projectToken !== client.config.token
+                    ? "dual-token"
+                    : "single-token",
             },
         });
     });

package/dist/lib/cache.js

@@ -66,7 +66,9 @@ export class SessionCache {
      */
     static queryKey(query, variables) {
         const normalized = query.replace(/\s+/g, " ").trim();
-        const varsKey = variables ? JSON.stringify(variables, Object.keys(variables).sort()) : "";
+        const varsKey = variables
+            ? JSON.stringify(variables, Object.keys(variables).sort())
+            : "";
         return `query:${normalized}:${varsKey}`;
     }
 }

package/dist/lib/group-detection.js

@@ -200,7 +200,10 @@ export async function detectGroup(client, owner, repo, seedNumber) {
     }
     // Check all discovered issues for dependency targets not yet in the set
     for (const issue of issueMap.values()) {
-        for (const depNum of [...issue.blockingNumbers, ...issue.blockedByNumbers]) {
+        for (const depNum of [
+            ...issue.blockingNumbers,
+            ...issue.blockedByNumbers,
+        ]) {
             if (!issueMap.has(depNum)) {
                 expandQueue.push(depNum);
             }
@@ -270,7 +273,11 @@ export async function detectGroup(client, owner, repo, seedNumber) {
     };
     return {
         groupTickets,
-        groupPrimary: { id: primary.id, number: primary.number, title: primary.title },
+        groupPrimary: {
+            id: primary.id,
+            number: primary.number,
+            title: primary.title,
+        },
         isGroup: groupTickets.length > 1,
         totalTickets: groupTickets.length,
     };
@@ -359,7 +366,10 @@ function filterGroupMembers(issueMap, seedNumber) {
             const issue = issueMap.get(num);
             if (!issue)
                 continue;
-            for (const depNum of [...issue.blockingNumbers, ...issue.blockedByNumbers]) {
+            for (const depNum of [
+                ...issue.blockingNumbers,
+                ...issue.blockedByNumbers,
+            ]) {
                 if (issueMap.has(depNum) && !members.has(depNum)) {
                     // Only add non-parent issues
                     const depIssue = issueMap.get(depNum);

package/dist/lib/pipeline-detection.js

@@ -84,8 +84,14 @@ export function detectPipelinePosition(issues, isGroup, groupPrimary) {
             required: isGroup,
             met: false,
             blocking: [
-                ...needsResearch.map((i) => ({ number: i.number, state: i.workflowState })),
-                ...inResearch.map((i) => ({ number: i.number, state: i.workflowState })),
+                ...needsResearch.map((i) => ({
+                    number: i.number,
+                    state: i.workflowState,
+                })),
+                ...inResearch.map((i) => ({
+                    number: i.number,
+                    state: i.workflowState,
+                })),
             ],
         };
         return buildResult("RESEARCH", `${needsResearch.length} need research, ${inResearch.length} in progress`, issues, isGroup, groupPrimary, convergence);
@@ -141,12 +147,23 @@ export function detectPipelinePosition(issues, isGroup, groupPrimary) {
 // Helpers
 // ---------------------------------------------------------------------------
 function buildResult(phase, reason, issues, isGroup, groupPrimary, convergence) {
+    // Derive recommendation from convergence state
+    let recommendation;
+    if (convergence.met) {
+        recommendation = "proceed";
+    }
+    else if (convergence.blocking.some((b) => b.state === "Human Needed")) {
+        recommendation = "escalate";
+    }
+    else {
+        recommendation = "wait";
+    }
     return {
         phase,
         reason,
         remainingPhases: REMAINING_PHASES[phase],
         issues,
-        convergence,
+        convergence: { ...convergence, recommendation },
         isGroup,
         groupPrimary,
     };

package/dist/lib/state-resolution.js

@@ -8,12 +8,12 @@
 // null means the intent is recognized but ambiguous for that command (multi-path)
 // undefined (missing key) means the intent isn't mapped for that command
 const SEMANTIC_INTENTS = {
-    "__LOCK__": {
+    __LOCK__: {
         ralph_research: "Research in Progress",
         ralph_plan: "Plan in Progress",
         ralph_impl: "In Progress",
     },
-    "__COMPLETE__": {
+    __COMPLETE__: {
         ralph_triage: null, // multi-path: caller must use direct state
         ralph_split: "Backlog",
         ralph_research: "Ready for Plan",
@@ -21,13 +21,19 @@ const SEMANTIC_INTENTS = {
         ralph_impl: "In Review",
         ralph_review: "In Progress",
     },
-    "__ESCALATE__": { "*": "Human Needed" },
-    "__CLOSE__": { "*": "Done" },
-    "__CANCEL__": { "*": "Canceled" },
+    __ESCALATE__: { "*": "Human Needed" },
+    __CLOSE__: { "*": "Done" },
+    __CANCEL__: { "*": "Canceled" },
 };
 // --- Per-command allowed output states (valid_output_states ∪ {lock_state}) ---
 const COMMAND_ALLOWED_STATES = {
-    ralph_triage: ["Research Needed", "Ready for Plan", "Done", "Canceled", "Human Needed"],
+    ralph_triage: [
+        "Research Needed",
+        "Ready for Plan",
+        "Done",
+        "Canceled",
+        "Human Needed",
+    ],
     ralph_split: ["Backlog"],
     ralph_research: ["Research in Progress", "Ready for Plan", "Human Needed"],
     ralph_plan: ["Plan in Progress", "Plan in Review", "Human Needed"],

package/dist/tools/issue-tools.js

@@ -7,8 +7,8 @@
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
 import { detectGroup } from "../lib/group-detection.js";
-import { detectPipelinePosition } from "../lib/pipeline-detection.js";
-import { isValidState, VALID_STATES, LOCK_STATES } from "../lib/workflow-states.js";
+import { detectPipelinePosition, } from "../lib/pipeline-detection.js";
+import { isValidState, VALID_STATES, LOCK_STATES, } from "../lib/workflow-states.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
 // ---------------------------------------------------------------------------
@@ -168,7 +168,8 @@ async function getCurrentFieldValue(client, fieldCache, owner, repo, issueNumber
         }
       }
     }`, { itemId: projectItemId });
-    const fieldValue = result.node?.fieldValues?.nodes?.find((fv) => fv.field?.name === fieldName && fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    const fieldValue = result.node?.fieldValues?.nodes?.find((fv) => fv.field?.name === fieldName &&
+        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
     return fieldValue?.name;
 }
 function resolveConfig(client, args) {
@@ -199,17 +200,44 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__list_issues
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository, optionally filtered by Workflow State, Estimate, Priority, or label. Returns issues with their project field values.", {
-        owner: z.string().optional().describe("GitHub owner (user or org). Defaults to GITHUB_OWNER env var"),
-        repo: z.string().optional().describe("Repository name. Defaults to GITHUB_REPO env var"),
-        workflowState: z.string().optional().describe("Filter by Workflow State name"),
-        estimate: z.string().optional().describe("Filter by Estimate (XS, S, M, L, XL)"),
-        priority: z.string().optional().describe("Filter by Priority (P0, P1, P2, P3)"),
+    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Returns: number, title, state, workflowState, estimate, priority, labels, assignees. Use workflowState filter to find issues in a specific phase. Recovery: if no results, broaden filters or check that issues exist in the project.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner (user or org). Defaults to GITHUB_OWNER env var"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Repository name. Defaults to GITHUB_REPO env var"),
+        workflowState: z
+            .string()
+            .optional()
+            .describe("Filter by Workflow State name"),
+        estimate: z
+            .string()
+            .optional()
+            .describe("Filter by Estimate (XS, S, M, L, XL)"),
+        priority: z
+            .string()
+            .optional()
+            .describe("Filter by Priority (P0, P1, P2, P3)"),
         label: z.string().optional().describe("Filter by label name"),
         query: z.string().optional().describe("Additional search query string"),
-        state: z.enum(["OPEN", "CLOSED"]).optional().default("OPEN").describe("Issue state filter (default: OPEN)"),
-        orderBy: z.enum(["CREATED_AT", "UPDATED_AT", "COMMENTS"]).optional().default("CREATED_AT").describe("Order by field"),
-        limit: z.number().optional().default(50).describe("Max items to return (default 50)"),
+        state: z
+            .enum(["OPEN", "CLOSED"])
+            .optional()
+            .default("OPEN")
+            .describe("Issue state filter (default: OPEN)"),
+        orderBy: z
+            .enum(["CREATED_AT", "UPDATED_AT", "COMMENTS"])
+            .optional()
+            .default("CREATED_AT")
+            .describe("Order by field"),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Max items to return (default 50)"),
     }, async (args) => {
         try {
             const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
@@ -282,7 +310,8 @@ export function registerIssueTools(server, client, fieldCache) {
             if (args.label) {
                 items = items.filter((item) => {
                     const content = item.content;
-                    const labels = content?.labels?.nodes || [];
+                    const labels = content?.labels?.nodes ||
+                        [];
                     return labels.some((l) => l.name === args.label);
                 });
             }
@@ -336,10 +365,21 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__get_issue
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__get_issue", "Get a single GitHub issue with full context: properties, project field values, relationships (parent, sub-issues, blocking, blocked-by), and recent comments", {
-        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"),
+    server.tool("ralph_hero__get_issue", "Get a single GitHub issue with full context: properties, project field values, relationships (parent, sub-issues, blocking, blocked-by), recent comments, and optional group detection. Returns group data by default so callers don't need a separate detect_group call. Key fields: number, title, workflowState, estimate, priority, parent, subIssues, blocking, blockedBy, comments, group.", {
+        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"),
         number: z.number().describe("Issue number"),
+        includeGroup: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include group detection results (default: true). Set to false to skip group detection and save API calls when group context is not needed."),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -402,7 +442,9 @@ export function registerIssueTools(server, client, fieldCache) {
                 return toolError(`Issue #${args.number} not found in ${owner}/${repo}`);
             }
             // Cache the node ID
-            client.getCache().set(`issue-node-id:${owner}/${repo}#${issue.number}`, issue.id, 30 * 60 * 1000);
+            client
+                .getCache()
+                .set(`issue-node-id:${owner}/${repo}#${issue.number}`, issue.id, 30 * 60 * 1000);
             // Extract project field values (find matching project if we know the project number)
             let workflowState;
             let estimate;
@@ -412,9 +454,12 @@ export function registerIssueTools(server, client, fieldCache) {
                 : issue.projectItems.nodes[0]; // Use first project item if no project configured
             if (projectItem) {
                 // Cache the project item ID
-                client.getCache().set(`project-item-id:${owner}/${repo}#${issue.number}`, projectItem.id, 30 * 60 * 1000);
+                client
+                    .getCache()
+                    .set(`project-item-id:${owner}/${repo}#${issue.number}`, projectItem.id, 30 * 60 * 1000);
                 for (const fv of projectItem.fieldValues.nodes) {
-                    if (fv.__typename === "ProjectV2ItemFieldSingleSelectValue" && fv.field) {
+                    if (fv.__typename === "ProjectV2ItemFieldSingleSelectValue" &&
+                        fv.field) {
                         switch (fv.field.name) {
                             case "Workflow State":
                                 workflowState = fv.name;
@@ -429,6 +474,32 @@ export function registerIssueTools(server, client, fieldCache) {
                     }
                 }
             }
+            // Optionally detect group context
+            let group = null;
+            if (args.includeGroup !== false) {
+                try {
+                    const { owner: cfgOwner, repo: cfgRepo } = resolveConfig(client, args);
+                    const groupResult = await detectGroup(client, cfgOwner, cfgRepo, args.number);
+                    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; don't fail the whole request
+                    group = null;
+                }
+            }
             return toolSuccess({
                 number: issue.number,
                 id: issue.id,
@@ -446,7 +517,11 @@ export function registerIssueTools(server, client, fieldCache) {
                 labels: issue.labels.nodes.map((l) => l.name),
                 assignees: issue.assignees.nodes.map((a) => a.login),
                 parent: issue.parent
-                    ? { number: issue.parent.number, title: issue.parent.title, state: issue.parent.state }
+                    ? {
+                        number: issue.parent.number,
+                        title: issue.parent.title,
+                        state: issue.parent.state,
+                    }
                     : null,
                 subIssuesSummary: issue.subIssuesSummary,
                 subIssues: issue.subIssues.nodes.map((si) => ({
@@ -470,6 +545,7 @@ export function registerIssueTools(server, client, fieldCache) {
                     author: c.author?.login || "unknown",
                     createdAt: c.createdAt,
                 })),
+                group,
             });
         }
         catch (error) {
@@ -480,14 +556,26 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__create_issue
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__create_issue", "Create a GitHub issue and add it to the project with optional field values (Workflow State, Estimate, Priority)", {
-        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"),
+    server.tool("ralph_hero__create_issue", "Create a GitHub issue and add it to the project with optional field values. Returns: number, id, title, url, projectItemId, fieldsSet. Recovery: if field value fails, verify the option name matches exactly (case-sensitive).", {
+        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"),
         title: z.string().describe("Issue title"),
         body: z.string().optional().describe("Issue body (Markdown)"),
         labels: z.array(z.string()).optional().describe("Label names to apply"),
-        assignees: z.array(z.string()).optional().describe("GitHub usernames to assign"),
-        workflowState: z.string().optional().describe("Initial Workflow State name"),
+        assignees: z
+            .array(z.string())
+            .optional()
+            .describe("GitHub usernames to assign"),
+        workflowState: z
+            .string()
+            .optional()
+            .describe("Initial Workflow State name"),
         estimate: z.string().optional().describe("Estimate (XS, S, M, L, XL)"),
         priority: z.string().optional().describe("Priority (P0, P1, P2, P3)"),
     }, async (args) => {
@@ -543,7 +631,9 @@ export function registerIssueTools(server, client, fieldCache) {
             });
             const issue = createResult.createIssue.issue;
             // Cache the node ID
-            client.getCache().set(`issue-node-id:${owner}/${repo}#${issue.number}`, issue.id, 30 * 60 * 1000);
+            client
+                .getCache()
+                .set(`issue-node-id:${owner}/${repo}#${issue.number}`, issue.id, 30 * 60 * 1000);
             // Step 4: Add to project
             const projectId = fieldCache.getProjectId();
             if (!projectId) {
@@ -559,7 +649,9 @@ export function registerIssueTools(server, client, fieldCache) {
           }`, { projectId, contentId: issue.id });
             const projectItemId = addResult.addProjectV2ItemById.item.id;
             // Cache project item ID
-            client.getCache().set(`project-item-id:${owner}/${repo}#${issue.number}`, projectItemId, 30 * 60 * 1000);
+            client
+                .getCache()
+                .set(`project-item-id:${owner}/${repo}#${issue.number}`, projectItemId, 30 * 60 * 1000);
             // Step 5: Set field values
             if (args.workflowState) {
                 await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", args.workflowState);
@@ -591,14 +683,26 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__update_issue
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__update_issue", "Update a GitHub issue's basic properties (title, body, labels, assignees)", {
-        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"),
+    server.tool("ralph_hero__update_issue", "Update a GitHub issue's basic properties (title, body, labels, assignees). Returns: number, title, url. Use update_workflow_state for state changes, update_estimate for estimates, update_priority for priorities.", {
+        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"),
         number: z.number().describe("Issue number"),
         title: z.string().optional().describe("New issue title"),
         body: z.string().optional().describe("New issue body (Markdown)"),
-        labels: z.array(z.string()).optional().describe("Label names (replaces existing labels)"),
-        assignees: z.array(z.string()).optional().describe("GitHub usernames to assign (replaces existing)"),
+        labels: z
+            .array(z.string())
+            .optional()
+            .describe("Label names (replaces existing labels)"),
+        assignees: z
+            .array(z.string())
+            .optional()
+            .describe("GitHub usernames to assign (replaces existing)"),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -653,13 +757,23 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__update_workflow_state
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__update_workflow_state", "Change an issue's Workflow State. Accepts semantic intents (__LOCK__, __COMPLETE__, __ESCALATE__, __CLOSE__, __CANCEL__) or direct state names. The command parameter enables validation.", {
-        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"),
+    server.tool("ralph_hero__update_workflow_state", "Change an issue's Workflow State using semantic intents or direct state names. Returns: number, previousState, newState, command. Semantic intents: __LOCK__ (lock for processing), __COMPLETE__ (mark done), __ESCALATE__ (needs human), __CLOSE__, __CANCEL__. Recovery: if state transition fails, verify the issue is in the project and the state name is valid.", {
+        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"),
         number: z.number().describe("Issue number"),
-        state: z.string().describe("Target state: semantic intent (__LOCK__, __COMPLETE__, __ESCALATE__, __CLOSE__, __CANCEL__) " +
+        state: z
+            .string()
+            .describe("Target state: semantic intent (__LOCK__, __COMPLETE__, __ESCALATE__, __CLOSE__, __CANCEL__) " +
             "or direct state name (e.g., 'Research Needed', 'In Progress')"),
-        command: z.string().describe("Ralph command making this transition (e.g., 'ralph_research', 'ralph_plan'). " +
+        command: z
+            .string()
+            .describe("Ralph command making this transition (e.g., 'ralph_research', 'ralph_plan'). " +
             "Required for validation and semantic intent resolution."),
     }, async (args) => {
         try {
@@ -693,9 +807,15 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__update_estimate
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__update_estimate", "Change an issue's Estimate in the project (XS, S, M, L, XL)", {
-        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"),
+    server.tool("ralph_hero__update_estimate", "Change an issue's Estimate in the project. Returns: number, estimate. Valid values: XS, S, M, L, XL. Recovery: if the issue is not in the project, add it first via create_issue.", {
+        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"),
         number: z.number().describe("Issue number"),
         estimate: z.string().describe("Estimate value (XS, S, M, L, XL)"),
     }, async (args) => {
@@ -717,9 +837,15 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__update_priority
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__update_priority", "Change an issue's Priority in the project (P0, P1, P2, P3)", {
-        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"),
+    server.tool("ralph_hero__update_priority", "Change an issue's Priority in the project. Returns: number, priority. Valid values: P0, P1, P2, P3. Recovery: if the issue is not in the project, add it first via create_issue.", {
+        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"),
         number: z.number().describe("Issue number"),
         priority: z.string().describe("Priority value (P0, P1, P2, P3)"),
     }, async (args) => {
@@ -741,9 +867,15 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__create_comment
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__create_comment", "Add a comment to a GitHub issue", {
-        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"),
+    server.tool("ralph_hero__create_comment", "Add a comment to a GitHub issue. Returns: commentId, issueNumber. Recovery: if issue not found, verify the issue number exists in the repository.", {
+        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"),
         number: z.number().describe("Issue number"),
         body: z.string().describe("Comment body (Markdown)"),
     }, async (args) => {
@@ -773,9 +905,15 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__detect_pipeline_position
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__detect_pipeline_position", "Determine the current pipeline position for an issue or group. Returns the phase to execute and remaining phases. Replaces manual interpretation of workflow state tables.", {
-        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"),
+    server.tool("ralph_hero__detect_pipeline_position", "Determine which workflow phase to execute next for an issue or its group. Returns: phase (SPLIT/TRIAGE/RESEARCH/PLAN/REVIEW/IMPLEMENT/COMPLETE/HUMAN_GATE/TERMINAL), convergence status with recommendation (proceed/wait/escalate), all group member states, and remaining phases. Call this INSTEAD of separate detect_group + check_convergence calls. Recovery: if issue not found, verify the issue number and that it has been added to the project.", {
+        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"),
         number: z.number().describe("Issue number (seed for group detection)"),
     }, async (args) => {
         try {
@@ -812,11 +950,19 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__check_convergence
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__check_convergence", "Check if all issues in a group have reached the required state for the next phase. Returns convergence status with details on blocking issues.", {
-        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"),
+    server.tool("ralph_hero__check_convergence", "Check if all issues in a group have reached the required state for the next phase. Returns: converged, targetState, total, ready, blocking (with distanceToTarget), recommendation (proceed/wait/escalate). Note: detect_pipeline_position already includes convergence data; use this only when checking convergence against a specific target state not covered by pipeline detection.", {
+        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"),
         number: z.number().describe("Issue number (any issue in the group)"),
-        targetState: z.string().describe("The state all issues must be in (e.g., 'Ready for Plan')"),
+        targetState: z
+            .string()
+            .describe("The state all issues must be in (e.g., 'Ready for Plan')"),
     }, async (args) => {
         try {
             // Validate target state
@@ -839,12 +985,16 @@ export function registerIssueTools(server, client, fieldCache) {
                     targetState: args.targetState,
                     total: 1,
                     ready: atTarget ? 1 : 0,
-                    blocking: atTarget ? [] : [{
-                            number: args.number,
-                            title: group.groupPrimary.title,
-                            currentState: state.workflowState || "unknown",
-                            distanceToTarget: computeDistance(state.workflowState || "unknown", args.targetState),
-                        }],
+                    blocking: atTarget
+                        ? []
+                        : [
+                            {
+                                number: args.number,
+                                title: group.groupPrimary.title,
+                                currentState: state.workflowState || "unknown",
+                                distanceToTarget: computeDistance(state.workflowState || "unknown", args.targetState),
+                            },
+                        ],
                     recommendation: atTarget ? "proceed" : "wait",
                 });
             }
@@ -895,11 +1045,23 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__pick_actionable_issue
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__pick_actionable_issue", "Find the highest-priority issue that matches the given workflow state and is not blocked or locked. 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"),
-        workflowState: z.string().describe("Target workflow state (e.g., 'Research Needed', 'Ready for Plan')"),
-        maxEstimate: z.string().optional().default("S").describe("Maximum estimate to include (XS, S, M, L, XL). Default: S"),
+    server.tool("ralph_hero__pick_actionable_issue", "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. Recovery: if no issues found, try a different workflowState or increase maxEstimate.", {
+        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"),
+        workflowState: z
+            .string()
+            .describe("Target workflow state (e.g., 'Research Needed', 'Ready for Plan')"),
+        maxEstimate: z
+            .string()
+            .optional()
+            .default("S")
+            .describe("Maximum estimate to include (XS, S, M, L, XL). Default: S"),
     }, async (args) => {
         try {
             // Validate workflow state
@@ -999,7 +1161,12 @@ export function registerIssueTools(server, client, fieldCache) {
                 return !blockedBy.nodes.some((dep) => dep.state === "OPEN");
             });
             // Sort by priority (P0 > P1 > P2 > P3 > none)
-            const priorityOrder = { P0: 0, P1: 1, P2: 2, P3: 3 };
+            const priorityOrder = {
+                P0: 0,
+                P1: 1,
+                P2: 2,
+                P3: 3,
+            };
             candidates.sort((a, b) => {
                 const pA = getFieldValue(a, "Priority");
                 const pB = getFieldValue(b, "Priority");
@@ -1016,10 +1183,34 @@ export function registerIssueTools(server, client, fieldCache) {
             }
             const best = candidates[0];
             const content = best.content;
+            const issueNumber = content.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: content.number,
+                    number: issueNumber,
                     title: content.title,
                     description: content.body || "",
                     workflowState: getFieldValue(best, "Workflow State"),
@@ -1028,6 +1219,7 @@ export function registerIssueTools(server, client, fieldCache) {
                     isLocked: false,
                     blockedBy: [],
                 },
+                group,
                 alternatives: candidates.length - 1,
             });
         }
@@ -1038,7 +1230,8 @@ export function registerIssueTools(server, client, fieldCache) {
     });
 }
 function getFieldValue(item, fieldName) {
-    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName && fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName &&
+        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
     return fieldValue?.name;
 }
 // ---------------------------------------------------------------------------

package/dist/tools/project-tools.js

@@ -10,19 +10,59 @@ import { toolSuccess, toolError } from "../types.js";
 import { resolveProjectOwner } from "../types.js";
 const WORKFLOW_STATE_OPTIONS = [
     { name: "Backlog", color: "GRAY", description: "Awaiting triage" },
-    { name: "Research Needed", color: "PURPLE", description: "Needs investigation before planning" },
-    { name: "Research in Progress", color: "PURPLE", description: "Investigation underway (locked)" },
-    { name: "Ready for Plan", color: "BLUE", description: "Research complete, ready for planning" },
-    { name: "Plan in Progress", color: "BLUE", description: "Plan being written (locked)" },
-    { name: "Plan in Review", color: "BLUE", description: "Plan awaiting approval" },
-    { name: "In Progress", color: "ORANGE", description: "Implementation underway" },
-    { name: "In Review", color: "YELLOW", description: "PR created, awaiting code review" },
+    {
+        name: "Research Needed",
+        color: "PURPLE",
+        description: "Needs investigation before planning",
+    },
+    {
+        name: "Research in Progress",
+        color: "PURPLE",
+        description: "Investigation underway (locked)",
+    },
+    {
+        name: "Ready for Plan",
+        color: "BLUE",
+        description: "Research complete, ready for planning",
+    },
+    {
+        name: "Plan in Progress",
+        color: "BLUE",
+        description: "Plan being written (locked)",
+    },
+    {
+        name: "Plan in Review",
+        color: "BLUE",
+        description: "Plan awaiting approval",
+    },
+    {
+        name: "In Progress",
+        color: "ORANGE",
+        description: "Implementation underway",
+    },
+    {
+        name: "In Review",
+        color: "YELLOW",
+        description: "PR created, awaiting code review",
+    },
     { name: "Done", color: "GREEN", description: "Completed and merged" },
-    { name: "Human Needed", color: "RED", description: "Escalated - requires human intervention" },
-    { name: "Canceled", color: "GRAY", description: "Ticket canceled or superseded" },
+    {
+        name: "Human Needed",
+        color: "RED",
+        description: "Escalated - requires human intervention",
+    },
+    {
+        name: "Canceled",
+        color: "GRAY",
+        description: "Ticket canceled or superseded",
+    },
 ];
 const PRIORITY_OPTIONS = [
-    { name: "P0", color: "RED", description: "Critical - Drop everything, fix now" },
+    {
+        name: "P0",
+        color: "RED",
+        description: "Critical - Drop everything, fix now",
+    },
     { name: "P1", color: "ORANGE", description: "High - Must do this sprint" },
     { name: "P2", color: "YELLOW", description: "Medium - Should do soon" },
     { name: "P3", color: "GRAY", description: "Low - Nice to have" },
@@ -138,8 +178,14 @@ export function registerProjectTools(server, client, fieldCache) {
     // ralph_hero__get_project
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__get_project", "Get a GitHub Project V2 with all fields and their options", {
-        owner: z.string().optional().describe("GitHub owner (user or org). Defaults to GITHUB_OWNER env var"),
-        number: z.number().optional().describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner (user or org). Defaults to GITHUB_OWNER env var"),
+        number: z
+            .number()
+            .optional()
+            .describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -185,12 +231,31 @@ export function registerProjectTools(server, client, fieldCache) {
     // ralph_hero__list_project_items
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_project_items", "List items in a GitHub Project V2, optionally filtered by Workflow State, Estimate, or Priority", {
-        owner: z.string().optional().describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
-        number: z.number().optional().describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
-        workflowState: z.string().optional().describe("Filter by Workflow State name"),
-        estimate: z.string().optional().describe("Filter by Estimate name (XS, S, M, L, XL)"),
-        priority: z.string().optional().describe("Filter by Priority name (P0, P1, P2, P3)"),
-        limit: z.number().optional().default(50).describe("Max items to return (default 50)"),
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
+        number: z
+            .number()
+            .optional()
+            .describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
+        workflowState: z
+            .string()
+            .optional()
+            .describe("Filter by Workflow State name"),
+        estimate: z
+            .string()
+            .optional()
+            .describe("Filter by Estimate name (XS, S, M, L, XL)"),
+        priority: z
+            .string()
+            .optional()
+            .describe("Filter by Priority name (P0, P1, P2, P3)"),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Max items to return (default 50)"),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -303,7 +368,8 @@ export function registerProjectTools(server, client, fieldCache) {
     });
 }
 function getFieldValue(item, fieldName) {
-    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName && fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName &&
+        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
     return fieldValue?.name;
 }
 async function fetchProject(client, owner, number) {

package/dist/tools/relationship-tools.js

@@ -9,7 +9,7 @@
  */
 import { z } from "zod";
 import { detectGroup } from "../lib/group-detection.js";
-import { isValidState, isEarlierState, VALID_STATES } from "../lib/workflow-states.js";
+import { isValidState, isEarlierState, VALID_STATES, } from "../lib/workflow-states.js";
 import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
 // ---------------------------------------------------------------------------
 // Helper: Resolve issue number to node ID (with caching)
@@ -51,11 +51,23 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__add_sub_issue
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__add_sub_issue", "Create a parent/child (sub-issue) relationship between two GitHub issues. The parent issue becomes the container for the child issue.", {
-        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"),
+        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"),
         parentNumber: z.number().describe("Parent issue number"),
-        childNumber: z.number().describe("Child issue number (will become sub-issue of parent)"),
-        replaceParent: z.boolean().optional().default(false).describe("If true, move child even if it already has a parent"),
+        childNumber: z
+            .number()
+            .describe("Child issue number (will become sub-issue of parent)"),
+        replaceParent: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, move child even if it already has a parent"),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -93,8 +105,14 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__list_sub_issues
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_sub_issues", "List all sub-issues (children) of a parent GitHub issue, with completion summary", {
-        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"),
+        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"),
         number: z.number().describe("Parent issue number"),
     }, async (args) => {
         try {
@@ -133,7 +151,8 @@ export function registerRelationshipTools(server, client, fieldCache) {
                     total: issue.subIssues.nodes.length,
                     completed: issue.subIssues.nodes.filter((si) => si.state === "CLOSED").length,
                     percentCompleted: issue.subIssues.nodes.length > 0
-                        ? Math.round((issue.subIssues.nodes.filter((si) => si.state === "CLOSED").length /
+                        ? Math.round((issue.subIssues.nodes.filter((si) => si.state === "CLOSED")
+                            .length /
                             issue.subIssues.nodes.length) *
                             100)
                         : 0,
@@ -150,10 +169,20 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__add_dependency
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__add_dependency", "Create a blocking dependency between two GitHub issues. The 'blockingNumber' issue blocks the 'blockedNumber' issue.", {
-        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"),
-        blockedNumber: z.number().describe("Issue number that IS blocked (cannot proceed until blocker is done)"),
-        blockingNumber: z.number().describe("Issue number that IS the blocker (must be completed first)"),
+        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"),
+        blockedNumber: z
+            .number()
+            .describe("Issue number that IS blocked (cannot proceed until blocker is done)"),
+        blockingNumber: z
+            .number()
+            .describe("Issue number that IS the blocker (must be completed first)"),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -190,8 +219,14 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__remove_dependency
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__remove_dependency", "Remove a blocking dependency between two GitHub issues", {
-        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"),
+        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"),
         blockedNumber: z.number().describe("Issue number that was blocked"),
         blockingNumber: z.number().describe("Issue number that was the blocker"),
     }, async (args) => {
@@ -230,8 +265,14 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__list_dependencies
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_dependencies", "List all dependencies (blocking and blocked-by) for a GitHub issue", {
-        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"),
+        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"),
         number: z.number().describe("Issue number"),
     }, async (args) => {
         try {
@@ -290,9 +331,17 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__detect_group
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__detect_group", "Detect the group of related issues by traversing sub-issues and dependencies transitively from a seed issue. Returns all group members in topological order (blockers first). Used by Ralph workflow to discover atomic implementation groups.", {
-        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"),
-        number: z.number().describe("Seed issue number to start group detection from"),
+        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"),
+        number: z
+            .number()
+            .describe("Seed issue number to start group detection from"),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -308,10 +357,18 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // ralph_hero__advance_children
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__advance_children", "Advance all child/sub-issues of a parent to match the parent's new state. Only advances children that are in earlier workflow states. Returns what changed, what was skipped, and any errors.", {
-        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"),
+        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"),
         number: z.number().describe("Parent issue number"),
-        targetState: z.string().describe("State to advance children to (e.g., 'Research Needed', 'Ready for Plan')"),
+        targetState: z
+            .string()
+            .describe("State to advance children to (e.g., 'Research Needed', 'Ready for Plan')"),
     }, async (args) => {
         try {
             // Validate target state
@@ -506,7 +563,8 @@ async function getCurrentFieldValueForRelationships(client, fieldCache, owner, r
         }
       }
     }`, { itemId: projectItemId });
-    const fieldValue = result.node?.fieldValues?.nodes?.find((fv) => fv.field?.name === "Workflow State" && fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    const fieldValue = result.node?.fieldValues?.nodes?.find((fv) => fv.field?.name === "Workflow State" &&
+        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
     return fieldValue?.name;
 }
 async function updateProjectItemFieldForRelationships(client, fieldCache, projectItemId, fieldName, optionName) {

package/dist/tools/view-tools.js

@@ -17,8 +17,14 @@ export function registerViewTools(server, client, fieldCache) {
     // ralph_hero__list_views
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_views", "List all views for a GitHub Project V2", {
-        owner: z.string().optional().describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
-        number: z.number().optional().describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
+        number: z
+            .number()
+            .optional()
+            .describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -52,14 +58,35 @@ export function registerViewTools(server, client, fieldCache) {
     // ralph_hero__update_field_options
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__update_field_options", "Update a single-select field's options (names, colors, descriptions). Overwrites ALL existing options — include unchanged options to preserve them.", {
-        owner: z.string().optional().describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
-        number: z.number().optional().describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
-        fieldName: z.string().describe("Name of the single-select field to update (e.g., 'Workflow State', 'Priority', 'Estimate')"),
-        options: z.array(z.object({
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
+        number: z
+            .number()
+            .optional()
+            .describe("Project number. Defaults to RALPH_GH_PROJECT_NUMBER env var"),
+        fieldName: z
+            .string()
+            .describe("Name of the single-select field to update (e.g., 'Workflow State', 'Priority', 'Estimate')"),
+        options: z
+            .array(z.object({
             name: z.string().describe("Option name"),
-            color: z.enum(["GRAY", "BLUE", "GREEN", "YELLOW", "ORANGE", "RED", "PINK", "PURPLE"]).describe("Display color"),
+            color: z
+                .enum([
+                "GRAY",
+                "BLUE",
+                "GREEN",
+                "YELLOW",
+                "ORANGE",
+                "RED",
+                "PINK",
+                "PURPLE",
+            ])
+                .describe("Display color"),
             description: z.string().describe("Description text"),
-        })).describe("Complete list of options (replaces all existing options)"),
+        }))
+            .describe("Complete list of options (replaces all existing options)"),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -144,7 +171,11 @@ async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
             const result = await client.projectQuery(QUERY.replace("OWNER_TYPE", ownerType), { owner, number: projectNumber }, { cache: true });
             const project = result[ownerType]?.projectV2;
             if (project) {
-                fieldCache.populate(project.id, project.fields.nodes.map((f) => ({ id: f.id, name: f.name, options: f.options })));
+                fieldCache.populate(project.id, project.fields.nodes.map((f) => ({
+                    id: f.id,
+                    name: f.name,
+                    options: f.options,
+                })));
                 return;
             }
         }

package/package.json

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