@pmelab/gtd 53.0.0 → 55.0.0

package/src/workflows/feature/seam.ts

@@ -3,7 +3,6 @@ import {
   agent,
   applyScript,
   changes,
-  changesSince,
   check,
   codeChanges,
   env,
@@ -92,43 +91,19 @@ const reaches = (imports: ReturnType<typeof importsOf>, added: string): boolean
     imports.some(({ path, tail }) => name === path || (tail && name.endsWith(`/${path}`))),
   )
 
-const named = (id: string, text: string): boolean =>
-  new RegExp(`(?<![\\w-])${id}(?!\\d)`).test(text)
-
-/** The lines `change` added: an ID an earlier change left in the file does not count. */
-const addedLines = (change: Change): string => {
-  const before = new Set((change.before ?? "").split("\n"))
-  return change
-    .after!.split("\n")
-    .filter((line) => !before.has(line))
-    .join("\n")
-}
-
 const acceptanceTests = (changes: readonly Change[]): readonly Change[] =>
   changes.filter((c) => c.after !== undefined && isCode(c.path) && isTestFile(c.path))
 
-const idsOf = (file: string): string[] => criterionIds(read(file) ?? "")
-
-// One rule for both gates, so a naive test carried over verbatim always satisfies the rebuild's.
-const unnamed = (ids: readonly string[], tests: readonly Change[]): string[] => {
-  const lines = tests.map(addedLines)
-  return ids.filter((id) => !lines.some((text) => named(id, text)))
-}
-
 /**
- * Why `tip`'s tests fall short, or `undefined`: a criterion ID of `file` no
- * test line of the pass names, or a test importing a file the pass added —
- * naive structure a reset and refactor replaces, which the tests must survive.
+ * Why `tip`'s tests fall short, or `undefined`: a test importing a file the
+ * pass added — naive structure a reset and refactor replaces, which the tests
+ * must survive.
  */
