@pmelab/gtd 58.2.0 → 59.0.1

package/src/flows/factory.ts

@@ -52,7 +52,9 @@ export const defineWorkflow = <S extends StandardSchemaV1>(
     // A factory call used to be a flow; awaiting one in a composed flow must fail, not no-op.
     // oxlint-disable-next-line unicorn/no-thenable -- awaiting a call must fail
     then: () => {
-      throw new Error("a configured workflow is not a flow — compose fixFlow/reviewFlow instead")
+      throw new Error(
+        "a configured workflow is not a flow — await the flow functions it is built from instead",
+      )
     },
   })
   return Object.assign(factory, { [FACTORY]: internals }) as never

package/src/gherkin/index.ts

@@ -21,6 +21,10 @@ import {
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
+import { assertContains, assertLacks, refusal, refusedWith, restDescription } from "./messages.js"
+
+// Kept off the class so the exported world's type stays as it is.
+const usedActors = new WeakMap<TestkitWorld, Set<string>>()
 
 export class TestkitWorld extends QuickPickleWorld {
   // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
@@ -88,6 +92,8 @@ export class TestkitWorld extends QuickPickleWorld {
 
   async drive(): Promise<void> {
     const actors: Record<string, Actor> = {}
+    const used = usedActors.get(this) ?? new Set<string>()
+    usedActors.set(this, used)
     for (const [step, actions] of this.actions) {
       actors[step] = async (beat, repo) => {
         for (const action of actions) await action(beat, repo)
@@ -115,7 +121,14 @@ export class TestkitWorld extends QuickPickleWorld {
         return hit[1]
       }
     }
-    await this.repo().drive(actors)
+    const tracked: Record<string, Actor> = {}
+    for (const [step, actor] of Object.entries(actors)) {
+      tracked[step] = (beat, repo) => {
+        used.add(step)
+        return actor(beat, repo)
+      }
+    }
+    await this.repo().drive(tracked)
   }
 }
 
@@ -125,6 +138,29 @@ const withNewline = (content: string): string => (content.endsWith("\n") ? conte
 
 const args = (list: string): string[] => list.split(" ").filter((arg) => arg !== "")
 
+const neverUsed = (world: TestkitWorld): string[] => {
+  const used = usedActors.get(world) ?? new Set<string>()
+  const scripted = new Set([
+    ...world.actions.keys(),
+    ...world.verdicts.keys(),
+    ...world.conditionalVerdicts.keys(),
+  ])
+  return [...scripted].filter((step) => !used.has(step))
+}
+
+/** An outcome step: a failure ends with where the process rests. */
+const outcome =
+  <A extends unknown[]>(check: (world: TestkitWorld, ...rest: A) => unknown) =>
+  async (world: TestkitWorld, ...rest: A): Promise<void> => {
+    try {
+      await check(world, ...rest)
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error))
+      failure.message += `\n\n${await restDescription(() => world.repo(), neverUsed(world))}`
+      throw failure
+    }
+  }
+
 Given("a gtd config with:", (world: TestkitWorld, source: string) => {
   world.configure(withNewline(source))
 })
@@ -337,74 +373,86 @@ When("the process is driven", async (world: TestkitWorld) => {
 
 Then(
   "opening door {string} is refused with {string}",
-  async (world: TestkitWorld, door: string, message: string) => {
-    await assert.rejects(world.repo().door(door), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, door: string, message: string) => {
+    await refusedWith(world.repo().door(door), message)
+  }),
 )
 
 Then(
   "starting workflow {string} with {string} is refused with {string}",
-  async (world: TestkitWorld, workflow: string, list: string, message: string) => {
-    await assert.rejects(world.repo().start(workflow, ...args(list)), (error: Error) =>
-      error.message.includes(message),
-    )
-  },
+  outcome(async (world, workflow: string, list: string, message: string) => {
+    await refusedWith(world.repo().start(workflow, ...args(list)), message)
+  }),
 )
 
-Then("landing is refused with {string}", async (world: TestkitWorld, message: string) => {
-  await assert.rejects(world.repo().land(), (error: Error) => error.message.includes(message))
-})
+Then(
+  "landing is refused with {string}",
+  outcome(async (world, message: string) => {
+    await refusedWith(world.repo().land(), message)
+  }),
+)
 
 Then(
   "driving the process is refused with {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    await refusedWith(world.drive(), message)
+  }),
 )
 
 Then(
   "driving the process is refused without {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => !error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    const got = await refusal(world.drive(), `without "${message}"`)
+    if (got.includes(message))
+      assert.fail(`expected a refusal without "${message}", but it was refused with:\n${got}`)
+  }),
 )
 
