ralph-hero-mcp-server 2.4.89 → 2.4.91

package/dist/tools/issue-tools.js

@@ -14,7 +14,7 @@ import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Register issue tools
 // ---------------------------------------------------------------------------
@@ -338,6 +338,11 @@ export function registerIssueTools(server, client, fieldCache) {
             .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."),
+        includePipeline: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include pipeline position: phase, convergence, member states, remaining phases. Auto-enables includeGroup."),
     }, async (args) => {
         try {
             const { owner, repo } = resolveConfig(client, args);
@@ -434,7 +439,9 @@ export function registerIssueTools(server, client, fieldCache) {
             }
             // Optionally detect group context
             let group = null;
-            if (args.includeGroup !== false) {
+            // Force includeGroup when includePipeline is requested
+            const shouldIncludeGroup = args.includePipeline || args.includeGroup !== false;
+            if (shouldIncludeGroup) {
                 try {
                     const { owner: cfgOwner, repo: cfgRepo } = resolveConfig(client, args);
                     const groupResult = await detectGroup(client, cfgOwner, cfgRepo, args.number);
@@ -458,6 +465,88 @@ export function registerIssueTools(server, client, fieldCache) {
                     group = null;
                 }
             }
+            // Optionally detect pipeline position
+            let pipeline = null;
+            if (args.includePipeline) {
+                try {
+                    // Need resolveFullConfig for project field lookups
+                    const { owner: cfgOwner, repo: cfgRepo } = resolveConfig(client, args);
+                    const { projectNumber: pn, projectOwner: po } = resolveFullConfig(client, args);
+                    await ensureFieldCache(client, fieldCache, po, pn);
+                    // Force group if not already detected
+                    if (!group) {
+                        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,
+                        };
+                    }
+                    // Build IssueState[] from group members
+                    const issueStates = await Promise.all((group.members || []).map(async (member) => {
+                        if (member.number === args.number) {
+                            // Use already-fetched values for the seed issue
+                            return {
+                                number: member.number,
+                                title: member.title,
+                                workflowState: workflowState || "unknown",
+                                estimate: estimate || null,
+                                subIssueCount: 0,
+                            };
+                        }
+                        // Fetch field values for non-seed members
+                        const state = await getIssueFieldValues(client, fieldCache, cfgOwner, cfgRepo, member.number);
+                        return {
+                            number: member.number,
+                            title: member.title,
+                            workflowState: state.workflowState || "unknown",
+                            estimate: state.estimate || null,
+                            subIssueCount: 0,
+                        };
+                    }));
+                    // Fetch sub-issue counts for M/L/XL estimates
+                    const oversized = issueStates.filter((s) => s.estimate && OVERSIZED_ESTIMATES.has(s.estimate));
+                    if (oversized.length > 0) {
+                        await Promise.all(oversized.map(async (s) => {
+                            try {
+                                const subResult = await client.query(`query($owner: String!, $repo: String!, $issueNum: Int!) {
+                        repository(owner: $owner, name: $repo) {
+                          issue(number: $issueNum) { subIssuesSummary { total } }
+                        }
+                      }`, { owner: cfgOwner, repo: cfgRepo, issueNum: s.number });
+                                if (subResult.repository?.issue?.subIssuesSummary) {
+                                    s.subIssueCount = subResult.repository.issue.subIssuesSummary.total;
+                                }
+                            }
+                            catch {
+                                // Best-effort, leave at 0
+                            }
+                        }));
+                    }
+                    // Run pipeline detection
+                    const pipelineResult = detectPipelinePosition(issueStates, group.isGroup, group.primary?.number ?? null);
+                    pipeline = {
+                        phase: pipelineResult.phase,
+                        reason: pipelineResult.reason,
+                        remainingPhases: pipelineResult.remainingPhases,
+                        convergence: pipelineResult.convergence,
+                        memberStates: pipelineResult.issues,
+                        suggestedRoster: pipelineResult.suggestedRoster,
+                    };
+                }
+                catch {
+                    pipeline = null; // Best-effort, same as includeGroup
+                }
+            }
             return toolSuccess({
                 number: issue.number,
                 id: issue.id,
@@ -504,6 +593,7 @@ export function registerIssueTools(server, client, fieldCache) {
                     createdAt: c.createdAt,
                 })),
                 group,
+                ...(pipeline !== null ? { pipeline } : {}),
             });
         }
         catch (error) {
@@ -876,198 +966,6 @@ 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). 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.coerce.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)"),
-    }, async (args) => {
-        try {
-            const { owner, repo } = resolveConfig(client, args);
-            const issueId = await resolveIssueNodeId(client, owner, repo, args.number);
-            // Resolve label IDs if provided
-            let labelIds;
-            if (args.labels) {
-                const labelResult = await client.query(`query($owner: String!, $repo: String!) {
-              repository(owner: $owner, name: $repo) {
-                labels(first: 100) {
-                  nodes { id name }
-                }
-              }
-            }`, { owner, repo }, { cache: true, cacheTtlMs: 5 * 60 * 1000 });
-                const allLabels = labelResult.repository.labels.nodes;
-                labelIds = args.labels
-                    .map((name) => allLabels.find((l) => l.name === name)?.id)
-                    .filter((id) => id !== undefined);
-            }
-            const result = await client.mutate(`mutation($issueId: ID!, $title: String, $body: String, $labelIds: [ID!], $assigneeIds: [ID!]) {
-            updateIssue(input: {
-              id: $issueId,
-              title: $title,
-              body: $body,
-              labelIds: $labelIds,
-              assigneeIds: $assigneeIds
-            }) {
-              issue {
-                number
-                title
-                url
-              }
-            }
-          }`, {
-                issueId,
-                title: args.title || null,
-                body: args.body || null,
-                labelIds: labelIds || null,
-                assigneeIds: null, // Would need username -> ID resolution
-            });
-            return toolSuccess({
-                number: result.updateIssue.issue.number,
-                title: result.updateIssue.issue.title,
-                url: result.updateIssue.issue.url,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to update issue: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
-    // ralph_hero__update_workflow_state
-    // -------------------------------------------------------------------------
-    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"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().describe("Issue number"),
-        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'). " +
-            "Required for validation and semantic intent resolution."),
-    }, async (args) => {
-        try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            // Resolve semantic intent or validate direct state
-            const { resolvedState, wasIntent, originalState } = resolveState(args.state, args.command);
-            // Ensure field cache is populated
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            // Get current state for the response
-            const previousState = await getCurrentFieldValue(client, fieldCache, owner, repo, args.number, "Workflow State", projectNumber);
-            // Resolve project item ID
-            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
-            // Update the field with the resolved state
-            await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", resolvedState, projectNumber);
-            // Sync default Status field (best-effort, one-way)
-            await syncStatusField(client, fieldCache, projectItemId, resolvedState, projectNumber);
-            const result = {
-                number: args.number,
-                previousState: previousState || "(unknown)",
-                newState: resolvedState,
-                command: args.command,
-            };
-            if (wasIntent) {
-                result.resolvedFrom = originalState;
-            }
-            return toolSuccess(result);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to update workflow state: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
-    // ralph_hero__update_estimate
-    // -------------------------------------------------------------------------
-    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"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().describe("Issue number"),
-        estimate: z.string().describe("Estimate value (XS, S, M, L, XL)"),
-    }, async (args) => {
-        try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
-            await updateProjectItemField(client, fieldCache, projectItemId, "Estimate", args.estimate, projectNumber);
-            return toolSuccess({
-                number: args.number,
-                estimate: args.estimate,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to update estimate: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
-    // ralph_hero__update_priority
-    // -------------------------------------------------------------------------
-    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"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().describe("Issue number"),
-        priority: z.string().describe("Priority value (P0, P1, P2, P3)"),
-    }, async (args) => {
-        try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
-            await updateProjectItemField(client, fieldCache, projectItemId, "Priority", args.priority, projectNumber);
-            return toolSuccess({
-                number: args.number,
-                priority: args.priority,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to update priority: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
     // ralph_hero__create_comment
     // -------------------------------------------------------------------------
     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.", {
@@ -1106,170 +1004,6 @@ export function registerIssueTools(server, client, fieldCache) {
         }
     });
     // -------------------------------------------------------------------------
-    // ralph_hero__detect_pipeline_position
-    // -------------------------------------------------------------------------
-    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"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().describe("Issue number (seed for group detection)"),
-    }, async (args) => {
-        try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            // Ensure field cache is populated
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            // Detect group from seed issue
-            const group = await detectGroup(client, owner, repo, args.number);
-            // Fetch workflow state and estimate for each group member
-            const issueStates = await Promise.all(group.groupTickets.map(async (ticket) => {
-                const state = await getIssueFieldValues(client, fieldCache, owner, repo, ticket.number);
-                return {
-                    number: ticket.number,
-                    title: ticket.title,
-                    workflowState: state.workflowState || "unknown",
-                    estimate: state.estimate || null,
-                    subIssueCount: 0,
-                };
-            }));
-            // Fetch sub-issue counts for oversized issues (targeted query, not all issues)
-            const oversizedNumbers = issueStates
-                .filter((i) => i.estimate !== null && OVERSIZED_ESTIMATES.has(i.estimate))
-                .map((i) => i.number);
-            if (oversizedNumbers.length > 0) {
-                await Promise.all(oversizedNumbers.map(async (num) => {
-                    const subResult = await client.query(`query($owner: String!, $repo: String!, $issueNum: Int!) {
-                  repository(owner: $owner, name: $repo) {
-                    issue(number: $issueNum) {
-                      subIssuesSummary { total }
-                    }
-                  }
-                }`, { owner, repo, issueNum: num });
-                    const issueState = issueStates.find((i) => i.number === num);
-                    if (issueState && subResult.repository?.issue?.subIssuesSummary) {
-                        issueState.subIssueCount = subResult.repository.issue.subIssuesSummary.total;
-                    }
-                }));
-            }
-            // Detect pipeline position
-            const position = detectPipelinePosition(issueStates, group.isGroup, group.groupPrimary.number);
-            return toolSuccess(position);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            // Check if it's a "not found" error
-            if (message.includes("not found")) {
-                return toolError(`Issue #${args.number} not found in project. ` +
-                    `Recovery: verify the issue number is correct and the issue has been added to the project ` +
-                    `via ralph_hero__create_issue or ralph_hero__get_issue.`);
-            }
-            return toolError(`Failed to detect pipeline position: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
-    // 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: 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"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.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')"),
-    }, async (args) => {
-        try {
-            // Validate target state
-            if (!isValidState(args.targetState)) {
-                return toolError(`Unknown target state '${args.targetState}'. ` +
-                    `Valid states: ${VALID_STATES.join(", ")}. ` +
-                    `Recovery: retry with a valid state name.`);
-            }
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            // Ensure field cache is populated
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            // Detect group from seed issue
-            const group = await detectGroup(client, owner, repo, args.number);
-            // Single issue trivially converges
-            if (!group.isGroup) {
-                const state = await getIssueFieldValues(client, fieldCache, owner, repo, args.number);
-                const atTarget = state.workflowState === args.targetState;
-                return toolSuccess({
-                    converged: atTarget,
-                    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),
-                            },
-                        ],
-                    recommendation: atTarget ? "proceed" : "wait",
-                });
-            }
-            // Check each group member
-            const blocking = [];
-            let readyCount = 0;
-            for (const ticket of group.groupTickets) {
-                const state = await getIssueFieldValues(client, fieldCache, owner, repo, ticket.number);
-                const currentState = state.workflowState || "unknown";
-                if (currentState === args.targetState) {
-                    readyCount++;
-                }
-                else {
-                    blocking.push({
-                        number: ticket.number,
-                        title: ticket.title,
-                        currentState,
-                        distanceToTarget: computeDistance(currentState, args.targetState),
-                    });
-                }
-            }
-            const converged = blocking.length === 0;
-            const hasHumanNeeded = blocking.some((b) => b.currentState === "Human Needed");
-            let recommendation;
-            if (converged) {
-                recommendation = "proceed";
-            }
-            else if (hasHumanNeeded) {
-                recommendation = "escalate";
-            }
-            else {
-                recommendation = "wait";
-            }
-            return toolSuccess({
-                converged,
-                targetState: args.targetState,
-                total: group.totalTickets,
-                ready: readyCount,
-                blocking,
-                recommendation,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to check convergence: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
     // ralph_hero__pick_actionable_issue
     // -------------------------------------------------------------------------
     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.", {
@@ -1523,15 +1257,4 @@ async function getIssueFieldValues(client, fieldCache, owner, repo, issueNumber)
     }
     return { workflowState, estimate, priority };
 }
-// ---------------------------------------------------------------------------
-// Helper: Compute "distance" between two states in the pipeline
-// ---------------------------------------------------------------------------
-import { stateIndex } from "../lib/workflow-states.js";
-function computeDistance(currentState, targetState) {
-    const currentIdx = stateIndex(currentState);
-    const targetIdx = stateIndex(targetState);
-    if (currentIdx === -1 || targetIdx === -1)
-        return -1;
-    return targetIdx - currentIdx;
-}
 //# sourceMappingURL=issue-tools.js.map

package/dist/tools/project-management-tools.js

@@ -20,67 +20,6 @@ export const PROTECTED_FIELDS = ["Workflow State", "Priority", "Estimate", "Stat
 // Register project management tools
 // ---------------------------------------------------------------------------
 export function registerProjectManagementTools(server, client, fieldCache) {
-    // -------------------------------------------------------------------------
-    // ralph_hero__archive_item
-    // -------------------------------------------------------------------------
-    server.tool("ralph_hero__archive_item", "Archive or unarchive a project item. Archived items are hidden from default views but not deleted. Accepts either number (for issues) or projectItemId (for draft items). Returns: number, archived, projectItemId.", {
-        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
-        repo: z.string().optional().describe("Repository name. Defaults to env var"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().optional().describe("Issue number (provide this or projectItemId)"),
-        projectItemId: z.string().optional()
-            .describe("Project item node ID (PVTI_...) — use instead of number for draft items"),
-        unarchive: z.boolean().optional().default(false)
-            .describe("If true, unarchive instead of archive (default: false)"),
-    }, async (args) => {
-        try {
-            if (!args.number && !args.projectItemId) {
-                return toolError("Either number or projectItemId must be provided");
-            }
-            if (args.number && args.projectItemId) {
-                return toolError("Provide either number or projectItemId, not both");
-            }
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            const projectId = fieldCache.getProjectId(projectNumber);
-            if (!projectId) {
-                return toolError("Could not resolve project ID");
-            }
-            const itemId = args.projectItemId
-                ? args.projectItemId
-                : await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
-            if (args.unarchive) {
-                await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
-              unarchiveProjectV2Item(input: {
-                projectId: $projectId,
-                itemId: $itemId
-              }) {
-                item { id }
-              }
-            }`, { projectId, itemId });
-            }
-            else {
-                await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
-              archiveProjectV2Item(input: {
-                projectId: $projectId,
-                itemId: $itemId
-              }) {
-                item { id }
-              }
-            }`, { projectId, itemId });
-            }
-            return toolSuccess({
-                number: args.number ?? null,
-                archived: !args.unarchive,
-                projectItemId: itemId,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to ${args.unarchive ? "unarchive" : "archive"} item: ${message}`);
-        }
-    });
     // -------------------------------------------------------------------------
     // ralph_hero__remove_from_project
     // -------------------------------------------------------------------------
