@pmelab/gtd 58.2.0 → 59.0.1

package/src/cli/Help.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest"
+import { closest, definition, wrap } from "./Help.js"
+
+describe("wrap", () => {
+  it("fills lines up to the width, never past it", () => {
+    expect(wrap("aaa bbb ccc ddd", 7)).toEqual(["aaa bbb", "ccc ddd"])
+  })
+
+  it("keeps a code span on one line", () => {
+    expect(wrap("run `gtd help land` now", 12)).toEqual(["run", "`gtd help land`", "now"])
+  })
+
+  it("keeps an indented example paragraph verbatim", () => {
+    expect(wrap('text\n\n  s=$(x) && sh -c "$s"', 4)).toEqual([
+      "text",
+      "",
+      '  s=$(x) && sh -c "$s"',
+    ])
+  })
+})
+
+describe("definition", () => {
+  it("puts a short term beside its description", () => {
+    expect(definition("next", "Print it", 10)).toEqual(["  next    Print it"])
+  })
+
+  it("gives a term too wide for the column a line of its own", () => {
+    expect(definition("a-very-long-term", "Text", 10)).toEqual([
+      "  a-very-long-term",
+      "          Text",
+    ])
+  })
+})
+
+describe("closest", () => {
+  const commands = ["next", "land", "history", "help"]
+
+  it("finds a dropped letter and a swapped pair", () => {
+    expect(closest("nxt", commands)).toBe("next")
+    expect(closest("lnad", commands)).toBe("land")
+    expect(closest("histroy", commands)).toBe("history")
+  })
+
+  it("suggests nothing for a word unlike every candidate", () => {
+    expect(closest("frobnicate", commands)).toBeUndefined()
+  })
+})

package/src/cli/Help.ts

