@pmelab/gtd 49.0.0 → 50.0.0

package/src/workflows/feature/severity-sorted-review.feature

@@ -0,0 +1,197 @@
+@inmem
+Feature: the final review lists what matters most first
+
+  Before the review rests, the judge rates every chunk the reviewer wrote — a
+  walkthrough chunk or a carried quality finding — on the same four questions
+  as a human's note (`build.review.ranking`): critical (security, or a one-way
+  door), should (a contract, or a new concept), could. The review lists them
+  in that order, security before one-way doors, each led by its tier and
+  reason. A chunk the judge cannot rate is critical, so it is shown first.
+
+  Background:
+    Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_FLAGMODE" set to "false"
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And the working tree is committed as "feat: add calculator"
+    And a file "TODO.md" with:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    And step "design.triage" writes ".gtd/REQUIREMENTS.md" with:
+      """
+      # Requirements
+
+      ## Acceptance Criteria
+
+      - AC-1: subtract(a, b) returns a - b.
+      """
+    And step "design.gate.answer" changes nothing
+    And step "seam.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => {})
+      """
+    And step "seam.naive" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => a - b
+      """
+    And step "seam.check" changes nothing
+    And step "implement.applying" runs its script
+    And step "implement.health.check" changes nothing
+    And step "implement.closing" runs its script
+    And judge step "implement.coverage" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9}]
+      """
+    And step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
+      """
+      # Quality
+
+      ## AC-1 ignores floating point
+
+      Should subtract round? The criterion does not say.
+      """
+    And judge step "build.quality.triage" answers:
+      """
+      [{"id":"Q1","answer":"design","p":0.9}]
+      """
+    And step "build.quality.sorting" runs its script
+    And step "build.quality.closing" runs its script
+    And step "build.review.carrying" runs its script
+
+  Scenario: security and one-way doors come first, a carried finding sorted among the rest
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      The new export.
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## Session token
+
+      - [ ] ./src/calc.ts#1-1 — reads the caller's token
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+
+      ## Saved format
+
+      - [ ] ./src/calc.ts#1-2 — what callers persist
+      """
+    And judge step "build.review.ranking" answers:
+      """
+      [{"id":"C1.security","answer":"no","p":0.9},{"id":"C1.reversibility","answer":"two-way","p":0.9},{"id":"C1.blastRadius","answer":"local","p":0.9},{"id":"C1.newConcept","answer":"no","p":0.9},{"id":"C2.security","answer":"yes","p":0.9},{"id":"C2.reversibility","answer":"two-way","p":0.9},{"id":"C2.blastRadius","answer":"module","p":0.9},{"id":"C2.newConcept","answer":"no","p":0.9},{"id":"C3.security","answer":"no","p":0.9},{"id":"C3.reversibility","answer":"two-way","p":0.9},{"id":"C3.blastRadius","answer":"contract","p":0.9},{"id":"C3.newConcept","answer":"no","p":0.9},{"id":"C4.security","answer":"no","p":0.9},{"id":"C4.reversibility","answer":"one-way","p":0.9},{"id":"C4.blastRadius","answer":"contract","p":0.9},{"id":"C4.newConcept","answer":"no","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## Session token
+
+      _critical: security_
+
+      - [ ] ./src/calc.ts#1-1 — reads the caller's token
+
+      ## Saved format
+
+      _critical: one-way door_
+
+      - [ ] ./src/calc.ts#1-2 — what callers persist
+
+      ## AC-1 ignores floating point
+
+      _should: contract_
+
+      Should subtract round? The criterion does not say.
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      - [ ] _your answer_
+
+      ## Subtract
+
+      _could_
+
+      The new export.
+      """
+    And the commit "gtd(judge): build.review.ranking → build.review.carrying" has a body containing "Gtd-Judge:"
+    And the commit subjects end with:
+      """
+      gtd(agent): build.review.reviewing → build.review.ranking
+      gtd(judge): build.review.ranking → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
+      """
+
+  Scenario: a chunk the judge is unsure about is listed as critical
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      The new export.
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## Session token
+
+      - [ ] ./src/calc.ts#1-1 — reads the caller's token
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+
+      ## Saved format
+
+      - [ ] ./src/calc.ts#1-2 — what callers persist
+      """
+    And judge step "build.review.ranking" answers:
+      """
+      [{"id":"C1.security","answer":"no","p":0.9},{"id":"C1.reversibility","answer":"two-way","p":0.9},{"id":"C1.blastRadius","answer":"local","p":0.9},{"id":"C1.newConcept","answer":"no","p":0.9},{"id":"C2.security","answer":"no","p":0.4},{"id":"C2.reversibility","answer":"two-way","p":0.9},{"id":"C2.blastRadius","answer":"local","p":0.9},{"id":"C2.newConcept","answer":"no","p":0.9},{"id":"C3.security","answer":"no","p":0.9},{"id":"C3.reversibility","answer":"two-way","p":0.9},{"id":"C3.blastRadius","answer":"contract","p":0.9},{"id":"C3.newConcept","answer":"no","p":0.9},{"id":"C4.security","answer":"no","p":0.9},{"id":"C4.reversibility","answer":"two-way","p":0.9},{"id":"C4.blastRadius","answer":"local","p":0.9},{"id":"C4.newConcept","answer":"yes","p":0.9}]
+      """
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Session token
+
+      _critical: judge unsure_
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## AC-1 ignores floating point
+
+      _should: contract_
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## Saved format
+
+      _should: new concept_
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## Subtract
+
+      _could_
+      """

