@pmelab/gtd 27.1.0 → 27.2.0

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

@@ -0,0 +1,305 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { installContext } from "../../flows/index.js"
+import { flagReferences, flipProblems, registryEntry, requireFlag } from "./registry.js"
+
+const ONE_LINE = `export const FLAGS = [
+  { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+  { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release", defaultOn: true },
+  { name: "gamma", owner: "c", expiry: "2027-03-01", kind: "ops" },
+] as const
+`
+
+const WRAPPED = `export const FLAGS = [
+  {
+    name: "alpha",
+    owner: "a",
+    expiry: "2027-01-01",
+    kind: "release",
+  },
+  {
+    name: "beta",
+    owner: "b",
+    expiry: "2027-02-01",
+    kind: "release",
+    defaultOn: true,
+  },
+] as const
+`
+
+describe("registryEntry", () => {
+  it("finds name, kind and defaultOn in a one-line entry", () => {
+    expect(registryEntry(ONE_LINE, "alpha")).toEqual({
+      kind: "release",
+      defaultOn: false,
+    })
+    expect(registryEntry(ONE_LINE, "beta")).toEqual({
+      kind: "release",
+      defaultOn: true,
+    })
+    expect(registryEntry(ONE_LINE, "gamma")?.kind).toBe("ops")
+  })
+
+  it("finds them in an oxfmt-wrapped entry", () => {
+    expect(registryEntry(WRAPPED, "alpha")).toEqual({
+      kind: "release",
+      defaultOn: false,
+    })
+    expect(registryEntry(WRAPPED, "beta")?.defaultOn).toBe(true)
+  })
+
+  it("is undefined for an unknown name", () => {
+    expect(registryEntry(ONE_LINE, "delta")).toBeUndefined()
+  })
+
+  it("ignores a kind inside a block comment ahead of the real one", () => {
+    const text = 'export const FLAGS = [{ name: "alpha", /* kind: "ops" */ kind: "release" }]'
+    expect(registryEntry(text, "alpha")?.kind).toBe("release")
+  })
+
+  it("reads no kind from one with no closing quote", () => {
+    const text = 'export const FLAGS = [{ name: "alpha", kind: "release-candidate" }]'
+    expect(registryEntry(text, "alpha")?.kind).toBe("")
+  })
+
+  it("reads the kind right after a comment with no space between", () => {
+    const text = 'export const FLAGS = [{ name: "alpha", /*x*/kind: "release" }]'
+    expect(registryEntry(text, "alpha")?.kind).toBe("release")
+  })
+
+  it("ignores a kind inside a line comment on a prior line", () => {
+    const text =
+      'export const FLAGS = [{\n  name: "alpha",\n  // kind: "ops"\n  kind: "release",\n}]'
+    expect(registryEntry(text, "alpha")?.kind).toBe("release")
+  })
+
+  it("ignores a kind inside a string ahead of the real one", () => {
+    const text = `export const FLAGS = [{ name: "alpha", owner: "kind: 'ops'", kind: "release" }]`
+    expect(registryEntry(text, "alpha")?.kind).toBe("release")
+  })
+})
+
+describe("flipProblems", () => {
+  it("is empty when defaultOn is added to the named entry", () => {
+    const after = ONE_LINE.replace(
+      'kind: "release" },\n  { name: "beta"',
+      'kind: "release", defaultOn: true },\n  { name: "beta"',
+    )
+    expect(after).not.toBe(ONE_LINE)
+    expect(flipProblems(ONE_LINE, after, "alpha")).toEqual([])
+  })
+
+  it("is empty when false flips to true", () => {
+    const before = ONE_LINE.replace('kind: "release" },', 'kind: "release", defaultOn: false },')
+    const after = ONE_LINE.replace('kind: "release" },', 'kind: "release", defaultOn: true },')
+    expect(flipProblems(before, after, "alpha")).toEqual([])
+  })
+
+  it("ignores re-wrapping and a trailing comma inside the entry", () => {
+    const after = WRAPPED.replace(
+      'kind: "release",\n  },',
+      'kind: "release",\n    defaultOn: true,\n  },',
+    )
+    expect(flipProblems(WRAPPED, after, "alpha")).toEqual([])
+    const oneLiner = ONE_LINE.replace(
+      'kind: "release" },\n  { name: "beta"',
+      'kind: "release", defaultOn: true, },\n  { name: "beta"',
+    )
+    expect(flipProblems(ONE_LINE, oneLiner, "alpha")).toEqual([])
+  })
+
+  describe("with a non-BMP character in the entry", () => {
+    const EMOJI =
+      'export const FLAGS = [\n  { name: "alpha", owner: "Team 🚀", kind: "release" },\n]'
+
+    it("is empty for an oxfmt re-wrap with a trailing comma", () => {
+      const after =
+        'export const FLAGS = [\n  {\n    name: "alpha",\n    owner: "Team 🚀",\n    kind: "release",\n    defaultOn: true,\n  },\n]'
+      expect(flipProblems(EMOJI, after, "alpha")).toEqual([])
+    })
+
+    it("faults an out-of-scope edit to a field after the emoji", () => {
+      const before =
+        'export const FLAGS = [\n  { name: "alpha", owner: "Team 🚀", kind: " release", defaultOn: false },\n]'
+      const after =
+        'export const FLAGS = [\n  { name: "alpha", owner: "Team 🚀", kind: "release", defaultOn: true },\n]'
+      expect(flipProblems(before, after, "alpha")).toContain(
+        'entry "alpha" changed beyond defaultOn',
+      )
+    })
+  })
+
+  it("faults a change to a second entry", () => {
+    const after = ONE_LINE.replace(
+      'kind: "release" },',
+      'kind: "release", defaultOn: true },',
+    ).replace('owner: "c"', 'owner: "z"')
+    expect(flipProblems(ONE_LINE, after, "alpha")).not.toEqual([])
+  })
+
+  it("faults an owner or expiry change inside the entry", () => {
+    const owner = ONE_LINE.replace(
+      'owner: "a", expiry: "2027-01-01", kind: "release"',
+      'owner: "q", expiry: "2027-01-01", kind: "release", defaultOn: true',
+    )
+    const expiry = ONE_LINE.replace(
+      'owner: "a", expiry: "2027-01-01", kind: "release"',
+      'owner: "a", expiry: "2030-01-01", kind: "release", defaultOn: true',
+    )
+    expect(flipProblems(ONE_LINE, owner, "alpha")).not.toEqual([])
+    expect(flipProblems(ONE_LINE, expiry, "alpha")).not.toEqual([])
+  })
+
+  it("faults a comment outside the entry", () => {
+    const after = `// note\n${ONE_LINE.replace('kind: "release" },', 'kind: "release", defaultOn: true },')}`
+    expect(flipProblems(ONE_LINE, after, "alpha")).not.toEqual([])
+  })
+
+  it("faults defaultOn: false", () => {
+    const after = ONE_LINE.replace('kind: "release" },', 'kind: "release", defaultOn: false },')
+    expect(flipProblems(ONE_LINE, after, "alpha")).not.toEqual([])
+  })
+
+  it("faults an unchanged registry", () => {
+    expect(flipProblems(ONE_LINE, ONE_LINE, "alpha")).toEqual([
+      '"alpha" is not set to defaultOn: true',
+    ])
+  })
+
+  it("faults a removed entry", () => {
+    expect(flipProblems(ONE_LINE, "export const FLAGS = []\n", "alpha")).toEqual([
+      'entry "alpha" is gone',
+    ])
+  })
+
+  it("faults defaultOn smuggled into a string instead of set as a property", () => {
+    const after = ONE_LINE.replace('owner: "a"', 'owner: "adefaultOn: true"')
+    expect(flipProblems(ONE_LINE, after, "alpha")).not.toEqual([])
+  })
+
+  it("faults whitespace edited inside a string", () => {
+    const before = ONE_LINE.replace('owner: "a"', 'owner: "a b"')
+    const after = before
+      .replace('owner: "a b"', 'owner: "ab"')
+      .replace('kind: "release" },', 'kind: "release", defaultOn: true },')
+    expect(flipProblems(before, after, "alpha")).not.toEqual([])
+  })
+
+  it("is empty for a flip when a JSDoc example of the entry precedes the array", () => {
+    const doc = '/** e.g. { name: "alpha", kind: "ops" } */\n'
+    const after = ONE_LINE.replace('kind: "release" },', 'kind: "release", defaultOn: true },')
+    expect(flipProblems(doc + ONE_LINE, doc + after, "alpha")).toEqual([])
+  })
+})
+
+describe("flipProblems trailing commas", () => {
+  const flip = (s: string) => s.replace('kind: "release" }', 'kind: "release", defaultOn: true }')
+
+  it("faults a comma-brace dropped inside a string", () => {
+    const before = ONE_LINE.replace('owner: "a"', 'owner: "team,}blue"')
+    const after = flip(before).replace('"team,}blue"', '"team}blue"')
+    expect(flipProblems(before, after, "alpha")).toContain('entry "alpha" changed beyond defaultOn')
+  })
+
+  it("faults a comma-brace dropped inside a comment", () => {
+    const before = ONE_LINE.replace('kind: "release" }', 'kind: "release", /* a,} */ }')
+    const after = flip(before).replace("/* a,} */", "/* a} */")
+    expect(flipProblems(before, after, "alpha")).toContain('entry "alpha" changed beyond defaultOn')
+  })
+
+  it("passes a real trailing comma added or removed", () => {
+    const comma = flip(ONE_LINE).replace("defaultOn: true }", "defaultOn: true, }")
+    expect(flipProblems(ONE_LINE, comma, "alpha")).toEqual([])
+    const before = ONE_LINE.replace('kind: "release" }', 'kind: "release", }')
+    expect(flipProblems(before, flip(ONE_LINE), "alpha")).toEqual([])
+  })
+})
+
+describe("requireFlag", () => {
+  afterEach(() => installContext(undefined))
+
+  const asFile = (text: string | undefined) =>
+    installContext({
+      read: (path: string) => (path === "reg.ts" ? text : undefined),
+      refuse: (message: string): never => {
+        throw new Error(message)
+      },
+    } as never)
+
+  it("accepts a flag that matches", () => {
+    asFile(ONE_LINE)
+    expect(() => requireFlag("rollout", "reg.ts", "alpha", false)).not.toThrow()
+    expect(() => requireFlag("cleanup", "reg.ts", "beta", true)).not.toThrow()
+  })
+
+  it("refuses an empty name", () => {
+    asFile(ONE_LINE)
+    expect(() => requireFlag("rollout", "reg.ts", "", false)).toThrow(
+      "gtd: rollout needs --var flag=<name>",
+    )
+  })
+
+  it("refuses an unknown flag, and a missing registry", () => {
+    asFile(ONE_LINE)
+    expect(() => requireFlag("cleanup", "reg.ts", "nope", true)).toThrow(
+      'gtd: cleanup: no flag "nope" in reg.ts',
+    )
+    asFile(undefined)
+    expect(() => requireFlag("rollout", "reg.ts", "alpha", false)).toThrow(
+      'gtd: rollout: no flag "alpha" in reg.ts',
+    )
+  })
+
+  it("refuses a non-release flag", () => {
+    asFile(ONE_LINE)
+    expect(() => requireFlag("rollout", "reg.ts", "gamma", false)).toThrow(
+      'gtd: rollout: flag "gamma" is ops, not release',
+    )
+  })
+
+  it("refuses the wrong default", () => {
+    asFile(ONE_LINE)
+    expect(() => requireFlag("rollout", "reg.ts", "beta", false)).toThrow(
+      'gtd: rollout: flag "beta" is already default-on',
+    )
+    expect(() => requireFlag("cleanup", "reg.ts", "alpha", true)).toThrow(
+      'gtd: cleanup: flag "alpha" is not default-on — roll it out first',
+    )
+  })
+})
+
+describe("flagReferences", () => {
+  it("reports path:line for the flag's env var in shipped sources", () => {
+    const files = [
+      { path: "src/a.ts", text: "x\nconst on = env.GTD_FLAG_ALPHA\n" },
+      { path: "src/web/b.tsx", text: "GTD_FLAG_ALPHA\n\nGTD_FLAG_ALPHA" },
+      { path: "src/c.ts", text: "nothing\n" },
+    ]
+    expect(flagReferences(files, "alpha")).toEqual([
+      "src/a.ts:2",
+      "src/web/b.tsx:1",
+      "src/web/b.tsx:3",
+    ])
+  })
+
+  it("ignores test, fixture and stories files and longer names", () => {
+    const text = "GTD_FLAG_ALPHA\n"
+    const files = [
+      { path: "src/a.test.ts", text },
+      { path: "src/a.fixture.ts", text },
+      { path: "src/a.stories.tsx", text },
+      { path: "src/b.ts", text: "GTD_FLAG_ALPHA_X\nXGTD_FLAG_ALPHA\n" },
+    ]
+    expect(flagReferences(files, "alpha")).toEqual([])
+  })
+
+  it("matches regex metacharacters in the name literally", () => {
+    const files = [
+      { path: "src/a.ts", text: "GTD_FLAG_AXB\nGTD_FLAG_A.B\n" },
+      { path: "src/b.ts", text: "GTD_FLAG_AAB\nGTD_FLAG_A+B\n" },
+    ]
+    expect(flagReferences(files, "a.b")).toEqual(["src/a.ts:2"])
+    expect(flagReferences(files, "a+b")).toEqual(["src/b.ts:2"])
+    expect(() => flagReferences(files, "a(b")).not.toThrow()
+    expect(flagReferences(files, "a(b")).toEqual([])
+  })
+})

