fix(delivery): support custom pull request bodies (#1012)

Fixes #1011.

## Summary
- add `--pr-body <template>` for run and finish, with deterministic
issue tokens
- persist the unrendered body through detached and resumed runs
- correct resumed issue-number lookup and suppress unknown/N/A
references
- shell-quote custom bodies and legacy finish metadata across GitHub,
GitLab, and Azure DevOps

## Validation
- 63 focused tests pass
- lint passes with repository baseline warnings only
- full TypeScript typecheck passes
- introduced-change Opcore validation passes
- Opcore Zero reports no introduced cycles, duplicates, interface
findings, or documentation requirements

A local full-suite attempt was stopped after the shared tmpfs filled and
cascaded into ENOSPC failures; required GitHub CI is the authoritative
clean full-suite run.

Author: tomdps

AGENTS.md

@@ -86,6 +86,7 @@ Destructive commands (need permission): `zeroshot kill`, `zeroshot clear`, `zero
 | Hosted capsule image                  | `docker/zeroshot-oecp/`, `scripts/hosted-oecp-image.js`                                                                          |
 | Docker mounts/env                     | `lib/docker-config.js`                                                                                                           |
 | Container lifecycle                   | `src/isolation-manager.js`                                                                                                       |
+| Pull-request body templates           | `src/pr-body-template.js`, `src/agents/git-pusher-template.js`                                                                   |
 | Settings                              | `lib/settings.js`                                                                                                                |
 | Legacy settings property selection    | `src/repo-settings-access.ts`                                                                                                    |
 | Cluster wire/domain types             | `crates/openengine-cluster-protocol/`                                                                                            |

README.md

@@ -106,6 +106,7 @@ zeroshot run <input>             # issue, URL, markdown file, or inline text
 zeroshot run 123 --docker        # container isolation
 zeroshot run 123 --pr            # worktree + pull request
 zeroshot run 123 --ship          # worktree + PR + merge after approval
+zeroshot run 123 --pr --pr-body $'## Summary\n\nCustom text\n\n{{issue_reference}}'
 zeroshot run 123 -d              # background run
 
 zeroshot list                    # tasks and clusters (--json)
@@ -120,6 +121,11 @@ zeroshot settings                # effective settings
 zeroshot agents list             # available agents
 ```
 
+`--pr-body` supplies a deterministic pull-request body for `--pr` and `--ship` runs. The
+template supports `{{issue_number}}`, `{{issue_title}}`, and `{{issue_reference}}`; all three
+expand to empty text for tasks without an issue, so manual runs never emit `Closes #unknown`.
+The unrendered template is retained for detached and resumed runs.
+
 </details>
 
 <details>

cli/index.js

@@ -107,6 +107,8 @@ const {
   runLegacyUpdateIfRequested,
 } = require('./lib/update-checker');
 const { checkBinDirOnPath, printPathWarning } = require('../lib/path-check');
+const { quoteShellArgument } = require('../lib/git-remote-utils');
+const { renderPullRequestBody, resolveIssueContext } = require('../src/pr-body-template');
 const { StatusFooter, AGENT_STATE, ACTIVE_STATES } = require('../src/status-footer');
 const { EVENT_COPY, formatMergeStatus } = require('./event-copy');
 
@@ -2012,9 +2014,25 @@ function buildContextSummary({
   return contextSummary;
 }
 
-function buildCompletionPrompt({ contextSummary, taskText, issueNumber, issueTitle }) {
-  const mergeGoal = 'CREATE PR AND MERGE IT';
-  const mergeStep = `
+function buildDefaultFinishPrBody({ taskText, issueNumber, issueTitle }) {
+  const issueReference = renderPullRequestBody(undefined, { issueNumber, issueTitle });
+  return [
+    issueReference,
+    issueReference ? '' : null,
+    '## Summary',
+    `${String(taskText || 'Unknown task').slice(0, 200)}...`,
+    '',
+    '## Changes',
+    '- Implementation complete',
+    '- All validations addressed',
+    '',
+    '🤖 Generated with zeroshot finish',
+  ]
+    .filter((line) => line !== null)
+    .join('\n');
+}
+
+const FINISH_MERGE_STEP = `
 8. MERGE THE PR - THIS IS MANDATORY:
    \`\`\`bash
    gh pr merge --merge --auto
@@ -2029,7 +2047,29 @@ function buildCompletionPrompt({ contextSummary, taskText, issueNumber, issueTit
 
    REPEAT UNTIL MERGED. DO NOT GIVE UP.`;
 
-  return `# YOUR MISSION: ${mergeGoal}
+function buildFinishCommandArguments({ taskText, issueNumber, issueTitle, prBody }) {
+  const issueContext = resolveIssueContext({ issueNumber, issueTitle });
+  const resolvedTitle = issueContext.issueTitle;
+  const resolvedBody =
+    typeof prBody === 'string'
+      ? renderPullRequestBody(prBody, { issueNumber, issueTitle: resolvedTitle })
+      : buildDefaultFinishPrBody({ taskText, issueNumber, issueTitle: resolvedTitle });
+  return {
+    commitMessage: quoteShellArgument(resolvedTitle || 'feat: implement task'),
+    branch: quoteShellArgument(
+      issueContext.issueNumber !== 'unknown'
+        ? `issue-${issueContext.issueNumber}`
+        : 'feature/implementation'
+    ),
+    prTitle: quoteShellArgument(resolvedTitle),
+    prBody: quoteShellArgument(resolvedBody),
+  };
+}
+
+function buildCompletionPrompt({ contextSummary, taskText, issueNumber, issueTitle, prBody }) {
+  const args = buildFinishCommandArguments({ taskText, issueNumber, issueTitle, prBody });
+
+  return `# YOUR MISSION: CREATE PR AND MERGE IT
 
 ${contextSummary}
 
@@ -2050,12 +2090,12 @@ You are the FINISHER. Your ONLY job is to take this cluster's work and push it a
 2. COMMIT ALL CHANGES - Stage and commit everything:
    \`\`\`bash
    git add .
-   git commit -m "${issueTitle || 'feat: implement task'}"
+   git commit -m ${args.commitMessage}
    \`\`\`
 
 3. CREATE BRANCH - Use issue number if available:
    \`\`\`bash
-   ${issueNumber ? `git checkout -b issue-${issueNumber}` : 'git checkout -b feature/implementation'}
+   git checkout -b ${args.branch}
    \`\`\`
 
 4. PUSH TO REMOTE:
@@ -2065,16 +2105,7 @@ You are the FINISHER. Your ONLY job is to take this cluster's work and push it a
 
 5. CREATE PULL REQUEST:
    \`\`\`bash
-   gh pr create --title "${issueTitle || 'Implementation'}" --body "Closes #${issueNumber || 'N/A'}
-
-## Summary
-${taskText.slice(0, 200)}...
-
-## Changes
-- Implementation complete
-- All validations addressed
-
-🤖 Generated with zeroshot finish"
+   gh pr create --title ${args.prTitle} --body ${args.prBody}
    \`\`\`
 
 6. GET PR URL:
@@ -2083,7 +2114,7 @@ ${taskText.slice(0, 200)}...
    \`\`\`
 
 7. OUTPUT THE PR URL - Print it clearly so user can see it
-${mergeStep}
+${FINISH_MERGE_STEP}
 
 ## RULES
 
@@ -2707,6 +2738,10 @@ program
     'Full automation: worktree isolation + PR + auto-merge (use --docker for Docker)'
   )
   .option('--pr-base <branch>', 'Target branch for PRs (default: repo default branch)')
+  .option(
+    '--pr-body <template>',
+    'PR body template; supports {{issue_number}}, {{issue_title}}, and {{issue_reference}}'
+  )
   .option('--merge-queue', 'Use GitHub merge queue instead of direct merge')
   .option(
     '--close-issue <mode>',
@@ -3714,6 +3749,10 @@ program
   .helpGroup('Control:')
   .description('Take existing cluster and create completion-focused task (creates PR and merges)')
   .option('-y, --yes', 'Skip confirmation if cluster is running')
+  .option(
+    '--pr-body <template>',
+    'PR body template; supports {{issue_number}}, {{issue_title}}, and {{issue_reference}}'
+  )
   .action(async (id, options) => {
     try {
       const orchestrator = await getOrchestrator();
@@ -3732,6 +3771,7 @@ program
         taskText: context.taskText,
         issueNumber: context.issueNumber,
         issueTitle: context.issueTitle,
+        prBody: options.prBody ?? cluster.prOptions?.prBody,
       });
       printCompletionPromptPreview(completionPrompt);
 
@@ -6190,6 +6230,9 @@ module.exports = {
   isStartupUpdateEligible,
   handleNoArgumentInvocation,
   shouldRunInitialSetup,
+  extractFinishContext,
+  buildDefaultFinishPrBody,
+  buildCompletionPrompt,
   resolveRunMode,
   killRunningClusters,
 };

src/agents/git-pusher-template.js

@@ -277,6 +277,7 @@ return hasSufficientEvidence;`;
 const { readRepoSettings } = require('../../lib/repo-settings');
 const { normalizeGitRemoteName, quoteShellArgument } = require('../../lib/git-remote-utils');
 const { resolveRequiredQualityGates } = require('../quality-gates');
+const { renderPullRequestBody, resolveIssueContext } = require('../pr-body-template');
 
 function getSafeBranchName(value) {
   if (typeof value !== 'string') {
@@ -314,35 +315,6 @@ function normalizeCloseIssueMode(value) {
   return null;
 }
 
-function normalizeIssueNumber(value) {
-  const candidate = typeof value === 'number' ? String(value) : value;
-  if (typeof candidate !== 'string') return 'unknown';
-  const trimmed = candidate.trim();
-  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) ? trimmed : 'unknown';
-}
-
-function normalizeIssueTitle(value) {
-  if (typeof value !== 'string' || value.trim() === '') return 'Implementation';
-  const normalized = [...value]
-    .map((character) => {
-      const codePoint = character.codePointAt(0);
-      return codePoint < 0x20 || codePoint === 0x7f ? ' ' : character;
-    })
-    .join('')
-    .trim();
-  return normalized || 'Implementation';
-}
-
-function resolveIssueContext(options) {
-  const issueNumber = normalizeIssueNumber(options.issueNumber);
-  const issueTitle = normalizeIssueTitle(options.issueTitle);
-  const issueReference =
-    options.includeIssueReference === false || issueNumber === 'unknown'
-      ? ''
-      : `Closes #${issueNumber}`;
-  return { issueNumber, issueTitle, issueReference };
-}
-
 /**
  * Resolve GitHub configuration from CLI options and repo settings.
  * Priority: CLI options > repo settings (.zeroshot/settings.json) > defaults
@@ -355,6 +327,7 @@ function resolveIssueContext(options) {
  * @param {string|number} [options.issueNumber] - Typed issue identifier for prompt commands
  * @param {string} [options.issueTitle] - Typed issue title for prompt commands
  * @param {boolean} [options.includeIssueReference] - Include the closing reference in PR text
+ * @param {string} [options.prBody] - Literal PR body template with supported issue tokens
  * @returns {Object} Resolved configuration
  */
 function resolveGitHubConfig(options = {}) {
@@ -385,16 +358,23 @@ function resolveGitHubConfig(options = {}) {
     options.autoMerge === true ||
     (options.autoMerge !== false && parseBool(repoGithub.autoMerge) === true);
 
+  const issueContext = resolveIssueContext(options);
+
   return {
     prBase,
     useMergeQueue,
     closeIssueMode,
     autoMerge,
     gitRemote,
-    issueContext: resolveIssueContext(options),
+    issueContext,
+    prBody: renderPullRequestBody(options.prBody, options),
   };
 }
 
+function resolvedPrBody(config, issueContext) {
+  return typeof config.prBody === 'string' ? config.prBody : issueContext.issueReference;
+}
+
 /**
  * Generate platform-specific configuration based on resolved GitHub config.
  *
@@ -406,13 +386,15 @@ function getPlatformConfig(platform, config = {}) {
   const { prBase, useMergeQueue, closeIssueMode, autoMerge, gitRemote } = config;
   const issueContext = config.issueContext || resolveIssueContext({});
   const issueTitleArgument = quoteShellArgument(`feat: ${issueContext.issueTitle}`);
-  const issueReferenceArgument = quoteShellArgument(issueContext.issueReference);
+  const prBodyArgument = quoteShellArgument(resolvedPrBody(config, issueContext));
 
   const PLATFORM_CONFIGS = {
     github: {
       prName: 'PR',
       prNameLower: 'pull request',
-      createCmd: `gh pr create${prBase ? ` --base ${prBase}` : ''} --title ${issueTitleArgument} --body ${issueReferenceArgument}`,
+      createCmd:
+        `gh pr create${prBase ? ` --base ${prBase}` : ''} ` +
+        `--title ${issueTitleArgument} --body ${prBodyArgument}`,
       mergeCmd: useMergeQueue
         ? `PR_ID="$(timeout 30 gh pr view --json id --jq .id)"
 gh api graphql -f query='mutation($id:ID!){enqueuePullRequest(input:{pullRequestId:$id}){mergeQueueEntry{state}}}' -f id="$PR_ID"
@@ -434,7 +416,7 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
     gitlab: {
       prName: 'MR',
       prNameLower: 'merge request',
-      createCmd: `glab mr create --title ${issueTitleArgument} --description ${issueReferenceArgument}`,
+      createCmd: `glab mr create --title ${issueTitleArgument} --description ${prBodyArgument}`,
       mergeCmd: 'glab mr merge --auto-merge',
       mergeFallbackCmd: 'glab mr merge',
       prUrlExample: 'https://gitlab.com/owner/repo/-/merge_requests/123',
@@ -447,7 +429,7 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
     'azure-devops': {
       prName: 'PR',
       prNameLower: 'pull request',
-      createCmd: `az repos pr create --title ${issueTitleArgument} --description ${issueReferenceArgument}`,
+      createCmd: `az repos pr create --title ${issueTitleArgument} --description ${prBodyArgument}`,
       mergeCmd: 'az repos pr update --id <PR_ID> --auto-complete true',
       mergeFallbackCmd: 'az repos pr update --id <PR_ID> --status completed',
       prUrlExample: 'https://dev.azure.com/org/project/_git/repo/pullrequest/123',
@@ -803,6 +785,7 @@ If blocked before creating a ${prName}, output:
  * @param {string|number} [options.issueNumber] - Typed issue identifier for prompt commands
  * @param {string} [options.issueTitle] - Typed issue title for prompt commands
  * @param {boolean} [options.includeIssueReference] - Include the closing reference in PR text
+ * @param {string} [options.prBody] - Literal PR body template with supported issue tokens
  * @param {Array} [options.requiredQualityGates] - Required handoff quality gates
  * @param {boolean} [options.autoMerge] - Merge the PR (--ship). False stops after PR creation (--pr).
  * @returns {Object} Agent configuration object

src/legacy-lib/detached-startup.ts

@@ -26,6 +26,7 @@ interface RunOptions extends Record<string, unknown> {
   mergeQueue?: unknown;
   pr?: unknown;
   prBase?: unknown;
+  prBody?: unknown;
   ship?: unknown;
   worktree?: unknown;
 }
@@ -236,9 +237,10 @@ async function registerDetachedSetupCluster({
       setupStartedAt: Date.now(),
       setupStage: 'starting',
       autoPr: plan.delivery !== 'none',
-      prOptions: runOptions.prBase
+      prOptions: plan.delivery !== 'none'
         ? {
             prBase: runOptions.prBase,
+            prBody: typeof runOptions.prBody === 'string' ? runOptions.prBody : null,
             mergeQueue: runOptions.mergeQueue || false,
             closeIssue: runOptions.closeIssue || null,
             autoMerge: plan.autoMerge,

src/legacy-lib/start-cluster-environment.ts

@@ -10,6 +10,7 @@ interface RunOptions extends Record<string, unknown> {
   mount?: readonly string[] | null;
   noIsolation?: unknown;
   prBase?: unknown;
+  prBody?: unknown;
 }
 
 interface MountSpec {

src/legacy-lib/start-cluster-run-options.ts

@@ -28,6 +28,7 @@ interface RunOptions extends Record<string, unknown> {
   noMounts?: unknown;
   pr?: unknown;
   prBase?: unknown;
+  prBody?: unknown;
   preparedWorktree?: unknown;
   requiredQualityGates?: unknown;
   ship?: unknown;
@@ -201,6 +202,7 @@ function buildStartOptionsFromPlan({
     containerHome: optionalValue(options.containerHome),
     forceProvider: optionalValue(forceProvider),
     prBase: environment ? resolvePrBase(options) : optionalValue(options.prBase),
+    prBody: typeof options.prBody === 'string' ? options.prBody : undefined,
     mergeQueue: environment ? resolveMergeQueue(options) : optionalValue(options.mergeQueue),
     closeIssue: environment ? resolveCloseIssue(options) : optionalValue(options.closeIssue),
     ship: plan.delivery === 'ship',

src/orchestrator.js

@@ -262,6 +262,7 @@ function buildPrOptions(options, requiredQualityGates) {
     prBase: options.prBase || null,
     mergeQueue: options.mergeQueue || false,
     closeIssue: options.closeIssue || null,
+    prBody: typeof options.prBody === 'string' ? options.prBody : null,
     gitRemote: options.gitRemote || null,
     autoMerge,
     ...(requiredQualityGates.length > 0 ? { requiredQualityGates } : {}),
@@ -2038,6 +2039,7 @@ class Orchestrator {
       prBase: options.prBase,
       mergeQueue: options.mergeQueue,
       closeIssue: options.closeIssue,
+      prBody: options.prBody,
       requiredQualityGates: options.requiredQualityGates,
       autoMerge: resolveRunPlan(options).autoMerge,
       gitRemote: gitContext?.remote || options.gitRemote,
@@ -4225,7 +4227,7 @@ Continue from where you left off. Review your previous output to understand what
 
       // Get issue context from ledger
       const issueMsg = cluster.messageBus.ledger.findLast({ topic: 'ISSUE_OPENED' });
-      const issueNumber = issueMsg?.content?.data?.number || 'unknown';
+      const issueNumber = issueMsg?.content?.data?.issue_number || 'unknown';
       const issueTitle = issueMsg?.content?.data?.title || 'Implementation';
 
       // Generate the final prompt in one typed assembly pass. Issue values are