@pmelab/gtd 59.0.1 → 60.1.0

package/src/cli/Cli.test.ts

@@ -35,8 +35,8 @@ const FLAG_NAMES = [
   "--dev",
   "--cost",
   "--model",
-  "--workflow",
   "--var",
+  "--threshold",
   "--open-questions",
   "--open-threads",
   "--verbose",
@@ -105,13 +105,18 @@ describe("parseArgv — scope", () => {
     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", () => {
+  it("--json is in scope for next, land, the judge and script commands and the listings — every other command usage-errors on it", () => {
     for (const args of [
       ["next", "--json"],
       ["land", "--json"],
       ["judge", "--json"],
       ["judge", "answer", "--json"],
-      ["doors", "--json"],
+      ["validate", "--json"],
+      ["abandon", "--json"],
+      ["restore", "--json"],
+      ["start", "--json"],
+      ["start", "fix", "--json"],
+      ["history", "fetch", "--json"],
     ]) {
       const ok = parseArgv(["node", "gtd.js", ...args])
       expect(ok.kind).toBe("command")
@@ -120,18 +125,16 @@ describe("parseArgv — scope", () => {
 
     for (const args of [
       ["lsp", "--json"],
-      ["validate", "--json"],
       ["check", "qa", "TODO.md", "--json"],
-      ["install", "--json"],
-      ["abandon", "--json"],
-      ["restore", "--json"],
-      ["--workflow", "some-state", "--json"],
+      ["guide", "--json"],
+      ["summary", "--json"],
+      ["base", "--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")
+        expect(plan.message).toContain("gtd guide")
       }
     }
   })
@@ -167,38 +170,31 @@ describe("parseArgv — scope", () => {
     }
   })
 
-  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 (or `gtd history judges`)")
-  })
-
-  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("--var outside `gtd start` is rejected", () => {
+    for (const args of [
+      ["land", "--var", "a=1"],
+      ["history", "judges", "--var", "qualityTriageMinP=0.9"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage")
+        expect(plan.message).toBe("gtd: --var is only valid for `gtd start <name>`")
+    }
   })
 
-  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("--cost and --model on `gtd start` are rejected (landing and starting are different verbs)", () => {
+    for (const flag of ["--cost=5", "--model=gpt"]) {
+      const plan = parseArgv(["node", "gtd.js", "start", "foo", flag])
+      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"],
-    ]) {
+  it("--workflow is gone: an unknown option on its own and after any command", () => {
+    for (const args of [["--workflow", "e"], ["--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",
-        )
-      }
+      if (plan.kind === "usage") expect(plan.message).toContain("unknown option '--workflow")
     }
   })
 
@@ -370,13 +366,13 @@ describe("parseArgv — bare/unknown command under --json", () => {
     }
   })
 
-  it("bare gtd prints a short usage, not the overview, and points at gtd help and gtd install", () => {
+  it("bare gtd prints a short usage, not the overview, and points at gtd help and gtd guide", () => {
     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 help`")
-      expect(plan.message).toContain("gtd install")
+      expect(plan.message).toContain("gtd guide")
       expect(plan.stdout).toMatch(/^Usage: gtd <command>/)
       expect(plan.stdout.split("\n").length).toBeLessThan(10)
     }
@@ -435,43 +431,16 @@ describe("parseArgv — bare/unknown command under --json", () => {
   })
 })
 
-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"])
+describe("parseArgv — --var details", () => {
+  it("a second --var occurrence of one name is a usage error (not last-wins)", () => {
+    const plan = parseArgv(["node", "gtd.js", "start", "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])
+      const plan = parseArgv(["node", "gtd.js", "start", "e", "--var", raw])
       expect(plan.kind).toBe("usage")
       if (plan.kind === "usage") {
         expect(plan.message).toContain(
@@ -482,36 +451,25 @@ describe("parseArgv — entry/var flag details (formerly parseEntryFlags/takeFla
   })
 
   it("a multiline --var value is a usage error", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", "a=1\n2"])
+    const plan = parseArgv(["node", "gtd.js", "start", "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", () => {
+  it("is an ordinary unknown option", () => {
     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")
-    }
+    if (plan.kind === "usage") expect(plan.message).toContain("--entry")
   })
 })
 
-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 start <name>", () => {
+  it("a workflow named like a command word still parses to a start command", () => {
+    for (const name of ["version", "help"]) {
+      const plan = parseArgv(["node", "gtd.js", "start", name])
+      expect(plan.kind).toBe("command")
+      if (plan.kind === "command") expect(plan.command).toMatchObject({ kind: "start", name })
     }
   })
 })
@@ -720,7 +678,7 @@ describe("parseArgv — --verbose / -v (the -v/-V swap)", () => {
       ["land", "--verbose"],
       ["next", "--verbose", "--json"],
       ["check", "qa", "TODO.md", "--verbose"],
-      ["--workflow", "some-state", "--verbose"],
+      ["start", "some-state", "--verbose"],
     ]) {
       const plan = parseArgv(["node", "gtd.js", ...args])
       expect(plan.kind).toBe("command")
@@ -729,30 +687,39 @@ describe("parseArgv — --verbose / -v (the -v/-V swap)", () => {
   })
 })
 
-describe("parseArgv — gtd install", () => {
-  it("parses to an install command", () => {
-    const plan = parseArgv(["node", "gtd.js", "install"])
+describe("parseArgv — gtd guide", () => {
+  it("parses to a guide command", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide"])
     expect(plan.kind).toBe("command")
     if (plan.kind === "command") {
-      expect(plan.command).toEqual({ kind: "install" })
+      expect(plan.command).toEqual({ kind: "guide" })
       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("install, door and doors are gone: unknown commands", () => {
+    expect(parseArgv(["node", "gtd.js", "install"])).toMatchObject({
+      kind: "usage",
+      message: expect.stringContaining("unknown command 'install'"),
+    })
+    for (const word of ["door", "doors"]) {
+      expect(parseArgv(["node", "gtd.js", word, "fix"])).toMatchObject({
+        kind: "usage",
+        message: expect.stringContaining(`unknown command '${word}'`),
+      })
+    }
+    expect(parseArgv(["node", "gtd.js", "help", "install"]).kind).toBe("usage")
+    expect(renderHelp()).not.toMatch(/^ {2}(install|doors?)\b|--workflow|Older spellings/m)
   })
 
-  it("gtd install extra is a usage error (install takes no argument)", () => {
-    const plan = parseArgv(["node", "gtd.js", "install", "extra"])
+  it("gtd guide extra is a usage error (guide takes no argument)", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide", "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"])
+  it("a scoped-out flag (e.g. --port) is rejected on guide", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide", "--port=3"])
     expect(plan.kind).toBe("usage")
     if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd ui`")
   })
@@ -895,7 +862,7 @@ describe("parseArgv — gtd judge run", () => {
     [["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`"],
+    [["next", "--model", "x"], "`gtd land` (with --cost: the model to record the cost against)"],
     [["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`"],
@@ -908,59 +875,6 @@ describe("parseArgv — gtd judge run", () => {
   })
 })
 
-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 parses, so the loaded config can list its doors", () => {
-    expect(parse("door")).toMatchObject({ kind: "command", command: { kind: "door", args: [] } })
-  })
-
-  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("parseArgv — gtd history", () => {
   const parse = (...args: string[]) => parseArgv(["node", "gtd.js", ...args])
   const usage = (plan: CliPlan): string => (plan.kind === "usage" ? plan.message : "")
@@ -987,7 +901,7 @@ describe("parseArgv — gtd history", () => {
     expect(parse("history", "metrics", "a", "feat/b")).toMatchObject({
       command: { kind: "historyMetrics", refs: ["a", "feat/b"] },
     })
-    expect(parse("history", "judges", "a", "--var", "qualityTriageMinP=0.9")).toMatchObject({
+    expect(parse("history", "judges", "a", "--threshold", "qualityTriageMinP=0.9")).toMatchObject({
       command: {
         kind: "historyJudges",
         refs: ["a"],
@@ -1000,21 +914,40 @@ describe("parseArgv — gtd history", () => {
     })
   })
 
-  it("judges takes only judge thresholds as --var, and --jsonl alone", () => {
-    expect(usage(parse("history", "judges", "--var", "reviewBase=main"))).toContain(
-      "no judge threshold",
+  it("judges takes only judge thresholds as --threshold, and --jsonl alone", () => {
+    expect(
+      parse(
+        "history",
+        "judges",
+        "--threshold=qualityTriageMinP=0.9",
+        "--threshold",
+        "judgeIdenticalMinP=0.5",
+      ),
+    ).toMatchObject({
+      command: { vars: { qualityTriageMinP: "0.9", judgeIdenticalMinP: "0.5" } },
+    })
+    expect(usage(parse("history", "judges", "--threshold", "reviewBase=main"))).toBe(
+      "gtd history judges: --threshold reviewBase is no judge threshold — use judgeIdenticalMinP or qualityTriageMinP",
     )
-    expect(usage(parse("history", "judges", "--var", "toString=0.9"))).toContain(
+    expect(usage(parse("history", "judges", "--threshold", "toString=0.9"))).toContain(
       "no judge threshold",
     )
-    expect(usage(parse("history", "judges", "--var", "qualityTriageMinP=0,9"))).toContain(
-      "must be a number",
-    )
+    for (const value of ["x", "0,9"]) {
+      expect(usage(parse("history", "judges", "--threshold", `qualityTriageMinP=${value}`))).toBe(
+        `gtd history judges: --threshold qualityTriageMinP must be a number — got "${value}"`,
+      )
+    }
     expect(usage(parse("history", "judges", "--jsonl", "--json"))).toContain("mutually exclusive")
-    expect(usage(parse("history", "judges", "--jsonl", "--var", "qualityTriageMinP=1"))).toContain(
-      "mutually exclusive",
+    expect(
+      usage(parse("history", "judges", "--jsonl", "--threshold", "qualityTriageMinP=1")),
+    ).toContain("mutually exclusive")
+    expect(usage(parse("history", "metrics", "--threshold", "qualityTriageMinP=1"))).toContain(
+      "only valid for `gtd history judges`",
     )
     expect(usage(parse("history", "metrics", "--jsonl"))).toContain("only valid for")
+    const help = helpFor("help", "history", "judges")
+    expect(help).toContain("--threshold <name>=<value>")
+    expect(help).not.toContain("--var")
   })
 
   it("bare history and an unknown subcommand are usage errors naming list, show, metrics, fetch", () => {
@@ -1035,7 +968,7 @@ describe("parseArgv — gtd history", () => {
     expect(usage(parse("history", "fetch", "a", "b"))).toContain("too many arguments")
   })
 
-  it("--json is accepted for list, show and metrics, rejected for fetch", () => {
+  it("--json is accepted for list, show, metrics and fetch", () => {
     expect(parse("history", "list", "--json")).toMatchObject({ json: { kind: "document" } })
     expect(parse("history", "show", "x", "--json=ended")).toMatchObject({
       json: { kind: "select", path: "ended" },
@@ -1043,7 +976,9 @@ describe("parseArgv — gtd history", () => {
     expect(parse("history", "metrics", "--json=total.refactorFirstRate")).toMatchObject({
       json: { kind: "select", path: "total.refactorFirstRate" },
     })
-    expect(parse("history", "fetch", "--json").kind).toBe("usage")
+    expect(parse("history", "fetch", "--json=script")).toMatchObject({
+      json: { kind: "select", path: "script" },
+    })
   })
 
   it("help lists the four history rows", () => {
@@ -1056,6 +991,70 @@ describe("parseArgv — gtd history", () => {
   })
 })
 
+describe("parseArgv — gtd start", () => {
+  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
+
+  it("bare `gtd start` parses with no name, so the loaded config can list what starts", () => {
+    expect(parse("start")).toEqual({
+      kind: "command",
+      command: { kind: "start", args: [], vars: {} },
+      json: { kind: "off" },
+      verbose: false,
+    })
+    expect(parse("start", "--json")).toMatchObject({ json: { kind: "document" } })
+  })
+
+  it("carries the name, every positional after it, and the --var pins", () => {
+    expect(parse("start", "review", "main", "--var", "a=1", "--var=b=2")).toMatchObject({
+      command: { kind: "start", name: "review", args: ["main"], vars: { a: "1", b: "2" } },
+    })
+  })
+
+  it("--var with no name is a usage error", () => {
+    const plan = parse("start", "--var", "a=1")
+    expect(plan.kind === "usage" && plan.message).toContain("--var needs a <name>")
+  })
+
+  it("its help names doors, workflows, --var and the --json=script idiom", () => {
+    const help = helpFor("help", "start")
+    expect(help).toMatch(/^Usage: gtd start \[name\] \[args\.\.\.\] \[options\]\n/)
+    expect(help).toMatch(/A door\s+shadows a workflow of the same name/)
+    expect(help).toContain("--var <name>=<value>")
+    expect(help).toContain('s=$(gtd start <name> --json=script) && sh -c "$s"')
+  })
+})
+
+describe("parseArgv — -- ends the options", () => {
+  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
+
+  it("every word after -- is a positional, even one that looks like an option", () => {
+    expect(parse("strays", "a..b", "--", "--weird", "-x")).toMatchObject({
+      command: { kind: "strays", globs: ["--weird", "-x"] },
+    })
+    expect(parse("start", "fix", "--json=script", "--", "--var")).toMatchObject({
+      command: { kind: "start", name: "fix", args: ["--var"], vars: {} },
+      json: { kind: "select", path: "script" },
+    })
+  })
+
+  it("--help, -h, --version and -V after -- are arguments, not short-circuits", () => {
+    expect(parse("start", "fix", "--", "--help")).toMatchObject({
+      command: { kind: "start", args: ["--help"] },
+    })
+    expect(parse("start", "fix", "--", "-V").kind).toBe("command")
+    expect(parse("next", "--", "--version")).toMatchObject({ kind: "usage" })
+  })
+
+  it("a bare -- changes nothing", () => {
+    expect(parse("next", "--")).toEqual(parse("next"))
+  })
+
+  it("an option that needs a value never takes -- as it", () => {
+    const plan = parse("start", "fix", "--var", "--", "a=1")
+    expect(plan.kind === "usage" && plan.message).toContain("--var requires a value")
+  })
+})
+
 describe("parseArgv — gtd strays", () => {
   const strays = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", "strays", ...args])
 
@@ -1102,14 +1101,14 @@ describe("parseArgv — gtd strays", () => {
 
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
-    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "judgeRun", "strays"])
+    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "guide", "judgeRun", "strays"])
   })
 
   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("guide")).toBe("none")
     expect(needsOf("judgeRun")).toBe("none")
     expect(needsOf("strays")).toBe("none")
     for (const kind of [
@@ -1122,8 +1121,6 @@ describe("standaloneKinds / needsOf", () => {
       "ui",
       "judge",
       "judgeAnswer",
-      "door",
-      "doors",
       "historyList",
       "historyShow",
       "historyMetrics",
@@ -1151,14 +1148,14 @@ describe("renderHelp", () => {
     for (const heading of ["Core loop:", "Start and stop:", "Inspect:", "Driver plumbing:"]) {
       expect(help).toContain(`\n${heading}\n`)
     }
-    expect(help).toContain("--workflow <name>")
-    expect(help).toContain("--var")
+    expect(help).toContain("start [name] [args...]")
     expect(help).toContain("check <mode> <file>")
-    expect(help).toContain("door <name> [args...]")
     expect(help).toContain("-V, --version")
     expect(help).toContain("-h, --help")
     expect(help).toContain("Examples:")
     for (const removed of [
+      "--workflow",
+      "Older spellings",
       "visualize",
       ".gtdrc",
       "--no-open",
@@ -1168,7 +1165,7 @@ describe("renderHelp", () => {
     ]) {
       expect(help).not.toContain(removed)
     }
-    expect(help).not.toMatch(/^ {2}(init|serve)\b/m)
+    expect(help).not.toMatch(/^ {2}(init|serve|install|door|doors)\b/m)
     expect(help).toMatch(/\n$/)
   })
 
@@ -1206,7 +1203,10 @@ describe("renderHelp", () => {
 
   it("a flag that means something else per command is described per command", () => {
     expect(helpFor("help", "land")).toContain("With --cost: the model")
+    expect(helpFor("help", "land")).toContain("nothing runs on it")
     expect(helpFor("help", "judge", "run")).toContain("The claude model")
+    expect(helpFor("help", "abandon")).toContain("Print { schema, script }")
+    expect(helpFor("help", "next")).not.toContain("Print { schema, script }")
   })
 
   it("--help after an unknown command still prints the overview", () => {
@@ -1361,17 +1361,18 @@ describe("runCli — a garbled GTD_FLAG_* value", () => {
 })
 
 describe("runCli — StartFlags", () => {
-  const CONFIG = `import { agent, human } from "@pmelab/gtd/flows"
+  const CONFIG = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle")
 }
 
-export const side = async () => {
-  await agent("working", "w")
-}
-
-export const defaults = { flag_beta: "0" }
+export const side = workflow(
+  async () => {
+    await agent("working", "w")
+  },
+  { defaults: { flag_beta: "0" } },
+)
 `
   const BETA = { name: "beta", owner: "pmelab", expiry: "2099-01-01", kind: "release" } as const
   const start = async (
@@ -1383,7 +1384,7 @@ export const defaults = { flag_beta: "0" }
     repo.seedCommit("chore: add workflow")
     const { io, result } = makeCapturingCliIo(repo, env)
     await Effect.runPromise(
-      runCli(["node", "gtd.js", "--workflow", "side"], { ...io, ...(flags ? { flags } : {}) }),
+      runCli(["node", "gtd.js", "start", "side"], { ...io, ...(flags ? { flags } : {}) }),
     )
     return result().stdout
   }
@@ -1536,7 +1537,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
     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),
+      stdout: (chunk) => stdoutCalls.push(String(chunk)),
       stderr: () => {},
       exit: () => {},
       layers: () => testLayers(repo),
@@ -1547,7 +1548,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
 })
 
 describe("nodeCliIo", () => {
-  const io = nodeCliIo(Layer.succeed(ToolCommands, {} as ToolCommands["Type"]))
+  const io = nodeCliIo(Layer.succeed(ToolCommands, {} as ToolCommands["Service"]))
 
   it("exposes stdout/stderr/exit/layers", () => {
     expect(typeof io.stdout).toBe("function")