package/src/workflows/shared/registry.ts

@@ -0,0 +1,158 @@
+import { read, refuse } from "../../flows/index.js"
+
+// The registry is read as TEXT: workflows may not import `src/flags/`, and this
+// also lets a repository point at its own registry file.
+
+export interface RegistryEntry {
+  readonly kind: string
+  readonly defaultOn: boolean
+}
+
+// Filler for masked text: a non-word char, so `/*x*/kind` still has a `\b` before `kind`.
+const FILL = "\u0001"
+
+// Same length as `text`, with string contents and comments filled with FILL, so
+// a hit inside either (a JSDoc example, `owner: "defaultOn: true"`) is rejected.
+const commentLength = (rest: string): number => {
+  const end = rest.startsWith("//") ? rest.indexOf("\n") : rest.indexOf("*/") + 2
+  return end <= 0 ? rest.length : end
+}
+
+// Index of the closing quote of the string opened at `i` (or text end).
+const stringEnd = (text: string, i: number, quote: string): number => {
+  let j = i + 1
+  while (j < text.length && text[j] !== quote) j += text[j] === "\\" ? 2 : 1
+  return Math.min(j, text.length)
+}
+
+const mask = (text: string): string => {
+  let out = ""
+  let i = 0
+  while (i < text.length) {
+    const c = text[i] as string
+    const rest = text.slice(i)
+    if (rest.startsWith("//") || rest.startsWith("/*")) {
+      const len = commentLength(rest)
+      out += FILL.repeat(len)
+      i += len
+    } else if (c === '"' || c === "'" || c === "`") {
+      const j = stringEnd(text, i, c)
+      out += c + FILL.repeat(j - i - 1) + (j < text.length ? c : "")
+      i = j + 1
+    } else {
+      out += c
+      i += 1
+    }
+  }
+  return out
+}
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+// Entries are flat object literals, so the nearest braces around the name delimit one.
+const entrySpan = (text: string, name: string) => {
+  const quoted = escapeRegExp(name)
+  const re = new RegExp(`\\bname\\s*:\\s*(["'\`])${quoted}\\1`, "g")
+  const masked = mask(text)
+  for (const hit of text.matchAll(re)) {
+    if (masked[hit.index] === FILL) continue
+    const start = masked.lastIndexOf("{", hit.index)
+    const close = masked.indexOf("}", hit.index)
+    return start < 0 || close < 0 ? undefined : { start, end: close + 1 }
+  }
+  return undefined
+}
+
+const DEFAULT_ON = /\bdefaultOn\s*:\s*(true|false)\s*,?/
+
+// `defaultOn` as a property of `body`, never one inside a string or comment.
+const defaultOnHit = (body: string) => DEFAULT_ON.exec(mask(body))
+
+const defaultOnValue = (body: string): string | undefined => defaultOnHit(body)?.[1]
+
+const KIND = /\bkind\s*:\s*["'`]/
+
+export const registryEntry = (text: string, name: string): RegistryEntry | undefined => {
+  const span = entrySpan(text, name)
+  if (span === undefined) return undefined
+  const body = text.slice(span.start, span.end)
+  const hit = KIND.exec(mask(body))
+  const kind = hit === null ? null : /^(\w+)["'`]/.exec(body.slice(hit.index + hit[0].length))
+  return {
+    kind: kind?.[1] ?? "",
+    defaultOn: defaultOnValue(body) === "true",
+  }
+}
+
+// Drops the `defaultOn` property, then whitespace and trailing commas outside strings.
+const canonical = (body: string): string => {
+  const hit = defaultOnHit(body)
+  const kept =
+    hit === null ? body : body.slice(0, hit.index) + body.slice(hit.index + hit[0].length)
+  const masked = mask(kept)
+  // UTF-16 units, to match `masked` indexing; code points would drift after a surrogate pair
+  return kept
+    .split("")
+    .filter(
+      (c, i) =>
+        masked[i] === FILL || !(/\s/.test(c) || (c === "," && /^\s*}/.test(masked.slice(i + 1)))),
+    )
+    .join("")
+}
+
+/**
+ * [] when `after` differs from `before` only by the named entry's `defaultOn`
+ * going absent/false → true (whitespace and trailing commas inside that entry
+ * ignored, so oxfmt re-wrapping it passes); else one line per fault.
+ */
+export const flipProblems = (before: string, after: string, name: string): readonly string[] => {
+  const was = entrySpan(before, name)
+  const now = entrySpan(after, name)
+  if (was === undefined) return [`no entry "${name}" before the turn`]
+  if (now === undefined) return [`entry "${name}" is gone`]
+  const faults: string[] = []
+  if (before.slice(0, was.start) !== after.slice(0, now.start)) {
+    faults.push("text before the entry changed")
+  }
+  if (before.slice(was.end) !== after.slice(now.end)) faults.push("text after the entry changed")
+  const oldBody = before.slice(was.start, was.end)
+  const newBody = after.slice(now.start, now.end)
+  if (canonical(oldBody) !== canonical(newBody))
+    faults.push(`entry "${name}" changed beyond defaultOn`)
+  if (defaultOnValue(newBody) !== "true") faults.push(`"${name}" is not set to defaultOn: true`)
+  return faults
+}
+
+/** `path:line` for every `GTD_FLAG_<NAME>` in shipped sources; re-states scripts/lint-flags.ts' rule by hand. */
+export const flagReferences = (
+  files: readonly { readonly path: string; readonly text: string }[],
+  name: string,
+): readonly string[] => {
+  const pattern = new RegExp(`\\bGTD_FLAG_${escapeRegExp(name.toUpperCase())}\\b`)
+  return files
+    .filter(({ path }) => !/\.(test|fixture|stories)\.tsx?$/.test(path))
+    .flatMap(({ path, text }) =>
+      text.split("\n").flatMap((line, i) => (pattern.test(line) ? [`${path}:${i + 1}`] : [])),
+    )
+}
+
+export const requireFlag = (
+  workflow: "rollout" | "cleanup",
+  registryPath: string,
+  name: string,
+  defaultOn: boolean,
+): void => {
+  if (name === "") return refuse(`gtd: ${workflow} needs --var flag=<name>`)
+  const entry = registryEntry(read(registryPath) ?? "", name)
+  if (entry === undefined) return refuse(`gtd: ${workflow}: no flag "${name}" in ${registryPath}`)
+  if (entry.kind !== "release") {
+    return refuse(`gtd: ${workflow}: flag "${name}" is ${entry.kind}, not release`)
+  }
+  if (entry.defaultOn !== defaultOn) {
+    return refuse(
+      defaultOn
+        ? `gtd: ${workflow}: flag "${name}" is not default-on — roll it out first`
+        : `gtd: ${workflow}: flag "${name}" is already default-on`,
+    )
+  }
+}

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

@@ -5,6 +5,7 @@ import {
   type CodeThreadInfo,
   type StepRequest,
 } from "../../flows/index.js"
+import type { Guard } from "./health.js"
 import { handOffReview, REVIEW_ORIG } from "./tail.js"
 import { fixtureContext } from "./text.fixture.js"
 
@@ -30,7 +31,11 @@ const reviewDoc = (note: string): string =>
  */
 const handOff = async (
   after: string | "deleted" | "unwritten",
-  extra: { paths?: readonly string[]; codeThreads?: readonly CodeThreadInfo[] } = {},
+  extra: {
+    paths?: readonly string[]
+    codeThreads?: readonly CodeThreadInfo[]
+    guard?: Guard
+  } = {},
 ) => {
   const log: string[] = []
   const scripts = new Map<string, string>()
@@ -87,7 +92,7 @@ const handOff = async (
       },
     ),
   )
