muonroi-cli 1.8.4 → 1.9.0

package/dist/src/lsp/manager.js

@@ -1,16 +1,26 @@
 import { readFile } from "fs/promises";
 import path from "path";
-import { pathToFileURL } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import { createRuntimeLspDefinitions } from "./builtins.js";
 import { createLspClientSession } from "./client.js";
 export function createWorkspaceLspManager(cwd, settings, options = {}) {
     const definitions = createRuntimeLspDefinitions(cwd, settings);
     const clients = new Map();
+    // Servers we have already reported as not installed. Without this the "no
+    // command" path is silent: a Go/Rust/C++/Java file just gets no LSP and the
+    // caller sees "unavailable" with no way to learn WHICH server is missing.
+    const reportedMissing = new Set();
     const createClient = options.createClient ??
         (async ({ serverId, root, definition, settings: normalizedSettings }) => {
             const launch = await definition.resolveLaunch(root, normalizedSettings);
-            if (!launch?.command)
+            if (!launch?.command) {
+                if (!reportedMissing.has(serverId)) {
+                    reportedMissing.add(serverId);
+                    console.error(`[lsp] no language server found for "${serverId}" (${definition.extensions.join(", ")}). ` +
+                        `Install it and make sure it is on PATH, or set lsp.builtins.${serverId}.command in settings.`);
+                }
                 return null;
+            }
             return createLspClientSession({
                 serverId,
                 root,
@@ -96,7 +106,10 @@ export function createWorkspaceLspManager(cwd, settings, options = {}) {
                     diagnostics: client.getDiagnostics(filePath),
                 };
             }
-            catch {
+            catch (err) {
+                // Dropping the client silently here is what let a dead language server
+                // look like "no diagnostics" for the whole session.
+                console.error(`[lsp:${definition.id}] sync failed for ${filePath}, dropping client: ${err instanceof Error ? err.message : String(err)}`);
                 clients.delete(key);
                 return null;
             }
@@ -167,11 +180,238 @@ export function createWorkspaceLspManager(cwd, settings, options = {}) {
         await Promise.allSettled(active.map((entry) => entry.client.stop()));
         clients.clear();
     }
+    // ── Sprint 1: impact/readiness contract (SLICE1-BUILD-NOTE.md) ─────────────
+    const TOKEN_BUDGET_CAP = 500; // hard cap (spec §49-54)
+    const REF_TOKEN_COST = 30; // per-reference estimate (spec §53)
+    const MAX_REFS = Math.floor(TOKEN_BUDGET_CAP / REF_TOKEN_COST); // 16 — truncation threshold
+    /** Error-level = severity ≤ 1 (Error). Warnings/infos ignored (spec §21-25). */
+    function errorLevel(diags) {
+        return diags.filter((d) => (d.severity ?? 1) <= 1);
+    }
+    /** tokenBudgetUsed = elapsed estimate + refs×30, clamped ≤500 (spec §49-54). */
+    function tokenBudget(elapsedMs, refCount) {
+        const elapsedTokens = Math.min(200, Math.round(elapsedMs / 25));
+        return Math.min(TOKEN_BUDGET_CAP, elapsedTokens + refCount * REF_TOKEN_COST);
+    }
+    /** Top-2 distinct error messages joined "; ", ≤120 chars; "none" when clean (spec §42-47). */
+    function suggestedGuardFrom(errs) {
+        if (errs.length === 0)
+            return "none";
+        const seen = new Set();
+        const messages = [];
+        for (const d of errs) {
+            const cat = (d.source ?? d.code ?? d.message.split(/[:.]/)[0] ?? "error").toString().trim();
+            const key = `${cat}:${d.message.trim()}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            messages.push(d.message.trim());
+            if (messages.length === 2)
+                break;
+        }
+        return messages.join("; ").slice(0, 120) || "none";
+    }
+    /**
+     * didOpen `filePath` on every client that is about to be asked for its
+     * diagnostics, so the server actually analyses it. Returns true when the file
+     * cannot be read — nothing to diagnose, and reporting it "clean" would lie.
+     */
+    async function openForDiagnostics(filePath, records) {
+        let content;
+        try {
+            content = await readFile(filePath, "utf8");
+        }
+        catch (err) {
+            console.error(`[lsp] cannot read ${filePath} for diagnostics: ${err instanceof Error ? err.message : String(err)}`);
+            return true;
+        }
+        const extension = path.extname(filePath).toLowerCase();
+        await Promise.all(records.map(async ({ key, definition, client }) => {
+            const languageId = definition.languageIds[extension] ?? (extension.slice(1) || "plaintext");
+            try {
+                await client.openOrChangeFile(filePath, languageId, content);
+            }
+            catch (err) {
+                // Drop the client so the next call re-spawns it; the diagnostics wait
+                // below will surface this as a failure rather than a clean verdict.
+                console.error(`[lsp:${definition.id}] didOpen failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+                clients.delete(key);
+            }
+        }));
+        return false;
+    }
+    async function waitForDiagnostics(filePath, timeout) {
+        const clampedTimeout = Math.min(Math.max(timeout, 0), 5000);
+        const t0 = Date.now();
+        const records = await getClientsForFile(filePath);
+        if (records.length === 0) {
+            return {
+                diagnostics: [],
+                lspStatus: "unavailable",
+                clean: false,
+                metadata: { tokenBudgetUsed: tokenBudget(Date.now() - t0, 0) },
+            };
+        }
+        // A language server only publishes diagnostics for files it has been told
+        // about. Without this didOpen, waiting on a file the server has never seen
+        // waits out the full timeout, gets nothing, and reports lspStatus "ok" /
+        // clean: true — a green verdict on a file that was never analysed at all.
+        // (Proven: a file with two tsc type errors reported clean.) Callers that
+        // already synced the buffer (syncFile) are unaffected: openOrChangeFile is
+        // idempotent, and diagnostics already cached short-circuit the wait below.
+        const unreadable = await openForDiagnostics(filePath, records);
+        if (unreadable) {
+            return {
+                diagnostics: [],
+                lspStatus: "unavailable",
+                clean: false,
+                metadata: { tokenBudgetUsed: tokenBudget(Date.now() - t0, 0) },
+            };
+        }
+        let anyTimedOut = false;
+        let anyFailed = false;
+        const allDiagnostics = [];
+        for (const record of records) {
+            try {
+                const diags = await withRequestTimeout(record.client.waitForDiagnostics(filePath, clampedTimeout), clampedTimeout);
+                allDiagnostics.push(...diags);
+            }
+            catch (err) {
+                if (err instanceof LspRequestTimeoutError) {
+                    anyTimedOut = true;
+                    allDiagnostics.push(...record.client.getDiagnostics(filePath));
+                }
+                else {
+                    anyFailed = true;
+                }
+            }
+        }
+        const lspStatus = anyTimedOut
+            ? "partial"
+            : anyFailed && allDiagnostics.length === 0
+                ? "unavailable"
+                : "ok";
+        // clean: true only when we actually have data and zero error-level diags (spec §85).
+        const clean = lspStatus !== "unavailable" && errorLevel(allDiagnostics).length === 0;
+        return {
+            diagnostics: allDiagnostics,
+            lspStatus,
+            clean,
+            metadata: { tokenBudgetUsed: tokenBudget(Date.now() - t0, 0) },
+        };
+    }
+    async function impactOfChange(filePath, _query, timeout) {
+        const t0 = Date.now();
+        const diag = await waitForDiagnostics(filePath, timeout ?? 1500);
+        if (diag.lspStatus === "unavailable") {
+            const errs = errorLevel(diag.diagnostics);
+            return {
+                references: [],
+                diagnostics: diag.diagnostics,
+                referencesComplete: false,
+                safeToRename: false,
+                clean: false,
+                suggestedGuard: suggestedGuardFrom(errs),
+                degraded: "lsp_unavailable",
+                lspStatus: "unavailable",
+                metadata: { tokenBudgetUsed: tokenBudget(Date.now() - t0, 0) },
+            };
+        }
+        const records = await getClientsForFile(filePath);
+        const rawReferences = [];
+        for (const record of records) {
+            try {
+                const uri = pathToFileURL(path.resolve(filePath)).href;
+                const params = {
+                    textDocument: { uri },
+                    position: { line: 0, character: 0 },
+                    context: { includeDeclaration: true },
+                };
+                const refs = await record.client.sendRequest("textDocument/references", params);
+                if (Array.isArray(refs)) {
+                    for (const ref of refs) {
+                        const r = ref;
+                        if (r?.uri && r?.range) {
+                            rawReferences.push({
+                                uri: r.uri,
+                                range: {
+                                    start: { line: r.range.start.line + 1, character: r.range.start.character + 1 },
+                                    end: { line: r.range.end.line + 1, character: r.range.end.character + 1 },
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                // Individual reference query failure: continue with partial results
+            }
+        }
+        // Truncate so references×30 stays within budget headroom (spec §38, §53).
+        const truncated = rawReferences.length > MAX_REFS;
+        const references = truncated ? rawReferences.slice(0, MAX_REFS) : rawReferences;
+        const referencesComplete = !truncated;
+        // Frozen union: the symbol file's waited diagnostics + each unique referenced
+        // file's already-published diagnostics (cheap getDiagnostics, no extra waits).
+        // clean is computed over this union of error-level diagnostics (spec §19-25).
+        const unionDiags = [...diag.diagnostics];
+        const seenFiles = new Set([path.resolve(filePath)]);
+        for (const ref of references) {
+            let refPath;
+            try {
+                refPath = fileURLToPath(ref.uri);
+            }
+            catch {
+                continue;
+            }
+            if (seenFiles.has(refPath))
+                continue;
+            seenFiles.add(refPath);
+            for (const record of records)
+                unionDiags.push(...record.client.getDiagnostics(refPath));
+        }
+        const unionErrors = errorLevel(unionDiags);
+        const clean = unionErrors.length === 0;
+        // Precedence: lsp_unavailable (handled above) > diagnostics_timeout > refs_truncated > none.
+        const degraded = diag.lspStatus === "partial" ? "diagnostics_timeout" : truncated ? "refs_truncated" : "none";
+        // safeToRename only when refs are complete, the union is clean, and nothing degraded (spec §27-31).
+        const safeToRename = referencesComplete && clean && degraded === "none" && diag.lspStatus === "ok";
+        return {
+            references,
+            diagnostics: diag.diagnostics,
+            referencesComplete,
+            safeToRename,
+            clean,
+            suggestedGuard: suggestedGuardFrom(unionErrors),
+            degraded,
+            lspStatus: diag.lspStatus,
+            metadata: { tokenBudgetUsed: tokenBudget(Date.now() - t0, references.length) },
+        };
+    }
+    async function lspMutationPreview(_filePath, _change) {
+        // Fixed stub schema — no workspaceEdit, no apply path (spec §55-71).
+        return { op: "allowlist", dryRunResult: { proposedEdits: [], tokenEstimate: 0 }, schemaVersion: "1.0" };
+    }
+    async function lspBeforeGrep(filePath, query) {
+        const result = await impactOfChange(filePath, query);
+        // Policy keys on lspStatus: grep fallback allowed unless the LSP was fully ok (spec §73-77).
+        if (result.lspStatus !== "ok") {
+            return { kind: "allow", reason: `LSP ${result.lspStatus}; fall back to grep` };
+        }
+        if (result.safeToRename) {
+            return { kind: "allow", reason: "LSP ok and rename is safe" };
+        }
+        return { kind: "enrich", enrichWith: result };
+    }
     return {
         touchFile,
         syncFile,
         query,
         close,
+        waitForDiagnostics,
+        impactOfChange,
+        lspMutationPreview,
+        lspBeforeGrep,
     };
 }
 class LspRequestTimeoutError extends Error {
@@ -211,6 +451,8 @@ function getOperationMethod(operation) {
         case "incomingCalls":
         case "outgoingCalls":
             return "textDocument/prepareCallHierarchy";
+        case "waitForDiagnostics":
+            return "textDocument/diagnostic";
     }
 }
 function createOperationParams(input, absolutePath) {
@@ -244,6 +486,10 @@ function createOperationParams(input, absolutePath) {
             return {
                 query: input.query ?? "",
             };
+        case "waitForDiagnostics":
+            return {
+                textDocument: { uri },
+            };
     }
 }
 export function summarizeLspDiagnostics(diagnostics) {

package/dist/src/lsp/npm-cache.d.ts

@@ -1,2 +1,12 @@
-export declare function lspNpmWhich(pkg: string): Promise<string | null>;
+/**
+ * Absolute path to a language-server binary in the cache, installing the package
+ * on first use.
+ *
+ * `preferredBin` is the binary the CALLER needs, which is not always the one
+ * named after the package: `pyright` ships both `pyright` (the batch CLI) and
+ * `pyright-langserver` (the LSP server). Choosing by package name alone launched
+ * the CLI with `--stdio`, which exits 4 with "pyright --help for usage" — so
+ * Python LSP never started for anyone relying on auto-install.
+ */
+export declare function lspNpmWhich(pkg: string, preferredBin?: string): Promise<string | null>;
 export declare function lspNpmAdd(pkg: string): Promise<string>;

package/dist/src/lsp/npm-cache.js

@@ -10,13 +10,27 @@ function packageDir(pkg) {
         : pkg;
     return path.join(CACHE_ROOT, sanitized);
 }
-export async function lspNpmWhich(pkg) {
+/**
+ * Absolute path to a language-server binary in the cache, installing the package
+ * on first use.
+ *
+ * `preferredBin` is the binary the CALLER needs, which is not always the one
+ * named after the package: `pyright` ships both `pyright` (the batch CLI) and
+ * `pyright-langserver` (the LSP server). Choosing by package name alone launched
+ * the CLI with `--stdio`, which exits 4 with "pyright --help for usage" — so
+ * Python LSP never started for anyone relying on auto-install.
+ */
+export async function lspNpmWhich(pkg, preferredBin) {
     const dir = packageDir(pkg);
     const binDir = path.join(dir, "node_modules", ".bin");
     const pick = async () => {
         const files = await readdir(binDir).catch(() => []);
         if (files.length === 0)
             return undefined;
+        // The caller's choice wins whenever the package actually ships it. Match the
+        // extension-less shim: Windows also lists .cmd/.ps1 wrappers for each bin.
+        if (preferredBin && files.includes(preferredBin))
+            return preferredBin;
         if (files.length === 1)
             return files[0];
         const pkgJsonPath = path.join(dir, "node_modules", pkg, "package.json");
@@ -29,6 +43,8 @@ export async function lspNpmWhich(pkg) {
             const keys = Object.keys(bin);
             if (keys.length === 1)
                 return keys[0];
+            if (preferredBin && bin[preferredBin])
+                return preferredBin;
             return bin[unscoped] ? unscoped : keys[0];
         }
         return files[0];

package/dist/src/lsp/runtime.d.ts

@@ -1,6 +1,11 @@
-import type { LspDiagnosticFile, LspQueryInput, LspToolResponse } from "./types.js";
+import { type WorkspaceLspManager } from "./manager.js";
+import type { ImpactOfChangeResult, LspDiagnosticFile, LspQueryInput, LspQueryResult, LspToolResponse, MutationPreviewResult } from "./types.js";
 export declare function queryLsp(cwd: string, input: LspQueryInput): Promise<LspToolResponse>;
+export declare function waitForDiagnosticsLsp(cwd: string, filePath: string, timeout?: number): Promise<LspQueryResult>;
+export declare function impactOfChangeLsp(cwd: string, filePath: string, query?: string): Promise<ImpactOfChangeResult>;
+export declare function lspMutationPreview(cwd: string, filePath: string, change: string): Promise<MutationPreviewResult>;
 export declare function syncFileWithLsp(cwd: string, filePath: string, content: string, save?: boolean, waitForDiagnostics?: boolean, diagnosticsTimeoutMs?: number): Promise<LspDiagnosticFile[]>;
 export declare function isLspToolEnabled(_cwd: string): boolean;
 export declare function summarizeDiagnostics(diagnostics: LspDiagnosticFile[]): string | null;
 export declare function shutdownWorkspaceLspManager(cwd: string): Promise<void>;
+export declare function getOrCreateManager(cwd: string): WorkspaceLspManager;

package/dist/src/lsp/runtime.js

@@ -10,6 +10,22 @@ export async function queryLsp(cwd, input) {
         filePath: path.isAbsolute(input.filePath) ? input.filePath : path.resolve(cwd, input.filePath),
     });
 }
+// Default timeout (ms) when a caller omits one. manager.waitForDiagnostics now
+// takes a REQUIRED timeout (Sprint-1 readiness contract, commit 4af6efb1) and no
+// longer defaults internally, so the public wrapper supplies the documented 1500ms.
+const DEFAULT_WAIT_DIAGNOSTICS_MS = 1500;
+export async function waitForDiagnosticsLsp(cwd, filePath, timeout) {
+    const manager = getOrCreateManager(cwd);
+    return manager.waitForDiagnostics(path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath), timeout ?? DEFAULT_WAIT_DIAGNOSTICS_MS);
+}
+export async function impactOfChangeLsp(cwd, filePath, query) {
+    const manager = getOrCreateManager(cwd);
+    return manager.impactOfChange(path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath), query);
+}
+export async function lspMutationPreview(cwd, filePath, change) {
+    const manager = getOrCreateManager(cwd);
+    return manager.lspMutationPreview(path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath), change);
+}
 export async function syncFileWithLsp(cwd, filePath, content, save = true, waitForDiagnostics = true, diagnosticsTimeoutMs) {
     const manager = getOrCreateManager(cwd);
     return manager.syncFile(path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath), content, save, waitForDiagnostics, diagnosticsTimeoutMs);
@@ -29,7 +45,7 @@ export async function shutdownWorkspaceLspManager(cwd) {
     managers.delete(key);
     await manager.close();
 }
-function getOrCreateManager(cwd) {
+export function getOrCreateManager(cwd) {
     const key = resolveManagerKey(cwd);
     const existing = managers.get(key);
     if (existing)

package/dist/src/lsp/types.d.ts

@@ -1,4 +1,4 @@
-export declare const LSP_TOOL_OPERATIONS: readonly ["goToDefinition", "findReferences", "hover", "documentSymbol", "workspaceSymbol", "goToImplementation", "prepareCallHierarchy", "incomingCalls", "outgoingCalls"];
+export declare const LSP_TOOL_OPERATIONS: readonly ["goToDefinition", "findReferences", "hover", "documentSymbol", "workspaceSymbol", "goToImplementation", "prepareCallHierarchy", "incomingCalls", "outgoingCalls", "waitForDiagnostics"];
 export type LspToolOperation = (typeof LSP_TOOL_OPERATIONS)[number];
 export type LspBuiltInServerId = "typescript" | "pyright" | "gopls" | "rust-analyzer" | "bash-language-server" | "yaml-language-server" | "clangd" | "jdtls" | "sourcekit-lsp" | "csharp-ls";
 export interface LspPosition {
@@ -78,6 +78,88 @@ export interface LspQueryInput {
     character?: number;
     query?: string;
 }
+/**
+ * LSP readiness status (SLICE1-BUILD-NOTE.md §79-86, §73-77).
+ * - `ok`          — diagnostics resolved within the ≤5s budget
+ * - `partial`     — one or more waits timed out; stale diagnostics were used
+ * - `unavailable` — no server could be reached or the query threw
+ * The lsp-before-grep policy keys on this: grep fallback is allowed when
+ * `lspStatus !== 'ok'`.
+ */
+export type LspStatus = "ok" | "partial" | "unavailable";
+/**
+ * Reason a composite result is degraded (SLICE1-BUILD-NOTE.md §33-40).
+ * Precedence when several apply: lsp_unavailable > diagnostics_timeout >
+ * refs_truncated > none.
+ */
+export type DegradedReason = "none" | "refs_truncated" | "diagnostics_timeout" | "lsp_unavailable";
+/** Per-call token-budget accounting; `tokenBudgetUsed` is hard-capped ≤500. */
+export interface LspResultMetadata {
+    /** Elapsed + reference estimate, clamped to ≤500 (SLICE1-BUILD-NOTE.md §49-54). */
+    tokenBudgetUsed: number;
+}
+/** `waitForDiagnostics` result (SLICE1-BUILD-NOTE.md §79-86). */
+export interface LspQueryResult {
+    diagnostics: LspDiagnostic[];
+    lspStatus: LspStatus;
+    /** True only when zero error-level (severity ≤ 1) diagnostics exist for the file. */
+    clean: boolean;
+    metadata: LspResultMetadata;
+}
+/** `impact_of_change` composite result (SLICE1-BUILD-NOTE.md §10, §19-54). */
+export interface ImpactOfChangeResult {
+    references: LspLocation[];
+    diagnostics: LspDiagnostic[];
+    /** False when the reference list was truncated to stay within token budget. */
+    referencesComplete: boolean;
+    /**
+     * True only when `referencesComplete === true` AND the frozen union (symbol
+     * file + every referenced file) has zero error-level diagnostics AND the LSP
+     * was fully available. `false` is the safe default → agents grep-fallback.
+     */
+    safeToRename: boolean;
+    /** Zero error-level diagnostics on the union of the symbol file + reference files. */
+    clean: boolean;
+    /** Top-2 error category messages joined with "; ", ≤120 chars; "none" when clean. */
+    suggestedGuard: string;
+    degraded: DegradedReason;
+    lspStatus: LspStatus;
+    metadata: LspResultMetadata;
+}
+/**
+ * `lsp_mutation_preview` stub (SLICE1-BUILD-NOTE.md §55-71). Fixed schema, no
+ * `workspaceEdit`, no apply path — real diff computation is Slice 2.
+ */
+export interface MutationPreviewResult {
+    readonly op: "allowlist";
+    readonly dryRunResult: {
+        readonly proposedEdits: [];
+        readonly tokenEstimate: number;
+    };
+    readonly schemaVersion: "1.0";
+}
+/**
+ * Tagged error kind for LSP operation failures.
+ * Throw-only canonical failure for slice 1 ── every failure flows
+ * through a single syntactic choke point (the projection's try/catch).
+ */
+export type LspErrorKind = "no_server" | "request_timeout" | "request_failed" | "lsp_disabled" | "unknown";
+/** Tagged‑union Error used by manager methods. */
+export declare class LspError extends Error {
+    readonly kind: LspErrorKind;
+    constructor(kind: LspErrorKind, message: string);
+}
+/** Policy decision the lsp‑before‑grep gate returns. */
+export type PolicyAction = {
+    kind: "allow";
+    reason: string;
+} | {
+    kind: "block";
+    reason: string;
+} | {
+    kind: "enrich";
+    enrichWith: ImpactOfChangeResult;
+};
 export interface LspToolResponse {
     success: boolean;
     output: string;

package/dist/src/lsp/types.js

@@ -8,5 +8,15 @@ export const LSP_TOOL_OPERATIONS = [
     "prepareCallHierarchy",
     "incomingCalls",
     "outgoingCalls",
+    "waitForDiagnostics",
 ];
+/** Tagged‑union Error used by manager methods. */
+export class LspError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "LspError";
+        this.kind = kind;
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/src/maintain/pr-builder.js

@@ -186,9 +186,13 @@ async function squashSinceMarker(cwd, markerSha, title) {
     }
 }
 // ─── PR body prompt ───────────────────────────────────────────────────────────
-const PR_BODY_SYSTEM = "You are a developer writing a GitHub pull request body. " +
-    "Output ONLY the markdown body — no preamble, no code fences wrapping the whole output. " +
-    "Follow the template exactly. Be concise.";
+const PR_BODY_SYSTEM = "You are a senior engineer writing the description for your own pull request. " +
+    "Write for a busy reviewer: they should understand what this PR does, why it exists, and how to verify it " +
+    "within thirty seconds of reading — before they open a single file. " +
+    "Write in plain, confident prose. Prefer specific claims ('caps retry backoff at 30s') over vague ones " +
+    "('improves retry handling'). Never restate filenames or diffs mechanically — explain intent and effect. " +
+    "Do not pad, do not apologize, and do not invent changes that are not evidenced by the task data or diff. " +
+    "Output ONLY the finished markdown body — no preamble, no commentary, and no code fence wrapping the whole output.";
 function buildPrBodyPrompt(task, diff, intel, result, filesOutsideRadius) {
     const diffSnippet = diff.length > 8192 ? `${diff.slice(0, 8192)}\n...[diff truncated to 8KB]` : diff;
     const descriptionSummary = task.description.length > 600 ? `${task.description.slice(0, 597)}…` : task.description;
@@ -199,29 +203,35 @@ function buildPrBodyPrompt(task, diff, intel, result, filesOutsideRadius) {
         ? `\n## Review Concerns\n${result.reviewConcerns.map((c) => `- ${c}`).join("\n")}`
         : "";
     return [
-        "Generate a PR body for the following maintenance task.",
-        "Use the template below. Replace each placeholder with real content.",
+        "Write the pull request body for the maintenance task below.",
+        "Use exactly the section structure described here, in this order. Render real content for every section — no placeholders, no angle brackets in the output.",
         "Output ONLY the rendered markdown body — nothing else.",
         "",
-        "## Template",
+        "## Structure",
         "---",
         "## Summary",
-        "<copy task description verbatim — trim to 3-5 sentences>",
+        "Two to four sentences a reviewer can read in isolation: what problem this PR solves, why it matters now, and the shape of the fix. Ground it in the task description, but rewrite it as prose — do not paste the task text verbatim.",
         "",
         "## What changed",
-        "<bullet list inferred from diff hunks — focus on user-visible behavior, not file mechanics>",
+        "Three to six bullets describing observable behavior changes, ordered most-significant first. Each bullet states an effect ('X now does Y', 'Z no longer happens when W'), not a file operation. Infer these from the diff hunks; mention a file path only when it clarifies scope. If the diff is trivially small, two bullets are fine — do not pad.",
         "",
         "## Test plan",
-        "<bullet list from acceptance_criteria + regression tests run>",
+        "One bullet per acceptance criterion, phrased as a verifiable check the reviewer could repeat. Then list the regression tests that were run. If something was NOT verified, say so plainly rather than omitting it.",
         outsideSection ? "## Files outside declared impact radius" : "",
-        outsideSection ? "<list filesOutsideRadius>" : "",
+        outsideSection
+            ? "List each file from the task data below, and for each add a short honest note on why it was touched (or 'reason unclear from diff' if you cannot tell). These files deserve extra reviewer scrutiny — do not downplay them."
+            : "",
         concernsSection ? "## Review Concerns" : "",
-        concernsSection ? "<list reviewConcerns — these are non-blocking, for reviewer awareness>" : "",
+        concernsSection
+            ? "List each concern from the task data verbatim, one bullet each. These are non-blocking flags for reviewer awareness — preserve their meaning, do not soften or editorialize."
+            : "",
         "## Related",
-        "- Impact radius: <first 5 entries from impactRadius>",
-        "- Regression tests run: <first 5 entries from regressionTests>",
+        "- Impact radius: the first 5 entries from the impact radius in the task data",
+        "- Regression tests run: the first 5 entries from the regression tests in the task data",
         "---",
         "",
+        "Rules: British understatement over marketing tone. No emoji. No headers beyond those specified. Keep the whole body under ~350 words unless the concerns/outside-radius sections force it longer.",
+        "",
         "## Task data",
         `Kind: ${task.kind}`,
         `Title: ${task.title}`,