package/src/workflows/feature/slice-findings.feature

@@ -71,6 +71,10 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
     And step "build.quality.closing" runs its script
     And step "build.health.check" changes nothing
     And step "build.review.carrying" runs its script
+    And judge step "build.review.ranking" answers:
+      """
+      []
+      """
 
   Scenario: a finding questioning a criterion reaches the final review, never the fixer
     Given step "build.quality.correctness.reviewing" writes ".gtd/QUALITY.md" with:
@@ -112,6 +116,8 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       """
       ## AC-1 ignores floating point
 
+      _critical: judge unsure_
+
       _From slice 1, lens correctness._
 
       Should subtract round? The criterion does not say.
@@ -120,6 +126,8 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       """
       ## AC-1 ignores floating point (2)
 
+      _critical: judge unsure_
+
       _From slice 2, lens correctness._
       """
     And the commit subjects end with:
@@ -137,7 +145,8 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       gtd(agent): build.quality.correctness.reviewing → build.quality.triage
       gtd(judge): build.quality.triage → build.quality.sorting
       gtd(check): build.quality.sorting → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(agent): build.review.reviewing → build.review.ranking
+      gtd(judge): build.review.ranking → build.review.carrying
       gtd(check): build.review.carrying → build.review.await-review
       """
 
@@ -181,6 +190,8 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       """
       ## subtract has no negative test
 
+      _critical: judge unsure_
+
       _From slice 1, lens correctness._
 
       _The fixer left this unresolved._
@@ -208,7 +219,8 @@ Feature: every slice's quality lap is triaged, and its leftovers wait for the re
       gtd(agent): build.fix.quality.fixing → build.health.check
       gtd(check): build.health.check → build.quality.closing
       gtd(check): build.quality.closing → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.carrying
+      gtd(agent): build.review.reviewing → build.review.ranking
+      gtd(judge): build.review.ranking → build.review.carrying
       gtd(check): build.review.carrying → build.review.await-review
       """
 

package/src/workflows/feature/standards.feature

@@ -92,6 +92,10 @@ Feature: the review learns standards from the human's answers
       - [ ] ./src/calc.ts#2-2 — a plain function
       """
     And step "build.review.carrying" runs its script
+    And judge step "build.review.ranking" answers:
+      """
+      []
+      """
     And judge step "build.quality.triage" answers:
       """
       [{"id":"Q1","answer":"design","p":0.9}]

package/src/workflows/shared/review.ts

@@ -70,10 +70,15 @@ interface Severity {
   readonly reason: string
   /** Capture order: 0 one-way door, 1 new concept, 2 everything else. */
   readonly rank: 0 | 1 | 2
+  readonly security?: true
 }
 
 /** Anything unanswered, unrecognised, cut or below `minP` is `critical`, never `could`. */
