@pmelab/gtd 59.0.0 → 59.0.1

package/dist/testkit/gherkin.mjs

@@ -1,9 +1,66 @@
-import { n as testRepo, t as runsItsScript } from "../chunks/testkit-CMBAAyRK.mjs";
+import { n as testRepo, t as runsItsScript } from "../chunks/testkit-07Z_ENch.mjs";
 import { resolve } from "node:path";
 import assert from "node:assert";
 import { pathToFileURL } from "node:url";
 import { Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";
+//#region src/gherkin/messages.ts
+const CONTENT_LINES = 5;
+const reason = (error) => error instanceof Error ? error.message : String(error);
+const beatLines = async (repo) => {
+	try {
+		const beat = await repo.next();
+		const content = beat.content.trimEnd().split("\n");
+		const more = content.length - CONTENT_LINES;
+		return [
+			`step "${beat.state}" (${beat.kind}, ${beat.actor}${beat.idle ? ", idle" : ""})`,
+			"content:",
+			...content.slice(0, CONTENT_LINES).map((line) => `  | ${line}`),
+			...more > 0 ? [`  | … ${more} more lines`] : []
+		];
+	} catch (error) {
+		return [`unknown — gtd next failed: ${reason(error)}`];
+	}
+};
+/** Where the process rests, for a failed outcome to end with. Never throws: it describes a failure. */
+const restDescription = async (repo, neverUsed) => {
+	let lines;
+	try {
+		const r = repo();
+		lines = [
+			...await beatLines(r),
+			"last commits:",
+			...r.subjects().slice(-5).map((subject) => `  ${subject}`)
+		];
+	} catch (error) {
+		lines = [`unknown — ${reason(error)}`];
+	}
+	if (neverUsed.length > 0) lines.push(`actors never used: ${neverUsed.map((step) => `"${step}"`).join(", ")}`);
+	return ["where the process rests:", ...lines.map((line) => `  ${line}`)].join("\n");
+};
+/** Both sides of a failed `contains`: the text looked for, and what was there. */
+const containsFailure = (where, text, content, expected) => content === void 0 ? `${where} does not exist${expected ? `, so it cannot contain "${text}"` : ""}` : `${where} ${expected ? "does not contain" : "contains"} "${text}"; it holds:\n${content}`;
+/** What `attempt` was refused with; fails when it was not refused at all. */
+const refusal = async (attempt, expectation) => {
+	try {
+		await attempt;
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	assert.fail(`expected a refusal ${expectation}, but nothing was refused`);
+};
+const refusedWith = async (attempt, message) => {
+	const got = await refusal(attempt, `with "${message}"`);
+	if (!got.includes(message)) assert.fail(`expected a refusal with "${message}", but it was refused with:\n${got}`);
+};
+const assertContains = (where, text, content) => {
+	if (content === void 0 || !content.includes(text)) assert.fail(containsFailure(where, text, content, true));
+};
+const assertLacks = (where, text, content) => {
+	if (content === void 0 || content.includes(text)) assert.fail(containsFailure(where, text, content, false));
+};
+//#endregion
 //#region src/gherkin/index.ts
+const usedActors = /* @__PURE__ */ new WeakMap();
 var TestkitWorld = class extends QuickPickleWorld {
 	constructor(context, info) {
 		super(context, info);
@@ -51,6 +108,8 @@ var TestkitWorld = class extends QuickPickleWorld {
 	}
 	async drive() {
 		const actors = {};
+		const used = usedActors.get(this) ?? /* @__PURE__ */ new Set();
+		usedActors.set(this, used);
 		for (const [step, actions] of this.actions) actors[step] = async (beat, repo) => {
 			for (const action of actions) await action(beat, repo);
 		};
@@ -67,12 +126,35 @@ var TestkitWorld = class extends QuickPickleWorld {
 				return hit[1];
 			};
 		}
-		await this.repo().drive(actors);
+		const tracked = {};
+		for (const [step, actor] of Object.entries(actors)) tracked[step] = (beat, repo) => {
+			used.add(step);
+			return actor(beat, repo);
+		};
+		await this.repo().drive(tracked);
 	}
 };
 setWorldConstructor(TestkitWorld);
 const withNewline = (content) => content.endsWith("\n") ? content : `${content}\n`;
 const args = (list) => list.split(" ").filter((arg) => arg !== "");
+const neverUsed = (world) => {
+	const used = usedActors.get(world) ?? /* @__PURE__ */ new Set();
+	return [.../* @__PURE__ */ new Set([
+		...world.actions.keys(),
+		...world.verdicts.keys(),
+		...world.conditionalVerdicts.keys()
+	])].filter((step) => !used.has(step));
+};
+/** An outcome step: a failure ends with where the process rests. */
+const outcome = (check) => async (world, ...rest) => {
+	try {
+		await check(world, ...rest);
+	} catch (error) {
+		const failure = error instanceof Error ? error : new Error(String(error));
+		failure.message += `\n\n${await restDescription(() => world.repo(), neverUsed(world))}`;
+		throw failure;
+	}
+};
 Given("a gtd config with:", (world, source) => {
 	world.configure(withNewline(source));
 });
@@ -197,87 +279,85 @@ When("gtd lands", async (world) => {
 When("the process is driven", async (world) => {
 	await world.drive();
 });
-Then("opening door {string} is refused with {string}", async (world, door, message) => {
-	await assert.rejects(world.repo().door(door), (error) => error.message.includes(message));
-});
-Then("starting workflow {string} with {string} is refused with {string}", async (world, workflow, list, message) => {
-	await assert.rejects(world.repo().start(workflow, ...args(list)), (error) => error.message.includes(message));
-});
-Then("landing is refused with {string}", async (world, message) => {
-	await assert.rejects(world.repo().land(), (error) => error.message.includes(message));
-});
-Then("driving the process is refused with {string}", async (world, message) => {
-	await assert.rejects(world.drive(), (error) => error.message.includes(message));
-});
-Then("driving the process is refused without {string}", async (world, message) => {
-	await assert.rejects(world.drive(), (error) => !error.message.includes(message));
-});
-Then("the process rests at {string}", async (world, step) => {
+Then("opening door {string} is refused with {string}", outcome(async (world, door, message) => {
+	await refusedWith(world.repo().door(door), message);
+}));
+Then("starting workflow {string} with {string} is refused with {string}", outcome(async (world, workflow, list, message) => {
+	await refusedWith(world.repo().start(workflow, ...args(list)), message);
+}));
+Then("landing is refused with {string}", outcome(async (world, message) => {
+	await refusedWith(world.repo().land(), message);
+}));
+Then("driving the process is refused with {string}", outcome(async (world, message) => {
+	await refusedWith(world.drive(), message);
+}));
+Then("driving the process is refused without {string}", outcome(async (world, message) => {
+	const got = await refusal(world.drive(), `without "${message}"`);
+	if (got.includes(message)) assert.fail(`expected a refusal without "${message}", but it was refused with:\n${got}`);
+}));
+Then("the process rests at {string}", outcome(async (world, step) => {
 	assert.strictEqual((await world.repo().next()).state, step);
-});
-Then("the resting step's content contains {string}", async (world, text) => {
-	const { content } = await world.repo().next();
-	assert.ok(content.includes(text), content);
-});
-Then("the resting step's content contains the hash of the commit {string}", async (world, subject) => {
+}));
+Then("the resting step's content contains {string}", outcome(async (world, text) => {
+	assertContains("the resting step's content", text, (await world.repo().next()).content);
+}));
+Then("the resting step's content contains the hash of the commit {string}", outcome(async (world, subject) => {
 	const repo = world.repo();
 	const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)];
 	assert.ok(hash !== void 0, `no commit "${subject}"`);
-	const { content } = await repo.next();
-	assert.ok(content.includes(hash), content);
-});
-Then("the resting step's content does not contain {string}", async (world, text) => {
-	const { content } = await world.repo().next();
-	assert.ok(!content.includes(text), content);
-});
-Then("the last commit subject is {string}", (world, subject) => {
+	assertContains("the resting step's content", hash, (await repo.next()).content);
+}));
+Then("the resting step's content does not contain {string}", outcome(async (world, text) => {
+	assertLacks("the resting step's content", text, (await world.repo().next()).content);
+}));
+Then("the last commit subject is {string}", outcome((world, subject) => {
 	assert.strictEqual(world.repo().subjects().at(-1), subject);
-});
-Then("the commit subjects end with:", (world, list) => {
+}));
+Then("the commit subjects end with:", outcome((world, list) => {
 	const expected = list.split("\n").filter((line) => line.trim() !== "");
 	assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected);
-});
+}));
 const outputOf = async (world, list) => {
 	const result = await world.repo().gtd(...args(list));
 	assert.strictEqual(result.exitCode, 0, result.stderr);
 	return result.stdout;
 };
-Then("the output of gtd {string} contains {string}", async (world, list, text) => {
-	const out = await outputOf(world, list);
-	assert.ok(out.includes(text), out);
-});
-Then("the output of gtd {string} does not contain {string}", async (world, list, text) => {
-	const out = await outputOf(world, list);
-	assert.ok(!out.includes(text), out);
-});
-Then("the output lines of gtd {string} start with:", async (world, list, prefixes) => {
+Then("the output of gtd {string} contains {string}", outcome(async (world, list, text) => {
+	assertContains(`the output of gtd ${list}`, text, await outputOf(world, list));
+}));
+Then("the output of gtd {string} does not contain {string}", outcome(async (world, list, text) => {
+	assertLacks(`the output of gtd ${list}`, text, await outputOf(world, list));
+}));
+Then("the output lines of gtd {string} start with:", outcome(async (world, list, prefixes) => {
 	const out = (await outputOf(world, list)).split("\n").filter((line) => line !== "");
 	const expected = prefixes.split("\n").filter((line) => line.trim() !== "");
-	assert.strictEqual(out.length, expected.length, out.join("\n"));
-	out.forEach((line, i) => assert.ok(line.startsWith(expected[i]), out.join("\n")));
-});
-Then("{string} contains {string}", (world, path, text) => {
-	assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`);
-});
-Then("{string} contains:", (world, path, text) => {
-	assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`);
-});
-Then("{string} contains the short hash of the commit {string}", (world, path, subject) => {
+	const sides = `expected lines starting with:\n${expected.join("\n")}\ngot:\n${out.join("\n")}`;
+	assert.strictEqual(out.length, expected.length, sides);
+	out.forEach((line, i) => assert.ok(line.startsWith(expected[i]), sides));
+}));
+Then("{string} contains {string}", outcome((world, path, text) => {
+	assertContains(`"${path}"`, text, world.repo().read(path));
+}));
+Then("{string} contains:", outcome((world, path, text) => {
+	assertContains(`"${path}"`, text, world.repo().read(path));
+}));
+Then("{string} contains the short hash of the commit {string}", outcome((world, path, subject) => {
 	const repo = world.repo();
 	const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)];
 	assert.ok(hash !== void 0, `no commit "${subject}"`);
-	assert.ok(repo.read(path)?.includes(hash.slice(0, 7)), `${path}: ${repo.read(path)}`);
-});
-Then("{string} contains {string} exactly once", (world, path, text) => {
+	assertContains(`"${path}"`, hash.slice(0, 7), repo.read(path));
+}));
+Then("{string} contains {string} exactly once", outcome((world, path, text) => {
 	const content = world.repo().read(path) ?? "";
-	assert.strictEqual(content.split(text).length - 1, 1, `${path}: ${content}`);
-});
-Then("{string} does not contain {string}", (world, path, text) => {
+	const times = content.split(text).length - 1;
+	assert.strictEqual(times, 1, `"${path}" contains "${text}" ${times} times; it holds:\n${content}`);
+}));
+Then("{string} does not contain {string}", outcome((world, path, text) => {
+	assertLacks(`"${path}"`, text, world.repo().read(path));
+}));
+Then("{string} does not exist", outcome((world, path) => {
 	const content = world.repo().read(path);
-	assert.ok(content !== void 0 && !content.includes(text), `${path}: ${content}`);
-});
-Then("{string} does not exist", (world, path) => {
-	assert.strictEqual(world.repo().read(path), void 0);
-});
+	assert.strictEqual(content, void 0, `"${path}" exists; it holds:\n${content}`);
+}));
 //#endregion
 export { TestkitWorld };

