fix: semantically structure judge critique

Author: jahilldev

api/src/judge/judge.model.ts

@@ -23,7 +23,8 @@ export interface JudgeAssessInput extends JudgePromptContext {
 export interface JudgeVerdict {
   /** True when every part of the goal is evidenced in the committed changes (or genuinely blocked). */
   passed: boolean;
-  /** When not passed, a specific, actionable list of what remains — fed verbatim to the next agent. */
+  /** When not passed, a specific, actionable list of what remains — fed to the next agent (with its
+   * heading hierarchy re-leveled to nest cleanly under the prompt). Stored verbatim for humans. */
   critique: string;
 }
 

api/src/judge/judge.prompts.ts

@@ -20,7 +20,7 @@ export function buildJudgePrompt(ctx: JudgePromptContext): string {
 
 ## Critique
 
-Under that heading, if not passed, write a concise, specific, actionable checklist of exactly what still needs doing — name files, functions, and the concrete remaining steps. This is plain markdown, so code fences, quotes and lists are all fine and need no escaping; it is handed verbatim to the next agent as its to-do list. If passed, instead write a short summary of what you found. Keep the JSON block exactly as shown — \`passed\` is the only field, and the critique never goes inside it.`,
+Under that heading, if not passed, write a concise, specific, actionable checklist of exactly what still needs doing — name files, functions, and the concrete remaining steps. This is plain markdown handed to the next agent as its to-do list, so code fences, quotes and lists are all fine and need no escaping (the verdict above is the only JSON). Use nested headings/sub-bullets freely to group the work — the orchestrator re-levels your heading depths to fit the next prompt, so just keep the structure internally consistent. If passed, instead write a short summary of what you found. Keep the JSON block exactly as shown — \`passed\` is the only field, and the critique never goes inside it.`,
   ]
     .filter(Boolean)
     .join('\n\n');

api/src/judge/judge.utility.spec.ts

@@ -1,4 +1,4 @@
-import { parseJudgeVerdict } from './judge.utility.js';
+import { parseJudgeVerdict, relevelCritique } from './judge.utility.js';
 
 describe('parseJudgeVerdict', () => {
   it('parses a passed verdict (JSON block only)', () => {
@@ -49,3 +49,32 @@ describe('parseJudgeVerdict', () => {
     expect(parseJudgeVerdict('no verdict here')).toBeNull();
   });
 });
+
+describe('relevelCritique', () => {
+  it('shifts headings so the shallowest sits at the base, preserving relative depth', () => {
+    expect(relevelCritique('## Tests\nbody\n### Edge cases\nmore', 3)).toBe(
+      '### Tests\nbody\n#### Edge cases\nmore',
+    );
+  });
+
+  it('leaves headings inside fenced code blocks untouched', () => {
+    const input = '## Fix\n```sh\n# this is a shell comment, not a heading\n```\n### Then';
+    expect(relevelCritique(input, 3)).toBe(
+      '### Fix\n```sh\n# this is a shell comment, not a heading\n```\n#### Then',
+    );
+  });
+
+  it('returns the text unchanged when it has no headings', () => {
+    const input = '- item one\n- item two\n```ts\nconst x = 1;\n```';
+    expect(relevelCritique(input, 3)).toBe(input);
+  });
+
+  it('is a no-op when the shallowest heading is already at the base', () => {
+    const input = '### Already\n#### Deeper';
+    expect(relevelCritique(input, 3)).toBe(input);
+  });
+
+  it('clamps shifted levels at h6', () => {
+    expect(relevelCritique('##### Deep\n###### Deeper', 3)).toBe('### Deep\n#### Deeper');
+  });
+});

api/src/judge/judge.utility.ts

@@ -21,6 +21,65 @@ export function parseJudgeVerdict(stdout: string): JudgeVerdict | null {
   return { passed, critique: extractCritique(stdout) };
 }
 
+const HEADING_RE = /^[ \t]*(#{1,6})[ \t]+(.+?)[ \t]*#*$/;
+
+/**
+ * Re-bases the headings in the judge's freeform critique so the shallowest sits at `base` —
+ * keeping the critique's own relative hierarchy but nesting it cleanly beneath the surrounding
+ * prompt sections instead of colliding with them. Headings inside fenced code blocks are left
+ * untouched. Mirrors the persist_state plugin's _relevel_headings so injected agent text behaves
+ * consistently across the system. Returns the text unchanged when it has no headings.
+ */
+export function relevelCritique(text: string, base = 3): string {
+  const lines = text.split('\n');
+
+  const levels: number[] = [];
+  let inFence = false;
+  for (const line of lines) {
+    const s = line.trimStart();
+    if (s.startsWith('```') || s.startsWith('~~~')) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    const m = HEADING_RE.exec(line);
+    if (m) {
+      levels.push(m[1].length);
+    }
+  }
+
+  if (levels.length === 0) {
+    return text;
+  }
+
+  const shift = base - Math.min(...levels);
+  if (shift === 0) {
+    return text;
+  }
+
+  inFence = false;
+  return lines
+    .map((line) => {
+      const s = line.trimStart();
+      if (s.startsWith('```') || s.startsWith('~~~')) {
+        inFence = !inFence;
+        return line;
+      }
+      if (inFence) {
+        return line;
+      }
+      const m = HEADING_RE.exec(line);
+      if (!m) {
+        return line;
+      }
+      const level = Math.max(1, Math.min(6, m[1].length + shift));
+      return `${'#'.repeat(level)} ${m[2].trim()}`;
+    })
+    .join('\n');
+}
+
 /**
  * The critique is everything after the JSON verdict block. We strip the fenced ```json {...} ```
  * block (or a bare {...} object as a fallback) and an optional leading "Critique" heading,

api/src/orchestrator/orchestrator.service.ts

@@ -27,6 +27,7 @@ import { buildVerifyPrompt } from '../verify/verify.prompts.js';
 import { parseVerifyCommand } from '../verify/verify.utility.js';
 import { VerifyService } from '../verify/verify.service.js';
 import { JudgeService } from '../judge/judge.service.js';
+import { relevelCritique } from '../judge/judge.utility.js';
 import { buildSummaryPrompt } from '../summary/summary.prompts.js';
 import { buildPrBody } from '../summary/summary.utility.js';
 import { WorkspaceService } from '../workspace/workspace.service.js';
@@ -1129,7 +1130,9 @@ export class OrchestratorService {
         break;
       }
 
-      critique = verdict.critique;
+      // Re-level the judge's critique headings so they nest under the next prompt's sections
+      // instead of colliding with them; the verbatim critique stays in the run's stdout.
+      critique = relevelCritique(verdict.critique);
 
       this.logger.log(
         `[job ${p.job.id}] ${p.phase} judged incomplete (attempt ${attempt}); continuing with judge critique`,