-Then("the process rests at {string}", async (world: TestkitWorld, step: string) => {
-  assert.strictEqual((await world.repo().next()).state, step)
-})
+Then(
+  "the process rests at {string}",
+  outcome(async (world, step: string) => {
+    assert.strictEqual((await world.repo().next()).state, step)
+  }),
+)
 
-Then("the resting step's content contains {string}", async (world: TestkitWorld, text: string) => {
-  const { content } = await world.repo().next()
-  assert.ok(content.includes(text), content)
-})
+Then(
+  "the resting step's content contains {string}",
+  outcome(async (world, text: string) => {
+    assertContains("the resting step's content", text, (await world.repo().next()).content)
+  }),
+)
 
 Then(
   "the resting step's content contains the hash of the commit {string}",
-  async (world: TestkitWorld, subject: string) => {
+  outcome(async (world, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    const { content } = await repo.next()
-    assert.ok(content.includes(hash), content)
-  },
+    assertContains("the resting step's content", hash, (await repo.next()).content)
+  }),
 )
 
 Then(
   "the resting step's content does not contain {string}",
-  async (world: TestkitWorld, text: string) => {
-    const { content } = await world.repo().next()
-    assert.ok(!content.includes(text), content)
-  },
+  outcome(async (world, text: string) => {
+    assertLacks("the resting step's content", text, (await world.repo().next()).content)
+  }),
 )
 
-Then("the last commit subject is {string}", (world: TestkitWorld, subject: string) => {
-  assert.strictEqual(world.repo().subjects().at(-1), subject)
-})
+Then(
+  "the last commit subject is {string}",
+  outcome((world, subject: string) => {
+    assert.strictEqual(world.repo().subjects().at(-1), subject)
+  }),
+)
 
-Then("the commit subjects end with:", (world: TestkitWorld, list: string) => {
-  const expected = list.split("\n").filter((line) => line.trim() !== "")
-  assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
-})
+Then(
+  "the commit subjects end with:",
+  outcome((world, list: string) => {
+    const expected = list.split("\n").filter((line) => line.trim() !== "")
+    assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
+  }),
+)
 
 const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
   const result = await world.repo().gtd(...args(list))
@@ -414,61 +462,77 @@ const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
 
 Then(
   "the output of gtd {string} contains {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertContains(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output of gtd {string} does not contain {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(!out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertLacks(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output lines of gtd {string} start with:",
-  async (world: TestkitWorld, list: string, prefixes: string) => {
+  outcome(async (world, list: string, prefixes: string) => {
     const out = (await outputOf(world, list)).split("\n").filter((line) => line !== "")
     const expected = prefixes.split("\n").filter((line) => line.trim() !== "")
-    assert.strictEqual(out.length, expected.length, out.join("\n"))
-    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), out.join("\n")))
-  },
+    const sides = `expected lines starting with:\n${expected.join("\n")}\ngot:\n${out.join("\n")}`
+    assert.strictEqual(out.length, expected.length, sides)
+    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), sides))
+  }),
 )
 
