patchrelay 0.50.1 → 0.50.2

package/README.md

@@ -61,12 +61,12 @@ patchrelay service status
 patchrelay dashboard
 ```
 
-Each repo needs two workflow files that act as agent prompts:
+Each repo needs two workflow files for repo-specific run behavior:
 
 - `IMPLEMENTATION_WORKFLOW.md` — implementation, CI repair, queue repair runs
 - `REVIEW_WORKFLOW.md` — review fix runs
 
-Keep them short, action-oriented, human-authored. See [prompting.md](./docs/prompting.md) for how the built-in scaffold composes them with the rest of the prompt.
+Keep them short, action-oriented, human-authored. Durable machine-level policy belongs in Codex `developer_instructions`; workflow files are for repo-local behavior and validation. See [prompting.md](./docs/prompting.md) for how the built-in scaffold composes them.
 
 Full install, ingress, and GitHub/Linear app setup: [self-hosting.md](./docs/self-hosting.md). Daily ops and CLI cheatsheet: [operator-guide.md](./docs/operator-guide.md).
 

package/config/patchrelay.example.json

@@ -6,7 +6,8 @@
     "git_bin": "git",
     "codex": {
       "model": "gpt-5.3-codex-spark",
-      "reasoning_effort": "high"
+      "reasoning_effort": "high",
+      "developer_instructions": "Keep the public API stable for this installation unless the task explicitly requires a breaking change."
     }
   }
 }

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.50.1",
-  "commit": "27eb3a4a1840",
-  "builtAt": "2026-04-20T12:44:08.573Z"
+  "version": "0.50.2",
+  "commit": "59ab92391401",
+  "builtAt": "2026-04-20T18:42:11.703Z"
 }

package/dist/completion-check.js

@@ -101,6 +101,12 @@ function buildCompletionCheckPrompt(params) {
         '- "done" if the task was successfully completed without a PR.',
         '- "failed" if the run stopped incorrectly and PatchRelay should not auto-continue.',
         "",
+        "Bias rules:",
+        '- Prefer "continue" when the task looks like normal code-delivery work and the run simply ended before publishing a branch or PR.',
+        '- Use "done" only when the issue explicitly permits a no-PR outcome or the deliverable is clearly non-repo work such as planning, orchestration, or follow-up issue creation.',
+        '- Use "needs_input" only when one specific missing human decision blocks the very next concrete action. Do not use it just because the branch might need more work.',
+        '- If the run appears unfinished but still actionable by PatchRelay, return "continue", not "done".',
+        "",
         "Facts:",
         `- Issue: ${params.issue.issueKey ?? params.issue.linearIssueId}`,
         ...(params.issue.title ? [`- Title: ${params.issue.title}`] : []),

package/dist/config.js

@@ -9,6 +9,21 @@ import { ensureAbsolutePath } from "./utils.js";
 const LINEAR_OAUTH_CALLBACK_PATH = "/oauth/linear/callback";
 const REPO_SETTINGS_DIRNAME = ".patchrelay";
 const REPO_SETTINGS_FILENAME = "project.json";
+const DEFAULT_PATCHRELAY_DEVELOPER_INSTRUCTIONS = [
+    "You are PatchRelay's coding agent.",
+    "",
+    "Core rules:",
+    "- Complete the delegated task in the current repository and worktree.",
+    "- Stay inside the issue's scope. Do not widen into unrelated cleanup or polish.",
+    "- Use repository docs and workflow files as the source of truth for local conventions.",
+    "- Prefer concrete fixes over speculative defenses.",
+    "- For code-delivery work, publish before stopping.",
+    "- If you change files for an implementation run, commit, push the issue branch, and open or update the PR.",
+    "- For repair runs, work on the existing PR branch and do not open a new PR.",
+    "- A requested-changes repair is only complete after a newer PR head is pushed, unless a genuine external blocker prevents correct publication.",
+    "- If a broader inconsistency is not required to make this task correct, mention it briefly instead of expanding scope.",
+    "- Before publishing, do one brief reviewer-minded pass on the current head and fix likely in-scope blockers.",
+].join("\n");
 const trustedActorsSchema = z
     .object({
     ids: z.array(z.string().min(1)).default([]),
@@ -238,6 +253,13 @@ function loadPromptLayer(configDir, layer) {
         replaceSections: Object.fromEntries(Object.entries(layer.replace_sections).map(([sectionId, fragmentPath]) => [sectionId, readPromptFile(configDir, fragmentPath)])),
     };
 }
+function mergeDeveloperInstructions(custom) {
+    const normalized = custom?.trim();
+    if (!normalized) {
+        return DEFAULT_PATCHRELAY_DEVELOPER_INSTRUCTIONS;
+    }
+    return `${DEFAULT_PATCHRELAY_DEVELOPER_INSTRUCTIONS}\n\n## Local Developer Instructions\n\n${normalized}`;
+}
 function expandEnv(value, env) {
     if (typeof value === "string") {
         return value.replace(/\$\{([A-Z0-9_]+)(?::-(.*?))?\}/g, (_match, name, fallback) => {
@@ -548,9 +570,7 @@ export function loadConfig(configPath = process.env.PATCHRELAY_CONFIG ?? getDefa
                 ...(parsed.runner.codex.reasoning_effort ? { reasoningEffort: parsed.runner.codex.reasoning_effort } : {}),
                 ...(parsed.runner.codex.service_name ? { serviceName: parsed.runner.codex.service_name } : {}),
                 ...(parsed.runner.codex.base_instructions ? { baseInstructions: parsed.runner.codex.base_instructions } : {}),
-                ...(parsed.runner.codex.developer_instructions
-                    ? { developerInstructions: parsed.runner.codex.developer_instructions }
-                    : {}),
+                developerInstructions: mergeDeveloperInstructions(parsed.runner.codex.developer_instructions),
                 approvalPolicy: parsed.runner.codex.approval_policy,
                 sandboxMode: parsed.runner.codex.sandbox_mode,
                 persistExtendedHistory: parsed.runner.codex.persist_extended_history,

package/dist/prompting/patchrelay.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import path from "node:path";
 const WORKFLOW_FILES = {
     implementation: "IMPLEMENTATION_WORKFLOW.md",
@@ -22,12 +22,10 @@ export const PATCHRELAY_REPLACEABLE_SECTION_IDS = [
     "workflow-guidance",
     "publication-contract",
 ];
-function readWorkflowFile(repoPath, runType) {
+function hasWorkflowFile(repoPath, runType) {
     const filename = WORKFLOW_FILES[runType];
     const filePath = path.join(repoPath, filename);
-    if (!existsSync(filePath))
-        return undefined;
-    return readFileSync(filePath, "utf8").trim();
+    return existsSync(filePath);
 }
 function buildPromptHeader(issue) {
     return [
@@ -102,7 +100,7 @@ function summarizeRelationEntries(entries, options) {
     }
     return lines;
 }
-function buildCoordinationGuidance(context) {
+function buildIssueTopology(context) {
     const unresolvedBlockers = Array.isArray(context?.unresolvedBlockers)
         ? context.unresolvedBlockers.filter((entry) => Boolean(entry) && typeof entry === "object")
         : [];
@@ -111,18 +109,10 @@ function buildCoordinationGuidance(context) {
         : 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 && childIssues.length === 0) {
-        return lines;
+        return [];
     }
-    lines.push("", "Known relations from PatchRelay:");
+    const lines = ["### Issue Topology", ""];
     if (unresolvedBlockers.length > 0) {
         lines.push("Unresolved blockers:");
         lines.push(...summarizeRelationEntries(unresolvedBlockers));
@@ -136,35 +126,25 @@ function buildCoordinationGuidance(context) {
     }
     return lines;
 }
-function buildScopeDiscipline(issue, context) {
+function buildConstraints(issue, context) {
     const description = issue.description?.trim();
     const scope = extractIssueSection(description, "Scope");
     const acceptance = extractIssueSection(description, "Acceptance criteria")
         ?? extractIssueSection(description, "Success criteria");
     const relevantCode = extractIssueSection(description, "Relevant code");
+    const topology = buildIssueTopology(context);
     return [
-        "## Scope Discipline",
+        "## Constraints",
         "",
-        "Stay inside the delegated task.",
-        "Finish the issue completely enough to satisfy its stated scope and acceptance criteria, but do not widen it into unrelated product polish or follow-up cleanup.",
-        "Only broaden to adjacent routes, copy, or supporting surfaces when the issue text or repository guidance explicitly says they are the same user flow.",
-        "Your implementation goal is to leave the branch review-ready, not merely locally working: look for likely regressions or invariant breaks in the touched flow before you stop.",
-        "If a narrow patch fixes the immediate symptom but leaves the same underlying risk elsewhere in the changed flow, keep going until the branch is likely to survive strict review or clearly explain the blocker.",
-        "If you notice a worthwhile broader inconsistency that is not required to make this task correct, mention it in your summary as follow-up context instead of expanding the implementation.",
+        "Stay inside the delegated task. Do not widen scope into unrelated cleanup or optional polish.",
         "",
         ...(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.",
-        "- If repository guidance says certain changed surfaces are one flow, verify that shared flow, but do not treat unrelated surrounding cleanup as part of this task.",
-        "- A review repair should fix the concrete concern on the current head, not silently expand the Linear issue into a broader rewrite.",
+        ...topology,
     ].join("\n");
 }
-function buildOrchestrationScopeDiscipline(context) {
+function buildOrchestrationConstraints(context) {
     const unresolvedBlockers = Array.isArray(context?.unresolvedBlockers)
         ? context.unresolvedBlockers.filter((entry) => Boolean(entry) && typeof entry === "object")
         : [];
@@ -174,23 +154,11 @@ function buildOrchestrationScopeDiscipline(context) {
             ? context.trackedDependents.filter((entry) => Boolean(entry) && typeof entry === "object")
             : [];
     return [
-        "## Scope Discipline",
+        "## Constraints",
         "",
-        "This issue is orchestration work.",
-        "Treat it as the owner of convergence across related issues rather than as a normal code-owning implementation branch.",
-        "Inspect why this wake happened before acting.",
-        "Adopt already-existing canonical child issues when they cover the intended split.",
-        "Do not recreate child issues that already exist under this parent unless a genuinely missing required slice remains.",
-        "Do not create an overlapping umbrella PR unless this parent clearly owns unique direct cleanup work that child issues do not already cover.",
-        "When you split required implementation work out of the parent, make it a child issue of this umbrella rather than making the parent block the child.",
-        "If sequencing matters, let the parent wait on the child; do not model the child as blocked by the parent umbrella it is supposed to satisfy.",
-        "If child work is still in motion, babysit the plan, record useful observations, and return to waiting.",
-        "If child work looks delivered, audit whether the original parent goal is actually satisfied.",
-        "Create blocking follow-up work only when it is necessary to satisfy the original parent goal.",
-        "Prefer non-blocking follow-up issues over keeping the umbrella open for optional polish or adjacent expansion.",
-        "New child issues should stay in Backlog and undelegated by default.",
-        "Only delegate or move a new child to Start when it is immediately actionable, unblocked, and you intend for PatchRelay to begin it right away.",
-        "If you create multiple new child issues, keep later-wave or dependency-bound children queued rather than waking them all at once.",
+        "This issue is orchestration work. Coordinate convergence instead of duplicating child implementation.",
+        "Do not open an overlapping umbrella PR unless this parent owns unique direct work.",
+        "Leave later-wave child issues queued unless they are immediately actionable.",
         "",
         "### Child Issue Summaries",
         "",
@@ -204,29 +172,28 @@ function buildOrchestrationScopeDiscipline(context) {
         "### Convergence Rule",
         "",
         "- Close the umbrella when the original parent goal is satisfied.",
-        "- If you discover one missing required slice, you may create a justified blocking follow-up.",
-        "- Do not invent optional expansion without explicit human approval.",
+        "- Create blocking follow-up work only when it is required to satisfy that goal.",
     ].join("\n");
 }
-function buildHumanContext(context) {
+function buildHumanContextLines(context) {
     const promptContext = typeof context?.promptContext === "string" ? context.promptContext.trim() : "";
     const latestPrompt = typeof context?.promptBody === "string" ? context.promptBody.trim() : "";
     const operatorPrompt = typeof context?.operatorPrompt === "string" ? context.operatorPrompt.trim() : "";
     const userComment = typeof context?.userComment === "string" ? context.userComment.trim() : "";
     const lines = [];
     if (promptContext) {
-        lines.push("## Linear Session Context", "", promptContext, "");
+        lines.push("Linear session context:", promptContext, "");
     }
     if (latestPrompt) {
-        lines.push("## Latest Human Instruction", "", latestPrompt, "");
+        lines.push("Latest human instruction:", latestPrompt, "");
     }
     if (operatorPrompt) {
-        lines.push("## Operator Prompt", "", operatorPrompt, "");
+        lines.push("Operator prompt:", operatorPrompt, "");
     }
     if (userComment) {
-        lines.push("## Human Follow-up Comment", "", userComment, "");
+        lines.push("Human follow-up comment:", userComment, "");
     }
-    return lines.length > 0 ? lines.join("\n").trim() : undefined;
+    return lines;
 }
 function resolveRequestedChangesMode(runType, context) {
     if (runType === "branch_upkeep") {
@@ -303,12 +270,12 @@ function buildRequestedChangesContext(runType, context) {
     const mode = resolveRequestedChangesMode(runType, context);
     const lines = [];
     if (mode === "branch_upkeep") {
-        lines.push("## Branch Upkeep After Requested Changes", "", "Goal: restore merge readiness on the existing PR branch without regressing review or CI readiness.", "The requested review changes may already be addressed, but GitHub still shows the PR branch as behind or dirty against the base branch.", "Update the existing PR branch onto the latest base branch, resolve conflicts carefully, rerun the narrowest relevant verification, and push a newer head.", "Do not open a new PR.", "", "1. Refresh the latest remote branch and base branch state first.", "2. Rebase or merge onto the latest base branch and resolve conflicts in a way that preserves the branch's current intent and prior fixes.", "3. Audit the conflicted areas for semantic regressions, not just textual conflicts.", "4. Run focused verification for the touched areas and enough surrounding checks to regain confidence that the branch is still review-ready.", "5. Commit and push a newer head on the existing PR branch.", "6. Do not stop at 'conflicts resolved' if the resulting branch is no longer likely to pass review or CI.", "");
+        lines.push("Branch upkeep is required on the existing PR branch.", "Goal: restore merge readiness on the current branch and push a newer head without regressing review or CI readiness.");
     }
     else {
         const reviewer = typeof context?.reviewerName === "string" ? context.reviewerName : undefined;
         const reviewBody = typeof context?.reviewBody === "string" ? context.reviewBody.trim() : "";
-        lines.push("## Review Changes Requested", "", "Goal: restore review readiness on the existing PR branch, not merely patch the latest cited line.", "Treat the reviewer comments as evidence of what still makes the branch unready. Your job is to return the branch to a state that is likely to pass the next full review.", "", reviewer ? `Reviewer: ${reviewer}` : "", reviewBody ? `Review summary:\n${reviewBody}` : "", "", "1. Start with the structured review context below, then inspect the PR's inline review comments with `gh api repos/<owner>/<repo>/pulls/<pr>/comments?per_page=100` so you begin from the full code-review context, not just the latest triggering comment.", "2. Inspect the current diff with `review-quill diff` when available so you see the reviewer-oriented diff view from this checkout; use `git diff origin/main` as a fallback, then inspect the current code before deciding what still needs work.", "3. Infer the underlying concern or invariant behind the review feedback. Do not assume each comment is an isolated chore.", "4. For each review point: if already resolved on the current head, note why. If not, fix it. Then inspect adjacent code paths and flows that could fail for the same reason.", "5. Verify the branch as a whole for the relevant concern class: current review issue, nearby regressions, relevant tests, and compatibility with the latest base branch.", "6. Only finish when you believe the branch is review-ready again. If you cannot get it there, stop and surface the blocker clearly.", "7. Commit and push a newer head on the existing PR branch. Do not try to hand the same head back to review.", "8. GitHub review happens after the new head is pushed and CI is green. Do not use `gh pr edit --add-reviewer` as part of this workflow.", "");
+        lines.push("Requested changes on the existing PR branch.", "Goal: restore review readiness and push a newer head on the current PR branch.", "Address the real concern behind the feedback and verify nearby invariants in the touched flow before you publish.", reviewer ? `Reviewer: ${reviewer}` : "", reviewBody ? `Review summary:\n${reviewBody}` : "");
         appendStructuredReviewContext(lines, context);
     }
     return lines.join("\n").trim();
@@ -318,10 +285,8 @@ function buildCiRepairContext(context) {
         ? context.ciSnapshot
         : undefined;
     return [
-        "## CI Repair",
-        "",
-        "Goal: restore CI readiness on the existing PR branch so the next full CI run is likely to pass.",
-        "A full CI iteration has settled failed on your PR. Start from the specific failing check/job/step below on the latest remote PR branch tip, but do not stop at a narrow patch if the same root cause is likely to fail other checks in the suite.",
+        "Settled CI failure on the existing PR branch.",
+        "Goal: restore CI readiness and push a branch that is likely to pass the next full CI run.",
         snapshot?.gateCheckName ? `Gate check: ${String(snapshot.gateCheckName)}` : "",
         snapshot?.gateCheckStatus ? `Gate status: ${String(snapshot.gateCheckStatus)}` : "",
         snapshot?.settledAt ? `Settled at: ${String(snapshot.settledAt)}` : "",
@@ -337,14 +302,6 @@ function buildCiRepairContext(context) {
         Array.isArray(context?.annotations) && context.annotations.length > 0
             ? `Annotations:\n${context.annotations.map((entry) => `- ${String(entry)}`).join("\n")}`
             : "",
-        "",
-        "Fetch the latest remote branch state first. If the branch moved since this failure, restart from the new tip instead of pushing older work.",
-        "Read the latest logs for the named failing check, identify the root cause, and check whether that same cause is likely to affect other jobs or checks.",
-        "Fix the root cause, not just the first visible symptom.",
-        "Do not change workflows, dependency installation, or unrelated tests unless the failing logs clearly point there.",
-        "Run the narrowest local verification that gives real confidence for the suite, then commit and push.",
-        "Do not open a new PR. Keep working on the existing branch until the branch is likely to pass CI again or the situation is clearly stuck.",
-        "Do not change test expectations unless the test is genuinely wrong.",
     ].filter(Boolean).join("\n");
 }
 function appendQueueRepairContext(lines, context) {
@@ -388,67 +345,57 @@ function appendQueueRepairContext(lines, context) {
 function buildQueueRepairContext(context) {
     const lines = [];
     appendQueueRepairContext(lines, context);
-    lines.push("## Merge Queue Failure", "", "The merge queue rejected this PR. Rebase onto latest main and fix conflicts.", context?.failureReason ? `Failure reason: ${String(context.failureReason)}` : "", "", "Fetch and rebase onto latest main, resolve conflicts, run verification, push.", "If the conflict is a semantic contradiction, explain and stop.");
+    lines.push("Merge queue rejection on the existing PR branch.", "Goal: restore a mergeable branch, verify the queue-blocking fix, and push the existing PR branch.", context?.failureReason ? `Failure reason: ${String(context.failureReason)}` : "");
     return lines.filter(Boolean).join("\n");
 }
-function buildFollowUpPromptPrelude(issue, runType, context) {
+function buildFollowUpContextLines(issue, runType, context) {
     const wakeReason = typeof context?.wakeReason === "string" ? context.wakeReason : undefined;
     const followUps = Array.isArray(context?.followUps) ? context.followUps : [];
     const followUpLines = followUps
         .filter((entry) => Boolean(entry) && typeof entry === "object")
         .map((entry) => `${String(entry.type ?? "follow_up")} from ${String(entry.author ?? "unknown")}: ${String(entry.text ?? "").trim()}`.trim())
         .filter((line) => !line.endsWith(":"));
-    const lines = [
-        "## Follow-up Turn",
-        "",
-        wakeReason === "direct_reply"
-            ? "Why this turn exists: A human reply arrived for the outstanding question from the previous turn."
-            : wakeReason === "initial_delegate"
-                ? "Why this turn exists: This orchestration issue was just delegated and needs an initial plan."
-                : wakeReason === "child_delivered"
-                    ? "Why this turn exists: A child issue was delivered and the umbrella needs to review the outcome."
-                    : wakeReason === "child_changed"
-                        ? "Why this turn exists: A child issue changed state and the umbrella may need to adjust."
-                        : wakeReason === "child_regressed"
-                            ? "Why this turn exists: A previously progressing child issue regressed and the umbrella needs to reassess."
-                            : wakeReason === "human_instruction"
-                                ? "Why this turn exists: A human added new guidance for this orchestration issue."
-                                : wakeReason === "completion_check_continue"
-                                    ? "Why this turn exists: The previous turn ended without a PR, and PatchRelay's completion check decided the work should continue automatically."
-                                    : wakeReason === "branch_upkeep"
-                                        ? "Why this turn exists: GitHub still shows the PR branch as needing upkeep after the requested code change was addressed."
-                                        : wakeReason === "followup_comment"
-                                            ? "Why this turn exists: A human follow-up comment arrived after the previous turn."
-                                            : `Why this turn exists: Continue the existing ${runType} run from the latest issue state.`,
-        wakeReason === "direct_reply"
-            ? "Required action now: Apply the latest human answer, continue from the current branch/session context, and publish the next concrete result."
-            : wakeReason === "initial_delegate"
-                ? "Required action now: Inspect the umbrella goal, review the child set, and record the next orchestration step."
-                : wakeReason === "completion_check_continue"
-                    ? "Required action now: Continue from the current branch and thread context, finish the task, and publish the next concrete result."
-                    : "Required action now: Continue from the latest branch state, refresh any stale assumptions, and publish the next concrete result.",
-        "",
-    ];
+    const lines = [];
+    const turnReason = wakeReason === "direct_reply"
+        ? "Human reply to the previous question."
+        : wakeReason === "initial_delegate"
+            ? "Initial orchestration turn after delegation."
+            : wakeReason === "child_delivered"
+                ? "A child issue was delivered."
+                : wakeReason === "child_changed"
+                    ? "A child issue changed state."
+                    : wakeReason === "child_regressed"
+                        ? "A child issue regressed."
+                        : wakeReason === "human_instruction"
+                            ? "A human added new orchestration guidance."
+                            : wakeReason === "completion_check_continue"
+                                ? "The previous turn ended without a PR and PatchRelay chose to continue automatically."
+                                : wakeReason === "branch_upkeep"
+                                    ? "GitHub still shows the PR branch as needing upkeep."
+                                    : wakeReason === "followup_comment"
+                                        ? "A human follow-up comment arrived after the previous turn."
+                                        : `Continue the existing ${runType} run from the latest issue state.`;
+    lines.push(`Turn reason: ${turnReason}`);
     if (wakeReason === "completion_check_continue" && typeof context?.completionCheckSummary === "string" && context.completionCheckSummary.trim()) {
-        lines.push(`Completion check summary: ${context.completionCheckSummary.trim()}`, "");
+        lines.push(`Completion check summary: ${context.completionCheckSummary.trim()}`);
     }
     if (followUpLines.length > 0) {
-        lines.push("Recent updates:");
+        lines.push("", "Recent updates:");
         followUpLines.forEach((line) => lines.push(`- ${line}`));
-        lines.push("");
     }
     if (issue.prNumber || issue.prHeadSha || issue.prReviewState || context?.mergeStateStatus) {
-        lines.push("## Current PR Facts", "", `Fact freshness: ${context?.githubFactsFresh === true
+        lines.push("", "Current PR facts:", `Fact freshness: ${context?.githubFactsFresh === true
             ? "refreshed immediately before this turn was created."
             : "may now be stale; refresh before making irreversible decisions."}`, issue.prNumber ? `Current PR: #${issue.prNumber}` : "", issue.prHeadSha ? `Current relevant head SHA: ${issue.prHeadSha}` : "", issue.prReviewState ? `Current review state: ${issue.prReviewState}` : "", typeof context?.mergeStateStatus === "string" ? `Merge state against ${String(context?.baseBranch ?? "main")}: ${String(context.mergeStateStatus)}` : "");
     }
-    return lines.filter(Boolean).join("\n");
+    return lines.filter(Boolean);
 }
-function buildReactiveContext(runType, issue, context, followUp = false) {
+function buildCurrentContext(runType, issue, context, followUp = false) {
     const lines = [];
     if (followUp) {
-        lines.push(buildFollowUpPromptPrelude(issue, runType, context), "");
+        lines.push(...buildFollowUpContextLines(issue, runType, context), "");
     }
+    lines.push(...buildHumanContextLines(context));
     switch (runType) {
         case "ci_repair":
             lines.push(buildCiRepairContext(context));
@@ -464,74 +411,72 @@ function buildReactiveContext(runType, issue, context, followUp = false) {
             break;
     }
     const content = lines.map((line) => line.trimEnd()).join("\n").trim();
-    return content.length > 0 ? content : undefined;
+    if (!content.length)
+        return undefined;
+    return ["## Current Context", "", content].join("\n");
 }
 function buildWorkflowGuidance(repoPath, runType) {
-    const workflowBody = readWorkflowFile(repoPath, runType);
-    if (workflowBody)
-        return workflowBody;
-    if (runType === "implementation") {
-        return "Implement the Linear issue. Read the issue via MCP for details.";
+    const filename = WORKFLOW_FILES[runType];
+    if (hasWorkflowFile(repoPath, runType)) {
+        return [
+            "## Workflow",
+            "",
+            `Read and follow \`${filename}\` in the repository for task-specific behavior before making irreversible changes.`,
+        ].join("\n");
     }
-    return "";
+    return [
+        "## Workflow",
+        "",
+        "Use repository docs and local guidance as the source of truth for task-specific behavior.",
+    ].join("\n");
 }
 function buildOrchestrationWorkflowGuidance() {
     return [
-        "## Workflow Guidance",
+        "## Workflow",
         "",
-        "Use the wake reason and current child issue summaries to decide what kind of orchestration work is needed now.",
-        "Typical orchestration phases are: initial setup, waiting on child progress, reviewing delivered child work, final audit, creating a justified follow-up, or closing the umbrella.",
-        "When creating follow-up work, prefer one immediately runnable child at a time and keep the rest queued until their prerequisites are genuinely ready.",
+        "Use the wake reason and child issue summaries to decide the next orchestration step.",
         "Keep outputs concise and observable in Linear.",
     ].join("\n");
 }
+function buildPrePushSelfReviewSection(target) {
+    const publishTarget = target === "new_pr"
+        ? "open or update the PR"
+        : "push the existing PR branch";
+    return [
+        "## Final Self-Review Before Push",
+        "",
+        `Before you ${publishTarget}, do one brief reviewer-minded pass on the current head.`,
+        "Fix any likely in-scope blocker you can see now: missing edge-case handling, broken adjacent invariant in the touched flow, mismatch between the PR explanation and the code, or an obviously unreviewable half-finished branch.",
+        "Do not widen scope for optional cleanup. If the issue explicitly allows a non-PR outcome, complete that outcome clearly; otherwise publish before stopping.",
+    ];
+}
 function buildPublicationContract(runType, issueClass) {
     if (issueClass === "orchestration") {
         return [
-            "## Publication Requirements",
+            "## Publish",
             "",
-            "Before finishing, publish the orchestration outcome rather than leaving it implicit.",
-            "By default, orchestration work should finish without opening an overlapping umbrella PR.",
-            "Valid orchestration outcomes include: recording an observation, updating the rollout plan, creating follow-up issues, opening a small cleanup PR that the parent clearly owns, or closing the umbrella.",
-            "If you create new blocking follow-up work, justify it against the original parent goal rather than optional polish.",
-            "Blocking follow-up children must block the parent goal they satisfy, not the other way around.",
-            "If you create new child issues, leave them in Backlog unless they are truly ready to start now.",
+            "Publish the orchestration outcome clearly: observation, follow-up issues, rollout update, closeout, or a small parent-owned cleanup PR.",
+            "Do not open an overlapping umbrella PR unless this parent owns unique direct work.",
         ].join("\n");
     }
     if (runType === "implementation") {
         return [
-            "## Publication Requirements",
+            "## Publish",
             "",
-            "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 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.",
+            "If this is code-delivery work, publish before stopping: commit, push the issue branch, and open or update the PR.",
+            "If the issue explicitly allows a non-PR outcome, complete that outcome clearly instead of inventing a PR.",
             "",
-            "## PR Body Contract",
-            "",
-            "When you open or update a PR, shape the body so a strict reviewer can decide in one pass.",
-            "",
-            "Title: imperative, ≤72 chars. Do not prefix with the issue key — the branch carries it.",
-            "",
-            "Body sections, in this order. Omit any that do not apply but keep the order:",
-            "",
-            "  ## Why — 1-3 sentences on the problem and motivation.",
-            "  ## What — ≤5 bullets naming the files or surfaces that change.",
-            "  ## Tradeoffs — one explicit tradeoff taken, or the single word \"None\".",
-            "  ## Risks — 1-3 things a strict reviewer would ask about. For each, either fix it before committing or explain why it is acceptable. This section is load-bearing; a strict reviewer reads it first.",
-            "",
-            "Do not restate the diff in prose. Quote the ambiguous fragment directly if the reader needs to see it.",
-            "Do not add a \"Verification\" or \"I ran these commands\" section; CI owns pass/fail and posts check runs the reviewer already sees.",
+            ...buildPrePushSelfReviewSection("new_pr"),
         ].join("\n");
     }
     return [
-        "## Publication Requirements",
+        "## Publish",
         "",
-        "Before finishing, publish the result to the existing PR branch.",
-        "If you changed files for this repair, commit them and push the same branch before stopping.",
+        "Restore and publish on the existing PR branch: commit and push the same branch.",
         "Do not open a new PR.",
-        "Do not stop with only local commits or uncommitted changes.",
+        "A PR-less stop is not a successful outcome for a repair run unless a genuine external blocker prevents any correct push.",
+        "",
+        ...buildPrePushSelfReviewSection("existing_pr"),
     ].join("\n");
 }
 function buildSections(issue, runType, repoPath, context, followUp = false) {
@@ -539,20 +484,13 @@ function buildSections(issue, runType, repoPath, context, followUp = false) {
     const sections = [
         { id: "header", content: buildPromptHeader(issue) },
     ];
-    const reactiveContext = buildReactiveContext(runType, issue, context, followUp);
-    if (followUp && reactiveContext) {
-        sections.push({ id: "follow-up-turn", content: reactiveContext });
-    }
+    const currentContext = buildCurrentContext(runType, issue, context, followUp);
     sections.push({ id: "task-objective", content: buildTaskObjective(issue) }, {
         id: "scope-discipline",
-        content: issueClass === "orchestration" ? buildOrchestrationScopeDiscipline(context) : buildScopeDiscipline(issue, context),
+        content: issueClass === "orchestration" ? buildOrchestrationConstraints(context) : buildConstraints(issue, context),
     });
-    const humanContext = buildHumanContext(context);
-    if (humanContext) {
-        sections.push({ id: "human-context", content: humanContext });
-    }
-    if (!followUp && reactiveContext) {
-        sections.push({ id: "reactive-context", content: reactiveContext });
+    if (currentContext) {
+        sections.push({ id: "reactive-context", content: currentContext });
     }
     const workflow = issueClass === "orchestration"
         ? buildOrchestrationWorkflowGuidance()

package/package.json

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