@@ -0,0 +1,70 @@
+const HELP_WIDTH = 80
+
+/**
+ * Word-wraps prose to `width` columns, every line prefixed by `indent`.
+ * Paragraphs are separated by a blank line; a paragraph whose lines start
+ * with two spaces is an example and is kept verbatim (indented, not wrapped).
+ */
+const wrapParagraph = (paragraph: string, width: number, indent: string): string[] => {
+  const lines: string[] = []
+  let line = ""
+  // A `code span` is one word: a command split across lines can't be copied.
+  for (const word of paragraph.match(/\S*`[^`]*`\S*|\S+/g) ?? []) {
+    if (line !== "" && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line)
+      line = word
+    } else {
+      line = line === "" ? word : `${line} ${word}`
+    }
+  }
+  if (line !== "") lines.push(indent + line)
+  return lines
+}
+
+export const wrap = (text: string, width = HELP_WIDTH, indent = ""): string[] =>
+  text
+    .split("\n\n")
+    .flatMap((paragraph, i) => [
+      ...(i > 0 ? [""] : []),
+      ...(paragraph.startsWith("  ")
+        ? paragraph.split("\n").map((l) => indent + l)
+        : wrapParagraph(paragraph, width, indent)),
+    ])
+
+/** `term` and `description` side by side, the description wrapped into the column after `column`; a term too wide for it gets a line of its own. */
+export const definition = (term: string, description: string, column: number): string[] => {
+  const cell = `  ${term}`
+  const body = wrap(description, HELP_WIDTH, " ".repeat(column))
+  if (cell.length + 1 >= column) return [cell, ...body]
+  const [first = "", ...rest] = body
+  return [cell.padEnd(column) + first.trimStart(), ...rest]
+}
+
+/** Optimal-string-alignment distance: Levenshtein plus adjacent transpositions, so `nxet` is one edit from `next`. */
+const distance = (a: string, b: string): number => {
+  const d: number[][] = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  )
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      let best = Math.min(d[i - 1]![j]! + 1, d[i]![j - 1]! + 1, d[i - 1]![j - 1]! + cost)
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        best = Math.min(best, d[i - 2]![j - 2]! + 1)
+      }
+      d[i]![j] = best
+    }
+  }
+  return d[a.length]![b.length]!
+}
+
+/** The candidate closest to `word`, when it is a plausible typo of it: at most one edit per three characters, and at least one. */
+export const closest = (word: string, candidates: readonly string[]): string | undefined => {
+  const limit = Math.max(1, Math.floor(word.length / 3))
+  let best: { readonly name: string; readonly d: number } | undefined
+  for (const name of candidates) {
+    const d = distance(word, name)
+    if (d <= limit && (best === undefined || d < best.d)) best = { name, d }
+  }
+  return best?.name
+}

package/src/cli/Program.test.ts

@@ -4,7 +4,7 @@
  * e2e tier observes. Argv parsing is pinned in `src/cli/Cli.test.ts`.
  */
 
-import { Cause, Effect, Exit } from "effect"
+import { Cause, Context, Effect, Exit } from "effect"
 import { PassThrough } from "node:stream"
 import { afterEach, describe, expect, it, vi } from "vitest"
 
@@ -17,7 +17,7 @@ vi.mock("node:os", async (importOriginal) => ({
 
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
-import { needsOf, runCommand, SelectorUsageError } from "./Program.js"
+import { needsOf, runCommand, SelectorUsageError, type CommandRequirements } from "./Program.js"
 import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
 import {
   commitAll,
@@ -26,9 +26,9 @@ import {
   noteOutcome,
   restoredOutcome,
 } from "../emit/index.js"
-import { HISTORY_REF } from "../platform/index.js"
-import { CONFIG_SCAFFOLD } from "../install/index.js"
+import { GitService, HISTORY_REF, Host } from "../platform/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"
 
@@ -119,6 +119,19 @@ export const defaults = { greeting: "hello" }
     expect(stderr).toContain("startable: hotfix")
   })
 
+  it("lists the paths its script commits as comments a path cannot break out of", async () => {
+    const repo = seed(WORKFLOW)
+    repo.writeFile("NOTE.md", "a note\n")
+    repo.writeFile("evil\nrm -rf x", "")
+    const { stdout, exitCode } = await run(repo, "--workflow", "hotfix")
+    expect(exitCode).toBe(0)
+    expect(stdout).toContain("# commits every change in the working tree (git add -A):\n")
+    expect(stdout).toContain("#   A NOTE.md\n")
+    expect(stdout).toContain("evil?rm -rf x")
+    expect(stdout).not.toMatch(/^rm -rf x/m)
+    expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
+  })
+
   it("`default` is not startable by name", async () => {
     const repo = seed(WORKFLOW)
     const { exitCode, stderr } = await run(repo, "--workflow", "default")
@@ -194,9 +207,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 +263,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 +331,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
   }
@@ -1702,7 +1746,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   )
 
   const NO_COMMITS_MESSAGE =
-    "gtd requires a repository with at least one commit — make an initial commit, then run gtd again"
+    "gtd: the repository has no commits yet — make an initial commit, then run gtd again"
 
   it("derives exactly the eighteen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
@@ -1752,7 +1796,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 +1809,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 +1994,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 +2031,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.
@@ -2263,3 +2307,53 @@ export const defaults = ${vars}
     expect(repo.lastCommitMessage()).not.toContain("Gtd-Payload:")
   })
 })
+
+describe("runCommand — the repository-root guard's messages", () => {
+  const guarded = async (
+    override: (
+      git: Context.Tag.Service<GitService>,
+      host: Context.Tag.Service<Host>,
+    ) => Effect.Effect<unknown, Error, CommandRequirements>,
+  ): Promise<string> => {
+    const exit = await Effect.runPromiseExit(
+      Effect.gen(function* () {
+        return yield* override(yield* GitService, yield* Host)
+      }).pipe(Effect.provide(testLayers(seedIdle()))),
+    )
+    return Exit.isFailure(exit) ? (Cause.squash(exit.cause) as Error).message : ""
+  }
+  const out = { write: () => {}, flush: () => {} }
+  const next = runCommand({ kind: "next" }, { kind: "off" }, out)
+
+  it("outside a git repository says so instead of quoting git", async () => {
+    const message = await guarded((git) =>
+      next.pipe(
+        Effect.provideService(GitService, {
+          ...git,
+          topLevel: () =>
+            Effect.fail(
+              new Error(
+                "git rev-parse --show-toplevel failed (exit 128): fatal: not a git repository (or any of the parent directories): .git",
+              ),
+            ),
+        }),
+      ),
+    )
+    expect(message).toBe("gtd: not a git repository — run gtd inside one (`git init` makes one)")
+  })
+
+  it("from a subdirectory names the root to cd to", async () => {
+    const message = await guarded((_git, host) =>
+      next.pipe(
+        Effect.provideService(Host, {
+          ...host,
+          root: "/repo/my sub",
+          realPath: (path: string) => Effect.succeed(path),
+        }),
+      ),
+    )
+    expect(message).toBe(
+      "gtd: run gtd from the repository root — cd /repo (the current directory is /repo/my sub)",
+    )
+  })
+})

package/src/cli/Program.ts

@@ -33,6 +33,7 @@ import {
   landFields,
   noopText,
   renderBeatJson,
+  DEMAND_BRIEFING,
   renderBeatPlain,
   renderLandJson,
   renderLandPlain,
@@ -87,7 +88,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,
@@ -143,7 +144,7 @@ export type Command =
       readonly vars: Readonly<Record<string, string>>
       readonly label: string
     }
-  | { readonly kind: "door"; readonly name: string; readonly args: readonly string[] }
+  | { readonly kind: "door"; readonly name?: string; readonly args: readonly string[] }
   | { readonly kind: "doors" }
   | { readonly kind: "abandon" }
   | { readonly kind: "restore" }
@@ -207,13 +208,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 +222,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)`,
     )
   })
 