-Then("{string} contains {string}", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains {string}",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} contains:", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains:",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
 Then(
   "{string} contains the short hash of the commit {string}",
-  (world: TestkitWorld, path: string, subject: string) => {
+  outcome((world, path: string, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    assert.ok(repo.read(path)?.includes(hash.slice(0, 7)), `${path}: ${repo.read(path)}`)
-  },
+    assertContains(`"${path}"`, hash.slice(0, 7), repo.read(path))
+  }),
 )
 
 Then(
   "{string} contains {string} exactly once",
-  (world: TestkitWorld, path: string, text: string) => {
+  outcome((world, path: string, text: string) => {
     const content = world.repo().read(path) ?? ""
-    assert.strictEqual(content.split(text).length - 1, 1, `${path}: ${content}`)
-  },
+    const times = content.split(text).length - 1
+    assert.strictEqual(
+      times,
+      1,
+      `"${path}" contains "${text}" ${times} times; it holds:\n${content}`,
+    )
+  }),
 )
 
-Then("{string} does not contain {string}", (world: TestkitWorld, path: string, text: string) => {
-  const content = world.repo().read(path)
-  assert.ok(content !== undefined && !content.includes(text), `${path}: ${content}`)
-})
+Then(
+  "{string} does not contain {string}",
+  outcome((world, path: string, text: string) => {
+    assertLacks(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} does not exist", (world: TestkitWorld, path: string) => {
-  assert.strictEqual(world.repo().read(path), undefined)
-})
+Then(
+  "{string} does not exist",
+  outcome((world, path: string) => {
+    const content = world.repo().read(path)
+    assert.strictEqual(content, undefined, `"${path}" exists; it holds:\n${content}`)
+  }),
+)

package/src/gherkin/messages.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest"
+import { agent, human } from "../flows/index.js"
+import { testRepo } from "../testkit/index.js"
+import { assertContains, assertLacks, refusedWith, restDescription } from "./messages.js"
+
+const flow = async (): Promise<void> => {
+  await agent("plan", "Write PLAN.md.\nKeep it short.\n3\n4\n5\n6\n7")
+  await human("sign-off")
+}
+
+const thrown = async (fn: () => unknown): Promise<string> => {
+  try {
+    await fn()
+  } catch (error) {
+    return (error as Error).message
+  }
+  throw new Error("did not throw")
+}
+
+describe("restDescription", () => {
+  it("names the step, its kind and actor, the content's head, the last commits and the unused actors", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    expect(await restDescription(() => repo, ["repair", "ready"])).toBe(
+      [
+        "where the process rests:",
+        '  step "sign-off" (message, human)',
+        "  content:",
+        "    | sign-off",
+        "  last commits:",
+        "    chore: initial commit",
+        "    gtd(agent): plan → sign-off",
+        '  actors never used: "repair", "ready"',
+      ].join("\n"),
+    )
+  })
+
+  it("cuts long content to its first lines", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    const description = await restDescription(() => repo, [])
+    expect(description).toContain('step "plan" (prompt, agent)')
+    expect(description).toContain("    | 5\n    | … 2 more lines")
+    expect(description).not.toContain("actors never used")
+  })
+
+  it("says why the rest is unknown instead of throwing", async () => {
+    const description = await restDescription(() => {
+      throw new Error("no gtd config")
+    }, [])
+    expect(description).toBe("where the process rests:\n  unknown — no gtd config")
+  })
+})
+
+describe("refusedWith", () => {
+  it("says nothing was refused when the attempt succeeds", async () => {
+    expect(await thrown(() => refusedWith(Promise.resolve(), "nope"))).toBe(
+      'expected a refusal with "nope", but nothing was refused',
+    )
+  })
+
+  it("prints the refusal it got when the text is missing", async () => {
+    expect(await thrown(() => refusedWith(Promise.reject(new Error("other")), "nope"))).toBe(
+      'expected a refusal with "nope", but it was refused with:\nother',
+    )
+  })
+
+  it("passes on a refusal carrying the text", async () => {
+    await refusedWith(Promise.reject(new Error("a nope b")), "nope")
+  })
+})
+
+describe("contains", () => {
+  it("prints the text looked for and what was there", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", "y\n"))).toBe(
+      '"a.md" does not contain "x"; it holds:\ny\n',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "y", "y\n"))).toBe(
+      '"a.md" contains "y"; it holds:\ny\n',
+    )
+  })
+
+  it("says a missing file does not exist", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", undefined))).toBe(
+      '"a.md" does not exist, so it cannot contain "x"',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "x", undefined))).toBe('"a.md" does not exist')
+  })
+})

