@pmelab/gtd 27.9.0 → 28.0.0

package/src/workflow/load.ts

@@ -548,31 +548,43 @@ const doorsFrom = (exports: Record<string, unknown>): ReadonlyMap<string, Door>
 
 /**
  * Each exported workflow's own doors, onto the name it is exported under. The
- * `doors` export adds to them and settles a name two workflows both declare.
+ * `doors` export adds to them and declares a name several workflows clash on.
  */
 const derivedDoors = (
   catalogue: ReadonlyMap<string, LoadedWorkflow>,
   declared: ReadonlyMap<string, Door>,
-): ReadonlyMap<string, Door> => {
-  const doors = new Map<string, Door>()
+): {
+  readonly doors: ReadonlyMap<string, Door>
+  readonly clashes: ReadonlyMap<string, readonly string[]>
+} => {
+  const builders = new Map<string, Door[]>()
   for (const [workflow, loaded] of catalogue) {
     for (const [name, spec] of Object.entries(loaded.doors ?? {})) {
       const door: Door = { ...spec, workflow }
       const problem = doorProblem(name, door)
       if (problem !== undefined)
         throw new Error(`workflow "${workflow}" builds door "${name}", which ${problem}`)
-      const other = doors.get(name)
-      if (other !== undefined && !declared.has(name)) {
-        throw new Error(
-          `door "${name}" is built by workflows "${other.workflow}" and "${workflow}" — declare it in the "doors" export to choose one (a declared door replaces the derived one, so restate its args and vars)`,
-        )
-      }
-      doors.set(name, door)
+      builders.set(name, [...(builders.get(name) ?? []), door])
     }
   }
-  return new Map([...doors, ...declared])
+  const doors = new Map<string, Door>()
+  const clashes = new Map<string, readonly string[]>()
+  for (const [name, built] of builders) {
+    const owner = ownerOf(name, built)
+    if (owner !== undefined) doors.set(name, owner)
+    else if (!declared.has(name))
+      clashes.set(
+        name,
+        built.map((door) => door.workflow),
+      )
+  }
+  return { doors: new Map([...doors, ...declared]), clashes }
 }
 
+/** The export named after the door owns it, else the sole builder; a clash of several builds no door. */
+const ownerOf = (name: string, built: readonly Door[]): Door | undefined =>
+  built.find((door) => door.workflow === name) ?? (built.length === 1 ? built[0] : undefined)
+
 /** Sort the doors and check each names a startable workflow. */
 const checkDoors = (
   declared: ReadonlyMap<string, Door>,
@@ -628,16 +640,28 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
     }),
   )
   const defaultWorkflow = built.get(value)
