@pmelab/gtd 43.0.0 → 45.0.0

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
-import type { StepRequest } from "../../flows/index.js"
-import { captureStep } from "./text.fixture.js"
+import { installContext, type ScopeOptions, type StepRequest } from "../../flows/index.js"
+import { captureStep, fixtureContext } from "./text.fixture.js"
 import * as steps from "./steps.js"
 
 const capture = (
@@ -151,4 +151,66 @@ describe("the bundled workflow's model hints", () => {
     expect(await modelOf(() => steps.fixQuality())).toBe("base")
     expect(await modelOf(() => steps.fixCheck(), { env: { coderModel: "sonnet" } })).toBe("sonnet")
   })
+
+  it("answerReviewQuestions answers inline in .gtd/REVIEW.md as the reviewer, with its bundled skills", async () => {
+    const request = await capture(
+      () =>
+        steps.answerReviewQuestions([{ id: "note-1", anchor: "calc ./a.ts#1-1", text: "why?" }]),
+      "build",
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.answer-review-questions")
+    expect(request.options).toMatchObject({
+      file: ".gtd/REVIEW.md",
+      mode: "review",
+    })
+    expect(request.prompt).toContain("code-review-and-quality")
+    expect(request.prompt).toContain("note-1 — calc ./a.ts#1-1")
+    expect(request.prompt).toContain("`A: ` line")
+    expect(request.prompt).toContain("gtd check review .gtd/REVIEW.md")
+  })
+
+  it("fixNits fixes every nit in one turn and leaves .gtd/REVIEW.md alone", async () => {
+    const request = await capture(
+      () =>
+        steps.fixNits([
+          { id: "note-1", anchor: "calc ./a.ts#1-1", text: "typo" },
+          { id: "note-2", anchor: "calc ./a.ts#2-2", text: "semicolon" },
+        ]),
+      "build",
+    )
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("review.fix.nits.fixing")
+    expect(request.prompt).toContain("incremental-implementation, code-simplification")
+    expect(request.prompt).toContain("typo")
+    expect(request.prompt).toContain("semicolon")
+    expect(request.prompt).toContain("Leave `.gtd/REVIEW.md` untouched")
+  })
+
+  it("fixNits with access runs in a review.fix.nits scope, the step named fixing inside it", async () => {
+    const scopes: ScopeOptions[] = []
+    const steps_: StepRequest[] = []
+    const access = { write: ["src/a.ts", ".gtd/**"] }
+    installContext(
+      fixtureContext(
+        { scope: "refactor.build" },
+        {
+          step: (request) => {
+            steps_.push(request)
+            return Promise.resolve()
+          },
+          pushScope: (s) => void scopes.push(s),
+          popScope: () => undefined,
+          changesSince: () => [],
+        },
+      ),
+    )
+    try {
+      await steps.fixNits([], access)
+    } finally {
+      installContext(undefined)
+    }
+    expect(scopes).toEqual([{ name: "review.fix.nits", access }])
+    expect(steps_.map((r) => ("name" in r ? r.name : ""))).toEqual(["fixing"])
+  })
 })

package/src/workflows/shared/steps.ts

@@ -1,5 +1,5 @@
 import { changesSince, env, human, scope, type ScopeAccess } from "../../flows/index.js"
-import { removedAssertions } from "../../workflow-kit/index.js"
+import { removedAssertions, type CollectRound } from "../../workflow-kit/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -145,6 +145,45 @@ export const awaitReview = (
     acceptClean: true,
   })
 
+/** Answer every `question` note inline in `.gtd/REVIEW.md`. */
+export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<void> =>
+  t.agentWithSkills("review.answer-review-questions", t.buildReviewAnswerQuestionsPrompt(notes), {
+    label: "Answering your questions",
+    file: REVIEW,
+    mode: "review",
+    model: planner(),
+    system: t.reviewerSystem(),
+  })
+
+/** Fix every `nit` note in one turn. */
+export const fixNits = (
+  notes: readonly t.NoteInput[],
+  access?: ScopeAccess,
+  rules?: string,
+): Promise<void> => {
+  const fixing = (name: string): Promise<void> =>
+    t.agentWithSkills(name, t.buildReviewFixNitsPrompt(notes, rules), {
+      label: "Fixing your nits",
+      file: REVIEW,
+      model: planner(),
+      system: t.reviewerSystem(),
+    })
+  return access === undefined
+    ? fixing("review.fix.nits.fixing")
+    : scope({ name: "review.fix.nits", access }, () => fixing("fixing"))
+}
+
+/** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
+export const collecting = (capture: string, round?: CollectRound): Promise<void> =>
+  t.agentWithSkills("review.collecting", t.buildReviewCollectingPrompt(capture, undefined, round), {
+    label: "Collecting your feedback",
+    file: REQUIREMENTS,
+    mode: "qa",
+    model: planner(),
+    system: t.reviewerSystem(),
+    allowEmpty: true,
+  })
+
 /** The round at commit `round` left no `.gtd/REVIEW.md`. */
 export const reviewMissing = (round: string): Promise<void> =>
   human("review.review-missing", {

package/src/workflows/shared/tail.ts

@@ -190,7 +190,7 @@ const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
   })
 
 /**
- * The review and fix workflows' human review since `base`: a sign-off closes
+ * The fix workflow's human review since `base`: a sign-off closes
  * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
  * `REVIEW_ORIG`, for the next `fix` to read — never a re-plan.
  */