package/src/gherkin/messages.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert"
+import type { TestRepo } from "../testkit/index.js"
+
+const CONTENT_LINES = 5
+const SUBJECTS = 5
+
+const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+const beatLines = async (repo: TestRepo): Promise<string[]> => {
+  try {
+    const beat = await repo.next()
+    const content = beat.content.trimEnd().split("\n")
+    const more = content.length - CONTENT_LINES
+    return [
+      `step "${beat.state}" (${beat.kind}, ${beat.actor}${beat.idle ? ", idle" : ""})`,
+      "content:",
+      ...content.slice(0, CONTENT_LINES).map((line) => `  | ${line}`),
+      ...(more > 0 ? [`  | … ${more} more lines`] : []),
+    ]
+  } catch (error) {
+    return [`unknown — gtd next failed: ${reason(error)}`]
+  }
+}
+
+/** Where the process rests, for a failed outcome to end with. Never throws: it describes a failure. */
+export const restDescription = async (
+  repo: () => TestRepo,
+  neverUsed: readonly string[],
+): Promise<string> => {
+  let lines: string[]
+  try {
+    const r = repo()
+    lines = [
+      ...(await beatLines(r)),
+      "last commits:",
+      ...r
+        .subjects()
+        .slice(-SUBJECTS)
+        .map((subject) => `  ${subject}`),
+    ]
+  } catch (error) {
+    lines = [`unknown — ${reason(error)}`]
+  }
+  if (neverUsed.length > 0)
+    lines.push(`actors never used: ${neverUsed.map((step) => `"${step}"`).join(", ")}`)
+  return ["where the process rests:", ...lines.map((line) => `  ${line}`)].join("\n")
+}
+
+/** Both sides of a failed `contains`: the text looked for, and what was there. */
+const containsFailure = (
+  where: string,
+  text: string,
+  content: string | undefined,
+  expected: boolean,
+): string =>
+  content === undefined
+    ? `${where} does not exist${expected ? `, so it cannot contain "${text}"` : ""}`
+    : `${where} ${expected ? "does not contain" : "contains"} "${text}"; it holds:\n${content}`
+
+/** What `attempt` was refused with; fails when it was not refused at all. */
+export const refusal = async (attempt: Promise<unknown>, expectation: string): Promise<string> => {
+  try {
+    await attempt
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+  assert.fail(`expected a refusal ${expectation}, but nothing was refused`)
+}
+
+export const refusedWith = async (attempt: Promise<unknown>, message: string): Promise<void> => {
+  const got = await refusal(attempt, `with "${message}"`)
+  if (!got.includes(message))
+    assert.fail(`expected a refusal with "${message}", but it was refused with:\n${got}`)
+}
+
+export const assertContains = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || !content.includes(text))
+    assert.fail(containsFailure(where, text, content, true))
+}
+
+export const assertLacks = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || content.includes(text))
+    assert.fail(containsFailure(where, text, content, false))
+}

package/src/install/Install.test.ts

@@ -9,8 +9,13 @@ import { readFileSync } from "node:fs"
 import { resolve } from "node:path"
 import { createRequire } from "node:module"
 import { describe, expect, it } from "vitest"
-import { EDIT_COMMAND, DOOR_COMMAND, MINIMAL_DRIVER, renderBriefing } from "./Install.js"
-import { CONFIG_SCAFFOLD } from "./index.js"
+import {
+  EDIT_COMMAND,
+  DOOR_COMMAND,
+  MINIMAL_DRIVER,
+  renderBriefing,
+  WORKFLOWS_REPO,
+} from "./Install.js"
 
 const SUITE_PATHS = ["gtd-build", "gtd-edit", "gtd-door"]
 const SUPERSEDED_PATHS = ["gtd-fix", "gtd-review"]
@@ -110,6 +115,13 @@ describe("renderBriefing", () => {
     expect(briefing).not.toContain(".gtdrc")
   })
 
+  it("says gtd ships no workflow, offering gtd-workflows or the user's own", () => {
+    const briefing = renderBriefing()
+    expect(briefing).toContain("gtd ships no")
+    expect(briefing).toContain(`git clone ${WORKFLOWS_REPO}`)
+    expect(briefing).toMatch(/\*\*Their own workflow\.\*\*/)
+  })
+
   it("instructs committing the config before the first drive", () => {
     expect(renderBriefing()).toMatch(/commit (it|the config).{0,40}before.{0,20}drive/is)
   })
