@pmelab/gtd 49.0.0 → 51.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "49.0.0",
+  "version": "51.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/steering/index.ts

@@ -16,6 +16,7 @@ export {
   reviewDecisions,
   reviewNotes,
   reviewRisks,
+  severityLine,
   unansweredNotes,
   type ReviewChoice,
   type ReviewDecision,

package/src/steering/review.test.ts

@@ -1276,6 +1276,33 @@ describe("review.view", () => {
     expect(view.nodes[1]!.detail).toBe("")
   })
 
+  it("shows a chunk's leading severity line as its status, not its prose", () => {
+    const view = review.view(
+      [
+        "# Review: abc1234",
+        "",
+        "## Ranked",
+        "",
+        "_critical: security, one-way door_",
+        "",
+        "The new export.",
+        "",
+        "- [ ] ./a.ts#1-1",
+        "",
+        "## Unranked",
+        "",
+        "_emphasis, not a tier_",
+        "",
+        "- [ ] ./a.ts#2-2",
+        "",
+      ].join("\n"),
+    )
+    expect(view.nodes.map((c) => [c.status, c.detail])).toEqual([
+      ["critical: security, one-way door", "The new export."],
+      [undefined, "_emphasis, not a tier_"],
+    ])
+  })
+
   it("is built from one parse of the document, not one per element", () => {
     const uniqueContent = [
       "# Review: def4567",
@@ -1706,6 +1733,29 @@ describe("reviewNotes", async () => {
     expect(reviewNotes(base, base)).toEqual([])
   })
 
+  it("an edited tier line is a note", () => {
+    const was = doc("_could_\n\nProse.")
+    const after = doc("_critical: this leaks the token_\n\nProse.")
+    expect(reviewNotes(was, after)).toMatchObject([
+      {
+        kind: "chunk",
+        before: "Prose.\n\n_could_",
+        text: "Prose.\n\n_critical: this leaks the token_",
+      },
+    ])
+  })
+
+  it("prose added under a tier is the human's alone, and a leading ! still forces", () => {
+    const was = doc("_could_\n\nProse.")
+    expect(reviewNotes(was, doc("_could_\n\n! Not here.\n\nProse."))).toMatchObject([
+      { kind: "chunk", text: "! Not here. Prose.", forced: true },
+    ])
+  })
+
+  it("a deleted tier line asks nothing", () => {
+    expect(reviewNotes(doc("_could_\n\nProse."), base)).toEqual([])
+  })
+
   it("a pointer note added", () => {
     const after = doc("Prose.").replace("#1-3", "#1-3 rename this")
     expect(reviewNotes(base, after)).toEqual([
@@ -1863,8 +1913,16 @@ describe("reviewChunks", async () => {
       "- [ ] _your answer_",
     ].join("\n")
     expect(reviewChunks(content)).toEqual([
-      { title: "Walkthrough", line: 4, pointers: 2 },
-      { title: "Fixed automatically", line: 9, pointers: 0 },
+      {
+        title: "Walkthrough",
+        line: 4,
+        pointers: 2,
+        files: [
+          { path: "./src/a.ts", line: 1, rangeEnd: 3 },
+          { path: "./src/b.ts", line: 4, rangeEnd: 6 },
+        ],
+      },
+      { title: "Fixed automatically", line: 9, pointers: 0, files: [] },
     ])
   })
 })

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/coverage.feature

@@ -9,6 +9,7 @@ Feature: a feature is done only when every acceptance criterion has a passing te
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to ""
     And an environment variable "GTD_FLAGMODE" set to "false"
     And a file "src/calc.ts" with:

package/src/workflows/feature/fast-path.feature

@@ -8,6 +8,7 @@ Feature: a trivial change takes the same few beats at either risk tier
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
     And an environment variable "GTD_FLAG_RISK_TIER" set to "1"
     And a file "src/greeting.ts" with:

package/src/workflows/feature/feature.ts

@@ -28,6 +28,7 @@ import {
 } from "./criteria.js"
 import { design } from "./planning.js"
 import { buildTail, humanReview, isCode, reUnwind, type ReviewOutcome } from "../shared/review.js"
+import { prototypeRounds } from "./prototype.js"
 import { implement, implementing, seamBuild } from "./seam.js"
 import { sliceCap, sliceCriteria, slicing } from "./slicing.js"
 import { recordRisk, riskTierOn, type RiskTier } from "./tier.js"
@@ -36,7 +37,8 @@ import { recordRisk, riskTierOn, type RiskTier } from "./tier.js"
 // `unwind` reverts the sketch (its intent survives in history) → a
 // green-baseline gate → design → per slice of the criteria, a naive pass,
 // judged with `flagMode` on: it lands as the implementation, or (refactoring
-// first when the judge asks) is built fresh from → the health loop → the
+// first when the judge asks) is built fresh from → the health loop → a
+// hands-on test of every criterion, fixed and re-tested → the
 // triaged quality lap, whose leftovers are carried on → after the last slice,
 // a reviewer's walkthrough of the whole change, every slice's findings
 // among its chunks, for the human, which
@@ -227,6 +229,7 @@ export const ordinaryStart = async (): Promise<void> => {
   // Read right after idle, so a bad value refuses the landing that would pin it.
   flagModeOn()
   sliceCap()
+  prototypeRounds()
   const stated = statedCriteria(changes(), head())
   await unwind()
   if (changes(FEEDBACK).some((c) => c.status !== "deleted")) {

package/src/workflows/feature/flag-mode.feature

@@ -11,7 +11,7 @@ Feature: flag mode off lands the naive pass with no release flag, seam judge or
       """
       import { feature } from "@pmelab/gtd/workflows/feature"
       export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
-      export default feature({ flagMode: false })
+      export default feature({ flagMode: false, prototypeRounds: "0" })
       """
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
     And a file "src/calc.ts" with:

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

@@ -12,6 +12,7 @@ Feature: each quality lens runs on its own model hint
       export { summary, steering, skills, access } from "@pmelab/gtd/workflows/feature"
       export default feature({
         flagMode: false,
+        prototypeRounds: "0",
         qualityReviews: "correctness, conventions, test-audit=opus",
       })
       """

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

@@ -9,6 +9,7 @@ Feature: the quality lap's findings are triaged before the review
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     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:
@@ -75,6 +76,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 +115,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 +154,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 +197,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 +237,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 +253,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 +356,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/one-step-land.feature

@@ -10,6 +10,7 @@ Feature: a naive pass the judge rules land is itself the implementation
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
+    And an environment variable "GTD_PROTOTYPEROUNDS" set to "0"
     And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
     And an environment variable "GTD_FLAG_RISK_TIER" set to "0"
     And a file "src/greeting.ts" with:

package/src/workflows/feature/prototype-rounds.feature

@@ -0,0 +1,152 @@
+@inmem
+Feature: past its round cap the hands-on test rests at a person's gate
+
+  `prototypeRounds` caps the fix turns a slice's hands-on test gets. Once they
+  are spent and the report still has open items, the process rests at
+  implement.prototype.open naming them; a person's fix there is tested again
+  with a fresh budget.
+
+  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_PROTOTYPEROUNDS" set to "1"
+    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.
+      - AC-2: add is unchanged.
+      """
+    And step "design.gate.answer" changes nothing
+    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.naive" writes "src/calc.test.ts" with:
+      """
+      it("[AC-1] subtracts", () => expect(subtract(3, 1)).toBe(2))
+      it("[AC-2] adds", () => expect(add(1, 1)).toBe(2))
+      """
+    And step "seam.check" changes nothing
+    And step "implement.applying" runs its script
+    And step "implement.health.check" changes nothing
+    And judge step "implement.coverage" answers:
+      """
+      [{"id":"AC-1","answer":"yes","p":0.9},{"id":"AC-2","answer":"yes","p":0.9}]
+      """
+    And step "implement.closing" runs its script
+
+  Scenario: past the round cap a person is asked, naming the open items
+    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
+      """
+      ## AC-1: fail
+
+      `subtract(3, 1)` printed 4. Expected 2.
+
+      ## AC-2: pass
+
+      Printed 2.
+      """
+    And step "implement.prototype.testing", when prompted with "This is a re-test", writes ".gtd/PROTOTYPE.md" with:
+      """
+      ## AC-1: fail
+
+      Re-tested: `subtract(3, 1)` printed -2. Expected 2.
+
+      ## AC-2: pass
+
+      Printed 2.
+      """
+    And step "implement.prototype.fix.fixing" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => b - a
+      """
+    And step "implement.prototype.health.check" changes nothing
+    When the process is driven
+    Then the process rests at "implement.prototype.open"
+    And the resting step's content contains "- AC-1: fail"
+    And the resting step's content contains "after 1 fix round"
+    And the resting step's content does not contain "AC-2"
+
+  Scenario: a person's change at the gate is tested again
+    Given step "implement.prototype.testing", when prompted with "Find how this project", writes ".gtd/PROTOTYPE.md" with:
+      """
+      ## AC-1: blocked
+
+      `subtract` is not exported from any entry point I could run.
+
+      ## AC-2: pass
+
+      Printed 2.
+      """
+    And step "implement.prototype.open" 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 "implement.prototype.health.check" changes nothing
+    And step "implement.prototype.testing", when prompted with "This is a re-test", writes ".gtd/PROTOTYPE.md" with:
+      """
+      ## AC-1: pass
+
+      `subtract(3, 1)` printed 2.
+
+      ## AC-2: pass
+
+      Printed 2.
+      """
+    When the process is driven
+    Then the process rests at "build.quality.correctness.reviewing"
+    And the commit subjects end with:
+      """
+      gtd(agent): implement.prototype.testing → implement.prototype.open
+      gtd(human): implement.prototype.open → implement.prototype.health.check
+      gtd(check): implement.prototype.health.check → implement.prototype.testing
+      gtd(agent): implement.prototype.testing → implement.closing
+      gtd(check): implement.closing → build.quality.correctness.reviewing
+      """
+
+  Scenario: a re-test that sees exactly what the last round saw still ends the round
+    Given step "implement.prototype.testing" writes ".gtd/PROTOTYPE.md" with:
+      """
+      ## AC-1: fail
+
+      `subtract(3, 1)` printed 4. Expected 2.
+
+      ## AC-2: pass
+
+      Printed 2.
+      """
+    And step "implement.prototype.fix.fixing" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      export const subtract = (a: number, b: number) => b - a
+      """
+    And step "implement.prototype.health.check" changes nothing
+    When the process is driven
+    Then the process rests at "implement.prototype.open"
+    And the commit subjects end with:
+      """
+      gtd(agent): implement.prototype.testing → implement.prototype.fix.fixing
+      gtd(agent): implement.prototype.fix.fixing → implement.prototype.health.check
+      gtd(check): implement.prototype.health.check → implement.prototype.testing
+      gtd(agent): implement.prototype.testing → implement.prototype.open
+      """