@@ -568,10 +567,12 @@ const runStartCommand = (
     const config = yield* (yield* ConfigService).load
     const resolved = config.workflowNamed(workflow)
     if (resolved === undefined) {
+      const startable =
+        config.workflowNames.length > 0
+          ? `startable: ${config.workflowNames.join(", ")}`
+          : "this config exports no workflow besides its default, which an ordinary start runs"
       return yield* Effect.fail(
-        new GtdUsageError(
-          `gtd --workflow: unknown workflow "${workflow}" — startable: ${config.workflowNames.join(", ")}`,
-        ),
+        new GtdUsageError(`gtd --workflow: unknown workflow "${workflow}" — ${startable}`),
       )
     }
     const rest = yield* restAt(undefined, varOverrides)
@@ -593,35 +594,57 @@ const runStartCommand = (
     if (plan.kind === "refusal") {
       return yield* Effect.fail(new Error(plan.message))
     }
-    out.write(landingScript(ScriptSurface.render(plan.steps)))
+    out.write(listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes))
   })
 
+/**
+ * A start commits the whole tree (`git add -A`), so its script says up front
+ * which paths that is. Comment lines only: control characters are masked so a
+ * path can never end the comment and become a command.
+ */
+const listingCommitted = (script: string, changes: readonly PendingChange[]): string => {
+  if (changes.length === 0) return script
+  const listing = [
+    "# commits every change in the working tree (git add -A):",
+    ...changes.map((change) => `#   ${change.status} ${change.path.replace(/\p{Cc}/gu, "?")}`),
+  ].join("\n")
+  const at = script.indexOf("\n\n")
+  return at === -1 ? script : `${script.slice(0, at)}\n\n${listing}${script.slice(at)}`
+}
+
 const doorSynopsis = (name: string, door: Door): string =>
   [
     name,
     ...(door.args ?? []).map((arg) => (arg.optional === true ? `[${arg.name}]` : `<${arg.name}>`)),
   ].join(" ")
 