@@ -425,12 +437,3 @@ describe("DOOR_COMMAND", () => {
     expect(DOOR_COMMAND).toMatch(/usage: gtd-door <name> \[args\.\.\.\]" >&2\n\s*exit 2/)
   })
 })
-
-describe("bundled door lists", () => {
-  it("the scaffold's exports stay feature, review, fix, never rollout or cleanup", () => {
-    const code = CONFIG_SCAFFOLD.split("\n")
-      .filter((l) => !l.startsWith("//"))
-      .join("\n")
-    expect(code).not.toMatch(/rollout|cleanup/)
-  })
-})

package/src/install/Install.ts

@@ -1,6 +1,8 @@
 // `MINIMAL_DRIVER` is pinned equal to https://github.com/pmelab/gtd/blob/main/docs/driver.md's "A complete minimal driver" fenced bash block by `Install.test.ts`, so the two can never drift.
 import { GTD_VERSION } from "./Version.js"
 
+export const WORKFLOWS_REPO = "https://github.com/pmelab/gtd-workflows"
+
 export const MINIMAL_DRIVER = `#!/usr/bin/env sh
 set -eu
 
@@ -82,7 +84,7 @@ while :; do
       system="$(gtd next --json=system)"
       validate="$(gtd next --json=validate)"
       log="$(gtd next --json=log)"
-      # \`model\` is a hint, not a model name — the bundled workflow ships
+      # \`model\` is a hint, not a model name — gtd-workflows' default ships
       # \`smart\` and \`base\`, which \`claude --model\` rejects. Resolve them
       # from your environment; unset, the hint is dropped and the agent runs
       # its own default. Any other value is a real model name.
@@ -420,14 +422,37 @@ follow in the same numbered list.
    existing config, the project's own README/docs) and ask the user what
    they're trying to accomplish with gtd here — don't assume a fresh
    install or silently start a process on their behalf.
-2. **Make sure a \`gtd.config.ts\` governs the repository.** Run at the
-   repository root, \`gtd install\` writes one importing gtd's shipped
-   workflows when none exists yet (its own message says so). Repository
-   settings — steering-file modes, \`gtd ui\`, per-scope skills and access —
-   go in its \`config\` export; workflow settings are options of the
-   workflow factory it exports.
-3. **Commit the config before the first drive.** \`gtd install\` leaves the
-   file it writes uncommitted on purpose — an uncommitted config is a
+2. **Make sure a \`gtd.config.ts\` governs the repository.** gtd ships no
+   workflow: the config imports the workflows it runs. Ask the user which
+   way they want:
+   - **A workflow from ${WORKFLOWS_REPO}.** Its \`default\` is a feature →
+     review → fix workflow. It is used from a checkout pinned on this
+     machine:
+
+     \`\`\`sh
+     git clone ${WORKFLOWS_REPO} ~/.local/share/gtd/workflows
+     ~/.local/share/gtd/workflows/bin/gtd-wf pin origin/main   # or a tag
+     ~/.local/share/gtd/workflows/bin/gtd-wf config default > gtd.config.ts
+     \`\`\`
+
+     \`pin\` checks the ref out and bundles each workflow; \`config\` prints a
+     config importing the bundle by its ABSOLUTE path. Tell the user what
+     that means: the committed config works only where the checkout sits at
+     that same path, so a teammate or CI needs their own checkout there (or
+     their own config). If a checkout exists already, \`gtd-wf status\`
+     shows its pin — reuse it rather than cloning again. Read the
+     repository's README for the workflows it offers and their options.
+   - **Their own workflow.** A workflow is TypeScript the config exports,
+     written against \`@pmelab/gtd/flows\` — see
+     https://github.com/pmelab/gtd/blob/main/docs/configuration.md, and
+     https://github.com/pmelab/gtd/blob/main/docs/testing.md to test it. A
+     copy of a gtd-workflows workflow (\`gtd-wf new <name> --from default\`
+     in a clone of it) is a good start.
+
+   Repository settings — steering-file modes, \`gtd ui\`, per-scope skills
+   and access — go in the config's \`config\` export; workflow settings are
+   options of the workflow factory it exports.
+3. **Commit the config before the first drive.** An uncommitted config is a
    pending change, so starting a process without committing it first turns
    the config into the very first thing the process plans against. Commit
    it, THEN start driving.
@@ -453,7 +478,8 @@ follow in the same numbered list.
    from every prompt line and writing no model exports, so every turn runs
    on the chosen CLI's own default tier.
 6. **If model hints are honored, resolve them to real model identifiers.**
-   The bundled workflow ships \`plannerModel: smart\` and \`coderModel: base\`.
+   A workflow may declare model hints — gtd-workflows' \`default\` ships
+   \`plannerModel: smart\` and \`coderModel: base\`.
    **Those are opaque hints, not model names** — gtd never interprets them,
    and passing \`--model smart\` to a real CLI fails on the first prompt
    beat. Derive the chosen CLI's own available models at install time — its
@@ -550,11 +576,8 @@ hands off to \`gtd-build\`, which halts at the blocked gate and prints it,
 rather than starting the review; \`gtd-door fix\` on a GREEN suite is a no-op
 straight back to \`idle\` — the exec'd \`gtd-build\` exits immediately on it.
 \`gtd doors\` lists the doors a repository offers (those of the workflows its
-config exports — the bundled \`fix\` and \`review [base]\`, plus the opt-in
-\`rollout <flag>\` (turn a release flag default-on) and \`cleanup <flag>\`
-(remove it), which a config adds by exporting \`rollout\` from
-\`@pmelab/gtd/workflows/rollout\` and \`cleanup\` from
-\`@pmelab/gtd/workflows/cleanup\` — plus any it declares). Refuses with
+config exports — gtd-workflows' \`default\` brings \`fix\` and
+\`review [base]\` — plus any the config declares). Refuses with
 \`usage: gtd-door <name> [args...]\` on stderr and exit \`2\` when the name is
 missing — nothing was even attempted. Default path: \`~/.local/bin/gtd-door\`.
 

package/src/install/index.ts

@@ -1,3 +1,2 @@
-export { renderBriefing } from "./Install.js"
-export { CONFIG_SCAFFOLD } from "./ConfigScaffold.js"
+export { renderBriefing, WORKFLOWS_REPO } from "./Install.js"
 export { GTD_VERSION } from "./Version.js"

package/src/replay/Replay.test.ts

@@ -175,7 +175,7 @@ const restName = (outcome: ReplayOutcome): string => {
 }
 
 // Plain loops, a counter cap, and helper-driven branches: the shape the
-// bundled workflow has.
+// workflow might have.
 const fixLoop = async () => {
   await human("idle", { file: "TODO.md" })
   for (let attempt = 1; ; attempt++) {

package/src/replay/index.ts

@@ -15,6 +15,6 @@ export {
   type CommitSpec,
   type JudgeVerdict,
 } from "./Trailers.js"
-export { accessShapeFault, foldAccess } from "./Access.js"
+export { accessShapeFault } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"

package/src/step/planStart.ts

@@ -4,6 +4,7 @@ import {
   ConfigDiscovery,
   ConfigService,
   multilineSetting,
+  ownFlagRefusal,
   resolveStartVars,
   StartFlags,
   type ConfigFingerprint,
@@ -110,7 +111,11 @@ export const planStart = (
     if (overrideRefusal !== undefined) return overrideRefusal
 
     const baseOf = workflow.def.base
-    const vars = resolveStartVars(workflow.vars, yield* StartFlags, varOverrides, (yield* Host).env)
+    const flags = yield* StartFlags
+    const hostEnv = (yield* Host).env
+    const badFlag = ownFlagRefusal(workflow.vars, flags, hostEnv)
+    if (badFlag !== undefined) return refusal(`${commandLabel}: ${badFlag}`)
+    const vars = resolveStartVars(workflow.vars, flags, varOverrides, hostEnv)
     const multiline = multilineSetting(vars)
     if (multiline !== undefined) {
       return refusal(