patchrelay 0.47.1 → 0.47.2

package/README.md

@@ -83,14 +83,22 @@ You will also need:
 
 1. A human delegates PatchRelay on an issue to start automation.
 2. PatchRelay verifies the webhook, routes the issue to the right local project, and packages the issue context for the first loop.
-3. Delegated issues create or reuse the issue worktree and launch an implementation run through `codex app-server`.
+3. Delegated issues create or reuse the issue worktree and launch the appropriate first run through `codex app-server`.
 4. PatchRelay persists thread ids, run state, and observations so the work stays inspectable and resumable.
 5. GitHub webhooks drive reactive verification and repair loops: CI repair on check failures and review fix on changes requested.
-6. PatchRelay opens draft PRs while implementation is in progress and marks its own PR ready when implementation is complete.
+6. Implementation issues usually open draft PRs while work is in progress and mark PatchRelay-owned PRs ready when implementation is complete.
 7. Downstream automation reacts to GitHub truth: `reviewbot` reviews ready PRs with green CI, and Merge Steward admits ready PRs with green CI and approval into the merge queue.
 8. If requested changes, red CI, or a merge-steward incident lands on a linked delegated PR, PatchRelay resumes work on that same PR branch.
 9. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
 
+Not every delegated issue should produce its own PR. Some delegated issues are coordination-only:
+
+- parent trackers that spawn or coordinate child implementation issues
+- audit or convergence issues that should wait for child issues before doing a narrow final pass
+- planning/specification issues that are complete once the right follow-up issues or decisions exist
+
+In those cases, PatchRelay should avoid opening an overlapping umbrella PR and should finish through coordination, follow-up issue creation, or a no-PR completion path instead.
+
 ### Undelegation And Re-delegation
 
 Undelegation pauses PatchRelay authority. It does not erase PR truth.

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.47.1",
-  "commit": "919d86a4ee45",
-  "builtAt": "2026-04-18T12:45:08.672Z"
+  "version": "0.47.2",
+  "commit": "8e7084588da7",
+  "builtAt": "2026-04-18T12:47:45.623Z"
 }

package/dist/prompting/patchrelay.js

@@ -65,7 +65,76 @@ function buildTaskObjective(issue) {
         ...(intro ? ["", intro] : []),
     ].join("\n");
 }
