@pmelab/gtd 59.0.0 → 60.0.0

package/src/workflow/load.ts

@@ -4,10 +4,12 @@ import { dirname, join } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import { Context, Effect, Layer } from "effect"
 import { GtdError, Narrator } from "../platform/index.js"
-import { replay, type TreeView } from "../replay/index.js"
+import { accessShapeFault, replay, type TreeView } from "../replay/index.js"
+// The published facade: what a config's `@pmelab/gtd/flows` import is served.
 import * as flows from "../flows/index.js"
+import { configure, isFactoryWorkflow, markedOptions, type OptionIssue } from "../flows/internal.js"
 import type { StateMode, WorkflowDefinition } from "./Workflow.js"
-import type { Door, Flow } from "../flows/index.js"
+import type { Door, Flow, ScopeAccess } from "../flows/index.js"
 import { Host, Workspace, type WorkspaceOps } from "../platform/index.js"
 import { compileConfig, type CompiledConfig } from "./compile.js"
 import { SETTING_NAME_RULE, isSettingName } from "./vars.js"
@@ -33,10 +35,10 @@ export interface ConfigOperations {
   readonly workflow: WorkflowDefinition
   /** The default, resolved like a named one; its name is what status shows: the named export it also is, else `"default"`. */
   readonly defaultWorkflow: ResolvedWorkflow
-  /** Every name `gtd --workflow` accepts, sorted — never `"default"`. */
+  /** Every workflow name `gtd start` accepts, sorted — never `"default"`. */
   readonly workflowNames: readonly string[]
   readonly workflowNamed: (name: string) => ResolvedWorkflow | undefined
-  /** Every door `gtd door` accepts. A door's `workflow` resolves through `workflowNamed`. */
+  /** Every door `gtd start` accepts. A door's `workflow` resolves through `workflowNamed`. */
   readonly doors: ReadonlyMap<string, Door>
   /** `config.ui` (absent when unconfigured) — `gtd ui` and its CLI flags read it. */
   readonly ui?: flows.UiSettings
@@ -50,7 +52,7 @@ export interface ConfigOperations {
 // prints `message` verbatim and would print a duplicated `detail` twice.
 const configError = (diagnostics: readonly Diagnostic[]): GtdError =>
   new GtdError(
-    `gtd config:\n${diagnostics
+    `gtd: config:\n${diagnostics
       .filter((d) => d.severity === "error")
       .map((d) => `  - ${formatDiagnostic(d)}`)
       .join("\n")}`,
@@ -84,11 +86,11 @@ export const refuseLegacyRc: Effect.Effect<void, GtdError, Host | ConfigDiscover
     return yield* Effect.fail(
       new GtdError(
         [
-          "gtd config:",
+          "gtd: config:",
           ...found.map((file) => `  - ${file}: no longer read — delete it`),
           "  gtd 23 removed the .gtdrc files; move each key they set:",
-          "    vars    → an option of the workflow factory in gtd.config.ts, or its `defaults` export",
-          "    env     → an option of the workflow factory in gtd.config.ts, or its `envDefaults` export",
+          "    vars    → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { defaults })`",
+          "    env     → an option of the workflow factory in gtd.config.ts, or `workflow(flow, { envDefaults })`",
           "    judge   → ~/.config/gtd/judge.json, or GTD_JUDGE_PROVIDER / GTD_JUDGE_MODEL",
           "    modes, ui, skills, access → the `config` export of gtd.config.ts (`defineConfig`)",
           "    $schema → nothing; drop it",
@@ -115,7 +117,7 @@ export const load: Effect.Effect<
     const missing: Diagnostic = {
       severity: "error",
       path: [],
-      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd install\` says where to get one`,
+      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd guide\` says where to get one`,
       origin: host.root,
     }
     return yield* Effect.fail(configError([missing]))
@@ -129,7 +131,7 @@ export const load: Effect.Effect<
     try: () => loadWorkflows(module, shipped),
     catch: (e) =>
       new GtdError(
-        `gtd config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
+        `gtd: config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
       ),
   })
   const compiled = loaded.config
@@ -142,17 +144,15 @@ export const load: Effect.Effect<
   }
 
   const initial = yield* firstStep(loaded.default, headTree(yield* Workspace))
