@pmelab/gtd 17.3.0 → 18.0.0

package/src/workflows/steps.test.ts

@@ -5,95 +5,83 @@ import * as steps from "./steps.js"
 
 const capture = (
   fn: () => Promise<void>,
+  scope: string,
   skills?: Readonly<Record<string, readonly string[]>>,
-): Promise<StepRequest> => captureStep(fn, skills !== undefined ? { skills } : {})
+): Promise<StepRequest> => captureStep(fn, { scope, ...(skills !== undefined ? { skills } : {}) })
 
 const agentPrompt = (request: StepRequest): string => {
   if (request.kind !== "agent") throw new Error(`expected an agent step, got ${request.kind}`)
   return request.prompt
 }
 
-// The preamble (`agentPrompt`) reflects `skillsFor`'s resolved map — but the
-// WIRE `skills` field a request actually carries is whatever `options.skills`
-// the step itself passed; `Replay.ts`'s `resolve()` only overrides it from
-// `.gtdrc` (never reachable here — this fixture skips replay entirely). Most
-// bundled steps pass no `skills` option of their own, so this is normally
-// `undefined`; `reviewQuality` is the one step that does.
-const agentSkillsOption = (request: StepRequest): readonly string[] | undefined => {
-  if (request.kind !== "agent") throw new Error(`expected an agent step, got ${request.kind}`)
-  return request.options.skills
-}
-
 describe("the bundled workflow's steps declare skills — a bundled step's rendered prompt carries its bundled skills.ts preamble", () => {
   it("triage carries design.triage's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.triage("base")))
+    const prompt = agentPrompt(await capture(() => steps.triage("base"), "design"))
     expect(prompt).toContain("spec-driven-development, planning-and-task-breakdown")
   })
 
   it("author carries architecture.author's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.author()))
+    const prompt = agentPrompt(await capture(() => steps.author(), "architecture"))
     expect(prompt).toContain("api-and-interface-design, documentation-and-adrs, ponytail")
   })
 
   it("decompose carries architecture.decompose's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.decompose()))
+    const prompt = agentPrompt(await capture(() => steps.decompose(), "architecture"))
     expect(prompt).toContain("incremental-implementation, planning-and-task-breakdown")
   })
 
   it("build carries packages.item.building's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.build("pkg")))
+    const prompt = agentPrompt(await capture(() => steps.build("pkg"), "packages.item"))
     expect(prompt).toContain("test-driven-development, incremental-implementation")
   })
 