-function buildScopeDiscipline(issue) {
+function summarizeRelationEntries(entries, options) {
+    if (entries.length === 0) {
+        return options?.emptyText ? [options.emptyText] : [];
+    }
+    const maxItems = options?.maxItems ?? 5;
+    const lines = entries.slice(0, maxItems).map((entry) => {
+        const issueRef = typeof entry.issueKey === "string" && entry.issueKey.trim()
+            ? entry.issueKey.trim()
+            : typeof entry.linearIssueId === "string" && entry.linearIssueId.trim()
+                ? entry.linearIssueId.trim()
+                : "unknown issue";
+        const title = typeof entry.title === "string" && entry.title.trim() ? entry.title.trim() : undefined;
+        const stateName = typeof entry.stateName === "string" && entry.stateName.trim()
+            ? entry.stateName.trim()
+            : typeof entry.currentLinearState === "string" && entry.currentLinearState.trim()
+                ? entry.currentLinearState.trim()
+                : undefined;
+        const factoryState = typeof entry.factoryState === "string" && entry.factoryState.trim() ? entry.factoryState.trim() : undefined;
+        const delegated = typeof entry.delegatedToPatchRelay === "boolean"
+            ? (entry.delegatedToPatchRelay ? "delegated" : "not delegated")
+            : undefined;
+        const openPr = typeof entry.hasOpenPr === "boolean"
+            ? (entry.hasOpenPr ? "open PR" : "no open PR")
+            : undefined;
+        return [
+            `- ${issueRef}`,
+            title ? `: ${title}` : "",
+            [stateName, factoryState, delegated, openPr].filter(Boolean).length > 0
+                ? ` (${[stateName, factoryState, delegated, openPr].filter(Boolean).join("; ")})`
+                : "",
+        ].join("");
+    });
+    if (entries.length > maxItems) {
+        lines.push(`- ...and ${entries.length - maxItems} more`);
+    }
+    return lines;
+}
+function buildCoordinationGuidance(context) {
+    const unresolvedBlockers = Array.isArray(context?.unresolvedBlockers)
+        ? context.unresolvedBlockers.filter((entry) => Boolean(entry) && typeof entry === "object")
+        : [];
+    const trackedDependents = Array.isArray(context?.trackedDependents)
+        ? context.trackedDependents.filter((entry) => Boolean(entry) && typeof entry === "object")
+        : [];
+    const lines = [
+        "### Coordination / Issue Topology",
+        "",
+        "First decide whether this issue should publish code itself or mainly coordinate other issues.",
+        "If this issue is a parent tracker, umbrella, migration program, or convergence container and the concrete implementation belongs in child issues, do not create a duplicate umbrella PR.",
+        "When child issues already own the concrete code slices, use this issue to coordinate, create or refine follow-up issues, or verify convergence. Only ship code here if this issue still has unique implementation scope that is not already owned elsewhere.",
+        "Prefer one PR per concrete implementation issue over a broad parent branch that restates overlapping child work.",
+    ];
+    if (unresolvedBlockers.length === 0 && trackedDependents.length === 0) {
+        return lines;
+    }
+    lines.push("", "Known relations from PatchRelay:");
+    if (unresolvedBlockers.length > 0) {
+        lines.push("Unresolved blockers:");
+        lines.push(...summarizeRelationEntries(unresolvedBlockers));
+    }
+    if (trackedDependents.length > 0) {
+        if (unresolvedBlockers.length > 0) {
+            lines.push("");
+        }
+        lines.push("Tracked dependent issues:");
+        lines.push(...summarizeRelationEntries(trackedDependents));
+    }
+    return lines;
+}
+function buildScopeDiscipline(issue, context) {
     const description = issue.description?.trim();
     const scope = extractIssueSection(description, "Scope");
     const acceptance = extractIssueSection(description, "Acceptance criteria")
@@ -84,6 +153,8 @@ function buildScopeDiscipline(issue) {
         ...(scope ? ["### In Scope", "", scope, ""] : []),
         ...(acceptance ? ["### Acceptance / Done", "", acceptance, ""] : []),
         ...(relevantCode ? ["### Relevant Code", "", relevantCode, ""] : []),
+        ...buildCoordinationGuidance(context),
+        "",
         "### Likely Review Invariants",
         "",
         "- Check the surfaces explicitly named in the task before stopping.",
@@ -353,6 +424,7 @@ function buildPublicationContract(runType) {
             "",
             "Before finishing, publish the result instead of leaving it only in the worktree.",
             "If the task is genuinely complete without a PR, say so clearly in your normal summary instead of inventing one.",
+            "If the issue is acting as coordination-only work and the real implementation belongs in child issues, finish without opening an overlapping umbrella PR.",
             "If the worktree already contains relevant changes for this issue, verify them and publish them.",
             "If you changed files for this issue, commit them, push the issue branch, and open or update the PR before stopping.",
             "Do not stop with only local commits or uncommitted changes.",
@@ -391,7 +463,7 @@ function buildSections(issue, runType, repoPath, context, followUp = false) {
     if (followUp && reactiveContext) {
         sections.push({ id: "follow-up-turn", content: reactiveContext });
     }
-    sections.push({ id: "task-objective", content: buildTaskObjective(issue) }, { id: "scope-discipline", content: buildScopeDiscipline(issue) });
+    sections.push({ id: "task-objective", content: buildTaskObjective(issue) }, { id: "scope-discipline", content: buildScopeDiscipline(issue, context) });
     const humanContext = buildHumanContext(context);
     if (humanContext) {
         sections.push({ id: "human-context", content: humanContext });

package/dist/run-orchestrator.js

@@ -30,6 +30,9 @@ function shouldDelayZombieRecoveryLaunch(issue, issueSession, runType) {
         return 0;
     return getRemainingZombieRecoveryDelayMs(issue.lastZombieRecoveryAt, issue.zombieRecoveryAttempts);
 }
+function isResolvedDependencyState(stateType) {
+    return stateType === "completed" || stateType?.trim().toLowerCase() === "done";
+}
 export class RunOrchestrator {
     config;
     db;
@@ -135,6 +138,38 @@ export class RunOrchestrator {
     materializeLegacyPendingWake(issue, lease) {
         return this.runWakePlanner.materializeLegacyPendingWake(issue, lease);
     }
+    buildImplementationCoordinationContext(issue) {
+        const unresolvedBlockers = this.db.issues
+            .listIssueDependencies(issue.projectId, issue.linearIssueId)
+            .filter((entry) => !isResolvedDependencyState(entry.blockerCurrentLinearStateType))
+            .map((entry) => ({
+            linearIssueId: entry.blockerLinearIssueId,
+            ...(entry.blockerIssueKey ? { issueKey: entry.blockerIssueKey } : {}),
+            ...(entry.blockerTitle ? { title: entry.blockerTitle } : {}),
+            ...(entry.blockerCurrentLinearState ? { stateName: entry.blockerCurrentLinearState } : {}),
+            ...(entry.blockerCurrentLinearStateType ? { stateType: entry.blockerCurrentLinearStateType } : {}),
+        }));
+        const trackedDependents = this.db.issues
+            .listDependents(issue.projectId, issue.linearIssueId)
+            .map((entry) => this.db.issues.getIssue(issue.projectId, entry.linearIssueId))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => ({
+            linearIssueId: entry.linearIssueId,
+            ...(entry.issueKey ? { issueKey: entry.issueKey } : {}),
+            ...(entry.title ? { title: entry.title } : {}),
+            factoryState: entry.factoryState,
+            ...(entry.currentLinearState ? { currentLinearState: entry.currentLinearState } : {}),
+            delegatedToPatchRelay: entry.delegatedToPatchRelay,
+            hasOpenPr: entry.prNumber !== undefined && entry.prState !== "closed" && entry.prState !== "merged",
+        }));
+        if (unresolvedBlockers.length === 0 && trackedDependents.length === 0) {
+            return {};
+        }
+        return {
+            ...(unresolvedBlockers.length > 0 ? { unresolvedBlockers } : {}),
+            ...(trackedDependents.length > 0 ? { trackedDependents } : {}),
+        };
+    }
     // ─── Run ────────────────────────────────────────────────────────
     async run(item) {
         await this.refreshCodexRuntimeConfig();
@@ -177,9 +212,15 @@ export class RunOrchestrator {
             this.releaseIssueSessionLease(item.projectId, item.issueId);
             return;
         }
-        const effectiveContext = isRequestedChangesRunType(runType)
+        const baseContext = isRequestedChangesRunType(runType)
             ? await this.runCompletionPolicy.resolveRequestedChangesWakeContext(issue, runType, context)
             : context;
+        const coordinationContext = runType === "implementation"
+            ? this.buildImplementationCoordinationContext(issue)
+            : undefined;
+        const effectiveContext = coordinationContext
+            ? { ...coordinationContext, ...(baseContext ?? {}) }
+            : baseContext;
         const sourceHeadSha = typeof effectiveContext?.failureHeadSha === "string"
             ? effectiveContext.failureHeadSha
             : typeof effectiveContext?.headSha === "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.47.1",
+  "version": "0.47.2",
   "license": "MIT",
   "type": "module",
   "repository": {