@pmelab/gtd 63.0.0 → 64.1.0

package/src/cli/Program.ts

@@ -1,4 +1,4 @@
-import { Effect, Option, Schema } from "effect"
+import { Effect, Option, type Path, Schema } from "effect"
 import {
   GtdError,
   GtdUsageError,
@@ -70,6 +70,7 @@ import { formatCommitMessage, PIN_STATES } from "../replay/index.js"
 import { planStart, planStep as planStepPure, type JudgeVerdict } from "../step/index.js"
 import {
   BUILT_IN_MODE_NAMES,
+  formatFromSpec,
   steeringFormatFor,
   openThreads,
   parseCodeThreads,
@@ -99,7 +100,7 @@ import {
   restoredOutcome,
 } from "../emit/index.js"
 import { GTD_VERSION, renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
-import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
+import { ToolCommands } from "./ToolCommands.js"
 import {
   normalizeScriptNewline,
   SelectorUsageError,
@@ -169,6 +170,8 @@ export type Command =
       readonly file?: string
       readonly openQuestions?: boolean
       readonly openThreads?: boolean
+      /** A declared format's spec: `mode` names it, and no built-in is looked up. */
+      readonly spec?: string
     }
   | { readonly kind: "uncheck"; readonly file: string }
   | { readonly kind: "guide" }
@@ -210,14 +213,12 @@ export type Command =
  */
 export type Needs = "pure" | "removed" | "none" | "fs" | "state"
 
-const selfGtd = (): SelfGtd => {
-  const script = process.argv[1]
-  return script === undefined ? ["gtd"] : [process.execPath, script]
-}
-
 /** `needs: "none"` skips the repo-root guard — the server is keyed on file name, not workflow state. */
-const runLspCommand = (): Effect.Effect<void, Error, ToolCommands> =>
-  Effect.flatMap(ToolCommands, (tools) => tools.lsp(selfGtd()))
+const runLspCommand = (): Effect.Effect<void, Error, ToolCommands | Host> =>
+  Effect.gen(function* () {
+    const { self } = yield* Host
+    return yield* (yield* ToolCommands).lsp(self)
+  })
 
 /**
  * Prints the briefing, emitted by the binary itself so it's always current.
@@ -246,7 +247,7 @@ const runBundleCommand = (
 ): Effect.Effect<
   void,
   Error,
-  ConfigService | ConfigDiscovery | EngineCore | Host | Narrator | Workspace
+  ConfigService | ConfigDiscovery | EngineCore | Host | Path.Path | Narrator | Workspace
 > =>
   Effect.gen(function* () {
     yield* (yield* ConfigService).load
@@ -430,23 +431,6 @@ const parseJudgeDocument = (rendered: string): Effect.Effect<JudgeDocument, Erro
       ),
   })
 
-/**
- * The first stdin-consuming command outside `src/lsp/Lsp.ts` (which reads LSP's
- * own length-prefixed frames off `process.stdin`, not a one-shot read) —
- * reads stdin to completion and decodes it as UTF-8 text, no framing.
- */
-const readStdin = (): Effect.Effect<string, Error> =>
-  Effect.tryPromise({
-    try: async () => {
-      const chunks: Buffer[] = []
-      for await (const chunk of process.stdin as AsyncIterable<Buffer>) {
-        chunks.push(chunk)
-      }
-      return Buffer.concat(chunks).toString("utf8")
-    },
-    catch: (e) => (e instanceof Error ? e : new Error(String(e))),
-  })
-
 /** A stdin that is no judgment is the caller's mistake, a usage error like `gtd judge answer`'s. */
 const judgmentShape = (input: string): Effect.Effect<void, GtdUsageError> => {
   let doc: unknown
@@ -470,7 +454,7 @@ const runJudgeRunCommand = (
     const host = yield* Host
     const tools = yield* ToolCommands
     yield* refuseLegacyRc
-    const input = yield* readStdin()
+    const input = yield* host.stdin
     yield* judgmentShape(input)
     const verdict = yield* Effect.tryPromise({
       try: () =>
@@ -535,7 +519,7 @@ const runJudgeAnswerCommand = (
     const document = yield* parseJudgeDocument(rendered.judge)
     const ids = document.questions.map((q) => q.id)
 
-    const raw = yield* readStdin()
+    const raw = yield* (yield* Host).stdin
     const parsed = yield* Effect.try({
       try: () => JSON.parse(raw) as unknown,
       catch: () => new SelectorUsageError("gtd judge answer: stdin is not valid JSON"),
@@ -922,8 +906,9 @@ const selfValidateCommand = (
   state: string,
   mode: StateMode,
   file: string,
+  spec: string | undefined,
 ): string => {
-  const resolved = resolveMode(def, state, mode)
+  const resolved = resolveMode(def, state, mode, spec)
   const validate = resolved.kind === "resolved" ? resolved.validate : undefined
   const command = validate?.kind === "command" ? validate.command : seededValidateCommand(mode)
   return commandForFile(command, file)
@@ -946,14 +931,14 @@ const resolveValidateScript = (
 ): Effect.Effect<
   { readonly file: string; readonly mode: StateMode; readonly script: string } | undefined,
   Error,
-  Host
+  Host | Path.Path
 > =>
   Effect.gen(function* () {
     const file = rest.hints.file
     const mode = rest.stepDef.mode
     if (file === undefined || mode === undefined) return undefined
 
-    const resolved = resolveMode(rest.def, rest.state, mode)
+    const resolved = resolveMode(rest.def, rest.state, mode, rest.stepDef.modeSpec)
     if (resolved.kind === "unknown") {
       return yield* Effect.fail(new Error(resolved.message))
     }
@@ -995,7 +980,13 @@ const runNextCommand = (
       yield* writeSelection(out, fields, json.path)
     } else {
       const validateCommand = emitsValidatablePrompt(rendered)
-        ? selfValidateCommand(rest.def, rest.state, rendered.mode!, rendered.file!)
+        ? selfValidateCommand(
+            rest.def,
+            rest.state,
+            rendered.mode!,
+            rendered.file!,
+            rest.stepDef.modeSpec,
+          )
         : undefined
       if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
         // A prompt's stdout is the agent's input, so its header goes to stderr;
@@ -1038,9 +1029,10 @@ const runCheckCommand = (
   file: string,
   openQuestions: boolean,
   openThreadsFlag: boolean,
+  spec: string | undefined,
 ): Effect.Effect<void, Error, Workspace> =>
   Effect.gen(function* () {
-    const format = steeringFormatFor(mode)
+    const format = spec !== undefined ? yield* declaredFormat(spec) : steeringFormatFor(mode)
     if (format === undefined) {
       return yield* Effect.fail(
         new GtdUsageError(
@@ -1090,6 +1082,13 @@ const runCheckCommand = (
     )
   })
 
+const declaredFormat = (spec: string): Effect.Effect<SteeringFormat, GtdUsageError> =>
+  Effect.try({
+    try: () => formatFromSpec(spec),
+    catch: (error) =>
+      new GtdUsageError(`gtd check: --spec is not a declared format: ${(error as Error).message}`),
+  })
+
 const existingFile = (file: string): Effect.Effect<string, Error, Workspace> =>
   Effect.flatMap(Workspace, (workspace) => {
     const content = workspace.atPath(file)
@@ -1403,6 +1402,7 @@ const dispatchVoidCommand = (
         command.file,
         command.openQuestions ?? false,
         command.openThreads ?? false,
+        command.spec,
       )
     case "uncheck":
       return runUncheckCommand(command.file)

package/src/cli/ToolCommands.ts

@@ -1,9 +1,7 @@
 import { Context } from "effect"
 import type { Effect } from "effect"
 import type { UiSettings } from "../flows/index.js"
-
-/** How to run THIS gtd — a tool (the LSP) never reads a different version's state than the one it ships with. */
-export type SelfGtd = readonly [string, ...string[]]
+import type { HostOps } from "../platform/index.js"
 
 export interface UiRequest {
   readonly flags: {
@@ -36,7 +34,8 @@ export class ToolCommands extends Context.Service<
       request: UiRequest,
       out: { readonly write: (chunk: string) => void; readonly flush: () => void },
     ) => Effect.Effect<void, Error>
-    readonly lsp: (gtd: SelfGtd) => Effect.Effect<void, Error>
+    /** `gtd` runs THIS gtd, so the LSP never reads a different version's state than the one it ships with. */
+    readonly lsp: (gtd: HostOps["self"]) => Effect.Effect<void, Error>
     readonly judge: (request: JudgeRequest) => Promise<string>
   }
 >()("ToolCommands") {}

package/src/edge/Edge.test.ts

@@ -185,7 +185,7 @@ describe("currentRun", () => {
     expect(run.episode.base).toBe(boundary)
     expect(run.episode.commits.map((c) => c.message.split("\n")[0])).toEqual([
       "gtd(human): idle → building",
-      "gtd(check): pin → building",
+      "gtd(check): gtd:pin → building",
       "gtd(agent): building → checking",
     ])
   })
@@ -205,7 +205,7 @@ describe("currentRun", () => {
     await land(repo, { "a.txt": "a\n" })
     await land(repo, { "b.txt": "b\n" })
     const closing = await land(repo, { "c.txt": "c\n" })
-    expect(repo.lastCommitSubject()).toBe("gtd(check): unpin → idle")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:unpin → idle")
     const next = await land(repo, { "d.txt": "d\n" })
     const run = await provide(currentRun, repo)
     expect(run.startParentHash).toBe(closing)
@@ -217,7 +217,7 @@ describe("currentRun", () => {
     const before = headOf(repo)
     const opening = await enter(repo, "side")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 3`,
+      `gtd(human): fixing\n\nGtd-Workflow: side\nGtd-Var: base=\nGtd-Var: reviewer=nobody\nGtd-Format: 4`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -250,7 +250,7 @@ export const again = workflow(async () => {
     const before = headOf(repo)
     const opening = await enter(repo, "again")
     expect(repo.lastCommitMessage(opening)).toBe(
-      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 3`,
+      `gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 4`,
     )
     const fixed = await land(repo, { "fix.txt": "x\n" })
     const run = await provide(currentRun, repo)
@@ -264,6 +264,29 @@ export const again = workflow(async () => {
     ])
   })
 
+  it("a format 3 pin commit naming the default's initial step bounds nothing either", async () => {
+    const repo = repoWith(`import { agent, human, workflow } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+}
+
+export const again = workflow(async () => {
+  await human("idle", { message: "idle-message" })
+  await agent("fixing", "fix-prompt")
+})
+`)
+    const before = headOf(repo)
+    repo.seedCommit("gtd(human): idle\n\nGtd-Workflow: again\nGtd-Format: 3")
+    const opening = headOf(repo)
+    repo.writeFile(".gtd/process.gtdpin", "gtdpin 1 gtd in-memory\n")
+    repo.seedCommit("gtd(check): pin → idle\n\nGtd-Pin: add\nGtd-Format: 3")
+    const run = await provide(currentRun, repo)
+    expect(run.workflow).toBe("again")
+    expect(run.startHash).toBe(opening)
+    expect(run.startParentHash).toBe(before)
+  })
+
   it("collects every process commit's Gtd-Cost, attributing a model-less one to UNATTRIBUTED_MODEL", async () => {
     const repo = repoWith(LINEAR)
     commit(
@@ -395,7 +418,7 @@ export const again = workflow(async () => {
     it("is undefined at a pin commit, which is no turn", async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
-      expect(repo.lastCommitSubject()).toBe("gtd(check): pin → building")
+      expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:pin → building")
       expect((await provide(currentRun, repo)).headTurn).toBeUndefined()
     })
 
@@ -403,7 +426,7 @@ export const again = workflow(async () => {
       const repo = repoWith(LINEAR)
       await land(repo, { "a.txt": "a\n" })
       await land(repo)
-      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 3")
+      expect(repo.lastCommitMessage()).toBe("gtd(agent): building\n\nGtd-Format: 4")
       const run = await provide(currentRun, repo)
       expect(run.headTurn).toEqual({ state: "building", actor: "agent", empty: true, step: false })
     })
@@ -544,7 +567,7 @@ describe("summaryRun", () => {
     expect(summary.trace).toEqual([
       { state: "building", hash: building, actor: "human" },
       { state: "checking", hash: checking, actor: "agent" },
-      { state: "unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
+      { state: "gtd:unpin", hash: headOf(repo, `${closing}~1`), actor: "agent" },
       { state: "idle", hash: closing, actor: "check" },
     ])
   })
@@ -831,7 +854,7 @@ export const review = workflow(async () => {
   it("is the base the resting step names", async () => {
     const repo = repoWith(LOOP)
     const first = await land(repo, { "a.txt": "a\n" })
-    expect(repo.lastCommitSubject()).toBe("gtd(check): pin → checkpoint")
+    expect(repo.lastCommitSubject()).toBe("gtd(check): gtd:pin → checkpoint")
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
     await land(repo, { "b.txt": "b\n" })
     expect(reviewBaseFor(await provide(currentRest, repo))).toBe(first)
@@ -1306,7 +1329,7 @@ describe("finishing landings keep history", () => {
     await land(repo, { "b.txt": "b\n" })
     repo.writeFile("c.txt", "c\n")
     const landing = await landingOf(repo)
-    expect(landing.to).toBe("unpin")
+    expect(landing.to).toBe("gtd:unpin")
     expect(landing.keepHistory).toBeUndefined()
     expect(landing.spec.version).toBeUndefined()
   })
@@ -1522,13 +1545,16 @@ describe("historyTrail", () => {
       tip,
     ])
     expect(trail.steps[2]).toMatchObject({
-      subject: "gtd(agent): checking → unpin",
+      subject: "gtd(agent): checking → gtd:unpin",
       actor: "agent",
       from: "checking",
-      to: "unpin",
+      to: "gtd:unpin",
       verdicts: [],
     })
-    expect(trail.steps[3]).toMatchObject({ subject: "gtd(check): unpin → idle", actor: "check" })
+    expect(trail.steps[3]).toMatchObject({
+      subject: "gtd(check): gtd:unpin → idle",
+      actor: "check",
+    })
     expect(trail.steps[0]).toMatchObject({ actor: "human", to: "building" })
   })
 

package/src/edge/Edge.ts

@@ -1,4 +1,4 @@
-import { Effect, Option } from "effect"
+import { Effect, Option, Path } from "effect"
 import {
   Narrator,
   GitService,
@@ -42,6 +42,7 @@ import {
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
+  LEGACY_PIN_STATES,
   type PinChange,
   PIN_STATES,
   type ReachedStep,
@@ -62,7 +63,6 @@ import {
 
 import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
-import { isAbsolute, relative, resolve, sep } from "node:path"
 import { accessRefusal, type Landing, type RepoSnapshot } from "../step/index.js"
 
 export { UNATTRIBUTED_MODEL }
@@ -337,8 +337,14 @@ const subjectIsBoundary = (def: WorkflowDefinition, subject: string): boolean =>
   const parsed = parseCommitMessage(subject).parsed
   if (parsed === undefined || !ACTORS.has(parsed.actor)) return true
   if (parsed.actor === "human" && parsed.from === undefined) return false
-  // A pin commit's subject can name the first step; it bounds nothing.
-  if (parsed.actor === "check" && parsed.from === PIN_STATES.add) return false
+  // A pin commit's subject can name the first step; it bounds nothing. The
+  // subject alone carries no format, so either spelling counts.
+  if (
+    parsed.actor === "check" &&
+    (parsed.from === PIN_STATES.add || parsed.from === LEGACY_PIN_STATES.add)
+  ) {
+    return false
+  }
   return parsed.to === def.initial
 }
 
@@ -421,7 +427,14 @@ const computeProcessRun = (
     runOf(history, locateEpisode(def, history)),
   )
 
-type ConfigRequirements = GitService | ConfigService | ConfigDiscovery | Narrator | Workspace | Host
+type ConfigRequirements =
+  | GitService
+  | ConfigService
+  | ConfigDiscovery
+  | Narrator
+  | Workspace
+  | Host
+  | Path.Path
 
 /** The run alone, never replaying — `gtd abandon` must work even when replay would refuse, short of a history it cannot read. */
 export const currentRun: Effect.Effect<ProcessRun, Error, ConfigRequirements> = Effect.gen(
@@ -692,7 +705,7 @@ const DEFAULT_JUDGE_MESSAGE =
 const optional = <K extends string, V>(key: K, value: V | undefined): { [P in K]?: V } =>
   (value === undefined ? {} : { [key]: value }) as { [P in K]?: V }
 
-type StepCommon = Pick<StepDef, "actor" | "label" | "file" | "mode">
+type StepCommon = Pick<StepDef, "actor" | "label" | "file" | "mode" | "modeSpec">
 
 const commonOf = (step: ReachedStep): StepCommon => {
   const options = step.request.options
@@ -700,7 +713,9 @@ const commonOf = (step: ReachedStep): StepCommon => {
     actor: step.actor,
     ...optional("label", options.label),
     ...optional("file", options.file),
-    ...optional("mode", options.mode),
+    ...(typeof options.mode === "object"
+      ? { mode: options.mode.name, modeSpec: options.mode.spec }
+      : optional("mode", options.mode)),
   }
 }
 
@@ -820,6 +835,23 @@ const hintsOf = (def: StepDef): RestHints => ({
   ...optional("access", def.access),
 })
 
+/** A step's mode is a name the workflow knows, or a declared format named apart from all of them. */
+const modeFaultOf = (
+  def: WorkflowDefinition,
+  stepName: string,
+  stepDef: StepDef,
+): string | undefined => {
+  if (stepDef.mode === undefined) return undefined
+  const known = def.modes[stepDef.mode] !== undefined
+  if (stepDef.modeSpec !== undefined)
+    return known
+      ? `gtd: config: step "${stepName}": declared format "${stepDef.mode}" has the name of a mode this workflow already knows — rename the format`
+      : undefined
+  return known
+    ? undefined
+    : `gtd: config: step "${stepName}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`
+}
+
 const normalizeStatus = (raw: string): ChangeStatus => (raw === "A" ? "A" : raw === "D" ? "D" : "M")
 
 /** The currently rested step and its description — enough for the viewer and the LSP. */
@@ -984,13 +1016,8 @@ export const restAt = (
     const { reached, step } = resting
     const { stepDef, state, memory } = restFacts(pin, step, reached.trace, run)
     yield* (yield* Narrator).narrate(`rest resolved: ${state} (awaits ${stepDef.actor})`)
-    if (stepDef.mode !== undefined && def.modes[stepDef.mode] === undefined) {
-      return yield* Effect.fail(
-        new Error(
-          `gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`,
-        ),
-      )
-    }
+    const modeFault = modeFaultOf(def, step.name, stepDef)
+    if (modeFault !== undefined) return yield* Effect.fail(new Error(modeFault))
     const changes =
       ref === undefined
         ? (yield* pendingChanges(git, stepDef.approve === true)).map((e) => ({
@@ -1564,10 +1591,16 @@ export interface HistoryTrail {
  * repository cannot be read at a ref, so it is left out. A file only the old
  * config read needs no check: whichever file imported it differs too.
  */
-const inRepoConfigPaths = (root: string, files: readonly string[]): readonly string[] => {
-  const paths = new Set<string>()
-  for (const file of files) paths.add(relative(root, resolve(root, file)).split(sep).join("/"))
-  return [...paths].filter((p) => p !== "" && !p.startsWith("..") && !isAbsolute(p)).sort()
+const inRepoConfigPaths = (
+  path: Path.Path,
+  root: string,
+  files: readonly string[],
+): readonly string[] => {
+  const found = new Set<string>()
+  for (const file of files) {
+    found.add(path.relative(root, path.resolve(root, file)).split(path.sep).join("/"))
+  }
+  return [...found].filter((p) => p !== "" && !p.startsWith("..") && !path.isAbsolute(p)).sort()
 }
 
 const configRefusal = (
@@ -1589,7 +1622,8 @@ const differingConfigPaths = (
 ) =>
   Effect.gen(function* () {
     const differing: string[] = []
-    for (const path of inRepoConfigPaths(root, Object.keys(config.fingerprint))) {
+    const configPaths = inRepoConfigPaths(yield* Path.Path, root, Object.keys(config.fingerprint))
+    for (const path of configPaths) {
       const atTip = yield* Effect.orElseSucceed(git.readFileAtRef(hash, path), () => undefined)
       if (atTip !== workspace.readSync(path)) differing.push(path)
     }

package/src/emit/SteeringMode.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { Effect } from "effect"
+import { Effect, Layer, Path } from "effect"
 import { resolveMode, validateScriptFor, type ModeResolution } from "./SteeringMode.js"
 import { Host } from "../platform/index.js"
 import { steeringFormatFor } from "../steering/index.js"
@@ -16,7 +16,9 @@ const envVarsLayer = Host.layer({ root: "/repo", home: "/repo", env: { PATH: "/u
 
 const runScript = (resolved: ModeResolution, file: string) => {
   if (resolved.kind !== "resolved") throw new Error("expected a resolved mode")
-  return Effect.runPromise(validateScriptFor(resolved, file).pipe(Effect.provide(envVarsLayer)))
+  return Effect.runPromise(
+    validateScriptFor(resolved, file).pipe(Effect.provide(Layer.merge(envVarsLayer, Path.layer))),
+  )
 }
 
 describe("resolveMode", () => {

package/src/emit/SteeringMode.ts

@@ -1,13 +1,18 @@
-import { join } from "node:path"
-import { Effect } from "effect"
-import { Host } from "../platform/index.js"
+import { Effect, Path } from "effect"
+import { Host, type HostOps } from "../platform/index.js"
 import {
+  declaredValidateCommand,
   isSeededValidateCommand,
   knownModes,
   type StateMode,
   type WorkflowDefinition,
 } from "../workflow/index.js"
-import { steeringFormatFor, type SteeringFinding, type SteeringFormat } from "../steering/index.js"
+import {
+  formatFromSpec,
+  steeringFormatFor,
+  type SteeringFinding,
+  type SteeringFormat,
+} from "../steering/internal.js"
 import { buildModeContradictionCheck, modeContradictionSkipNotice } from "./ModeContradiction.js"
 import {
   binaryGuard,
@@ -102,12 +107,26 @@ const capabilitiesFor = (
  * The `"unknown"` arm carries the whole refusal message, naming what IS known
  * when `def` is given — this is the one place that message is built, so it
  * can never drift from what actually resolved.
+ *
+ * `spec` is a declared format's: it alone decides, validating through
+ * `gtd check --spec` with no `format:` half.
  */
 export const resolveMode = (
   def: Pick<WorkflowDefinition, "modes"> | undefined,
   state: string,
   mode: StateMode,
+  spec?: string,
 ): ModeResolution => {
+  if (spec !== undefined) {
+    const format = formatFromSpec(spec)
+    return {
+      kind: "resolved",
+      mode,
+      format,
+      validate: { kind: "command", command: declaredValidateCommand(mode, spec) },
+      capabilities: { format, liveValidate: format.validate },
+    }
+  }
   const declared = def?.modes?.[mode]
   const format = steeringFormatFor(mode)
   if (declared === undefined && format === undefined) {
@@ -191,8 +210,11 @@ const modeCommandSteps = (resolved: ResolvedMode, file: string): readonly EmitSt
 }
 
 /** `<Host.scratchDir>/gtd-mode-sample-<mode>-<pid>.md` — an absolute literal baked in at emit time, never a shell variable. `<pid>` avoids collisions between concurrent `gtd` processes. Never a `/tmp` literal or `mktemp` (`tests/tooling/no-tmp-assumption.test.ts` scans for both). */
-const scratchSamplePath = (scratchDir: string, mode: StateMode): string =>
-  join(scratchDir, `gtd-mode-sample-${mode}-${process.pid}.md`)
+const scratchSamplePath = (
+  path: Path.Path,
+  { scratchDir, pid }: HostOps,
+  mode: StateMode,
+): string => path.join(scratchDir, `gtd-mode-sample-${mode}-${pid}.md`)
 
 /**
  * The contradiction round-trip/skip-notice steps for `resolved`'s `mode:`.
@@ -204,13 +226,12 @@ const scratchSamplePath = (scratchDir: string, mode: StateMode): string =>
  */
 const modeContradictionSteps = (
   resolved: ResolvedMode,
-): Effect.Effect<readonly EmitStep[], Error, Host> =>
+): Effect.Effect<readonly EmitStep[], Error, Host | Path.Path> =>
   Effect.gen(function* () {
     if (resolved.formatCommand === undefined) return []
     const { capabilities } = resolved
     if (capabilities.format !== undefined && capabilities.liveValidate !== undefined) {
-      const { scratchDir } = yield* Host
-      const samplePath = scratchSamplePath(scratchDir, resolved.mode)
+      const samplePath = scratchSamplePath(yield* Path.Path, yield* Host, resolved.mode)
       const formatCommand = withFileVar(resolved.formatCommand, samplePath)
       return [
         {
@@ -245,7 +266,7 @@ export interface ValidateScript {
 export const validateScriptFor = (
   resolved: ResolvedMode,
   file: string,
-): Effect.Effect<ValidateScript, Error, Host> =>
+): Effect.Effect<ValidateScript, Error, Host | Path.Path> =>
   Effect.gen(function* () {
     const steps: EmitStep[] = [
       ...(yield* modeContradictionSteps(resolved)),

package/src/flows/index.ts

@@ -50,6 +50,7 @@ export {
   type Judgment,
   type KeptTip,
   type Mark,
+  type DeclaredMode,
   type ModeName,
   type OpenQuestion,
   type RunOptions,

package/src/flows/runtime.test.ts

@@ -19,6 +19,7 @@ import {
   type AgentOptions,
   type HumanOptions,
   type Judgment,
+  type DeclaredMode,
   type ModeName,
   type RunOptions,
   type Settings,
@@ -315,6 +316,6 @@ describe("mode", () => {
     expectTypeOf<"qa">().toMatchTypeOf<ModeName>()
     expectTypeOf<string>().toMatchTypeOf<ModeName>()
     expectTypeOf<ModeName>().toMatchTypeOf<string>()
-    expectTypeOf<SteeringOptions["mode"]>().toEqualTypeOf<ModeName | undefined>()
+    expectTypeOf<SteeringOptions["mode"]>().toEqualTypeOf<ModeName | DeclaredMode | undefined>()
   })
 })

package/src/flows/runtime.ts

@@ -8,6 +8,12 @@ import type { WorkflowBuild } from "./factory.js"
 /** A steering-file mode: a built-in format's name or a `config.modes` entry. */
 export type ModeName = "qa" | "review" | "findings" | (string & {})
 
+/** A format declared with `listFormat`/`sectionFormat` from `@pmelab/gtd/steering`, used as a step's mode. */
+export interface DeclaredMode {
+  readonly name: string
+  readonly spec: string
+}
+
 interface SteeringCommon {
   /** Display name for drivers and viewers. */
   readonly label?: string | undefined
@@ -24,8 +30,8 @@ type SteeringFile =
     }
   | {
       readonly file: string
-      /** The steering file's mode — a built-in name or a `modes:` entry. Requires `file`. */
-      readonly mode: ModeName
+      /** The steering file's mode — a built-in name, a `modes:` entry, or a declared format. Requires `file`. */
+      readonly mode: ModeName | DeclaredMode
     }
 
 /** A steering-file declaration shared by the steps that rest on one. `mode` requires `file`. */

package/src/gherkin/messages.test.ts

@@ -45,7 +45,7 @@ describe("restDescription", () => {
         "  last commits:",
         "    chore: initial commit",
         "    gtd(agent): plan → sign-off",
-        "    gtd(check): pin → sign-off",
+        "    gtd(check): gtd:pin → sign-off",
         '  actors never used: "repair" (scenario), "ready" (Background)',
       ].join("\n"),
     )

package/src/gherkin/module-config.feature

@@ -20,6 +20,6 @@ Feature: a scenario runs a workflow module from disk
     And the commit subjects end with:
       """
       gtd(agent): plan → sign-off
-      gtd(check): pin → sign-off
+      gtd(check): gtd:pin → sign-off
       """
 

package/src/gherkin/testkit.feature

@@ -43,7 +43,7 @@ Feature: testkit drives any workflow against the real engine
     And the commit subjects end with:
       """
       gtd(human): plan
-      gtd(check): pin → plan
+      gtd(check): gtd:pin → plan
       gtd(agent): plan → check
       gtd(check): check → ready
       gtd(judge): ready → ship
@@ -107,7 +107,7 @@ Feature: testkit drives any workflow against the real engine
     When gtd starts workflow "tiny"
     And the process is driven
     Then the process rests at "plan"
-    And the last commit subject is "gtd(check): pin → plan"
+    And the last commit subject is "gtd(check): gtd:pin → plan"
 
   Scenario: a prompt asserted beside a script is checked at every visit, before the step acts
     Given step "check" is prompted with "npm test"