package/dist/testkit.mjs

@@ -1,2 +1,2 @@
-import { n as testRepo, r as InMemRepo, t as runsItsScript } from "./chunks/testkit-CMBAAyRK.mjs";
+import { n as testRepo, r as InMemRepo, t as runsItsScript } from "./chunks/testkit-07Z_ENch.mjs";
 export { InMemRepo, runsItsScript, testRepo };

package/dist/wire.mjs

@@ -1,2 +1,2 @@
-import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-C12dahrH.mjs";
+import { C as EXIT_SIGTERM, D as UNATTRIBUTED_MODEL, E as ACCESS_REFUSAL, O as WIRE_SCHEMA, S as EXIT_SIGINT, T as EXIT_USAGE_ERROR, _ as demandOf, a as landFields, b as EXIT_OK, c as renderLandJson, d as renderBeatPlain, f as beatDocument, g as beatKindOf, h as BEAT_KINDS, i as judgeJson, k as renderFormat, l as renderLandPlain, m as statusOf, n as resolveSession, o as landProseText, p as renderBeatJson, r as selectPath, s as noopText, t as globMatches, u as DEMAND_BRIEFING, v as stallDiagnosis, w as EXIT_STRAYS_FOUND, x as EXIT_RUNTIME_ERROR, y as EXIT_CODES } from "./chunks/wire-BTUhRGXj.mjs";
 export { ACCESS_REFUSAL, BEAT_KINDS, DEMAND_BRIEFING, EXIT_CODES, EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_SIGINT, EXIT_SIGTERM, EXIT_STRAYS_FOUND, EXIT_USAGE_ERROR, UNATTRIBUTED_MODEL, WIRE_SCHEMA, beatDocument, beatKindOf, demandOf, globMatches, judgeJson, landFields, landProseText, noopText, renderBeatJson, renderBeatPlain, renderFormat, renderLandJson, renderLandPlain, resolveSession, selectPath, stallDiagnosis, statusOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "59.0.0",
+  "version": "59.0.1",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/skills/authoring/SKILL.md

@@ -139,7 +139,7 @@ inside. Skills are declared per scope, never on `agent()`, and a driver
 restricts each turn to its scope's list where it can. `refuse(message)` refuses
 the pending landing — call it right after the step whose turn you reject.
 `@pmelab/gtd/flows` exports `requireProgress(file)`, `requireAnswers(file)` and
-`requireRevert(edited, base)`, three such checks ready-made.
+`requireRevert(edited, base)` among its ready-made checks.
 
 ## Names, commits and history
 
@@ -206,7 +206,8 @@ divergence later.
   network or filesystem. Read the tree through the helpers; do IO inside a
   `run()` body.
 - Await only a step, `scope()`, or a function that steps. Anything else fails
-  with `the flow awaited something that is not a step`.
+  with `the flow awaited something that is not a step`. gtd does not flag a step
+  you forget to await — turn on a `no-floating-promises` lint rule.
 - One call site per step name — wrap a reused helper in two different
   `scope()`s.
 - No `try`/`catch` around a step: `restart()` and refusals travel as exceptions.

package/src/cli/Cli.test.ts

@@ -71,7 +71,8 @@ describe("parseArgv — unknown options", () => {
     expect(plan).toEqual({
       kind: "usage",
       stdout: "",
-      message: "gtd: unknown option '--jsn' — see `gtd --help`",
+      message:
+        "gtd: unknown option '--jsn' — did you mean `--json`? Run `gtd help <command>` for its options",
       json: false,
     })
   })
@@ -369,17 +370,52 @@ describe("parseArgv — bare/unknown command under --json", () => {
     }
   })
 