@@ -220,6 +220,6 @@ export const handOffReview = (
       "gtd land: review-doc: .gtd/REVIEW.md was deleted — restore it, or leave a note to hand to fix.",
   })
 
-/** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
+/** The tail the fix workflow runs: ends at the hand-off review since `base`. */
 export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
   tail((escalations) => handOffReview(base, escalations, guard), { fixFirst, guard })

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

@@ -31,7 +31,7 @@ import {
   withSkills,
   composedReview,
 } from "./text.js"
-import { steeringFormatFor, unansweredNotes } from "../../steering/index.js"
+import { reviewDecisions, steeringFormatFor, unansweredNotes } from "../../steering/index.js"
 import { captureStep, renderText } from "./text.fixture.js"
 
 describe("withSkills", () => {
@@ -68,6 +68,28 @@ describe("agentWithSkills", () => {
     expect(request.options).not.toHaveProperty("skills")
   })
 
+  it("ends every prompt with the kept standards, never the undecided ones", async () => {
+    const standards = [
+      "# Standards",
+      "",
+      "- Prefer early returns.",
+      "",
+      "## Undecided",
+      "",
+      "- Use classes.",
+      "  - contradicts: Prefer early returns.",
+    ].join("\n")
+    const request = await captureStep(() => agentWithSkills("name", "do-the-work"), {
+      scope: "a",
+      skills: { a: [] },
+      read: (path) => (path === ".gtd/STANDARDS.md" ? standards : undefined),
+    })
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.prompt.startsWith("do-the-work\n\n## Standards")).toBe(true)
+    expect(request.prompt.endsWith("- Prefer early returns.")).toBe(true)
+    expect(request.prompt).not.toContain("Use classes.")
+  })
+
   it("leaves the prompt bare when the scope resolves to an empty list", async () => {
     const request = await capture(() => agentWithSkills("name", "do-the-work"), { a: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
@@ -1244,6 +1266,41 @@ describe("buildReviewCollectingPrompt answer boxes", () => {
 describe("composedReview", () => {
   const BASE = "0123456789abcdef0123456789abcdef01234567"
 
+  describe("standards", () => {
+    const conflict = { text: "Calculators are functions.", olds: ["Calculators are classes."] }
+    const withConflict = composedReview(BASE, {
+      notes: [],
+      fixed: [],
+      noise: [],
+      standards: { added: [], undecided: [conflict] },
+    })
+
+    it("asks about each undecided standard in a note that blocks sign-off", () => {
+      expect(withConflict).toMatch(/^## Standard conflict [0-9a-f]{8}$/m)
+      expect(withConflict).toContain("- [ ] keep the new one (drop the old)")
+      expect(unansweredNotes(withConflict)).toHaveLength(1)
+    })
+
+    it("reads its boxes by position, like a note's", () => {
+      const ticked = withConflict.replace("- [ ] keep the old one", "- [x] keep the old one")
+      expect(unansweredNotes(ticked)).toEqual([])
+      expect(reviewDecisions(withConflict, ticked)).toEqual([
+        expect.objectContaining({ choice: "wontfix" }),
+      ])
+    })
+
+    it("lists the standards added", () => {
+      const doc = composedReview(BASE, {
+        notes: [],
+        fixed: [],
+        noise: [],
+        standards: { added: ["Prefer early returns."], undecided: [] },
+      })
+      expect(doc).toContain("## Standards added")
+      expect(doc).toContain("- Prefer early returns.")
+    })
+  })
+
   it("is a valid review with unique chunk titles, so every note matches its own chunk", () => {
     const doc = composedReview(BASE, {
       notes: [

package/src/workflows/shared/text.ts

@@ -1,6 +1,7 @@
 import {
   agent,
   codeThreads,
+  read,
   displayPath,
   env,
   head,
@@ -19,6 +20,13 @@ import {
   FREE_TEXT_PLACEHOLDER,
 } from "../../steering/index.js"
 import { escapeRegExp } from "./registry.js"
+import {
+  conflictBody,
+  conflictTitle,
+  standardsBlock,
+  STANDARDS,
+  type Conflict,
+} from "./standards.js"
 import { defaultFlagRegistry } from "./vars.js"
 import type { CollectRound, RemovedAssertions, Requested } from "../../workflow-kit/index.js"
 import {
@@ -57,7 +65,8 @@ export const agentWithSkills = (
   options: AgentOptions = {},
 ): Promise<void> => {
   const access = accessPreamble(accessFor(name, options.file))
-  const body = access === "" ? prompt : `${access}\n\n${prompt}`
+  const standards = standardsBlock(read(STANDARDS))
+  const body = [access, prompt, standards].filter((part) => part !== "").join("\n\n")
   return agent(name, withSkills(skillsFor(name).join(", "), body), options)
 }
 
@@ -124,12 +133,17 @@ export interface ComposedReview {
   readonly nitFix?: string | undefined
   /** Titles of notes the human already answered, left out. */
   readonly answered?: ReadonlySet<string> | undefined
+  /** Standards added since the review base, and the conflicts still waiting on the human. */
+  readonly standards?:
+    | { readonly added: readonly string[]; readonly undecided: readonly Conflict[] }
+    | undefined
 }
 
 const SUMMARY_TITLES = [
   "Weakened scenarios",
   "Fixed from your notes",
   "Fixed automatically",
+  "Standards added",
   "Dropped as noise",
   "Nothing to note",
 ]
@@ -157,6 +171,10 @@ export const composedReview = (base: string, report: ComposedReview): string =>
   const chunk = (title: string, body: string): string => `## ${title}\n\n${body.trim()}`
   // The lead-in line keeps a body that ends in a list from absorbing the boxes.
   const answerBoxes = `${ANSWER_LEAD}\n\n- [ ] ${ANSWER_FIX}\n- [ ] ${ANSWER_WONT_FIX}\n- [ ] ${FREE_TEXT_PLACEHOLDER}`
+  const conflicts = (report.standards?.undecided ?? []).map((c) =>
+    chunk(unique(conflictTitle(c)), conflictBody(c)),
+  )
+  const added = report.standards?.added ?? []
   const notes = report.notes
     .map((n) => ({ ...n, title: unique(n.title) }))
     .filter((n) => report.answered?.has(n.title) !== true)
@@ -180,6 +198,7 @@ export const composedReview = (base: string, report: ComposedReview): string =>
             `These scenarios lost an assertion the review base had:\n\n${weakened.join("\n")}`,
           ),
         ]),
+    ...conflicts,
     ...notes.map((n) =>
       chunk(
         n.title,
@@ -200,6 +219,14 @@ export const composedReview = (base: string, report: ComposedReview): string =>
             report.fixed.map((f) => `- ${f.title} (${short(f.commit)})`).join("\n"),
           ),
         ]),
+    ...(added.length === 0
+      ? []
+      : [
+          chunk(
+            "Standards added",
+            `Learned from your answers and kept in \`${STANDARDS}\`:\n\n${added.map((s) => `- ${s}`).join("\n")}`,
+          ),
+        ]),
     ...(report.noise.length === 0
       ? []
       : [chunk("Dropped as noise", report.noise.map((f) => `- ${f.title} (p=${f.p})`).join("\n"))]),
@@ -875,6 +902,17 @@ The reviewer's risks are:
 
 ${risks.length === 0 ? "(none)\n" : notesCapture(risks)}`
 
+export const reviewFeedbackFixPrompt = (): string =>
+  `${stateFileRules}
+- Read \`.gtd/REQUIREMENTS.md\` — the concerns the human's review asked for,
+  one \`## \` heading each, in build order
+- Build every concern in this one turn; an answered question is context,
+  not a concern
+- Where a change is behavioural, add a test that fails without it
+- Leave \`.gtd/REQUIREMENTS.md\` untouched — the next step removes it
+- Leave everything uncommitted and finish your turn
+`
+
 export const buildReviewReviewMissingMessage = (commit: string): string =>
   `The review round committed no \`.gtd/REVIEW.md\` (at ${commit}), so there is
 nothing to sign off on.

package/src/workflows/shared/vars.ts

@@ -24,6 +24,8 @@ export const defaults: Readonly<Record<string, string>> = {
   reviewNoteActionable: "0.7",
   reviewSeverityMinP: "0.7",
   qualityTriageMinP: "0.7",
+  // How sure the judge must be that an answer at the review gate is a reusable standard.
+  standardMinP: "0.8",
   refactorFlagPattern: "\\bGTD_FLAG_\\w+",
   seamAllow: [...testFileGlobs, ".gtd/**"].join(", "),
   flagMode: "true",