-export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number): Severity => {
+export const severityOf = (
+  note: { readonly id: string; readonly forced?: boolean | undefined },
+  judgment: Judgment,
+  minP: number,
+): Severity => {
   const ans = (q: string) => judgment.answers[`${note.id}.${q}`]
   const a = (q: string): string | undefined => ans(q)?.answer
   const rank = (): 0 | 1 | 2 =>
@@ -90,7 +95,12 @@ export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number):
     ...(a("reversibility") === "one-way" ? ["one-way door"] : []),
   ]
   if (critical.length > 0)
-    return { tier: "critical", reason: `critical: ${critical.join(", ")}`, rank: rank() }
+    return {
+      tier: "critical",
+      reason: `critical: ${critical.join(", ")}`,
+      rank: rank(),
+      ...(a("security") === "yes" ? { security: true as const } : {}),
+    }
   const should = [
     ...(a("blastRadius") === "contract" ? ["contract"] : []),
     ...(a("newConcept") === "yes" ? ["new concept"] : []),
@@ -100,31 +110,32 @@ export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number):
   return { tier: "could", reason: "could", rank: 2 }
 }
 
-const severityQuestions = (note: ReviewNote): JudgeQuestion[] => [
+/** `asks` names the change in full, `change` refers back to it. */
+const severityQuestions = (id: string, asks: string, change: string): JudgeQuestion[] => [
   {
-    id: `${note.id}.security`,
+    id: `${id}.security`,
     primitive: "noul",
-    instructions: `Does the change the human asks for in note "${note.id}" (on "${note.anchor}") touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
+    instructions: `Does ${asks} touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
     criteria: "yes: it changes or could weaken a security property. no: it does not.",
   },
   {
-    id: `${note.id}.reversibility`,
+    id: `${id}.reversibility`,
     primitive: "choice",
-    instructions: `Once the change in note "${note.id}" ships, can it be undone without breaking anyone who already depends on it?`,
+    instructions: `Once ${change} ships, can it be undone without breaking anyone who already depends on it?`,
     criteria:
       "one-way: a published API, file format, persisted data, protocol or other contract that cannot be taken back. two-way: can be reverted freely.",
   },
   {
-    id: `${note.id}.blastRadius`,
+    id: `${id}.blastRadius`,
     primitive: "choice",
-    instructions: `How far does the change in note "${note.id}" reach?`,
+    instructions: `How far does ${change} reach?`,
     criteria:
       "local: one function or file. module: a whole module or several files. contract: a public interface other code or users depend on.",
   },
   {
-    id: `${note.id}.newConcept`,
+    id: `${id}.newConcept`,
     primitive: "noul",
-    instructions: `Does the change in note "${note.id}" introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
+    instructions: `Does ${change} introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
     criteria: "yes: a genuinely new concept. no: reuses or extends an existing one.",
   },
 ]
@@ -144,7 +155,14 @@ const triage =
       asked.length === 0
         ? { answers: {}, truncated: [] }
         : await judge("review.triage", {
-            questions: asked.flatMap((n) => [verdictQuestion(n), ...severityQuestions(n)]),
+            questions: asked.flatMap((n) => [
+              verdictQuestion(n),
+              ...severityQuestions(
+                n.id,
+                `the change the human asks for in note "${n.id}" (on "${n.anchor}")`,
+                `the change in note "${n.id}"`,
+              ),
+            ]),
             evidence: Object.fromEntries(
               asked.map((n) => [
                 n.id,
@@ -170,6 +188,91 @@ const triage =
     )
   }
 
+/** Review order: security, one-way doors, the judge unsure, then should, then could. */
+const chunkKey = (s: Severity): number =>
+  s.tier === "could" ? 4 : s.tier === "should" ? 3 : s.security === true ? 0 : s.rank === 0 ? 1 : 2
+
+type Pointer = ReturnType<typeof reviewChunks>[number]["files"][number]
+
+/** A chunk's text, then the code each of its pointers covers: a bare path the whole file. */
+const chunkEvidence = (text: string, files: readonly Pointer[]): string =>
+  [
+    text,
+    ...files.map(({ path, line, rangeEnd }) => {
+      const where = `${path}${line === undefined ? "" : `#${line}${rangeEnd === undefined ? "" : `-${rangeEnd}`}`}`
+      const lines = read(path.replace(/^\.\//, ""))?.split("\n")
+      if (lines === undefined) return `${where}: no longer exists`
+      const code = line === undefined ? lines : lines.slice(line - 1, rangeEnd ?? line)
+      return `${where}:\n${code.join("\n")}`
+    }),
+  ].join("\n\n")
+
+const bytes = (text: string): number => new TextEncoder().encode(text).length
+
+/** Fills each batch while the budget's even share still holds its widest evidence, so nothing is cut that fits alone. */
+const batched = <T extends { readonly evidence: string }>(
+  items: readonly T[],
+  budget: number,
+): T[][] => {
+  const batches: T[][] = []
+  let batch: T[] = []
+  let widest = 0
+  for (const item of items) {
+    const size = bytes(item.evidence)
+    if (batch.length > 0 && Math.floor(budget / (batch.length + 1)) < Math.max(widest, size)) {
+      batches.push(batch)
+      batch = []
+      widest = 0
+    }
+    batch.push(item)
+    widest = Math.max(widest, size)
+  }
+  return batch.length === 0 ? batches : [...batches, batch]
+}
+
+/**
+ * Rates every chunk the reviewer wrote — a walkthrough chunk or a carried
+ * finding — and sorts \`full\` by it, each chunk led by its tier and reason.
+ * gtd's summary chunks are not rated and stay last.
+ */
+const ranked = async (review: string, full: string): Promise<string> => {
+  const texts = t.chunkTexts(full)
+  const chunks = reviewChunks(review).map((c, i) => ({
+    id: `C${i + 1}`,
+    title: c.title,
+    evidence: chunkEvidence(texts.get(c.title) ?? "", c.files),
+  }))
+  if (chunks.length === 0) return full
+  const minP = numeric(vars.reviewSeverityMinP, Infinity)
+  const batches = batched(chunks, numeric(vars.judgeBudgetBytes, 32768))
+  const severities = new Map<string, Severity>()
+  for (const [i, batch] of batches.entries()) {
+    const judgment = await judge("review.ranking", {
+      questions: batch.flatMap((c) =>
+        severityQuestions(
+          c.id,
+          `the change review chunk "${c.id}" ("${c.title}") walks through`,
+          `the change in review chunk "${c.id}"`,
+        ),
+      ),
+      evidence: Object.fromEntries(batch.map((c) => [c.id, c.evidence])),
+      message: t.reviewRankingMessage(),
+      label:
+        batches.length === 1
+          ? "Ranking the review"
+          : `Ranking the review (${i + 1}/${batches.length})`,
+    })
+    for (const c of batch) severities.set(c.id, severityOf(c, judgment, minP))
+  }
+  return t.rankedReview(
+    full,
+    chunks
+      .map((c, i) => ({ c, i, s: severities.get(c.id)! }))
+      .sort((x, y) => chunkKey(x.s) - chunkKey(y.s) || x.i - y.i)
+      .map(({ c, s }) => ({ title: c.title, label: s.reason })),
+  )
+}
+
 export const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
 
 const composedOf = (
@@ -263,18 +366,21 @@ const walkthrough = async (
 ): Promise<void> => {
   const notes = t.titledNotes(report)
   await reviewing(base, carry, lap, t.walkthroughBlock(notes, report.nitFix))
-  const review = read(REVIEW)
+  const written = read(REVIEW)
   // A review the reviewer did not write is the round's own refusal or rest.
-  if (review === undefined) return
+  if (written === undefined) return
+  const review = t.unranked(written)
+  // Against the file as written, so a refusal's line numbers match it.
   requirePointers(
-    review,
+    written,
     notes,
     changesSince(base).some((c) => isCode(c.path)),
   )
-  const full = t.withWalkthrough(review, report)
-  if (full !== review) {
+  // Ranked even when it marks risks: the review written after their fix reaches the human with its own.
+  const full = await ranked(review, t.withWalkthrough(review, report))
+  if (full !== written) {
     await run("review.carrying", writeScript(REVIEW, full), {
-      label: "Adding the quality lap's findings",
+      label: "Ordering the review and adding the quality lap's findings",
       file: REVIEW,
       base,
     })

package/src/workflows/shared/text.test.ts

@@ -33,6 +33,8 @@ import {
   titledNotes,
   walkthroughBlock,
   withWalkthrough,
+  rankedReview,
+  unranked,
 } from "./text.js"
 import { reviewDecisions, steeringFormatFor, unansweredNotes } from "../../steering/index.js"
 import { captureStep, renderText } from "./text.fixture.js"
@@ -1517,3 +1519,91 @@ describe("walkthrough", () => {
     )
   })
 })
+
+describe("rankedReview", () => {
+  const review = [
+    "# Review: abc1234",
+    "",
+    "<!-- base: abc1234 -->",
+    "",
+    "## Rename",
+    "",
+    "- [ ] ./a.ts#1-1",
+    "",
+    "## Token",
+    "",
+    "_could_",
+    "",
+    "Reads the token.",
+    "",
+    "- [ ] ./a.ts#2-2",
+    "",
+    "## Fixed automatically",
+    "",
+    "- x (abc1234)",
+    "",
+  ].join("\n")
+
+  it("puts the ranked chunks first, each led by its tier, and leaves the rest in place", () => {
+    expect(
+      rankedReview(unranked(review), [
+        { title: "Token", label: "critical: security" },
+        { title: "Rename", label: "could" },
+      ]),
+    ).toBe(
+      [
+        "# Review: abc1234",
+        "",
+        "<!-- base: abc1234 -->",
+        "",
+        "## Token",
+        "",
+        "_critical: security_",
+        "",
+        "Reads the token.",
+        "",
+        "- [ ] ./a.ts#2-2",
+        "",
+        "## Rename",
+        "",
+        "_could_",
+        "",
+        "- [ ] ./a.ts#1-1",
+        "",
+        "## Fixed automatically",
+        "",
+        "- x (abc1234)",
+        "",
+      ].join("\n"),
+    )
+  })
+
+  it("keeps a setext heading whole", () => {
+    expect(
+      rankedReview("# Review: a\n\nToken\n-----\n\n- [ ] ./a.ts#1\n", [
+        { title: "Token", label: "could" },
+      ]),
+    ).toBe("# Review: a\n\nToken\n-----\n\n_could_\n\n- [ ] ./a.ts#1\n")
+  })
+
+  it("keeps a chunk's leading indented code block indented", () => {
+    const code = "# Review: abc1234\n\n## Code\n\n    const x = 1\n\n- [ ] ./a.ts#1-1\n"
+    expect(rankedReview(code, [{ title: "Code", label: "could" }])).toContain(
+      "_could_\n\n    const x = 1",
+    )
+  })
+
+  it("drops a stale tier with no blank line under the heading, never a longer paragraph", () => {
+    expect(unranked("## A\n_could_\n\nbody\n")).toBe("## A\nbody\n")
+    expect(unranked("## A\n\n_could_\n- [ ] ./a.ts#1\n")).toBe("## A\n\n- [ ] ./a.ts#1\n")
+    const code = "## A\n\n    _could_\n"
+    expect(unranked(code)).toBe(code)
+    const prose = "## A\n\n_should: x_\nruns on\n"
+    expect(unranked(prose)).toBe(prose)
+  })
+
+  it("drops a stale tier, so a re-review is ranked afresh", () => {
+    expect(unranked(review)).not.toContain("_could_")
+    expect(unranked(unranked(review))).toBe(unranked(review))
+  })
+})

package/src/workflows/shared/text.ts

@@ -19,6 +19,7 @@ import {
   ANSWER_WONT_FIX,
   FREE_TEXT_PLACEHOLDER,
   reviewChunks,
+  severityLine,
 } from "../../steering/index.js"
 import { escapeRegExp } from "./registry.js"
 import {
@@ -301,12 +302,78 @@ export const withWalkthrough = (review: string, report: ComposedReview): string
           `## ${unique("Dropped as noise")}\n\n${report.noise.map((f) => noiseLine(f, carriedOnly(f))).join("\n")}`,
         ]),
   ]
-  // Nothing to add leaves the review byte for byte, so no carrying step runs.
+  // Nothing to add leaves the review byte for byte.
   if (notes.size === listed && summary.length === 0) return review
   const body = lines.join("\n").trimEnd()
   return summary.length === 0 ? `${body}\n` : `${body}\n\n${summary.join("\n\n")}\n`
 }
 
+export interface RankedChunk {
+  readonly title: string
+  readonly label: string
+}
+
+const chunkBlocks = (
+  review: string,
+): { head: string[]; blocks: { title: string; lines: string[] }[] } => {
+  const lines = review.split("\n")
+  const chunks = reviewChunks(review)
+  return {
+    head: lines.slice(0, chunks[0]?.line ?? lines.length),
+    blocks: chunks.map((c, i) => ({
+      title: c.title,
+      lines: lines.slice(c.line, chunks[i + 1]?.line ?? lines.length),
+    })),
+  }
+}
+
+const isBlank = (line: string | undefined): boolean => line !== undefined && line.trim() === ""
+
+/** \`review\` with every chunk's severity line removed, so a re-review is ranked afresh. */
+export const unranked = (review: string): string => {
+  const drop = new Set(reviewChunks(review).flatMap((c) => c.severityLine ?? []))
+  if (drop.size === 0) return review
+  const lines = review.split("\n")
+  return lines.filter((_, i) => !drop.has(i) && !(drop.has(i - 1) && isBlank(lines[i]))).join("\n")
+}
+
+export const chunkTexts = (review: string): ReadonlyMap<string, string> =>
+  new Map(chunkBlocks(review).blocks.map((b) => [b.title, b.lines.join("\n").trim()]))
+
+// Blank lines only: a chunk opening with an indented code block keeps its indent.
+const trimBlankLines = (lines: readonly string[]): string[] => {
+  let start = 0
+  let end = lines.length
+  while (start < end && isBlank(lines[start])) start++
+  while (end > start && isBlank(lines[end - 1])) end--
+  return lines.slice(start, end)
+}
+
+/**
+ * \`review\` with the \`ranked\` chunks first, in their order, each led by its
+ * severity line; every other chunk follows in place.
+ */
+export const rankedReview = (review: string, ranked: readonly RankedChunk[]): string => {
+  const { head, blocks } = chunkBlocks(review)
+  const place = new Map(ranked.map((r, k) => [r.title, k]))
+  const labels = new Map(ranked.map((r) => [r.title, r.label]))
+  const order = (i: number): number => place.get(blocks[i]!.title) ?? ranked.length
+  const chunk = (i: number): string => {
+    const { title, lines } = blocks[i]!
+    const label = labels.get(title)
+    // A setext heading is its title line and its underline.
+    const heading = /^ {0,3}-+\s*$/.test(lines[1] ?? "") ? 2 : 1
+    const body = trimBlankLines(lines.slice(heading)).join("\n")
+    return [
+      lines.slice(0, heading).join("\n"),
+      ...(label === undefined ? [] : [severityLine(label)]),
+      ...(body === "" ? [] : [body]),
+    ].join("\n\n")
+  }
+  const sorted = blocks.map((_, i) => i).sort((x, y) => order(x) - order(y) || x - y)
+  return `${[head.join("\n").trim(), ...sorted.map(chunk)].filter((p) => p !== "").join("\n\n")}\n`
+}
+
 /**
  * \`.gtd/REVIEW.md\` as gtd writes it: one chunk per note, each ending in its
  * answer boxes, then the fixed and noise lists. Chunk titles are made unique —
@@ -1074,6 +1141,15 @@ const wrapItem = (item: string): string[] => {
   return [...out, line]
 }
 
+export const reviewRankingMessage = (): string =>
+  `Ranking each chunk of the review before the human reads it. Run
+\`gtd judge answer\` and pipe, per chunk \`C<n>\`: \`C<n>.security\`
+(yes/no), \`C<n>.reversibility\` (one-way/two-way),
+\`C<n>.blastRadius\` (local/module/contract) and \`C<n>.newConcept\`
+(yes/no) — or land without a verdict, which lists every chunk as
+critical.
+`
+
 export const buildReviewTriageMessage = (): string =>
   `Judging each note the human added to \`.gtd/REVIEW.md\` (a line note, a
 footnote, or prose under a chunk) with one verdict: \`edit\` (a change