@pmelab/gtd 27.1.0 → 27.3.0

package/src/workflows/feature/refactor.ts

@@ -0,0 +1,178 @@
+import {
+  changes,
+  changesSince,
+  head,
+  quote,
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  vars,
+  type DiffShapeResult,
+} from "../../flows/index.js"
+import { healthy } from "../shared/health.js"
+import { coder, FEEDBACK } from "../shared/steps.js"
+import * as t from "../shared/text.js"
+import { defaults } from "../shared/vars.js"
+
+export const REFACTOR_PACKAGE = ".gtd/REFACTOR.md"
+
+export interface RefactorOptions {
+  /** Blank counts as absent: `kept()` reports `""` while the keeping turn is pending. */
+  readonly reference?: string | undefined
+}
+
+const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
+
+export const requireWithin = (allowed: readonly string[]): void => {
+  const outside = changes()
+    .map((c) => c.path)
+    .filter((path) => isCode(path) && !allowed.includes(path))
+  if (outside.length === 0) return
+  refuse(
+    `gtd land: refactor-scope: the refactor may change only its stray paths — revert these:\n${outside.map((path) => `  - ${path}`).join("\n")}`,
+  )
+}
+
+const flagExpression = (pattern: string): RegExp => {
+  if (pattern.trim() === "") throw new Error("gtd: refactorFlagPattern must not be blank")
+  let expression: RegExp
+  try {
+    expression = new RegExp(pattern, "g")
+  } catch (error) {
+    throw new Error(`gtd: refactorFlagPattern is not a valid regular expression: ${String(error)}`)
+  }
+  // An empty match would count the name "" at every character.
+  if (expression.test(""))
+    throw new Error("gtd: refactorFlagPattern must not match the empty string")
+  return expression
+}
+
+// A zero-length match is never counted: a lookahead-only pattern would count every read
+// under "" and let a flag swap pass. Checked on the strays up front and again at landing.
+const countFlags = (text: string, expression: RegExp, into: Map<string, number>): boolean => {
+  let zeroLength = false
+  for (const [name] of text.matchAll(expression)) {
+    if (name === "") zeroLength = true
+    else into.set(name, (into.get(name) ?? 0) + 1)
+  }
+  return zeroLength
+}
+
+const listPaths = (paths: readonly string[]): string =>
+  paths.map((path) => `  - ${path}`).join("\n")
+
+// Counts per name, so a read moved between files passes.
+export const requireNoNewFlags = (pattern: string, since: string): void => {
+  const expression = flagExpression(pattern)
+  const before = new Map<string, number>()
+  const after = new Map<string, number>()
+  const unreadable: string[] = []
+  const zeroLength: string[] = []
+  for (const { path, status, before: was, after: now } of changesSince(since)) {
+    if (!isCode(path)) continue
+    // A side absent by status is empty; one absent otherwise could not be read.
+    const oldSide = status === "added" ? "" : was
+    const newSide = status === "deleted" ? "" : now
+    if (oldSide === undefined || newSide === undefined) {
+      unreadable.push(path)
+      continue
+    }
+    countFlags(oldSide, expression, before)
+    if (countFlags(newSide, expression, after)) zeroLength.push(path)
+  }
+  if (unreadable.length > 0)
+    refuse(`gtd land: refactor-flags: cannot compare flag reads in:\n${listPaths(unreadable)}`)
+  if (zeroLength.length > 0)
+    refuse(
+      `gtd land: refactor-flags: refactorFlagPattern (${pattern}) produced a zero-length match in:\n${listPaths(zeroLength)}`,
+    )
+  const raised = [...after].filter(([name, count]) => count > (before.get(name) ?? 0))
+  if (raised.length === 0) return
+  refuse(
+    `gtd land: refactor-flags: the refactor may not introduce or add reads of a flag (${pattern}):\n${raised.map(([name, count]) => `  - ${name}: ${before.get(name) ?? 0} → ${count}`).join("\n")}`,
+  )
+}
+
+const packageLines = (
+  strays: readonly string[],
+  pattern: string,
+  reference: string | undefined,
+): string[] => [
+  "# Behaviour-neutral refactor",
+  "",
+  "## Scope (read-only)",
+  "",
+  ...strays.map((path) => `- \`${path}\``),
+  "",
+  "This list is fixed when the package is derived: editing it here widens or narrows nothing.",
+  "",
+  "## Rules",
+  "",
+  "- The suite's outcome must not change",
+  "- Change only the paths above; a test file only when it is one of them",
+  `- Introduce no flag read and add no second read of an existing one (\`${pattern}\`)`,
+  "",
+  "## Reference",
+  "",
+  reference === undefined
+    ? "None."
+    : `Reading material only, never applied: \`git show ${reference} -- ${strays.map(quote).join(" ")}\``,
+  "",
+]
+
+const deriveScript = (lines: readonly string[]): string =>
+  `mkdir -p .gtd
+printf '%s\\n' ${lines.map(quote).join(" ")} > ${quote(REFACTOR_PACKAGE)}
+`
+
+export const refactorFirst = async (
+  shape: DiffShapeResult,
+  options: RefactorOptions = {},
+): Promise<boolean> => {
+  if (shape.choice !== "refactor-first" || shape.unreadable.length > 0) return false
+  const pattern = vars.refactorFlagPattern ?? defaults.refactorFlagPattern!
+  const expression = flagExpression(pattern)
+  const { strays } = shape
+  const zeroLength = strays.filter((path) => countFlags(read(path) ?? "", expression, new Map()))
+  if (zeroLength.length > 0)
+    throw new Error(
+      `gtd: refactorFlagPattern (${pattern}) produces a zero-length match in:\n${listPaths(zeroLength)}`,
+    )
+  const reference = options.reference?.trim() ? options.reference : undefined
+  return scope({ name: "refactor", access: { write: [...strays, ".gtd/**"] } }, async () => {
+    await run("deriving", deriveScript(packageLines(strays, pattern, reference)), {
+      label: "Deriving the refactor package",
+      file: REFACTOR_PACKAGE,
+    })
+    const from = head()
+    // The in-memory `strays`, never the package file: a hand edit of its list changes nothing.
+    // Scope looks at the turn's own changes: a person's edit at an escalation rest must not
+    // wedge every later fix turn. Flags look at the whole range.
+    const guard = (): void => {
+      requireWithin(strays)
+      requireNoNewFlags(pattern, from)
+    }
+    await t.agentWithSkills(
+      "building",
+      t.refactorBuildingPrompt(REFACTOR_PACKAGE, strays, pattern, reference),
+      { label: "Refactoring", model: coder(), system: t.builderSystem() },
+    )
+    guard()
+    await healthy(
+      async () => {
+        await t.agentWithSkills("fix.suite.fixing", t.refactorFixPrompt(strays, pattern), {
+          label: "Fixing the check",
+          file: FEEDBACK,
+          model: coder(),
+          system: t.builderSystem(),
+        })
+        guard()
+      },
+      { describeGuard: guard },
+    )
+    await run("closing", removeScript([REFACTOR_PACKAGE]), { label: "Closing out the refactor" })
+    return true
+  })
+}

