supipowers 1.5.2 → 2.0.0

package/src/discovery/rank.ts

@@ -0,0 +1,144 @@
+// src/discovery/rank.ts
+//
+// Deterministic ranking over a set of candidate paths. Each scoring source
+// contributes a weighted score and a rationale line; the final ranking is
+// the sum of contributions, sorted desc and then lex for stability.
+
+export interface DiscoveryInput {
+  cwd: string;
+  /** Absolute or cwd-relative repo root. */
+  repoRoot: string;
+  /** Free-text workflow query, e.g. "fix the login bug". Used for path-token scoring. */
+  query?: string;
+  /** Files changed in the current context (git diff, uncommitted, PR scope). */
+  changedFiles?: string[];
+  /**
+   * All discoverable files to consider. If omitted, only `changedFiles` are
+   * scored. Callers should keep this list pre-filtered to reasonable size.
+   */
+  candidatePool?: string[];
+  /**
+   * Additional per-source boost map: path → { score, rationale }. Used by
+   * workflow-specific callers (e.g. fix-pr injecting files mentioned in PR
+   * comments).
+   */
+  externalSignals?: Record<string, { score: number; rationale: string }>;
+  /** Cap the returned ranked list. Default: 20. */
+  limit?: number;
+}
+
+export type DiscoverySource =
+  | "changed"
+  | "query-path-match"
+  | "external-signal"
+  | "lsp";
+
+export interface DiscoveryCandidate {
+  path: string;
+  score: number;
+  /** Each source that contributed to the score. */
+  sources: DiscoverySource[];
+  /** Human-readable reasons explaining the score. */
+  rationale: string[];
+}
+
+export interface DiscoveryResult {
+  candidates: DiscoveryCandidate[];
+  /** Every source that touched at least one candidate, for observability. */
+  sourcesUsed: DiscoverySource[];
+}
+
+// ---------------------------------------------------------------------------
+// Source weights. Small and explicit — avoid hidden tuning.
+// ---------------------------------------------------------------------------
+
+const WEIGHT_CHANGED = 10;
+const WEIGHT_QUERY_TOKEN = 2;
+const MIN_QUERY_TOKEN_LENGTH = 4;
+
+function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function tokenize(query: string): string[] {
+  return [
+    ...new Set(
+      query
+        .toLowerCase()
+        .split(/[^a-z0-9_-]+/)
+        .filter((t) => t.length >= MIN_QUERY_TOKEN_LENGTH),
+    ),
+  ];
+}
+
+function countTokenHitsInPath(path: string, tokens: string[]): number {
+  if (tokens.length === 0) return 0;
+  const lower = path.toLowerCase();
+  let hits = 0;
+  for (const t of tokens) {
+    if (lower.includes(t)) hits += 1;
+  }
+  return hits;
+}
+
+/**
+ * Rank candidate files. Deterministic given identical input: sort is by
+ * score desc, then path asc, so ties resolve stably.
+ */
+export function rankDiscoveryCandidates(input: DiscoveryInput): DiscoveryResult {
+  const changedFiles = new Set((input.changedFiles ?? []).map(normalizePath));
+  const pool = new Set<string>([
+    ...changedFiles,
+    ...(input.candidatePool ?? []).map(normalizePath),
+    ...Object.keys(input.externalSignals ?? {}).map(normalizePath),
+  ]);
+
+  const queryTokens = input.query ? tokenize(input.query) : [];
+  const sourcesUsed = new Set<DiscoverySource>();
+
+  const candidates: DiscoveryCandidate[] = [];
+  for (const path of pool) {
+    const rationale: string[] = [];
+    const sources: DiscoverySource[] = [];
+    let score = 0;
+
+    if (changedFiles.has(path)) {
+      score += WEIGHT_CHANGED;
+      sources.push("changed");
+      sourcesUsed.add("changed");
+      rationale.push("changed in current context");
+    }
+
+    const tokenHits = countTokenHitsInPath(path, queryTokens);
+    if (tokenHits > 0) {
+      const contribution = tokenHits * WEIGHT_QUERY_TOKEN;
+      score += contribution;
+      sources.push("query-path-match");
+      sourcesUsed.add("query-path-match");
+      rationale.push(`path matches ${tokenHits} query token${tokenHits === 1 ? "" : "s"}`);
+    }
+
+    const external = input.externalSignals?.[path];
+    if (external) {
+      score += external.score;
+      sources.push("external-signal");
+      sourcesUsed.add("external-signal");
+      rationale.push(external.rationale);
+    }
+
+    if (score > 0) {
+      candidates.push({ path, score, sources, rationale });
+    }
+  }
+
+  candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.path.localeCompare(b.path);
+  });
+
+  const limit = input.limit ?? 20;
+  return {
+    candidates: candidates.slice(0, limit),
+    sourcesUsed: [...sourcesUsed].sort(),
+  };
+}

