@pmelab/gtd 21.1.0 → 23.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "21.1.0",
+  "version": "23.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -25,7 +25,6 @@
     "src/workflows/",
     "README.md",
     "LICENSE",
-    "schema.json",
     ".claude-plugin/plugin.json",
     "hooks/",
     "bin/",
@@ -52,7 +51,7 @@
     "prepare": "husky",
     "dev": "node dev/run.mjs",
     "build": "tsdown --filter web && npx @tailwindcss/cli -i src/web/styles.css -o dist/web/main.css --minify && node scripts/inline-web-client.mjs && tsdown --filter gtd && tsdown --filter workflows",
-    "postbuild": "jiti scripts/generate-schema.ts && node scripts/assert-no-test-doubles.mjs",
+    "postbuild": "node scripts/assert-no-test-doubles.mjs",
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
     "test": "turbo run format:check typecheck lint lint:sh lint:boundaries test:unit test:e2e:inmem test:e2e:live test:web analyze",
@@ -126,6 +125,7 @@
     "tsdown": "^0.22.8",
     "turbo": "^2.10.9",
     "vitest": "^3.2.0",
+    "yaml": "^2.8.2",
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
@@ -134,6 +134,7 @@
   "dependencies": {
     "@effect/platform": "^0.94.2",
     "@effect/platform-node": "^0.104.1",
+    "@standard-schema/spec": "^1.1.0",
     "@trpc/server": "^11.18.0",
     "effect": "^3.19.15",
     "jiti": "^2.7.0",
@@ -147,7 +148,6 @@
     "micromark-extension-gfm-strikethrough": "^2.1.0",
     "micromark-extension-gfm-task-list-item": "^2.1.0",
     "vscode-languageserver": "^10.1.0",
-    "vscode-languageserver-textdocument": "^1.0.13",
-    "yaml": "^2.8.2"
+    "vscode-languageserver-textdocument": "^1.0.13"
   }
 }

package/skills/authoring/SKILL.md

@@ -109,7 +109,7 @@ workflow that fails to load breaks every gtd command in the repository.
   step you add must fit one of them; there is no sixth.
 
 Options (all optional): `label`, `file` (a `.gtd/` path), `mode` (needs `file`;
-`qa`, `review`, or a `.gtdrc` `modes:` name), `message` (human/judge), `model`,
+`qa`, `review`, or a `config.modes` name), `message` (human/judge), `model`,
 `system` (agent), `allowEmpty` (agent), `acceptClean` (human), `base` (the
 commit the step reviews since — what `gtd base` prints).
 
@@ -150,7 +150,7 @@ the pending landing — call it right after the step whose turn you reject.
   `export const base = (workflow, vars) => commitish | undefined` fixes a
   started process's diff base (blank = default-branch merge-base).
   `--var <name>=<value>` only pins process settings: names the workflow's
-  `defaults` or `.gtdrc` `vars:` declare — never an environment setting.
+  `defaults` declare — never an environment setting.
 
 ## Landing rules you are designing for
 