package/src/workflows/index.ts

@@ -5,7 +5,7 @@ import { feature } from "./feature/feature.js"
 
 export { threads, type ThreadInfo } from "../flows/index.js"
 export * from "./shared/reserved.js"
-export { ShippedOptions } from "./shared/options.js"
+export { FlagOptions, ShippedOptions } from "./shared/options.js"
 export { agentWithSkills } from "./shared/text.js"
 export * from "./shared/steps.js"
 export * from "./shared/health.js"
@@ -22,10 +22,13 @@ export { lensesOf } from "../workflow-kit/index.js"
 export * from "./feature/steps.js"
 export * from "./feature/planning.js"
 export * from "./feature/packages.js"
+export * from "./feature/refactor.js"
 export { buildTail, type ReviewOutcome } from "./feature/review.js"
 export * from "./feature/feature.js"
 export { base, review, reviewFlow } from "./review/review.js"
 export { fix, fixFlow, fixReviewNotes } from "./fix/fix.js"
+export { rollout, rolloutFlow } from "./rollout/rollout.js"
+export { cleanup, cleanupFlow } from "./cleanup/cleanup.js"
 
 export default feature
 

package/src/workflows/rollout/index.ts

@@ -0,0 +1,6 @@
+import { rollout } from "./rollout.js"
+
+export { rollout, rolloutFlow } from "./rollout.js"
+export * from "../shared/reserved.js"
+
+export default rollout

