@pmelab/gtd 49.0.0 → 50.0.0

package/src/steering/review.ts

@@ -77,6 +77,8 @@ interface Changeset {
   readonly headingLine: number
   /** The chunk's answer boxes, when gtd gave it some. */
   readonly answers?: readonly AnswerOption[]
+  /** The tier and reason gtd ranked the chunk with, from its leading severity line. */
+  readonly severity?: { readonly label: string; readonly line: number }
 }
 
 interface AnswerOption {
@@ -89,6 +91,10 @@ export const ANSWER_LEAD = "Tick exactly one:"
 export const ANSWER_FIX = "fix as suggested"
 export const ANSWER_WONT_FIX = "won't fix"
 
+/** A chunk's leading `_critical: security_` paragraph: the tier gtd ranked it with, and why. */
+const SEVERITY_LINE_RE = /^_((?:critical|should|could)(?::[^_\n]*)?)_$/
+export const severityLine = (label: string): string => `_${label}_`
+
 interface ReviewDoc {
   readonly shortHash?: string
   readonly fullHash?: string
@@ -521,6 +527,26 @@ const answerListOf = (
   return { lead, list, options }
 }
 
+/** A leading severity line is the chunk's tier, never its prose. */
+const splitSeverity = (
+  content: string,
+  run: readonly RootContent[],
+): {
+  readonly severity?: { readonly label: string; readonly line: number } | undefined
+  readonly leadingRun: readonly RootContent[]
+} => {
+  const first = run[0]
+  const label =
+    first?.type === "paragraph"
+      ? SEVERITY_LINE_RE.exec(sourceText(content, first).trim())?.[1]
+      : undefined
+  if (label === undefined) return { leadingRun: run }
+  return {
+    severity: { label, line: toLspPosition(first!.position!.start).line },
+    leadingRun: run.slice(1),
+  }
+}
+
 /** Splits one chunk's body nodes into its file pointers (hunk pointers are task items, collected recursively at ANY nesting depth via `taskItems` — a nested hunk is the same kind of hunk as a top-level one) and description prose. The description is the chunk's own leading run and never a node that contains a hunk pointer: it stops at the first node whose `taskItems` include a real pointer (at any depth — a blockquote wrapping a pointer list stops it just as a top-level list would). Every node kind in what's left before that point contributes — a `footnoteDefinition` is the one exception, excluded by `blockNodesOfRun` itself (it's a note, never document content). */
 const parseChunkBody = (
   content: string,
@@ -534,6 +560,7 @@ const parseChunkBody = (
   readonly files: readonly ReviewFile[]
   readonly errors: readonly SteeringFinding[]
   readonly answers?: readonly AnswerOption[]
+  readonly severity?: { readonly label: string; readonly line: number } | undefined
   /** Whether a task box outside the answer list exists. */
   readonly boxed: boolean
 } => {
@@ -543,9 +570,10 @@ const parseChunkBody = (
   const firstPointerIndex = body.findIndex(
     (n) => !isAnswer(n) && taskItems(n).some((item) => hasPointerToken(content, item)),
   )
-  const leadingRun = (firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)).filter(
+  const run = (firstPointerIndex === -1 ? body : body.slice(0, firstPointerIndex)).filter(
     (n) => !isAnswer(n),
   )
+  const { severity, leadingRun } = splitSeverity(content, run)
   const descriptionNodes = blockNodesOfRun(content, leadingRun)
   const descriptionInline = collapseImages(blockRunInline(content, leadingRun))
   const description = leadingRun
@@ -569,6 +597,7 @@ const parseChunkBody = (
     files,
     errors,
     ...(answer === undefined ? {} : { answers: answer.options }),
+    ...(severity === undefined ? {} : { severity }),
     boxed: body.some((n) => !isAnswer(n) && taskItems(n).length > 0),
   }
 }
@@ -618,6 +647,7 @@ const parseChangesets = (
       descriptionInline,
       files,
       answers,
+      severity,
       boxed,
       errors: bodyErrors,
     } = parseChunkBody(content, lines, title, body)
@@ -638,6 +668,7 @@ const parseChangesets = (
       files,
       headingLine,
       ...(answers === undefined ? {} : { answers }),
+      ...(severity === undefined ? {} : { severity }),
     })
   }
   if (changesets.length === 0) errors.push({ message: "REVIEW.md has no '##' chunks" })
@@ -997,6 +1028,7 @@ const reviewView = (content: string): SteeringView => {
       detail: chunk.description,
       detailInline: chunk.descriptionInline,
       body: chunk.descriptionNodes,
+      ...(chunk.severity === undefined ? {} : { status: chunk.severity.label }),
       anchor: { kind: "chunk", index: chunkIndex },
       ...noteAt(chunk.headingLine),
       children: chunk.files.map((file, index) => ({
@@ -1177,11 +1209,22 @@ const pointerLabel = (f: ReviewFile): string =>
 
 type Found = { line: number; note: Omit<ReviewNote, "id" | "forced"> }
 
-// A chunk added with its own answer boxes (a driver's imported note) is
-// answered by its tick, never judged as prose as well.
-const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
-  chunk.description === (prior?.description ?? "") ||
-  (prior === undefined && chunk.answers !== undefined)
+// Rewording a tier disputes it, so a changed tier joins the note — after the
+// prose, so a leading `!` still forces; deleting one asks nothing.
+const chunkProse = (chunk: Changeset | undefined, retiered: boolean): string =>
+  [
+    chunk?.description ?? "",
+    retiered && chunk?.severity !== undefined ? severityLine(chunk.severity.label) : "",
+  ]
+    .filter((p) => p !== "")
+    .join("\n\n")
+
+const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] => {
+  const retiered = chunk.severity !== undefined && chunk.severity.label !== prior?.severity?.label
+  // A chunk added with its own answer boxes (a driver's imported note) is
+  // answered by its tick, never judged as prose as well.
+  return chunkProse(chunk, retiered) === chunkProse(prior, retiered) ||
+    (prior === undefined && chunk.answers !== undefined)
     ? []
     : [
         {
@@ -1189,11 +1232,12 @@ const chunkNote = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
           note: {
             kind: "chunk",
             anchor: chunk.title,
-            before: prior?.description ?? "",
-            text: chunk.description,
+            before: chunkProse(prior, retiered),
+            text: chunkProse(chunk, retiered),
           },
         },
       ]
+}
 
 const pointerNotes = (chunk: Changeset, prior: Changeset | undefined): Found[] =>
   chunk.files.flatMap((file): Found[] => {
@@ -1342,9 +1386,22 @@ export const reviewDecisions = (before: string, after: string): readonly ReviewD
 /** Each `##` chunk in document order: its title, 0-based heading line and how many hunk pointers it holds. */
 export const reviewChunks = (
   content: string,
-): readonly { title: string; line: number; pointers: number }[] =>
+): readonly {
+  title: string
+  line: number
+  pointers: number
+  /** 0-based line of the chunk's severity line, when it has one. */
+  severityLine?: number
+  files: readonly { path: string; line?: number; rangeEnd?: number }[]
+}[] =>
   parseReviewDoc(content).changesets.map((c) => ({
     title: c.title,
     line: c.headingLine,
     pointers: c.files.length,
+    ...(c.severity === undefined ? {} : { severityLine: c.severity.line }),
+    files: c.files.map((f) => ({
+      path: f.path,
+      ...(f.line === undefined ? {} : { line: f.line }),
+      ...(f.rangeEnd === undefined ? {} : { rangeEnd: f.rangeEnd }),
+    })),
   }))

package/src/workflows/feature/lens-review.feature

@@ -75,6 +75,10 @@ Feature: the quality lap's findings are triaged before the review
     And step "build.quality.sorting" runs its script
     And step "build.quality.closing" runs its script
     And step "build.review.carrying" runs its script
+    And judge step "build.review.ranking" answers:
+      """
+      []
+      """
 
   Scenario: a mechanical finding is fixed and listed, noise dropped and listed, a design one noted
     Given judge step "build.quality.triage" answers:
@@ -110,6 +114,8 @@ Feature: the quality lap's findings are triaged before the review
       """
       ## AC-1 ignores floating point
 
+      _critical: judge unsure_
+
       Should subtract round? The criterion does not say.
 
       In the code:
@@ -147,7 +153,8 @@ Feature: the quality lap's findings are triaged before the review
       gtd(check): build.quality.sorting → build.fix.quality.fixing
       gtd(agent): build.fix.quality.fixing → build.health.check
       gtd(check): build.health.check → 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
       """
 
@@ -189,7 +196,8 @@ Feature: the quality lap's findings are triaged before the review
       """
       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
       """
 
@@ -228,6 +236,8 @@ Feature: the quality lap's findings are triaged before the review
       """
       ## add could be a method
 
+      _critical: judge unsure_
+
       _The fixer left this unresolved._
 
       A class would read better.
@@ -242,7 +252,8 @@ Feature: the quality lap's findings are triaged before the review
       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
       """
 
@@ -344,7 +355,8 @@ Feature: the quality lap's findings are triaged before the review
     And ".gtd/REVIEW.md" does not exist
     And the commit subjects end with:
       """
-      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
       gtd(human): build.review.await-review → build.review.closing
       gtd(check): build.review.closing → idle

package/src/workflows/feature/review-answers.feature

@@ -109,6 +109,10 @@ Feature: every note in the review is answered with one tick
       - [ ] ./src/calc.ts#2-2 — now rounds the difference
       """
     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":"noise","p":0.9},{"id":"Q2","answer":"noise","p":0.9},{"id":"Q3","answer":"design","p":0.9}]
@@ -122,6 +126,8 @@ Feature: every note in the review is answered with one tick
       """
       ## AC-1 ignores floating point
 
+      _critical: judge unsure_
+
       Should subtract round? The criterion does not say.
 
       In the code:
@@ -215,7 +221,8 @@ Feature: every note in the review is answered with one tick
       gtd(agent): build.review.fix.nits.fixing → build.health.check
       gtd(check): build.health.check → build.review.closing
       gtd(check): build.review.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
       """
     And ".gtd/REVIEW.md" does not contain "AC-1 ignores floating point"

package/src/workflows/feature/review-gate.feature

@@ -69,6 +69,11 @@ Feature: a feature process ends at the human review
         new subtract function
       """
     And step "build.review.closing" runs its script
+    And step "build.review.carrying" runs its script
+    And judge step "build.review.ranking" answers:
+      """
+      []
+      """
 
   Scenario: a feature process ends at the review gate
     When the process is driven
@@ -79,7 +84,9 @@ Feature: a feature process ends at the human review
       """
       gtd(judge): implement.coverage → implement.closing
       gtd(check): implement.closing → build.review.reviewing
-      gtd(agent): build.review.reviewing → build.review.await-review
+      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 sign-off ends the process at idle
@@ -93,6 +100,8 @@ Feature: a feature process ends at the human review
 
       ## calc
 
+      _critical: judge unsure_
+
       - [x] ./src/calc.ts#2-2
         new subtract function
       """
@@ -102,7 +111,9 @@ Feature: a feature process ends at the human review
     And ".gtd/REVIEW.md" does not exist
     And the commit subjects end with:
       """
-      gtd(agent): build.review.reviewing → build.review.await-review
+      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
       gtd(human): build.review.await-review → build.review.closing
       gtd(check): build.review.closing → idle
       """
@@ -146,6 +157,8 @@ Feature: a feature process ends at the human review
 
         ## calc
 
+        _critical: judge unsure_
+
         - [ ] ./src/calc.ts#2-2
           new subtract function[^why]
 
@@ -164,6 +177,8 @@ Feature: a feature process ends at the human review
 
         ## calc
 
+        _critical: judge unsure_
+
         - [ ] ./src/calc.ts#2-2
           new subtract function
         """
@@ -215,7 +230,9 @@ Feature: a feature process ends at the human review
         gtd(check): implement.health.check → implement.coverage
         gtd(judge): implement.coverage → implement.closing
         gtd(check): implement.closing → build.review.reviewing
-        gtd(agent): build.review.reviewing → build.review.await-review
+        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 design numbering new behaviour at or below an earlier ID is refused

package/src/workflows/feature/reviewer-walkthrough.feature

@@ -67,6 +67,10 @@ Feature: a reviewer walks the human through the feature's code
     And step "build.quality.sorting" runs its script
     And step "build.quality.closing" runs its script
     And step "build.review.carrying" runs its script
+    And judge step "build.review.ranking" answers:
+      """
+      []
+      """
 
   Scenario: the finding gets its text and answer boxes under the reviewer's pointers
     Given step "build.review.reviewing" is prompted with "- `## AC-1 ignores floating point`:"
@@ -93,12 +97,16 @@ Feature: a reviewer walks the human through the feature's code
       """
       ## Subtract
 
+      _critical: judge unsure_
+
       The new export.
 
       - [ ] ./src/calc.ts#2-2 — subtract(a, b)
 
       ## AC-1 ignores floating point
 
+      _critical: judge unsure_
+
       Should subtract round? The criterion does not say.
 
       In the code:
@@ -114,7 +122,8 @@ Feature: a reviewer walks the human through the feature's code
     And no commit body contains "build.review.composing"
     And the commit subjects end with:
       """
-      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
       """
 
@@ -169,11 +178,13 @@ Feature: a reviewer walks the human through the feature's code
     Then the process rests at "build.review.await-review"
     And the commit subjects end with:
       """
-      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.fix.risks.fixing
       gtd(agent): build.review.fix.risks.fixing → build.health.check
       gtd(check): build.health.check → 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/severity-budget.feature

@@ -0,0 +1,111 @@
+@inmem
+Feature: the review's ranking is batched to the judge's budget
+
+  `build.review.ranking` puts as many chunks in one judgment as the budget's
+  even share still holds whole; the rest go to the next. A chunk too big to
+  fit even alone is cut, and a cut chunk is critical.
+
+  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 an environment variable "GTD_JUDGEBUDGETBYTES" set to "150"
+    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: a chunk the budget cuts is listed as critical, the others judged in batches of their own
+    Given step "build.review.reviewing" writes ".gtd/REVIEW.md" with:
+      """
+      # Review: abc1234
+
+      <!-- base: 0000000 -->
+
+      ## Subtract
+
+      - [ ] ./src/calc.ts#2-2 — subtract(a, b)
+
+      ## AC-1 ignores floating point
+
+      - [ ] ./src/calc.ts#2-2 — returns the raw difference
+      """
+    And judge step "build.review.ranking", when its questions contain "C1.security", 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}]
+      """
+    And judge step "build.review.ranking", when its questions contain "C2.security", answers:
+      """
+      [{"id":"C2.security","answer":"no","p":0.9},{"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}]
+      """
+    When the process is driven
+    Then the process rests at "build.review.await-review"
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## AC-1 ignores floating point
+
+      _critical: judge unsure_
+      """
+    And ".gtd/REVIEW.md" contains:
+      """
+      ## Subtract
+
+      _could_
+      """
+    And the commit subjects end with:
+      """
+      gtd(agent): build.review.reviewing → build.review.ranking
+      gtd(judge): build.review.ranking
+      gtd(judge): build.review.ranking → build.review.carrying
+      gtd(check): build.review.carrying → build.review.await-review
+      """