-export const acceptanceFault = (file: string, tip: KeptTip): string | undefined => {
-  const tests = acceptanceTests(tip.changes)
-  const untested = unnamed(idsOf(file), tests)
-  if (untested.length > 0)
-    return `acceptance-tests: no test of the naive pass names ${untested.join(", ")} — write a behaviour-level test for each criterion with its ID in the test or scenario name, e.g. "[${untested[0]}] …"`
+export const acceptanceFault = (tip: KeptTip): string | undefined => {
   const added = tip.changes
     .filter((c) => c.status === "added" && isCode(c.path) && !isTestFile(c.path))
     .map((c) => c.path)
-  const reaching = tests
+  const reaching = acceptanceTests(tip.changes)
     .filter((test) => holdsCallSites(test.path))
     .flatMap((test) => {
       const imports = importsOf(test)
@@ -141,48 +116,11 @@ export const acceptanceFault = (file: string, tip: KeptTip): string | undefined
   return undefined
 }
 
-/** What a rebuild carries over from the naive pass `tip`: the IDs its tests name, and those test files. */
-export const naiveAcceptance = (tip: KeptTip): t.Acceptance => {
-  const ids = idsOf(REQUIREMENTS)
-  const perTest = acceptanceTests(tip.changes).map((c) => {
-    const lines = addedLines(c)
-    return { path: c.path, ids: ids.filter((id) => named(id, lines)) }
-  })
-  return {
-    hash: tip.hash,
-    tests: perTest.filter((c) => c.ids.length > 0).map((c) => c.path),
-    ids: ids.filter((id) => perTest.some((c) => c.ids.includes(id))),
-  }
-}
-
-/**
- * Refuse a rebuild whose test changes since `since` leave out an ID the naive
- * pass's tests named. A skipped test still counts: the gate reads text, never runs it.
- */
-export const requireAcceptance = (acceptance: t.Acceptance, since: string): void => {
-  const missing = unnamed(acceptance.ids, acceptanceTests(changesSince(since)))
-  if (missing.length === 0) return
-  refuse(
-    `gtd land: rebuild-acceptance: the rebuild's tests leave out ${missing.join(", ")} — carry over the naive pass's acceptance tests (\`git show ${acceptance.hash} -- ${acceptance.tests.map(quote).join(" ")}\`), each with its ID in the test or scenario name`,
-  )
-}
-
-/**
- * Refuse a fix turn that, on its own, drops an ID the naive pass's tests named
- * from a test file. Turn-local, so a person's edit at an escalation rest never
- * wedges later fix turns.
- */
-export const requireAcceptanceKept = (acceptance: t.Acceptance): void => {
-  const dropped = acceptance.ids.filter((id) =>
-    changes()
-      .filter((c) => isCode(c.path) && isTestFile(c.path))
-      .some((c) => named(id, c.before ?? "") && !named(id, c.after ?? "")),
-  )
-  if (dropped.length === 0) return
-  refuse(
-    `gtd land: rebuild-acceptance: this turn drops ${dropped.join(", ")} from the tests — the naive pass's acceptance tests stay; fix the code, not them`,
-  )
-}
+/** What a rebuild carries over from the naive pass `tip`: every test file it added or changed. */
+export const naiveAcceptance = (tip: KeptTip): t.Acceptance => ({
+  hash: tip.hash,
+  tests: acceptanceTests(tip.changes).map((c) => c.path),
+})
 
 const restore = (path: string): string =>
   `if git cat-file -e ${quote(`HEAD:${path}`)} 2>/dev/null; then git checkout -q HEAD -- ${quote(path)}; else rm -f -- ${quote(path)}; fi`
@@ -243,12 +181,6 @@ const applied = async (tip: string): Promise<boolean> => {
   return !wrote(FEEDBACK) && codeChanges().length > 0
 }
 
-/** `carried` limited to the criteria `.gtd/REQUIREMENTS.md` lists now; a file listing none narrows nothing. */
-const settled = (carried: readonly string[]): readonly string[] => {
-  const listed = idsOf(REQUIREMENTS)
-  return listed.length === 0 ? carried : carried.filter((id) => listed.includes(id))
-}
-
 const build = async (options: ImplementOptions): Promise<void> => {
   await t.agentWithSkills(
     "building",
@@ -290,19 +222,11 @@ export async function implement(
 /** `implement`, resolving with the criterion IDs the requirements listed when it closed. */
 export const implementing = (options: ImplementOptions): Promise<readonly string[]> =>
   scope("implement", async () => {
-    const since = head()
-    const acceptance = options.rebuild?.acceptance
     const built = options.naive === undefined || !(await applied(options.naive))
     if (built) await build(options)
     else requireCriteriaFrozen(REQUIREMENTS)
-    // Only the criteria the requirements still list.
-    if (built && acceptance !== undefined)
-      requireAcceptance({ ...acceptance, ids: settled(acceptance.ids) }, since)
-    // Fix turns are held to the carried tests too: deleting a red one must not buy a green suite.
-    const keepsTests =
-      built && acceptance !== undefined ? () => requireAcceptanceKept(acceptance) : undefined
-    await green(keepsTests)
-    await prototypeTest(keepsTests)
+    await green()
+    await prototypeTest()
     const ids = criterionIds(read(REQUIREMENTS) ?? "")
     await run("closing", removeScript([REQUIREMENTS, REFACTOR_NOTE, PROTOTYPE]), {
       label: "Closing out the implementation",
@@ -360,7 +284,7 @@ interface Vetting {
 
 /** Sends a pass whose tests fall short or run red back (`undefined`: it goes on, an overruled one as it is). */
 const vetted = async (tip: KeptTip, vetting: Vetting): Promise<Verdict | undefined> => {
-  const fault = vetting.waived ? undefined : acceptanceFault(REQUIREMENTS, tip)
+  const fault = vetting.waived ? undefined : acceptanceFault(tip)
   if (fault !== undefined) {
     const verdict = await vetting.again({ fault, hash: tip.hash })
     if (verdict.kind !== "overruled") return verdict

package/src/workflows/fix/fix-quality.feature

@@ -4,11 +4,12 @@ Feature: fix's quality lap is triaged, and its leftovers go to the hand-off revi
   A judge sorts the lap's findings: mechanical ones are fixed for up to three
   turns, noise is dropped, and design ones — with whatever the fix turns left —
   are added to the reviewer's `.gtd/REVIEW.md` by gtd, never to a person's
-  gate before the review.
+  gate before the review. With no requirements to check against, the
+  `criteria-coverage` lens runs no turn.
 
   Background:
     Given the shipped workflows, as gtd install scaffolds them
-    And an environment variable "GTD_QUALITYREVIEWS" set to "correctness"
+    And an environment variable "GTD_QUALITYREVIEWS" set to "criteria-coverage, correctness"
     And a file "src/calc.ts" with:
       """
       export const add = (a: number, b: number) => a + b
@@ -81,6 +82,7 @@ Feature: fix's quality lap is triaged, and its leftovers go to the hand-off revi
     Then the process rests at "build.review.await-review"
     And ".gtd/QUALITY.md" does not exist
     And no commit body contains "build.health.describe"
+    And no commit body contains "build.quality.criteria-coverage"
     And ".gtd/REVIEW.md" contains:
       """
       ## sum has no negative test

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

@@ -19,6 +19,7 @@ describe("the bundled workflow's access export", () => {
       "build.quality.test-audit": { write: [] },
       "build.quality.conventions": { write: [] },
       "build.quality.spec-challenge": { write: [] },
+      "build.quality.criteria-coverage": { write: [] },
       "refactor.build.review": { write: [".gtd/REVIEW.md"] },
       "refactor.build.quality.correctness": { write: [] },
       "refactor.build.quality.ponytail-review": { write: [] },

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

@@ -575,7 +575,7 @@ describe("review verdict routing", () => {
 })
 
 describe("the default quality lenses", () => {
-  it("are the six lenses in the settled order", () => {
+  it("are the seven lenses in the settled order", () => {
     expect(bundled.defaults.qualityReviews!.split(",").map((l) => l.trim())).toEqual([
       "correctness",
       "owasp-security",
@@ -583,6 +583,7 @@ describe("the default quality lenses", () => {
       "test-audit",
       "conventions",
       "spec-challenge",
+      "criteria-coverage",
     ])
   })
 
@@ -590,6 +591,7 @@ describe("the default quality lenses", () => {
     expect(Object.keys(bundled.builtInLenses).sort()).toEqual([
       "conventions",
       "correctness",
+      "criteria-coverage",
       "spec-challenge",
     ])
   })

package/src/workflows/shared/review.ts

@@ -380,6 +380,7 @@ const walkthrough = async (
   report: t.ComposedReview,
   lap: t.ReviewRange,
   carry: string | undefined,
+  afterRiskFix: boolean,
 ): Promise<void> => {
   const notes = t.titledNotes(report)
   await reviewing(base, carry, lap, t.walkthroughBlock(notes, report.nitFix))
@@ -393,7 +394,8 @@ const walkthrough = async (
     notes,
     changesSince(base).some((c) => isCode(c.path)),
   )
-  // Ranked even when it marks risks: the review written after their fix reaches the human with its own.
+  // Its risks are fixed and the review written again, so the re-reviewer edits this draft, never gtd's layout.
+  if (!afterRiskFix && reviewRisks(written).length > 0) return
   const full = sectionedReview(
     await ranked(review, t.withWalkthrough(review, report), new Set(notes.map((n) => n.title))),
     new Set(reviewChunks(review).map((c) => c.title)),
@@ -432,12 +434,16 @@ export const humanReview = (
   let nitFix: string | undefined
   // Every note the human answered in this review, left out of a fresh one.
   const answered = new Set<string>()
+  // Set by a risk fix, so the review written next reaches the human whatever it marks.
+  let riskFixed = false
   return kit.review(base, {
     file: REVIEW,
     feedback: feedback.file,
     isCode,
     reviewing: (b, carry) => {
       const fixedAt = nitFix
+      const afterRiskFix = riskFixed
+      riskFixed = false
       const report = options.report ?? NO_FINDINGS
       return options.walkthrough === true
         ? guarded(
@@ -447,12 +453,16 @@ export const humanReview = (
                 composedOf(b, report, fixedAt, answered),
                 options.lap ?? "first",
                 carry,
+                afterRiskFix,
               ),
             guard,
           )()
         : composing(b, report, carry, fixedAt, answered)
     },
-    fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
+    fixRisks: guarded((notes) => {
+      riskFixed = true
+      return fixRisks(notes, fixAccess, rules)
+    }, guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
     // Kept until the human sees a review, so a re-review after a risk fix still names it.
     awaitReview: (b) => {

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

@@ -39,6 +39,7 @@ describe("the bundled workflow's skills export", () => {
         "build.quality.test-audit",
         "build.quality.conventions",
         "build.quality.spec-challenge",
+        "build.quality.criteria-coverage",
         "refactor.build",
         "refactor.build.health",
         "refactor.build.fix.quality",
@@ -98,10 +99,11 @@ describe("the bundled workflow's skills export", () => {
     expect(Object.keys(none).filter((k) => k.startsWith("refactor.build.quality."))).toEqual([])
   })
 
-  it("loads one lens skill per quality lens: correctness its review skill, conventions and spec-challenge none, any other itself", () => {
+  it("loads one lens skill per quality lens: correctness its review skill, conventions, spec-challenge and criteria-coverage none, any other itself", () => {
     expect(bundled["build.quality.correctness"]).toEqual(["code-review-and-quality"])
     expect(bundled["build.quality.conventions"]).toEqual([])
     expect(bundled["build.quality.spec-challenge"]).toEqual([])
+    expect(bundled["build.quality.criteria-coverage"]).toEqual([])
     expect(bundled["build.quality.owasp-security"]).toEqual(["owasp-security"])
   })
 

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

@@ -57,12 +57,15 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
       expect(body).toContain(point)
   })
 
-  it.each(["conventions", "spec-challenge"])("%s carries its brief", async (lens) => {
-    const request = await capture(() => steps.reviewQuality(lens), "build")
-    expect(JSON.stringify(request)).toContain(
-      steps.builtInLenses[lens]!.brief.split("\n")[0]!.slice(0, 40),
-    )
-  })
+  it.each(["conventions", "spec-challenge", "criteria-coverage"])(
+    "%s carries its brief",
+    async (lens) => {
+      const request = await capture(() => steps.reviewQuality(lens), "build")
+      expect(JSON.stringify(request)).toContain(
+        steps.builtInLenses[lens]!.brief.split("\n")[0]!.slice(0, 40),
+      )
+    },
+  )
 
   it("an unknown lens has no brief", async () => {
     const request = await capture(() => steps.reviewQuality("my-lens"), "build")

package/src/workflows/shared/steps.ts

@@ -66,15 +66,24 @@ 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 },
+  "criteria-coverage": { skills: [], brief: t.criteriaCoverageBrief },
 }
 
 const coderLenses: ReadonlySet<string> = new Set(["conventions", "ponytail-review", "test-audit"])
 
-/** One quality review through `lens`; each lens is its own scope, so its own conversation and skills. */
-export const reviewQuality = (lens: string, base?: string, model?: string): Promise<void> =>
+/**
+ * One quality review through `lens`; each lens is its own scope, so its own
+ * conversation and skills. `requirements`, when given, are quoted in the prompt.
+ */
+export const reviewQuality = (
+  lens: string,
+  base?: string,
+  model?: string,
+  requirements?: string,
+): Promise<void> =>
   t.agentWithSkills(
     `quality.${lens}.reviewing`,
-    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief, base),
+    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief, base, requirements),
     {
       label: "Reviewing (one quality lens)",
       file: QUALITY,

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

@@ -211,13 +211,17 @@ const prompts: string[] = []
 const models: (string | undefined)[] = []
 
 describe("the quality lap's lenses", () => {
-  const lap = async (run: () => Promise<unknown>, vars: Record<string, string> = {}) => {
+  const lap = async (
+    run: () => Promise<unknown>,
+    vars: Record<string, string> = {},
+    files: Record<string, string> = {},
+  ) => {
     const log: string[] = []
     prompts.length = 0
     models.length = 0
     installContext(
       fixtureContext(
-        { vars },
+        { vars, read: (path) => files[path] },
         {
           step: (request: StepRequest) => {
             if (request.kind !== "restart") log.push(request.name)
@@ -309,6 +313,20 @@ describe("the quality lap's lenses", () => {
     expect(models).toEqual(["smart", "opus"])
   })
 
+  it("criteria-coverage runs only with requirements, passed or in .gtd/REQUIREMENTS.md, and quotes them", async () => {
+    const lenses = ["criteria-coverage", "conventions"]
+    expect(await lap(() => qualityLap(undefined, lenses))).toEqual([
+      "quality.conventions.reviewing",
+    ])
+    await lap(() => qualityLap(undefined, lenses), {}, { ".gtd/REQUIREMENTS.md": "- AC-1: file" })
+    expect(prompts[0]).toContain("  > - AC-1: file")
+    expect(prompts[1]).not.toContain("AC-1")
+    await lap(() =>
+      tail(() => Promise.resolve(), { green: true, lenses, requirements: "- AC-1: passed" }),
+    )
+    expect(prompts[0]).toContain("  > - AC-1: passed")
+  })
+
   it("tail passes lenses to its lap and a guard after each lens turn", async () => {
     let guards = 0
     const log = await lap(() =>

package/src/workflows/shared/tail.ts

@@ -15,6 +15,7 @@ import {
   fixCheck,
   fixRisks,
   QUALITY,
+  REQUIREMENTS,
   REVIEW,
   reviewing,
   reviewMissing,
@@ -35,24 +36,31 @@ export const qualityLap = (
   guard?: Guard,
   lenses?: readonly string[],
   base?: string,
-): Promise<"clean" | "findings"> => lensLap(guard, lenses, base, () => {})
+): Promise<"clean" | "findings"> => lensLap(guard, lenses, base, undefined, () => {})
+
+const COVERAGE = "criteria-coverage"
 
 // `seen` gets each lens and every finding in the file once its turn is done.
 const lensLap = (
   guard: Guard | undefined,
   lenses: readonly string[] | undefined,
   base: string | undefined,
+  given: string | undefined,
   seen: (lens: string, findings: readonly Finding[]) => void,
-): Promise<"clean" | "findings"> =>
-  kit.qualityLap(
-    lenses ?? kit.lensEntriesOf(vars.qualityReviews ?? ""),
+): Promise<"clean" | "findings"> => {
+  const requirements = given ?? read(REQUIREMENTS)
+  return kit.qualityLap(
+    (lenses ?? kit.lensEntriesOf(vars.qualityReviews ?? "")).filter(
+      (entry) => requirements !== undefined || kit.lensOf(entry).lens !== COVERAGE,
+    ),
     guarded(async (entry: string) => {
       const { lens, model } = kit.lensOf(entry)
-      await reviewQuality(lens, base, model)
+      await reviewQuality(lens, base, model, lens === COVERAGE ? requirements : undefined)
       seen(lens, findingsOf(read(QUALITY) ?? ""))
     }, guard),
     QUALITY,
   )
+}
 
 // What the fixer left is in the lap's report by now; the next lap must not append to it.
 const closeQuality = async (): Promise<void> => {
@@ -91,6 +99,11 @@ export interface TailOptions {
   readonly lensBase?: string | undefined
   /** Appended to every fix and describe prompt of the tail. */
   readonly rules?: string | undefined
+  /**
+   * The requirements the change was built to, for the `criteria-coverage`
+   * lens; absent: `.gtd/REQUIREMENTS.md`, and with neither the lens is skipped.
+   */
+  readonly requirements?: string | undefined
 }
 
 /**
@@ -156,7 +169,7 @@ const tailForm = <T>(
 
 const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
   scope("build", async () => {
-    const { guard, lenses, lensBase, rules } = options
+    const { guard, lenses, lensBase, rules, requirements } = options
     // Only undefined defaults: a null reaches every escalation as falsy, as it reaches review's.
     const guardRests = options.guardRests === undefined ? true : options.guardRests
     const escalations: EscalationCount = { rounds: 0 }
@@ -170,7 +183,7 @@ const runTail = <T>(finish: Finish<T>, options: TailOptions): Promise<T> =>
     // The lap runs once a tail: after its findings are fixed, `finish` follows.
     // Lenses append, so a title the file did not hold before a lens's turn is that lens's.
     const byTitle: { title: string; lens: string }[] = []
-    const lap = await lensLap(guard, lenses, lensBase, (lens, findings) => {
+    const lap = await lensLap(guard, lenses, lensBase, requirements, (lens, findings) => {
       const before = byTitle.map((f) => f.title)
       for (const { title } of findings) {
         const at = before.indexOf(title)

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

@@ -898,14 +898,27 @@ describe("the seam phase's texts", () => {
     expect(prompt).toContain("solved the task the wrong way")
   })
 
-  it("asks for a breadth-first pass with ID-tagged behaviour tests, green before it ends", () => {
+  it("asks for a breadth-first pass tested through existing code, green before it ends", () => {
     const prompt = renderText(() => naivePassPrompt())
     expect(prompt).toContain("breadth-first")
-    expect(prompt).toContain("`[AC-3] …`")
     expect(prompt).toContain("never a file this pass adds")
     expect(prompt).toContain("green")
   })
 
+  it.each([
+    ["naive", () => naivePassPrompt()],
+    ["building", () => implementBuildingPrompt("abc123")],
+    ["prototype fixing", () => prototypeFixingPrompt()],
+  ])(
+    "the %s prompt asks for a test per behaviour, never a criterion ID in its name",
+    (_n, prompt) => {
+      const text = renderText(prompt)
+      expect(text).toContain("one test per behaviour, not per\n  criterion")
+      expect(text).toContain("never put criterion IDs in test or scenario names")
+      expect(text).not.toContain("[AC-3]")
+    },
+  )
+
   it("has a red retry pick up the kept attempt instead of starting over", () => {
     const prompt = renderText(() => naivePassPrompt({ red: "abc123" }))
     expect(prompt).toContain("left the suite red")
@@ -972,16 +985,16 @@ describe("the seam phase's texts", () => {
 
   it("hands a faulty pass back with the fault and the kept attempt to pick up", () => {
     const fault = {
-      fault: "acceptance-tests: no test of the naive pass names AC-2",
+      fault: "acceptance-internals: these tests import files the naive pass added",
       hash: "abc123",
     }
     const prompt = renderText(() => naivePassPrompt(fault))
-    expect(prompt).toContain("names AC-2")
+    expect(prompt).toContain("import files the naive pass added")
     expect(prompt).toContain(
       "git diff --binary --no-color --no-ext-diff --no-textconv abc123^ abc123 | git apply",
     )
     const message = renderText(() => seamSteerMessage(fault))
-    expect(message).toContain("names AC-2")
+    expect(message).toContain("import files the naive pass added")
     expect(message).toContain("`seam.check` runs its suite")
     expect(message).toContain("Overrule")
   })
@@ -997,7 +1010,7 @@ describe("the seam phase's texts", () => {
   })
 
   it("promises no judge on an overrule with flagMode off", () => {
-    for (const retry of [{ red: "abc123" }, { fault: "acceptance-tests: x", hash: "abc123" }]) {
+    for (const retry of [{ red: "abc123" }, { fault: "acceptance-internals: x", hash: "abc123" }]) {
       const message = renderText(() => seamSteerMessage(retry, false))
       expect(message).not.toContain("seam judge")
       expect(message).toContain("it lands as the implementation")