package/src/flows/config.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest"
+import { configProblems, defineConfig } from "./config.js"
+
+describe("defineConfig", () => {
+  it("returns a valid config as given", () => {
+    const config = {
+      modes: { qa: { format: "fmt" }, adr: { validate: "check" } },
+      ui: { port: 8443, format: "fmt" },
+      skills: { "feature.plan": ["tdd"] },
+      access: { "feature.plan": { write: [".gtd/**"] } },
+    }
+    expect(defineConfig(config)).toBe(config)
+  })
+
+  it("rejects a removed key at type level and at runtime", () => {
+    // @ts-expect-error -- `vars` is no `gtd.config.ts` setting
+    expect(() => defineConfig({ vars: { testCommand: "npm test" } })).toThrow(
+      "config.vars: is not a known key",
+    )
+  })
+
+  it("rejects an unknown nested key at type level and at runtime", () => {
+    // @ts-expect-error -- a mode has only format and validate
+    expect(() => defineConfig({ modes: { qa: { formatter: "fmt" } } })).toThrow(
+      "config.modes.qa.formatter: is not a known key",
+    )
+  })
+})
+
+describe("configProblems", () => {
+  it("finds every malformed value", () => {
+    expect(
+      configProblems({
+        modes: { empty: {}, scalar: "fmt", blank: { format: " " } },
+        ui: { port: "80", host: 1 },
+        skills: { a: "tdd" },
+        access: { a: { read: "*", other: [] } },
+      }),
+    ).toEqual([
+      { path: ["modes", "scalar"], message: 'must be an object with "format" and/or "validate"' },
+      { path: ["modes", "blank", "format"], message: "must be a non-empty shell command" },
+      { path: ["ui", "port"], message: "must be an integer" },
+      { path: ["ui", "host"], message: "must be a string" },
+      { path: ["skills", "a"], message: "must be an array of skill names" },
+      { path: ["access", "a", "other"], message: "is not a known key" },
+      { path: ["access", "a", "read"], message: "must be an array of glob strings" },
+    ])
+  })
+
+  it("rejects a container of the wrong shape", () => {
+    expect(configProblems({ modes: { "": {} }, skills: [], ui: "x", access: { a: "x" } })).toEqual([
+      { path: ["modes", ""], message: "is a mode without a name" },
+      { path: ["ui"], message: "must be an object" },
+      { path: ["skills"], message: "must be an object of skill-name arrays" },
+      { path: ["access", "a"], message: "must be an object of { read?, write? } glob arrays" },
+    ])
+    expect(configProblems({ modes: "x", access: [] })).toEqual([
+      { path: ["modes"], message: "must be an object of modes" },
+      { path: ["access"], message: "must be an object of scope access" },
+    ])
+  })
+
+  it("rejects a config that is no object", () => {
+    expect(configProblems([])).toEqual([{ path: [], message: "must be an object" }])
+  })
+})

package/src/flows/config.ts

@@ -0,0 +1,141 @@
+import type { ScopeAccess } from "./runtime.js"
+
+/** One steering-file mode's shell commands; each reads the file from `$GTD_FILE`. */
+export interface ModeCommands {
+  readonly format?: string
+  readonly validate?: string
+}
+
+/** `gtd ui` settings; its `--host`/`--port` flags outrank `host`/`port`. */
+export interface UiSettings {
+  readonly port?: number
+  readonly host?: string
+  readonly cert?: string
+  readonly key?: string
+  readonly format?: string
+}
+
+/** The repository settings a `gtd.config.ts` exports as `config`. */
+export interface GtdConfig {
+  readonly modes?: Readonly<Record<string, ModeCommands>>
+  readonly ui?: UiSettings
+  readonly skills?: Readonly<Record<string, readonly string[]>>
+  readonly access?: Readonly<Record<string, ScopeAccess>>
+}
+
+export interface ConfigProblem {
+  readonly path: readonly string[]
+  readonly message: string
+}
+
+const CONFIG_KEYS = ["modes", "ui", "skills", "access"] as const
+const MODE_KEYS = ["format", "validate"] as const
+const UI_KEYS = ["port", "host", "cert", "key", "format"] as const
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v)
+
+const isStringArray = (v: unknown): boolean =>
+  Array.isArray(v) && v.every((entry) => typeof entry === "string")
+
+const unknownKeys = (
+  value: Record<string, unknown>,
+  known: readonly string[],
+  path: readonly string[],
+): ConfigProblem[] =>
+  Object.keys(value)
+    .filter((key) => !known.includes(key))
+    .map((key) => ({ path: [...path, key], message: "is not a known key" }))
+
+const recordOf = (
+  value: unknown,
+  path: readonly string[],
+  shape: string,
+  entry: (value: unknown, path: readonly string[]) => ConfigProblem[],
+): ConfigProblem[] =>
+  isRecord(value)
+    ? Object.entries(value).flatMap(([key, v]) => entry(v, [...path, key]))
+    : [{ path, message: `must be an object of ${shape}` }]
+
+const modeProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (path.at(-1) === "") return [{ path, message: "is a mode without a name" }]
+  // An empty mode still registers its name: a step may use it, unformatted and unvalidated.
+  if (!isRecord(value))
+    return [{ path, message: 'must be an object with "format" and/or "validate"' }]
+  return [
+    ...unknownKeys(value, MODE_KEYS, path),
+    ...MODE_KEYS.flatMap((key) => {
+      const command = value[key]
+      return command === undefined || (typeof command === "string" && command.trim() !== "")
+        ? []
+        : [{ path: [...path, key], message: "must be a non-empty shell command" }]
+    }),
+  ]
+}
+
+const uiProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (!isRecord(value)) return [{ path, message: "must be an object" }]
+  return [
+    ...unknownKeys(value, UI_KEYS, path),
+    ...UI_KEYS.flatMap((key) => {
+      const v = value[key]
+      if (v === undefined) return []
+      const ok = key === "port" ? Number.isInteger(v) : typeof v === "string"
+      return ok
+        ? []
+        : [
+            {
+              path: [...path, key],
+              message: key === "port" ? "must be an integer" : "must be a string",
+            },
+          ]
+    }),
+  ]
+}
+
+const accessProblems = (value: unknown, path: readonly string[]): ConfigProblem[] => {
+  if (!isRecord(value))
+    return [{ path, message: "must be an object of { read?, write? } glob arrays" }]
+  return [
+    ...unknownKeys(value, ["read", "write"], path),
+    ...(["read", "write"] as const).flatMap((side) =>
+      value[side] === undefined || isStringArray(value[side])
+        ? []
+        : [{ path: [...path, side], message: "must be an array of glob strings" }],
+    ),
+  ]
+}
+
+/** Every way `value` is not a `GtdConfig`; an unknown key is one, so a removed key fails loudly. */
+export const configProblems = (value: unknown): readonly ConfigProblem[] => {
+  if (!isRecord(value)) return [{ path: [], message: "must be an object" }]
+  return [
+    ...unknownKeys(value, CONFIG_KEYS, []),
+    ...(value.modes === undefined ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems)),
+    ...(value.ui === undefined ? [] : uiProblems(value.ui, ["ui"])),
+    ...(value.skills === undefined
+      ? []
+      : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) =>
+          isStringArray(v) ? [] : [{ path, message: "must be an array of skill names" }],
+        )),
+    ...(value.access === undefined
+      ? []
+      : recordOf(value.access, ["access"], "scope access", accessProblems)),
+  ]
+}
+
+// The loader's diagnostic format, so a problem reads the same whether
+// `defineConfig` throws it or the loader finds it in a plain object.
+const formatConfigProblem = ({ path, message }: ConfigProblem): string =>
+  `${["config", ...path].join(".")}: ${message}`
+
+/**
+ * Type and check the `config` export. Not generic on purpose: a literal argument
+ * then gets TypeScript's excess-property check at every depth, so an unknown key
+ * is a type error — and it throws at runtime too.
+ */
+export const defineConfig = (config: GtdConfig): GtdConfig => {
+  const problems = configProblems(config)
+  if (problems.length > 0) throw new Error(problems.map(formatConfigProblem).join("; "))
+  return config
+}