@@ -242,51 +181,6 @@ export function registerProjectManagementTools(server, client, fieldCache) {
         }
     });
     // -------------------------------------------------------------------------
-    // ralph_hero__clear_field
-    // -------------------------------------------------------------------------
-    server.tool("ralph_hero__clear_field", "Clear a field value on a project item. Works for any single-select field (Workflow State, Estimate, Priority, Status, etc.). Returns: number, field, cleared.", {
-        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
-        repo: z.string().optional().describe("Repository name. Defaults to env var"),
-        projectNumber: z.coerce.number().optional()
-            .describe("Project number override (defaults to configured project)"),
-        number: z.coerce.number().describe("Issue number"),
-        field: z.string().describe("Field name to clear (e.g., 'Estimate', 'Priority', 'Workflow State')"),
-    }, async (args) => {
-        try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
-            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            const projectId = fieldCache.getProjectId(projectNumber);
-            if (!projectId) {
-                return toolError("Could not resolve project ID");
-            }
-            const fieldId = fieldCache.getFieldId(args.field, projectNumber);
-            if (!fieldId) {
-                const validFields = fieldCache.getFieldNames(projectNumber);
-                return toolError(`Field "${args.field}" not found in project. ` +
-                    `Valid fields: ${validFields.join(", ")}`);
-            }
-            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
-            await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
-            clearProjectV2ItemFieldValue(input: {
-              projectId: $projectId,
-              itemId: $itemId,
-              fieldId: $fieldId
-            }) {
-              projectV2Item { id }
-            }
-          }`, { projectId, itemId: projectItemId, fieldId });
-            return toolSuccess({
-                number: args.number,
-                field: args.field,
-                cleared: true,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to clear field: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
     // ralph_hero__create_draft_issue
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__create_draft_issue", "Create a draft issue in the project (no repo required). Optionally set workflow state, priority, and estimate after creation. Returns: projectItemId, title, fieldsSet.", {
@@ -1021,33 +915,92 @@ export function registerProjectManagementTools(server, client, fieldCache) {
         }
     });
     // -------------------------------------------------------------------------
-    // ralph_hero__bulk_archive
+    // ralph_hero__archive_items
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__bulk_archive", "Archive multiple project items matching workflow state filter. Uses aliased GraphQL mutations for efficiency (chunked at 50). Archived items are hidden from views but not deleted. Returns: archivedCount, items, errors.", {
+    server.tool("ralph_hero__archive_items", "Archive or unarchive project items. Single-item mode: provide number or projectItemId (supports unarchive). Bulk mode: provide workflowStates filter to archive multiple items matching those states. Uses aliased GraphQL mutations for efficiency (chunked at 50). Archived items are hidden from views but not deleted.", {
         owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
         repo: z.string().optional().describe("Repository name. Defaults to env var"),
         projectNumber: z.coerce.number().optional()
             .describe("Project number override (defaults to configured project)"),
+        number: z.coerce.number().optional()
+            .describe("Archive a single issue by number. Mutually exclusive with workflowStates filter."),
+        projectItemId: z.string().optional()
+            .describe("Archive by project item ID (for draft issues). Mutually exclusive with number and workflowStates."),
+        unarchive: z.boolean().optional().default(false)
+            .describe("Unarchive instead of archive. Only works with number or projectItemId (single-item mode)."),
         workflowStates: z
             .array(z.string())
-            .min(1)
-            .describe('Workflow states to archive (e.g., ["Done", "Canceled"])'),
+            .optional()
+            .describe('Workflow states to archive (e.g., ["Done", "Canceled"]). Required unless number or projectItemId is provided.'),
         maxItems: z
             .number()
             .optional()
             .default(50)
-            .describe("Max items to archive per invocation (default 50, cap 200)"),
+            .describe("Max items to archive per invocation (default 50, cap 200). Bulk mode only."),
         dryRun: z
             .boolean()
             .optional()
             .default(false)
-            .describe("If true, return matching items without archiving them (default: false)"),
+            .describe("If true, return matching items without archiving them (default: false). Bulk mode only."),
         updatedBefore: z
             .string()
             .optional()
-            .describe("ISO 8601 date (UTC). Only archive items with updatedAt before this date. Composable with workflowStates (AND logic)."),
+            .describe("ISO 8601 date (UTC). Only archive items with updatedAt before this date. Composable with workflowStates (AND logic). Bulk mode only."),
     }, async (args) => {
         try {
+            // Determine mode
+            const isSingleItem = args.number !== undefined || args.projectItemId !== undefined;
+            const isBulk = args.workflowStates && args.workflowStates.length > 0;
+            if (!isSingleItem && !isBulk) {
+                return toolError("Provide either 'number'/'projectItemId' (single item) or 'workflowStates' (bulk filter).");
+            }
+            if (isSingleItem && isBulk) {
+                return toolError("Cannot combine number/projectItemId with workflowStates. Use one mode.");
+            }
+            if (args.unarchive && isBulk) {
+                return toolError("Unarchive is only supported for single items (number or projectItemId).");
+            }
+            // Single-item mode
+            if (isSingleItem) {
+                if (args.number && args.projectItemId) {
+                    return toolError("Provide either number or projectItemId, not both");
+                }
+                const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+                await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+                const projectId = fieldCache.getProjectId(projectNumber);
+                if (!projectId) {
+                    return toolError("Could not resolve project ID");
+                }
+                const itemId = args.projectItemId
+                    ? args.projectItemId
+                    : await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);
+                if (args.unarchive) {
+                    await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
+                unarchiveProjectV2Item(input: {
+                  projectId: $projectId,
+                  itemId: $itemId
+                }) {
+                  item { id }
+                }
+              }`, { projectId, itemId });
+                }
+                else {
+                    await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
+                archiveProjectV2Item(input: {
+                  projectId: $projectId,
+                  itemId: $itemId
+                }) {
+                  item { id }
+                }
+              }`, { projectId, itemId });
+                }
+                return toolSuccess({
+                    number: args.number ?? null,
+                    archived: !args.unarchive,
+                    projectItemId: itemId,
+                });
+            }
+            // Bulk mode (workflowStates filter)
             const { projectNumber, projectOwner } = resolveFullConfig(client, args);
             await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
             const projectId = fieldCache.getProjectId(projectNumber);

package/dist/tools/project-tools.js

@@ -6,8 +6,6 @@
  */
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
-import { parseDateMath } from "../lib/date-math.js";
-import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
 import { resolveProjectOwner } from "../types.js";
 import { queryProjectRepositories } from "../lib/helpers.js";
@@ -486,257 +484,6 @@ 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"),
-        profile: z
-            .string()
-            .optional()
-            .describe("Named filter profile (e.g., 'analyst-triage', 'builder-active'). " +
-            "Profile filters are defaults; explicit params override them."),
-        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)"),
-        has: z
-            .array(z.enum(["workflowState", "estimate", "priority", "labels", "assignees"]))
-            .optional()
-            .describe("Include only items where these fields are non-empty. " +
-            "Valid fields: workflowState, estimate, priority, labels, assignees"),
-        no: z
-            .array(z.enum(["workflowState", "estimate", "priority", "labels", "assignees"]))
-            .optional()
-            .describe("Include only items where these fields are empty/absent. " +
-            "Valid fields: workflowState, estimate, priority, labels, assignees"),
-        excludeWorkflowStates: z
-            .array(z.string())
-            .optional()
-            .describe("Exclude items matching any of these Workflow State names " +
-            '(e.g., ["Done", "Canceled"])'),
-        excludeEstimates: z
-            .array(z.string())
-            .optional()
-            .describe("Exclude items matching any of these Estimate values " +
-            '(e.g., ["M", "L", "XL"])'),
-        excludePriorities: z
-            .array(z.string())
-            .optional()
-            .describe("Exclude items matching any of these Priority values " +
-            '(e.g., ["P3"])'),
-        itemType: z
-            .enum(["ISSUE", "PULL_REQUEST", "DRAFT_ISSUE"])
-            .optional()
-            .describe("Filter by item type (ISSUE, PULL_REQUEST, DRAFT_ISSUE). Omit to include all types."),
-        updatedSince: z
-            .string()
-            .optional()
-            .describe("Include items updated on or after this date. Supports date-math (@today-7d, @now-24h) or ISO dates."),
-        updatedBefore: z
-            .string()
-            .optional()
-            .describe("Include items updated before this date. Supports date-math (@today-7d, @now-24h) or ISO dates."),
-        limit: z
-            .number()
-            .optional()
-            .default(50)
-            .describe("Max items to return (default 50)"),
-    }, async (args) => {
-        try {
-            // Expand profile into filter defaults (explicit args override)
-            if (args.profile) {
-                const profileFilters = expandProfile(args.profile);
-                for (const [key, value] of Object.entries(profileFilters)) {
-                    if (args[key] === undefined) {
-                        args[key] = value;
-                    }
-                }
-            }
-            const owner = args.owner || resolveProjectOwner(client.config);
-            const projectNumber = args.number || client.config.projectNumber;
-            if (!owner) {
-                return toolError("owner is required");
-            }
-            if (!projectNumber) {
-                return toolError("number is required");
-            }
-            // Ensure field cache is populated
-            await ensureFieldCache(client, fieldCache, owner, projectNumber);
-            const projectId = fieldCache.getProjectId(projectNumber);
-            if (!projectId) {
-                return toolError("Could not resolve project ID");
-            }
-            // When filters are active, fetch more items to ensure adequate results after filtering
-            const hasFilters = args.updatedSince || args.updatedBefore || args.itemType ||
-                (args.has && args.has.length > 0) ||
-                (args.no && args.no.length > 0) ||
-                (args.excludeWorkflowStates && args.excludeWorkflowStates.length > 0) ||
-                (args.excludeEstimates && args.excludeEstimates.length > 0) ||
-                (args.excludePriorities && args.excludePriorities.length > 0);
-            const maxItems = hasFilters ? 500 : (args.limit || 50);
-            // Fetch all project items with field values
-            const itemsResult = await paginateConnection((q, v) => client.projectQuery(q, v), `query($projectId: ID!, $cursor: String, $first: Int!) {
-            node(id: $projectId) {
-              ... on ProjectV2 {
-                items(first: $first, after: $cursor) {
-                  totalCount
-                  pageInfo { hasNextPage endCursor }
-                  nodes {
-                    id
-                    type
-                    content {
-                      ... on Issue {
-                        number
-                        title
-                        state
-                        url
-                        updatedAt
-                        labels(first: 10) { nodes { name } }
-                        assignees(first: 5) { nodes { login } }
-                        repository { nameWithOwner name owner { login } }
-                      }
-                      ... on PullRequest {
-                        number
-                        title
-                        state
-                        url
-                        repository { nameWithOwner name owner { login } }
-                      }
-                      ... on DraftIssue {
-                        id
-                        title
-                        body
-                      }
-                    }
-                    fieldValues(first: 20) {
-                      nodes {
-                        ... on ProjectV2ItemFieldSingleSelectValue {
-                          __typename
-                          name
-                          optionId
-                          field { ... on ProjectV2FieldCommon { name } }
-                        }
-                        ... on ProjectV2ItemFieldTextValue {
-                          __typename
-                          text
-                          field { ... on ProjectV2FieldCommon { name } }
-                        }
-                        ... on ProjectV2ItemFieldNumberValue {
-                          __typename
-                          number
-                          field { ... on ProjectV2FieldCommon { name } }
-                        }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          }`, { projectId, first: Math.min(maxItems, 100) }, "node.items", { maxItems });
-            // Filter items by field values
-            let items = itemsResult.nodes;
-            // Filter by item type (broadest filter first to reduce working set)
-            if (args.itemType) {
-                items = items.filter((item) => item.type === args.itemType);
-            }
-            if (args.workflowState) {
-                items = items.filter((item) => getFieldValue(item, "Workflow State") === args.workflowState);
-            }
-            if (args.estimate) {
-                items = items.filter((item) => getFieldValue(item, "Estimate") === args.estimate);
-            }
-            if (args.priority) {
-                items = items.filter((item) => getFieldValue(item, "Priority") === args.priority);
-            }
-            // Filter by field presence (has)
-            if (args.has && args.has.length > 0) {
-                items = items.filter((item) => args.has.every((field) => hasField(item, field)));
-            }
-            // Filter by field absence (no)
-            if (args.no && args.no.length > 0) {
-                items = items.filter((item) => args.no.every((field) => !hasField(item, field)));
-            }
-            // Filter by excluded workflow states
-            if (args.excludeWorkflowStates && args.excludeWorkflowStates.length > 0) {
-                items = items.filter((item) => !args.excludeWorkflowStates.includes(getFieldValue(item, "Workflow State") ?? ""));
-            }
-            // Filter by excluded estimates
-            if (args.excludeEstimates && args.excludeEstimates.length > 0) {
-                items = items.filter((item) => !args.excludeEstimates.includes(getFieldValue(item, "Estimate") ?? ""));
-            }
-            // Filter by excluded priorities
-            if (args.excludePriorities && args.excludePriorities.length > 0) {
-                items = items.filter((item) => !args.excludePriorities.includes(getFieldValue(item, "Priority") ?? ""));
-            }
-            // Filter by updatedSince
-            if (args.updatedSince) {
-                const since = parseDateMath(args.updatedSince).getTime();
-                items = items.filter((item) => {
-                    const content = item.content;
-                    const updatedAt = content?.updatedAt;
-                    return updatedAt ? new Date(updatedAt).getTime() >= since : false;
-                });
-            }
-            // Filter by updatedBefore
-            if (args.updatedBefore) {
-                const before = parseDateMath(args.updatedBefore).getTime();
-                items = items.filter((item) => {
-                    const content = item.content;
-                    const updatedAt = content?.updatedAt;
-                    return updatedAt ? new Date(updatedAt).getTime() < before : false;
-                });
-            }
-            // Apply limit after filtering
-            items = items.slice(0, args.limit || 50);
-            // Format response
-            const formattedItems = items.map((item) => {
-                const content = item.content;
-                return {
-                    itemId: item.id,
-                    type: item.type,
-                    draftIssueId: item.type === "DRAFT_ISSUE" ? content?.id ?? null : null,
-                    number: content?.number,
-                    title: content?.title,
-                    state: content?.state,
-                    url: content?.url,
-                    updatedAt: content?.updatedAt ?? null,
-                    owner: content?.repository?.owner?.login ?? null,
-                    repo: content?.repository?.name ?? null,
-                    nameWithOwner: content?.repository?.nameWithOwner ?? null,
-                    workflowState: getFieldValue(item, "Workflow State"),
-                    estimate: getFieldValue(item, "Estimate"),
-                    priority: getFieldValue(item, "Priority"),
-                    labels: content?.labels?.nodes?.map((l) => l.name),
-                    assignees: content?.assignees?.nodes?.map((a) => a.login),
-                };
-            });
-            return toolSuccess({
-                totalCount: itemsResult.totalCount,
-                filteredCount: formattedItems.length,
-                items: formattedItems,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to list project items: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
     // ralph_hero__list_project_repos
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_project_repos", "List all repositories linked to a GitHub Project V2. Returns owner, name, and nameWithOwner for each linked repo.", {
@@ -774,31 +521,6 @@ export function registerProjectTools(server, client, fieldCache) {
         }
     });
 }
-function getFieldValue(item, fieldName) {
-    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName &&
-        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
-    return fieldValue?.name;
-}
-function hasField(item, field) {
-    switch (field) {
-        case "workflowState":
-            return getFieldValue(item, "Workflow State") !== undefined;
-        case "estimate":
-            return getFieldValue(item, "Estimate") !== undefined;
-        case "priority":
-            return getFieldValue(item, "Priority") !== undefined;
-        case "labels": {
-            const content = item.content;
-            const labels = content?.labels?.nodes || [];
-            return labels.length > 0;
-        }
-        case "assignees": {
-            const content = item.content;
-            const assignees = content?.assignees?.nodes || [];
-            return assignees.length > 0;
-        }
-    }
-}
 async function fetchProject(client, owner, number) {
     // Try user query first
     try {

package/dist/tools/relationship-tools.js

@@ -8,8 +8,6 @@
  * GitHub node IDs internally via cached lookups.
  */
 import { z } from "zod";
-import { detectGroup } from "../lib/group-detection.js";
-import { detectWorkStreams, } from "../lib/work-stream-detection.js";
 import { isValidState, isEarlierState, VALID_STATES, PARENT_GATE_STATES, isParentGateState, stateIndex, } from "../lib/workflow-states.js";
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, syncStatusField, } from "../lib/helpers.js";
@@ -349,70 +347,6 @@ 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"),
-    }, async (args) => {
-        try {
-            const { owner, repo } = resolveConfig(client, args);
-            const result = await detectGroup(client, owner, repo, args.number);
-            return toolSuccess(result);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to detect group: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
-    // ralph_hero__detect_work_streams
-    // -------------------------------------------------------------------------
-    server.tool("ralph_hero__detect_work_streams", "Cluster GitHub issues into independent work streams based on shared file ownership and blockedBy relationships. Uses union-find to group issues that share Will Modify files or are co-dependent. Returns WorkStreamResult with streams, sharedFiles, and a human-readable rationale.", {
-        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"),
-        issues: z
-            .array(z.object({
-            number: z.number().describe("Issue number"),
-            files: z
-                .array(z.string())
-                .describe("Will Modify file paths from research doc"),
-            blockedBy: z
-                .array(z.number())
-                .describe("GitHub blockedBy issue numbers"),
-        }))
-            .describe("List of issues with their file ownership and dependencies"),
-    }, async (args) => {
-        try {
-            const issueOwnership = args.issues.map((i) => ({
-                number: i.number,
-                files: i.files,
-                blockedBy: i.blockedBy,
-            }));
-            const result = detectWorkStreams(issueOwnership);
-            return toolSuccess(result);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return toolError(`Failed to detect work streams: ${message}`);
-        }
-    });
-    // -------------------------------------------------------------------------
     // ralph_hero__advance_children
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__advance_children", "Advance issues to a target workflow state. Provide either 'number' (parent issue, advances sub-issues) or 'issues' (explicit list of issue numbers). Only advances issues in earlier workflow states. Returns what changed, what was skipped, and any errors.", {

package/package.json

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