-  it("fixSuite carries packages.item.fix-suite's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fixSuite()))
+  it("fixSuite carries packages.item.fix.suite's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.fixSuite(), "packages.item"))
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
-  it("fixSpec carries packages.item.fix-spec's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fixSpec("pkg")))
+  it("fixSpec carries packages.item.fix.spec's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.fixSpec("pkg"), "packages.item"))
     expect(prompt).toContain("incremental-implementation, code-simplification")
   })
 
   it("reviewPackage carries packages.item.spec.review's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.reviewPackage("pkg")))
+    const prompt = agentPrompt(await capture(() => steps.reviewPackage("pkg"), "packages.item"))
     expect(prompt).toContain("code-review-and-quality, spec-driven-development")
   })
 
   it("fix carries build.fix's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fix()))
+    const prompt = agentPrompt(await capture(() => steps.fix(), "build"))
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
   it("describeEscalation carries health.describe's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.describeEscalation()))
+    const prompt = agentPrompt(await capture(() => steps.describeEscalation(), "build"))
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
-  it("reviewQuality's preamble falls back to the lens itself by default — build.quality.reviewing bundles no fixed skills of its own", async () => {
-    const prompt = agentPrompt(await capture(() => steps.reviewQuality("owasp-security")))
-    expect(prompt).toContain("missing one: owasp-security")
+  it("reviewQuality names its lens scope, build.quality.<lens>.reviewing", async () => {
+    const request = await capture(() => steps.reviewQuality("owasp-security"), "build")
+    if (request.kind !== "agent") throw new Error("unreachable")
+    expect(request.name).toBe("quality.owasp-security.reviewing")
   })
 
-  it("reviewQuality's own wire skills option IS the lens by default — the same list its preamble now names, never one without the other", async () => {
-    const request = await capture(() => steps.reviewQuality("owasp-security"))
-    expect(agentSkillsOption(request)).toEqual(["owasp-security"])
+  it("an unknown lens's preamble names the lens itself, from the bundled per-lens key", async () => {
+    const prompt = agentPrompt(await capture(() => steps.reviewQuality("owasp-security"), "build"))
+    expect(prompt).toContain("missing one: owasp-security")
   })
 
-  it("reviewQuality's preamble reflects a configured build.quality.reviewing entry, every turn, regardless of lens", async () => {
+  it("a configured build.quality.<lens> entry replaces the lens's skills in the preamble, every other lens untouched", async () => {
+    const skills = { "build.quality.owasp-security": ["my-org-checklist"] }
     const prompt = agentPrompt(
-      await capture(() => steps.reviewQuality("owasp-security"), {
-        "quality.reviewing": ["my-org-checklist"],
-      }),
+      await capture(() => steps.reviewQuality("owasp-security"), "build", skills),
     )
     expect(prompt).toContain("my-org-checklist")
-    // The body still names the lens — what makes N otherwise identical prompts distinguishable.
     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"])
+  it("correctness carries all four trace points", async () => {
+    const request = await capture(() => steps.reviewQuality("correctness"), "build")
     const body = JSON.stringify(request)
     for (const point of [
       "partial-failure",
@@ -104,57 +92,44 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
       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.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("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("an unknown lens has no brief", async () => {
+    const request = await capture(() => steps.reviewQuality("my-lens"), "build")
+    expect(JSON.stringify(request)).not.toContain("This lens's brief")
   })
 
-  it("fixQuality carries build.fix-quality's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fixQuality()))
+  it("fixQuality carries build.fix.quality's bundled skills", async () => {
+    const prompt = agentPrompt(await capture(() => steps.fixQuality(), "build"))
     expect(prompt).toContain("incremental-implementation, code-simplification")
   })
 
   it("reviewing carries build.review.reviewing's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.reviewing("base")))
+    const prompt = agentPrompt(await capture(() => steps.reviewing("base"), "build"))
     expect(prompt).toContain("code-review-and-quality")
   })
 
   it("collecting carries build.review.collecting's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.collecting("capture")))
+    const prompt = agentPrompt(await capture(() => steps.collecting("capture"), "build"))
     expect(prompt).toContain("code-review-and-quality")
   })
 
   it("an empty configured list leaves that step's skills empty, and its rendered prompt bare", async () => {
-    const request = await capture(() => steps.fix(), { fix: [] })
+    const request = await capture(() => steps.fix(), "build", { build: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).not.toContain("Load whatever's listed here")
   })
 
   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?" }]),
+    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")
@@ -169,14 +144,16 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   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" },
-      ]),
+    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")
+    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")
@@ -184,11 +161,12 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   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" }]),
+    const request = await capture(
+      () => steps.fixRisks([{ id: "risk-1", anchor: "calc ./a.ts#1-1", text: "Risk: drops it" }]),
+      "build",
     )
     if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.name).toBe("review.fix-risks")
+    expect(request.name).toBe("review.fix.risks.fixing")
     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")
@@ -197,8 +175,8 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   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"))
+    const bare = await capture(() => steps.reviewing("base"), "build")
+    const carried = await capture(() => steps.reviewing("base", "abc1234"), "build")
     if (bare.kind !== "agent" || carried.kind !== "agent") throw new Error("unreachable")
     expect(bare.prompt).not.toContain("Carry-over")
     expect(carried.prompt).toContain("Carry-over: commit `abc1234`")

package/src/workflows/steps.ts

@@ -39,7 +39,7 @@ export const author = (): Promise<void> =>
   })
 
 export const decompose = (): Promise<void> =>
-  t.agentWithSkills("decompose", t.architectureDecomposePrompt(), {
+  t.agentWithSkills("decompose.decomposing", t.architectureDecomposePrompt(), {
     label: "Decomposing into packages",
     model: planner(),
     system: t.architectSystem(),
@@ -73,7 +73,7 @@ export const build = (pkg: string): Promise<void> =>
   })
 
 export const fixSuite = (): Promise<void> =>
-  t.agentWithSkills("fix-suite", t.packagesItemFixSuitePrompt(), {
+  t.agentWithSkills("fix.suite.fixing", t.packagesItemFixSuitePrompt(), {
     label: "Fixing the check",
     file: FEEDBACK,
     model: coder(),
@@ -81,7 +81,7 @@ export const fixSuite = (): Promise<void> =>
   })
 
 export const fixSpec = (pkg: string): Promise<void> =>
-  t.agentWithSkills("fix-spec", t.packagesItemFixSpecPrompt(pkg), {
+  t.agentWithSkills("fix.spec.fixing", t.packagesItemFixSpecPrompt(pkg), {
     label: "Fixing review feedback",
     file: SPEC_FEEDBACK,
     model: coder(),
@@ -146,15 +146,10 @@ export const builtInLenses: Readonly<Record<string, BuiltInLens>> = {
   "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
- * overrides it (config beats a flow-supplied list same as any other step),
- * but absent one the lens itself is what the turn loads by default.
- */
+/** One quality review through `lens`; each lens is its own scope, so its own conversation and skills. */
 export const reviewQuality = (lens: string): Promise<void> =>
   t.agentWithSkills(
-    "quality.reviewing",
+    `quality.${lens}.reviewing`,
     t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief),
     {
       label: "Reviewing (one quality lens)",
@@ -162,12 +157,11 @@ export const reviewQuality = (lens: string): Promise<void> =>
       model: planner(),
       system: t.reviewerSystem(),
       allowEmpty: true,
-      skills: builtInLenses[lens]?.skills ?? [lens],
     },
   )
 
 export const fixQuality = (): Promise<void> =>
-  t.agentWithSkills("fix-quality", t.buildFixQualityPrompt(), {
+  t.agentWithSkills("fix.quality.fixing", t.buildFixQualityPrompt(), {
     label: "Fixing quality findings",
     file: QUALITY,
     model: coder(),
@@ -196,21 +190,18 @@ export const answerReviewQuestions = (notes: readonly t.NoteInput[]): Promise<vo
     system: t.reviewerSystem(),
   })
 
-/**
- * Fix every `nit` note in one turn. Its name puts it in the `build.review`
- * conversation, which has one identity — so it runs as the reviewer, not the coder.
- */
+/** Fix every `nit` note in one turn. */
 export const fixNits = (notes: readonly t.NoteInput[]): Promise<void> =>
-  t.agentWithSkills("review.fix-nits", t.buildReviewFixNitsPrompt(notes), {
+  t.agentWithSkills("review.fix.nits.fixing", t.buildReviewFixNitsPrompt(notes), {
     label: "Fixing your nits",
     file: REVIEW,
     model: planner(),
     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. */
+/** Fix the `Risk:`-marked notes the reviewer named; 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), {
+  t.agentWithSkills("review.fix.risks.fixing", t.buildReviewFixRisksPrompt(notes), {
     label: "Fixing the reviewer's risks",
     file: REVIEW,
     model: planner(),

package/src/workflows/text.fixture.ts

@@ -14,15 +14,9 @@ export interface TextContext {
   readonly start?: string
   readonly codeThreads?: readonly CodeThreadInfo[]
   readonly read?: (path: string) => string | undefined
-  /**
-   * A PER-KEY `skillsFor` override, keyed by the LOCAL name a bundled step
-   * calls itself with (`captureStep`/`renderText` push no scopes, so a local
-   * name is also the only name here) — stands in for a `.gtdrc` entry, so
-   * only the key it names is overridden; every other step still falls back
-   * to the call's own `skills` option, then the bundled map (`./skills.ts`),
-   * so an existing step test keeps its skills without having to declare them
-   * itself.
-   */
+  /** The scope the step runs in (`"build.review"`); the fixture pushes no scopes, so this stands in for the caller's. */
+  readonly scope?: string
+  /** Stands in for `.gtdrc` `skills:`, keyed by scope full name. */
   readonly skills?: Readonly<Record<string, readonly string[]>>
 }
 
@@ -30,28 +24,19 @@ const unavailable = (): never => {
   throw new Error("not available while rendering a text outside a replay")
 }
 
-/** The bundled map is keyed by FULL name, but a bundled step calls itself by its own LOCAL name and this fixture pushes no scope to prefix it with — so the default lookup matches on the local name alone, or as the last `.`-separated segment of a bundled key. `health.describe`'s two bundled entries (`packages.item.health.describe`, `build.health.describe`) share one list, so the ambiguity this leaves resolves to the same answer either way. */
-const bundledSkillsFor = (localName: string): readonly string[] => {
-  const exact = bundledSkills[localName]
-  if (exact !== undefined) return exact
-  const suffix = `.${localName}`
-  const hit = Object.entries(bundledSkills).find(([key]) => key.endsWith(suffix))
-  return hit?.[1] ?? []
-}
-
-/**
- * Mirrors `Replay.ts`'s `resolveSkills` three-way precedence: `context.skills`
- * (a per-key override, standing in for `.gtdrc`) beats `ownSkills` (a call's
- * own `skills` option), which beats the bundled default — so a step test that
- * passes its own `skills` option (like `reviewQuality`'s lens) sees it in the
- * preamble too, the same as a real replay would.
- */
+/** Mirrors `Replay.ts`'s scope walk: for each prefix of the step's memory scope, innermost first, a `.gtdrc` entry, then the bundled export. */
 const skillsForOf =
   (context: TextContext) =>
-  (localName: string, ownSkills?: readonly string[]): readonly string[] => {
-    const configured = context.skills?.[localName]
-    if (configured !== undefined) return configured
-    return ownSkills ?? bundledSkillsFor(localName)
+  (localName: string): readonly string[] => {
+    const full = [context.scope, localName].filter((part) => part !== undefined && part !== "")
+    const parts = full.join(".").split(".").slice(0, -1)
+    const bundled = bundledSkills({ ...defaults, ...context.vars })
+    for (let n = parts.length; n >= 0; n--) {
+      const prefix = parts.slice(0, n).join(".")
+      const hit = context.skills?.[prefix] ?? bundled[prefix]
+      if (hit !== undefined) return hit
+    }
+    return []
   }
 
 /** The fixed replay context texts render against; steps, refusals and scopes are unavailable unless overridden. */

package/src/workflows/text.test.ts

@@ -33,11 +33,11 @@ describe("withSkills", () => {
 
 describe("agentWithSkills", () => {
   const capture = (fn: () => Promise<void>, skills?: Readonly<Record<string, readonly string[]>>) =>
-    captureStep(fn, skills !== undefined ? { skills } : {})
+    captureStep(fn, { scope: "a", ...(skills !== undefined ? { skills } : {}) })
 
-  it("puts skillsFor(name)'s list, joined, in the preamble", async () => {
+  it("puts the scope's list, joined, in the preamble", async () => {
     const request = await capture(() => agentWithSkills("name", "do-the-work"), {
-      name: ["code-review", "testing"],
+      a: ["code-review", "testing"],
     })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).toBe(withSkills("code-review, testing", "do-the-work"))
@@ -46,22 +46,14 @@ describe("agentWithSkills", () => {
   it("passes no skills option itself — the replay resolver fills the wire field", async () => {
     const request = await capture(() => agentWithSkills("name", "do-the-work"))
     if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.options.skills).toBeUndefined()
+    expect(request.options).not.toHaveProperty("skills")
   })
 
-  it("leaves the prompt bare when the name resolves to no configured skills", async () => {
-    const request = await capture(() => agentWithSkills("name", "do-the-work"), { name: [] })
+  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")
     expect(request.prompt).toBe("do-the-work")
   })
-
-  it("still accepts an explicit options.skills of its own, untouched", async () => {
-    const request = await capture(() =>
-      agentWithSkills("name", "do-the-work", { skills: ["own-skill"] }),
-    )
-    if (request.kind !== "agent") throw new Error("unreachable")
-    expect(request.options.skills).toEqual(["own-skill"])
-  })
 })
 
 describe("the shared open-question instruction", () => {

package/src/workflows/text.ts

@@ -37,23 +37,12 @@ export const withSkills = (skills: string | undefined, prompt: string): string =
   return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`
 }
 
-/**
- * An `agent()` step whose preamble names its resolved skills: `skillsFor`
- * resolves `name` (scoped from here, same as `agent()`'s own resolver) for
- * the preamble prose, passing `options.skills` through as `ownSkills` — the
- * same precedence tier `agent()`'s own wire resolver gives a call's own
- * `skills` option, so a step that declares one (`reviewQuality`'s per-turn
- * lens) gets it in the preamble too, not just on the wire, whenever no
- * bundled or configured entry outranks it. Both reads share one resolver
- * (`Replay.ts`'s `resolveSkills`), so the preamble and the wire can't drift
- * apart.
- */
+/** An `agent()` step whose prompt opens with the preamble naming its scope's skills. */
 export const agentWithSkills = (
   name: string,
   prompt: string,
   options: AgentOptions = {},
-): Promise<void> =>
-  agent(name, withSkills(skillsFor(name, options.skills).join(", "), prompt), options)
+): Promise<void> => agent(name, withSkills(skillsFor(name).join(", "), prompt), options)
 
 export const unwindFailure = (commit: string): string =>
   `gtd could not unwind ${commit} out of your working tree.`
@@ -612,7 +601,7 @@ When you've been through the whole diff, run \`gtd land\`:
   - \`question\` — answered inline under the note in
     \`.gtd/REVIEW.md\` (**review.answer-review-questions**); the process
     rests at this gate again, no lap
-  - \`nit\` — fixed in one batched turn (**review.fix-nits**), then a
+  - \`nit\` — fixed in one batched turn (**review.fix.nits.fixing**), then a
     fresh review of the change rests at this gate again, no re-plan
   - \`praise\` — dropped; a round of only praise signs off
   When a round mixes \`edit\` with \`question\` or \`nit\`, questions get

package/src/workflows/vars.ts

@@ -12,10 +12,8 @@ export const defaults: Readonly<Record<string, string>> = {
   specPreJudge: "0.9",
   reviewNoteActionable: "0.7",
   architectureSkipMinP: "0.85",
-  // `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.
+  // Decides the turn count: one `build.quality.<lens>` scope per entry, each
+  // keyed in `./skills.ts`.
   qualityReviews:
     "correctness, owasp-security, ponytail-review, test-audit, conventions, spec-challenge",
 }