@pmelab/gtd 27.0.0 → 27.2.0

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/health.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { toRequest } from "../../judges/index.js"
+import { testRepo } from "../../testkit/index.js"
 import { retryQuestion } from "./health.js"
 
 describe("retryQuestion", () => {
@@ -11,3 +12,41 @@ describe("retryQuestion", () => {
     ).toBeGreaterThanOrEqual(2)
   })
 })
+
+describe("gate guard", () => {
+  const config = (guard: string) =>
+    [
+      `import { gate } from "@pmelab/gtd/workflows"`,
+      `import { agent, refuse } from "@pmelab/gtd/flows"`,
+      `export const held = async () => { await agent("first", "go"); ${guard}; await gate("suite", "fix it", guard) }`,
+      `export default held`,
+    ].join("\n")
+
+  const red = {
+    first: (_: unknown, r: { write(p: string, c: string): void }) => r.write("f", "1\n"),
+    "suite.check": (_: unknown, r: { write(p: string, c: string): void }) =>
+      r.write(".gtd/FEEDBACK.md", "red\n"),
+  }
+
+  it("runs the guard after a blocked landing and lets its refusal stop it", async () => {
+    const repo = testRepo({
+      workflow: config('const guard = () => { refuse("guarded: nope") }'),
+      env: { GTD_TEST_COMMAND: "true" },
+    })
+    await repo.start("held")
+    await repo.drive(red)
+    await expect(repo.drive({ "suite.blocked": (_, r) => r.write("x", "1\n") })).rejects.toThrow(
+      "guarded: nope",
+    )
+  })
+
+  it("never runs the guard after the check step", async () => {
+    const repo = testRepo({
+      workflow: config('const guard = () => { refuse("guarded: nope") }'),
+      env: { GTD_TEST_COMMAND: "true" },
+    })
+    await repo.start("held")
+    const rest = await repo.drive(red)
+    expect(rest.state).toBe("suite.blocked")
+  })
+})

package/src/workflows/shared/health.ts

@@ -28,13 +28,30 @@ const escalationSteps: kit.EscalationSteps = {
   exhausted: escalationExhausted,
 }
 
+/** Runs after an agent or human turn; refuses it by throwing (`refuse`). */
+export type Guard = () => void
+
+export const guarded =
+  <A extends unknown[]>(turn: (...a: A) => Promise<void>, guard?: Guard) =>
+  async (...a: A): Promise<void> => {
+    await turn(...a)
+    guard?.()
+  }
+
+const guardedSteps = (guard?: Guard): kit.EscalationSteps => ({
+  limit: escalationSteps.limit,
+  describe: guarded(escalationSteps.describe, guard),
+  stop: guarded(escalationSteps.stop, guard),
+  exhausted: guarded(escalationSteps.exhausted, guard),
+})
+
 /**
  * Hand a red suite that repeated attempts could not fix to a person: an
  * agent writes `.gtd/ESCALATION.md`, a human narrows it. From the third round
  * on, the human is told the budget is spent instead.
  */
-export const escalation = (count: kit.EscalationCount): Promise<void> =>
-  kit.escalation(count, escalationSteps)
+export const escalation = (count: kit.EscalationCount, guard?: Guard): Promise<void> =>
+  kit.escalation(count, guardedSteps(guard))
 
 /** "Is this red round the same failure as the last one?" — asked of two reports, or of nothing when one is empty. */
 export const retryQuestion = (comparable: boolean): JudgeQuestion =>
@@ -79,6 +96,8 @@ export interface HealthOptions {
   readonly escalations?: kit.EscalationCount
   /** Paths removed on a green run. */
   readonly sweepOnGreen?: readonly string[]
+  /** Runs after every fix and escalation turn. */
+  readonly guard?: Guard | undefined
 }
 
 const runSuite = (options: HealthOptions): Promise<boolean> =>
@@ -95,20 +114,24 @@ const runSuite = (options: HealthOptions): Promise<boolean> =>
  * identical to the previous round's.
  */
 export const healthy = (fix: () => Promise<void>, options: HealthOptions = {}): Promise<void> =>
-  kit.healthy(fix, {
+  kit.healthy(guarded(fix, options.guard), {
     check: () => runSuite(options),
     report: FEEDBACK,
     fixCap: FIX_CAP,
     fixesSoFar: options.fixesSoFar ?? 0,
     sameFailure,
     escalations: options.escalations ?? { rounds: 0 },
-    escalation: escalationSteps,
+    escalation: guardedSteps(options.guard),
   })
 
-/** Hold the process at `<name>.blocked` until the suite is green. */
-export const gate = (name: string, message: string): Promise<void> =>
+/**
+ * Hold the process at `<name>.blocked` until the suite is green. `guard` runs
+ * after each `blocked` landing only — never after a check, whose refusal would
+ * re-run the same script forever.
+ */
+export const gate = (name: string, message: string, guard?: Guard): Promise<void> =>
   kit.gate(
     name,
     () => baseline("check"),
-    () => human("blocked", { message, label: "Baseline is red", file: FEEDBACK }),
+    guarded(() => human("blocked", { message, label: "Baseline is red", file: FEEDBACK }), guard),
   )

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

@@ -1,8 +1,10 @@
 import { describe, expect, it } from "vitest"
 import { configure } from "../../flows/index.js"
 import * as workflows from "../index.js"
+import * as options from "./options.js"
 
 const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflows
+const { flagShipped } = options
 
 describe("the shipped workflow factories", () => {
   it("take exactly the settings the shipped workflows declare as options", () => {
@@ -57,4 +59,24 @@ describe("the shipped workflow factories", () => {
     const result = configure(fix({ judgeBudgetBytes: 65536 }))
     expect(result).toMatchObject({ ok: false, issues: [{ path: ["judgeBudgetBytes"] }] })
   })
+
+  describe("flagShipped", () => {
+    const factory = flagShipped(async () => {})
+
+    it("declare flag and flagRegistry as process settings, so --var flag= is accepted", () => {
+      expect(configure(factory)).toMatchObject({
+        ok: true,
+        build: {
+          defaults: { ...defaults, flag: "", flagRegistry: "src/flags/index.ts" },
+          envDefaults,
+        },
+      })
+    })
+
+    it("fail the load on an unknown option", () => {
+      // @ts-expect-error — `flag` is a --var, not an option
+      const result = configure(factory({ flag: "x" }))
+      expect(result).toMatchObject({ ok: false, issues: [{ path: ["flag"] }] })
+    })
+  })
 })

package/src/workflows/shared/options.ts

@@ -48,3 +48,22 @@ export const shipped = (
       base,
     }),
   )
+
+export const FlagOptions = Schema.Struct({ ...ShippedOptions.fields, flagRegistry: setting })
+
+export type FlagOptions = Schema.Schema.Encoded<typeof FlagOptions>
+
+export const flagShipped = (flow: Flow): WorkflowFactory<FlagOptions> =>
+  defineWorkflow(
+    Schema.standardSchemaV1(FlagOptions, { onExcessProperty: "error", errors: "all" }),
+    (options) => {
+      const flagDefaults = { ...defaults, flag: "", flagRegistry: "src/flags/index.ts" }
+      return {
+        flow,
+        defaults: over(flagDefaults, options),
+        envDefaults: over(envDefaults, options),
+        doors: {},
+        base: undefined,
+      }
+    },
+  )