@pmelab/gtd 58.2.0 → 59.0.0

package/src/cli/Program.test.ts

@@ -27,8 +27,8 @@ import {
   restoredOutcome,
 } from "../emit/index.js"
 import { HISTORY_REF } from "../platform/index.js"
-import { CONFIG_SCAFFOLD } from "../install/index.js"
 import { contentHash } from "../workflow/index.js"
+import { WORKFLOWS_REPO } from "../install/index.js"
 
 const run = async (
   repo: InMemRepo,
@@ -64,15 +64,6 @@ const seed = (source: string, extra: Record<string, string> = {}): InMemRepo =>
   return repo
 }
 
-/** A repo `gtd install` set up: its config runs the shipped workflows. */
-const seedBundled = (): InMemRepo => {
-  const repo = new InMemRepo()
-  repo.writeFile("README.md", "# test project\n")
-  repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
-  repo.seedCommit("chore: init")
-  return repo
-}
-
 const IDLE_THEN_WORKING = `import { agent, human } from "@pmelab/gtd/flows"
 
 export default async () => {
@@ -81,6 +72,15 @@ export default async () => {
 }
 `
 
+/** A repo at rest: its config runs {@link IDLE_THEN_WORKING}. */
+const seedIdle = (): InMemRepo => {
+  const repo = new InMemRepo()
+  repo.writeFile("README.md", "# test project\n")
+  repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
+  repo.seedCommit("chore: init")
+  return repo
+}
+
 describe("gtd --workflow <name> — a custom workflow's named workflow", () => {
   const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
 
@@ -194,9 +194,50 @@ export const defaults = { greeting: "hello" }
   })
 })
 