+const noSuchDoor = (name: string | undefined, doors: ReadonlyMap<string, Door>): GtdUsageError => {
+  const listing =
+    doors.size > 0
+      ? `doors: ${[...doors].map(([n, d]) => doorSynopsis(n, d)).join(", ")}`
+      : "this config has no doors"
+  return new GtdUsageError(
+    name === undefined
+      ? `gtd door: missing door name — ${listing}`
+      : `gtd door: unknown door "${name}" — ${listing}`,
+  )
+}
+
 /**
  * `gtd door <name> [args…]`: `gtd --workflow` with the door's workflow and the
  * process settings its `vars` derive from the positional args. A wrong name or
  * arity is a usage error naming what would have worked.
  */
 const runDoorCommand = (
-  name: string,
+  name: string | undefined,
   args: readonly string[],
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const config = yield* (yield* ConfigService).load
-    const door = config.doors.get(name)
-    if (door === undefined) {
-      const known = [...config.doors]
-      return yield* Effect.fail(
-        new GtdUsageError(
-          `gtd door: unknown door "${name}" — doors: ${known.map(([n, d]) => doorSynopsis(n, d)).join(", ")}`,
-        ),
-      )
+    const door = name === undefined ? undefined : config.doors.get(name)
+    if (name === undefined || door === undefined) {
+      return yield* Effect.fail(noSuchDoor(name, config.doors))
     }
     const declared = door.args ?? []
     const required = declared.filter((arg) => arg.optional !== true).length
@@ -652,6 +675,11 @@ const runDoorsCommand = (
     const config = yield* (yield* ConfigService).load
     const doors = [...config.doors]
     if (json.kind === "off") {
+      if (doors.length === 0) {
+        yield* (yield* Narrator).warn(
+          "gtd doors: this config has no doors — a workflow factory's `doors` option or the config's `doors` export adds one",
+        )
+      }
       out.write(doors.map(([n, d]) => `${doorSynopsis(n, d)} → ${d.workflow}\n`).join(""))
       return
     }
@@ -851,6 +879,12 @@ const runNextCommand = (
       const validateCommand = emitsValidatablePrompt(rendered)
         ? selfValidateCommand(rest.def, rest.state, rendered.mode!, rendered.file!)
         : undefined
+      if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
+        // A prompt's stdout is the agent's input, so its header goes to stderr;
+        // rendered as a header-showing kind to reuse the one header layout.
+        const shown = renderBeatPlain({ ...fields, kind: "message" })
+        yield* narrator.warn(shown.slice(0, shown.indexOf("\n\n")))
+      }
       out.write(renderBeatPlain(fields, validateCommand))
     }
   })
@@ -1127,19 +1161,30 @@ const runUiCliCommand = (
  */
 const assertRunningFromRepoRoot = (git: GitOperations, host: HostOps): Effect.Effect<void, Error> =>
   Effect.gen(function* () {
-    const topLevel = yield* git.topLevel()
+    const topLevel = yield* git
+      .topLevel()
+      .pipe(
+        Effect.mapError((e) =>
+          /not a git repository/.test(e.message)
+            ? new Error("gtd: not a git repository — run gtd inside one (`git init` makes one)")
+            : e,
+        ),
+      )
     const topReal = yield* host.realPath(topLevel)
     const cwdReal = yield* host.realPath(host.root)
     if (topReal !== cwdReal) {
       return yield* Effect.fail(
         new Error(
-          `gtd must be run from the repository root (${topLevel}); ` +
-            `the current directory is ${host.root}`,
+          `gtd: run gtd from the repository root — cd ${shellWord(topLevel)} ` +
+            `(the current directory is ${host.root})`,
         ),
       )
     }
   })
 
+const shellWord = (path: string): string =>
+  /^[\w@%+=:,./-]+$/.test(path) ? path : `'${path.replace(/'/g, "'\\''")}'`
+
 /** A command that derives workflow state needs at least one commit too — a commitless repository has no HEAD to resolve a `Rest` at. */
 const assertRepositoryHasCommits = (git: GitOperations): Effect.Effect<void, Error> =>
   Effect.gen(function* () {
@@ -1147,7 +1192,7 @@ const assertRepositoryHasCommits = (git: GitOperations): Effect.Effect<void, Err
     if (!hasCommits) {
       return yield* Effect.fail(
         new Error(
-          "gtd requires a repository with at least one commit — make an initial commit, then run gtd again",
+          "gtd: the repository has no commits yet — make an initial commit, then run gtd again",
         ),
       )
     }

package/src/edge/Edge.ts

@@ -995,7 +995,7 @@ export const restAt = (
     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(", ")})`,
+          `gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`,
         ),
       )
     }
@@ -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/emit/Emit.test.ts

@@ -359,7 +359,7 @@ describe("real repo — an assembled script end to end", () => {
 describe("combinedScript — the plain-text write commands' single pasteable script", () => {
   it("DID_NOT_RUN_COMMENT points the reader at sh, not bash", () => {
     expect(DID_NOT_RUN_COMMENT).toBe(
-      "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn",
+      "# gtd emitted this and did NOT run it — run it with `sh` to apply it",
     )
     expect(DID_NOT_RUN_COMMENT).not.toContain("bash")
   })

package/src/emit/Emit.ts

@@ -112,7 +112,7 @@ export const emitScripts = (
 
 /** Exported so `src/twins/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
 export const DID_NOT_RUN_COMMENT =
-  "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn"
+  "# gtd emitted this and did NOT run it — run it with `sh` to apply it"
 
 export const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip"
 

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> = {