@pmelab/gtd 28.2.0 → 29.0.0

package/src/workflows/shared/__fixtures__/feature-collecting-prompt.txt

@@ -0,0 +1,97 @@
+- A deliverable, not a chat reply — size follows the work; cut padding
+- Lead with the answer; never circle back to restate it
+- Flat, commanding sentences — commit to the claim, never hedge
+- Everyday words; define an unavoidable term in five words or fewer, on
+  first use
+- Bold carries the load: bold the claim, not the sentence around it —
+  the bold text alone must yield the full point and every risk
+- **Never trim a risk, a number, a threshold, or a scoped condition to
+  save space — this outranks every other rule here**
+- Ship the artifact bare — no lead-in, no sign-off
+- Compressing is not dropping: three load-bearing parts ship as three,
+  each shorter, never as two
+- One idea per block; break when the idea shifts
+- Flag risk in one blunt line, never hedged prose; never narrate — do it
+
+- Machine-read: its format contract outranks every style rule above —
+  keep every `##`/`###` heading, checkbox row, and marker line exactly
+  as specified. Never renumber or rename a heading; a parser reads
+  these literally and a violation refuses the turn
+- Voice rules above govern only the prose between these elements
+
+You are judging and classifying a round of review feedback.
+
+- You are an autonomous coding agent
+- This workflow's own state files are its private scratchpad, never
+  project code or documentation
+- A footnote (`[^name]` plus its `[^name]:` definition) is a comment on
+  its exact anchor — fold it in as a mandatory concern described
+  against that anchor's hunk or paragraph, never flattened into a
+  whole-file remark
+- A one-shot footnote needs no reply: fold it in and DELETE it in this
+  same turn — marker and definition together. Never re-read a footnote
+  already acted on. A one-shot footnote that asks a question becomes a
+  thread instead: rewrite its definition as `- H: <its body>` then
+  `- A: <your reply>`, keeping the marker
+- A thread is a definition whose body is a list of `- H:`/`- A:`
+  entries. Handle each by its last entry:
+  - last is `- H:` and asks something — reply with exactly one
+    `- A: <reply>` entry and change nothing else for it
+  - last concludes or advises — fold it in like a one-shot footnote,
+    then delete marker and definition
+  - last is `- A:` — it waits on the human; leave it alone
+- Never start a thread yourself, and never leave a thread whose last
+  entry is `- H:` — a turn that does is refused
+- This turn writes `.gtd/REQUIREMENTS.md` (the folded concerns) and
+  replies inside `.gtd/REVIEW.md` (thread replies only; the file stays
+  in the tree) — you classify, you do not build
+- Fold every concluded thread, ticked answer and hand-edit — and each
+  `edit` note the capture lists, no other note — into
+  `.gtd/REQUIREMENTS.md` and delete the folded threads from
+  `.gtd/REVIEW.md`; append one `- A:` reply to each thread
+  whose last entry is a `- H:` question
+- When the capture names an answering commit, carry each answered
+  question into `.gtd/REQUIREMENTS.md`'s `## Answered Questions` as
+  `### <the note>` plus its answer — the lap replaces `.gtd/REVIEW.md`
+- Keep capture order, and carry each note's `(tier: reason)`
+  label into the concern folded from it
+- Nit notes were already fixed: never re-raise a fixed nit as a concern
+- Finish by running `gtd check review .gtd/REVIEW.md` and fix
+  what it reports
+
+The raw review material is:
+
+capture-text
+It names a commit. Work from what you already reviewed if you
+wrote today's review earlier this conversation; otherwise read
+that commit's diff yourself first.
+
+The round is actionable if any of these hold:
+
+- The human left a note on `.gtd/REVIEW.md`. A note is a mandatory
+  concern below
+- The human added a code comment this round. A comment run whose
+  first line starts `H:` is a THREAD: when its last entry is an
+  `H:` question, write exactly one `A:` comment line, same token
+  and indentation, directly below it — no fold-in; a concluded
+  thread is folded into the requirements and its comment lines
+  deleted. Any other comment, even a plain-prose one, is a one-shot
+  concern — describe it, and note the comment line itself is
+  transient: it must not survive the lap that satisfies it
+- The human hand-edited non-comment code this round — no longer
+  a committed intent to build on, but a sketch like the entry
+  commit's own diff. Describe what it was reaching for; expect
+  the next lap to re-derive it from scratch, never call it final
+
+Not actionable only when none of the above holds — nothing but an
+approving remark, no code edit, no substantive note. Never invent
+actionability, and never dismiss a real note or edit as approval.
+
+- If actionable: write `.gtd/REQUIREMENTS.md` with an ordered
+  list of concerns, each PRODUCT or TECHNICAL — the shape
+  `design.triage` builds, one `## <heading>` per concern in
+  build order. Fold every note, comment, and hand-edit in under
+  its concern. Raise no open questions here — `design.triage`
+  owns that later. Then finish
+- If not: finish without writing anything — changing nothing is
+  the sign-off

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

