@pmelab/gtd 16.0.0 → 17.2.0

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

@@ -1,4 +1,4 @@
-import { human, vars } from "../flows/index.js"
+import { env, human } from "../flows/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -14,8 +14,8 @@ export const REVIEW = ".gtd/REVIEW.md"
 export const QUALITY = ".gtd/QUALITY.md"
 export const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md"
 
-const planner = (): string => vars.plannerModel ?? ""
-const coder = (): string => vars.coderModel ?? ""
+const planner = (): string => env.plannerModel ?? ""
+const coder = (): string => env.coderModel ?? ""
 
 // ── Planning ────────────────────────────────────────────────────────────────
 
@@ -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.fixture.ts

@@ -5,10 +5,11 @@ import {
   type StepRequest,
 } from "../flows/index.js"
 import { skills as bundledSkills } from "./skills.js"
-import { defaults } from "./vars.js"
+import { defaults, envDefaults } from "./vars.js"
 
 export interface TextContext {
   readonly vars?: Readonly<Record<string, string>>
+  readonly env?: Readonly<Record<string, string>>
   readonly head?: string
   readonly start?: string
   readonly codeThreads?: readonly CodeThreadInfo[]
@@ -73,6 +74,7 @@ export const fixtureContext = (
   threads: () => [],
   codeThreads: () => context.codeThreads ?? [],
   vars: { ...defaults, ...context.vars },
+  env: { ...envDefaults, ...context.env },
   head: () => context.head ?? "",
   start: () => context.start ?? "",
   skillsFor: skillsForOf(context),

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({
@@ -129,6 +162,7 @@ describe("summaryPrompt", () => {
         { model: "base", cost: 7 },
       ],
       vars: {},
+      env: {},
     })
     expect(prompt).toContain("Token cost: 12\n- smart: 5\n- base: 7\n\nPrint the closing message")
   })
@@ -197,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

@@ -1,10 +1,10 @@
 import {
   agent,
   codeThreads,
+  env,
   head,
   skillsFor,
   start,
-  vars,
   type AgentOptions,
   type SummaryContext,
 } from "../flows/index.js"
@@ -195,7 +195,7 @@ ${questionBarReturn}
   never re-open one. A genuinely open PRODUCT point may still
   raise a fresh \`## Open Questions\` entry: the product gate sits
   on this path exactly as on the first lap
-- Before grouping anything, run \`${vars.testCommand}\`
+- Before grouping anything, run \`${env.testCommand}\`
   yourself — a loop-back runs no green-baseline gate, so the
   tree may already be red (reverting the edit can undo a fix it
   made). If red, make that breakage the first concern, ahead of
@@ -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/unified.ts

@@ -31,7 +31,7 @@ import * as t from "./text.js"
 // re-exported below.
 
 export { threads, type ThreadInfo } from "../flows/index.js"
-export { defaults } from "./vars.js"
+export { defaults, envDefaults } from "./vars.js"
 export { skills } from "./skills.js"
 export { agentWithSkills } from "./text.js"
 export * from "./steps.js"

package/src/workflows/vars.ts

@@ -1,21 +1,28 @@
-// The bundled workflow's variable defaults. `.gtdrc` `vars:`, `--var` and
-// `GTD_<NAME>` override any of them.
+// The bundled workflow's settings, in two kinds. A process setting changes
+// which step comes next, so it is pinned for the whole process at its start;
+// an environment setting only changes how a step runs on this machine, so it
+// is read live on every invocation. `.gtdrc` `vars:`/`env:`, `--var` (process
+// settings only) and `GTD_<NAME>` override either.
+
+/** Process settings. */
 export const defaults: Readonly<Record<string, string>> = {
-  testCommand: "npm test",
-  plannerModel: "smart",
-  coderModel: "base",
   reviewBase: "",
   judgeBudgetBytes: "32768",
   judgeIdenticalMinP: "0.7",
   specPreJudge: "0.9",
   reviewNoteActionable: "0.7",
   architectureSkipMinP: "0.85",
-  // The per-step skill lists formerly declared here as `*Skills` vars now
-  // live in `./skills.ts`, addressed per step by `.gtdrc` `skills:`.
-  // `qualityReviews` is the one exception: it fans out into one turn per
-  // entry (`qualityLenses`, in `./review.ts`) rather than naming one step's
-  // skill list, so it stays a var — 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` fans out into one turn per entry (`qualityLenses`, in
+  // `./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:
+    "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge",
+}
+
+/** Environment settings. */
+export const envDefaults: Readonly<Record<string, string>> = {
+  testCommand: "npm test",
+  plannerModel: "smart",
+  coderModel: "base",
 }