-  const refusal = await handOffReview("base", { rounds: 0 }).then(
+  const refusal = await handOffReview("base", { rounds: 0 }, extra.guard).then(
     () => undefined,
     (e: unknown) => (e as Error).message,
   )
@@ -162,4 +167,33 @@ describe("the hand-off review", () => {
     expect(run.refusal).toMatch(/was deleted — restore it, or leave a note to hand to fix/)
     expect(run.log).toEqual(["review.reviewing", "review.await-review"])
   })
+
+  describe("guard", () => {
+    it("runs after the reviewing turn and never after the human's await-review landing", async () => {
+      const seen: string[] = []
+      const run = await handOff(reviewDoc("new add function"), {
+        guard: () => seen.push("guard"),
+      })
+      expect(run.log).toEqual(["review.reviewing", "review.await-review", "review.closing"])
+      expect(seen).toEqual(["guard"])
+    })
+
+    it("a refusal after reviewing stops the round before the human gate", async () => {
+      const run = await handOff(reviewDoc("new add function"), {
+        guard: () => {
+          throw new Error("guarded: nope")
+        },
+      })
+      expect(run.refusal).toBe("guarded: nope")
+      expect(run.log).toEqual(["review.reviewing"])
+    })
+
+    it("does not run after review-missing", async () => {
+      let calls = 0
+      const run = await handOff("unwritten", { guard: () => void calls++ })
+      expect(run.log).toContain("review.review-missing")
+      // the fixture aborts the second reviewing turn: only the first was guarded
+      expect(calls).toBe(1)
+    })
+  })
 })