@@ -22,9 +22,21 @@ describe("the bundled workflow's access export", () => {
       "build.quality.test-audit": { write: [] },
       "build.quality.conventions": { write: [] },
       "build.quality.spec-challenge": { write: [] },
+      "refactor.build.review": { write: [".gtd/REVIEW.md"] },
+      "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
+      "refactor.build.quality.correctness": { write: [] },
+      "refactor.build.quality.ponytail-review": { write: [] },
+      "refactor.build.quality.conventions": { write: [] },
     })
   })
 
+  it("leaves the refactor review's fix scopes to the refactor's own scope option", () => {
+    expect(bundled).not.toHaveProperty(["refactor.build.review.fix.nits"])
+    expect(bundled).not.toHaveProperty(["refactor.build.review.fix.risks"])
+    expect(bundled["refactor.build.review"]).toEqual({ write: [".gtd/REVIEW.md"] })
+    expect(bundled["refactor.build.review.defer"]).toEqual({ write: [".gtd/TODO.md"] })
+  })
+
   it("keys one lens scope per qualityReviews entry", () => {
     const custom = access({ ...defaults, qualityReviews: " my-lens ,, correctness" })
     expect(
@@ -34,9 +46,27 @@ describe("the bundled workflow's access export", () => {
     ).toEqual(["build.quality.correctness", "build.quality.my-lens"])
   })
 
+  it("keys one refactor lens scope per refactorQualityReviews entry beside the refactor review's own", () => {
+    const custom = access({ ...defaults, refactorQualityReviews: " my-lens ,, correctness" })
+    expect(
+      Object.keys(custom)
+        .filter((k) => k.startsWith("refactor."))
+        .sort(),
+    ).toEqual([
+      "refactor.build.quality.correctness",
+      "refactor.build.quality.my-lens",
+      "refactor.build.review",
+      "refactor.build.review.defer",
+    ])
+  })
+
   it("keys only turn or script scopes", () => {
     // `build.review.defer` is a script scope: no turn, so no skills entry.
-    const known = [...Object.keys(workflow.skills(defaults)), "build.review.defer"]
+    const known = [
+      ...Object.keys(workflow.skills(defaults)),
+      "build.review.defer",
+      "refactor.build.review.defer",
+    ]
     for (const key of Object.keys(bundled)) expect(known).toContain(key)
   })
 })

package/src/workflows/shared/access.ts

@@ -6,7 +6,8 @@ import { lensesOf, lensScopes } from "../../workflow-kit/index.js"
 // are restricted, and only on writes; no scope restricts reads. `refactor`'s
 // write restriction lives in its own `scope()` option, not here. A step's own
 // steering file is folded in per step, so it is not listed here. Build and fix