package/src/workflows/rollout/rollout.feature

@@ -0,0 +1,214 @@
+Feature: rollout turns one release flag default-on and touches nothing else
+
+  `gtd --workflow rollout --var flag=<name>` has an agent set `defaultOn: true`
+  on the named registry entry; a check refuses any other change, and a red
+  suite rests at a human gate — never a fix turn.
+
+  Background:
+    Given a gtd config with:
+      """
+      export {
+        feature as default,
+        feature,
+        defaults,
+        envDefaults,
+        summary,
+        steering,
+        skills,
+        access,
+      } from "@pmelab/gtd/workflows/feature"
+      import { rollout } from "@pmelab/gtd/workflows"
+      export { rollout }
+      export const elsewhere = rollout({ flagRegistry: "config/flags.ts" })
+      """
+    And a file "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => a + b
+      """
+    And a file "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+        { 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 the working tree is committed as "feat: registry"
+
+  Scenario: a flip of the named entry lands, the suite passes and the process ends
+    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
+    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"
+
+  Scenario: a turn also changing a source file 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.flipping" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => b + a
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    Then driving the process is refused with "rollout-only: src/calc.ts changed"
+
+  Scenario: a turn editing a second registry entry 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: "zed", 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 "other edits in src/flags/index.ts"
+
+  Scenario: a factory flagRegistry names the one file the guard allows
+    Given a file "config/flags.ts" with:
+      """
+      export const FLAGS = [
+        { name: "gamma", owner: "g", expiry: "2027-05-01", kind: "release" },
+      ] as const
+      """
+    And the working tree is committed as "feat: second registry"
+    And step "rollout.flipping" writes "config/flags.ts" with:
+      """
+      export const FLAGS = [
+        { name: "gamma", owner: "g", expiry: "2027-05-01", kind: "release", defaultOn: true },
+      ] as const
+      """
+    And step "rollout.suite.check" changes nothing
+    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"
+
+  Scenario: a missing flag var is refused before any turn
+    Then starting workflow "rollout" with "" is refused with "gtd: rollout needs --var flag=<name>"
+
+  Scenario: an unknown flag is refused before any turn
+    Then starting workflow "rollout" with "--var flag=nope" is refused with "no flag \"nope\" in src/flags/index.ts"
+
+  Scenario: an ops flag is refused before any turn
+    Then starting workflow "rollout" with "--var flag=ops1" is refused with "flag \"ops1\" is ops, not release"
+
+  Scenario: an already default-on flag is refused before any turn
+    Then starting workflow "rollout" with "--var flag=live" is refused with "flag \"live\" is already default-on"
+
+  Scenario: a red suite after the flip rests at the blocked gate with no fix turn
+    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" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "rollout.suite.blocked"
+
+  @inmem
+  Scenario: a human fix at the blocked gate that also edits a source file 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" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "rollout.suite.blocked"
+    And step "rollout.suite.blocked" writes "src/calc.ts" with:
+      """
+      export const add = (a: number, b: number) => b + a
+      """
+    Then driving the process is refused with "rollout-only: src/calc.ts changed"
+
+  @inmem
+  Scenario: a human fix at the blocked gate that edits a second registry entry 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" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "rollout.suite.blocked"
+    And step "rollout.suite.blocked" writes "src/flags/index.ts" with:
+      """
+      export const FLAGS = [
+        { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true },
+        { name: "beta", owner: "zed", 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
+      """
+    Then driving the process is refused with "other edits in src/flags/index.ts"
+
+  @inmem
+  Scenario: a human fix touching only the feedback file lands and the process ends with no review
+    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" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "rollout" with "--var flag=alpha"
+    And the process is driven
+    Then the process rests at "rollout.suite.blocked"
+    And step "rollout.suite.blocked" writes ".gtd/FEEDBACK.md" with:
+      """
+      fixed by hand
+      """
+    And step "rollout.suite.check" from now on changes nothing
+    When the process is driven
+    Then the process rests at "idle"
+    And the last commit subject is "gtd(check): rollout.suite.check → idle"

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

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest"
+import { CONFIG_SCAFFOLD } from "../../install/index.js"
+import { testRepo } from "../../testkit/index.js"
+
+const CONFIG = `${CONFIG_SCAFFOLD}export { rollout } from "@pmelab/gtd/workflows"\n`
+
+const REGISTRY = `export const FLAGS = [
+  { name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" },
+  { 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
+`
+
+const FLIPPED = REGISTRY.replace(
+  '{ name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release" }',
+  '{ name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true }',
+)
+
+const repoWith = () =>
+  testRepo({ workflow: CONFIG, files: { "src/flags/index.ts": REGISTRY, "src/a.ts": "a\n" } })
+
+describe("the rollout workflow", () => {
+  it("lands a flip, checks the suite and ends with no review", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    const rest = await repo.drive({
+      "rollout.flipping": (beat, r) => {
+        expect(beat.content).toContain("alpha")
+        r.write("src/flags/index.ts", FLIPPED)
+      },
+      "rollout.suite.check": () => undefined,
+    })
+    expect(rest.state).toBe("idle")
+    expect(repo.subjects().at(-1)).toBe("gtd(check): rollout.suite.check → idle")
+  })
+
+  it("lands a flip when the tree was already dirty at the start", async () => {
+    const repo = repoWith()
+    repo.write("src/other.ts", "dirty\n")
+    await repo.start("rollout", "--var", "flag=alpha")
+    const rest = await repo.drive({
+      "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
+      "rollout.suite.check": () => undefined,
+    })
+    expect(rest.state).toBe("idle")
+  })
+
+  it("refuses a turn that also changes a source file, naming it", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    await expect(
+      repo.drive({
+        "rollout.flipping": (_, r) => {
+          r.write("src/flags/index.ts", FLIPPED)
+          r.write("src/a.ts", "changed\n")
+        },
+      }),
+    ).rejects.toThrow(/rollout-only: src\/a\.ts changed/)
+  })
+
+  it("refuses an edit to a second entry", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    await expect(
+      repo.drive({
+        "rollout.flipping": (_, 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("refuses a turn that writes defaultOn: false, naming the fault", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    await expect(
+      repo.drive({
+        "rollout.flipping": (_, r) =>
+          r.write("src/flags/index.ts", FLIPPED.replace("defaultOn: true }", "defaultOn: false }")),
+      }),
+    ).rejects.toThrow('"alpha" is not set to defaultOn: true')
+  })
+
+  it("refuses a turn that also writes under .gtd/", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    await expect(
+      repo.drive({
+        "rollout.flipping": (_, r) => {
+          r.write("src/flags/index.ts", FLIPPED)
+          r.write(".gtd/NOTES.md", "planted\n")
+        },
+      }),
+    ).rejects.toThrow(/rollout-only: \.gtd\/NOTES\.md changed/)
+  })
+
+  it.each([
+    [[], "gtd: rollout needs --var flag=<name>"],
+    [["--var", "flag=nope"], 'gtd: rollout: no flag "nope" in src/flags/index.ts'],
+    [["--var", "flag=ops1"], 'gtd: rollout: flag "ops1" is ops, not release'],
+    [["--var", "flag=live"], 'gtd: rollout: flag "live" is already default-on'],
+  ])("refuses %j at start", async (args, message) => {
+    await expect(repoWith().start("rollout", ...args)).rejects.toThrow(message)
+  })
+
+  it("rests at rollout.suite.blocked on a red suite, with no fix turn", async () => {
+    const repo = repoWith()
+    await repo.start("rollout", "--var", "flag=alpha")
+    const rest = await repo.drive({
+      "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
+      "rollout.suite.check": (_, r) => r.write(".gtd/FEEDBACK.md", "1 failing\n"),
+    })
+    expect(rest).toMatchObject({ state: "rollout.suite.blocked", actor: "human" })
+  })
+
+  describe("the human's fix at rollout.suite.blocked", () => {
+    const blocked = async () => {
+      const repo = repoWith()
+      await repo.start("rollout", "--var", "flag=alpha")
+      await repo.drive({
+        "rollout.flipping": (_, r) => r.write("src/flags/index.ts", FLIPPED),
+        "rollout.suite.check": (_, r) => r.write(".gtd/FEEDBACK.md", "1 failing\n"),
+      })
+      return repo
+    }
+
+    it("refuses a fix that edits a source file, naming it", async () => {
+      const repo = await blocked()
+      await expect(
+        repo.drive({ "rollout.suite.blocked": (_, r) => r.write("src/a.ts", "fixed\n") }),
+      ).rejects.toThrow(/rollout-only: src\/a\.ts changed/)
+    })
+
+    it("refuses a fix that edits a second registry entry", async () => {
+      const repo = await blocked()
+      await expect(
+        repo.drive({
+          "rollout.suite.blocked": (_, 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("refuses a fix that rewrites the flipped entry back to defaultOn: false", async () => {
+      const repo = await blocked()
+      await expect(
+        repo.drive({ "rollout.suite.blocked": (_, r) => r.write("src/flags/index.ts", REGISTRY) }),
+      ).rejects.toThrow('"alpha" is not set to defaultOn: true')
+    })
+
+    it("lands a fix that re-wraps the flag's entry and ends with no review", async () => {
+      const repo = await blocked()
+      const rest = await repo.drive({
+        "rollout.suite.blocked": (_, r) =>
+          r.write(
+            "src/flags/index.ts",
+            FLIPPED.replace(
+              '{ name: "alpha", owner: "a", expiry: "2027-01-01", kind: "release", defaultOn: true }',
+              '{\n    name: "alpha",\n    owner: "a",\n    expiry: "2027-01-01",\n    kind: "release",\n    defaultOn: true,\n  }',
+            ),
+          ),
+        "rollout.suite.check": () => undefined,
+      })
+      expect(rest.state).toBe("idle")
+    })
+  })
+})

package/src/workflows/rollout/rollout.ts

@@ -0,0 +1,44 @@
+import { agent, changesSince, head, read, refuse, 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 { coder, FEEDBACK } from "../shared/steps.js"
+
+const flippingPrompt = (name: string, registry: string): string =>
+  `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`
+
+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."
+
+// No review gate — a one-field change needs no review lap.
+export const rolloutFlow = async (): Promise<void> => {
+  const registry = vars.flagRegistry ?? ""
+  const name = vars.flag ?? ""
+  // Before the turn, never after: replay re-runs every pre-turn check.
+  requireFlag("rollout", registry, name, false)
+  // Strays count from the same point `before` is read at, not `start()`: the opening commit sweeps in whatever the human left uncommitted.
+  const base = head()
+  const before = read(registry) ?? ""
+  const guard = (): void => {
+    const strays = changesSince(base).paths.filter((path) => path !== registry && path !== FEEDBACK)
+    if (strays.length > 0) {
+      refuse(
+        `gtd land: rollout-only: ${strays.join(", ")} changed — rollout may only set defaultOn: true on "${name}" in ${registry}`,
+      )
+    }
+    const problems = flipProblems(before, read(registry) ?? "", name)
+    if (problems.length > 0) {
+      refuse(`gtd land: rollout-only: other edits in ${registry}: ${problems.join("; ")}`)
+    }
+  }
+  await scope("rollout", async () => {
+    await agent("flipping", flippingPrompt(name, registry), {
+      label: `Rolling out ${name}`,
+      model: coder(),
+    })
+    guard()
+    await gate("suite", suiteBlockedMessage(), guard)
+  })
+}
+
+export const rollout = flagShipped(rolloutFlow)

package/src/workflows/shared/access.ts

@@ -3,7 +3,8 @@ import { lensesOf, lensScopes } from "../../workflow-kit/index.js"
 
 // The bundled workflow's default file access, keyed by scope full name — the
 // name a `config.access` entry addresses. Only planning and review scopes
-// are restricted, and only on writes; no scope restricts reads. A step's own
+// 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.
 export const access = (