@pmelab/gtd 27.8.0 → 28.0.0

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")

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { configure } from "../../flows/index.js"
+import { configure, type WorkflowDoors } from "../../flows/index.js"
 import * as workflows from "../index.js"
 import * as options from "./options.js"
 
@@ -85,7 +85,7 @@ describe("the shipped workflow factories", () => {
   })
 
   describe("flagShipped", () => {
-    const factory = flagShipped(async () => {})
+    const factory = flagShipped(async () => {}, "rollout")
 
     it("declare flag and flagRegistry as process settings, so --var flag= is accepted", () => {
       expect(configure(factory)).toMatchObject({
@@ -97,6 +97,29 @@ describe("the shipped workflow factories", () => {
       })
     })
 
+    it.each(["rollout", "cleanup"] as const)(
+      "%s declares one door named after it, with one required flag arg",
+      (name) => {
+        const result = configure(workflows[name]())
+        expect(result).toMatchObject({
+          ok: true,
+          build: { doors: { [name]: { args: [{ name: "flag" }] } } },
+        })
+        const build = (result as { build?: { doors?: WorkflowDoors } }).build
+        expect(Object.keys(build?.doors ?? {})).toEqual([name])
+        expect(build?.doors?.[name]?.vars?.({ flag: "x" })).toEqual({ flag: "x" })
+      },
+    )
+
+    it.each(["rollout", "cleanup"] as const)("%s builds one door of that name", (name) => {
+      const result = configure(flagShipped(async () => {}, name))
+      const doors = (result as { build?: { doors?: WorkflowDoors } }).build?.doors
+      expect(Object.keys(doors ?? {})).toEqual([name])
+      expect(doors?.[name]?.args).toEqual([{ name: "flag" }])
+      expect(doors?.[name]?.vars?.({ flag: "x" })).toEqual({ flag: "x" })
+      expect(doors?.[name]?.vars?.({})).toEqual({ flag: "" })
+    })
+
     it("fail the load on an unknown option", () => {
       // @ts-expect-error — `flag` is a --var, not an option
       const result = configure(factory({ flag: "x" }))

package/src/workflows/shared/options.ts

@@ -6,7 +6,7 @@ import {
   type WorkflowDoors,
   type WorkflowFactory,
 } from "../../flows/index.js"
-import { defaults, envDefaults } from "./vars.js"
+import { defaultFlagRegistry, defaults, envDefaults } from "./vars.js"
 
 const setting = Schema.optionalWith(Schema.String, { exact: true })
 
@@ -55,16 +55,19 @@ export const FlagOptions = Schema.Struct({ ...ShippedOptions.fields, flagRegistr
 
 export type FlagOptions = Schema.Schema.Encoded<typeof FlagOptions>
 
-export const flagShipped = (flow: Flow): WorkflowFactory<FlagOptions> =>
+export const flagShipped = (
+  flow: Flow,
+  name: "rollout" | "cleanup",
+): WorkflowFactory<FlagOptions> =>
   defineWorkflow(
     Schema.standardSchemaV1(FlagOptions, { onExcessProperty: "error", errors: "all" }),
     (options) => {
-      const flagDefaults = { ...defaults, flag: "", flagRegistry: "src/flags/index.ts" }
+      const flagDefaults = { ...defaults, flag: "", flagRegistry: defaultFlagRegistry }
       return {
         flow,
         defaults: over(flagDefaults, options),
         envDefaults: over(envDefaults, options),
-        doors: {},
+        doors: { [name]: { args: [{ name: "flag" }], vars: ({ flag }) => ({ flag: flag ?? "" }) } },
         base: undefined,
       }
     },

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

@@ -1,6 +1,12 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext } from "../../flows/index.js"
-import { flagReferences, flipProblems, registryEntry, requireFlag } from "./registry.js"
+import {
+  flagMentions,
+  flagReferences,
+  flipProblems,
+  registryEntry,
+  requireFlag,
+} from "./registry.js"
 
 const ONE_LINE = `export const FLAGS = [
   { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
@@ -303,3 +309,37 @@ describe("flagReferences", () => {
     expect(flagReferences(files, "a(b")).toEqual([])
   })
 })
+
+describe("flagMentions", () => {
+  it("matches the env var, the flag_ form and the bare name, any case, 1-based", () => {
+    const files = [
+      {
+        path: "README.md",
+        text: "intro\non under GTD_FLAG_ALPHA=1\nflag_alpha helper\nThe Alpha flag\nnone\n",
+      },
+    ]
+    expect(flagMentions(files, "alpha")).toEqual([
+      { path: "README.md", line: 2 },
+      { path: "README.md", line: 3 },
+      { path: "README.md", line: 4 },
+    ])
+  })
+
+  it("never matches inside a longer identifier", () => {
+    const text = "alphabet\nalpha_two\nGTD_FLAG_ALPHA_TWO\nxalpha\nflag_alphabet\n"
+    expect(flagMentions([{ path: "a.md", text }], "alpha")).toEqual([])
+  })
+
+  it("keeps test files, and skips a file holding a NUL byte", () => {
+    const files = [
+      { path: "src/a.test.ts", text: "GTD_FLAG_ALPHA\n" },
+      { path: "bin.dat", text: "alpha\u0000alpha\n" },
+    ]
+    expect(flagMentions(files, "alpha").map((m) => m.path)).toEqual(["src/a.test.ts"])
+  })
+
+  it("matches regex metacharacters in the name literally", () => {
+    const files = [{ path: "a.md", text: "a.b\naxb\n" }]
+    expect(flagMentions(files, "a.b").map((m) => m.line)).toEqual([1])
+  })
+})

package/src/workflows/shared/registry.ts

@@ -47,7 +47,7 @@ const mask = (text: string): string => {
   return out
 }
 
-const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+export 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) => {
@@ -136,6 +136,31 @@ export const flagReferences = (
     )
 }
 
+export interface FlagMention {
+  readonly path: string
+  readonly line: number
+}
+
+/**
+ * Every line naming flag `name` as `GTD_FLAG_<NAME>`, `flag_<name>` or bare
+ * `<name>` — case-insensitive, never inside a longer identifier. Unlike
+ * `flagReferences`, test files count; a file holding a NUL byte is skipped.
+ */
+export const flagMentions = (
+  files: readonly { readonly path: string; readonly text: string }[],
+  name: string,
+): readonly FlagMention[] => {
+  const pattern = new RegExp(
+    `(?<![A-Za-z0-9_])(?:GTD_FLAG_|flag_)?${escapeRegExp(name)}(?![A-Za-z0-9_])`,
+    "i",
+  )
+  return files
+    .filter(({ text }) => !text.includes("\u0000"))
+    .flatMap(({ path, text }) =>
+      text.split("\n").flatMap((line, i) => (pattern.test(line) ? [{ path, line: i + 1 }] : [])),
+    )
+}
+
 export const requireFlag = (
   workflow: "rollout" | "cleanup",
   registryPath: string,

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

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process"
-import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { describe, expect, it } from "vitest"
+import { afterEach, describe, expect, it } from "vitest"
 import {
   buildReviewTriageMessage,
   deferNotesScript,
@@ -261,6 +261,38 @@ describe("buildQualityReviewingPrompt", () => {
   })
 })
 
+// These cases run real git and sh on purpose: they prove the command a person
+// pastes works in real git, which an in-memory twin cannot show. An inherited
+// GIT_DIR would commit into the real repository; the user's git config would
+// change the exact output lines compared.
+const gitEnv = (): NodeJS.ProcessEnv => {
+  const env = { ...process.env }
+  delete env.GIT_DIR
+  delete env.GIT_WORK_TREE
+  delete env.GIT_INDEX_FILE
+  env.GIT_CONFIG_GLOBAL = "/dev/null"
+  env.GIT_CONFIG_NOSYSTEM = "1"
+  return env
+}
+
+const scratchDirs: string[] = []
+afterEach(() => {
+  for (const dir of scratchDirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+const scratchRepo = () => {
+  const dir = mkdtempSync(join(tmpdir(), "gtd-grep-"))
+  scratchDirs.push(dir)
+  const env = gitEnv()
+  const git = (...args: string[]) =>
+    execFileSync(
+      "git",
+      ["-c", "commit.gpgsign=false", "-c", "user.name=t", "-c", "user.email=t@t", ...args],
+      { cwd: dir, env },
+    )
+  return { dir, env, git }
+}
+
 describe("summaryPrompt", () => {
   it("puts the total and every model's cost on a line of its own", () => {
     const prompt = summaryPrompt({
@@ -298,6 +330,224 @@ describe("summaryPrompt", () => {
     expect(summaryPrompt(base)).not.toContain("Production signals")
   })
 
+  it("adds the one no-mentions line, naming the flag, for flag-mentions=0", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha" },
+      marks: [{ name: "flag-mentions", value: "0" }],
+    })
+    expect(prompt).toContain("Flag `alpha`: no line outside the registry names it.")
+  })
+
+  it("keeps a backtick flag name inside one span in the heading and the no-mentions line", () => {
+    const zero = summaryPrompt({
+      ...base,
+      vars: { flag: "a`b" },
+      marks: [{ name: "flag-mentions", value: "0" }],
+    })
+    expect(zero).toContain("Flag `` a`b ``: no line outside the registry names it.")
+    const some = summaryPrompt({
+      ...base,
+      vars: { flag: "a``b" },
+      marks: [
+        { name: "flag-mentions", value: "1" },
+        { name: "flag-mention", value: "README.md:1" },
+      ],
+    })
+    expect(some).toContain("still naming flag ``` a``b ``` —")
+  })
+
+  const listedMentions = Array.from({ length: 50 }, (_, i) => ({
+    name: "flag-mention",
+    value: `README.md:${i + 1}`,
+  }))
+
+  it("lists the flag-mention values as data, then says how many more there are", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    expect(prompt).toContain("naming flag `alpha`")
+    expect(prompt).toContain("- `README.md:1`\n")
+    expect(prompt).toContain("- `README.md:50`\n")
+    expect(prompt).toContain(
+      "…and 3 more: `git grep --full-name -niIE '(^|[^a-z0-9_])(gtd_flag_|flag_)?alpha([^a-z0-9_]|$)' -- ':(top)' ':(top,exclude,literal)src/flags/index.ts' ':(top,exclude).gtd'`",
+    )
+  })
+
+  const listed = (value: string): string =>
+    summaryPrompt({
+      ...base,
+      vars: { flag: "alpha", flagRegistry: "src/flags/index.ts" },
+      marks: [
+        { name: "flag-mentions", value: "1" },
+        { name: "flag-mention", value },
+      ],
+    })
+
+  it("prints a listed path with one backtick verbatim inside a double-backtick fence", () => {
+    expect(listed("a`b.ts:1")).toContain("- `` a`b.ts:1 ``\n")
+  })
+
+  it("prints a listed path with a double-backtick run verbatim inside a triple-backtick fence", () => {
+    expect(listed("a``b.ts:1")).toContain("- ``` a``b.ts:1 ```\n")
+  })
+
+  it("prints a plain listed path as a single-backtick span", () => {
+    expect(listed("src/x.ts:7")).toContain("- `src/x.ts:7`\n") // gtd-path-exempt: fixture path
+  })
+
+  it("escapes regex metacharacters in the more-hint", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "a.b", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    const command = /more: `(git grep [^`]+)`/.exec(prompt)?.[1] ?? ""
+    expect(command).toContain("a\\.b")
+  })
+
+  it("shell-quotes a flag name holding a quote and the command still matches it", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "it's", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    const command = /more: `(git grep [^`]+)`/.exec(prompt)?.[1] ?? ""
+    expect(command).toContain("it'\\''s")
+    const { dir, env, git } = scratchRepo()
+    git("init", "-q")
+    writeFileSync(join(dir, "a.txt"), "uses it's here\nuses GTD_FLAG_it's too\nunrelated\n")
+    git("add", "a.txt")
+    git("commit", "-q", "-m", "x")
+    const out = execFileSync("sh", ["-c", command], { cwd: dir, env }).toString()
+    expect(out.trim().split("\n")).toHaveLength(2)
+    expect(out).toContain("it's here")
+    expect(out).toContain("GTD_FLAG_it's")
+  })
+
+  it("keeps a backtick in the flag name and wraps the command in a double-backtick span", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "a`b", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    const command = /more: `` (git grep .+?) ``\n/.exec(prompt)?.[1] ?? ""
+    expect(command).toContain("a`b")
+  })
+
+  it("sizes the span delimiter past a backtick run in the flag name", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "a``b", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    const command = /more: ``` (git grep .+?) ```\n/.exec(prompt)?.[1] ?? ""
+    expect(command).toContain("a``b")
+  })
+
+  it("shell-quotes a registry path holding a quote, and the command still runs", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha", flagRegistry: "config/it's flags.ts" },
+      marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+    })
+    const command = /more: `(git grep [^`]+)`/.exec(prompt)?.[1] ?? ""
+    expect(command).toContain(`':(top,exclude,literal)config/it'\\''s flags.ts'`)
+    const { dir, env, git } = scratchRepo()
+    git("init", "-q")
+    // git grep exits 1 for no match; 128 would be a rejected pathspec
+    expect(() =>
+      execFileSync("sh", ["-c", `${command}; test $? -le 1`], { cwd: dir, env }),
+    ).not.toThrow()
+  })
+
+  it("prints a git grep hint that finds all three mention forms in tracked files only", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha", flagRegistry: "src/flags/index.ts" },
+      marks: [{ name: "flag-mentions", value: "2" }],
+    })
+    const command = /more: `(git grep [^`]+)`/.exec(prompt)?.[1] ?? ""
+    const { dir, env, git } = scratchRepo()
+    mkdirSync(join(dir, "src/flags"), { recursive: true })
+    mkdirSync(join(dir, ".gtd"))
+    writeFileSync(
+      join(dir, "a.md"),
+      "GTD_FLAG_ALPHA=1\nflag_alpha\nThe alpha flag\nalphabet\nmy_alpha\n",
+    )
+    writeFileSync(join(dir, "src/flags/index.ts"), "alpha\n")
+    writeFileSync(join(dir, ".gtd/TODO.md"), "alpha\n")
+    writeFileSync(join(dir, "untracked.md"), "alpha\n")
+    writeFileSync(join(dir, "bin.dat"), "alpha\u0000\n")
+    git("init", "-q")
+    git("add", "a.md", "bin.dat", "src/flags/index.ts")
+    git("add", "-f", ".gtd/TODO.md")
+    git("commit", "-q", "-m", "init")
+    const expected = ["a.md:1:GTD_FLAG_ALPHA=1", "a.md:2:flag_alpha", "a.md:3:The alpha flag"]
+    // from a subdirectory the hint must still search the whole repository
+    for (const cwd of [dir, join(dir, "src")]) {
+      const out = execFileSync("sh", ["-c", `${command}; test $? -le 1`], { cwd, env }).toString()
+      expect(out.trim().split("\n")).toEqual(expected)
+    }
+  })
+
+  describe("with no usable flagRegistry", () => {
+    const run = (vars: Record<string, string>) => {
+      const prompt = summaryPrompt({
+        ...base,
+        vars: { flag: "alpha", ...vars },
+        marks: [{ name: "flag-mentions", value: "53" }, ...listedMentions],
+      })
+      const command = /more: `(git grep [^`]+)`/.exec(prompt)?.[1] ?? ""
+      const { dir, env, git } = scratchRepo()
+      mkdirSync(join(dir, "src/flags"), { recursive: true })
+      writeFileSync(join(dir, "a.md"), "The alpha flag\n")
+      writeFileSync(join(dir, "src/flags/index.ts"), "alpha\n")
+      git("init", "-q")
+      git("add", "a.md", "src/flags/index.ts")
+      git("commit", "-q", "-m", "init")
+      const out = execFileSync("sh", ["-c", `${command}; test $? -le 1`], { cwd: dir, env })
+      return { command, out: out.toString().trim() }
+    }
+
+    it("falls back to the default registry when the var is unset", () => {
+      const { out } = run({})
+      expect(out).toBe("a.md:1:The alpha flag")
+    })
+
+    it("falls back to the default registry when the var is empty, never an empty exclude", () => {
+      const { command, out } = run({ flagRegistry: "" })
+      expect(command).toContain("':(top,exclude,literal)src/flags/index.ts'")
+      expect(command).not.toContain("':(top,exclude,literal)'")
+      expect(out).toBe("a.md:1:The alpha flag")
+    })
+  })
+
+  it("says nothing of more when every mention is listed", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha" },
+      marks: [
+        { name: "flag-mentions", value: "1" },
+        { name: "flag-mention", value: "README.md:3" },
+      ],
+    })
+    expect(prompt).toContain("- `README.md:3`\n")
+    expect(prompt).not.toContain("more: ")
+  })
+
+  it("adds no flag section without flag marks, even with a flag var", () => {
+    const prompt = summaryPrompt({
+      ...base,
+      vars: { flag: "alpha" },
+      marks: [{ name: "risk-tier", value: "low" }],
+    })
+    expect(prompt).toContain("Token cost: 0\n\nPrint the closing message")
+    expect(prompt).not.toContain("alpha")
+  })
+
   it("adds the advisory risk line once for the last lap's high tier", () => {
     const prompt = summaryPrompt({
       ...base,