package/src/discovery/sources.ts

@@ -0,0 +1,89 @@
+// src/discovery/sources.ts
+//
+// Side-effectful discovery helpers that read from the filesystem / git /
+// workspace. Kept in a dedicated module so `rank.ts` stays pure and unit-
+// testable without mocks.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { DiscoveryInput, DiscoveryResult } from "./rank.js";
+import { rankDiscoveryCandidates } from "./rank.js";
+
+export interface SourcesDiscoveryOptions extends Omit<DiscoveryInput, "candidatePool"> {
+  /**
+   * Glob-lite allow-list of path suffixes to include in the candidate pool
+   * (e.g. [".ts", ".tsx"]). Empty means no suffix filter.
+   */
+  extensions?: string[];
+  /**
+   * Max pool size after filesystem walk. Prevents huge repos from dominating
+   * candidate evaluation. Default: 5000.
+   */
+  maxPoolSize?: number;
+  /**
+   * Directory names to skip while walking. Defaults cover `.git`, `node_modules`,
+   * `dist`, `.omp`, `.cache`.
+   */
+  excludeDirs?: string[];
+}
+
+const DEFAULT_EXCLUDES = new Set([".git", "node_modules", "dist", "build", ".omp", ".cache", ".next", ".turbo"]);
+
+function walkFiles(
+  root: string,
+  options: { extensions?: string[]; maxPoolSize: number; excludeDirs: Set<string> },
+): string[] {
+  const results: string[] = [];
+  const stack: string[] = [root];
+  const extFilter = options.extensions && options.extensions.length > 0 ? options.extensions : null;
+
+  while (stack.length > 0 && results.length < options.maxPoolSize) {
+    const current = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (options.excludeDirs.has(entry.name)) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (extFilter && !extFilter.some((ext) => entry.name.endsWith(ext))) continue;
+      results.push(path.relative(root, full));
+      if (results.length >= options.maxPoolSize) break;
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Walk `repoRoot`, build a candidate pool, then rank. Deterministic given
+ * the same filesystem state.
+ */
+export function discoverFromSources(options: SourcesDiscoveryOptions): DiscoveryResult {
+  const excludeDirs = new Set([...DEFAULT_EXCLUDES, ...(options.excludeDirs ?? [])]);
+  const maxPoolSize = options.maxPoolSize ?? 5000;
+
+  const candidatePool = walkFiles(options.repoRoot, {
+    extensions: options.extensions,
+    maxPoolSize,
+    excludeDirs,
+  });
+
+  return rankDiscoveryCandidates({
+    cwd: options.cwd,
+    repoRoot: options.repoRoot,
+    query: options.query,
+    changedFiles: options.changedFiles,
+    candidatePool,
+    externalSignals: options.externalSignals,
+    limit: options.limit,
+  });
+}

package/src/discovery/workflow.ts

@@ -0,0 +1,87 @@
+// src/discovery/workflow.ts
+//
+// High-level integration helper for workflows. Commands (/supi:review,
+// /supi:plan, /supi:qa, /supi:fix-pr) adopt discovery by calling
+// `suggestCandidatesForWorkflow` with the context they already have. The
+// helper composes the deterministic ranker, optional LSP augmentation, and
+// a concise rationale formatter so workflows don't wire the pieces
+// themselves.
+//
+// The helper is safe-by-default: when no inputs are provided, it returns
+// an empty result rather than scanning the whole repo. Workflows that want
+// a full filesystem pool should call `discoverFromSources` directly.
+
+import { rankDiscoveryCandidates, type DiscoveryCandidate, type DiscoveryInput } from "./rank.js";
+import { rankWithLspAugmentation, type LspSymbolLocation } from "./lsp.js";
+
+export interface WorkflowDiscoveryInput extends Omit<DiscoveryInput, "candidatePool"> {
+  /**
+   * Optional pre-filtered candidate pool (e.g. tracked files for a workspace
+   * target). When omitted, only changedFiles + externalSignals seed the pool.
+   */
+  candidatePool?: string[];
+  /**
+   * Optional LSP symbol lookup. When provided, LSP hits are folded in as
+   * external signals; failures degrade to the non-LSP ranking.
+   */
+  querySymbols?: (query: string) => LspSymbolLocation[] | Promise<LspSymbolLocation[]>;
+}
+
+export interface WorkflowDiscoveryResult {
+  candidates: DiscoveryCandidate[];
+  /** True when LSP augmentation ran successfully. False when disabled or it threw. */
+  lspUsed: boolean;
+  /** Short formatted summary lines suitable for notify / log / prompt injection. */
+  summaryLines: string[];
+}
+
+function formatSummary(candidates: DiscoveryCandidate[], maxLines = 5): string[] {
+  return candidates.slice(0, maxLines).map((c) => {
+    const why = c.rationale.join("; ");
+    return `${c.path} (score ${c.score}) — ${why}`;
+  });
+}
+
+/**
+ * Produce ranked candidates for a workflow. Always safe to call — returns
+ * empty candidates when no signals are provided. Prefer this over calling
+ * `rankDiscoveryCandidates` / `rankWithLspAugmentation` directly so every
+ * workflow uses the same composition and rationale format.
+ */
+export async function suggestCandidatesForWorkflow(
+  input: WorkflowDiscoveryInput,
+): Promise<WorkflowDiscoveryResult> {
+  if (input.querySymbols) {
+    const result = await rankWithLspAugmentation({
+      cwd: input.cwd,
+      repoRoot: input.repoRoot,
+      query: input.query,
+      changedFiles: input.changedFiles,
+      candidatePool: input.candidatePool,
+      externalSignals: input.externalSignals,
+      limit: input.limit,
+      querySymbols: input.querySymbols,
+    });
+    return {
+      candidates: result.candidates,
+      lspUsed: result.lspAvailable && result.lspHitCount > 0,
+      summaryLines: formatSummary(result.candidates),
+    };
+  }
+
+  const ranked = rankDiscoveryCandidates({
+    cwd: input.cwd,
+    repoRoot: input.repoRoot,
+    query: input.query,
+    changedFiles: input.changedFiles,
+    candidatePool: input.candidatePool,
+    externalSignals: input.externalSignals,
+    limit: input.limit,
+  });
+
+  return {
+    candidates: ranked.candidates,
+    lspUsed: false,
+    summaryLines: formatSummary(ranked.candidates),
+  };
+}

package/src/docs/contracts.ts

@@ -0,0 +1,39 @@
+// src/docs/contracts.ts
+//
+// Schema-backed contract for doc-drift sub-agent output. Every doc-drift
+// sub-agent must emit JSON that parses against DocDriftOutputSchema. The
+// retry loop (runWithOutputValidation) will hand validation errors back to
+// the model rather than letting a silent regex heuristic invent findings.
+
+import { Type, type Static } from "@sinclair/typebox";
+
+export const DOC_DRIFT_SEVERITIES = ["info", "warning", "error"] as const;
+export const DOC_DRIFT_STATUSES = ["ok", "drifted"] as const;
+
+export type DocDriftSeverity = (typeof DOC_DRIFT_SEVERITIES)[number];
+export type DocDriftStatus = (typeof DOC_DRIFT_STATUSES)[number];
+
+export const DocDriftFindingSchema = Type.Object(
+  {
+    file: Type.String({ minLength: 1 }),
+    description: Type.String({ minLength: 1 }),
+    severity: Type.Union(
+      DOC_DRIFT_SEVERITIES.map((value) => Type.Literal(value)),
+    ),
+    relatedFiles: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+  },
+  { additionalProperties: false },
+);
+
+export const DocDriftOutputSchema = Type.Object(
+  {
+    findings: Type.Array(DocDriftFindingSchema),
+    status: Type.Union(
+      DOC_DRIFT_STATUSES.map((value) => Type.Literal(value)),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export type DocDriftFinding = Static<typeof DocDriftFindingSchema>;
+export type DocDriftOutput = Static<typeof DocDriftOutputSchema>;

package/src/docs/drift.ts

@@ -1,8 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Platform, PlatformPaths } from "../platform/types.js";
-import type { DocDriftState, DriftCheckResult, DriftFinding } from "../types.js";
-import { runStructuredAgentSession } from "../quality/ai-session.js";
+import type { DocDriftState, DriftCheckResult, DriftFinding, WorkspaceTarget } from "../types.js";
+import { runWithOutputValidation, parseStructuredOutput } from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
+import { DocDriftOutputSchema, type DocDriftOutput } from "./contracts.js";
+import { ReleaseDocFixOutputSchema } from "../release/contracts.js";
+import { filterPathsForWorkspaceTarget } from "../workspace/path-mapping.js";
+import { getProjectStatePath, getProjectTargetStatePath } from "../workspace/state-paths.js";
 
 // ── State persistence ─────────────────────────────────────────
 
@@ -14,21 +19,41 @@ const EMPTY_STATE: DocDriftState = {
   lastRunAt: null,
 };
 
-export function statePath(paths: PlatformPaths, cwd: string): string {
-  return paths.project(cwd, STATE_FILENAME);
+export interface DocDriftScope<TTarget extends WorkspaceTarget = WorkspaceTarget> {
+  target: TTarget;
+  allTargets: TTarget[];
 }
 
-export function loadState(paths: PlatformPaths, cwd: string): DocDriftState {
-  const file = statePath(paths, cwd);
+function filterTrackedFilesToScope(
+  trackedFiles: string[],
+  scope?: DocDriftScope,
+): string[] {
+  if (!scope) {
+    return trackedFiles;
+  }
+
+  return filterPathsForWorkspaceTarget(scope.allTargets, scope.target, trackedFiles);
+}
+
+export function statePath(paths: PlatformPaths, cwd: string, target?: WorkspaceTarget): string {
+  return target ? getProjectTargetStatePath(paths, target, STATE_FILENAME) : getProjectStatePath(paths, cwd, STATE_FILENAME);
+}
+
+export function loadState(paths: PlatformPaths, cwd: string, scope?: DocDriftScope): DocDriftState {
+  const file = statePath(paths, cwd, scope?.target);
   try {
-    return JSON.parse(fs.readFileSync(file, "utf-8")) as DocDriftState;
+    const state = JSON.parse(fs.readFileSync(file, "utf-8")) as DocDriftState;
+    return {
+      ...state,
+      trackedFiles: filterTrackedFilesToScope(state.trackedFiles, scope),
+    };
   } catch {
     return { ...EMPTY_STATE, trackedFiles: [] };
   }
 }
 
-export function saveState(paths: PlatformPaths, cwd: string, state: DocDriftState): void {
-  const file = statePath(paths, cwd);
+export function saveState(paths: PlatformPaths, cwd: string, state: DocDriftState, target?: WorkspaceTarget): void {
+  const file = statePath(paths, cwd, target);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
 }
@@ -77,6 +102,7 @@ export function isProjectDoc(filePath: string): boolean {
 export async function discoverDocFiles(
   platform: Platform,
   cwd: string,
+  scope?: DocDriftScope,
 ): Promise<string[]> {
   const result = await platform.exec(
     "git",
@@ -85,13 +111,16 @@ export async function discoverDocFiles(
   );
   if (result.code !== 0) return [];
 
-  const files = result.stdout
-    .split("\n")
-    .map((f) => f.trim())
-    .filter((f) => f.length > 0 && isProjectDoc(f));
+  const files = [...new Set(
+    result.stdout
+      .split("\n")
+      .map((f) => f.trim())
+      .filter((f) => f.length > 0 && isProjectDoc(f)),
+  )].sort();
 
-  // Deduplicate (globs may overlap)
-  return [...new Set(files)].sort();
+  return scope
+    ? filterPathsForWorkspaceTarget(scope.allTargets, scope.target, files).sort()
+    : files;
 }
 
 // ── Git helpers ───────────────────────────────────────────────
@@ -279,85 +308,48 @@ export function buildSubAgentPrompt(group: DocDriftGroup, isFirstRun: boolean):
     `- Only flag things that are factually wrong or missing`,
     `- If documentation is accurate, say so`,
     ``,
-    `Respond with a JSON object:`,
-    `{`,
-    `  "findings": [`,
-    `    {`,
-    `      "file": "path/to/doc.md",`,
-    `      "description": "What is wrong or missing",`,
-    `      "severity": "info" | "warning" | "error",`,
-    `      "relatedFiles": ["path/to/source.ts"]`,
-    `    }`,
-    `  ],`,
-    `  "status": "ok" | "drifted"`,
-    `}`,
+    `Respond with a JSON object that matches this TypeScript shape exactly:`,
+    ``,
+    `\`\`\`ts`,
+    renderSchemaText(DocDriftOutputSchema),
+    `\`\`\``,
     ``,
-    `Set status to "drifted" if ANY findings exist, "ok" if all docs are accurate.`,
-    `Respond ONLY with the JSON object, no other text.`,
+    `Set "status" to "drifted" if ANY findings exist, "ok" if all docs are accurate.`,
+    `Respond with only the JSON object. You may wrap it in a \`\`\`json fence.`,
   );
 
   return parts.join("\n");
 }
 
-// ── Response parsing ──────────────────────────────────────────
-
-export function parseDriftFindings(text: string): { findings: DriftFinding[]; status: string } {
-  try {
-    const jsonMatch = text.match(/\{[\s\S]*\}/);
-    if (jsonMatch) {
-      const parsed = JSON.parse(jsonMatch[0]);
-      if (Array.isArray(parsed.findings)) {
-        const findings: DriftFinding[] = parsed.findings
-          .filter(
-            (f: any) =>
-              typeof f.file === "string" &&
-              typeof f.description === "string",
-          )
-          .map((f: any) => ({
-            file: f.file,
-            description: f.description,
-            severity: f.severity === "warning" || f.severity === "error" ? f.severity : "info",
-            ...(Array.isArray(f.relatedFiles) ? { relatedFiles: f.relatedFiles } : {}),
-          }));
-        return { findings, status: parsed.status === "ok" ? "ok" : "drifted" };
-      }
-    }
-  } catch {
-    // Fall through
-  }
-
-  // Fallback: treat unparseable response as potential drift
-  const lower = text.toLowerCase();
-  const likelyDrifted =
-    lower.includes("inaccura") ||
-    lower.includes("outdated") ||
-    lower.includes("missing") ||
-    lower.includes("drift");
-  return {
-    findings: likelyDrifted
-      ? [{ file: "unknown", description: text.slice(0, 200), severity: "warning" }]
-      : [],
-    status: likelyDrifted ? "drifted" : "ok",
-  };
-}
-
 // ── Sub-agent runner ──────────────────────────────────────────
 
+export type DriftSubAgentResult =
+  | { status: "ok"; output: DocDriftOutput }
+  | { status: "blocked"; error: string };
+
 async function runDriftSubAgent(
   createAgentSession: Platform["createAgentSession"],
+  paths: PlatformPaths,
   group: DocDriftGroup,
   isFirstRun: boolean,
   cwd: string,
-): Promise<{ findings: DriftFinding[]; status: string }> {
+): Promise<DriftSubAgentResult> {
   const prompt = buildSubAgentPrompt(group, isFirstRun);
-  const result = await runStructuredAgentSession(
-    createAgentSession.bind(undefined) as any,
-    { cwd, prompt },
+  const result = await runWithOutputValidation<DocDriftOutput>(
+    createAgentSession as any,
+    {
+      cwd,
+      prompt,
+      schema: renderSchemaText(DocDriftOutputSchema),
+      parse: (raw) => parseStructuredOutput<DocDriftOutput>(raw, DocDriftOutputSchema),
+      reliability: { paths, cwd, command: "docs", operation: "drift-analyze" },
+    },
   );
-  if (result.status !== "ok" || !result.finalText) {
-    return { findings: [], status: "error" };
+
+  if (result.status === "ok") {
+    return { status: "ok", output: result.output };
   }
-  return parseDriftFindings(result.finalText);
+  return { status: "blocked", error: result.error };
 }
 
 // ── Orchestrator ──────────────────────────────────────────────
@@ -365,19 +357,25 @@ async function runDriftSubAgent(
 /**
  * Checks tracked docs for drift using parallel sub-agents.
  * Returns null to skip silently, or a DriftCheckResult with per-doc findings.
+ * Sub-agents whose output fails schema validation surface their error via
+ * `result.errors` — the orchestrator never fabricates findings on parse failure.
  */
 export async function checkDocDrift(
   platform: Platform,
   cwd: string,
+  scope?: DocDriftScope,
 ): Promise<DriftCheckResult | null> {
-  const state = loadState(platform.paths, cwd);
+  const state = loadState(platform.paths, cwd, scope);
   if (state.trackedFiles.length === 0) return null;
 
   let changedFiles: string[] = [];
   const isFirstRun = !state.lastCommit;
 
   if (!isFirstRun) {
-    changedFiles = await getDiffFilesSince(platform, cwd, state.lastCommit!);
+    const diffFiles = await getDiffFilesSince(platform, cwd, state.lastCommit!);
+    changedFiles = scope
+      ? filterPathsForWorkspaceTarget(scope.allTargets, scope.target, diffFiles)
+      : diffFiles;
     if (changedFiles.length === 0) return null;
   }
 
@@ -390,6 +388,7 @@ export async function checkDocDrift(
     groups.map((group) =>
       runDriftSubAgent(
         platform.createAgentSession.bind(platform),
+        platform.paths,
         group,
         isFirstRun,
         cwd,
@@ -397,18 +396,32 @@ export async function checkDocDrift(
     ),
   );
 
-  // Aggregate findings
+  // Aggregate findings and errors
   const allFindings: DriftFinding[] = [];
+  const errors: string[] = [];
   for (const result of results) {
-    allFindings.push(...result.findings);
+    if (result.status === "ok") {
+      allFindings.push(...result.output.findings);
+    } else {
+      errors.push(result.error);
+    }
   }
 
   const drifted = allFindings.length > 0;
-  const summary = drifted
-    ? `${allFindings.length} finding(s) across ${new Set(allFindings.map((f) => f.file)).size} doc(s)`
-    : "All documentation is up to date.";
+  const parts: string[] = [];
+  if (drifted) {
+    parts.push(`${allFindings.length} finding(s) across ${new Set(allFindings.map((f) => f.file)).size} doc(s)`);
+  } else if (errors.length === 0) {
+    parts.push("All documentation is up to date.");
+  }
+  if (errors.length > 0) {
+    parts.push(`${errors.length} sub-agent(s) failed validation`);
+  }
+  const summary = parts.join(" · ");
 
-  return { drifted, summary, findings: allFindings };
+  return errors.length > 0
+    ? { drifted, summary, findings: allFindings, errors }
+    : { drifted, summary, findings: allFindings };
 }
 
 // ── Doc fix prompt ────────────────────────────────────────────
@@ -449,6 +462,23 @@ export function buildFixPrompt(findings: DriftFinding[]): string {
     parts.push(``);
   }
 
-  parts.push(`Read each file listed above, apply the fixes, and write the corrected files.`);
+  parts.push(
+    `Read each file listed above, apply the fixes, and write the corrected files.`,
+    ``,
+    `## Output`,
+    ``,
+    `After applying the edits, respond with a JSON object that matches this TypeScript shape exactly:`,
+    ``,
+    "```ts",
+    renderSchemaText(ReleaseDocFixOutputSchema),
+    "```",
+    ``,
+    `Field guide:`,
+    `- \`edits\`: one entry per file you modified, with \`file\` as the relative path and \`instructions\` as a short description of what you changed.`,
+    `- \`summary\`: one-sentence summary of the overall fix.`,
+    `- \`status\`: \`"ok"\` when every finding was addressed; \`"blocked"\` when you could not complete the fixes — put the reason in \`summary\`.`,
+    ``,
+    "Respond with only the JSON object. You may wrap it in a ```json fence.",
+  );
   return parts.join("\n");
 }