ralph-hero-mcp-server 2.5.2 → 2.5.3

package/dist/index.js

@@ -21,6 +21,7 @@ import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
+import { registerDecomposeTools } from "./tools/decompose-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -244,6 +245,17 @@ async function main() {
         console.error("[ralph-hero] Debug logging enabled (RALPH_DEBUG=true)");
     }
     const client = initGitHubClient(debugLogger);
+    // Load repo registry (.ralph-repos.yml) before repo inference (non-fatal)
+    try {
+        const { loadRepoRegistry } = await import("./lib/registry-loader.js");
+        const registry = await loadRepoRegistry(client);
+        if (registry) {
+            client.config.repoRegistry = registry;
+        }
+    }
+    catch (e) {
+        console.error(`[ralph-hero] Repo registry load skipped: ${e instanceof Error ? e.message : String(e)}`);
+    }
     // Attempt lazy repo inference from project (non-fatal)
     try {
         await resolveRepoFromProject(client);
@@ -287,6 +299,8 @@ async function main() {
     registerProjectManagementTools(server, client, fieldCache);
     // Hygiene reporting tools
     registerHygieneTools(server, client, fieldCache);
+    // Decompose feature tool (cross-repo decomposition via .ralph-repos.yml)
+    registerDecomposeTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/dashboard.js

@@ -618,6 +618,23 @@ export function formatMarkdown(data, issuesPerPhase = 10) {
     }
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// groupDashboardItemsByRepo
+// ---------------------------------------------------------------------------
+/**
+ * Group dashboard items by repository (nameWithOwner).
+ * Items without a repository are grouped under "(unknown)".
+ */
+export function groupDashboardItemsByRepo(items) {
+    const groups = {};
+    for (const item of items) {
+        const key = item.repository || "(unknown)";
+        if (!groups[key])
+            groups[key] = [];
+        groups[key].push(item);
+    }
+    return groups;
+}
 /**
  * Render dashboard data as an ASCII bar chart.
  */

package/dist/lib/helpers.js

@@ -249,6 +249,18 @@ export async function resolveRepoFromProject(client) {
         }
         return inferred.repo;
     }
+    // When a registry is loaded, use its first repo entry as the default
+    const registry = client.config.repoRegistry;
+    if (registry) {
+        const firstRepoName = Object.keys(registry.repos)[0];
+        const firstRepoEntry = registry.repos[firstRepoName];
+        client.config.repo = firstRepoName;
+        if (!client.config.owner && firstRepoEntry.owner) {
+            client.config.owner = firstRepoEntry.owner;
+        }
+        console.error(`[ralph-hero] Multiple repos linked. Using "${firstRepoName}" as default (from .ralph-repos.yml).`);
+        return firstRepoName;
+    }
     const repoList = result.repos.map(r => r.nameWithOwner).join(", ");
     console.error(`[ralph-hero] Multiple repos linked to project: ${repoList}. ` +
         `Set RALPH_GH_REPO to select the default repo. ` +

package/dist/lib/registry-loader.js

@@ -0,0 +1,100 @@
+/**
+ * Registry loader — fetches .ralph-repos.yml from project-linked GitHub repos.
+ *
+ * Called once at MCP server startup (before resolveRepoFromProject).
+ * The registry is optional: if not found in any linked repo, returns null.
+ */
+import { parseRepoRegistry } from "./repo-registry.js";
+import { queryProjectRepositories } from "./helpers.js";
+import { resolveProjectOwner } from "../types.js";
+const REGISTRY_FILENAME = ".ralph-repos.yml";
+// ---------------------------------------------------------------------------
+// Internal: fetch file content from a single repo via GraphQL
+// ---------------------------------------------------------------------------
+async function fetchFileFromRepo(client, owner, repo, expression) {
+    try {
+        const result = await client.query(`query($owner: String!, $repo: String!, $expr: String!) {
+        repository(owner: $owner, name: $repo) {
+          object(expression: $expr) {
+            ... on Blob { __typename text }
+          }
+        }
+      }`, { owner, repo, expr: expression });
+        const obj = result.repository?.object;
+        if (obj?.__typename === "Blob" && typeof obj.text === "string") {
+            return obj.text;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public: load registry from project-linked repos
+// ---------------------------------------------------------------------------
+/**
+ * Load .ralph-repos.yml from a GitHub repo linked to the configured project.
+ *
+ * Strategy:
+ * 1. If client.config.repo is set, try that repo first.
+ * 2. Otherwise, query linked repos and try each in order until one has the file.
+ * 3. If none found or any validation error, log a warning and return null.
+ *
+ * The registry is optional — consumers must handle null gracefully.
+ */
+export async function loadRepoRegistry(client) {
+    const expression = `HEAD:${REGISTRY_FILENAME}`;
+    // Try the explicitly configured repo first
+    if (client.config.repo && client.config.owner) {
+        const text = await fetchFileFromRepo(client, client.config.owner, client.config.repo, expression);
+        if (text !== null) {
+            return parseAndLog(text, client.config.owner, client.config.repo);
+        }
+    }
+    // Fall back to querying linked repos (multi-repo case or no explicit repo)
+    const projectOwner = resolveProjectOwner(client.config);
+    const projectNumber = client.config.projectNumber;
+    if (!projectOwner || !projectNumber) {
+        // Not enough config to query project repos — skip silently
+        return null;
+    }
+    const projectRepos = await queryProjectRepositories(client, projectOwner, projectNumber);
+    if (!projectRepos || projectRepos.repos.length === 0) {
+        return null;
+    }
+    for (const linked of projectRepos.repos) {
+        // Skip if we already tried this repo above
+        if (linked.repo === client.config.repo &&
+            linked.owner === client.config.owner) {
+            continue;
+        }
+        const text = await fetchFileFromRepo(client, linked.owner, linked.repo, expression);
+        if (text !== null) {
+            return parseAndLog(text, linked.owner, linked.repo);
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Internal: parse and log on success or validation failure
+// ---------------------------------------------------------------------------
+function parseAndLog(text, owner, repo) {
+    try {
+        const registry = parseRepoRegistry(text);
+        const repoCount = Object.keys(registry.repos).length;
+        const patternCount = registry.patterns
+            ? Object.keys(registry.patterns).length
+            : 0;
+        console.error(`[ralph-hero] Repo registry loaded from ${owner}/${repo}: ` +
+            `${repoCount} repo${repoCount !== 1 ? "s" : ""}, ` +
+            `${patternCount} pattern${patternCount !== 1 ? "s" : ""}`);
+        return registry;
+    }
+    catch (err) {
+        console.error(`[ralph-hero] Warning: ${REGISTRY_FILENAME} found in ${owner}/${repo} ` +
+            `but failed to parse: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=registry-loader.js.map

package/dist/lib/repo-registry.js

@@ -0,0 +1,256 @@
+/**
+ * Repo registry schema, types, parser, and lookup helpers.
+ *
+ * Provides structured configuration for multi-repo portfolio management.
+ * The registry YAML file maps short repo names to metadata (domain, tech
+ * stack, default labels/assignees/estimate) and defines cross-repo
+ * decomposition patterns for feature work.
+ *
+ * Consumers:
+ * - server startup: loads registry once from env-specified path
+ * - create_issue tool: merges repo defaults into issue creation args
+ * - decompose_feature tool: looks up patterns for cross-repo decomposition
+ * - pipeline_dashboard: groups issues by repo domain
+ */
+import { parse as yamlParse } from "yaml";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+/**
+ * Default values applied to issues created in a specific repo.
+ * All fields are optional — only specified ones are used.
+ *
+ * Example YAML:
+ *   defaults:
+ *     labels: ["backend", "infra"]
+ *     assignees: ["cdubiel08"]
+ *     estimate: "S"
+ */
+export const RepoDefaultsSchema = z.object({
+    labels: z
+        .array(z.string())
+        .optional()
+        .describe("Default labels to apply to issues in this repo"),
+    assignees: z
+        .array(z.string())
+        .optional()
+        .describe("Default assignees for issues in this repo"),
+    estimate: z
+        .string()
+        .optional()
+        .describe("Default estimate (e.g., 'XS', 'S', 'M', 'L') for this repo"),
+});
+/**
+ * A single repository entry in the registry.
+ *
+ * Example YAML:
+ *   mcp-server:
+ *     owner: cdubiel08
+ *     domain: platform
+ *     tech: [typescript, node]
+ *     defaults:
+ *       labels: [backend]
+ *     paths: [plugin/ralph-hero/mcp-server]
+ */
+export const RepoEntrySchema = z.object({
+    owner: z
+        .string()
+        .optional()
+        .describe("GitHub owner (user or org); falls back to RALPH_GH_OWNER if omitted"),
+    domain: z
+        .string()
+        .describe("Functional domain this repo belongs to (e.g., 'platform', 'frontend')"),
+    tech: z
+        .array(z.string())
+        .optional()
+        .describe("Technology stack tags for this repo (e.g., ['typescript', 'react'])"),
+    defaults: RepoDefaultsSchema
+        .optional()
+        .describe("Default values applied to issues created in this repo"),
+    paths: z
+        .array(z.string())
+        .optional()
+        .describe("Monorepo sub-paths owned by this repo (e.g., ['packages/core'])"),
+});
+/**
+ * One step in a cross-repo decomposition pattern.
+ *
+ * Example YAML:
+ *   - repo: mcp-server
+ *     role: Implement MCP tool endpoint
+ */
+export const DecompositionStepSchema = z.object({
+    repo: z
+        .string()
+        .describe("Registry key of the repo responsible for this step"),
+    role: z
+        .string()
+        .describe("Human-readable description of what this repo does in the decomposition"),
+});
+/**
+ * A named cross-repo decomposition pattern for feature work.
+ *
+ * Example YAML:
+ *   full-stack-feature:
+ *     description: "Frontend + backend + infra change"
+ *     decomposition:
+ *       - repo: frontend
+ *         role: Build UI
+ *       - repo: mcp-server
+ *         role: Add API endpoint
+ *     dependency-flow:
+ *       - mcp-server -> frontend
+ */
+export const PatternSchema = z.object({
+    description: z
+        .string()
+        .describe("Human-readable description of when to use this pattern"),
+    decomposition: z
+        .array(DecompositionStepSchema)
+        .min(1)
+        .describe("Ordered list of repo steps for this pattern (at least one required)"),
+    "dependency-flow": z
+        .array(z.string())
+        .optional()
+        .describe("Dependency edges between repos (e.g., 'api -> frontend')"),
+});
+/**
+ * Top-level repo registry configuration.
+ *
+ * Example YAML:
+ *   version: 1
+ *   repos:
+ *     mcp-server:
+ *       domain: platform
+ *       tech: [typescript]
+ *   patterns:
+ *     full-stack:
+ *       description: "Full stack feature"
+ *       decomposition:
+ *         - repo: mcp-server
+ *           role: Backend
+ */
+export const RepoRegistrySchema = z.object({
+    version: z
+        .literal(1)
+        .describe("Schema version for forward compatibility"),
+    repos: z
+        .record(z.string(), RepoEntrySchema)
+        .refine((r) => Object.keys(r).length >= 1, {
+        message: "At least one repo entry is required",
+    })
+        .describe("Map of short repo name to repo metadata"),
+    patterns: z
+        .record(z.string(), PatternSchema)
+        .optional()
+        .describe("Named cross-repo decomposition patterns"),
+});
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a YAML string into a validated RepoRegistry.
+ *
+ * Throws a descriptive error if:
+ * - the YAML is syntactically invalid
+ * - the parsed value does not match RepoRegistrySchema
+ *
+ * @param yamlContent - Raw YAML string (e.g., from fs.readFileSync)
+ * @returns Validated RepoRegistry object
+ */
+export function parseRepoRegistry(yamlContent) {
+    let parsed;
+    try {
+        parsed = yamlParse(yamlContent);
+    }
+    catch (err) {
+        throw new Error(`Repo registry YAML parse error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = RepoRegistrySchema.safeParse(parsed);
+    if (!result.success) {
+        const messages = result.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+            return `  ${path}: ${issue.message}`;
+        })
+            .join("\n");
+        throw new Error(`Repo registry schema validation failed:\n${messages}`);
+    }
+    return result.data;
+}
+// ---------------------------------------------------------------------------
+// Lookup Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Look up a repo entry by name (case-insensitive).
+ *
+ * @param registry - Parsed registry
+ * @param repoName - Repo key to look up (case-insensitive)
+ * @returns { name, entry } if found, undefined otherwise
+ */
+export function lookupRepo(registry, repoName) {
+    const lower = repoName.toLowerCase();
+    for (const [name, entry] of Object.entries(registry.repos)) {
+        if (name.toLowerCase() === lower) {
+            return { name, entry };
+        }
+    }
+    return undefined;
+}
+/**
+ * Look up a decomposition pattern by name (case-insensitive).
+ *
+ * @param registry - Parsed registry
+ * @param patternName - Pattern key to look up (case-insensitive)
+ * @returns { name, pattern } if found, undefined otherwise
+ */
+export function lookupPattern(registry, patternName) {
+    if (!registry.patterns)
+        return undefined;
+    const lower = patternName.toLowerCase();
+    for (const [name, pattern] of Object.entries(registry.patterns)) {
+        if (name.toLowerCase() === lower) {
+            return { name, pattern };
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Defaults Merging
+// ---------------------------------------------------------------------------
+/**
+ * Merge repo defaults with caller-supplied args.
+ *
+ * Merge rules:
+ * - **labels**: additive union, deduplicated (args labels + defaults labels)
+ * - **assignees**: args win; fall back to defaults if args omit it
+ * - **estimate**: args win; fall back to defaults if args omit it
+ *
+ * @param defaults - Repo-level defaults from registry (may be undefined)
+ * @param args - Caller-supplied values (take precedence for non-label fields)
+ * @returns Merged object with only the fields that have values
+ */
+export function mergeDefaults(defaults, args) {
+    const result = {};
+    // Labels: additive union, deduplicated
+    const allLabels = [
+        ...(args.labels ?? []),
+        ...(defaults?.labels ?? []),
+    ];
+    if (allLabels.length > 0) {
+        result.labels = [...new Set(allLabels)];
+    }
+    // Assignees: args win, fall back to defaults
+    const assignees = args.assignees ?? defaults?.assignees;
+    if (assignees !== undefined) {
+        result.assignees = assignees;
+    }
+    // Estimate: args win, fall back to defaults
+    const estimate = args.estimate ?? defaults?.estimate;
+    if (estimate !== undefined) {
+        result.estimate = estimate;
+    }
+    return result;
+}
+//# sourceMappingURL=repo-registry.js.map

package/dist/tools/dashboard-tools.js

@@ -7,7 +7,7 @@
  */
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
-import { buildDashboard, formatMarkdown, formatAscii, DEFAULT_HEALTH_CONFIG, } from "../lib/dashboard.js";
+import { buildDashboard, formatMarkdown, formatAscii, groupDashboardItemsByRepo, DEFAULT_HEALTH_CONFIG, } from "../lib/dashboard.js";
 import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers } from "../types.js";
 import { detectWorkStreams } from "../lib/work-stream-detection.js";
 import { detectStreamPipelinePositions } from "../lib/pipeline-detection.js";
@@ -225,6 +225,10 @@ export function registerDashboardTools(server, client, fieldCache) {
         }))
             .optional()
             .describe("Pre-computed stream assignments from detect_work_streams. When provided, dashboard includes a Streams section."),
+        groupBy: z
+            .enum(["repo"])
+            .optional()
+            .describe("Group dashboard output by dimension. 'repo' groups items by repository within the project."),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -287,6 +291,34 @@ export function registerDashboardTools(server, client, fieldCache) {
             for (const phase of dashboard.phases) {
                 phase.issues = phase.issues.slice(0, issuesPerPhase);
             }
+            // If groupBy=repo, build per-repo sub-dashboards
+            if (args.groupBy === "repo") {
+                const repoGroups = groupDashboardItemsByRepo(allItems);
+                if (args.format === "markdown") {
+                    let md = "# Pipeline Dashboard (by repo)\n\n";
+                    for (const [repoName, repoItems] of Object.entries(repoGroups)) {
+                        const sub = buildDashboard(repoItems, healthConfig);
+                        md += `## ${repoName} (${repoItems.length} items)\n\n`;
+                        md += formatMarkdown(sub) + "\n\n";
+                    }
+                    return toolSuccess({ markdown: md });
+                }
+                if (args.format === "ascii") {
+                    let ascii = "Pipeline Dashboard (by repo)\n\n";
+                    for (const [repoName, repoItems] of Object.entries(repoGroups)) {
+                        const sub = buildDashboard(repoItems, healthConfig);
+                        ascii += `=== ${repoName} (${repoItems.length} items) ===\n`;
+                        ascii += formatAscii(sub) + "\n\n";
+                    }
+                    return toolSuccess({ ascii });
+                }
+                // JSON format
+                const repoResults = {};
+                for (const [repoName, repoItems] of Object.entries(repoGroups)) {
+                    repoResults[repoName] = buildDashboard(repoItems, healthConfig);
+                }
+                return toolSuccess({ groupBy: "repo", repos: repoResults });
+            }
             // Compute metrics if requested
             let metrics;
             if (args.includeMetrics) {

package/dist/tools/decompose-tools.js

@@ -0,0 +1,321 @@
+/**
+ * MCP tools for cross-repo feature decomposition.
+ *
+ * Uses the .ralph-repos.yml registry to split a feature description into
+ * repo-specific issues following a named decomposition pattern.
+ *
+ * When dryRun=true (default), returns a proposed issue list for review.
+ * When dryRun=false, creates the actual issues on GitHub and adds each to
+ * the project board.
+ */
+import { z } from "zod";
+import { toolSuccess, toolError } from "../types.js";
+import { ensureFieldCache, resolveFullConfigOptionalRepo, } from "../lib/helpers.js";
+import { lookupRepo, lookupPattern, mergeDefaults, } from "../lib/repo-registry.js";
+// ---------------------------------------------------------------------------
+// Pure function: buildDecomposition
+// ---------------------------------------------------------------------------
+/**
+ * Build a decomposition proposal from a feature description and registry pattern.
+ *
+ * Pure function — no side effects, no API calls. Suitable for testing.
+ *
+ * @param input - { title, description, pattern }
+ * @param registry - Validated repo registry
+ * @param defaultOwner - Global owner fallback (from client.config.owner)
+ * @returns DecompositionResult with proposed issues and dependency chain
+ * @throws Error if pattern is not found (lists available patterns)
+ * @throws Error if a step references a repo not in the registry
+ */
+export function buildDecomposition(input, registry, defaultOwner) {
+    // Look up the pattern (case-insensitive)
+    const patternLookup = lookupPattern(registry, input.pattern);
+    if (!patternLookup) {
+        const available = Object.keys(registry.patterns ?? {});
+        const availableList = available.length > 0
+            ? `Available patterns: ${available.join(", ")}`
+            : "No patterns are defined in the registry.";
+        throw new Error(`Pattern "${input.pattern}" not found in registry. ${availableList}`);
+    }
+    const { name: matchedPattern, pattern } = patternLookup;
+    // Build a proposed issue for each step
+    const proposed_issues = pattern.decomposition.map((step) => {
+        const repoLookup = lookupRepo(registry, step.repo);
+        if (!repoLookup) {
+            const available = Object.keys(registry.repos);
+            throw new Error(`Pattern step references unknown repo "${step.repo}". ` +
+                `Available repos: ${available.join(", ")}`);
+        }
+        const { name: repoKey, entry } = repoLookup;
+        // Merge defaults: no caller overrides at decompose time
+        const merged = mergeDefaults(entry.defaults, {});
+        // Resolve owner: registry entry > global default
+        const owner = entry.owner ?? defaultOwner;
+        // Generate title
+        const title = `[${input.title}] ${step.role}`;
+        // Generate body
+        const domainLine = `Domain: ${entry.domain}`;
+        const techLine = entry.tech && entry.tech.length > 0
+            ? `Tech: ${entry.tech.join(", ")}`
+            : undefined;
+        const pathsLine = entry.paths && entry.paths.length > 0
+            ? `Paths: ${entry.paths.join(", ")}`
+            : undefined;
+        const repoDomainParts = [domainLine, techLine, pathsLine].filter((p) => p !== undefined);
+        const body = [
+            `## Context`,
+            ``,
+            input.description,
+            ``,
+            `## Scope`,
+            ``,
+            step.role,
+            ``,
+            `## Repo`,
+            ``,
+            repoDomainParts.join("\n"),
+        ].join("\n");
+        const proposed = { repoKey, owner, title, body };
+        if (merged.labels !== undefined)
+            proposed.labels = merged.labels;
+        if (merged.assignees !== undefined)
+            proposed.assignees = merged.assignees;
+        if (merged.estimate !== undefined)
+            proposed.estimate = merged.estimate;
+        return proposed;
+    });
+    // Extract dependency chain
+    const dependency_chain = pattern["dependency-flow"] ?? [];
+    return { proposed_issues, dependency_chain, matched_pattern: matchedPattern };
+}
+// ---------------------------------------------------------------------------
+// Register decompose tools
+// ---------------------------------------------------------------------------
+export function registerDecomposeTools(server, client, fieldCache) {
+    // -------------------------------------------------------------------------
+    // ralph_hero__decompose_feature
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__decompose_feature", "Split a feature description into repo-specific issues using a named decomposition pattern from .ralph-repos.yml. " +
+        "When no pattern is specified, lists available patterns and repos. " +
+        "When dryRun=true (default), returns a proposal without creating anything. " +
+        "When dryRun=false, creates the issues on GitHub and adds each to the project board. " +
+        "Returns: proposed_issues (with title, body, labels, assignees, estimate per repo), dependency_chain, matched_pattern.", {
+        title: z.string().describe("Feature name or title (used as issue title prefix)"),
+        description: z
+            .string()
+            .describe("Feature description (included in each issue body as Context)"),
+        pattern: z
+            .string()
+            .optional()
+            .describe("Decomposition pattern name from .ralph-repos.yml. " +
+            "Omit to list available patterns and repos."),
+        dryRun: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When true (default), return the proposal without creating issues. " +
+            "When false, create real issues on GitHub and add them to the project."),
+        projectNumber: z.coerce
+            .number()
+            .optional()
+            .describe("Project number override (defaults to configured project)"),
+    }, async (args) => {
+        try {
+            const registry = client.config.repoRegistry;
+            // If no registry is loaded, return a helpful error
+            if (!registry) {
+                return toolError("No .ralph-repos.yml registry loaded. " +
+                    "Create a .ralph-repos.yml file in your repo root and restart the MCP server. " +
+                    "See the ralph-hero documentation for the schema.");
+            }
+            // If no pattern specified, list available patterns and repos
+            if (!args.pattern) {
+                const available_patterns = Object.entries(registry.patterns ?? {}).map(([name, p]) => ({
+                    name,
+                    description: p.description,
+                    steps: p.decomposition.map((s) => `${s.repo}: ${s.role}`),
+                }));
+                const available_repos = Object.entries(registry.repos).map(([name, r]) => ({
+                    name,
+                    domain: r.domain,
+                    tech: r.tech,
+                    owner: r.owner,
+                }));
+                return toolSuccess({
+                    message: "No pattern specified. Provide a `pattern` parameter to decompose the feature.",
+                    available_patterns,
+                    available_repos,
+                });
+            }
+            // Build decomposition (pure — throws on unknown pattern or missing repo)
+            let decomposition;
+            try {
+                decomposition = buildDecomposition({
+                    title: args.title,
+                    description: args.description,
+                    pattern: args.pattern,
+                }, registry, client.config.owner);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return toolError(message);
+            }
+            // dryRun=true: return proposal without creating anything
+            if (args.dryRun !== false) {
+                return toolSuccess({
+                    dryRun: true,
+                    matched_pattern: decomposition.matched_pattern,
+                    proposed_issues: decomposition.proposed_issues,
+                    dependency_chain: decomposition.dependency_chain,
+                });
+            }
+            // dryRun=false: create real issues on GitHub
+            const { projectNumber, projectOwner } = resolveFullConfigOptionalRepo(client, { projectNumber: args.projectNumber });
+            // Ensure field cache is populated for project operations
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId(projectNumber);
+            if (!projectId) {
+                return toolError("Could not resolve project ID for adding issues to project");
+            }
+            const createdIssues = [];
+            // Create each proposed issue
+            for (const proposed of decomposition.proposed_issues) {
+                const issueOwner = proposed.owner ?? client.config.owner;
+                if (!issueOwner) {
+                    return toolError(`Cannot create issue for repo "${proposed.repoKey}": no owner resolved. ` +
+                        `Set owner in the registry entry or configure RALPH_GH_OWNER.`);
+                }
+                // Step 1: Get repository ID
+                const repoResult = await client.query(`query($owner: String!, $repo: String!) {
+              repository(owner: $owner, name: $repo) { id }
+            }`, { owner: issueOwner, repo: proposed.repoKey }, { cache: true, cacheTtlMs: 60 * 60 * 1000 });
+                const repoId = repoResult.repository?.id;
+                if (!repoId) {
+                    return toolError(`Repository ${issueOwner}/${proposed.repoKey} not found. ` +
+                        `Check that the repo key in .ralph-repos.yml matches the GitHub repo name.`);
+                }
+                // Step 2: Resolve label IDs if provided
+                let labelIds;
+                if (proposed.labels && proposed.labels.length > 0) {
+                    const labelResult = await client.query(`query($owner: String!, $repo: String!) {
+                repository(owner: $owner, name: $repo) {
+                  labels(first: 100) {
+                    nodes { id name }
+                  }
+                }
+              }`, { owner: issueOwner, repo: proposed.repoKey }, { cache: true, cacheTtlMs: 5 * 60 * 1000 });
+                    const allLabels = labelResult.repository.labels.nodes;
+                    labelIds = proposed.labels
+                        .map((name) => allLabels.find((l) => l.name === name)?.id)
+                        .filter((id) => id !== undefined);
+                }
+                // Step 3: Create the issue
+                const createResult = await client.mutate(`mutation($repoId: ID!, $title: String!, $body: String, $labelIds: [ID!]) {
+              createIssue(input: {
+                repositoryId: $repoId,
+                title: $title,
+                body: $body,
+                labelIds: $labelIds
+              }) {
+                issue {
+                  id
+                  number
+                  title
+                  url
+                }
+              }
+            }`, {
+                    repoId,
+                    title: proposed.title,
+                    body: proposed.body,
+                    labelIds: labelIds ?? null,
+                });
+                const issue = createResult.createIssue.issue;
+                // Cache the node ID
+                client
+                    .getCache()
+                    .set(`issue-node-id:${issueOwner}/${proposed.repoKey}#${issue.number}`, issue.id, 30 * 60 * 1000);
+                // Step 4: Add to project
+                const addResult = await client.projectMutate(`mutation($projectId: ID!, $contentId: ID!) {
+              addProjectV2ItemById(input: {
+                projectId: $projectId,
+                contentId: $contentId
+              }) {
+                item { id }
+              }
+            }`, { projectId, contentId: issue.id });
+                const projectItemId = addResult.addProjectV2ItemById.item.id;
+                // Cache project item ID
+                client
+                    .getCache()
+                    .set(`project-item-id:${issueOwner}/${proposed.repoKey}#${issue.number}`, projectItemId, 30 * 60 * 1000);
+                createdIssues.push({
+                    repoKey: proposed.repoKey,
+                    owner: issueOwner,
+                    number: issue.number,
+                    id: issue.id,
+                    title: issue.title,
+                    url: issue.url,
+                    projectItemId,
+                });
+            }
+            // Step 5: Wire dependencies (addSubIssue for dependency edges)
+            // Parse "a -> b" edges from dependency_chain; cross-repo sub-issues
+            // may not be supported — catch and continue.
+            const wiringResults = [];
+            for (const edge of decomposition.dependency_chain) {
+                const match = edge.match(/^\s*(\S+)\s*->\s*(\S+)\s*$/);
+                if (!match) {
+                    wiringResults.push({
+                        edge,
+                        status: "skipped",
+                        reason: "Unrecognized edge format (expected 'a -> b')",
+                    });
+                    continue;
+                }
+                const [, fromRepo, toRepo] = match;
+                const fromIssue = createdIssues.find((i) => i.repoKey === fromRepo);
+                const toIssue = createdIssues.find((i) => i.repoKey === toRepo);
+                if (!fromIssue || !toIssue) {
+                    wiringResults.push({
+                        edge,
+                        status: "skipped",
+                        reason: `Could not find created issue for repo "${fromRepo}" or "${toRepo}"`,
+                    });
+                    continue;
+                }
+                try {
+                    await client.mutate(`mutation($parentId: ID!, $childId: ID!) {
+                addSubIssue(input: {
+                  issueId: $parentId,
+                  subIssueId: $childId
+                }) {
+                  issue { id }
+                  subIssue { id }
+                }
+              }`, { parentId: fromIssue.id, childId: toIssue.id });
+                    wiringResults.push({ edge, status: "ok" });
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    wiringResults.push({
+                        edge,
+                        status: "skipped",
+                        reason: `addSubIssue failed (cross-repo sub-issues may not be supported): ${reason}`,
+                    });
+                }
+            }
+            return toolSuccess({
+                dryRun: false,
+                matched_pattern: decomposition.matched_pattern,
+                created_issues: createdIssues,
+                dependency_wiring: wiringResults,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to decompose feature: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=decompose-tools.js.map

package/dist/tools/issue-tools.js

@@ -15,6 +15,7 @@ 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, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, } from "../lib/helpers.js";
+import { lookupRepo, mergeDefaults } from "../lib/repo-registry.js";
 // ---------------------------------------------------------------------------
 // Register issue tools
 // ---------------------------------------------------------------------------
@@ -630,7 +631,33 @@ export function registerIssueTools(server, client, fieldCache) {
         priority: z.string().optional().describe("Priority (P0, P1, P2, P3)"),
     }, async (args) => {
         try {
-            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            // Resolve owner from registry for repo shorthand
+            let resolvedArgs = { ...args };
+            const registry = client.config.repoRegistry;
+            if (registry && args.repo && !args.owner) {
+                const repoLookup = lookupRepo(registry, args.repo);
+                if (repoLookup?.entry.owner) {
+                    resolvedArgs = { ...args, owner: repoLookup.entry.owner };
+                }
+            }
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, resolvedArgs);
+            // Apply registry defaults if available
+            let effectiveLabels = args.labels;
+            let effectiveAssignees = args.assignees;
+            let effectiveEstimate = args.estimate;
+            if (registry) {
+                const repoLookup = lookupRepo(registry, repo);
+                if (repoLookup) {
+                    const merged = mergeDefaults(repoLookup.entry.defaults, {
+                        labels: effectiveLabels,
+                        assignees: effectiveAssignees,
+                        estimate: effectiveEstimate,
+                    });
+                    effectiveLabels = merged.labels;
+                    effectiveAssignees = merged.assignees;
+                    effectiveEstimate = merged.estimate;
+                }
+            }
             // Ensure field cache is populated
             await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
             // Step 1: Get repository ID
@@ -643,7 +670,7 @@ export function registerIssueTools(server, client, fieldCache) {
             }
             // Step 2: Resolve label IDs if provided
             let labelIds;
-            if (args.labels && args.labels.length > 0) {
+            if (effectiveLabels && effectiveLabels.length > 0) {
                 const labelResult = await client.query(`query($owner: String!, $repo: String!) {
               repository(owner: $owner, name: $repo) {
                 labels(first: 100) {
@@ -652,7 +679,7 @@ export function registerIssueTools(server, client, fieldCache) {
               }
             }`, { owner, repo }, { cache: true, cacheTtlMs: 5 * 60 * 1000 });
                 const allLabels = labelResult.repository.labels.nodes;
-                labelIds = args.labels
+                labelIds = effectiveLabels
                     .map((name) => allLabels.find((l) => l.name === name)?.id)
                     .filter((id) => id !== undefined);
             }
@@ -707,8 +734,8 @@ export function registerIssueTools(server, client, fieldCache) {
                 await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", args.workflowState, projectNumber);
                 await syncStatusField(client, fieldCache, projectItemId, args.workflowState, projectNumber);
             }
-            if (args.estimate) {
-                await updateProjectItemField(client, fieldCache, projectItemId, "Estimate", args.estimate, projectNumber);
+            if (effectiveEstimate) {
+                await updateProjectItemField(client, fieldCache, projectItemId, "Estimate", effectiveEstimate, projectNumber);
             }
             if (args.priority) {
                 await updateProjectItemField(client, fieldCache, projectItemId, "Priority", args.priority, projectNumber);
@@ -721,7 +748,7 @@ export function registerIssueTools(server, client, fieldCache) {
                 projectItemId,
                 fieldsSet: {
                     workflowState: args.workflowState || null,
-                    estimate: args.estimate || null,
+                    estimate: effectiveEstimate || null,
                     priority: args.priority || null,
                 },
             });

package/package.json

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