-// scopes carry no entry: no project layout is assumed.
+// scopes carry no entry: no project layout is assumed. `refactor.build.review`'s
+// fix scopes carry none either: `reviewedRefactor` sets their write limit at run time.
 export const access = (
   vars: Readonly<Record<string, string>>,
 ): Readonly<Record<string, ScopeAccess>> => ({
@@ -18,5 +19,10 @@ export const access = (
   // `{}` reopens what `build.review` restricted: the fixes edit code.
   "build.review.fix.nits": {},
   "build.review.fix.risks": {},
+  "refactor.build.review": { write: [".gtd/REVIEW.md"] },
+  "refactor.build.review.defer": { write: [".gtd/TODO.md"] },
   ...lensScopes("build.quality", lensesOf(vars.qualityReviews ?? ""), () => ({ write: [] })),
+  ...lensScopes("refactor.build.quality", lensesOf(vars.refactorQualityReviews ?? ""), () => ({
+    write: [],
+  })),
 })

package/src/workflows/shared/fences.ts

@@ -0,0 +1,19 @@
+// An unclosed fence runs to end of file. A backtick
+// opener with a backtick in its info string still counts as a fence: deviates from CommonMark,
+// worst case is `high`.
+export const markFenced = (text: string): readonly { line: string; fenced: boolean }[] => {
+  let fence: string | undefined // the opener run, e.g. "````"
+  return text.split(/\r?\n/).map((line) => {
+    const run = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1]
+    const fenced = fence !== undefined || run !== undefined
+    if (fence === undefined) fence = run
+    else if (
+      run !== undefined &&
+      run[0] === fence[0] &&
+      run.length >= fence.length &&
+      /^ {0,3}(`+|~+)[ \t]*$/.test(line)
+    )
+      fence = undefined
+    return { line, fenced }
+  })
+}

package/src/workflows/shared/health.ts

@@ -21,12 +21,12 @@ export const baseline = (name: string, label = "Checking the baseline"): Promise
 
 export type { EscalationCount } from "../../workflow-kit/index.js"
 
-const escalationSteps: kit.EscalationSteps = {
+const escalationSteps = (rules?: string): kit.EscalationSteps => ({
   limit: 2,
-  describe: describeEscalation,
+  describe: () => describeEscalation(rules),
   stop: escalate,
   exhausted: escalationExhausted,
-}
+})
 
 /** Runs after an agent or human turn; refuses it by throwing (`refuse`). */
 export type Guard = () => void
@@ -38,20 +38,32 @@ export const guarded =
     guard?.()
   }
 
-const guardedSteps = (guard?: Guard, describeGuard?: Guard): kit.EscalationSteps => ({
-  limit: escalationSteps.limit,
-  describe: guarded(guarded(escalationSteps.describe, guard), describeGuard),
-  stop: guarded(escalationSteps.stop, guard),
-  exhausted: guarded(escalationSteps.exhausted, guard),
-})
+const guardedSteps = (
+  guard?: Guard,
+  describeGuard?: Guard,
+  rests = true,
+  rules?: string,
+): kit.EscalationSteps => {
+  const steps = escalationSteps(rules)
+  return {
+    limit: steps.limit,
+    describe: guarded(guarded(steps.describe, guard), describeGuard),
+    stop: guarded(steps.stop, rests ? guard : undefined),
+    exhausted: guarded(steps.exhausted, rests ? guard : undefined),
+  }
+}
 
 /**
  * Hand a red suite that repeated attempts could not fix to a person: an
  * agent writes `.gtd/ESCALATION.md`, a human narrows it. From the third round
  * on, the human is told the budget is spent instead.
  */
-export const escalation = (count: kit.EscalationCount, guard?: Guard): Promise<void> =>
-  kit.escalation(count, guardedSteps(guard))
+export const escalation = (
+  count: kit.EscalationCount,
+  guard?: Guard,
+  guardRests = true,
+  rules?: string,
+): Promise<void> => kit.escalation(count, guardedSteps(guard, undefined, guardRests, rules))
 
 /** "Is this red round the same failure as the last one?" — asked of two reports, or of nothing when one is empty. */
 export const retryQuestion = (comparable: boolean): JudgeQuestion =>
@@ -100,6 +112,9 @@ export interface HealthOptions {
   readonly guard?: Guard | undefined
   /** Runs after the escalation's agent turn only; the human rests stay unguarded. */
   readonly describeGuard?: Guard | undefined
+  /** `false`: `guard` skips the human rests `health.stop` and `health.exhausted`. */
+  readonly guardRests?: boolean | undefined
+  readonly rules?: string | undefined
 }
 
 const runSuite = (options: HealthOptions): Promise<boolean> =>
@@ -123,7 +138,12 @@ export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}):
     fixesSoFar: options.fixesSoFar ?? 0,
     sameFailure,
     escalations: options.escalations ?? { rounds: 0 },
-    escalation: guardedSteps(options.guard, options.describeGuard),
+    escalation: guardedSteps(
+      options.guard,
+      options.describeGuard,
+      options.guardRests,
+      options.rules,
+    ),
   })
 
 /**

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

@@ -56,6 +56,24 @@ describe("the shipped workflow factories", () => {
     })
   })
 
+  it("build seamAllow's default from the test-file globs, byte-equal to the shipped string", () => {
+    expect(defaults.seamAllow).toBe(
+      "**/*.test.*, **/*.spec.*, **/*.feature, **/tests/**, **/test/**, **/__tests__/**, .gtd/**",
+    )
+  })
+
+  it("default refactorQualityReviews to the three refactor lenses and let a factory option win", () => {
+    expect(defaults.refactorQualityReviews).toBe("correctness, ponytail-review, conventions")
+    expect(configure(feature({ refactorQualityReviews: "correctness" }))).toMatchObject({
+      ok: true,
+      build: { defaults: { refactorQualityReviews: "correctness" } },
+    })
+    expect(configure(workflows.rollout({ refactorQualityReviews: "" }))).toMatchObject({
+      ok: true,
+      build: { defaults: { refactorQualityReviews: "" } },
+    })
+  })
+
   it("build the shipped settings unchanged with no options", () => {
     for (const factory of [feature, fix, review]) {
       expect(configure(factory)).toMatchObject({ ok: true, build: { defaults, envDefaults } })

package/src/workflows/shared/options.ts

@@ -19,6 +19,7 @@ export const ShippedOptions = Schema.Struct({
   refactorFlagPattern: setting,
   seamAllow: setting,
   qualityReviews: setting,
+  refactorQualityReviews: setting,
   testCommand: setting,
   plannerModel: setting,
   coderModel: setting,

package/src/workflows/shared/prose.ts

@@ -248,11 +248,13 @@ export const footnoteRules = `- Leave a footnote anywhere: mark the exact spot w
   file changed in this process (\`#\`, \`--\` or \`;\` by language); the phone UI does not show them,
   and \`gtd check --open-threads\` lists the open ones`
 
-export const footnoteFoldIn = `- A footnote (\`[^name]\` plus its \`[^name]:\` definition) is a comment on
+export const footnoteAnchor = `- A footnote (\`[^name]\` plus its \`[^name]:\` definition) is a comment on
   its exact anchor — fold it in as a mandatory concern described
   against that anchor's hunk or paragraph, never flattened into a
   whole-file remark
-- A one-shot footnote needs no reply: fold it in and DELETE it in this
+`
+
+export const footnoteFoldIn = `${footnoteAnchor}- A one-shot footnote needs no reply: fold it in and DELETE it in this
   same turn — marker and definition together. Never re-read a footnote
   already acted on. A one-shot footnote that asks a question becomes a
   thread instead: rewrite its definition as \`- H: <its body>\` then

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

@@ -39,6 +39,15 @@ describe("the bundled workflow's skills export", () => {
         "build.quality.test-audit",
         "build.quality.conventions",
         "build.quality.spec-challenge",
+        "refactor.build",
+        "refactor.build.health",
+        "refactor.build.fix.quality",
+        "refactor.build.review",
+        "refactor.build.review.fix.nits",
+        "refactor.build.review.fix.risks",
+        "refactor.build.quality.correctness",
+        "refactor.build.quality.ponytail-review",
+        "refactor.build.quality.conventions",
       ].sort(),
     )
   })
@@ -51,7 +60,6 @@ describe("the bundled workflow's skills export", () => {
       "build.quality",
       "implement.fix",
       "seam.judge",
-      "seam.approve",
       "seam.steer",
       "seam.by-hand",
     ]) {
@@ -84,6 +92,17 @@ describe("the bundled workflow's skills export", () => {
     })
   })
 
+  it("keys one refactor lens scope per refactorQualityReviews entry", () => {
+    const custom = skills({ ...defaults, refactorQualityReviews: " my-lens ,, correctness" })
+    expect(
+      Object.keys(custom)
+        .filter((k) => k.startsWith("refactor.build.quality."))
+        .sort(),
+    ).toEqual(["refactor.build.quality.correctness", "refactor.build.quality.my-lens"])
+    const none = skills({ ...defaults, refactorQualityReviews: "" })
+    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", () => {
     expect(bundled["build.quality.correctness"]).toEqual(["code-review-and-quality"])
     expect(bundled["build.quality.conventions"]).toEqual([])

package/src/workflows/shared/skills.ts

@@ -9,35 +9,46 @@ import { lensesOf, lensScopes } from "../../workflow-kit/index.js"
 // `qualityReviews` entry, so the export is a function of the vars.
 export const skills = (
   vars: Readonly<Record<string, string>>,
-): Readonly<Record<string, readonly string[]>> => ({
-  design: ["spec-driven-development", "planning-and-task-breakdown"],
-  architecture: ["api-and-interface-design", "documentation-and-adrs", "ponytail"],
-  "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
-  "packages.item": ["test-driven-development", "incremental-implementation"],
-  "packages.item.fix.suite": ["debugging-and-error-recovery"],
-  // `health` is shared code reached from both `packages.item` and `build`.
-  "packages.item.health": ["debugging-and-error-recovery"],
-  build: ["debugging-and-error-recovery"],
-  "build.health": ["debugging-and-error-recovery"],
-  "build.fix.quality": ["incremental-implementation", "code-simplification"],
-  "build.review": ["code-review-and-quality"],
-  "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
-  "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
-  // `fix`'s turn over the notes a review handed on.
-  notes: ["incremental-implementation", "code-simplification"],
-  // Every refactor agent turn loads `ponytail`.
-  refactor: ["ponytail"],
-  "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
-  "refactor.health": ["ponytail", "debugging-and-error-recovery"],
-  // Declared whether or not `naive_pass` is on, so a config keyed on them keeps
-  // loading when the flag flips off.
-  seam: ["incremental-implementation"],
-  implement: ["test-driven-development", "incremental-implementation"],
-  "implement.fix.suite": ["debugging-and-error-recovery"],
-  "implement.health": ["debugging-and-error-recovery"],
-  ...lensScopes(
-    "build.quality",
-    lensesOf(vars.qualityReviews ?? ""),
-    (lens) => builtInLenses[lens]?.skills ?? [lens],
-  ),
-})
+): Readonly<Record<string, readonly string[]>> => {
+  const build: Record<string, readonly string[]> = {
+    build: ["debugging-and-error-recovery"],
+    "build.health": ["debugging-and-error-recovery"],
+    "build.fix.quality": ["incremental-implementation", "code-simplification"],
+    "build.review": ["code-review-and-quality"],
+    "build.review.fix.nits": ["incremental-implementation", "code-simplification"],
+    "build.review.fix.risks": ["debugging-and-error-recovery", "incremental-implementation"],
+  }
+  return {
+    design: ["spec-driven-development", "planning-and-task-breakdown"],
+    architecture: ["api-and-interface-design", "documentation-and-adrs", "ponytail"],
+    "architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
+    "packages.item": ["test-driven-development", "incremental-implementation"],
+    "packages.item.fix.suite": ["debugging-and-error-recovery"],
+    // `health` is shared code reached from both `packages.item` and `build`.
+    "packages.item.health": ["debugging-and-error-recovery"],
+    // `fix`'s turn over the notes a review handed on.
+    notes: ["incremental-implementation", "code-simplification"],
+    // The refactor's own turns load `ponytail`; `refactor.build.*` carry the `build.*` lists.
+    ...build,
+    ...Object.fromEntries(Object.entries(build).map(([name, list]) => [`refactor.${name}`, list])),
+    refactor: ["ponytail"],
+    "refactor.fix.suite": ["ponytail", "debugging-and-error-recovery"],
+    "refactor.health": ["ponytail", "debugging-and-error-recovery"],
+    // Declared whether or not `naive_pass` is on, so a config keyed on them keeps
+    // loading when the flag flips off.
+    seam: ["incremental-implementation"],
+    implement: ["test-driven-development", "incremental-implementation"],
+    "implement.fix.suite": ["debugging-and-error-recovery"],
+    "implement.health": ["debugging-and-error-recovery"],
+    ...lensScopes(
+      "build.quality",
+      lensesOf(vars.qualityReviews ?? ""),
+      (lens) => builtInLenses[lens]?.skills ?? [lens],
+    ),
+    ...lensScopes(
+      "refactor.build.quality",
+      lensesOf(vars.refactorQualityReviews ?? ""),
+      (lens) => builtInLenses[lens]?.skills ?? [lens],
+    ),
+  }
+}

package/src/workflows/shared/steps.ts

@@ -1,4 +1,4 @@
-import { changesSince, env, human } from "../../flows/index.js"
+import { changesSince, env, human, scope, type ScopeAccess } from "../../flows/index.js"
 import { removedAssertions } from "../../workflow-kit/index.js"
 import * as t from "./text.js"
 
@@ -12,6 +12,7 @@ export const ESCALATION = ".gtd/ESCALATION.md"
 export const REQUIREMENTS = ".gtd/REQUIREMENTS.md"
 export const ARCHITECTURE = ".gtd/ARCHITECTURE.md"
 export const REVIEW = ".gtd/REVIEW.md"
+export const REFACTOR = ".gtd/REFACTOR.md"
 export const QUALITY = ".gtd/QUALITY.md"
 
 export const planner = (): string => env.plannerModel ?? ""
@@ -19,16 +20,16 @@ export const coder = (): string => env.coderModel ?? ""
 
 // ── Keeping the suite green ─────────────────────────────────────────────────
 
-export const fixCheck = (): Promise<void> =>
-  t.agentWithSkills("fix", t.buildFixPrompt(), {
+export const fixCheck = (rules?: string): Promise<void> =>
+  t.agentWithSkills("fix", t.buildFixPrompt(rules), {
     label: "Fixing the check",
     file: FEEDBACK,
     model: coder(),
     system: t.finisherSystem(),
   })
 
-export const describeEscalation = (): Promise<void> =>
-  t.agentWithSkills("health.describe", t.healthDescribePrompt(), {
+export const describeEscalation = (rules?: string): Promise<void> =>
+  t.agentWithSkills("health.describe", t.healthDescribePrompt(rules), {
     label: "Describing the escalation",
     file: FEEDBACK,
     model: coder(),
@@ -67,10 +68,10 @@ export const builtInLenses: Readonly<Record<string, BuiltInLens>> = {
 }
 
 /** One quality review through `lens`; each lens is its own scope, so its own conversation and skills. */
-export const reviewQuality = (lens: string): Promise<void> =>
+export const reviewQuality = (lens: string, base?: string): Promise<void> =>
   t.agentWithSkills(
     `quality.${lens}.reviewing`,
-    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief),
+    t.buildQualityReviewingPrompt(lens, builtInLenses[lens]?.brief, base),
     {
       label: "Reviewing (one quality lens)",
       file: QUALITY,
@@ -80,8 +81,8 @@ export const reviewQuality = (lens: string): Promise<void> =>
     },
   )
 
-export const fixQuality = (): Promise<void> =>
-  t.agentWithSkills("fix.quality.fixing", t.buildFixQualityPrompt(), {
+export const fixQuality = (rules?: string): Promise<void> =>
+  t.agentWithSkills("fix.quality.fixing", t.buildFixQualityPrompt(rules), {
     label: "Fixing quality findings",
     file: QUALITY,
     model: coder(),
@@ -90,10 +91,14 @@ export const fixQuality = (): Promise<void> =>
   })
 
 /** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
-export const reviewing = (base: string, carry?: string): Promise<void> =>
+export const reviewing = (
+  base: string,
+  carry?: string,
+  lap: t.ReviewRange = "first",
+): Promise<void> =>
   t.agentWithSkills(
     "review.reviewing",
-    t.buildReviewReviewingPrompt(base, carry, removedAssertions(changesSince(base))),
+    t.buildReviewReviewingPrompt(base, lap, carry, removedAssertions(changesSince(base))),
     {
       label: "Reviewing",
       file: REVIEW,
@@ -105,14 +110,23 @@ export const reviewing = (base: string, carry?: string): Promise<void> =>
   )
 
 /** 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.fixing", t.buildReviewFixRisksPrompt(notes), {
-    label: "Fixing the reviewer's risks",
-    file: REVIEW,
-    model: planner(),
-    system: t.reviewerSystem(),
-    allowEmpty: true,
-  })
+export const fixRisks = (
+  notes: readonly t.NoteInput[],
+  access?: ScopeAccess,
+  rules?: string,
+): Promise<void> => {
+  const fixing = (name: string): Promise<void> =>
+    t.agentWithSkills(name, t.buildReviewFixRisksPrompt(notes, rules), {
+      label: "Fixing the reviewer's risks",
+      file: REVIEW,
+      model: planner(),
+      system: t.reviewerSystem(),
+      allowEmpty: true,
+    })
+  return access === undefined
+    ? fixing("review.fix.risks.fixing")
+    : scope({ name: "review.fix.risks", access }, () => fixing("fixing"))
+}
 
 export const awaitReview = (
   base: string,

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

@@ -6,7 +6,7 @@ import {
   type StepRequest,
 } from "../../flows/index.js"
 import type { Guard } from "./health.js"
-import { handOffReview, REVIEW_ORIG } from "./tail.js"
+import { handOffReview, qualityLap, REVIEW_ORIG, tail } from "./tail.js"
 import { fixtureContext } from "./text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -206,3 +206,86 @@ describe("the hand-off review", () => {
     })
   })
 })
+
+const prompts: string[] = []
+
+describe("the quality lap's lenses", () => {
+  const lap = async (run: () => Promise<unknown>, vars: Record<string, string> = {}) => {
+    const log: string[] = []
+    prompts.length = 0
+    installContext(
+      fixtureContext(
+        { vars },
+        {
+          step: (request: StepRequest) => {
+            if (request.kind !== "restart") log.push(request.name)
+            if (request.kind === "agent") prompts.push(request.prompt)
+            return Promise.resolve()
+          },
+          pushScope: () => undefined,
+          popScope: () => undefined,
+          start: () => "START-SHA",
+        },
+      ),
+    )
+    await run()
+    return log
+  }
+
+  it("default to the qualityReviews setting", async () => {
+    const log = await lap(() => qualityLap(), { qualityReviews: "correctness, conventions" })
+    expect(log).toEqual(["quality.correctness.reviewing", "quality.conventions.reviewing"])
+  })
+
+  it("lenses override qualityReviews", async () => {
+    const log = await lap(() => qualityLap(undefined, ["ponytail-review"]), {
+      qualityReviews: "correctness, conventions",
+    })
+    expect(log).toEqual(["quality.ponytail-review.reviewing"])
+  })
+
+  it("an empty list runs no lens turn", async () => {
+    const log = await lap(() => qualityLap(undefined, []), { qualityReviews: "correctness" })
+    expect(log).toEqual([])
+  })
+
+  it("lensBase reaches every lens turn's prompt; absent, they name start()", async () => {
+    await lap(() => qualityLap(undefined, ["conventions", "correctness"], "BASE-SHA"))
+    expect(prompts).toHaveLength(2)
+    for (const prompt of prompts) expect(prompt).toContain("from `BASE-SHA`")
+    await lap(() => qualityLap(undefined, ["conventions", "correctness"]))
+    expect(prompts).toHaveLength(2)
+    for (const prompt of prompts) expect(prompt).toContain("from `START-SHA`")
+  })
+
+  it("tail threads lensBase to every lens turn", async () => {
+    await lap(() =>
+      tail(
+        false,
+        () => Promise.resolve(),
+        true,
+        undefined,
+        ["conventions", "correctness"],
+        true,
+        "BASE-SHA",
+      ),
+    )
+    expect(prompts).toHaveLength(2)
+    for (const prompt of prompts) expect(prompt).toContain("from `BASE-SHA`")
+  })
+
+  it("tail passes lenses to its lap and a guard after each lens turn", async () => {
+    let guards = 0
+    const log = await lap(() =>
+      tail(
+        false,
+        () => Promise.resolve(),
+        true,
+        () => void guards++,
+        ["conventions"],
+      ),
+    )
+    expect(log).toEqual(["quality.conventions.reviewing"])
+    expect(guards).toBe(1)
+  })
+})