chore(bot): use template for generated PRs (#2585)

* chore(bot): use template for generated PRs

* fix(bot): tolerate PR template wording changes

Author: ascorbic

infra/emdash-bot/.flue/agents/investigate.ts

@@ -114,6 +114,11 @@ const screenshotSchema = v.object({
 	description: v.optional(v.string()),
 });
 
+const pullRequestSchema = v.object({
+	title: v.pipe(v.string(), v.minLength(1), v.maxLength(256)),
+	description: v.pipe(v.string(), v.minLength(10), v.maxLength(RESULT_SUMMARY_LIMIT)),
+});
+
 const resultSchema = v.pipe(
 	v.object({
 		skipped: v.optional(v.boolean()),
@@ -137,6 +142,7 @@ const resultSchema = v.pipe(
 		fixed: v.optional(v.boolean()),
 		verdict: v.optional(v.picklist(["bug", "intended-behavior", "unclear"])),
 		summary: v.pipe(v.string(), v.minLength(10), v.maxLength(RESULT_SUMMARY_LIMIT)),
+		pullRequest: v.optional(pullRequestSchema),
 		failureStage: v.optional(v.picklist(["workspace", "verification", "publication", "reporting"])),
 		/** Reproduction screenshots pushed to bot/artifacts-<n>, rendered in the ask comment. */
 		screenshots: v.optional(v.array(screenshotSchema)),
@@ -147,15 +153,26 @@ const resultSchema = v.pipe(
 			(result.demonstration !== "none" && result.demonstratedReportedIssue === true),
 		"reproduced=true requires demonstration != 'none' and demonstratedReportedIssue=true. If you demonstrated something other than the reported issue, or nothing, set reproduced=false and describe the finding in summary.",
 	),
+	v.check(
+		(result) => result.fixed !== true || result.pullRequest !== undefined,
+		"fixed=true requires pullRequest with a reviewer-facing title and description.",
+	),
 );
 
-const implementationResultSchema = v.object({
-	skipped: v.optional(v.boolean()),
-	implemented: v.boolean(),
-	summary: v.pipe(v.string(), v.minLength(10), v.maxLength(RESULT_SUMMARY_LIMIT)),
-	failureStage: v.optional(v.picklist(["workspace", "verification", "publication", "reporting"])),
-	screenshots: v.optional(v.array(screenshotSchema)),
-});
+const implementationResultSchema = v.pipe(
+	v.object({
+		skipped: v.optional(v.boolean()),
+		implemented: v.boolean(),
+		summary: v.pipe(v.string(), v.minLength(10), v.maxLength(RESULT_SUMMARY_LIMIT)),
+		pullRequest: v.optional(pullRequestSchema),
+		failureStage: v.optional(v.picklist(["workspace", "verification", "publication", "reporting"])),
+		screenshots: v.optional(v.array(screenshotSchema)),
+	}),
+	v.check(
+		(result) => result.implemented !== true || result.pullRequest !== undefined,
+		"implemented=true requires pullRequest with a reviewer-facing title and description.",
+	),
+);
 
 const publicationSchema = v.object({
 	branch: v.string(),
@@ -468,7 +485,7 @@ export function Investigate({ id }: AgentProps) {
 			defineTool({
 				name: "report_implementation",
 				description:
-					"Report the implementation outcome. Set implemented=true only after publish_candidate succeeds. Include the commands run and any verification failures in the summary.",
+					"Report the implementation outcome. Set implemented=true only after publish_candidate succeeds. Include the commands run and any verification failures in the summary. When implemented=true, provide pullRequest with a concise reviewer-facing title and description.",
 				input: implementationResultSchema,
 				output: reportedResultSchema,
 				durable: true,
@@ -505,7 +522,7 @@ export function Investigate({ id }: AgentProps) {
 			defineTool({
 				name: "report_result",
 				description:
-					"Report the final structured investigation result to the issue orchestrator. reproduced=true means you demonstrated the defect the reporter described, in this checkout. The demonstration does NOT need to copy their exact steps: a failing unit test that exercises the same defect a UI report describes is a full reproduction of the issue -- report it as one, without hedging. It must be the same defect, though: an adjacent or latent bug you demonstrated, an out-of-repo infrastructure symptom, or a root cause from reading code alone is not a reproduction. Three distinct non-reproduced outcomes -- pick the honest one: rootCauseFound=true when you identified the reporter's defect but could not confirm it with a demonstration (environment limits, browser-only path) -- this is a first-class 'diagnosed' verdict; plain reproduced=false when you investigated and found nothing wrong or a different/adjacent issue (describe findings in summary); verdict='unclear' when the issue lacks the information an attempt would need -- say what is missing. Fill demonstration and demonstratedReportedIssue truthfully. If demonstration attempts are not converging after a couple of angles, stop and report the diagnosis with rootCauseFound rather than grinding.",
+					"Report the final structured investigation result to the issue orchestrator. reproduced=true means you demonstrated the defect the reporter described, in this checkout. The demonstration does NOT need to copy their exact steps: a failing unit test that exercises the same defect a UI report describes is a full reproduction of the issue -- report it as one, without hedging. It must be the same defect, though: an adjacent or latent bug you demonstrated, an out-of-repo infrastructure symptom, or a root cause from reading code alone is not a reproduction. Three distinct non-reproduced outcomes -- pick the honest one: rootCauseFound=true when you identified the reporter's defect but could not confirm it with a demonstration (environment limits, browser-only path) -- this is a first-class 'diagnosed' verdict; plain reproduced=false when you investigated and found nothing wrong or a different/adjacent issue (describe findings in summary); verdict='unclear' when the issue lacks the information an attempt would need -- say what is missing. Fill demonstration and demonstratedReportedIssue truthfully. If demonstration attempts are not converging after a couple of angles, stop and report the diagnosis with rootCauseFound rather than grinding. When fixed=true, provide pullRequest with a concise reviewer-facing title and description.",
 				input: resultSchema,
 				output: reportedResultSchema,
 				durable: true,

infra/emdash-bot/.flue/lib/comments.ts

@@ -1,3 +1,4 @@
+import pullRequestTemplate from "../../../../.github/PULL_REQUEST_TEMPLATE.md?raw";
 import type { Kind, StateId } from "./machine.js";
 import {
 	artifactsBranch,
@@ -188,24 +189,65 @@ export function renderPreviewReadyAsk(input: {
 		.join("\n");
 }
 
+export interface PullRequestCopy {
+	readonly title: string;
+	readonly description: string;
+}
+
+const TYPE_SECTION_HEADING_RE = /^## Type of change\b/im;
+const BUG_FIX_CHECKBOX_RE = /^- \[ ] Bug fix\b(.*)$/im;
+const FEATURE_CHECKBOX_RE = /^- \[ ] Feature\b(.*)$/im;
+const AI_DISCLOSURE_CHECKBOX_RE = /^- \[ ] This PR includes AI-generated code\b.*$/im;
+
+export function fillPullRequestTemplate(template: string, kind: Kind): string {
+	const typeSectionStart = template.search(TYPE_SECTION_HEADING_RE);
+	if (typeSectionStart === -1) throw new Error("pull request template is missing its type section");
+	const typeCheckbox = kind === "bug" ? BUG_FIX_CHECKBOX_RE : FEATURE_CHECKBOX_RE;
+	const typeLabel = kind === "bug" ? "Bug fix" : "Feature";
+	const templateBody = template.slice(typeSectionStart);
+	if (!typeCheckbox.test(templateBody)) {
+		throw new Error(`pull request template is missing its ${typeLabel} checkbox`);
+	}
+	if (!AI_DISCLOSURE_CHECKBOX_RE.test(templateBody)) {
+		throw new Error("pull request template is missing its AI disclosure checkbox");
+	}
+	return templateBody
+		.replace(typeCheckbox, `- [x] ${typeLabel}$1`)
+		.replace(
+			AI_DISCLOSURE_CHECKBOX_RE,
+			"- [x] This PR includes AI-generated code — model/tool: emdashbot + Kimi K2.7 Code",
+		)
+		.trim();
+}
+
 /**
  * Body for the draft PR opened when the reporter confirms the change. References
  * the issue (so merging closes it), points at the preview the reporter just
- * verified, and flags that a maintainer must review before merge.
+ * verified, and fills the repository's pull request template.
  */
-export function renderDraftPrBody(issueNumber: number, previewPackage?: string): string {
+export function renderDraftPrBody(input: {
+	issueNumber: number;
+	kind: Kind;
+	description: string;
+	previewPackage?: string;
+}): string {
+	const completedTemplate = fillPullRequestTemplate(pullRequestTemplate, input.kind);
 	return [
-		`Closes #${issueNumber}.`,
+		"## What does this PR do?",
+		"",
+		input.description.trim(),
+		"",
+		`Closes #${input.issueNumber}.`,
 		"",
 		"A candidate change the reporter confirmed against their own site via the preview build:",
 		"",
 		"```bash",
-		previewInstallCommand(issueNumber, previewPackage),
+		previewInstallCommand(input.issueNumber, input.previewPackage),
 		"```",
 		"",
-		"Review the candidate diff and its verification before merging.",
-		"",
 		"<sub>Opened automatically by emdashbot as a draft. A maintainer must review before merge.</sub>",
+		"",
+		completedTemplate,
 	].join("\n");
 }
 

infra/emdash-bot/.flue/lib/orchestrator.ts

@@ -10,6 +10,7 @@ import { DurableObject } from "cloudflare:workers";
 import { Investigate } from "../agents/investigate.js";
 import { classifyComment, type ClassifierInput, type ClassifyResult } from "./classifier-client.js";
 import {
+	type PullRequestCopy,
 	type PreviewScreenshot,
 	renderAgentComment,
 	renderDraftPrBody,
@@ -164,6 +165,8 @@ export interface NormalizedEvent {
 	readonly agentFailureStage?: string;
 	/** Reproduction screenshots the fix run pushed, carried into the ask comment. */
 	readonly agentScreenshots?: readonly PreviewScreenshot[];
+	/** Reviewer-facing copy carried through preview confirmation into the draft PR. */
+	readonly agentPullRequest?: PullRequestCopy;
 	/**
 	 * Precomposed comment body that replaces the default `renderComment` output
 	 * for this transition. Used for the preview-ready ask, whose body needs data
@@ -194,6 +197,7 @@ export interface AgentResult {
 	readonly implemented?: boolean;
 	readonly verdict?: string;
 	readonly summary?: string;
+	readonly pullRequest?: PullRequestCopy;
 	readonly failureStage?: string;
 	readonly screenshots?: readonly PreviewScreenshot[];
 	readonly [key: string]: unknown;
@@ -288,6 +292,7 @@ const STORAGE = {
 	previewPollNextAt: "o:previewPollNextAt",
 	previewNotes: "o:previewNotes",
 	previewScreenshots: "o:previewScreenshots",
+	candidatePullRequest: "o:candidatePullRequest",
 	lastDiagnosis: "o:lastDiagnosis",
 	deadlineWarningSentRunId: "o:deadlineWarningSentRunId",
 	deadlineWarningRetryAt: "o:deadlineWarningRetryAt",
@@ -315,6 +320,16 @@ const INBOX_BATCH_LIMIT = 10;
 const CLASSIFIER_MAX_ATTEMPTS = 3;
 const CLASSIFIER_TEXT_LIMIT = 16_000;
 
+function normalizePullRequestCopy(value: unknown): PullRequestCopy | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const { title, description } = value as { title?: unknown; description?: unknown };
+	if (typeof title !== "string" || typeof description !== "string") return undefined;
+	const normalizedTitle = title.trim().replaceAll(/\s+/g, " ");
+	const normalizedDescription = description.trim();
+	if (!normalizedTitle || !normalizedDescription) return undefined;
+	return { title: normalizedTitle, description: normalizedDescription };
+}
+
 interface CachedToken {
 	token: string;
 	/** Unix ms; tokens are valid ~1h, we expire 5m early. */
@@ -1025,6 +1040,7 @@ export class OrchestratorDO extends DurableObject<Env> {
 		const labels = await this.projectLabels();
 		const agentSummary =
 			typeof input.result?.summary === "string" ? input.result.summary : undefined;
+		const agentPullRequest = normalizePullRequestCopy(input.result.pullRequest);
 		const runStatus: Exclude<WorkCommentStatus, "running"> =
 			event === "agent.failed"
 				? input.result.failureStage === "timeout"
@@ -1054,6 +1070,7 @@ export class OrchestratorDO extends DurableObject<Env> {
 			settlesRunId: input.runId,
 			agentRunId: input.runId,
 			...(agentSummary ? { agentSummary } : {}),
+			...(agentPullRequest ? { agentPullRequest } : {}),
 			...(finalizedWorkComment ? { commentBodyOverride: "" } : {}),
 			...(failureStage ? { agentFailureStage: failureStage } : {}),
 			...(agentScreenshots ? { agentScreenshots } : {}),
@@ -2145,15 +2162,25 @@ export class OrchestratorDO extends DurableObject<Env> {
 		const token = await this.getInstallationToken(creds);
 		const headBranch = `bot/fix-${anchorNumber}`;
 		const kind = (await this.ctx.storage.get<Kind>(STORAGE.kind)) ?? "bug";
+		const pullRequestCopy = draft
+			? await this.ctx.storage.get<PullRequestCopy>(STORAGE.candidatePullRequest)
+			: undefined;
 		try {
 			const created =
 				(await getOpenPullRequest(token, repo, headBranch)) ??
 				(await createPullRequest(token, repo, {
 					headBranch,
 					baseBranch: "main",
-					title: renderPullRequestTitle(anchorNumber, kind),
+					title: pullRequestCopy?.title || renderPullRequestTitle(anchorNumber, kind),
 					body: draft
-						? renderDraftPrBody(anchorNumber, this.env.PREVIEW_PACKAGE)
+						? renderDraftPrBody({
+								issueNumber: anchorNumber,
+								kind,
+								description:
+									pullRequestCopy?.description ||
+									`Automated candidate change for issue #${anchorNumber}.`,
+								previewPackage: this.env.PREVIEW_PACKAGE,
+							})
 						: `Fixes #${anchorNumber}.\n\nAutomated PR opened by emdashbot.`,
 					draft,
 				}));
@@ -2487,13 +2514,23 @@ export class OrchestratorDO extends DurableObject<Env> {
 					input.agentScreenshots?.length
 						? transaction.put(STORAGE.previewScreenshots, input.agentScreenshots)
 						: transaction.delete(STORAGE.previewScreenshots),
+					transaction.put<PullRequestCopy>(
+						STORAGE.candidatePullRequest,
+						input.agentPullRequest ?? {
+							title: "",
+							description: input.agentSummary ?? "",
+						},
+					),
 				);
 			} else {
 				puts.push(
 					transaction.delete(STORAGE.previewBuildDeadline),
 					transaction.delete(STORAGE.previewPollNextAt),
 					transaction.delete(STORAGE.previewNotes),
 					transaction.delete(STORAGE.previewScreenshots),
+					...(decision.to === "awaiting_reporter"
+						? []
+						: [transaction.delete(STORAGE.candidatePullRequest)]),
 				);
 			}
 			const kindLabel = decision.addLabels.find(

infra/emdash-bot/tests/integration/orchestrator.test.ts

@@ -1508,7 +1508,7 @@ describe("OrchestratorDO (workers-pool)", () => {
 		expect(await stub.getPendingSideEffectCount()).toBe(1);
 	});
 
-	test("draft PR titles distinguish bug fixes from directed implementations", async () => {
+	test("draft PRs use agent-authored copy with a legacy fallback", async () => {
 		const pullRequests: unknown[] = [];
 		let pullNumber = 100;
 		testEnv.GITHUB_APP_PRIVATE_KEY = "test-key-present";
@@ -1540,22 +1540,56 @@ describe("OrchestratorDO (workers-pool)", () => {
 			},
 		);
 
-		for (const [anchorNumber, kind] of [
-			[42, "bug"],
-			[43, "enhancement"],
-		] as const) {
-			const stub = testEnv.Orchestrator.getByName(uniqueIssueName());
-			await stub.debugSetTokenCache("cached-token", Date.now() + 60 * 60 * 1000);
-			await stub.debugPrimePreviewBuilding(anchorNumber, "Candidate notes.", kind);
-			await stub.event(
-				makeEvent({ event: "preview.ready", arg: null, actor: "system", anchorNumber }),
-			);
-			await stub.event(makeEvent({ event: "confirm", arg: null, actor: "reporter", anchorNumber }));
-		}
+		const customCopyStub = testEnv.Orchestrator.getByName(uniqueIssueName());
+		await customCopyStub.debugSetTokenCache("cached-token", Date.now() + 60 * 60 * 1000);
+		await customCopyStub.debugPrimeFixing(42);
+		await customCopyStub.debugSetStaleRun(
+			"implement-run",
+			Date.now(),
+			"investigate-42-implement-run",
+			"implement",
+		);
+		await customCopyStub.applyAgentResult({
+			runId: "implement-run",
+			result: {
+				implemented: true,
+				summary: "Keeps the selected locale when loading content.",
+				pullRequest: {
+					title: "fix(core): preserve the requested locale",
+					description: "Keeps the selected locale when loading content.",
+				},
+			},
+			pushed: true,
+			ok: true,
+		});
+		await customCopyStub.event(
+			makeEvent({ event: "preview.ready", arg: null, actor: "system", anchorNumber: 42 }),
+		);
+		await customCopyStub.event(
+			makeEvent({ event: "confirm", arg: null, actor: "reporter", anchorNumber: 42 }),
+		);
+
+		const legacyStub = testEnv.Orchestrator.getByName(uniqueIssueName());
+		await legacyStub.debugSetTokenCache("cached-token", Date.now() + 60 * 60 * 1000);
+		await legacyStub.debugPrimePreviewBuilding(43, "Candidate notes.", "enhancement");
+		await legacyStub.event(
+			makeEvent({ event: "preview.ready", arg: null, actor: "system", anchorNumber: 43 }),
+		);
+		await legacyStub.event(
+			makeEvent({ event: "confirm", arg: null, actor: "reporter", anchorNumber: 43 }),
+		);
 
 		expect(pullRequests).toMatchObject([
-			{ title: "Fix #42", draft: true },
-			{ title: "Implement #43", draft: true },
+			{
+				title: "fix(core): preserve the requested locale",
+				body: expect.stringContaining("Keeps the selected locale when loading content."),
+				draft: true,
+			},
+			{
+				title: "Implement #43",
+				body: expect.stringContaining("## What does this PR do?"),
+				draft: true,
+			},
 		]);
 	});