-describe("gtd --workflow <name> — the shipped workflows", () => {
+describe("gtd install", () => {
+  it("where no gtd.config.ts governs, prints the briefing and warns where to get a workflow — writing nothing", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("README.md", "# test project\n")
+    repo.seedCommit("chore: init")
+    const before = repo.snapshot()
+    const { stdout, stderr, exitCode } = await run(repo, "install")
+    expect(exitCode).toBe(0)
+    expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
+    expect(stderr).toContain(
+      "gtd install: no gtd.config.ts governs here, and gtd ships no workflow",
+    )
+    expect(stderr).toContain(WORKFLOWS_REPO)
+    expect(repo.hasPath("gtd.config.ts")).toBe(false)
+    expect(repo.snapshot()).toBe(before)
+  })
+
+  it("where a gtd.config.ts governs, prints the briefing alone", async () => {
+    const repo = seedIdle()
+    const { stdout, stderr, exitCode } = await run(repo, "install")
+    expect(exitCode).toBe(0)
+    expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
+    expect(stderr).not.toContain(WORKFLOWS_REPO)
+  })
+})
+
+describe("gtd --workflow <name> — a workflow that fixes its diff base", () => {
+  const WORKFLOW = `import { human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "hi" })
+}
+
+export const review = async () => {
+  await human("checking", { message: "check" })
+}
+
+export const defaults = { reviewBase: "" }
+
+export const base = (workflow, vars) => (workflow === "review" ? vars.reviewBase : undefined)
+`
+
   it("--workflow review --var reviewBase=<base> emits a script anchoring the process to that base", async () => {
-    const repo = seedBundled()
+    const repo = seed(WORKFLOW)
     const base = repo.commitHistory().at(-1)!.hash
     repo.writeFile("scratch.txt", "more work\n")
     repo.seedCommit("chore: more work")
@@ -209,26 +250,16 @@ describe("gtd --workflow <name> — the shipped workflows", () => {
       `reviewBase=${base}`,
     )
     expect(exitCode).toBe(0)
-    expect(stdout).toContain("gtd(human): review-gate.check")
+    expect(stdout).toContain("gtd(human): checking")
     expect(stdout).toContain("Gtd-Workflow: review")
     expect(stdout).toContain(`Gtd-Review-Base: ${base}`)
     expect(repo.commitHistory()).toHaveLength(before)
   })
-
-  it("--workflow fix emits a script that would start a fix process", async () => {
-    const repo = seedBundled()
-    const before = repo.commitHistory().length
-    const { stdout, exitCode } = await run(repo, "--workflow", "fix")
-    expect(exitCode).toBe(0)
-    expect(stdout).toContain("gtd(human): fix-precheck")
-    expect(stdout).toContain("Gtd-Workflow: fix")
-    expect(repo.commitHistory()).toHaveLength(before)
-  })
 })
 
 describe("config loading", () => {
   it('gtd next --verbose narrates "config: module" exactly once — the extra load that surfaces warnings is silent', async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const { stderr, exitCode } = await run(repo, "next", "--verbose")
     expect(exitCode).toBe(0)
     expect(stderr.match(/config: module /g)).toHaveLength(1)
@@ -287,7 +318,7 @@ describe("gtd next --json — log path emission", () => {
   const seededRepo = (): InMemRepo => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
-    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
     repo.seedCommit("gtd: init")
     return repo
   }
@@ -1752,7 +1783,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   )
 
   it("a repository with a commit passes the guard and dispatches normally", async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const written: string[] = []
     const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
 
@@ -1765,7 +1796,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   })
 
   it("gtd ui in a repository WITH commits reaches its own dispatch, past the guard", async () => {
-    const repo = seedBundled()
+    const repo = seedIdle()
     const out = { write: () => {}, flush: () => {} }
     const requests: unknown[] = []
     const ui = (request: unknown) => Effect.sync(() => void requests.push(request))
@@ -1950,7 +1981,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
   const seededRepo = (): InMemRepo => {
     const repo = new InMemRepo()
     repo.writeFile("NOTE.md", "a note\n")
-    repo.writeFile("gtd.config.ts", CONFIG_SCAFFOLD)
+    repo.writeFile("gtd.config.ts", IDLE_THEN_WORKING)
     repo.seedCommit("gtd: init")
     return repo
   }
@@ -1987,7 +2018,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
 
   it("an absent selector writes zero bytes to stdout and exits EXIT_OK", async () => {
     const repo = seededRepo()
-    // The built-in workflow's initial `idle` state declares no `mode:` —
+    // The workflow's initial `idle` step declares no `mode:` —
     // `mode` is a real, present-but-`undefined` field on the beat document
     // there (see `src/wire/BeatStatus.ts`'s `statusOf`), not merely an
     // unknown path.

package/src/cli/Program.ts

@@ -87,7 +87,7 @@ import {
   abandonNoopOutcome,
   restoredOutcome,
 } from "../emit/index.js"
-import { CONFIG_SCAFFOLD, renderBriefing } from "../install/index.js"
+import { renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
 import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
 import {
   SelectorUsageError,
@@ -207,13 +207,12 @@ const runLspCommand = (): Effect.Effect<void, Error, ToolCommands> =>
 
 /**
  * Prints the briefing, emitted by the binary itself so it's always current.
- * At a repository root no `gtd.config.ts` governs yet, it also writes one
- * importing gtd's shipped workflows, left uncommitted.
- * Anywhere else it writes nothing.
+ * gtd ships no workflow, so where no `gtd.config.ts` governs it says where to
+ * get one; it writes nothing.
  */
 const runInstallCommand = (
   out: ArtifactOut,
-): Effect.Effect<void, Error, GitService | Workspace | Host | ConfigDiscovery | Narrator> =>
+): Effect.Effect<void, Error, GitService | Host | ConfigDiscovery | Narrator> =>
   Effect.gen(function* () {
     const briefing = renderBriefing()
     out.write(briefing.endsWith("\n") ? briefing : briefing + "\n")
@@ -222,9 +221,8 @@ const runInstallCommand = (
     if (topLevel._tag === "Left") return
     if ((yield* host.realPath(topLevel.right)) !== (yield* host.realPath(host.root))) return
     if ((yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)) !== undefined) return
-    yield* (yield* Workspace).write(WORKFLOW_MODULE, CONFIG_SCAFFOLD)
     yield* (yield* Narrator).warn(
-      `gtd install: wrote ${WORKFLOW_MODULE}, importing gtd's shipped workflows — commit it before your first \`gtd land\``,
+      `gtd install: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`,
     )
   })
 

package/src/edge/Edge.ts

@@ -1476,12 +1476,12 @@ const historySteps = (run: ProcessRun): readonly HistoryStep[] => {
 const versionWarningFor = (recorded: string | undefined): string | undefined =>
   recorded === GTD_VERSION
     ? undefined
-    : `gtd: warning: this history was recorded by ${recorded === undefined ? "an unknown gtd version" : `gtd ${recorded}`} and is replayed by gtd ${GTD_VERSION} — a workflow imported from @pmelab/gtd/workflows may have changed since`
+    : `gtd: warning: this history was recorded by ${recorded === undefined ? "an unknown gtd version" : `gtd ${recorded}`} and is replayed by gtd ${GTD_VERSION} — the engine the workflow runs on may have changed since`
 
 /**
  * Replays the closed run at `tip` under today's config. The workflow is not
- * fingerprinted for a version change: one imported from `@pmelab/gtd/workflows`
- * moves with every upgrade, and the version warning is the only signal.
+ * fingerprinted for a version change: the engine under it moves with every
+ * upgrade, and the version warning is the only signal.
  */
 export const historyTrail = (tip: string): Effect.Effect<HistoryTrail, Error, RestRequirements> =>
   Effect.gen(function* () {

package/src/flags/index.test.ts

@@ -102,16 +102,3 @@ describe("flagSettings", () => {
     })
   })
 })
-
-describe("risk_tier", () => {
-  it("is a release flag, off by default, resolved from GTD_FLAG_RISK_TIER", () => {
-    expect(FLAGS.find((f) => f.name === "risk_tier")).toMatchObject({ kind: "release" })
-    expect(resolveFlags({}).risk_tier).toBe(false)
-    expect(resolveFlags({ GTD_FLAG_RISK_TIER: "1" }).risk_tier).toBe(true)
-  })
-
-  it("is pinned as flag_risk_tier", () => {
-    expect(flagSettings(resolveFlags({ GTD_FLAG_RISK_TIER: "1" })).flag_risk_tier).toBe("1")
-    expect(flagSettings(resolveFlags({})).flag_risk_tier).toBe("0")
-  })
-})

package/src/flags/index.ts

@@ -13,9 +13,7 @@ export interface FlagDeclaration {
   readonly defaultOn?: boolean
 }
 
-export const FLAGS = [
-  { name: "risk_tier", owner: "pmelab", expiry: "2027-01-15", kind: "release" },
-] as const satisfies readonly FlagDeclaration[]
+export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
 
 /** A misspelt name is a compile error. */
 export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {

package/src/install/Install.test.ts

@@ -9,8 +9,13 @@ import { readFileSync } from "node:fs"
 import { resolve } from "node:path"
 import { createRequire } from "node:module"
 import { describe, expect, it } from "vitest"
-import { EDIT_COMMAND, DOOR_COMMAND, MINIMAL_DRIVER, renderBriefing } from "./Install.js"
-import { CONFIG_SCAFFOLD } from "./index.js"
+import {
+  EDIT_COMMAND,
+  DOOR_COMMAND,
+  MINIMAL_DRIVER,
+  renderBriefing,
+  WORKFLOWS_REPO,
+} from "./Install.js"
 
 const SUITE_PATHS = ["gtd-build", "gtd-edit", "gtd-door"]
 const SUPERSEDED_PATHS = ["gtd-fix", "gtd-review"]
@@ -110,6 +115,13 @@ describe("renderBriefing", () => {
     expect(briefing).not.toContain(".gtdrc")
   })
 
+  it("says gtd ships no workflow, offering gtd-workflows or the user's own", () => {
+    const briefing = renderBriefing()
+    expect(briefing).toContain("gtd ships no")
+    expect(briefing).toContain(`git clone ${WORKFLOWS_REPO}`)
+    expect(briefing).toMatch(/\*\*Their own workflow\.\*\*/)
+  })
+
   it("instructs committing the config before the first drive", () => {
     expect(renderBriefing()).toMatch(/commit (it|the config).{0,40}before.{0,20}drive/is)
   })
@@ -425,12 +437,3 @@ describe("DOOR_COMMAND", () => {
     expect(DOOR_COMMAND).toMatch(/usage: gtd-door <name> \[args\.\.\.\]" >&2\n\s*exit 2/)
   })
 })
-
-describe("bundled door lists", () => {
-  it("the scaffold's exports stay feature, review, fix, never rollout or cleanup", () => {
-    const code = CONFIG_SCAFFOLD.split("\n")
-      .filter((l) => !l.startsWith("//"))
-      .join("\n")
-    expect(code).not.toMatch(/rollout|cleanup/)
-  })
-})

package/src/install/Install.ts

@@ -1,6 +1,8 @@
 // `MINIMAL_DRIVER` is pinned equal to https://github.com/pmelab/gtd/blob/main/docs/driver.md's "A complete minimal driver" fenced bash block by `Install.test.ts`, so the two can never drift.
 import { GTD_VERSION } from "./Version.js"
 
+export const WORKFLOWS_REPO = "https://github.com/pmelab/gtd-workflows"
+
 export const MINIMAL_DRIVER = `#!/usr/bin/env sh
 set -eu
 
@@ -82,7 +84,7 @@ while :; do
       system="$(gtd next --json=system)"
       validate="$(gtd next --json=validate)"
       log="$(gtd next --json=log)"
-      # \`model\` is a hint, not a model name — the bundled workflow ships
+      # \`model\` is a hint, not a model name — gtd-workflows' default ships
       # \`smart\` and \`base\`, which \`claude --model\` rejects. Resolve them
       # from your environment; unset, the hint is dropped and the agent runs
       # its own default. Any other value is a real model name.
@@ -420,14 +422,37 @@ follow in the same numbered list.
    existing config, the project's own README/docs) and ask the user what
    they're trying to accomplish with gtd here — don't assume a fresh
    install or silently start a process on their behalf.
-2. **Make sure a \`gtd.config.ts\` governs the repository.** Run at the
-   repository root, \`gtd install\` writes one importing gtd's shipped
-   workflows when none exists yet (its own message says so). Repository
-   settings — steering-file modes, \`gtd ui\`, per-scope skills and access —
-   go in its \`config\` export; workflow settings are options of the
-   workflow factory it exports.
-3. **Commit the config before the first drive.** \`gtd install\` leaves the
-   file it writes uncommitted on purpose — an uncommitted config is a
+2. **Make sure a \`gtd.config.ts\` governs the repository.** gtd ships no
+   workflow: the config imports the workflows it runs. Ask the user which
+   way they want:
+   - **A workflow from ${WORKFLOWS_REPO}.** Its \`default\` is a feature →
+     review → fix workflow. It is used from a checkout pinned on this
+     machine:
+
+     \`\`\`sh
+     git clone ${WORKFLOWS_REPO} ~/.local/share/gtd/workflows
+     ~/.local/share/gtd/workflows/bin/gtd-wf pin origin/main   # or a tag
+     ~/.local/share/gtd/workflows/bin/gtd-wf config default > gtd.config.ts
+     \`\`\`
+
+     \`pin\` checks the ref out and bundles each workflow; \`config\` prints a
+     config importing the bundle by its ABSOLUTE path. Tell the user what
+     that means: the committed config works only where the checkout sits at
+     that same path, so a teammate or CI needs their own checkout there (or
+     their own config). If a checkout exists already, \`gtd-wf status\`
+     shows its pin — reuse it rather than cloning again. Read the
+     repository's README for the workflows it offers and their options.
+   - **Their own workflow.** A workflow is TypeScript the config exports,
+     written against \`@pmelab/gtd/flows\` — see
+     https://github.com/pmelab/gtd/blob/main/docs/configuration.md, and
+     https://github.com/pmelab/gtd/blob/main/docs/testing.md to test it. A
+     copy of a gtd-workflows workflow (\`gtd-wf new <name> --from default\`
+     in a clone of it) is a good start.
+
+   Repository settings — steering-file modes, \`gtd ui\`, per-scope skills
+   and access — go in the config's \`config\` export; workflow settings are
+   options of the workflow factory it exports.
+3. **Commit the config before the first drive.** An uncommitted config is a
    pending change, so starting a process without committing it first turns
    the config into the very first thing the process plans against. Commit
    it, THEN start driving.
@@ -453,7 +478,8 @@ follow in the same numbered list.
    from every prompt line and writing no model exports, so every turn runs
    on the chosen CLI's own default tier.
 6. **If model hints are honored, resolve them to real model identifiers.**
-   The bundled workflow ships \`plannerModel: smart\` and \`coderModel: base\`.
+   A workflow may declare model hints — gtd-workflows' \`default\` ships
+   \`plannerModel: smart\` and \`coderModel: base\`.
    **Those are opaque hints, not model names** — gtd never interprets them,
    and passing \`--model smart\` to a real CLI fails on the first prompt
    beat. Derive the chosen CLI's own available models at install time — its
@@ -550,11 +576,8 @@ hands off to \`gtd-build\`, which halts at the blocked gate and prints it,
 rather than starting the review; \`gtd-door fix\` on a GREEN suite is a no-op
 straight back to \`idle\` — the exec'd \`gtd-build\` exits immediately on it.
 \`gtd doors\` lists the doors a repository offers (those of the workflows its
-config exports — the bundled \`fix\` and \`review [base]\`, plus the opt-in
-\`rollout <flag>\` (turn a release flag default-on) and \`cleanup <flag>\`
-(remove it), which a config adds by exporting \`rollout\` from
-\`@pmelab/gtd/workflows/rollout\` and \`cleanup\` from
-\`@pmelab/gtd/workflows/cleanup\` — plus any it declares). Refuses with
+config exports — gtd-workflows' \`default\` brings \`fix\` and
+\`review [base]\` — plus any the config declares). Refuses with
 \`usage: gtd-door <name> [args...]\` on stderr and exit \`2\` when the name is
 missing — nothing was even attempted. Default path: \`~/.local/bin/gtd-door\`.
 

package/src/install/index.ts

@@ -1,3 +1,2 @@
-export { renderBriefing } from "./Install.js"
-export { CONFIG_SCAFFOLD } from "./ConfigScaffold.js"
+export { renderBriefing, WORKFLOWS_REPO } from "./Install.js"
 export { GTD_VERSION } from "./Version.js"

package/src/replay/Replay.test.ts

@@ -175,7 +175,7 @@ const restName = (outcome: ReplayOutcome): string => {
 }
 
 // Plain loops, a counter cap, and helper-driven branches: the shape the
-// bundled workflow has.
+// workflow might have.
 const fixLoop = async () => {
   await human("idle", { file: "TODO.md" })
   for (let attempt = 1; ; attempt++) {

package/src/replay/index.ts

@@ -15,6 +15,6 @@ export {
   type CommitSpec,
   type JudgeVerdict,
 } from "./Trailers.js"
-export { accessShapeFault, foldAccess } from "./Access.js"
+export { accessShapeFault } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"

package/src/step/planStart.ts

@@ -4,6 +4,7 @@ import {
   ConfigDiscovery,
   ConfigService,
   multilineSetting,
+  ownFlagRefusal,
   resolveStartVars,
   StartFlags,
   type ConfigFingerprint,
@@ -110,7 +111,11 @@ export const planStart = (
     if (overrideRefusal !== undefined) return overrideRefusal
 
     const baseOf = workflow.def.base
-    const vars = resolveStartVars(workflow.vars, yield* StartFlags, varOverrides, (yield* Host).env)
+    const flags = yield* StartFlags
+    const hostEnv = (yield* Host).env
+    const badFlag = ownFlagRefusal(workflow.vars, flags, hostEnv)
+    if (badFlag !== undefined) return refusal(`${commandLabel}: ${badFlag}`)
+    const vars = resolveStartVars(workflow.vars, flags, varOverrides, hostEnv)
     const multiline = multilineSetting(vars)
     if (multiline !== undefined) {
       return refusal(

package/src/twins/FlowScripts.ts

@@ -224,7 +224,7 @@ const recognizePatch = (repo: InMemRepo, script: string): FlowScriptResult | und
 
 type PreambleOutcome = { readonly exit: boolean; readonly output: string }
 
-/** One preamble line — the closed vocabulary the bundled workflows write there. */
+/** One preamble line — the closed vocabulary workflows write there. */
 const runPreambleLine = (repo: InMemRepo, line: string): PreambleOutcome => {
   const quoted = words(line)
   if (line === "exit 0") return { exit: true, output: "" }

package/src/workflow/index.ts

@@ -15,6 +15,7 @@ export {
 export { formatDiagnostic } from "./Diagnostic.js"
 export {
   resolveVars,
+  ownFlagRefusal,
   resolveStartVars,
   StartFlags,
   multilineSetting,