@pmelab/gtd 58.1.0 → 59.0.0

package/src/cli/Program.test.ts

@@ -27,8 +27,8 @@ import {
   restoredOutcome,
 } from "../emit/index.js"
 import { HISTORY_REF } from "../platform/index.js"
-import { CONFIG_SCAFFOLD } from "../install/index.js"
 import { contentHash } from "../workflow/index.js"
+import { WORKFLOWS_REPO } from "../install/index.js"
 
 const run = async (
   repo: InMemRepo,
@@ -64,15 +64,6 @@ const seed = (source: string, extra: Record<string, string> = {}): InMemRepo =>
   return repo
 }
 
-/** A repo `gtd install` set up: its config runs the shipped workflows. */
-const seedBundled = (): InMemRepo => {
-  const repo = new InMemRepo()
-  repo.writeFile("README.md", "# test project\n")
-  repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-  repo.seedCommit("chore: init")
-  return repo
-}
-
 const IDLE_THEN_WORKING = `import { agent, human } from "@pmelab/gtd/flows"
 
 export default async () => {
@@ -81,6 +72,15 @@ export default async () => {
 }
 `
 
+/** A repo at rest: its config runs {@link IDLE_THEN_WORKING}. */
+const seedIdle = (): InMemRepo => {
+  const repo = new InMemRepo()
+  repo.writeFile("README.md", "# test project\n")
+  repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
+  repo.seedCommit("chore: init")
+  return repo
+}
+
 describe("gtd --workflow <name> — a custom workflow's named workflow", () => {
   const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
 
@@ -194,9 +194,50 @@ export const defaults = { greeting: "hello" }
   })
 })
 