package/src/workflows/shared/tail.ts

@@ -1,6 +1,13 @@
 import { read, refuse, removeScript, run, scope, showScript, vars } from "../../flows/index.js"
 import * as kit from "../../workflow-kit/index.js"
-import { escalation, FIX_CAP, healthy, type EscalationCount } from "./health.js"
+import {
+  escalation,
+  FIX_CAP,
+  guarded,
+  healthy,
+  type EscalationCount,
+  type Guard,
+} from "./health.js"
 import {
   awaitReview,
   fixCheck,
@@ -22,16 +29,16 @@ export const REVIEW_ORIG = ".gtd/REVIEW.orig.md"
  * finding to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
  * has any.
  */
-export const qualityLap = (): Promise<"clean" | "findings"> =>
-  kit.qualityLap(kit.lensesOf(vars.qualityReviews ?? ""), reviewQuality, QUALITY)
+export const qualityLap = (guard?: Guard): Promise<"clean" | "findings"> =>
+  kit.qualityLap(kit.lensesOf(vars.qualityReviews ?? ""), guarded(reviewQuality, guard), QUALITY)
 
 /** Resolves `true` once `.gtd/QUALITY.md` is resolved, `false` when the fix cap escalated instead. */
-export const fixQualityFindings = (escalations: EscalationCount): Promise<boolean> =>
+export const fixQualityFindings = (escalations: EscalationCount, guard?: Guard): Promise<boolean> =>
   kit.fixFindings({
-    fix: fixQuality,
+    fix: guarded(fixQuality, guard),
     findings: QUALITY,
     cap: FIX_CAP,
-    escalate: () => escalation(escalations),
+    escalate: () => escalation(escalations, guard),
   })
 
 /** `.gtd/REVIEW.md` removed at the end of a round at commit `round`. */
@@ -59,21 +66,22 @@ export const tail = <T>(
   fixFirst: boolean,
   finish: (escalations: EscalationCount) => Promise<T>,
   green = false,
+  guard?: Guard,
 ): Promise<T> =>
   scope("build", async () => {
     const escalations: EscalationCount = { rounds: 0 }
     const fix = fixCheck
     const repair = async () => {
-      await fix()
-      await healthy(fix, { fixesSoFar: 1, escalations })
+      await guarded(fix, guard)()
+      await healthy(fix, { fixesSoFar: 1, escalations, guard })
     }
     // fixFirst's own fix + healthy below already is the full run.
     if (fixFirst) await repair()
-    else if (!green) await healthy(fix, { escalations })
+    else if (!green) await healthy(fix, { escalations, guard })
     // The lap runs once a tail: after its findings are fixed, review follows.
-    if ((await qualityLap()) === "findings") {
-      if (await fixQualityFindings(escalations)) {
-        await healthy(fix, { escalations })
+    if ((await qualityLap(guard)) === "findings") {
+      if (await fixQualityFindings(escalations, guard)) {
+        await healthy(fix, { escalations, guard })
       } else await repair()
     }
     return finish(escalations)
@@ -84,12 +92,16 @@ export const tail = <T>(
  * `.gtd/REVIEW.md`; a note leaves it, with the reviewer's own version as
  * `REVIEW_ORIG`, for the next `fix` to read — never a re-plan.
  */
-export const handOffReview = (base: string, escalations: EscalationCount): Promise<void> =>
+export const handOffReview = (
+  base: string,
+  escalations: EscalationCount,
+  guard?: Guard,
+): Promise<void> =>
   kit.reviewToHandOff(base, {
     file: REVIEW,
-    reviewing,
-    fixRisks,
-    keepGreen: () => healthy(fixCheck, { escalations }),
+    reviewing: guarded(reviewing, guard),
+    fixRisks: guarded(fixRisks, guard),
+    keepGreen: () => healthy(fixCheck, { escalations, guard }),
     awaitReview: (b) => awaitReview(b, t.handOffAwaitReviewMessage(b)),
     reviewMissing,
     close: closeReview,
@@ -107,5 +119,5 @@ export const handOffReview = (base: string, escalations: EscalationCount): Promi
   })
 
 /** The tail the review and fix workflows run: ends at the hand-off review since `base`. */
-export const handOffTail = (fixFirst: boolean, base: string): Promise<void> =>
-  tail(fixFirst, (escalations) => handOffReview(base, escalations))
+export const handOffTail = (fixFirst: boolean, base: string, guard?: Guard): Promise<void> =>
+  tail(fixFirst, (escalations) => handOffReview(base, escalations, guard), false, guard)