package/src/flows/factory.test.ts

@@ -0,0 +1,94 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { describe, expect, it } from "vitest"
+import { configure, defineWorkflow, isFactoryWorkflow } from "./factory.js"
+
+// A hand-written Standard Schema: `{ greeting?: string }`, unknown keys rejected.
+const greetingSchema: StandardSchemaV1<{ greeting?: string }> = {
+  "~standard": {
+    version: 1,
+    vendor: "test",
+    validate: (value) => {
+      const issues: StandardSchemaV1.Issue[] = []
+      for (const [key, v] of Object.entries(value as object)) {
+        if (key !== "greeting") issues.push({ message: "is unexpected", path: [key] })
+        else if (typeof v !== "string") issues.push({ message: "Expected string", path: [{ key }] })
+      }
+      return issues.length > 0 ? { issues } : { value: value as { greeting?: string } }
+    },
+  },
+}
+
+const flow = async (): Promise<void> => {}
+const greeter = defineWorkflow(greetingSchema, (options) => ({
+  flow,
+  defaults: { greeting: options.greeting ?? "hello" },
+}))
+
+describe("defineWorkflow", () => {
+  it("marks the factory and a call's result as factory workflows, a plain flow not", () => {
+    expect(isFactoryWorkflow(greeter)).toBe(true)
+    expect(isFactoryWorkflow(greeter({ greeting: "hi" }))).toBe(true)
+    expect(isFactoryWorkflow(flow)).toBe(false)
+    expect(configure(flow)).toBeUndefined()
+  })
+
+  it("builds the factory itself with no options", () => {
+    expect(configure(greeter)).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hello" } },
+    })
+  })
+
+  it("builds a call's result from the options it was called with", () => {
+    expect(configure(greeter({ greeting: "hi" }))).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hi" } },
+    })
+  })
+
+  it("lays overrides over the options a call was given", () => {
+    expect(configure(greeter({ greeting: "hi" }), { greeting: "hey" })).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hey" } },
+    })
+  })
+
+  it("reports every issue with its key path, path segments flattened", () => {
+    const bad = greeter({ greeting: 1 } as never)
+    expect(configure(bad, { greting: "x" })).toEqual({
+      ok: false,
+      issues: [
+        { path: ["greeting"], message: "Expected string" },
+        { path: ["greting"], message: "is unexpected" },
+      ],
+    })
+  })
+
+  it("refuses a schema that validates asynchronously", () => {
+    const asyncSchema: StandardSchemaV1<object> = {
+      "~standard": {
+        version: 1,
+        vendor: "test",
+        validate: async (value) => ({ value: value as object }),
+      },
+    }
+    const result = configure(defineWorkflow(asyncSchema, () => ({ flow })))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: [] }] })
+  })
+
+  it("treats a schema failing with no issues as a rejection", () => {
+    const empty: StandardSchemaV1<object> = {
+      "~standard": { version: 1, vendor: "test", validate: () => ({ issues: [] }) },
+    }
+    expect(configure(defineWorkflow(empty, () => ({ flow })))).toMatchObject({
+      ok: false,
+      issues: [{ path: [] }],
+    })
+  })
+
+  it("throws when a call's result is awaited as if it were a flow", async () => {
+    await expect(Promise.resolve(greeter() as unknown as PromiseLike<void>)).rejects.toThrow(
+      /not a flow/,
+    )
+  })
+})

