@pmelab/gtd 23.2.0 → 24.1.0

package/src/cli/Cli.test.ts

@@ -0,0 +1,1329 @@
+/**
+ * Parse-tier unit tests for src/cli/Cli.ts — `parseArgv` is pure and total, so
+ * these need no repo, no layers, and no `Effect.runPromise`. Runtime-tier
+ * tests (`runCli` through a capturing `CliIo`) live in the second `describe`
+ * block below.
+ */
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import * as fc from "fast-check"
+import { Effect, Layer } from "effect"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import {
+  needsOf,
+  nodeCliIo,
+  normalizeTrailingNewline,
+  parseArgv,
+  renderHelp,
+  runCli,
+  standaloneKinds,
+  type CliIo,
+  type Command,
+  type CliPlan,
+  ToolCommands,
+} from "./index.js"
+import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { type CommandRequirements } from "./Cli.js"
+import { InMemRepo, testLayers } from "../testkit/index.js"
+import { CONFIG_SCAFFOLD } from "../install/index.js"
+
+const FLAG_NAMES = [
+  "--json",
+  "--port",
+  "--host",
+  "--self-signed",
+  "--dev",
+  "--cost",
+  "--model",
+  "--workflow",
+  "--var",
+  "--open-questions",
+  "--open-threads",
+  "--verbose",
+]
+
+describe("parseArgv — unknown options", () => {
+  it("any `--` token not in the flag table forces kind === 'usage' (property)", () => {
+    fc.assert(
+      fc.property(
+        fc.array(
+          fc.string({ minLength: 1, maxLength: 12 }).filter((s) => !s.includes("=")),
+          {
+            maxLength: 6,
+          },
+        ),
+        (words) => {
+          const bogus = "--totally-bogus-flag"
+          const argv = ["node", "gtd.js", ...words, bogus]
+          if (argv.includes("--help") || argv.includes("-h")) return
+          if (argv.includes("--version") || argv.includes("-V")) return
+          if (argv.includes("-v")) return
+          if (FLAG_NAMES.some((f) => argv.includes(f))) return
+          const plan: CliPlan = parseArgv(argv)
+          expect(plan.kind).toBe("usage")
+        },
+      ),
+    )
+  })
+
+  it("parseArgv(['node','gtd.js','next','--jsn']) is the exact usage plan", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--jsn"])
+    expect(plan).toEqual({
+      kind: "usage",
+      stdout: "",
+      message: "gtd: unknown option '--jsn' — see `gtd --help`",
+      json: false,
+    })
+  })
+})
+
+describe("parseArgv — arity", () => {
+  it("`gtd land human` is an arity error (land takes no positional)", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "human"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("`gtd next extra` is a usage error (next takes no argument)", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("`gtd next --at` is an unknown-option usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--at"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("unknown option '--at'")
+  })
+})
+
+describe("parseArgv — scope", () => {
+  it("--cost on an unknown command reports the flag's own scope error, not the unknown command", () => {
+    const plan = parseArgv(["node", "gtd.js", "frobnicate", "--cost=5"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  })
+
+  it("--json is in scope for next, land, judge and judge answer — every other command usage-errors on it", () => {
+    for (const args of [
+      ["next", "--json"],
+      ["land", "--json"],
+      ["judge", "--json"],
+      ["judge", "answer", "--json"],
+      ["doors", "--json"],
+    ]) {
+      const ok = parseArgv(["node", "gtd.js", ...args])
+      expect(ok.kind).toBe("command")
+      if (ok.kind === "command") expect(ok.json).toEqual({ kind: "document" })
+    }
+
+    for (const args of [
+      ["lsp", "--json"],
+      ["validate", "--json"],
+      ["check", "qa", "TODO.md", "--json"],
+      ["install", "--json"],
+      ["abandon", "--json"],
+      ["restore", "--json"],
+      ["--workflow", "some-state", "--json"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") {
+        expect(plan.message).toContain("only valid for `gtd next`/`gtd land`")
+        expect(plan.message).toContain("gtd install")
+      }
+    }
+  })
+
+  it("--sh is gone: a bare unknown-option usage error on next and land, exit 2", () => {
+    for (const args of [
+      ["next", "--sh"],
+      ["land", "--sh"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") {
+        expect(plan.message).toContain("unknown option '--sh'")
+      }
+    }
+  })
+
+  it("--port on land is rejected", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--port=1234"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd ui`")
+  })
+
+  it("--port is accepted by gtd ui", () => {
+    expect(parseArgv(["node", "gtd.js", "ui", "--port", "3000"]).kind).toBe("command")
+  })
+
+  it("--host on any other command (e.g. next) is a scope violation", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--host", "x"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toBe("gtd: --host is only valid for `gtd ui`")
+    }
+  })
+
+  it("--var without --workflow is rejected", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--var", "a=1"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toBe("gtd: --var requires --workflow")
+  })
+
+  it("--cost with --workflow is rejected (landing and starting are different verbs)", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "foo", "--cost=5"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  })
+
+  it("--model with --workflow is rejected the same way", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "foo", "--model=gpt"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  })
+
+  it("--workflow on `gtd land` (or any other command) is rejected — landing and starting are different verbs", () => {
+    for (const args of [
+      ["validate", "--workflow", "e"],
+      ["land", "--workflow", "e"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") {
+        expect(plan.message).toBe(
+          "gtd: --workflow is only valid with no other command — use the bare `gtd --workflow <name>` " +
+            "form; landing and starting are different verbs",
+        )
+      }
+    }
+  })
+
+  it("--model without --cost is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--model=opus"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--model requires --cost")
+  })
+
+  it("--dispatch is gone: an unknown-option usage error everywhere, `gtd next` included", () => {
+    for (const args of [
+      ["land", "--dispatch"],
+      ["validate", "--dispatch"],
+      ["next", "--json", "--dispatch"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") {
+        expect(plan.message).toContain("unknown option '--dispatch'")
+      }
+    }
+  })
+})
+
+describe("parseArgv — gtd next", () => {
+  it("parses to a bare next command — there is no separate claiming form any more", () => {
+    const plan = parseArgv(["node", "gtd.js", "next"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "next" })
+    }
+  })
+
+  it("gtd next --json parses to a next command with json set", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "next" })
+      expect(plan.json).toEqual({ kind: "document" })
+    }
+  })
+
+  it("gtd next --json=kind parses to JsonMode select with path 'kind'", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json=kind"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "next" })
+      expect(plan.json).toEqual({ kind: "select", path: "kind" })
+    }
+  })
+
+  it("gtd next with no --json parses to JsonMode off", () => {
+    const plan = parseArgv(["node", "gtd.js", "next"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") expect(plan.json).toEqual({ kind: "off" })
+  })
+
+  it("gtd next --json=session.id parses to a dotted selector path verbatim", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json=session.id"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") expect(plan.json).toEqual({ kind: "select", path: "session.id" })
+  })
+
+  it("gtd next --json= is a usage error naming only the legal --json=<path> form — never the rejected empty form or the illegal space form", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json="])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toBe("gtd: --json requires a value — use --json=<path>")
+      expect(plan.json).toBe(true)
+    }
+  })
+
+  it("gtd next --json kind (space form) leaves kind as a positional — next takes none, so this is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json", "kind"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("--json is non-repeatable: a second bare occurrence is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json", "--json"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--json may be given at most once")
+  })
+
+  it("--json is non-repeatable: two selector occurrences are a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json=a", "--json=b"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--json may be given at most once")
+  })
+
+  it("--json is non-repeatable across mixed bare/selector forms", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json", "--json=b"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--json may be given at most once")
+  })
+})
+
+describe("parseArgv — gtd land", () => {
+  it("gtd land parses to a bare land command", () => {
+    const plan = parseArgv(["node", "gtd.js", "land"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "land" })
+    }
+  })
+
+  it("gtd land --cost=5 --model=opus carries both, omitting neither key", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--cost=5", "--model=opus"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "land", cost: 5, model: "opus" })
+    }
+  })
+
+  it("gtd land --json parses to a land command with json set", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--json"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "land" })
+      expect(plan.json).toEqual({ kind: "document" })
+    }
+  })
+
+  it("gtd land --json=script parses to JsonMode select with path 'script'", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--json=script"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") expect(plan.json).toEqual({ kind: "select", path: "script" })
+  })
+
+  it("gtd land --json=model and gtd land --model=<name> do not collide — different tokens", () => {
+    const readBack = parseArgv(["node", "gtd.js", "land", "--json=model"])
+    expect(readBack.kind).toBe("command")
+    if (readBack.kind === "command") {
+      expect(readBack.json).toEqual({ kind: "select", path: "model" })
+      expect(readBack.command).toEqual({ kind: "land" })
+    }
+
+    const record = parseArgv(["node", "gtd.js", "land", "--model=opus", "--cost=1"])
+    expect(record.kind).toBe("command")
+    if (record.kind === "command") {
+      expect(record.json).toEqual({ kind: "off" })
+      expect(record.command).toEqual({ kind: "land", cost: 1, model: "opus" })
+    }
+  })
+})
+
+describe("parseArgv — flag orthogonality", () => {
+  it("--version with --json still produces the version output (flags are independent)", () => {
+    const plan = parseArgv(["node", "gtd.js", "--version", "--json"])
+    expect(plan.kind).toBe("output")
+  })
+
+  it("--help with extra args still prints help", () => {
+    const plan = parseArgv(["node", "gtd.js", "--help", "--json"])
+    expect(plan.kind).toBe("output")
+  })
+})
+
+describe("parseArgv — bare/unknown command under --json", () => {
+  // With no command resolved, `kind` is `undefined` — `--json`'s scope is
+  // violated just like any other scoped flag used standalone, so its scope
+  // error takes priority over "missing command"/"unknown command" here.
+  it("bare gtd --json is a usage error with json:true, naming --json's own scope error", () => {
+    const plan = parseArgv(["node", "gtd.js", "--json"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.json).toBe(true)
+      expect(plan.message).toContain("only valid for `gtd next`")
+    }
+  })
+
+  it("bare gtd's missing-command message (no --json) points at gtd install, not a bundled loop", () => {
+    const plan = parseArgv(["node", "gtd.js"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("missing command")
+      expect(plan.message).toContain("gtd decides and prints")
+      expect(plan.message).toContain("gtd install")
+      expect(plan.message).toContain("A complete minimal driver")
+    }
+  })
+
+  it("an unknown command under --json carries json:true, naming --json's own scope error over the subcommand", () => {
+    const plan = parseArgv(["node", "gtd.js", "bogus", "--json"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.json).toBe(true)
+      expect(plan.message).toContain("only valid for `gtd next`")
+    }
+  })
+
+  it("an unknown command without --json still names the subcommand", () => {
+    const plan = parseArgv(["node", "gtd.js", "bogus"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.json).toBe(false)
+      expect(plan.message).toContain("bogus")
+    }
+  })
+})
+
+describe("parseArgv — entry/var flag details (formerly parseEntryFlags/takeFlagValues)", () => {
+  it("accepts --workflow=<state> (= form)", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow=side-entry"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({
+        kind: "start",
+        actor: "human",
+        workflow: "side-entry",
+        vars: {},
+        label: "gtd --workflow side-entry",
+      })
+    }
+  })
+
+  it("a bare --workflow with no value is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--workflow requires a value")
+  })
+
+  it("a second --workflow occurrence is a usage error (not last-wins)", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "a", "--workflow", "b"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage")
+      expect(plan.message).toContain("--workflow may be given at most once")
+  })
+
+  it("a duplicate --var NAME is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", "a=1", "--var", "a=2"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("--var a")
+  })
+
+  it("a --var name outside the setting-name rule is a usage error naming it", () => {
+    for (const raw of ["a b=1", "a-b=1", "1a=1", "a\nb=1"]) {
+      const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", raw])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") {
+        expect(plan.message).toContain(
+          `--var ${JSON.stringify(raw.slice(0, raw.indexOf("=")))} is not a valid setting name`,
+        )
+      }
+    }
+  })
+
+  it("a multiline --var value is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", "a=1\n2"])
+    expect(plan.kind).toBe("usage")
+  })
+})
+
+describe("parseArgv — --entry is removed", () => {
+  it("is an ordinary unknown option, with no hint at --workflow", () => {
+    const plan = parseArgv(["node", "gtd.js", "--entry", "fix-precheck"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("--entry")
+      expect(plan.message).not.toContain("--workflow")
+    }
+  })
+})
+
+describe("parseArgv — the --workflow selector", () => {
+  it("gtd --workflow version parses to { kind: start, workflow: version } — the regression this RFC fixes", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "version"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toMatchObject({ kind: "start", workflow: "version" })
+    }
+  })
+
+  it("gtd --workflow help likewise parses to a start command, not the help text", () => {
+    const plan = parseArgv(["node", "gtd.js", "--workflow", "help"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toMatchObject({ kind: "start", workflow: "help" })
+    }
+  })
+})
+
+describe("parseArgv — gtd check <mode> <file>", () => {
+  it("parses to a check command carrying mode and file", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", ".gtd/TODO.md"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "check", mode: "qa", file: ".gtd/TODO.md" })
+      expect(plan.json).toEqual({ kind: "off" })
+    }
+  })
+
+  it("--json is out of scope for check — next/land are the only structured surfaces", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "review", "REVIEW.md", "--json"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd next`")
+  })
+
+  it("bare --open-threads (no mode, no file) parses to a check command", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "--open-threads"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "check", openThreads: true })
+    }
+  })
+
+  it("the <mode> <file> --open-threads form is unchanged", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", "N.md", "--open-threads"])
+    expect(plan.kind === "command" && plan.command).toEqual({
+      kind: "check",
+      mode: "qa",
+      file: "N.md",
+      openThreads: true,
+    })
+  })
+
+  it("missing both arguments is a usage error naming mode and file", () => {
+    const plan = parseArgv(["node", "gtd.js", "check"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("missing mode and file arguments")
+    }
+  })
+
+  it("missing the file argument (mode only) is a usage error naming file", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("missing file argument")
+    }
+  })
+
+  it("too many arguments is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", "TODO.md", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("too many arguments")
+      expect(plan.message).toContain("extra")
+    }
+  })
+
+  it("a scoped-out flag (e.g. --cost) is rejected on check", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", "TODO.md", "--cost=5"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  })
+})
+
+describe("parseArgv — gtd uncheck <file>", () => {
+  it("parses to an uncheck command carrying file", () => {
+    const plan = parseArgv(["node", "gtd.js", "uncheck", ".gtd/REVIEW.md"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "uncheck", file: ".gtd/REVIEW.md" })
+      expect(plan.json).toEqual({ kind: "off" })
+    }
+  })
+
+  it("missing the file argument is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "uncheck"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("missing file argument")
+  })
+
+  it("too many arguments is a usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "uncheck", "REVIEW.md", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toContain("too many arguments")
+      expect(plan.message).toContain("extra")
+    }
+  })
+
+  it("takes no mode argument — a second positional is rejected as extra, never accepted as mode", () => {
+    const plan = parseArgv(["node", "gtd.js", "uncheck", "qa", "REVIEW.md"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("a scoped-out flag (e.g. --cost) is rejected on uncheck", () => {
+    const plan = parseArgv(["node", "gtd.js", "uncheck", "REVIEW.md", "--cost=5"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  })
+})
+
+describe("parseArgv — gtd check --open-questions", () => {
+  it("parses to a check command carrying openQuestions: true", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", ".gtd/TODO.md", "--open-questions"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({
+        kind: "check",
+        mode: "qa",
+        file: ".gtd/TODO.md",
+        openQuestions: true,
+      })
+    }
+  })
+
+  it("omits openQuestions entirely when the flag is absent (unchanged shape)", () => {
+    const plan = parseArgv(["node", "gtd.js", "check", "qa", ".gtd/TODO.md"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "check", mode: "qa", file: ".gtd/TODO.md" })
+      expect("openQuestions" in plan.command).toBe(false)
+    }
+  })
+
+  it("--open-questions on any other command is a usage error carrying its own scopeError", () => {
+    const plan = parseArgv(["node", "gtd.js", "land", "--open-questions"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") {
+      expect(plan.message).toBe("gtd: --open-questions is only valid for `gtd check`")
+    }
+  })
+})
+
+describe("parseArgv — help/version short-circuits", () => {
+  it("--help produces an output plan", () => {
+    expect(parseArgv(["node", "gtd.js", "--help"]).kind).toBe("output")
+  })
+
+  it("--version produces an output plan containing a semver", () => {
+    const plan = parseArgv(["node", "gtd.js", "--version"])
+    expect(plan.kind).toBe("output")
+    if (plan.kind === "output") expect(plan.stdout).toMatch(/\d+\.\d+\.\d+/)
+  })
+
+  it("the `version` subcommand produces the same output as --version", () => {
+    const a = parseArgv(["node", "gtd.js", "--version"])
+    const b = parseArgv(["node", "gtd.js", "version"])
+    expect(a).toEqual(b)
+  })
+
+  it("the `help` subcommand produces the same output as --help", () => {
+    const a = parseArgv(["node", "gtd.js", "--help"])
+    const b = parseArgv(["node", "gtd.js", "help"])
+    expect(a).toEqual(b)
+  })
+
+  it("gtd bogus --help still prints help — help wins over an unknown command", () => {
+    const plan = parseArgv(["node", "gtd.js", "bogus", "--help"])
+    expect(plan.kind).toBe("output")
+  })
+
+  it("-V short-circuits to the version output, exactly like --version", () => {
+    const a = parseArgv(["node", "gtd.js", "-V"])
+    const b = parseArgv(["node", "gtd.js", "--version"])
+    expect(a).toEqual(b)
+  })
+})
+
+describe("parseArgv — --verbose / -v (the -v/-V swap)", () => {
+  it("bare `gtd -v` no longer prints a version — it is the missing-command usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "-v"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("missing command")
+  })
+
+  it("-v resolves to --verbose: `gtd -v next` carries verbose: true", () => {
+    const plan = parseArgv(["node", "gtd.js", "-v", "next"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "next" })
+      expect(plan.verbose).toBe(true)
+    }
+  })
+
+  it("--verbose is equivalent to -v", () => {
+    const a = parseArgv(["node", "gtd.js", "next", "--verbose"])
+    const b = parseArgv(["node", "gtd.js", "next", "-v"])
+    expect(a).toEqual(b)
+  })
+
+  it("every other command's plan carries verbose: false when the flag is absent", () => {
+    const plan = parseArgv(["node", "gtd.js", "next"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") expect(plan.verbose).toBe(false)
+  })
+
+  it("--verbose is valid alongside every command kind — never a scope violation", () => {
+    for (const args of [
+      ["land", "--verbose"],
+      ["next", "--verbose", "--json"],
+      ["check", "qa", "TODO.md", "--verbose"],
+      ["--workflow", "some-state", "--verbose"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("command")
+      if (plan.kind === "command") expect(plan.verbose).toBe(true)
+    }
+  })
+})
+
+describe("parseArgv — gtd install", () => {
+  it("parses to an install command", () => {
+    const plan = parseArgv(["node", "gtd.js", "install"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "install" })
+      expect(plan.json).toEqual({ kind: "off" })
+    }
+  })
+
+  it("--json is out of scope for install — the briefing is plain text only", () => {
+    const plan = parseArgv(["node", "gtd.js", "install", "--json"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd next`")
+  })
+
+  it("gtd install extra is a usage error (install takes no argument)", () => {
+    const plan = parseArgv(["node", "gtd.js", "install", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("a scoped-out flag (e.g. --port) is rejected on install", () => {
+    const plan = parseArgv(["node", "gtd.js", "install", "--port=3"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd ui`")
+  })
+})
+
+describe("parseArgv — gtd ui", () => {
+  it("parses --host/--port/--self-signed/--dev into one ui command", () => {
+    const plan = parseArgv([
+      "node",
+      "gtd.js",
+      "ui",
+      "--host",
+      "h",
+      "--port",
+      "8443",
+      "--self-signed",
+      "--dev",
+    ])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({
+        kind: "ui",
+        host: "h",
+        port: 8443,
+        selfSigned: true,
+        dev: true,
+      })
+    }
+  })
+
+  it("bare `gtd ui` omits host/port and defaults selfSigned/dev to false", () => {
+    const plan = parseArgv(["node", "gtd.js", "ui"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "ui", selfSigned: false, dev: false })
+    }
+  })
+
+  it("gtd ui --bogus is an unknown-option usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "ui", "--bogus"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("unknown option '--bogus'")
+  })
+
+  it("gtd ui extra is a usage error — ui takes no positional argument", () => {
+    const plan = parseArgv(["node", "gtd.js", "ui", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+})
+
+describe("parseArgv — gtd judge / gtd judge answer", () => {
+  it("gtd judge parses to a bare judge command", () => {
+    const plan = parseArgv(["node", "gtd.js", "judge"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "judge" })
+      expect(plan.json).toEqual({ kind: "off" })
+    }
+  })
+
+  it("gtd judge answer parses to a judgeAnswer command — the CLI's one two-level verb", () => {
+    const plan = parseArgv(["node", "gtd.js", "judge", "answer"])
+    expect(plan.kind).toBe("command")
+    if (plan.kind === "command") {
+      expect(plan.command).toEqual({ kind: "judgeAnswer" })
+    }
+  })
+
+  it("gtd judge --json / gtd judge answer --json both parse with json set", () => {
+    for (const args of [
+      ["judge", "--json"],
+      ["judge", "answer", "--json"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("command")
+      if (plan.kind === "command") expect(plan.json).toEqual({ kind: "document" })
+    }
+  })
+
+  it("gtd judge extra (not 'answer') is a too-many-arguments usage error, not judgeAnswer", () => {
+    const plan = parseArgv(["node", "gtd.js", "judge", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("gtd judge answer extra is a too-many-arguments usage error", () => {
+    const plan = parseArgv(["node", "gtd.js", "judge", "answer", "extra"])
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("a scoped-out flag (e.g. --cost) is rejected on judge and judge answer", () => {
+    for (const args of [
+      ["judge", "--cost=5"],
+      ["judge", "answer", "--cost=5"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+    }
+  })
+})
+
+describe("parseArgv — gtd judge run", () => {
+  const parse = (...args: string[]) => parseArgv(["node", "gtd.js", ...args])
+
+  it("parses --provider fixed with --answers", () => {
+    const plan = parse("judge", "run", "--provider", "fixed", "--answers", "a.json")
+    expect(plan.kind === "command" && plan.command).toEqual({
+      kind: "judgeRun",
+      provider: "fixed",
+      answers: "a.json",
+    })
+  })
+
+  it("parses --provider jev alone", () => {
+    const plan = parse("judge", "run", "--provider=jev")
+    expect(plan.kind === "command" && plan.command).toEqual({ kind: "judgeRun", provider: "jev" })
+  })
+
+  it("parses --provider llm with --model", () => {
+    const plan = parse("judge", "run", "--provider=llm", "--model", "sonnet")
+    expect(plan.kind === "command" && plan.command).toEqual({
+      kind: "judgeRun",
+      provider: "llm",
+      model: "sonnet",
+    })
+  })
+
+  it("parses no --provider (auto), with or without --model", () => {
+    const bare = parse("judge", "run")
+    expect(bare.kind === "command" && bare.command).toEqual({ kind: "judgeRun" })
+    const model = parse("judge", "run", "--model=x")
+    expect(model.kind === "command" && model.command).toEqual({ kind: "judgeRun", model: "x" })
+  })
+
+  it.each([
+    [["judge", "run", "--provider", "nope"], "must be one of fixed, jev, llm"],
+    [["judge", "run", "--answers", "a.json"], "--answers is only valid with --provider fixed"],
+    [["judge", "run", "--provider", "jev", "--model", "x"], "--model"],
+    [["judge", "run", "--provider", "fixed", "--model", "x"], "--model"],
+    [["next", "--model", "x"], "`gtd land` (with --cost) or `gtd judge run`"],
+    [["judge", "run", "--provider", "fixed", "--json"], "--json is only valid"],
+    [["judge", "run", "--provider", "fixed", "--answers="], "requires a value"],
+    [["judge", "--provider", "fixed"], "only valid for `gtd judge run`"],
+    [["judge", "answer", "--answers", "a.json"], "only valid for `gtd judge run`"],
+    [["next", "--provider", "fixed"], "only valid for `gtd judge run`"],
+  ])("%j is a usage error", (args, text) => {
+    const plan = parse(...args)
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain(text)
+  })
+})
+
+describe("parseArgv — doors", () => {
+  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
+
+  it("`gtd door <name>` carries the name and no args", () => {
+    const plan = parse("door", "fix")
+    expect(plan).toMatchObject({
+      kind: "command",
+      command: { kind: "door", name: "fix", args: [] },
+    })
+  })
+
+  it("`gtd door <name> a b` carries every positional after the name, in order", () => {
+    const plan = parse("door", "review", "v1.0", "extra")
+    expect(plan).toMatchObject({
+      kind: "command",
+      command: { kind: "door", name: "review", args: ["v1.0", "extra"] },
+    })
+  })
+
+  it("`gtd door` with no name is a usage error", () => {
+    const plan = parse("door")
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("gtd door: missing name argument")
+  })
+
+  it("`gtd doors` parses with every --json shape", () => {
+    expect(parse("doors")).toMatchObject({
+      kind: "command",
+      command: { kind: "doors" },
+      json: { kind: "off" },
+    })
+    expect(parse("doors", "--json")).toMatchObject({ json: { kind: "document" } })
+    expect(parse("doors", "--json=0.name")).toMatchObject({
+      json: { kind: "select", path: "0.name" },
+    })
+  })
+
+  it("`gtd doors` takes no argument", () => {
+    const plan = parse("doors", "extra")
+    expect(plan.kind).toBe("usage")
+    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
+  })
+
+  it("`gtd door` rejects --json and --var — a door's vars come from its args", () => {
+    expect(parse("door", "fix", "--json").kind).toBe("usage")
+    expect(parse("door", "fix", "--var", "a=1").kind).toBe("usage")
+  })
+
+  it("help lists both commands", () => {
+    const help = renderHelp()
+    expect(help).toContain("door <name> [args...]")
+    expect(help).toMatch(/^ {2}doors\b/m)
+  })
+})
+
+describe("standaloneKinds / needsOf", () => {
+  it("pins the standalone kinds", () => {
+    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "loop", "judgeRun"])
+  })
+
+  it("needsOf matches none/fs for the standalone kinds and state for everything else", () => {
+    expect(needsOf("lsp")).toBe("none")
+    expect(needsOf("check")).toBe("fs")
+    expect(needsOf("uncheck")).toBe("fs")
+    expect(needsOf("install")).toBe("none")
+    expect(needsOf("loop")).toBe("none")
+    expect(needsOf("judgeRun")).toBe("none")
+    for (const kind of [
+      "land",
+      "start",
+      "abandon",
+      "restore",
+      "next",
+      "validate",
+      "ui",
+      "judge",
+      "judgeAnswer",
+      "door",
+      "doors",
+    ] as const) {
+      expect(needsOf(kind)).toBe("state")
+    }
+  })
+})
+
+describe("renderHelp", () => {
+  it("mentions every command and flag, and no removed surface", () => {
+    const help = renderHelp()
+    expect(help).toContain("Usage")
+    expect(help).toContain("land")
+    expect(help).toContain("--workflow <name>")
+    expect(help).toContain("--var")
+    expect(help).toContain("abandon")
+    expect(help).toContain("restore")
+    expect(help).toContain("next")
+    expect(help).toContain("validate")
+    expect(help).toContain("lsp")
+    expect(help).not.toContain("visualize")
+    expect(help).not.toMatch(/^ {2}init\b/m)
+    expect(help).not.toContain(".gtdrc")
+    expect(help).toMatch(/^ {2}ui\b/m)
+    expect(help).toContain("check <mode> <file>")
+    expect(help).toContain("install")
+    expect(help).toContain("base ")
+    expect(help).toMatch(/^ {2}judge\b/m)
+    expect(help).toContain("judge answer")
+    expect(help).toContain("version")
+    expect(help).toContain("help")
+    expect(help).toContain("--json")
+    expect(help).toContain("--port")
+    expect(help).not.toContain("--no-open")
+    expect(help).toContain("--host")
+    expect(help).toContain("--self-signed")
+    expect(help).toContain("--dev")
+    expect(help).toContain("--cost")
+    expect(help).toContain("--model")
+    expect(help).toContain("--open-questions")
+    expect(help).toContain("--verbose")
+    expect(help).toContain("--version, -V")
+    expect(help).toContain("--help, -h")
+    expect(help).not.toContain("review <commitish>")
+    expect(help).not.toContain("format <file>")
+    expect(help).not.toContain("--debug")
+    expect(help).not.toContain("bin/gtd")
+    expect(help).not.toContain("(no command), loop")
+    expect(help).not.toContain("--dispatch")
+    expect(help).not.toContain("--if-resting")
+    expect(help).not.toMatch(/^ {2}serve\b/m)
+    expect(help).toMatch(/\n$/)
+  })
+
+  it("every flag row's name appears in the Options: block and vice versa", () => {
+    const help = renderHelp()
+    const optionsBlock = help.slice(help.indexOf("Options:"))
+    for (const name of FLAG_NAMES) expect(optionsBlock).toContain(name)
+  })
+
+  it("the docs/cli.md Commands fenced block equals renderHelp()", () => {
+    const doc = readFileSync(resolve(import.meta.dirname, "../../docs/cli.md"), "utf8")
+    const match = doc.match(/## Commands\n\n```\n([\s\S]*?)\n```/)
+    expect(match).not.toBeNull()
+    expect(match![1] + "\n").toBe(renderHelp())
+  })
+
+  it("README.md and COMPATIBILITY.md list exactly the commands", () => {
+    const commands = new Set(
+      [...renderHelp().matchAll(/^ {2}([a-z]+(?: [a-z]+)?)(?= )/gm)].map(([, name]) => name),
+    )
+    expect(commands).toContain("judge answer")
+    const listed = (file: string, list: RegExp): Set<string> => {
+      const doc = readFileSync(resolve(import.meta.dirname, file), "utf8")
+      const match = doc.match(list)
+      expect(match, file).not.toBeNull()
+      return new Set([...match![1]!.matchAll(/`([a-z]+(?: [a-z]+)?)`/g)].map(([, name]) => name!))
+    }
+    expect(listed("../../README.md", /The `gtd` bin's commands — ([\s\S]*?) — are listed/)).toEqual(
+      commands,
+    )
+    expect(listed("../../COMPATIBILITY.md", /every command \(([\s\S]*?)\), option/)).toEqual(
+      commands,
+    )
+  })
+
+  it("docs/cli.md's Exit codes table, pinned beside the rendered help output, is exactly wire's frozen EXIT_CODES", () => {
+    const doc = readFileSync(resolve(import.meta.dirname, "../../docs/cli.md"), "utf8")
+    const match = doc.match(/### Exit codes\n\n[^\n]*\n[^\n]*\n\n((?:\|.*\n)+)/)
+    expect(match).not.toBeNull()
+    const table = match![1] ?? ""
+    const codes = [...table.matchAll(/\|\s*(\d+)(?:\s*\/\s*(\d+))?\s*\|/g)].flatMap(([, a, b]) =>
+      b !== undefined ? [Number(a), Number(b)] : [Number(a)],
+    )
+    expect(new Set(codes)).toEqual(EXIT_CODES)
+  })
+})
+
+interface Captured {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number | undefined
+  readonly layersBuilt: number
+}
+
+const capturingIo = (
+  layers: (verbose: boolean) => Layer.Layer<CommandRequirements>,
+): { io: CliIo; captured: () => Captured } => {
+  let stdout = ""
+  let stderr = ""
+  let exitCode: number | undefined
+  let layersBuilt = 0
+  const io: CliIo = {
+    stdout: (chunk) => {
+      stdout += chunk
+    },
+    stderr: (chunk) => {
+      stderr += chunk
+    },
+    exit: (code) => {
+      exitCode = code
+    },
+    layers: (verbose) => {
+      layersBuilt++
+      return layers(verbose)
+    },
+  }
+  return { io, captured: () => ({ stdout, stderr, exitCode, layersBuilt }) }
+}
+
+// Fails as soon as any property is accessed — proves `layers()` is never
+// asked to build a real service for --version/--help/a usage error.
+const throwingLayers = (): Layer.Layer<CommandRequirements> =>
+  Layer.effectDiscard(
+    Effect.sync(() => {
+      throw new Error("layers() must not be called")
+    }),
+  ) as Layer.Layer<CommandRequirements>
+
+describe("runCli — layers() is never invoked for output/usage plans", () => {
+  it("--version", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "--version"], io))
+    expect(captured().layersBuilt).toBe(0)
+  })
+
+  it("--help", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "--help"], io))
+    expect(captured().layersBuilt).toBe(0)
+  })
+
+  it("a usage error", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "bogus"], io))
+    expect(captured().layersBuilt).toBe(0)
+  })
+})
+
+describe("runCli — exit codes", () => {
+  it("output plan: exit is never called (success) — --help and --version still exit 0", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "--version"], io))
+    expect(captured().exitCode).toBeUndefined()
+    const { io: helpIo, captured: helpCaptured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "--help"], helpIo))
+    expect(helpCaptured().exitCode).toBeUndefined()
+  })
+
+  it("usage plan: exit(EXIT_USAGE_ERROR) — an unknown/missing/malformed invocation, never EXIT_RUNTIME_ERROR", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "bogus"], io))
+    expect(captured().exitCode).toBe(EXIT_USAGE_ERROR)
+  })
+
+  it("gtd ui --bogus exits EXIT_USAGE_ERROR (unknown flag)", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "ui", "--bogus"], io))
+    expect(captured().exitCode).toBe(EXIT_USAGE_ERROR)
+  })
+
+  it("--host on a non-ui command exits EXIT_USAGE_ERROR with a clear scopeError message", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "next", "--host", "x"], io))
+    const result = captured()
+    expect(result.exitCode).toBe(EXIT_USAGE_ERROR)
+    expect(result.stderr).toContain("only valid for `gtd ui`")
+  })
+
+  it("a command failure that is NOT a usage error still exits EXIT_RUNTIME_ERROR", async () => {
+    // Unlike a usage error (never builds a layer), a resolved command
+    // always does, so this exercises `report`'s own exit code.
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "next"], io))
+    expect(captured().exitCode).toBe(EXIT_RUNTIME_ERROR)
+  })
+
+  it("an unknown --json=<path> selector exits EXIT_USAGE_ERROR, not EXIT_RUNTIME_ERROR — Program.ts's SelectorUsageError mapped by report()", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("NOTE.md", "a note\n")
+    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.commitAllWithPrefix("gtd: init")
+    const { io, captured } = capturingIo(() => testLayers(repo))
+    await Effect.runPromise(runCli(["node", "gtd.js", "next", "--json=does.not.exist"], io))
+    const { stdout, stderr, exitCode } = captured()
+    expect(exitCode).toBe(EXIT_USAGE_ERROR)
+    expect(stdout).toBe("")
+    expect(stderr).toContain("does.not.exist")
+  })
+})
+
+describe("runCli — --json envelopes", () => {
+  it("a usage error under --json writes the envelope on stderr, leaving stdout byte-empty", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "bogus", "--json"], io))
+    const { stdout, stderr } = captured()
+    expect(stdout).toBe("")
+    const [envelopeLine] = stderr.split("\n")
+    const parsed = JSON.parse(envelopeLine!) as { state: string; prompt: string }
+    expect(parsed.state).toBe("error")
+    expect(stderr).toMatch(/gtd: [^\n]*\n$/)
+    expect(stderr).not.toContain("gtd: gtd:")
+  })
+
+  it("a runtime error under --json writes the envelope on stderr, leaving stdout byte-empty", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "next", "--json"], io))
+    const { stdout, stderr } = captured()
+    expect(stdout).toBe("")
+    const [envelopeLine] = stderr.split("\n")
+    const parsed = JSON.parse(envelopeLine!) as { state: string; prompt: string }
+    expect(parsed.state).toBe("error")
+  })
+})
+
+describe("runCli — stdout stays byte-empty on every failing surface", () => {
+  // A handler may write through `out` and still fail — `bufferedArtifactOut`'s
+  // buffer is simply never flushed, so `io.stdout` is never called at all.
+
+  it("usage error: stdout is byte-empty, the message lands on stderr", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "bogus"], io))
+    const { stdout, stderr } = captured()
+    expect(stdout).toBe("")
+    expect(stderr).toContain("unknown command")
+  })
+
+  it("refusal: a real command's own typed Effect.fail leaves stdout byte-empty", async () => {
+    const repo = new InMemRepo() // no commits yet — assertRepositoryHasCommits refuses
+    const { io, captured } = capturingIo(() => testLayers(repo))
+    await Effect.runPromise(runCli(["node", "gtd.js", "next"], io))
+    const { stdout, stderr, exitCode } = captured()
+    expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
+    expect(stdout).toBe("")
+    expect(stderr).toContain("gtd requires a repository with at least one commit")
+  })
+
+  it("runtime error: a handler's own Effect.fail (not the shared repo-root/commit guard) leaves stdout byte-empty", async () => {
+    // `gtd check` needs neither a repository nor a commit — this exercises a
+    // plain `FileSystem`-only failure inside the handler itself, distinct
+    // from the "refusal" test above (which fails in the shared guard).
+    const repo = new InMemRepo()
+    repo.writeFile(".gtd/TODO.md", "## Open Questions\n\n###\n\nno question text.\n")
+    const { io, captured } = capturingIo(() => testLayers(repo))
+    await Effect.runPromise(runCli(["node", "gtd.js", "check", "qa", ".gtd/TODO.md"], io))
+    const { stdout, stderr, exitCode } = captured()
+    expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
+    expect(stdout).toBe("")
+    expect(stderr).toContain("has no question text")
+  })
+
+  it("defect: an unchecked throw building the layer still leaves stdout byte-empty", async () => {
+    const { io, captured } = capturingIo(throwingLayers)
+    await Effect.runPromise(runCli(["node", "gtd.js", "next"], io))
+    const { stdout, stderr, exitCode } = captured()
+    expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
+    expect(stdout).toBe("")
+    expect(stderr).toContain("layers() must not be called")
+  })
+
+  it("unit: a failing command's collected buffer is never handed to io.stdout", async () => {
+    // Same failure as the "runtime error" case above, observed directly
+    // through `io.stdout` (a raw call-recording array) — a failing run must
+    // produce zero calls, not merely an empty joined string.
+    const repo = new InMemRepo()
+    repo.writeFile("README.md", "x\n")
+    repo.commitAllWithPrefix("chore: init gtd workflow")
+    repo.writeFile(".gtd/TODO.md", "## Open Questions\n\n###\n\nno question text.\n")
+    const stdoutCalls: string[] = []
+    const io: CliIo = {
+      stdout: (chunk) => stdoutCalls.push(chunk),
+      stderr: () => {},
+      exit: () => {},
+      layers: () => testLayers(repo),
+    }
+    await Effect.runPromise(runCli(["node", "gtd.js", "check", "qa", ".gtd/TODO.md"], io))
+    expect(stdoutCalls).toEqual([])
+  })
+})
+
+describe("nodeCliIo", () => {
+  const io = nodeCliIo(Layer.succeed(ToolCommands, {} as ToolCommands["Type"]))
+
+  it("exposes stdout/stderr/exit/layers", () => {
+    expect(typeof io.stdout).toBe("function")
+    expect(typeof io.stderr).toBe("function")
+    expect(typeof io.exit).toBe("function")
+    expect(typeof io.layers).toBe("function")
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("stdout writes through process.stdout.write with a completion callback, even when the write is queued (backpressure)", () => {
+    const write = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((_chunk: unknown, cb?: unknown) => {
+        if (typeof cb === "function") cb()
+        return false // the queued-data case
+      })
+    io.stdout("a large chunk")
+    expect(write).toHaveBeenCalledTimes(1)
+    const [chunk, cb] = write.mock.calls[0]!
+    expect(chunk).toBe("a large chunk")
+    expect(typeof cb).toBe("function")
+  })
+
+  it("exit sets process.exitCode rather than calling process.exit — an undrained stdout.write must not be torn down", () => {
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit must never be called on the normal path")
+    })
+    const before = process.exitCode
+    try {
+      io.exit(10)
+      expect(process.exitCode).toBe(10)
+      expect(exit).not.toHaveBeenCalled()
+    } finally {
+      process.exitCode = before
+    }
+  })
+})
+
+describe("normalizeTrailingNewline", () => {
+  it("leaves a byte-empty artifact byte-empty", () => {
+    expect(normalizeTrailingNewline("")).toBe("")
+  })
+
+  it("appends exactly one trailing newline to a non-empty artifact with none", () => {
+    expect(normalizeTrailingNewline("no newline yet")).toBe("no newline yet\n")
+  })
+
+  it("collapses several trailing newlines to exactly one", () => {
+    expect(normalizeTrailingNewline("content\n\n\n\n")).toBe("content\n")
+  })
+
+  it("leaves an artifact already ending in exactly one newline unchanged", () => {
+    expect(normalizeTrailingNewline("content\n")).toBe("content\n")
+  })
+})
+
+describe("runCli — flush normalizes the artifact's trailing newline", () => {
+  it("a plain-text write command's script (no trailing newline) reaches io.stdout with exactly one", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".gitignore", "node_modules\n")
+    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.commitAllWithPrefix("chore: initial commit")
+    const { io, captured } = capturingIo(() => testLayers(repo))
+    await Effect.runPromise(runCli(["node", "gtd.js", "land"], io))
+    const { stdout } = captured()
+    expect(stdout.length).toBeGreaterThan(0)
+    expect(stdout.endsWith("\n")).toBe(true)
+    expect(stdout.endsWith("\n\n")).toBe(false)
+  })
+})
+
+// Re-exported so downstream test files can build Command values without
+// importing from Program.js — keeps the type import exercised here too.
+export type { Command }