@pmelab/gtd 17.0.0 → 17.2.0

package/src/workflows/review.ts

@@ -17,7 +17,7 @@ import {
   type Change,
   type JudgeQuestion,
 } from "../flows/index.js"
-import { reviewNotes, stripCodeThreads, type ReviewNote } from "../steering/index.js"
+import { reviewNotes, reviewRisks, stripCodeThreads, type ReviewNote } from "../steering/index.js"
 import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
 import {
   answerReviewQuestions,
@@ -26,6 +26,7 @@ import {
   fix,
   fixNits,
   fixQuality,
+  fixRisks,
   QUALITY,
   REQUIREMENTS,
   REVIEW,
@@ -43,8 +44,8 @@ export const qualityLenses = (): readonly string[] =>
     .filter((lens) => lens.length > 0)
 
 /**
- * One review turn per lens over the whole change, each appending what it
- * finds blocking to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
+ * One review turn per lens over the whole change, each appending every
+ * finding to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
  * has any.
  */
 export const qualityLap = async (): Promise<"clean" | "findings"> => {
@@ -270,6 +271,20 @@ const finish = async (
   return routeNotes(notes, { round, escalations, close, outcome, unfolded })
 }
 
+/** Write the review; if it marks risks, fix them, keep green, and write it again — once, so the re-review's own risks reach the human unfixed. */
+const reviewOnce = async (
+  base: string,
+  carry: string | undefined,
+  escalations: EscalationCount,
+): Promise<void> => {
+  await reviewing(base, carry)
+  const risks = reviewRisks(read(REVIEW) ?? "")
+  if (risks.length === 0) return
+  await fixRisks(risks)
+  await healthy(fix, { escalations })
+  await reviewing(base, carry)
+}
+
 /**
  * A reviewer writes `.gtd/REVIEW.md` over everything since `base`, a human
  * reviews and signs off or comments, and each note is judged: edits go to
@@ -282,7 +297,7 @@ export const review = async (
 ): Promise<ReviewOutcome> => {
   let carry: string | undefined
   for (;;) {
-    await reviewing(base, carry)
+    await reviewOnce(base, carry, escalations)
     carry = undefined
     let reviewed = head()
     let collectedAt: string | undefined

package/src/workflows/skills.test.ts

@@ -26,7 +26,7 @@ import { skills } from "./skills.js"
 //   - build.review.answer-review-questions, build.review.fix-nits — NOT yet
 //     e2e-grounded; only steps.test.ts's preamble checks, which use local names
 describe("the bundled workflow's skills map", () => {
-  it("declares exactly the sixteen bundled agent steps, by full name", () => {
+  it("declares exactly the seventeen bundled agent steps, by full name", () => {
     expect(Object.keys(skills).sort()).toEqual(
       [
         "design.triage",
@@ -44,6 +44,7 @@ describe("the bundled workflow's skills map", () => {
         "build.review.reviewing",
         "build.review.answer-review-questions",
         "build.review.fix-nits",
+        "build.review.fix-risks",
         "build.review.collecting",
       ].sort(),
     )

package/src/workflows/skills.ts

@@ -33,5 +33,6 @@ export const skills: Readonly<Record<string, readonly string[]>> = {
   "build.review.reviewing": ["code-review-and-quality"],
   "build.review.answer-review-questions": ["code-review-and-quality"],
   "build.review.fix-nits": ["incremental-implementation", "code-simplification"],
+  "build.review.fix-risks": ["debugging-and-error-recovery", "incremental-implementation"],
   "build.review.collecting": ["code-review-and-quality"],
 }

package/src/workflows/steps.test.ts

@@ -91,6 +91,46 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(prompt).toContain("owasp-security")
   })
 
+  it("correctness loads code-review-and-quality and carries all four trace points", async () => {
+    const request = await capture(() => steps.reviewQuality("correctness"))
+    expect(agentSkillsOption(request)).toEqual(["code-review-and-quality"])
+    const body = JSON.stringify(request)
+    for (const point of [
+      "partial-failure",
+      "format, not just its presence",
+      "parallel write paths",
+      "contract test",
+    ])
+      expect(body).toContain(point)
+  })
+
+  it.each(["conventions", "spec-challenge"])(
+    "%s sends no skills and carries its brief",
+    async (lens) => {
+      const request = await capture(() => steps.reviewQuality(lens))
+      expect(agentSkillsOption(request)).toEqual([])
+      expect(JSON.stringify(request)).toContain(
+        steps.builtInLenses[lens]!.brief.split("\n")[0]!.slice(0, 40),
+      )
+    },
+  )
+
+  it("an unknown lens loads itself as a skill, with no brief", async () => {
+    const request = await capture(() => steps.reviewQuality("my-lens"))
+    expect(agentSkillsOption(request)).toEqual(["my-lens"])
+    expect(JSON.stringify(request)).not.toContain("This lens's brief")
+  })
+
+  it("a configured build.quality.reviewing entry replaces a built-in lens's skills; the brief stays", async () => {
+    const prompt = agentPrompt(
+      await capture(() => steps.reviewQuality("conventions"), {
+        "quality.reviewing": ["my-org-checklist"],
+      }),
+    )
+    expect(prompt).toContain("my-org-checklist")
+    expect(prompt).toContain("AGENTS.md")
+  })
+
   it("fixQuality carries build.fix-quality's bundled skills", async () => {
     const prompt = agentPrompt(await capture(() => steps.fixQuality()))
     expect(prompt).toContain("incremental-implementation, code-simplification")
@@ -143,6 +183,19 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
     expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
   })
 
+  it("fixRisks fixes every risk, tolerates an empty turn, and leaves .gtd/REVIEW.md alone", async () => {
+    const request = await capture(() =>
+      steps.fixRisks([{ id: "risk-1", anchor: "calc ./a.ts#1-1", text: "Risk: drops it" }]),
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.fix-risks")
+    expect(request.options).toMatchObject({ allowEmpty: true })
+    expect(request.prompt).toContain("debugging-and-error-recovery, incremental-implementation")
+    expect(request.prompt).toContain("risk-1 — calc ./a.ts#1-1")
+    expect(request.prompt).toContain("Risk: drops it")
+    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
+  })
+
   it("reviewing names the carry-over commit only when given one", async () => {
     const bare = await capture(() => steps.reviewing("base"))
     const carried = await capture(() => steps.reviewing("base", "abc1234"))

package/src/workflows/steps.ts

@@ -134,6 +134,18 @@ export const escalationExhausted = (): Promise<void> =>
 
 // ── Quality and review ──────────────────────────────────────────────────────
 
+export interface BuiltInLens {
+  readonly skills: readonly string[]
+  readonly brief: string
+}
+
+/** Lenses the workflow defines itself, not bundled skills: `skills/` is not in the npm package, and a missing lens skill burns a turn silently. */
+export const builtInLenses: Readonly<Record<string, BuiltInLens>> = {
+  correctness: { skills: ["code-review-and-quality"], brief: t.correctnessBrief },
+  conventions: { skills: [], brief: t.conventionsBrief },
+  "spec-challenge": { skills: [], brief: t.specChallengeBrief },
+}
+
 /**
  * One quality review, through the skill `lens`. `lens` rides as this turn's
  * own `skills` option — a `.gtdrc` `build.quality.reviewing` entry still
@@ -141,14 +153,18 @@ export const escalationExhausted = (): Promise<void> =>
  * but absent one the lens itself is what the turn loads by default.
  */
 export const reviewQuality = (lens: string): Promise<void> =>
-  t.agentWithSkills("quality.reviewing", t.buildQualityReviewingPrompt(lens), {
-    label: "Reviewing (one quality lens)",
-    file: QUALITY,
-    model: planner(),
-    system: t.reviewerSystem(),
-    allowEmpty: true,
-    skills: [lens],
-  })
+  t.agentWithSkills(
+    "quality.reviewing",
+    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief),
+    {
+      label: "Reviewing (one quality lens)",
+      file: QUALITY,
+      model: planner(),
+      system: t.reviewerSystem(),
+      allowEmpty: true,
+      skills: builtInLenses[lens]?.skills ?? [lens],
+    },
+  )
 
 export const fixQuality = (): Promise<void> =>
   t.agentWithSkills("fix-quality", t.buildFixQualityPrompt(), {
@@ -192,6 +208,16 @@ export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
     system: t.reviewerSystem(),
   })
 
+/** Fix the `Risk:`-marked notes the reviewer named. Shares the `build.review` conversation like `fixNits`; an empty turn means the risk was judged false. */
+export const fixRisks = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.fix-risks", t.buildReviewFixRisksPrompt(notes), {
+    label: "Fixing the reviewer's risks",
+    file: REVIEW,
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })
+
 export const awaitReview = (base: string): Promise<void> =>
   human("review.await-review", {
     message: t.buildReviewAwaitReviewMessage(base),

package/src/workflows/text.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "vitest"
 import {
+  buildReviewReviewingPrompt,
   agentWithSkills,
   architectureAuthorPrompt,
   architectureGateAnswerMessage,
   buildFixQualityPrompt,
+  buildQualityReviewingPrompt,
   buildReviewAwaitReviewMessage,
   buildReviewCollectingPrompt,
   designGateAnswerMessage,
@@ -116,6 +118,37 @@ describe("buildFixQualityPrompt", () => {
   })
 })
 
+describe("buildFixQualityPrompt scope", () => {
+  it("fixes every finding, blocking or not", () => {
+    const prompt = renderText(() => buildFixQualityPrompt())
+    expect(prompt).toContain("fix every finding in every chunk, blocking or not")
+    expect(prompt).not.toContain("found something blocking")
+  })
+})
+
+describe("buildQualityReviewingPrompt", () => {
+  const prompt = renderText(() => buildQualityReviewingPrompt("x"))
+  it("traces, reads touched paths on a large change, and judges tests by reasoning", () => {
+    expect(prompt).toContain("Trace, do not skim")
+    expect(prompt).toContain("order of external calls against")
+    expect(prompt).toContain("read the touched code")
+    expect(prompt).toContain("would fail with the guarded")
+    expect(prompt).toContain("never by running a")
+    expect(prompt).toContain("pins a bug is a finding")
+  })
+  it("writes every finding and approves only when nothing was found", () => {
+    expect(prompt).toContain("APPEND every finding you have, blocking or not")
+    expect(prompt).toContain("only when this lens found nothing at all")
+    expect(prompt).not.toContain("Write nothing when nothing is blocking")
+  })
+  it("adds a brief block only when given one", () => {
+    expect(prompt).not.toContain("This lens's brief")
+    expect(renderText(() => buildQualityReviewingPrompt("x", "BRIEF-TEXT"))).toContain(
+      "This lens's brief:\nBRIEF-TEXT",
+    )
+  })
+})
+
 describe("summaryPrompt", () => {
   it("puts the total and every model's cost on a line of its own", () => {
     const prompt = summaryPrompt({
@@ -198,3 +231,13 @@ describe("code threads in prompts", () => {
     }
   })
 })
+
+describe("buildReviewReviewingPrompt risk marking", () => {
+  it("states the Risk: marker rule and the re-review rule", () => {
+    const prompt = renderText(() => buildReviewReviewingPrompt("base"))
+    expect(prompt).toContain("Open a hunk's note with `Risk:` only for a concrete defect")
+    expect(prompt).toContain("never a style remark")
+    expect(prompt).toContain("describe what the fix changed under the")
+    expect(prompt).toContain("re-mark only a risk the fix did not resolve")
+  })
+})

package/src/workflows/text.ts

@@ -505,28 +505,70 @@ ${agentConduct}`
 
 export const buildFixQualityPrompt = (): string =>
   `${stateFileRules}
-- Read \`.gtd/QUALITY.md\` — one \`## \` chunk per quality dimension
-  that found something blocking. Merge duplicate findings across
-  dimensions FIRST, then fix every chunk
+- Read \`.gtd/QUALITY.md\` — one \`## \` chunk per finding a quality
+  dimension wrote. Merge duplicate findings across dimensions
+  FIRST, then fix every finding in every chunk, blocking or not
 - When findings conflict, missing test signal beats line count —
   a test is never deleted to satisfy a simplification finding
 - Delete \`.gtd/QUALITY.md\` once every finding is resolved
 - Leave everything else uncommitted and finish your turn
 `
 
-export const buildQualityReviewingPrompt = (lens: string): string =>
+/** Brief for a lens the workflow defines itself; a lens with none is just a skill of that name. */
+export const correctnessBrief = `- Trace partial-failure and retry paths: what a step that fails
+  after saving an id leaves behind, and whether the retry resumes
+  it or starts over
+- Check validation done before an external side effect — its
+  format, not just its presence
+- Check invariants that parallel write paths share: every path
+  that writes the same data must enforce what the main path
+  enforces
+- New mock behaviour without a contract test against the live
+  behaviour (mock/live drift) is a finding`
+
+export const conventionsBrief = `- Read every \`AGENTS.md\` and \`CLAUDE.md\` in the repository root
+  and in each touched file's directory ancestry, end to end, plus
+  every file they pull in by \`@path\`
+- Every violation of them in the change is a finding — quote the
+  rule it breaks`
+
+export const specChallengeBrief = `- Find this process's planning documents in history:
+  \`git log <start>..HEAD\` (\`<start>\` is the commit above) over the steering directory
+  (\`.gtd/\`), then \`git show\` the last version of the
+  requirements, architecture and package files
+- Flag a spec decision that conflicts with a system invariant — an
+  existing test, a documented constraint, or a data invariant
+  other code relies on — naming the decision and the invariant
+- With no planning documents in history, write nothing`
+
+export const buildQualityReviewingPrompt = (lens: string, brief?: string): string =>
   `${stateFileRules}
 - The only state file this turn writes is \`.gtd/QUALITY.md\` — no
   other files for notes or output
 - Review the whole assembled change, from \`${start()}\`
   to the working tree, through this ONE quality lens only —
-  \`${lens}\`, already loaded as this turn's own skill
-- Where you find something blocking, APPEND a \`## \` chunk to
-  \`.gtd/QUALITY.md\` describing it — never overwrite what an
-  earlier dimension already wrote there
-- Write nothing when nothing is blocking under this lens — a
+  \`${lens}\`
+- Trace, do not skim: follow the order of external calls against
+  the resume/retry logic. On a large change, read the touched code
+  paths, not just the diff hunks
+- A test counts as coverage only if it would fail with the guarded
+  behaviour removed — decide that by reasoning, never by running a
+  mutation-testing tool. A test that pins a bug is a finding, not
+  praise
+- APPEND every finding you have, blocking or not, as a \`## \`
+  chunk to \`.gtd/QUALITY.md\` — never overwrite what an earlier
+  dimension already wrote there
+- Write nothing only when this lens found nothing at all — then a
   clean turn IS this dimension's approval
-- Touch no other state file, and leave everything uncommitted
+${
+  brief
+    ? `
+This lens's brief:
+${brief}
+
+`
+    : ""
+}- Touch no other state file, and leave everything uncommitted
 `
 
 export const reviewerSystem = (): string =>
@@ -642,6 +684,17 @@ The nit notes are:
 
 ${notesCapture(notes)}`
 
+export const buildReviewFixRisksPrompt = (notes: readonly NoteInput[]): string =>
+  `${stateFileRules}
+- Fix every risk below in this one turn, all together
+- Where a risk is behavioural, add a test that fails without the fix
+- Leave \`.gtd/REVIEW.md\` untouched — the re-review rewrites it
+- Leave everything uncommitted and finish your turn
+
+The risk notes are:
+
+${notesCapture(notes)}`
+
 export const reviewEditNotesCapture = (
   commit: string,
   edits: readonly NoteInput[],
@@ -767,6 +820,14 @@ review the changes:
       - [ ] ./path/to/file.ts#42-70 — what this hunk does
         and here is more detail, continued below it
 
+  Open a hunk's note with \`Risk:\` only for a concrete defect
+  the change introduces, never a style remark — each such note is
+  fixed automatically before the human sees the review. On the
+  re-review after a fix, describe what the fix changed under the
+  hunk it touched, and re-mark only a risk the fix did not resolve:
+
+      - [ ] ./path/to/file.ts#42-70 — Risk: what is wrong
+
   A note sitting entirely on the line(s) beneath the pointer is
   also valid. Either way, the note must never start with a bare \`./path\` token
   — that parses as a second pointer, not a note

package/src/workflows/vars.ts

@@ -16,7 +16,8 @@ export const defaults: Readonly<Record<string, string>> = {
   // `./review.ts`) rather than naming one step's skill list, so it is a
   // setting — pairing with `build.quality.reviewing`'s entry in
   // `./skills.ts`, which replaces the lens on every one of those turns.
-  qualityReviews: "owasp-security, ponytail-review, test-audit",
+  qualityReviews:
+    "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge",
 }
 
 /** Environment settings. */