-  it("bare gtd's missing-command message (no --json) points at gtd install, not a bundled loop", () => {
+  it("bare gtd prints a short usage, not the overview, and points at gtd help and gtd install", () => {
     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 help`")
       expect(plan.message).toContain("gtd install")
-      expect(plan.message).toContain("A complete minimal driver")
+      expect(plan.stdout).toMatch(/^Usage: gtd <command>/)
+      expect(plan.stdout.split("\n").length).toBeLessThan(10)
     }
   })
 
+  it("an unknown command that looks like a typo names the nearest command", () => {
+    expect(parseArgv(["node", "gtd.js", "nxt"])).toEqual({
+      kind: "usage",
+      stdout: "",
+      message:
+        "gtd: unknown command 'nxt' — did you mean `gtd next`? Run `gtd help` for every command",
+      json: false,
+    })
+  })
+
+  it("an unknown command nothing resembles points at gtd help only", () => {
+    const plan = parseArgv(["node", "gtd.js", "frobnicate"])
+    expect(plan.kind === "usage" && plan.message).toBe(
+      "gtd: unknown command 'frobnicate' — run `gtd help` for every command",
+    )
+  })
+
+  it("a mistyped history subcommand names the nearest one", () => {
+    const plan = parseArgv(["node", "gtd.js", "history", "shwo"])
+    expect(plan.kind === "usage" && plan.message).toContain("did you mean `gtd history show`?")
+  })
+
+  it("a bare --json followed by a word suggests the = form", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json", "kind"])
+    expect(plan.kind === "usage" && plan.message).toBe(
+      "gtd next: too many arguments — expected none, got: kind — to print one field, write --json=kind",
+    )
+  })
+
+  it("an unknown single-dash option is an unknown option, not an extra argument", () => {
+    const plan = parseArgv(["node", "gtd.js", "-j", "next"])
+    expect(plan.kind === "usage" && plan.message).toContain("unknown option '-j'")
+  })
+
   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")
@@ -891,10 +927,8 @@ describe("parseArgv — doors", () => {
     })
   })
 
-  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 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", () => {
@@ -1061,7 +1095,8 @@ describe("parseArgv — gtd strays", () => {
     const plan = parseArgv(["node", "gtd.js", "lsp", "--json"])
     if (plan.kind === "usage") expect(plan.message).toContain("`gtd strays`")
     expect(renderHelp()).toContain("strays <range> [glob...]")
-    expect(renderHelp()).toContain("gtd strays only")
+    const help = parseArgv(["node", "gtd.js", "help", "strays"])
+    expect(help.kind === "output" && help.stdout).toContain("--json[=<path>]")
   })
 })
 
@@ -1100,56 +1135,93 @@ describe("standaloneKinds / needsOf", () => {
   })
 })
 
+const helpFor = (...args: string[]): string => {
+  const plan = parseArgv(["node", "gtd.js", ...args])
+  if (plan.kind !== "output") throw new Error(`no help for ${args.join(" ")}`)
+  return plan.stdout
+}
+
+/** The command names the overview lists — `  name ` lines, as the docs pins read them. */
+const listedCommands = (): string[] =>
+  [...renderHelp().matchAll(/^ {2}([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)(?= )/gm)].map(([, n]) => n!)
+
 describe("renderHelp", () => {
-  it("mentions every command and flag, and no removed surface", () => {
+  it("groups the commands and mentions no removed surface", () => {
     const help = renderHelp()
-    expect(help).toContain("Usage")
-    expect(help).toContain("land")
+    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("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).toContain("door <name> [args...]")
+    expect(help).toContain("-V, --version")
+    expect(help).toContain("-h, --help")
+    expect(help).toContain("Examples:")
+    for (const removed of [
+      "visualize",
+      ".gtdrc",
+      "--no-open",
+      "--debug",
+      "--dispatch",
+      "bin/gtd",
+    ]) {
+      expect(help).not.toContain(removed)
+    }
+    expect(help).not.toMatch(/^ {2}(init|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("keeps every line of every help text within 80 columns", () => {
+    for (const text of [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))]) {
+      for (const line of text.split("\n")) expect(line.length, line).toBeLessThanOrEqual(80)
+    }
+  })
+
+  it("names no internals", () => {
+    const all = [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))].join("")
+    for (const internal of ["it.processCost", "refs/worktree/gtd/history", "Effect Schema"]) {
+      expect(all).not.toContain(internal)
+    }
+  })
+
+  it("every flag is in the help of a command it is valid for", () => {
+    const all = [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))].join("")
+    for (const name of FLAG_NAMES) expect(all).toContain(name)
+  })
+
+  it("gtd <cmd> --help, gtd <cmd> -h and gtd help <cmd> print that command's own help", () => {
+    const help = helpFor("help", "land")
+    expect(help).toMatch(/^Usage: gtd land \[options\]\n/)
+    expect(help).toContain("--cost=<n>")
+    expect(help).not.toContain("--port")
+    expect(helpFor("land", "--help")).toBe(help)
+    expect(helpFor("land", "-h")).toBe(help)
+  })
+
+  it("a two-word command's help is its own", () => {
+    expect(helpFor("judge", "run", "--help")).toMatch(/^Usage: gtd judge run \[options\]/)
+    expect(helpFor("help", "history", "show")).toMatch(/^Usage: gtd history show <ref>/)
+  })
+
+  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", "judge", "run")).toContain("The claude model")
+  })
+
+  it("--help after an unknown command still prints the overview", () => {
+    expect(helpFor("bogus", "--help")).toBe(renderHelp())
+  })
+
+  it("gtd help <unknown> is a usage error naming the nearest command", () => {
+    const plan = parseArgv(["node", "gtd.js", "help", "lnad"])
+    expect(plan).toEqual({
+      kind: "usage",
+      stdout: "",
+      message:
+        "gtd: help: no command 'lnad' — did you mean `gtd help land`? Run `gtd help` for every command",
+      json: false,
+    })
   })
 
   it("the docs/cli.md Commands fenced block equals renderHelp()", () => {
@@ -1159,6 +1231,15 @@ describe("renderHelp", () => {
     expect(match![1] + "\n").toBe(renderHelp())
   })
 
+  it("docs/cli.md's Every command section is every command's help, in the overview's order", () => {
+    const doc = readFileSync(resolve(import.meta.dirname, "../../docs/cli.md"), "utf8")
+    const section = doc.slice(doc.indexOf("\n## Every command\n"))
+    const documented = [...section.matchAll(/^### `gtd ([^`]+)`\n\n```\n([\s\S]*?)```\n/gm)].map(
+      ([, name, help]) => [name, help],
+    )
+    expect(documented).toEqual(listedCommands().map((name) => [name, helpFor("help", name)]))
+  })
+
   it("README.md and COMPATIBILITY.md list exactly the commands", () => {
     const commands = new Set(
       [...renderHelp().matchAll(/^ {2}([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)(?= )/gm)].map(
@@ -1419,7 +1500,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
     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")
+    expect(stderr).toContain("gtd: the repository has no commits yet")
   })
 
   it("runtime error: a handler's own Effect.fail (not the shared repo-root/commit guard) leaves stdout byte-empty", async () => {