+  const derived =
+    rejections.length > 0
+      ? { doors: new Map<string, Door>(), clashes: new Map<string, readonly string[]>() }
+      : derivedDoors(catalogue, doorsFrom(exports))
   return {
     file,
     catalogue,
-    doors:
-      rejections.length > 0
-        ? new Map()
-        : checkDoors(derivedDoors(catalogue, doorsFrom(exports)), catalogue),
+    doors: checkDoors(derived.doors, catalogue),
     default: defaultWorkflow && { ...defaultWorkflow, name: defaultName },
     config: compileConfig(exports["config"], module.filepath),
-    diagnostics: nameRejections(rejections),
+    diagnostics: [
+      ...nameRejections(rejections),
+      ...[...derived.clashes].map(([name, builders]): Diagnostic => {
+        const names = [...builders].sort().map((b) => JSON.stringify(b))
+        return {
+          severity: "warning",
+          message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — declare it in the "doors" export`,
+          path: ["doors", name],
+          origin: file.origin,
+        }
+      }),
+    ],
   }
 }
 

package/src/workflows/cleanup/cleanup.feature

@@ -75,6 +75,27 @@ Feature: cleanup removes a default-on release flag and keeps its flag-on path
     And the process is driven
     Then the process rests at "build.review.reviewing"
 
+  @inmem
+  Scenario: gtd door cleanup starts the cleanup of its flag argument and reaches the review
+    Given step "cleanup.removing" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+      ] as const
+      """
+    And step "cleanup.removing" writes "src/calc.ts" with:
+      """
+      export const on = true
+      """
+    And step "build.health.check" changes nothing
+    When gtd opens door "cleanup" with "live"
+    And the process is driven
+    Then the process rests at "build.review.reviewing"
+
+  @inmem
+  Scenario: gtd door cleanup with no argument is refused naming the flag
+    Then opening door "cleanup" is refused with "usage: gtd door cleanup <flag>"
+
   @inmem
   Scenario: a fix after a red suite that restores the registry entry is refused
     Given step "cleanup.removing" writes "src/flags/index.ts" with:

package/src/workflows/cleanup/cleanup.ts

@@ -49,4 +49,4 @@ export const cleanupFlow = async (): Promise<void> => {
   await handOffTail(false, start(), guard)
 }
 
-export const cleanup = flagShipped(cleanupFlow)
+export const cleanup = flagShipped(cleanupFlow, "cleanup")

package/src/workflows/index.ts

@@ -35,6 +35,7 @@ export default feature
 
 /**
  * @deprecated Empty: each shipped workflow builds its own doors, so a config
- * gets `fix` and `review [base]` by exporting `fix` and `review`.
+ * gets `fix` and `review [base]` by exporting `fix` and `review`, and
+ * `rollout <flag>` and `cleanup <flag>` by exporting `rollout` and `cleanup`.
  */
 export const doors: Doors = {}

package/src/workflows/rollout/rollout.feature

@@ -47,11 +47,16 @@ Feature: rollout turns one release flag default-on and touches nothing else
       ] as const
       """
     And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
     When gtd starts workflow "rollout" with "--var flag=alpha"
     And the process is driven
     Then the process rests at "idle"
     And "src/flags/index.ts" contains "kind: \"release\", defaultOn: true },"
-    And the last commit subject is "gtd(check): rollout.suite.check → idle"
+    And the commit subjects end with:
+      """
+      gtd(check): rollout.suite.check → rollout.mentions
+      gtd(check): rollout.mentions → idle
+      """
 
   Scenario: a turn also changing a source file is refused naming that path
     Given step "rollout.flipping" writes "src/flags/index.ts" with:
@@ -98,11 +103,34 @@ Feature: rollout turns one release flag default-on and touches nothing else
       ] as const
       """
     And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
     When gtd starts workflow "elsewhere" with "--var flag=gamma"
     And the process is driven
     Then the process rests at "idle"
     And "config/flags.ts" contains "defaultOn: true"
 
+  @inmem
+  Scenario: gtd door rollout starts the rollout of its flag argument
+    Given step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    When gtd opens door "rollout" with "alpha"
+    And the process is driven
+    Then the process rests at "idle"
+    And "src/flags/index.ts" contains "kind: \"release\", defaultOn: true },"
+
+  @inmem
+  Scenario: gtd door rollout with no argument is refused naming the flag
+    Then opening door "rollout" is refused with "usage: gtd door rollout <flag>"
+
   Scenario: a missing flag var is refused before any turn
     Then starting workflow "rollout" with "" is refused with "gtd: rollout needs --var flag=<name>"
 
@@ -209,6 +237,258 @@ Feature: rollout turns one release flag default-on and touches nothing else
       fixed by hand
       """
     And step "rollout.suite.check" from now on changes nothing
+    And step "rollout.mentions" runs its script
     When the process is driven
     Then the process rests at "idle"
-    And the last commit subject is "gtd(check): rollout.suite.check → idle"
+    And the commit subjects end with:
+      """
+      gtd(check): rollout.suite.check → rollout.mentions
+      gtd(check): rollout.mentions → idle
+      """
+
+  @inmem
+  Scenario: a stray file written at the mentions step is refused naming that path
+    Given step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    And step "rollout.mentions" writes "src/stray.ts" with:
+      """
+      export const x = 1
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    Then driving the process is refused with "rollout-only: src/stray.ts changed"
+
+  @inmem
+  Scenario: a second registry entry edited at the mentions step is refused
+    Given step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    And step "rollout.mentions" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "z", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    Then driving the process is refused with "rollout-only: other edits in src/flags/index.ts"
+
+  @inmem
+  Scenario: every line naming the flag is listed, no file is edited, and gtd summary repeats the list
+    Given a file "README.md" with:
+      """
+      # calc
+
+      The alpha formatter is on under GTD_FLAG_ALPHA=1.
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const help = "pass --flag_alpha to enable the alpha formatter"
+      """
+    And the working tree is committed as "docs: mention the flag"
+    And step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/FEEDBACK.md" does not exist
+    And "README.md" contains "The alpha formatter is on under GTD_FLAG_ALPHA=1."
+    And "src/calc.ts" contains "pass --flag_alpha to enable the alpha formatter"
+    And the output of gtd "summary" contains "`README.md:3`"
+    And the output of gtd "summary" contains "src/calc.ts:1"
+
+  @inmem
+  Scenario: gtd summary's grep hint excludes a factory flagRegistry
+    Given a file "config/flags.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "g", expiry: "2027-05-01", kind: "release" },
+      ] as const
+      """
+    And a file "NOTES.md" with:
+      """
+      alpha 1
+      alpha 2
+      alpha 3
+      alpha 4
+      alpha 5
+      alpha 6
+      alpha 7
+      alpha 8
+      alpha 9
+      alpha 10
+      alpha 11
+      alpha 12
+      alpha 13
+      alpha 14
+      alpha 15
+      alpha 16
+      alpha 17
+      alpha 18
+      alpha 19
+      alpha 20
+      alpha 21
+      alpha 22
+      alpha 23
+      alpha 24
+      alpha 25
+      alpha 26
+      alpha 27
+      alpha 28
+      alpha 29
+      alpha 30
+      alpha 31
+      alpha 32
+      alpha 33
+      alpha 34
+      alpha 35
+      alpha 36
+      alpha 37
+      alpha 38
+      alpha 39
+      alpha 40
+      alpha 41
+      alpha 42
+      alpha 43
+      alpha 44
+      alpha 45
+      alpha 46
+      alpha 47
+      alpha 48
+      alpha 49
+      alpha 50
+      alpha 51
+      alpha 52
+      alpha 53
+      alpha 54
+      alpha 55
+      """
+    And the working tree is committed as "docs: mention the flag"
+    And step "rollout.flipping" writes "config/flags.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "g", expiry: "2027-05-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    When gtd starts workflow "elsewhere" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "idle"
+    And the output of gtd "summary" contains "':(top,exclude,literal)config/flags.ts'"
+
+  @inmem
+  Scenario: a flag named nowhere outside the registry says so in gtd summary
+    Given step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "idle"
+    And ".gtd/FEEDBACK.md" does not exist
+    And the output of gtd "summary" contains "no line outside the registry names it"
+
+  @inmem
+  Scenario: the closing commit marks the total and each listed line
+    Given a file "README.md" with:
+      """
+      # calc
+
+      The alpha formatter is on under GTD_FLAG_ALPHA=1.
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const help = "pass --flag_alpha to enable the alpha formatter"
+      """
+    And the working tree is committed as "docs: mention the flag"
+    And step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the last commit subject is "gtd(check): rollout.mentions → idle"
+    And the last commit body contains "Gtd-Mark: flag-mentions=2"
+    And the last commit body contains "Gtd-Mark: flag-mention=README.md:3"
+    And the last commit body contains "Gtd-Mark: flag-mention=src/calc.ts:1"
+
+  @inmem
+  Scenario: a finished rollout leaves no state file for the next feature start
+    Given a file "README.md" with:
+      """
+      # calc
+
+      The alpha formatter is on under GTD_FLAG_ALPHA=1.
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const help = "pass --flag_alpha to enable the alpha formatter"
+      """
+    And the working tree is committed as "docs: mention the flag"
+    And step "rollout.flipping" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "b", expiry: "2027-02-01", kind: "release" },
+        { name: "ops1", owner: "c", expiry: "2027-03-01", kind: "ops" },
+        { name: "live", owner: "d", expiry: "2027-04-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    And step "rollout.mentions" runs its script
+    And step "unwind" changes nothing
+    And step "start-gate.check" changes nothing
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "idle"
+    Given a file "TODO.md" with:
+      """
+      # Add subtract
+
+      subtract(a, b) returns the difference.
+      """
+    When the process is driven
+    Then the process rests at "design.triage"
+    And ".gtd/FEEDBACK.md" does not exist

package/src/workflows/rollout/rollout.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { CONFIG_SCAFFOLD } from "../../install/index.js"
-import { testRepo } from "../../testkit/index.js"
+import { runsItsScript, testRepo } from "../../testkit/index.js"
 
 const CONFIG = `${CONFIG_SCAFFOLD}export { rollout } from "@pmelab/gtd/workflows"\n`
 
@@ -30,9 +30,13 @@ describe("the rollout workflow", () => {
         r.write("src/flags/index.ts", FLIPPED)
       },
       "rollout.suite.check": () => undefined,
+      "rollout.mentions": runsItsScript,
     })
     expect(rest.state).toBe("idle")
-    expect(repo.subjects().at(-1)).toBe("gtd(check): rollout.suite.check → idle")
+    expect(repo.subjects().slice(-2)).toEqual([
+      "gtd(check): rollout.suite.check → rollout.mentions",
+      "gtd(check): rollout.mentions → idle",
+    ])
   })
 
   it("lands a flip when the tree was already dirty at the start", async () => {
@@ -42,6 +46,7 @@ describe("the rollout workflow", () => {
     const rest = await repo.drive({
       "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
       "rollout.suite.check": () => undefined,
+      "rollout.mentions": runsItsScript,
     })
     expect(rest.state).toBe("idle")
   })
@@ -160,8 +165,97 @@ describe("the rollout workflow", () => {
             ),
           ),
         "rollout.suite.check": () => undefined,
+        "rollout.mentions": runsItsScript,
       })
       expect(rest.state).toBe("idle")
     })
   })
 })
+
+describe("rollout.mentions", () => {
+  const flip = {
+    "rollout.flipping": (_: unknown, r: { write: (p: string, c: string) => void }) =>
+      r.write("src/flags/index.ts", FLIPPED),
+  }
+  const finish = async (
+    files: Record<string, string>,
+    mentions: typeof runsItsScript = runsItsScript,
+  ) => {
+    const repo = testRepo({
+      workflow: CONFIG,
+      files: { "src/flags/index.ts": REGISTRY, "src/a.ts": "a\n", ...files },
+    })
+    await repo.start("rollout", "--var", "flag=alpha")
+    const rest = await repo.drive({
+      ...flip,
+      "rollout.suite.check": () => undefined,
+      "rollout.mentions": mentions,
+    })
+    expect(rest.state).toBe("idle")
+    const marks = (repo.messages().at(-1) ?? "")
+      .split("\n")
+      .filter((l) => l.startsWith("Gtd-Mark: "))
+      .map((l) => l.slice("Gtd-Mark: ".length))
+    return { repo, marks }
+  }
+
+  it("lists mentions outside the registry and under no .gtd/ path", async () => {
+    const { marks } = await finish({
+      "README.md": "intro\non under GTD_FLAG_ALPHA=1\n",
+      "src/help.ts": 'export const h = "alpha help"\n',
+      ".gtd/NOTES.md": "alpha\n",
+    })
+    expect(marks).toEqual([
+      "flag-mentions=2",
+      "flag-mention=README.md:2",
+      "flag-mention=src/help.ts:1",
+    ])
+  })
+
+  it("the mentions script removes a feedback file present at the step; marks list the tree", async () => {
+    const { repo, marks } = await finish({ "README.md": "alpha\n" }, (beat, r) => {
+      r.write(".gtd/FEEDBACK.md", "alpha\n")
+      runsItsScript(beat, r)
+    })
+    expect(repo.read(".gtd/FEEDBACK.md")).toBeUndefined()
+    expect(marks).toEqual(["flag-mentions=1", "flag-mention=README.md:1"])
+  })
+
+  it("refuses a stray file written by the mentions script", async () => {
+    await expect(
+      finish({}, (beat, r) => {
+        runsItsScript(beat, r)
+        r.write("src/stray.ts", "x\n")
+      }),
+    ).rejects.toThrow("gtd land: rollout-only: src/stray.ts changed")
+  })
+
+  it("refuses a registry edit beyond the flip made by the mentions script", async () => {
+    await expect(
+      finish({}, (beat, r) => {
+        runsItsScript(beat, r)
+        r.write("src/flags/index.ts", FLIPPED.replace('owner: "b"', 'owner: "z"'))
+      }),
+    ).rejects.toThrow("rollout-only: other edits in src/flags/index.ts")
+  })
+
+  it("marks 0 when nothing names the flag", async () => {
+    const { marks } = await finish({})
+    expect(marks).toEqual(["flag-mentions=0"])
+  })
+
+  it("marks the total for 60 mentions but only the first 50 lines", async () => {
+    const text = Array.from({ length: 60 }, (_, i) => `alpha ${i}`).join("\n")
+    const { marks } = await finish({ "docs/many.md": `${text}\n` })
+    expect(marks[0]).toBe("flag-mentions=60")
+    expect(marks.filter((m) => m.startsWith("flag-mention="))).toHaveLength(50)
+  })
+
+  it("counts a path the mark grammar rejects without marking it, and never throws", async () => {
+    const { marks } = await finish({
+      "docs/bad\u0001name.md": "alpha\n",
+      "README.md": "alpha\n",
+    })
+    expect(marks).toEqual(["flag-mentions=2", "flag-mention=README.md:1"])
+  })
+})

package/src/workflows/rollout/rollout.ts

@@ -1,7 +1,19 @@
-import { agent, changesSince, head, read, refuse, scope, vars } from "../../flows/index.js"
+import {
+  agent,
+  changesSince,
+  glob,
+  head,
+  mark,
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  vars,
+} from "../../flows/index.js"
 import { gate } from "../shared/health.js"
 import { flagShipped } from "../shared/options.js"
-import { flipProblems, requireFlag } from "../shared/registry.js"
+import { flagMentions, flipProblems, requireFlag } from "../shared/registry.js"
 import { coder, FEEDBACK } from "../shared/steps.js"
 
 const flippingPrompt = (name: string, registry: string): string =>
@@ -10,6 +22,31 @@ const flippingPrompt = (name: string, registry: string): string =>
 const suiteBlockedMessage = (): string =>
   "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land."
 
+// Marks past this many are dropped; the summary points at grep for the rest.
+const MARKED_MENTIONS = 50
+
+// Lists, never edits: the human fixes the now-stale prose, or cleanup does. The
+// list rides in marks only: a state file left at idle would be published by
+// ship and read as a failed unwind by the next process.
+const listMentions = async (registry: string, name: string, guard: () => void): Promise<void> => {
+  await run("mentions", removeScript([FEEDBACK]), { label: "Listing flag mentions" })
+  guard()
+  const files = glob("**")
+    .filter((path) => path !== registry && path !== ".gtd" && !path.startsWith(".gtd/"))
+    .sort()
+    .map((path) => ({ path, text: read(path) ?? "" }))
+  const mentions = flagMentions(files, name)
+  mark("flag-mentions", String(mentions.length))
+  for (const m of mentions.slice(0, MARKED_MENTIONS)) {
+    // A path the mark grammar rejects stays counted above, just unlisted here.
+    try {
+      mark("flag-mention", `${m.path}:${m.line}`)
+    } catch {
+      continue
+    }
+  }
+}
+
 // No review gate — a one-field change needs no review lap.
 export const rolloutFlow = async (): Promise<void> => {
   const registry = vars.flagRegistry ?? ""
@@ -38,7 +75,8 @@ export const rolloutFlow = async (): Promise<void> => {
     })
     guard()
     await gate("suite", suiteBlockedMessage(), guard)
+    await listMentions(registry, name, guard)
   })
 }
 
-export const rollout = flagShipped(rolloutFlow)
+export const rollout = flagShipped(rolloutFlow, "rollout")