-describe("gtd --workflow <name> — the shipped workflows", () => {
+describe("gtd install", () => {
+  it("where no gtd.config.ts governs, prints the briefing and warns where to get a workflow — writing nothing", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("README.md", "# test project\n")
+    repo.seedCommit("chore: init")
+    const before = repo.snapshot()
+    const { stdout, stderr, exitCode } = await run(repo, "install")
+    expect(exitCode).toBe(0)
+    expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
+    expect(stderr).toContain(
+      "gtd install: no gtd.config.ts governs here, and gtd ships no workflow",
+    )
+    expect(stderr).toContain(WORKFLOWS_REPO)
+    expect(repo.hasPath("gtd.config.ts")).toBe(false)
+    expect(repo.snapshot()).toBe(before)
+  })
+
+  it("where a gtd.config.ts governs, prints the briefing alone", async () => {
+    const repo = seedIdle()
+    const { stdout, stderr, exitCode } = await run(repo, "install")
+    expect(exitCode).toBe(0)
+    expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
+    expect(stderr).not.toContain(WORKFLOWS_REPO)
+  })
+})
+
+describe("gtd --workflow <name> — a workflow that fixes its diff base", () => {
+  const WORKFLOW = `import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "hi" })
+}
+
+export const review = async () => {
+  await human("checking", { message: "check" })
+}
+
+export const defaults = { reviewBase: "" }
+
+export const base = (workflow, vars) => (workflow === "review" ? vars.reviewBase : undefined)
+`
+
   it("--workflow review --var reviewBase=<base> emits a script anchoring the process to that base", async () => {
-    const repo = seedBundled()
+    const repo = seed(WORKFLOW)
     const base = repo.commitHistory().at(-1)!.hash
     repo.writeFile("scratch.txt", "more work\n")
     repo.seedCommit("chore: more work")
@@ -209,26 +250,16 @@ describe("gtd --workflow <name> — the shipped workflows", () => {
       `reviewBase=${base}`,
     )
     expect(exitCode).toBe(0)
-    expect(stdout).toContain("gtd(human): review-gate.check")
+    expect(stdout).toContain("gtd(human): checking")
     expect(stdout).toContain("Gtd-Workflow: review")
     expect(stdout).toContain(`Gtd-Review-Base: ${base}`)
     expect(repo.commitHistory()).toHaveLength(before)
   })
-
-  it("--workflow fix emits a script that would start a fix process", async () => {
-    const repo = seedBundled()
-    const before = repo.commitHistory().length
-    const { stdout, exitCode } = await run(repo, "--workflow", "fix")
-    expect(exitCode).toBe(0)
-    expect(stdout).toContain("gtd(human): fix-precheck")
-    expect(stdout).toContain("Gtd-Workflow: fix")
-    expect(repo.commitHistory()).toHaveLength(before)
-  })
 })
 
 describe("config loading", () => {
   it('gtd next --verbose narrates "config: module" exactly once — the extra load that surfaces warnings is silent', async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const { stderr, exitCode } = await run(repo, "next", "--verbose")
     expect(exitCode).toBe(0)
     expect(stderr.match(/config: module /g)).toHaveLength(1)
@@ -287,7 +318,7 @@ describe("gtd next --json — log path emission", () => {
   const seededRepo = (): InMemRepo => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
-    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
     repo.seedCommit("gtd: init")
     return repo
   }
@@ -1752,7 +1783,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   )
 
   it("a repository with a commit passes the guard and dispatches normally", async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const written: string[] = []
     const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
 
@@ -1765,7 +1796,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   })
 
   it("gtd ui in a repository WITH commits reaches its own dispatch, past the guard", async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const out = { write: () => {}, flush: () => {} }
     const requests: unknown[] = []
     const ui = (request: unknown) => Effect.sync(() => void requests.push(request))
@@ -1950,7 +1981,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
   const seededRepo = (): InMemRepo => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
-    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
     repo.seedCommit("gtd: init")
     return repo
   }
@@ -1987,7 +2018,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
 
   it("an absent selector writes zero bytes to stdout and exits EXIT_OK", async () => {
     const repo = seededRepo()
-    // The built-in workflow's initial `idle` state declares no `mode:` —
+    // The workflow's initial `idle` step declares no `mode:` —
     // `mode` is a real, present-but-`undefined` field on the beat document
     // there (see `src/wire/BeatStatus.ts`'s `statusOf`), not merely an
     // unknown path.

package/src/cli/Program.ts

@@ -87,7 +87,7 @@ import {
   abandonNoopOutcome,
   restoredOutcome,
 } from "../emit/index.js"
-import { CONFIG_SCAFFOLD, renderBriefing } from "../install/index.js"
+import { renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
 import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
 import {
   SelectorUsageError,
@@ -207,13 +207,12 @@ const runLspCommand = (): Effect.Effect<void, Error, ToolCommands> =>
 
 /**
  * Prints the briefing, emitted by the binary itself so it's always current.
- * At a repository root no `gtd.config.ts` governs yet, it also writes one
- * importing gtd's shipped workflows, left uncommitted.
- * Anywhere else it writes nothing.
+ * gtd ships no workflow, so where no `gtd.config.ts` governs it says where to
+ * get one; it writes nothing.
  */
 const runInstallCommand = (
   out: ArtifactOut,
-): Effect.Effect<void, Error, GitService | Workspace | Host | ConfigDiscovery | Narrator> =>
+): Effect.Effect<void, Error, GitService | Host | ConfigDiscovery | Narrator> =>
   Effect.gen(function* () {
     const briefing = renderBriefing()
     out.write(briefing.endsWith("\n") ? briefing : briefing + "\n")
@@ -222,9 +221,8 @@ const runInstallCommand = (
     if (topLevel._tag === "Left") return
     if ((yield* host.realPath(topLevel.right)) !== (yield* host.realPath(host.root))) return
     if ((yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)) !== undefined) return
-    yield* (yield* Workspace).write(WORKFLOW_MODULE, CONFIG_SCAFFOLD)
     yield* (yield* Narrator).warn(
-      `gtd install: wrote ${WORKFLOW_MODULE}, importing gtd's shipped workflows — commit it before your first \`gtd land\``,
+      `gtd install: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`,
     )
   })
 

package/src/edge/Edge.ts

@@ -1476,12 +1476,12 @@ const historySteps = (run: ProcessRun): readonly HistoryStep[] => {
 const versionWarningFor = (recorded: string | undefined): string | undefined =>
   recorded === GTD_VERSION
     ? undefined
-    : `gtd: warning: this history was recorded by ${recorded === undefined ? "an unknown gtd version" : `gtd ${recorded}`} and is replayed by gtd ${GTD_VERSION} — a workflow imported from @pmelab/gtd/workflows may have changed since`
+    : `gtd: warning: this history was recorded by ${recorded === undefined ? "an unknown gtd version" : `gtd ${recorded}`} and is replayed by gtd ${GTD_VERSION} — the engine the workflow runs on may have changed since`
 
 /**
  * Replays the closed run at `tip` under today's config. The workflow is not
- * fingerprinted for a version change: one imported from `@pmelab/gtd/workflows`
- * moves with every upgrade, and the version warning is the only signal.
+ * fingerprinted for a version change: the engine under it moves with every
+ * upgrade, and the version warning is the only signal.
  */
 export const historyTrail = (tip: string): Effect.Effect<HistoryTrail, Error, RestRequirements> =>
   Effect.gen(function* () {

package/src/flags/index.test.ts

@@ -102,16 +102,3 @@ describe("flagSettings", () => {
     })
   })
 })
-
-describe("risk_tier", () => {
-  it("is a release flag, off by default, resolved from GTD_FLAG_RISK_TIER", () => {
-    expect(FLAGS.find((f) => f.name === "risk_tier")).toMatchObject({ kind: "release" })
-    expect(resolveFlags({}).risk_tier).toBe(false)
-    expect(resolveFlags({ GTD_FLAG_RISK_TIER: "1" }).risk_tier).toBe(true)
-  })
-
-  it("is pinned as flag_risk_tier", () => {
-    expect(flagSettings(resolveFlags({ GTD_FLAG_RISK_TIER: "1" })).flag_risk_tier).toBe("1")
-    expect(flagSettings(resolveFlags({})).flag_risk_tier).toBe("0")
-  })
-})

package/src/flags/index.ts

@@ -13,9 +13,7 @@ export interface FlagDeclaration {
   readonly defaultOn?: boolean
 }
 
-export const FLAGS = [
-  { name: "risk_tier", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
-] as const satisfies readonly FlagDeclaration[]
+export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */
 export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {

package/src/gherkin/git-control.feature

@@ -0,0 +1,78 @@
+@inmem
+Feature: a scenario controls the commands and the history a workflow sees
+
+  A step's script may run programs the in-memory repository has none of: a
+  canned command stands in for each, matched by the command as the script
+  spells it. Branches and refs are set up before the process starts, so a
+  workflow that reads another branch or a remote ref finds them.
+
+  Background:
+    Given a gtd config with:
+      """
+      import { check, human, run, showScript } from "@pmelab/gtd/flows"
+
+      export const tested = async () => {
+        const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+        await human(green ? "sign-off" : "red")
+      }
+
+      export const restored = async () => {
+        await run("restore", showScript("origin/main", "a.txt", "a.txt"))
+        await human("done")
+      }
+
+      export default tested
+      """
+    And a file "a.txt" with:
+      """
+      base
+      """
+    And the working tree is committed as "chore: base"
+
+  Scenario: a red canned command writes its output to the check's report
+    Given the command "npm test" exits 1 with:
+      """
+      1 failing
+      """
+    And step "test" runs its script
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "red"
+    And ".gtd/FEEDBACK.md" contains "1 failing"
+
+  Scenario: a green canned command passes the check
+    Given the command "npm test" exits 0
+    And step "test" runs its script
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "sign-off"
+
+  Scenario: a command no canned command matches fails the drive, naming it
+    Given step "test" runs its script
+    When gtd starts workflow "tested"
+    Then driving the process is refused with "no canned command matches `npm test`"
+
+  Scenario: a remote ref is read by its short name
+    Given the ref "refs/remotes/origin/main" points at HEAD
+    And a file "a.txt" with:
+      """
+      local
+      """
+    And the working tree is committed as "chore: local"
+    And step "restore" runs its script
+    When gtd starts workflow "restored"
+    And the process is driven
+    Then the process rests at "done"
+    And "a.txt" contains "base"
+
+  Scenario: a branch is checked out and back
+    Given a branch "feature/x"
+    And "feature/x" is checked out
+    And a file "a.txt" with:
+      """
+      feature
+      """
+    And the working tree is committed as "feat: x"
+    And "main" is checked out
+    Then "a.txt" contains "base"
+    And "a.txt" does not contain "feature"

package/src/gherkin/index.ts

@@ -17,6 +17,7 @@ import {
   runsItsScript,
   testRepo,
   type Actor,
+  type CannedCommand,
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
@@ -31,6 +32,7 @@ export class TestkitWorld extends QuickPickleWorld {
 
   private gtdConfig: WorkflowModule | undefined = undefined
   private env: Record<string, string> = {}
+  private commands: CannedCommand[] = []
   /** Per step, what its scripted actor does, in the order the scenario declared it. */
   actions = new Map<string, Actor[]>()
   verdicts = new Map<string, string>()
@@ -54,6 +56,11 @@ export class TestkitWorld extends QuickPickleWorld {
     this.gtdConfig += `\n${tail}`
   }
 
+  command(command: CannedCommand): void {
+    if (this.created === undefined) this.commands.push(command)
+    else this.created.command(command)
+  }
+
   setEnv(name: string, value: string): void {
     this.assertNotCreated(`the environment variable ${name}`)
     this.env[name] = value
@@ -68,7 +75,11 @@ export class TestkitWorld extends QuickPickleWorld {
   repo(): TestRepo {
     if (this.gtdConfig === undefined)
       throw new Error("no gtd config: add a `gtd config` step first")
-    return (this.created ??= testRepo({ workflow: this.gtdConfig, env: this.env }))
+    return (this.created ??= testRepo({
+      workflow: this.gtdConfig,
+      env: this.env,
+      commands: this.commands,
+    }))
   }
 
   act(step: string, action: Actor): void {
@@ -136,6 +147,29 @@ Given(
   },
 )
 
+Given("the command {string} exits {int}", (world: TestkitWorld, run: string, exit: number) => {
+  world.command({ run, exit })
+})
+
+Given(
+  "the command {string} exits {int} with:",
+  (world: TestkitWorld, run: string, exit: number, output: string) => {
+    world.command({ run, exit, output: withNewline(output) })
+  },
+)
+
+Given("a branch {string}", (world: TestkitWorld, name: string) => {
+  world.repo().branch(name)
+})
+
+Given("{string} is checked out", (world: TestkitWorld, name: string) => {
+  world.repo().checkout(name)
+})
+
+Given("the ref {string} points at HEAD", (world: TestkitWorld, name: string) => {
+  world.repo().ref(name)
+})
+
 Given("a file {string} with:", (world: TestkitWorld, path: string, content: string) => {
   world.repo().write(path, withNewline(content))
 })

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(