@pmelab/gtd 19.0.0 → 20.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "19.0.0",
+  "version": "20.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "exports": {
     "./flows": "./src/flows/index.ts",
-    "./workflow": "./src/workflows/unified.ts"
+    "./workflow": "./src/workflows/bundled.ts"
   },
   "files": [
     "dist/",

package/skills/authoring/SKILL.md

@@ -11,33 +11,38 @@ description: >-
 # Authoring a gtd workflow
 
 A gtd workflow is **plain async TypeScript**: a `gtd.config.ts` at the
-repository root default-exports the **flow**, one async function that awaits
-**steps** built from `@pmelab/gtd/flows`; optional `defaults` (process
-settings), `envDefaults` (environment settings), `summary`, `base` and
-`steering` (steering file → mode, for the LSP) exports sit beside it, and any
-other export is a helper gtd ignores. Every step is a commit; gtd finds where a
-process rests by **replaying** the flow over the episode's commits, so the git
-history IS the state and nothing is stored anywhere else.
+repository root exports **workflows** — every exported async function is one,
+named by its export, awaiting **steps** built from `@pmelab/gtd/flows`; the
+`default` export is the ordinary start. Optional reserved exports (`defaults`
+process settings, `envDefaults` environment settings, `summary`, `base`,
+`steering`, `skills`, `doors`) are shared by the file's workflows. **Never
+export a helper function you do not want startable** — it becomes a workflow.
+Every step is a commit; gtd finds where a process rests by **replaying** the
+flow over the episode's commits, so the git history IS the state and nothing is
+stored anywhere else.
 
 Your job is to produce or edit that module so it loads cleanly and does what the
 user wants. Driving a workflow once it exists is a separate concern — that is
 what a driver does.
 
 **Trust:** gtd evaluates `gtd.config.ts` on every command that resolves workflow
-state (`gtd next` and `gtd lsp` included). It is code the user's repository
-runs; write it with the same care as a build script.
+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 bundled default, edit incrementally
 
 Do **not** write a workflow from a blank page unless the user wants something
-tiny. gtd ships one known-good workflow and runs it when no `gtd.config.ts` is
-found, and publishes it as `@pmelab/gtd/workflow`: its default export is that
-flow, and every phase and single step it is built from is a named export. Start
-by importing what you keep and writing only what changes:
+tiny. gtd ships three startable workflows (`feature`, `review`, `fix`) as named
+exports of `@pmelab/gtd/workflow` and runs them when no `gtd.config.ts` is
+found. 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
+`export *` from it** — every exported function of your file would become a
+startable workflow:
 
 ```ts
 import { start } from "@pmelab/gtd/flows"
-import bundled, { afterTail, buildTail } from "@pmelab/gtd/workflow"
+import { afterTail, buildTail, feature } from "@pmelab/gtd/workflow"
 
 export {
   defaults,
@@ -45,14 +50,20 @@ export {
   summary,
   base,
   steering,
+  skills,
 } from "@pmelab/gtd/workflow"
 
-export default async ({ entry }) =>
-  entry === "hotfix"
-    ? afterTail(await buildTail(true, start()))
-    : bundled({ entry })
+export default feature
+
+export async function hotfix() {
+  return afterTail(await buildTail(true, start()))
+}
+
+export const doors = { hotfix: { workflow: "hotfix" } }
 ```
 
+`gtd --workflow hotfix` (or `gtd door hotfix`) starts 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
@@ -64,8 +75,8 @@ it in place.
 
 Prefer the bundled workflow's own parts over re-implementing them — `healthy`,
 `escalation`, `gate`, `design`, `architecture`, `packages`, `qualityLap`,
-`review`, `buildTail`, and single steps like `triage` or `fix`. Their full step
-names are versioned API.
+`buildTail`, and single steps like `triage` or `fixCheck`. Their full step names
+are versioned API.
 
 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.
@@ -132,13 +143,14 @@ the pending landing — call it right after the step whose turn you reject.
 - 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", …)`).
-- `gtd --entry <name>` starts a process with the flow's `{ entry }` argument set
-  to `<name>` (`undefined` on an ordinary start). Branch on it, and `refuse()`
-  names you don't accept; a flow that never reads `entry` accepts none. An
-  `export const base = (entry, vars) => commitish | undefined` fixes an entered
-  process's diff base. `--var <name>=<value>` only pins process settings: names
-  the workflow's `defaults` or `.gtdrc` `vars:` declare — never an environment
-  setting.
+- `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; bundled:
+  `fix`, `review [base]`; 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` or `.gtdrc` `vars:` declare — never an environment setting.
 
 ## Landing rules you are designing for
 

package/src/flows/runtime.ts

@@ -259,7 +259,7 @@ export const changesSince = (hash: string, pattern?: string): Changes => {
 /** The commit the process stands on at this point of the flow. */
 export const head = (): string => ctx().head()
 
-/** The process's diff base: the commit before it began, or the base `gtd --entry` fixed. */
+/** The process's diff base: the commit before it began, or the base `gtd --workflow` fixed. */
 export const start = (): string => ctx().start()
 
 /** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
@@ -348,17 +348,8 @@ export const openQuestions = (text: string): readonly OpenQuestion[] => ctx().op
 
 // ── The workflow ────────────────────────────────────────────────────────────
 
-export interface FlowArgs {
-  /** The name `gtd --entry <name>` started the process with; `undefined` for an ordinary start. */
-  readonly entry: string | undefined
-}
-
-/**
- * A workflow's one flow. A flow that never reads `entry` accepts no
- * `--entry`; one that does decides for itself which names it honours,
- * `refuse()`-ing the rest.
- */
-export type Flow = (args: FlowArgs) => Promise<void>
+/** A workflow's one flow. */
+export type Flow = () => Promise<void>
 
 export interface SummaryContext {
   readonly entryCommit: string
@@ -375,11 +366,25 @@ export interface SummaryContext {
 export type Summary = (context: SummaryContext) => string
 
 /**
- * A workflow module's optional `base` export: the commitish that fixes the
- * diff base of a process `gtd --entry <entry>` starts, or `undefined` for
- * none. Runs when the process is entered, with the vars `--var` sets.
+ * A workflow file's optional `base` export: the commitish that fixes the diff
+ * base of a process `gtd --workflow <workflow>` starts, or `undefined` for
+ * none. Runs when the process is started, with the vars `--var` sets.
  */
-export type EntryBase = (
-  entry: string,
+export type WorkflowBase = (
+  workflow: string,
   vars: Readonly<Record<string, string>>,
 ) => string | undefined
+
+/** A named shortcut: `gtd door <name> [args…]` starts `workflow` with the positional args mapped to process settings. */
+export interface Door {
+  readonly workflow: string
+  /** Static, so `gtd doors --json` can list them. */
+  readonly args?: readonly { readonly name: string; readonly optional?: boolean }[]
+  /** A pure function of the args: no git runs at declaration time. */
+  readonly vars?: (
+    args: Readonly<Record<string, string | undefined>>,
+  ) => Readonly<Record<string, string>>
+}
+
+/** A workflow module's reserved `doors` export. */
+export type Doors = Readonly<Record<string, Door>>

package/src/workflows/access.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest"
 import { access } from "./access.js"
-import { unified } from "./index.js"
+import { bundled as workflow } from "./index.js"
 
-const { defaults } = unified
+const { defaults } = workflow
 
 const bundled = access(defaults)
 
@@ -34,7 +34,7 @@ describe("the bundled workflow's access export", () => {
   })
 
   it("keys only scopes that run a turn (every key is a skills key)", () => {
-    const known = Object.keys(unified.skills(defaults))
+    const known = Object.keys(workflow.skills(defaults))
     for (const key of Object.keys(bundled)) expect(known).toContain(key)
   })
 })

package/src/workflows/{unified.ts → bundled.ts}

@@ -2,14 +2,13 @@ import {
   changes,
   head,
   human,
-  refuse,
   requireRevert,
   restoreScript,
   revertScript,
   run,
   start,
-  type EntryBase,
-  type FlowArgs,
+  type Doors,
+  type WorkflowBase,
   type Summary,
 } from "../flows/index.js"
 import { baseline, gate } from "./health.js"
@@ -20,13 +19,13 @@ import { buildTail, type ReviewOutcome } from "./review.js"
 import { ARCHITECTURE, FEEDBACK, REQUIREMENTS, REVIEW } from "./steps.js"
 import * as t from "./text.js"
 
-// gtd's built-in default workflow. Any change to the tree starts a process:
+// gtd's bundled workflows. Any change to the tree starts a process:
 // `idle` → `unwind` reverts the sketch (its intent survives in history) → a
 // green-baseline gate → design, architecture and one package per concern →
 // the quality lap → human review, which signs off (the episode ends back at
-// `idle`) or sends a full re-plan lap. `--entry fix-precheck`, `--entry
-// review-gate.check --var reviewBase=<commitish>` and `--entry
-// start-gate.check` enter the same flow further in.
+// `idle`) or sends a full re-plan lap. `feature` is that ordinary start;
+// `gtd --workflow fix` and `gtd --workflow review --var reviewBase=<commitish>`
+// enter the same build tail further in.
 //
 // Every part is exported for other workflows to compose; see the modules
 // re-exported below.
@@ -107,30 +106,34 @@ export const ordinaryStart = async (): Promise<void> => {
   await planAndBuild(start())
 }
 
-const ENTRIES = ["fix-precheck", "review-gate.check", "start-gate.check"]
+/** Repair a red baseline through the build tail, as its own reviewed commit. */
+export const fix = async (): Promise<void> => {
+  if (await baseline("fix-precheck")) return
+  return afterTail(await buildTail(true, start()))
+}
 
-export default async function unified({ entry }: FlowArgs): Promise<void> {
-  if (entry === undefined) return ordinaryStart()
-  if (entry === "fix-precheck") {
-    if (await baseline("fix-precheck")) return
-    return afterTail(await buildTail(true, start()))
-  }
-  if (entry === "review-gate.check") {
-    await gate("review-gate", t.reviewGateBlockedMessage())
-    return afterTail(await buildTail(false, start()))
-  }
-  if (entry === "start-gate.check") {
-    await gate("start-gate", t.startGateBlockedMessage())
-    return planAndBuild(start())
-  }
-  refuse(
-    `"${entry}" is not an enterable state — enterable states:\n${ENTRIES.map((name) => `  ${name}`).join("\n")}`,
-  )
+/** Pure review of everything since `reviewBase`. */
+export const review = async (): Promise<void> => {
+  await gate("review-gate", t.reviewGateBlockedMessage())
+  return afterTail(await buildTail(false, start()))
 }
 
+export const feature = ordinaryStart
+
+export default feature
+
 export const summary: Summary = t.summaryPrompt
 
 export const steering = { [REQUIREMENTS]: "qa", [ARCHITECTURE]: "qa", [REVIEW]: "review" }
 
-export const base: EntryBase = (entry, vars) =>
-  entry === "review-gate.check" ? (vars.reviewBase ?? "") : undefined
+export const base: WorkflowBase = (workflow, vars) =>
+  workflow === "review" ? (vars.reviewBase ?? "") : undefined
+
+export const doors: Doors = {
+  fix: { workflow: "fix" },
+  review: {
+    workflow: "review",
+    args: [{ name: "base", optional: true }],
+    vars: ({ base }) => (base === undefined ? {} : { reviewBase: base }),
+  },
+}

package/src/workflows/index.ts

@@ -1 +1 @@
-export * as unified from "./unified.js"
+export * as bundled from "./bundled.js"

package/src/workflows/review.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it } from "vitest"
 import { installContext, type Change, type JudgeAnswer, type StepRequest } from "../flows/index.js"
 import { fixQualityFindings, review, type ReviewOutcome } from "./review.js"
-import { unified } from "./index.js"
+import { bundled } from "./index.js"
 import { fixtureContext } from "./text.fixture.js"
 
 afterEach(() => installContext(undefined))
@@ -313,7 +313,7 @@ describe("review verdict routing", () => {
 
 describe("the default quality lenses", () => {
   it("are the six lenses in the settled order", () => {
-    expect(unified.defaults.qualityReviews!.split(",").map((l) => l.trim())).toEqual([
+    expect(bundled.defaults.qualityReviews!.split(",").map((l) => l.trim())).toEqual([
       "correctness",
       "owasp-security",
       "ponytail-review",
@@ -324,7 +324,7 @@ describe("the default quality lenses", () => {
   })
 
   it("expose builtInLenses through the public workflow module", () => {
-    expect(Object.keys(unified.builtInLenses).sort()).toEqual([
+    expect(Object.keys(bundled.builtInLenses).sort()).toEqual([
       "conventions",
       "correctness",
       "spec-challenge",

package/src/workflows/review.ts

@@ -26,7 +26,7 @@ import {
   ARCHITECTURE,
   awaitReview,
   collecting,
-  fix,
+  fixCheck,
   fixNits,
   fixQuality,
   fixRisks,
@@ -230,7 +230,7 @@ const routeNotes = async (notes: readonly ReviewNote[], r: Round): Promise<Finis
   }
   if (nits.length > 0) {
     await guarded(r.frozen, () => fixNits(nits), "review")()
-    await healthy(guarded(r.frozen, fix, "review"), { escalations: r.escalations })
+    await healthy(guarded(r.frozen, fixCheck, "review"), { escalations: r.escalations })
   }
   if (edits.length > 0) {
     await r.close()
@@ -291,7 +291,7 @@ const reviewOnce = async (
   const risks = reviewRisks(read(REVIEW) ?? "")
   if (risks.length === 0) return
   await guarded(frozen, () => fixRisks(risks), "review")()
-  await healthy(guarded(frozen, fix, "review"), { escalations })
+  await healthy(guarded(frozen, fixCheck, "review"), { escalations })
   await reviewing(base, carry)
 }
 
@@ -335,12 +335,12 @@ export const buildTail = (
   scope("build", async () => {
     const frozen = built?.frozen
     const escalations: EscalationCount = { rounds: 0 }
-    const guardedFix = guarded(frozen, () => fix())
+    const guardedFix = guarded(frozen, () => fixCheck())
     let redFirst = fixFirst
     // fixFirst's own fix + healthy below already is the full run.
     if (!fixFirst) {
       await healthy(
-        guarded(frozen, () => fix(built)),
+        guarded(frozen, () => fixCheck(built)),
         { escalations, sweepOnGreen: [ARCHITECTURE] },
       )
     }

package/src/workflows/skills.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest"
 import { skills } from "./skills.js"
-import { unified } from "./index.js"
+import { bundled as workflow } from "./index.js"
 
-const { defaults } = unified
+const { defaults } = workflow
 
 const bundled = skills(defaults)
 

package/src/workflows/steps.test.ts

@@ -41,7 +41,7 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   it("fix carries build.fix's bundled skills", async () => {
-    const prompt = agentPrompt(await capture(() => steps.fix(), "build"))
+    const prompt = agentPrompt(await capture(() => steps.fixCheck(), "build"))
     expect(prompt).toContain("debugging-and-error-recovery")
   })
 
@@ -110,7 +110,7 @@ describe("the bundled workflow's steps declare skills — a bundled step's rende
   })
 
   it("an empty configured list leaves that step's skills empty, and its rendered prompt bare", async () => {
-    const request = await capture(() => steps.fix(), "build", { build: [] })
+    const request = await capture(() => steps.fixCheck(), "build", { build: [] })
     if (request.kind !== "agent") throw new Error("unreachable")
     expect(request.prompt).not.toContain("Load whatever's listed here")
   })

package/src/workflows/steps.ts

@@ -81,7 +81,7 @@ export const fixSuite = (): Promise<void> =>
 
 // ── Keeping the suite green ─────────────────────────────────────────────────
 
-export const fix = (built?: t.BuildContext): Promise<void> =>
+export const fixCheck = (built?: t.BuildContext): Promise<void> =>
   t.agentWithSkills("fix", t.buildFixPrompt(built), {
     label: "Fixing the check",
     file: FEEDBACK,

package/src/workflows/text.ts

@@ -87,7 +87,7 @@ export const startGateBlockedMessage = (): string =>
 \`.gtd/FEEDBACK.md\` holds the failing output.
 
 What each change does next (then run \`gtd land\`):
-- **Retry check** — edit the code and/or \`.gtd/FEEDBACK.md\` to fix the failing tests (**start-gate.check**). To repair the baseline as its own separate reviewed commit instead, abandon this start and run \`gtd --entry fix-precheck\` from a clean \`idle\`.
+- **Retry check** — edit the code and/or \`.gtd/FEEDBACK.md\` to fix the failing tests (**start-gate.check**). To repair the baseline as its own separate reviewed commit instead, abandon this start and run \`gtd --workflow fix\` from a clean \`idle\`.
 `
 
 export const reviewGateBlockedMessage = (): string =>

package/claude/hooks/entry.ts

@@ -1,34 +0,0 @@
-// The workflow's side doors: `fix` repairs a red baseline as its own reviewed
-// commit, `review` reviews everything since a base, straight to the review
-// tail. `gtd --entry` prints the script that starts the process; running it
-// is the driver's job, as with every git write gtd plans.
-
-import type { ShipIo, Shipped } from "./ship"
-
-const fail = (text: string): Shipped => ({ ok: false, text })
-
-export async function enter(io: ShipIo, door: "fix" | "review", base?: string): Promise<Shipped> {
-  const args = door === "fix" ? ["--entry", "fix-precheck"] : await reviewArgs(io, base)
-  if (typeof args === "string") return fail(args)
-  const planned = await io.run(["gtd", ...args])
-  if (planned.code !== 0)
-    return fail(planned.err.trim() || `gtd ${args.join(" ")} exited ${planned.code}`)
-  const started = await io.run(["sh", "-c", planned.out])
-  if (started.code !== 0) return fail(`The entry script failed.\n${started.err.trim()}`)
-  return {
-    ok: true,
-    text: door === "fix" ? "Started a fix." : `Started a review since ${args.at(-1)?.slice(-7)}.`,
-  }
-}
-
-// Reviews the branch since it left `base`, the default branch unless named.
-async function reviewArgs(io: ShipIo, base: string | undefined) {
-  const git = async (...a: string[]) => (await io.run(["git", ...a])).out.trim()
-  const from =
-    base || (await git("symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD")) || "main"
-  const mergeBase = await git("merge-base", from, "HEAD")
-  if (!mergeBase) return `There is no common ancestor of ${from} and HEAD to review from.`
-  if (mergeBase === (await git("rev-parse", "HEAD")))
-    return `Nothing to review: HEAD has no commits beyond ${from}.`
-  return ["--entry", "review-gate.check", "--var", `reviewBase=${mergeBase}`]
-}