package/src/flows/factory.ts

@@ -0,0 +1,116 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { Flow } from "./runtime.js"
+
+// Registered, so a factory made by any copy of this file is recognised by the
+// engine's copy — the same reason the replay context is.
+const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory")
+
+export interface WorkflowBuild {
+  readonly flow: Flow
+  /** Process settings this workflow declares, over its file's `defaults` export. */
+  readonly defaults?: Readonly<Record<string, string>> | undefined
+  /** Environment settings this workflow declares, over its file's `envDefaults` export. */
+  readonly envDefaults?: Readonly<Record<string, string>> | undefined
+}
+
+interface FactoryInternals {
+  readonly schema: StandardSchemaV1
+  readonly build: (options: never) => WorkflowBuild
+}
+
+/**
+ * A factory call's result. Nothing is validated yet: gtd validates the options
+ * when it loads the config, so a bad one is reported like any other config
+ * finding instead of throwing out of `gtd.config.ts`.
+ */
+export interface ConfiguredWorkflow {
+  readonly [FACTORY]: FactoryInternals & { readonly options: unknown }
+  readonly then: () => never
+}
+
+export type WorkflowFactory<Options> = ({} extends Options
+  ? (options?: Options) => ConfiguredWorkflow
+  : (options: Options) => ConfiguredWorkflow) & { readonly [FACTORY]: FactoryInternals }
+
+/**
+ * Define a workflow configured by options. `schema` is any Standard Schema
+ * (https://standardschema.dev); it should reject unknown keys, so a removed or
+ * misspelled option fails at load. Exported from `gtd.config.ts`, the factory
+ * itself and a call's result are both workflows.
+ */
+export const defineWorkflow = <S extends StandardSchemaV1>(
+  schema: S,
+  build: (options: StandardSchemaV1.InferOutput<S>) => WorkflowBuild,
+): WorkflowFactory<StandardSchemaV1.InferInput<S>> => {
+  const internals: FactoryInternals = { schema, build }
+  const factory = (options?: unknown): ConfiguredWorkflow => ({
+    [FACTORY]: { ...internals, options },
+    // 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")
+    },
+  })
+  return Object.assign(factory, { [FACTORY]: internals }) as never
+}
+
+export interface OptionIssue {
+  readonly path: readonly (string | number)[]
+  readonly message: string
+}
+
+export type Configured =
+  | { readonly ok: true; readonly build: WorkflowBuild }
+  | { readonly ok: false; readonly issues: readonly OptionIssue[] }
+
+const internalsOf = (
+  value: unknown,
+): (FactoryInternals & { readonly options?: unknown }) | undefined =>
+  (typeof value === "function" || (typeof value === "object" && value !== null)) && FACTORY in value
+    ? (value as { readonly [FACTORY]: FactoryInternals & { readonly options?: unknown } })[FACTORY]
+    : undefined
+
+export const isFactoryWorkflow = (value: unknown): boolean => internalsOf(value) !== undefined
+
+const segment = (key: PropertyKey | StandardSchemaV1.PathSegment): string | number => {
+  const raw = typeof key === "object" ? key.key : key
+  return typeof raw === "number" ? raw : String(raw)
+}
+
+/**
+ * Validate a factory workflow's options — those it was called with, `overrides`
+ * on top — and build it. `undefined` for an export that is no factory workflow.
+ */
+export const configure = (
+  value: unknown,
+  overrides: Readonly<Record<string, unknown>> = {},
+): Configured | undefined => {
+  const internals = internalsOf(value)
+  if (internals === undefined) return undefined
+  const options = { ...(internals.options as object), ...overrides }
+  const result = internals.schema["~standard"].validate(options)
+  if (result instanceof Promise) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [],
+          message: "the options schema validates asynchronously — gtd needs a synchronous one",
+        },
+      ],
+    }
+  }
+  if (result.issues !== undefined) {
+    return {
+      ok: false,
+      issues:
+        result.issues.length === 0
+          ? [{ path: [], message: "the options schema rejected them without saying why" }]
+          : result.issues.map((issue) => ({
+              path: (issue.path ?? []).map(segment),
+              message: issue.message,
+            })),
+    }
+  }
+  return { ok: true, build: internals.build(result.value as never) }
+}

