@pmelab/gtd 58.2.0 → 59.0.1

package/dist/testkit/gherkin.mjs

@@ -1,9 +1,66 @@
-import { n as testRepo, t as runsItsScript } from "../chunks/testkit-JDtpNKyi.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-JDtpNKyi.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": "58.2.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": {
@@ -27,41 +27,6 @@
       "source": "./src/workflow-kit/index.ts",
       "default": "./dist/workflow-kit.mjs"
     },
-    "./workflows": {
-      "types": "./src/workflows/index.ts",
-      "source": "./src/workflows/index.ts",
-      "default": "./dist/workflows.mjs"
-    },
-    "./workflows/feature": {
-      "types": "./src/workflows/feature/index.ts",
-      "source": "./src/workflows/feature/index.ts",
-      "default": "./dist/workflows/feature.mjs"
-    },
-    "./workflows/review": {
-      "types": "./src/workflows/review/index.ts",
-      "source": "./src/workflows/review/index.ts",
-      "default": "./dist/workflows/review.mjs"
-    },
-    "./workflows/fix": {
-      "types": "./src/workflows/fix/index.ts",
-      "source": "./src/workflows/fix/index.ts",
-      "default": "./dist/workflows/fix.mjs"
-    },
-    "./workflow": {
-      "types": "./src/workflows/index.ts",
-      "source": "./src/workflows/index.ts",
-      "default": "./dist/workflows.mjs"
-    },
-    "./workflows/rollout": {
-      "types": "./src/workflows/rollout/index.ts",
-      "source": "./src/workflows/rollout/index.ts",
-      "default": "./dist/workflows/rollout.mjs"
-    },
-    "./workflows/cleanup": {
-      "types": "./src/workflows/cleanup/index.ts",
-      "source": "./src/workflows/cleanup/index.ts",
-      "default": "./dist/workflows/cleanup.mjs"
-    },
     "./testkit": {
       "types": "./src/testkit/index.ts",
       "source": "./src/testkit/index.ts",
@@ -76,7 +41,6 @@
   "files": [
     "dist/",
     "src/flows/",
-    "src/workflows/",
     "src/workflow-kit/",
     "src/wire/",
     "src/steering/",
@@ -119,7 +83,7 @@
   "scripts": {
     "prepare": "husky",
     "dev": "node dev/run.mjs",
-    "build": "tsdown --filter web && npx @tailwindcss/cli -i src/web/styles.css -o dist/web/main.css --minify && node scripts/inline-web-client.mjs && tsdown --filter gtd && tsdown --filter workflows && tsdown --filter entrypoints",
+    "build": "tsdown --filter web && npx @tailwindcss/cli -i src/web/styles.css -o dist/web/main.css --minify && node scripts/inline-web-client.mjs && tsdown --filter gtd && tsdown --filter entrypoints",
     "postbuild": "node scripts/assert-no-test-doubles.mjs",
     "watch": "tsdown --watch",
     "bench:replay": "node scripts/bench-replay.mjs",
@@ -141,9 +105,7 @@
     "analyze": "fallow --summary --quiet",
     "test:web": "vitest run --project storybook",
     "storybook": "storybook dev --host 0.0.0.0",
-    "coverage": "vitest run --project unit --coverage",
-    "eval": ": \"${GTD_EVALS_URL:?GTD_EVALS_URL is required — the OpenAI-compatible gateway every graded turn and the judge run through}\" && : \"${GTD_EVALS_KEY:?GTD_EVALS_KEY is required — the gateway bearer key}\" && npx turbo run build && node evals/eval.mjs",
-    "eval:baseline": "node evals/compare-baseline.mjs --record"
+    "coverage": "vitest run --project unit --coverage"
   },
   "lint-staged": {
     "*": "oxfmt --no-error-on-unmatched-pattern --write"
@@ -184,7 +146,6 @@
     "oxlint": "^1.74.0",
     "playwright": "^1.62.1",
     "prettier": "^3.8.1",
-    "promptfoo": "0.122.1",
     "quickpickle": "1.11.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

package/skills/authoring/SKILL.md

@@ -29,20 +29,25 @@ what a driver does.
 state (`gtd next`, `gtd lsp`, `gtd door` and `gtd doors` included). It is code
 the user's repository runs; write it with the same care as a build script.
 
-## Golden rule: start from the shipped workflows, edit incrementally
+## Golden rule: start from an existing workflow, edit incrementally
 
 Do **not** write a workflow from a blank page unless the user wants something
-tiny. gtd ships three workflows (`feature`, `review`, `fix`) as named exports of
-`@pmelab/gtd/workflows`; `gtd install` scaffolds a `gtd.config.ts` re-exporting
-them. Its default export is `feature` (the ordinary start), and every phase and
-single step they are built from is a named export too. Start by importing what
-you keep and writing only what changes. Import phases by name; **never
+tiny. gtd ships no workflow; https://github.com/pmelab/gtd-workflows does. Its
+`default` (feature, review, fix, rollout, cleanup) is used from a checkout
+pinned on the machine — `bin/gtd-wf pin` there, then `bin/gtd-wf config default`
+prints a `gtd.config.ts` importing its bundle by absolute path. Every phase and
+single step that bundle is built from is a named export too, so a config can
+import what it keeps and write only what changes. Import phases by name; **never
 `export *` from it** — every exported function of your file would become a
 startable workflow:
 
 ```ts
 import { start } from "@pmelab/gtd/flows"
-import { afterTail, buildTail, feature } from "@pmelab/gtd/workflows"
+import {
+  afterTail,
+  buildTail,
+  feature,
+} from "/home/me/.local/share/gtd/workflows/dist/default.mjs"
 
 export {
   defaults,
@@ -51,9 +56,9 @@ export {
   base,
   steering,
   skills,
-} from "@pmelab/gtd/workflows"
+} from "/home/me/.local/share/gtd/workflows/dist/default.mjs"
 
-export default feature
+export default feature()
 
 export async function hotfix() {
   return afterTail(await buildTail(start(), { fixFirst: true }))
@@ -62,21 +67,22 @@ export async function hotfix() {
 export const doors = { hotfix: { workflow: "hotfix" } }
 ```
 
-`gtd --workflow hotfix` (or `gtd door hotfix`) starts it.
+`gtd --workflow hotfix` (or `gtd door hotfix`) starts it. Use the checkout's
+real path; `gtd-wf status` shows it.
 
-To change a phase itself, read its source in the npm package
-(`node_modules/@pmelab/gtd/src/workflows/`, or under `$(npm root -g)` for a
-global install) and write your own version in `gtd.config.ts`, reusing its
-single steps.
+To change a phase itself, read its source in the checkout (`workflows/default/`)
+and either write your own version in `gtd.config.ts`, reusing its single steps,
+or copy the whole workflow in a clone of gtd-workflows
+(`bin/gtd-wf new <name> --from default`) and change it there, with its tests.
 
 There is no `extends`/merge: the innermost `gtd.config.ts` walking up from the
 current directory is the whole workflow. If one already exists, read it and edit
 it in place.
 
-Prefer the bundled workflow's own parts over re-implementing them — `healthy`,
+Prefer the workflow's own parts over re-implementing them — `healthy`,
 `escalation`, `gate`, `design`, `seamBuild`, `implement`, `qualityLap`,
 `buildTail`, and single steps like `triage` or `fixCheck`. Their full step names
-are versioned API.
+are that workflow's versioned API, not gtd's.
 
 Make one small change, **verify it loads** (see "Verify"), then make the next. A
 workflow that fails to load breaks every gtd command in the repository.
@@ -133,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
 
@@ -142,15 +148,15 @@ the pending landing — call it right after the step whose turn you reject.
   the last dot). Rename a step and every process resting on it diverges.
 - An episode ends when the flow returns or calls `restart()`; the next starts at
   the flow's first step on an ordinary start — that step is where a finished
-  process waits (the bundled one is `human("idle", …)`).
+  process waits (gtd-workflows' default uses `human("idle", …)`).
 - `gtd --workflow <name>` starts a process on the exported workflow `<name>` (an
   unknown name is a usage error); `gtd door <name> [args]` starts one through a
   `doors` entry `{ workflow, args?, vars? }` (`gtd doors` lists them). A
-  factory's build may return `doors` without `workflow`; exporting the bundled
-  `fix`, `review`, `rollout` and `cleanup` brings `fix`, `review [base]`,
-  `rollout <flag>` and `cleanup <flag>`, and yours merge over them. An
-  `export const base = (workflow, vars) => commitish | undefined` fixes a
-  started process's diff base (blank = default-branch merge-base).
+  factory's build may return `doors` without `workflow`; exporting
+  gtd-workflows' `fix`, `review`, `rollout` and `cleanup` brings `fix`,
+  `review [base]`, `rollout <flag>` and `cleanup <flag>`, and yours merge over
+  them. An `export const base = (workflow, vars) => commitish | undefined` fixes
+  a started process's diff base (blank = default-branch merge-base).
   `--var <name>=<value>` only pins process settings: names the workflow's
   `defaults` declare — never an environment setting.
 
@@ -200,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.
@@ -222,7 +229,7 @@ workflow.
 
 ## Worked example: add an approval gate before building
 
-In the bundled default, `planAndBuild` runs the design phase, then
+In gtd-workflows' default, `planAndBuild` runs the design phase, then
 `buildFeature`: the naive pass and its seam judge, then the implementation (the
 pass itself on `land`), the quality lap and the human review (a review feedback
 lap re-runs design inside `buildFeature` and does not pass it again). Add a
@@ -260,5 +267,5 @@ process before switching to the edited workflow.
 - This skill is versioned in the gtd repository, not auto-installed. When gtd is
   upgraded, re-copy it from the new version's `skills/authoring/SKILL.md`.
 - Where this file and the code disagree, the code wins: the step API's own doc
-  comments in `@pmelab/gtd/flows`, and the bundled workflow under
-  `src/workflows/`.
+  comments in `@pmelab/gtd/flows`, and the workflow's source in its own
+  repository (gtd-workflows' `workflows/default/`).