-  const steering = loaded.file.steering as Record<string, StateMode>
   const define = (entry: LoadedWorkflow): WorkflowDefinition => ({
     flow: entry.flow,
-    summary: entry.file.summary,
-    // A config's own `base` export wins when it answers; else the factory's.
-    base: (w, v) => entry.file.base?.(w, v) ?? entry.base?.(w, v),
-    steering,
+    summary: entry.summary,
+    base: (w, v) => entry.base?.(w, v),
+    steering: entry.steering as Record<string, StateMode>,
     modes: compiled.modes,
-    skills: entry.file.skills,
+    skills: entry.skills,
     configuredSkills: compiled.skills,
-    access: entry.file.access,
+    access: entry.access,
     configuredAccess: compiled.access,
     skillsOrigin: entry.file.origin,
     initial,
@@ -197,10 +197,7 @@ interface Settings {
   readonly envDefaults: Readonly<Record<string, string>>
 }
 
-interface LoadedFile
-  extends
-    Pick<WorkflowDefinition, "summary" | "base" | "steering" | "skills" | "access">,
-    Settings {
+interface LoadedFile {
   readonly origin: string
   /**
    * Every real file this module's evaluation touched — `origin` itself plus
@@ -214,8 +211,9 @@ interface LoadedFile
   readonly dependencyFiles: readonly string[]
 }
 
-/** A startable workflow; its settings are its file's, under whatever its factory declared. */
-interface LoadedWorkflow extends Settings {
+/** A startable workflow, built from a factory or a `workflow()` call's options. */
+interface LoadedWorkflow
+  extends Settings, Pick<WorkflowDefinition, "summary" | "steering" | "skills" | "access"> {
   readonly flow: Flow
   readonly file: LoadedFile
   readonly doors?: flows.WorkflowDoors | undefined
@@ -384,75 +382,105 @@ const requiredOnUse = (
   })
 }
 
-const stringRecord = (
-  exports: Record<string, unknown>,
-  name: string,
-): Readonly<Record<string, string>> => {
-  const value = exports[name] ?? {}
+/** `what` names the value in an error: `workflow "x"'s "steering"`. */
+const stringRecord = (value: unknown, what: string): Readonly<Record<string, string>> => {
+  const record = value ?? {}
   if (
-    typeof value !== "object" ||
-    value === null ||
-    Object.values(value).some((entry) => typeof entry !== "string")
+    typeof record !== "object" ||
+    record === null ||
+    Object.values(record).some((entry) => typeof entry !== "string")
   ) {
-    throw new Error(`the "${name}" export is not a record of strings`)
+    throw new Error(`${what} is not a record of strings`)
   }
-  return value as Readonly<Record<string, string>>
+  return record as Readonly<Record<string, string>>
 }
 
 const isStringArray = (v: unknown): v is readonly string[] =>
   Array.isArray(v) && v.every((entry) => typeof entry === "string")
 
-const checkSkillsRecord = (value: unknown): Readonly<Record<string, readonly string[]>> => {
+const checkSkillsRecord = (
+  value: unknown,
+  what: string,
+): Readonly<Record<string, readonly string[]>> => {
   if (
     typeof value !== "object" ||
     value === null ||
     Object.values(value).some((entry) => !isStringArray(entry))
   ) {
-    throw new Error(`the "skills" export is not a record of skill-name arrays`)
+    throw new Error(`${what} is not a record of skill-name arrays`)
   }
   return value as Readonly<Record<string, readonly string[]>>
 }
 
-/** Read a module's optional `skills` export — a scope full name -> skill list record, or a function of the vars returning one. */
-const skillsExport = (exports: Record<string, unknown>): WorkflowDefinition["skills"] => {
-  const value = exports["skills"] ?? {}
+/** A workflow's `skills` option — a scope full name -> skill list record, or a function of the vars returning one. */
+const skillsFrom = (value: unknown, what: string): WorkflowDefinition["skills"] => {
   if (typeof value === "function") {
-    return (vars) => checkSkillsRecord((value as (v: typeof vars) => unknown)(vars))
+    return (vars) => checkSkillsRecord((value as (v: typeof vars) => unknown)(vars), what)
   }
-  const record = checkSkillsRecord(value)
+  const record = checkSkillsRecord(value ?? {}, what)
   return () => record
 }
 
-/** Read a module's optional `access` export — a scope full name -> `{ read?, write? }` record, or a function of the vars returning one. */
-const accessExport = (exports: Record<string, unknown>): WorkflowDefinition["access"] => {
-  const value = exports["access"] ?? {}
+const checkAccessRecord = (value: unknown, what: string): Readonly<Record<string, ScopeAccess>> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${what} is not a record of scope access (scope -> { read?, write? }) or a function returning one`,
+    )
+  }
+  for (const [scope, access] of Object.entries(value)) {
+    const fault = accessShapeFault(access)
+    if (fault !== undefined) throw new Error(`${what}: scope "${scope}": ${fault}`)
+  }
+  return value as Readonly<Record<string, ScopeAccess>>
+}
+
+/**
+ * A workflow's `access` option — a scope full name -> `{ read?, write? }`
+ * record, checked now, or a function of the vars returning one, checked when
+ * the process's settings are known.
+ */
+const accessFrom = (value: unknown, what: string): WorkflowDefinition["access"] => {
   if (typeof value === "function") {
     return (vars) => (value as (v: typeof vars) => never)(vars)
   }
-  return () => value as never
+  const record = checkAccessRecord(value ?? {}, what)
+  return () => record
 }
 
-const optionalFunction = <T>(exports: Record<string, unknown>, name: string): T | undefined => {
-  const value = exports[name]
+const optionalFunction = <T>(value: unknown, what: string): T | undefined => {
   if (value === undefined) return undefined
-  if (typeof value !== "function") throw new Error(`the "${name}" export is not a function`)
+  if (typeof value !== "function") throw new Error(`${what} is not a function`)
   return value as T
 }
 
-const RESERVED_EXPORTS: ReadonlySet<string> = new Set([
-  "default",
-  "summary",
-  "base",
+// What each file-level export of earlier versions became: an option of the
+// workflow it configured. Exporting one is a load error, never silently ignored.
+const RETIRED_EXPORTS: ReadonlySet<string> = new Set([
   "defaults",
   "envDefaults",
   "steering",
   "skills",
   "access",
   "doors",
-  "config",
+  "summary",
+  "base",
 ])
 
-/** The rules every declared setting meets, whether a file's export or a factory's build. */
+/** Names that are never a workflow. */
+const RESERVED_EXPORTS: ReadonlySet<string> = new Set(["default", "config", ...RETIRED_EXPORTS])
+
+const retiredExports = (exports: Record<string, unknown>, origin: string): Diagnostic[] =>
+  Object.keys(exports)
+    .filter((name) => RETIRED_EXPORTS.has(name))
+    .sort()
+    .map((name) => ({
+      severity: "error",
+      path: [name],
+      origin,
+      message: `the "${name}" export is no longer read — pass it to the workflow it configures: \`workflow(flow, { ${name} })\`, or the build a workflow factory returns`,
+    }))
+
+/** The rules every declared setting meets. */
 const checkSettings = (
   defaults: Readonly<Record<string, unknown>>,
   envDefaults: Readonly<Record<string, unknown>>,
@@ -481,28 +509,6 @@ const checkSettings = (
   }
 }
 
-/** A module's per-file exports: `defaults`, `envDefaults`, `steering`, `skills`, `access`, `summary`, `base`. */
-const fileFrom = (
-  exports: Record<string, unknown>,
-  origin: string,
-  dependencyFiles: readonly string[],
-): LoadedFile => {
-  const defaults = stringRecord(exports, "defaults")
-  const envDefaults = stringRecord(exports, "envDefaults")
-  checkSettings(defaults, envDefaults, (kind) => `the "${kind}" export declares`)
-  return {
-    defaults,
-    envDefaults,
-    steering: stringRecord(exports, "steering"),
-    skills: skillsExport(exports),
-    access: accessExport(exports),
-    summary: optionalFunction(exports, "summary"),
-    base: optionalFunction(exports, "base"),
-    origin,
-    dependencyFiles,
-  }
-}
-
 const DOOR_NAME_RULE = /^[a-z][a-z0-9-]*$/
 
 /** Why one door's `args` are malformed, or `undefined` when they are well-formed. */
@@ -532,27 +538,12 @@ const doorProblem = (name: string, door: unknown): string | undefined => {
   return argsProblem(args) ?? (varsOk ? undefined : `has "vars" that is not a function`)
 }
 
-/** A module's `doors` export, shape-checked; the workflow names are checked later, against the catalogue. */
-const doorsFrom = (exports: Record<string, unknown>): ReadonlyMap<string, Door> => {
-  const value = exports["doors"]
-  if (value === undefined) return new Map()
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error(`the "doors" export is not a record of doors`)
-  }
-  for (const [name, door] of Object.entries(value)) {
-    const problem = doorProblem(name, door)
-    if (problem !== undefined) throw new Error(`door "${name}" ${problem}`)
-  }
-  return new Map(Object.entries(value) as [string, Door][])
-}
-
 /**
- * Each exported workflow's own doors, onto the name it is exported under. The
- * `doors` export adds to them and declares a name several workflows clash on.
+ * Each exported workflow's own doors, onto the name it is exported under. A
+ * door several workflows build and none is exported under is a clash: no door.
  */
 const derivedDoors = (
   catalogue: ReadonlyMap<string, LoadedWorkflow>,
-  declared: ReadonlyMap<string, Door>,
 ): {
   readonly doors: ReadonlyMap<string, Door>
   readonly clashes: ReadonlyMap<string, readonly string[]>
@@ -572,45 +563,29 @@ const derivedDoors = (
   for (const [name, built] of builders) {
     const owner = ownerOf(name, built)
     if (owner !== undefined) doors.set(name, owner)
-    else if (!declared.has(name))
+    else
       clashes.set(
         name,
         built.map((door) => door.workflow),
       )
   }
-  return { doors: new Map([...doors, ...declared]), clashes }
+  return { doors, clashes }
 }
 
 /** The export named after the door owns it, else the sole builder; a clash of several builds no door. */
 const ownerOf = (name: string, built: readonly Door[]): Door | undefined =>
   built.find((door) => door.workflow === name) ?? (built.length === 1 ? built[0] : undefined)
 
-/** Sort the doors and check each names a startable workflow. */
-const checkDoors = (
-  declared: ReadonlyMap<string, Door>,
-  catalogue: ReadonlyMap<string, LoadedWorkflow>,
-): ReadonlyMap<string, Door> => {
-  const doors = new Map([...declared].sort(([a], [b]) => a.localeCompare(b)))
-  for (const [name, door] of doors) {
-    if (!catalogue.has(door.workflow)) {
-      throw new Error(
-        `door "${name}" names workflow "${door.workflow}", which is not startable — known: ${[...catalogue.keys()].sort().join(", ")}`,
-      )
-    }
-  }
-  return doors
-}
-
 const namespaceOf = (exported: unknown): Record<string, unknown> =>
   (typeof exported === "object" && exported !== null ? exported : {}) as Record<string, unknown>
 
 /**
- * Evaluate `gtd.config.ts`. Every exported function or factory workflow but
- * the reserved names is a workflow named by its export. `cache` is jiti's OWN
- * per-call module cache (unrelated to the instance's `moduleCache: false`) —
- * passing an empty object in has the side effect of collecting every real file
- * jiti resolved evaluating this module, module AND every relative import it
- * pulled in, transitively.
+ * Evaluate `gtd.config.ts`. Every export but the reserved names that went
+ * through `workflow()` or is a factory workflow is a workflow named by its
+ * export. `cache` is jiti's OWN per-call module cache (unrelated to the
+ * instance's `moduleCache: false`) — passing an empty object in has the side
+ * effect of collecting every real file jiti resolved evaluating this module,
+ * module AND every relative import it pulled in, transitively.
  */
 const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded => {
   const { exports: evaluated, files } =
@@ -618,7 +593,7 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
       ? evaluateFromDisk(module, shipped)
       : evaluateRead(module, module.read, shipped)
   const exports = namespaceOf(evaluated)
-  const file = fileFrom(exports, module.filepath, files)
+  const file: LoadedFile = { origin: module.filepath, dependencyFiles: files }
   const exported = Object.entries(exports).filter(
     ([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value),
   )
@@ -643,20 +618,23 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   const derived =
     rejections.length > 0
       ? { doors: new Map<string, Door>(), clashes: new Map<string, readonly string[]>() }
-      : derivedDoors(catalogue, doorsFrom(exports))
+      : derivedDoors(catalogue)
+  const doors = new Map([...derived.doors].sort(([a], [b]) => a.localeCompare(b)))
   return {
     file,
     catalogue,
-    doors: checkDoors(derived.doors, catalogue),
+    doors,
     default: defaultWorkflow && { ...defaultWorkflow, name: defaultName },
     config: compileConfig(exports["config"], module.filepath),
     diagnostics: [
+      ...retiredExports(exports, file.origin),
       ...nameRejections(rejections),
+      ...shadowingDoors(doors, catalogue, file.origin),
       ...[...derived.clashes].map(([name, builders]): Diagnostic => {
         const names = [...builders].sort().map((b) => JSON.stringify(b))
         return {
           severity: "warning",
-          message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — declare it in the "doors" export`,
+          message: `door "${name}" is built by workflows ${names.slice(0, -1).join(", ")} and ${names.at(-1)} and none is exported under that name — rename the export that should own it to "${name}"`,
           path: ["doors", name],
           origin: file.origin,
         }
@@ -665,6 +643,21 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   }
 }
 
+/** `gtd start <name>` takes the door, so a door named like a workflow it does not start hides that workflow. */
+const shadowingDoors = (
+  doors: ReadonlyMap<string, Door>,
+  catalogue: ReadonlyMap<string, unknown>,
+  origin: string,
+): Diagnostic[] =>
+  [...doors]
+    .filter(([name, door]) => catalogue.has(name) && door.workflow !== name)
+    .map(([name, door]) => ({
+      severity: "warning",
+      message: `door "${name}" starts workflow ${JSON.stringify(door.workflow)} and hides the workflow of the same name from \`gtd start ${name}\` — rename one of them`,
+      path: ["doors", name],
+      origin,
+    }))
+
 const evaluateFromDisk = (
   module: WorkflowModule,
   shipped: ShippedModules,
@@ -720,61 +713,91 @@ const evaluateRead = (
 }
 
 const isWorkflow = (value: unknown): boolean =>
-  typeof value === "function" || flows.isFactoryWorkflow(value)
+  markedOptions(value) !== undefined || isFactoryWorkflow(value)
 
 const defaultExport = (exports: Record<string, unknown>): unknown => {
   const value = exports.default
   if (value === undefined) {
     throw new Error(
-      "no default export — export the workflow an ordinary start runs (`gtd install` scaffolds one)",
+      "no default export — export the workflow an ordinary start runs; `gtd guide` says where to get one, or write your own",
     )
   }
-  if (!isWorkflow(value)) throw new Error("the default export is not a function")
+  if (typeof value !== "function" && !isFactoryWorkflow(value)) {
+    throw new Error("the default export is not a function")
+  }
   return value
 }
 
-/** One exported workflow: a plain flow as-is, a factory validated and built. */
+/** One exported workflow: a factory validated and built, a `workflow()` call's options checked alike. */
 const buildWorkflow = (
   name: string,
   value: unknown,
   file: LoadedFile,
   rejections: Rejection[],
 ): LoadedWorkflow | undefined => {
-  const result = flows.configure(value)
-  if (result === undefined)
-    return { flow: value as Flow, file, defaults: file.defaults, envDefaults: file.envDefaults }
+  const result = configure(value)
+  if (result === undefined) {
+    // A plain function only gets here as the default export: a flow without options.
+    return checkedBuild(name, file, { ...markedOptions(value), flow: value as Flow })
+  }
   if (!result.ok) {
     for (const issue of result.issues) rejections.push(optionDiagnostic(name, issue, file))
     return undefined
   }
+  return checkedBuild(name, file, result.build)
+}
+
+const BUILD_KEYS: ReadonlySet<string> = new Set([
+  "flow",
+  "defaults",
+  "envDefaults",
+  "doors",
+  "base",
+  "skills",
+  "access",
+  "steering",
+  "summary",
+])
+
+/** A build — a factory's, or a `workflow()` call's options with its flow — held to one set of rules. */
+const checkedBuild = (
+  name: string,
+  file: LoadedFile,
+  build: flows.WorkflowBuild,
+): LoadedWorkflow => {
+  const what = (key: string): string => `workflow "${name}"'s "${key}"`
+  const unknown = Object.keys(build).filter((key) => !BUILD_KEYS.has(key))
+  if (unknown.length > 0) {
+    throw new Error(
+      `workflow "${name}" has unknown option(s) ${unknown.map((key) => JSON.stringify(key)).join(", ")} — known: ${[...BUILD_KEYS].filter((key) => key !== "flow").join(", ")}`,
+    )
+  }
+  if (typeof build.flow !== "function") throw new Error(`${what("flow")} is not a function`)
+  const defaults = stringRecord(build.defaults, what("defaults"))
+  const envDefaults = stringRecord(build.envDefaults, what("envDefaults"))
+  checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" declares ${kind}`)
+  if (
+    build.doors !== undefined &&
+    (typeof build.doors !== "object" || build.doors === null || Array.isArray(build.doors))
+  ) {
+    throw new Error(`${what("doors")} is not a record of doors`)
+  }
   return {
-    flow: result.build.flow,
+    flow: build.flow,
     file,
-    ...builtSettings(name, file, result.build),
-    doors: result.build.doors,
-    base: result.build.base,
+    defaults,
+    envDefaults,
+    summary: optionalFunction<flows.Summary>(build.summary, what("summary")),
+    steering: stringRecord(build.steering, what("steering")),
+    skills: skillsFrom(build.skills, what("skills")),
+    access: accessFrom(build.access, what("access")),
+    doors: build.doors,
+    base: optionalFunction<flows.WorkflowBase>(build.base, what("base")),
   }
 }
 
-/** A factory's settings over its file's, held to the rules a file's own exports are. */
-const builtSettings = (name: string, file: LoadedFile, build: flows.WorkflowBuild): Settings => {
-  checkSettings(
-    build.defaults ?? {},
-    build.envDefaults ?? {},
-    (kind) => `workflow "${name}" builds ${kind}`,
-  )
-  const defaults = { ...file.defaults, ...build.defaults }
-  const envDefaults = { ...file.envDefaults, ...build.envDefaults }
-  checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" builds ${kind}`)
-  return { defaults, envDefaults }
-}
-
 /** A rejected factory option, reported at `gtd.config.ts`. */
-const optionDiagnostic = (
-  workflow: string,
-  issue: flows.OptionIssue,
-  file: LoadedFile,
-): Rejection => ({
+const optionDiagnostic = (workflow: string, issue: OptionIssue, file: LoadedFile): Rejection => ({
   workflow,
   severity: "error",
   path: issue.path,
@@ -885,7 +908,7 @@ const replayToFirstStep = (
         outcome.kind === "failed" || outcome.kind === "refused"
           ? outcome.message.replace(/^gtd: /, "")
           : "the default entry must begin at a step — that step is where a finished process waits"
-      return Effect.fail(new GtdError(`gtd config:\n  - ${loaded.file.origin}: ${problem}`))
+      return Effect.fail(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: ${problem}`))
     },
   )
 
@@ -912,7 +935,7 @@ const firstStep = (
     if (reads.length > 0) {
       return yield* Effect.fail(
         new GtdError(
-          `gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`,
+          `gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`,
         ),
       )
     }
@@ -923,7 +946,7 @@ const firstStep = (
     if (atHead === name) return name
     return yield* Effect.fail(
       new GtdError(
-        `gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`,
+        `gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`,
       ),
     )
   })

package/src/workflow/skills.test.ts

@@ -17,24 +17,24 @@ describe("resolveScopeSkills", () => {
     const message = await failure(() => {
       throw new Error("boom")
     })
-    expect(message).toContain(`gtd config:\n  - ${FILE}: boom`)
+    expect(message).toContain(`gtd: config:\n  - ${FILE}: boom`)
   })
 
   it("rejects a non-object return", async () => {
     expect(await failure(() => ["a"])).toContain(
-      `gtd config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
+      `gtd: config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
     )
   })
 
   it("rejects a non-array value", async () => {
     expect(await failure(() => ({ a: "x" }))).toContain(
-      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+      `gtd: config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
     )
   })
 
   it("rejects a non-string entry", async () => {
     expect(await failure(() => ({ a: ["x", 1] }))).toContain(
-      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+      `gtd: config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
     )
   })
 
@@ -80,7 +80,7 @@ describe("resolveScopeAccess", () => {
 
   it("rejects a malformed export with the file", async () => {
     expect(message(await run({ access: () => ["a"] }))).toContain(
-      `gtd config:\n  - ${FILE}: access export must return an object`,
+      `gtd: config:\n  - ${FILE}: access export must return an object`,
     )
     expect(message(await run({ access: () => ({ a: { write: "x" } }) }))).toContain(
       `${FILE}: access export: "a": access.write must be an array`,

package/src/workflow/skills.ts

@@ -7,7 +7,7 @@ import type { Diagnostic } from "./Diagnostic.js"
 import { failOnErrors } from "./load.js"
 
 const fail = (origin: string, message: string): GtdError =>
-  new GtdError(`gtd config:\n  - ${origin}: ${message}`)
+  new GtdError(`gtd: config:\n  - ${origin}: ${message}`)
 
 const checkShape = (value: unknown): Record<string, readonly string[]> => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {

package/src/workflow-kit/index.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest"
+import * as kit from "./index.js"
+
+describe("@pmelab/gtd/workflow-kit", () => {
+  it("publishes its helpers by name", () => {
+    expect(Object.keys(kit).sort()).toEqual(
+      [
+        "assertionLines",
+        "escalation",
+        "fixFindings",
+        "gate",
+        "healthy",
+        "lensEntriesOf",
+        "lensOf",
+        "lensScopes",
+        "lensesOf",
+        "qualityLap",
+        "removedAssertions",
+        "review",
+        "reviewToHandOff",
+        "untilSettled",
+      ].sort(),
+    )
+  })
+})