package/src/flows/index.ts

@@ -1,3 +1,5 @@
 export * from "./runtime.js"
 export * from "./helpers.js"
 export * from "./scripts.js"
+export * from "./factory.js"
+export * from "./config.js"

package/src/workflows/access.ts

@@ -2,7 +2,7 @@ import type { ScopeAccess } from "../flows/index.js"
 import { lensesOf } from "./review.js"
 
 // The bundled workflow's default file access, keyed by scope full name — the
-// name a `.gtdrc` `access:` entry addresses. Only planning and review scopes
+// 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
 // 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.

package/src/workflows/bundled.ts

@@ -17,6 +17,7 @@ import { architecture, design } from "./planning.js"
 import type { FrozenScenarios } from "./scenarios.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
 import { ARCHITECTURE, FEEDBACK, REQUIREMENTS, REVIEW } from "./steps.js"
+import { shipped } from "./options.js"
 import * as t from "./text.js"
 
 // gtd's bundled workflows. Any change to the tree starts a process:
@@ -25,13 +26,15 @@ import * as t from "./text.js"
 // the quality lap → human review, which signs off (the episode ends back at
 // `idle`) or sends a full re-plan lap. `feature` is that ordinary start;
 // `gtd --workflow fix` and `gtd --workflow review --var reviewBase=<commitish>`
-// enter the same build tail further in.
+// enter the same build tail further in. Each of the three is a factory over
+// the settings in `./vars.ts`; its flow is exported too, for composing.
 //
 // Every part is exported for other workflows to compose; see the modules
 // re-exported below.
 
 export { threads, type ThreadInfo } from "../flows/index.js"
 export { defaults, envDefaults } from "./vars.js"
+export { ShippedOptions } from "./options.js"
 export { skills } from "./skills.js"
 export { access } from "./access.js"
 export { agentWithSkills } from "./text.js"
@@ -107,18 +110,20 @@ export const ordinaryStart = async (): Promise<void> => {
 }
 
 /** Repair a red baseline through the build tail, as its own reviewed commit. */
-export const fix = async (): Promise<void> => {
+export const fixFlow = async (): Promise<void> => {
   if (await baseline("fix-precheck")) return
   return afterTail(await buildTail(true, start()))
 }
 
 /** Pure review of everything since `reviewBase`. */
-export const review = async (): Promise<void> => {
+export const reviewFlow = async (): Promise<void> => {
   await gate("review-gate", t.reviewGateBlockedMessage())
   return afterTail(await buildTail(false, start()))
 }
 
-export const feature = ordinaryStart
+export const feature = shipped(ordinaryStart)
+export const fix = shipped(fixFlow)
+export const review = shipped(reviewFlow)
 
 export default feature
 

package/src/workflows/health.ts

@@ -19,7 +19,7 @@ import * as t from "./text.js"
 export const SETUP = ".gtd/SETUP.md"
 
 const SETUP_TEXT =
-  "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it under `env:` in `.gtdrc` or as GTD_FASTTESTCOMMAND."
+  "The bundled workflow needs the `fastTestCommand` setting: the fast suite (everything but e2e).\nSet it as a workflow option in `gtd.config.ts` or as GTD_FASTTESTCOMMAND."
 
 /** Shell lines for a check's preamble: unset (blank after trim) setting writes `SETUP` and skips the suite. */
 export const fastSuiteGuard = (): string[] =>

package/src/workflows/options.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest"
+import { configure } from "../flows/index.js"
+import * as workflows from "./index.js"
+
+const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflows
+
+describe("the shipped workflow factories", () => {
+  it("take exactly the settings the shipped workflows declare as options", () => {
+    expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
+      [...Object.keys(defaults), ...Object.keys(envDefaults)].sort(),
+    )
+  })
+
+  it("lay each option over the shipped setting of its own kind", () => {
+    const result = configure(feature({ qualityReviews: "correctness", testCommand: "npm run ci" }))
+    expect(result).toMatchObject({
+      ok: true,
+      build: {
+        defaults: { ...defaults, qualityReviews: "correctness" },
+        envDefaults: { ...envDefaults, testCommand: "npm run ci" },
+      },
+    })
+  })
+
+  it("build the shipped settings unchanged with no options", () => {
+    for (const factory of [feature, fix, review]) {
+      expect(configure(factory)).toMatchObject({ ok: true, build: { defaults, envDefaults } })
+    }
+  })
+
+  it("reject a misspelled option, at the type level and at load, naming the known ones", () => {
+    // @ts-expect-error — `testComand` is no option
+    const configured = feature({ testComand: "npm test" })
+    const result = configure(configured)
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["testComand"] }] })
+    expect(result?.ok === false && result.issues[0]?.message).toMatch(
+      /^is unexpected, expected: .*"testCommand"/,
+    )
+  })
+
+  it("reject a removed option at the type level and at load", () => {
+    // @ts-expect-error — `model` was never (or is no longer) an option
+    const result = configure(review({ model: "smart" }))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["model"] }] })
+  })
+
+  it("reject a value of the wrong type at the type level and at load", () => {
+    // @ts-expect-error — settings are strings
+    const result = configure(fix({ judgeBudgetBytes: 65536 }))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["judgeBudgetBytes"] }] })
+  })
+})

package/src/workflows/options.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect"
+import { defineWorkflow, type Flow, type WorkflowFactory } from "../flows/index.js"
+import { defaults, envDefaults } from "./vars.js"
+
+const setting = Schema.optionalWith(Schema.String, { exact: true })
+
+export const ShippedOptions = Schema.Struct({
+  reviewBase: setting,
+  judgeBudgetBytes: setting,
+  judgeIdenticalMinP: setting,
+  reviewNoteActionable: setting,
+  qualityReviews: setting,
+  testCommand: setting,
+  fastTestCommand: setting,
+  plannerModel: setting,
+  coderModel: setting,
+})
+
+export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
+
+const over = (
+  base: Readonly<Record<string, string>>,
+  options: Readonly<Record<string, string>>,
+): Record<string, string> => ({
+  ...base,
+  ...Object.fromEntries(Object.entries(options).filter(([name]) => Object.hasOwn(base, name))),
+})
+
+/** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
+export const shipped = (flow: Flow): WorkflowFactory<ShippedOptions> =>
+  defineWorkflow(
+    Schema.standardSchemaV1(ShippedOptions, { onExcessProperty: "error", errors: "all" }),
+    (options) => ({
+      flow,
+      defaults: over(defaults, options),
+      envDefaults: over(envDefaults, options),
+    }),
+  )

package/src/workflows/skills.ts

@@ -2,7 +2,7 @@ import { builtInLenses } from "./steps.js"
 import { lensesOf } from "./review.js"
 
 // The bundled workflow's default skills, one list per SCOPE, keyed by the
-// scope's full name — the same name a `.gtdrc` `skills:` entry addresses. A
+// scope's full name — the same name a `config.skills` entry addresses. A
 // nested scope with no entry inherits its parent's; group scopes
 // (`packages.item.fix`, `build.fix`, `build.review.fix`, `build.quality`) run
 // no turn and carry no key. `build.quality.<lens>` is one key per