@pmelab/gtd 58.1.0 → 58.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "58.1.0",
+  "version": "58.2.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/dist/chunks/{testkit-D1-auYau.mjs → testkit-JDtpNKyi.mjs}

@@ -8662,7 +8662,9 @@ var InMemRepo = class InMemRepo {
 		}
 		const refHash = this.refs.get(ref);
 		if (refHash !== void 0) return refHash;
-		return this.branches.get(ref) ?? null;
+		const short = this.refs.get(`refs/tags/${ref}`) ?? this.refs.get(`refs/remotes/${ref}`);
+		if (short !== void 0) return short;
+		return this.branches.get(ref.replace(/^refs\/heads\//, "")) ?? null;
 	}
 	lastCommitSubject(ref = "HEAD") {
 		const hash = this.resolveRef(ref);
@@ -8678,6 +8680,24 @@ var InMemRepo = class InMemRepo {
 	branchName() {
 		return this.currentBranch;
 	}
+	/** `git branch <name> <ref>`. */
+	createBranch(name, ref) {
+		if (this.branches.has(name)) throw new Error(`a branch named '${name}' already exists`);
+		const hash = this.resolveRef(ref);
+		if (hash === null) throw new Error(`not a valid object name: '${ref}'`);
+		this.branches.set(name, hash);
+	}
+	/** `git checkout <name>`, refusing any uncommitted change rather than carrying it over. */
+	checkoutBranch(name) {
+		const hash = this.branches.get(name);
+		if (hash === void 0) throw new Error(`pathspec '${name}' did not match any branch`);
+		if (this.statusPorcelain().trim() !== "") throw new Error(`cannot check out '${name}': the working tree has uncommitted changes`);
+		const tree = this.getCommit(hash)?.files ?? /* @__PURE__ */ new Map();
+		this.head = hash;
+		this.currentBranch = name;
+		this.worktree = new Map(tree);
+		this.index = new Map(tree);
+	}
 	/** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
 	listRefs(prefix) {
 		return [...this.refs.entries()].filter(([ref]) => ref.startsWith(prefix)).map(([ref, hash]) => ({
@@ -9528,8 +9548,11 @@ const parseCheck = (script) => {
 };
 const runCommand = (repo, commands, command) => {
 	const scripted = commands.get(command);
-	if (scripted === void 0) throw new Error(`testkit: cannot run \`${command}\` in memory — script it ("the shell command … exits …")`);
-	if (scripted.kind === "exit") return scripted;
+	if (scripted === void 0) throw new Error(`testkit: no canned command matches \`${command}\` — add one to \`commands\``);
+	if (scripted.kind === "exit") {
+		scripted.effect?.();
+		return scripted;
+	}
 	if (scripted.kind === "missing") return {
 		status: 127,
 		output: `sh: ${command}: not found\n`
@@ -10025,6 +10048,7 @@ const recognizeScriptedCommand = (repo, commands, block) => {
 		error: `sh: ${block.split(" ")[0]}: not found`,
 		status: 127
 	};
+	scripted.effect?.();
 	if (scripted.status !== 0) return {
 		kind: "failed",
 		error: scripted.output,
@@ -10231,15 +10255,15 @@ const LINES = [
 	}]
 ];
 const knownLine = (line) => LINES.find(([pattern]) => pattern.test(line));
-const cannotRun = (error) => /* @__PURE__ */ new Error(`testkit: cannot run script in memory — give the step an actor instead\n${error}`);
-const runLines = (repo, script) => {
+const cannotRun = (error) => /* @__PURE__ */ new Error(`testkit: cannot run script in memory — add a canned command for it, or give the step an actor\n${error}`);
+const runLines = (repo, commands, script) => {
 	const lines = script.split("\n").map((line) => line.trim());
 	const known = lines.map(knownLine);
 	if (known.every(Boolean)) {
 		known.forEach((k, i) => k[1](repo, words(lines[i])));
 		return;
 	}
-	const applied = applyEmittedScript(repo, /* @__PURE__ */ new Map(), script, { git: false });
+	const applied = applyEmittedScript(repo, commands, script, { git: false });
 	if (!applied.ok) throw cannotRun(applied.error ?? "");
 };
 const failed = (what, result) => /* @__PURE__ */ new Error(`${what} exited ${result.exitCode}\n${result.stderr}${result.stdout}`);
@@ -10251,6 +10275,18 @@ const testRepo = (options) => {
 	repo.writeFile("gtd.config.ts", typeof workflow === "string" ? workflow : moduleSource(id, workflow));
 	for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content);
 	repo.seedCommit("chore: initial commit");
+	const canned = [...options.commands ?? []];
+	const commands = { get: (command) => {
+		const hit = canned.find(({ run }) => typeof run === "string" ? run === command : run.test(command));
+		if (hit === void 0) return void 0;
+		const { exit = 0, output = "", effect } = hit;
+		return {
+			kind: "exit",
+			status: exit,
+			output,
+			effect: () => effect?.(self)
+		};
+	} };
 	const gtd = async (...args) => {
 		const { io, result } = makeCapturingCliIo(repo, env);
 		if (typeof workflow !== "string") registry().set(id, workflow);
@@ -10281,7 +10317,7 @@ const testRepo = (options) => {
 	};
 	const apply = (what, script) => {
 		if (script.length === 0) return;
-		const applied = applyEmittedScript(repo, /* @__PURE__ */ new Map(), script);
+		const applied = applyEmittedScript(repo, commands, script);
 		if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`);
 	};
 	/** Runs a write command, then the script its `--json=script` twin prints. */
@@ -10315,14 +10351,26 @@ const testRepo = (options) => {
 		await runWrite(["judge", "answer"], verdict);
 	};
 	const self = {
+		command: (command) => {
+			canned.push(command);
+		},
+		branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
+		checkout: (name) => repo.checkoutBranch(name),
+		ref: (name, ref = "HEAD") => {
+			if (!name.startsWith("refs/")) throw new Error(`testkit: ref "${name}" must start with refs/`);
+			const hash = repo.resolveRef(ref);
+			if (hash === null) throw new Error(`testkit: ref "${ref}" resolves to no commit`);
+			repo.updateRef(name, hash);
+		},
+		branchName: () => repo.branchName(),
 		read: (path) => repo.readFile(path),
 		write: (path, content) => repo.writeFile(path, content),
 		remove: (path) => repo.deleteFile(path),
 		commit: (message) => repo.seedCommit(message),
 		show: (ref, path) => repo.fileAtRef(ref, path) ?? void 0,
 		runScript: (script) => {
-			const flow = applyFlowScript(repo, /* @__PURE__ */ new Map(), script);
-			if (flow === void 0) runLines(repo, script);
+			const flow = applyFlowScript(repo, commands, script);
+			if (flow === void 0) runLines(repo, commands, script);
 			else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`);
 		},
 		gtd,

package/dist/testkit/gherkin.mjs

@@ -1,4 +1,4 @@
-import { n as testRepo, t as runsItsScript } from "../chunks/testkit-D1-auYau.mjs";
+import { n as testRepo, t as runsItsScript } from "../chunks/testkit-JDtpNKyi.mjs";
 import { resolve } from "node:path";
 import assert from "node:assert";
 import { pathToFileURL } from "node:url";
@@ -10,6 +10,7 @@ var TestkitWorld = class extends QuickPickleWorld {
 	}
 	gtdConfig = void 0;
 	env = {};
+	commands = [];
 	/** Per step, what its scripted actor does, in the order the scenario declared it. */
 	actions = /* @__PURE__ */ new Map();
 	verdicts = /* @__PURE__ */ new Map();
@@ -26,6 +27,10 @@ var TestkitWorld = class extends QuickPickleWorld {
 		if (typeof this.gtdConfig !== "string") throw new Error("a gtd config from a module cannot be extended");
 		this.gtdConfig += `\n${tail}`;
 	}
+	command(command) {
+		if (this.created === void 0) this.commands.push(command);
+		else this.created.command(command);
+	}
 	setEnv(name, value) {
 		this.assertNotCreated(`the environment variable ${name}`);
 		this.env[name] = value;
@@ -37,7 +42,8 @@ var TestkitWorld = class extends QuickPickleWorld {
 		if (this.gtdConfig === void 0) throw new Error("no gtd config: add a `gtd config` step first");
 		return this.created ??= testRepo({
 			workflow: this.gtdConfig,
-			env: this.env
+			env: this.env,
+			commands: this.commands
 		});
 	}
 	act(step, action) {
@@ -79,6 +85,28 @@ Given("the gtd config ends with:", (world, source) => {
 Given("an environment variable {string} set to {string}", (world, name, value) => {
 	world.setEnv(name, value);
 });
+Given("the command {string} exits {int}", (world, run, exit) => {
+	world.command({
+		run,
+		exit
+	});
+});
+Given("the command {string} exits {int} with:", (world, run, exit, output) => {
+	world.command({
+		run,
+		exit,
+		output: withNewline(output)
+	});
+});
+Given("a branch {string}", (world, name) => {
+	world.repo().branch(name);
+});
+Given("{string} is checked out", (world, name) => {
+	world.repo().checkout(name);
+});
+Given("the ref {string} points at HEAD", (world, name) => {
+	world.repo().ref(name);
+});
 Given("a file {string} with:", (world, path, content) => {
 	world.repo().write(path, withNewline(content));
 });

package/dist/testkit.mjs

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

package/package.json

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

package/src/gherkin/git-control.feature

@@ -0,0 +1,78 @@
+@inmem
+Feature: a scenario controls the commands and the history a workflow sees
+
+  A step's script may run programs the in-memory repository has none of: a
+  canned command stands in for each, matched by the command as the script
+  spells it. Branches and refs are set up before the process starts, so a
+  workflow that reads another branch or a remote ref finds them.
+
+  Background:
+    Given a gtd config with:
+      """
+      import { check, human, run, showScript } from "@pmelab/gtd/flows"
+
+      export const tested = async () => {
+        const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+        await human(green ? "sign-off" : "red")
+      }
+
+      export const restored = async () => {
+        await run("restore", showScript("origin/main", "a.txt", "a.txt"))
+        await human("done")
+      }
+
+      export default tested
+      """
+    And a file "a.txt" with:
+      """
+      base
+      """
+    And the working tree is committed as "chore: base"
+
+  Scenario: a red canned command writes its output to the check's report
+    Given the command "npm test" exits 1 with:
+      """
+      1 failing
+      """
+    And step "test" runs its script
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "red"
+    And ".gtd/FEEDBACK.md" contains "1 failing"
+
+  Scenario: a green canned command passes the check
+    Given the command "npm test" exits 0
+    And step "test" runs its script
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "sign-off"
+
+  Scenario: a command no canned command matches fails the drive, naming it
+    Given step "test" runs its script
+    When gtd starts workflow "tested"
+    Then driving the process is refused with "no canned command matches `npm test`"
+
+  Scenario: a remote ref is read by its short name
+    Given the ref "refs/remotes/origin/main" points at HEAD
+    And a file "a.txt" with:
+      """
+      local
+      """
+    And the working tree is committed as "chore: local"
+    And step "restore" runs its script
+    When gtd starts workflow "restored"
+    And the process is driven
+    Then the process rests at "done"
+    And "a.txt" contains "base"
+
+  Scenario: a branch is checked out and back
+    Given a branch "feature/x"
+    And "feature/x" is checked out
+    And a file "a.txt" with:
+      """
+      feature
+      """
+    And the working tree is committed as "feat: x"
+    And "main" is checked out
+    Then "a.txt" contains "base"
+    And "a.txt" does not contain "feature"

package/src/gherkin/index.ts

@@ -17,6 +17,7 @@ import {
   runsItsScript,
   testRepo,
   type Actor,
+  type CannedCommand,
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
@@ -31,6 +32,7 @@ export class TestkitWorld extends QuickPickleWorld {
 
   private gtdConfig: WorkflowModule | undefined = undefined
   private env: Record<string, string> = {}
+  private commands: CannedCommand[] = []
   /** Per step, what its scripted actor does, in the order the scenario declared it. */
   actions = new Map<string, Actor[]>()
   verdicts = new Map<string, string>()
@@ -54,6 +56,11 @@ export class TestkitWorld extends QuickPickleWorld {
     this.gtdConfig += `\n${tail}`
   }
 
+  command(command: CannedCommand): void {
+    if (this.created === undefined) this.commands.push(command)
+    else this.created.command(command)
+  }
+
   setEnv(name: string, value: string): void {
     this.assertNotCreated(`the environment variable ${name}`)
     this.env[name] = value
@@ -68,7 +75,11 @@ export class TestkitWorld extends QuickPickleWorld {
   repo(): TestRepo {
     if (this.gtdConfig === undefined)
       throw new Error("no gtd config: add a `gtd config` step first")
-    return (this.created ??= testRepo({ workflow: this.gtdConfig, env: this.env }))
+    return (this.created ??= testRepo({
+      workflow: this.gtdConfig,
+      env: this.env,
+      commands: this.commands,
+    }))
   }
 
   act(step: string, action: Actor): void {
@@ -136,6 +147,29 @@ Given(
   },
 )
 
+Given("the command {string} exits {int}", (world: TestkitWorld, run: string, exit: number) => {
+  world.command({ run, exit })
+})
+
+Given(
+  "the command {string} exits {int} with:",
+  (world: TestkitWorld, run: string, exit: number, output: string) => {
+    world.command({ run, exit, output: withNewline(output) })
+  },
+)
+
+Given("a branch {string}", (world: TestkitWorld, name: string) => {
+  world.repo().branch(name)
+})
+
+Given("{string} is checked out", (world: TestkitWorld, name: string) => {
+  world.repo().checkout(name)
+})
+
+Given("the ref {string} points at HEAD", (world: TestkitWorld, name: string) => {
+  world.repo().ref(name)
+})
+
 Given("a file {string} with:", (world: TestkitWorld, path: string, content: string) => {
   world.repo().write(path, withNewline(content))
 })

package/src/testkit/TestRepo.test.ts

@@ -12,7 +12,16 @@ import {
   softResetTo,
   updateRef,
 } from "../emit/index.js"
-import { agent, human, moveScript, read, removeScript, run } from "../flows/index.js"
+import {
+  agent,
+  check,
+  human,
+  moveScript,
+  read,
+  removeScript,
+  run,
+  showScript,
+} from "../flows/index.js"
 import { runsItsScript, testRepo } from "./TestRepo.js"
 
 const tiny = async (): Promise<void> => {
@@ -112,7 +121,7 @@ describe("testRepo", () => {
   it("carries the recognizer's error when a git-free fallback fails", () => {
     const repo = testRepo({ workflow: { default: tiny } })
     expect(() => repo.runScript("printf 'x' > 'y'\n")).toThrow(
-      "testkit: cannot run script in memory — give the step an actor instead\nunrecognized script block: printf 'x' > 'y'",
+      "testkit: cannot run script in memory — add a canned command for it, or give the step an actor\nunrecognized script block: printf 'x' > 'y'",
     )
   })
 
@@ -194,4 +203,111 @@ describe("testRepo", () => {
       repo.drive({ spin: (_, r) => r.write("n", `${++n}\n`) }, { maxBeats: 5 }),
     ).rejects.toThrow(/did not rest within 5 beats/)
   })
+
+  describe("canned commands", () => {
+    const checked = async (): Promise<void> => {
+      const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+      await human(green ? "sign-off" : "red")
+    }
+
+    it("runs a check's command as canned, its output the report", async () => {
+      const repo = testRepo({
+        workflow: { default: checked },
+        commands: [{ run: "npm test", exit: 1, output: "1 failing" }],
+      })
+      repo.write("go", "\n")
+      const rest = await repo.drive({ test: runsItsScript })
+      expect(rest.state).toBe("red")
+      expect(repo.read(".gtd/FEEDBACK.md")).toContain("1 failing")
+    })
+
+    it("exits 0 by default, and matches by pattern", async () => {
+      const repo = testRepo({ workflow: { default: checked }, commands: [{ run: /^npm / }] })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("sign-off")
+    })
+
+    it("lets a command change the tree, and takes the first match", async () => {
+      const repo = testRepo({
+        workflow: { default: checked },
+        commands: [
+          { run: "npm test", effect: (r) => r.write("ran", "first\n") },
+          { run: /npm/, exit: 1 },
+        ],
+      })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("sign-off")
+      expect(repo.read("ran")).toBe("first\n")
+    })
+
+    it("takes a command added later", async () => {
+      const repo = testRepo({ workflow: { default: checked } })
+      repo.command({ run: "npm test", exit: 2 })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("red")
+    })
+
+    it("runs a plain script line as canned", () => {
+      const repo = testRepo({
+        workflow: { default: tiny },
+        commands: [{ run: "make docs", effect: (r) => r.write("docs.html", "<p>\n") }],
+      })
+      repo.runScript("make docs\n")
+      expect(repo.read("docs.html")).toBe("<p>\n")
+    })
+
+    it("fails the drive on a command none matches, naming it", async () => {
+      const repo = testRepo({ workflow: { default: checked } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ test: runsItsScript })).rejects.toThrow(
+        "no canned command matches `npm test`",
+      )
+    })
+  })
+
+  describe("history", () => {
+    it("creates and checks out a branch, refusing uncommitted changes", () => {
+      const repo = testRepo({ workflow: { default: tiny }, files: { "a.txt": "main\n" } })
+      repo.branch("feature/x")
+      repo.checkout("feature/x")
+      expect(repo.branchName()).toBe("feature/x")
+      repo.write("a.txt", "feature\n")
+      expect(() => repo.checkout("main")).toThrow("uncommitted changes")
+      repo.commit("feat: x")
+      repo.checkout("main")
+      expect(repo.branchName()).toBe("main")
+      expect(repo.read("a.txt")).toBe("main\n")
+      expect(repo.show("feature/x", "a.txt")).toBe("feature\n")
+    })
+
+    it("branches at a given ref, and refuses an existing name or a missing ref", () => {
+      const repo = testRepo({ workflow: { default: tiny }, files: { "a.txt": "one\n" } })
+      repo.write("a.txt", "two\n")
+      repo.commit("chore: two")
+      repo.branch("old", "HEAD~1")
+      expect(repo.show("old", "a.txt")).toBe("one\n")
+      expect(() => repo.branch("old")).toThrow("already exists")
+      expect(() => repo.branch("new", "nowhere")).toThrow("not a valid object name")
+    })
+
+    it("points a remote ref that a script reads by its short name", async () => {
+      const restore = async (): Promise<void> => {
+        await run("restore", showScript("origin/main", "a.txt", "a.txt"))
+        await human("done")
+      }
+      const repo = testRepo({ workflow: { default: restore }, files: { "a.txt": "base\n" } })
+      repo.ref("refs/remotes/origin/main")
+      repo.write("a.txt", "local\n")
+      repo.commit("chore: local")
+      repo.write("go", "\n")
+      await repo.drive({ restore: runsItsScript })
+      expect(repo.read("a.txt")).toBe("base\n")
+    })
+
+    it("refuses a ref outside refs/ or at nothing", () => {
+      const repo = testRepo({ workflow: { default: tiny } })
+      expect(() => repo.ref("origin/main")).toThrow("must start with refs/")
+      expect(() => repo.ref("refs/tags/v1", "nowhere")).toThrow("resolves to no commit")
+    })
+  })
 })

package/src/testkit/TestRepo.ts

@@ -8,6 +8,7 @@ import {
   InMemRepo,
   makeCapturingCliIo,
   type CapturedCliResult,
+  type CommandTable,
 } from "../twins/index.js"
 
 /**
@@ -18,8 +19,23 @@ import {
  */
 export type WorkflowModule = string | Readonly<Record<string, unknown>>
 
+/**
+ * What a command a step's script runs does in memory. `run` matches the command
+ * as the script spells it, exactly or by a pattern; the first match wins.
+ */
+export interface CannedCommand {
+  readonly run: string | RegExp
+  /** Defaults to 0. */
+  readonly exit?: number
+  readonly output?: string
+  /** What the command does to the tree, e.g. a formatter's rewrite. */
+  readonly effect?: (repo: TestRepo) => void
+}
+
 export interface TestRepoOptions {
   readonly workflow: WorkflowModule
+  /** The commands a step's script may run. A command none matches fails the script. */
+  readonly commands?: readonly CannedCommand[]
   /** Committed alongside the config, before any process starts. */
   readonly files?: Readonly<Record<string, string>>
   /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
@@ -42,6 +58,15 @@ export interface DriveOptions {
 }
 
 export interface TestRepo {
+  /** Adds a command a step's script may run, after those `testRepo` was given. */
+  command(command: CannedCommand): void
+  /** Creates branch `name` at `ref` (HEAD by default). Outside a process only. */
+  branch(name: string, ref?: string): void
+  /** Checks branch `name` out; refuses with uncommitted changes. Outside a process only. */
+  checkout(name: string): void
+  /** Points ref `name` (`refs/remotes/origin/main`, `refs/tags/v1`) at `ref` (HEAD by default). Outside a process only. */
+  ref(name: string, ref?: string): void
+  branchName(): string
   read(path: string): string | undefined
   write(path: string, content: string): void
   remove(path: string): void
@@ -158,19 +183,21 @@ const LINES: ReadonlyArray<readonly [RegExp, (repo: InMemRepo, words: string[])
 const knownLine = (line: string) => LINES.find(([pattern]) => pattern.test(line))
 
 const cannotRun = (error: string): Error =>
-  new Error(`testkit: cannot run script in memory — give the step an actor instead\n${error}`)
+  new Error(
+    `testkit: cannot run script in memory — add a canned command for it, or give the step an actor\n${error}`,
+  )
 
 // A script with a line `LINES` lacks goes to the contract-tested recognizers
 // whole, minus the git builders: they would apply a commit/reset/update-ref in
 // memory, so any git-mutating block is refused whatever its spelling.
-const runLines = (repo: InMemRepo, script: string): void => {
+const runLines = (repo: InMemRepo, commands: CommandTable, script: string): void => {
   const lines = script.split("\n").map((line) => line.trim())
   const known = lines.map(knownLine)
   if (known.every(Boolean)) {
     known.forEach((k, i) => k![1](repo, words(lines[i]!)))
     return
   }
-  const applied = applyEmittedScript(repo, new Map(), script, { git: false })
+  const applied = applyEmittedScript(repo, commands, script, { git: false })
   if (!applied.ok) throw cannotRun(applied.error ?? "")
 }
 
@@ -189,6 +216,18 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
   repo.seedCommit("chore: initial commit")
 
+  const canned = [...(options.commands ?? [])]
+  const commands: CommandTable = {
+    get: (command) => {
+      const hit = canned.find(({ run }) =>
+        typeof run === "string" ? run === command : run.test(command),
+      )
+      if (hit === undefined) return undefined
+      const { exit = 0, output = "", effect } = hit
+      return { kind: "exit", status: exit, output, effect: () => effect?.(self) }
+    },
+  }
+
   // The module is registered only while gtd runs, so nothing outlives the
   // call that loads it and no test can reach another's module.
   const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
@@ -217,7 +256,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
 
   const apply = (what: string, script: string): void => {
     if (script.length === 0) return
-    const applied = applyEmittedScript(repo, new Map(), script)
+    const applied = applyEmittedScript(repo, commands, script)
     if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`)
   }
 
@@ -260,14 +299,26 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   const self: TestRepo = {
+    command: (command) => {
+      canned.push(command)
+    },
+    branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
+    checkout: (name) => repo.checkoutBranch(name),
+    ref: (name, ref = "HEAD") => {
+      if (!name.startsWith("refs/")) throw new Error(`testkit: ref "${name}" must start with refs/`)
+      const hash = repo.resolveRef(ref)
+      if (hash === null) throw new Error(`testkit: ref "${ref}" resolves to no commit`)
+      repo.updateRef(name, hash)
+    },
+    branchName: () => repo.branchName(),
     read: (path) => repo.readFile(path),
     write: (path, content) => repo.writeFile(path, content),
     remove: (path) => repo.deleteFile(path),
     commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
-      const flow = applyFlowScript(repo, new Map(), script)
-      if (flow === undefined) runLines(repo, script)
+      const flow = applyFlowScript(repo, commands, script)
+      if (flow === undefined) runLines(repo, commands, script)
       else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,

package/src/testkit/index.ts

@@ -6,6 +6,7 @@ export {
   testRepo,
   type Actor,
   type Actors,
+  type CannedCommand,
   type DriveOptions,
   type TestRepo,
   type TestRepoOptions,

package/src/twins/EmittedScriptRecognizer.ts

@@ -36,7 +36,7 @@ import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable } from "./Layers.js"
 
 export interface AppliedScriptResult {
   readonly ok: boolean
@@ -266,10 +266,7 @@ const recognizeFileExistsGuard = (repo: InMemRepo, block: string): BlockOutcome
 /** `binaryGuard`. The in-memory tier has no `$PATH`: a binary is present unless declared `missing`. */
 const BINARY_GUARD_MESSAGE_RE = /^gtd: mode "([^"]+)": "(format|validate)" command not found: (.+)$/
 
-const recognizeBinaryGuard = (
-  commands: ReadonlyMap<string, ScriptedCommand>,
-  block: string,
-): BlockOutcome | undefined => {
+const recognizeBinaryGuard = (commands: CommandTable, block: string): BlockOutcome | undefined => {
   const [binary, , message] = extractQuotedTokens(block)
   if (binary === undefined || message === undefined) return undefined
   const match = BINARY_GUARD_MESSAGE_RE.exec(message)
@@ -330,7 +327,7 @@ const expandFileVar = (text: string): string | undefined => {
  */
 const recognizeModeCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const command = expandFileVar(block) ?? block
@@ -356,7 +353,7 @@ const FAILURE_PROMPT_FOOTER = ' "$gtd_validate_out"\n  exit "$gtd_validate_statu
 
 const recognizeFailurePromptWrapper = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   if (!block.startsWith(FAILURE_PROMPT_HEADER) || !block.endsWith(FAILURE_PROMPT_FOOTER)) {
@@ -465,7 +462,7 @@ const parseModeContradictionCheck = (block: string): ParsedModeContradictionChec
  */
 const simulateModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   parsed: ParsedModeContradictionCheck,
 ): BlockOutcome => {
   const { mode, samplePath, sample, formatCommand, format } = parsed
@@ -502,7 +499,7 @@ const simulateModeContradictionCheck = (
  */
 const recognizeModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const parsed = parseModeContradictionCheck(block)
@@ -570,7 +567,7 @@ const PRESENTATION_SUBSHELL_SUFFIX = `\n) || ${PRESENTATION_FAILURE_WARNING}`
 
 const recognizePresentationSubshell = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
   git: boolean,
 ): BlockOutcome | undefined => {
@@ -595,7 +592,7 @@ const recognizePresentationSubshell = (
 /** Anything left over must be an EXACT hit in the scripted-command table — mirrors `ScriptedCommand`'s two `kind`s (`Layers.ts`). */
 const recognizeScriptedCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const scripted = commands.get(block)
@@ -607,6 +604,7 @@ const recognizeScriptedCommand = (
   if (scripted.kind === "missing") {
     return { kind: "failed", error: `sh: ${block.split(" ")[0]}: not found`, status: 127 }
   }
+  scripted.effect?.()
   if (scripted.status !== 0) {
     return { kind: "failed", error: scripted.output, status: scripted.status }
   }
@@ -693,7 +691,7 @@ const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | und
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   git: boolean,
 ): ReadonlyArray<(block: string) => BlockOutcome | undefined> => [
   (block) => recognizeSetFlags(block),
@@ -735,7 +733,7 @@ const recognizeBlock = (
  */
 export const applyEmittedScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   { git = true }: { readonly git?: boolean } = {},
 ): AppliedScriptResult => {
@@ -750,7 +748,7 @@ export const applyEmittedScript = (
 
 const applyBlocks = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   git: boolean,
 ): AppliedScriptResult => {

package/src/twins/FlowScripts.ts

@@ -15,7 +15,7 @@ import {
   writeScript,
 } from "../flows/index.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable, ScriptedCommand } from "./Layers.js"
 
 export interface FlowScriptResult {
   readonly ok: boolean
@@ -299,16 +299,17 @@ const parseCheck = (script: string): ParsedCheck | undefined => {
 
 const runCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   command: string,
 ): { readonly status: number; readonly output: string } => {
   const scripted = commands.get(command)
   if (scripted === undefined) {
-    throw new Error(
-      `testkit: cannot run \`${command}\` in memory — script it ("the shell command … exits …")`,
-    )
+    throw new Error(`testkit: no canned command matches \`${command}\` — add one to \`commands\``)
+  }
+  if (scripted.kind === "exit") {
+    scripted.effect?.()
+    return scripted
   }
-  if (scripted.kind === "exit") return scripted
   if (scripted.kind === "missing") return { status: 127, output: `sh: ${command}: not found\n` }
   repo.writeFile(scripted.file, rewritten(repo, scripted))
   return { status: 0, output: "" }
@@ -325,7 +326,7 @@ export const rewritten = (
 
 const recognizeCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   const parsed = parseCheck(script)
@@ -362,7 +363,7 @@ const recognizeCheck = (
  */
 export const applyFlowScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   if (!script.startsWith(`${SHEBANG}\n`)) return undefined

package/src/twins/InMemRepo.ts

@@ -134,7 +134,10 @@ export class InMemRepo {
     const refHash = this.refs.get(ref)
     if (refHash !== undefined) return refHash
 
-    return this.branches.get(ref) ?? null
+    // git's own short names: `origin/main` for refs/remotes/origin/main, …
+    const short = this.refs.get(`refs/tags/${ref}`) ?? this.refs.get(`refs/remotes/${ref}`)
+    if (short !== undefined) return short
+    return this.branches.get(ref.replace(/^refs\/heads\//, "")) ?? null
   }
 
   lastCommitSubject(ref = "HEAD"): string | null {
@@ -154,6 +157,28 @@ export class InMemRepo {
     return this.currentBranch
   }
 
+  /** `git branch <name> <ref>`. */
+  createBranch(name: string, ref: string): void {
+    if (this.branches.has(name)) throw new Error(`a branch named '${name}' already exists`)
+    const hash = this.resolveRef(ref)
+    if (hash === null) throw new Error(`not a valid object name: '${ref}'`)
+    this.branches.set(name, hash)
+  }
+
+  /** `git checkout <name>`, refusing any uncommitted change rather than carrying it over. */
+  checkoutBranch(name: string): void {
+    const hash = this.branches.get(name)
+    if (hash === undefined) throw new Error(`pathspec '${name}' did not match any branch`)
+    if (this.statusPorcelain().trim() !== "") {
+      throw new Error(`cannot check out '${name}': the working tree has uncommitted changes`)
+    }
+    const tree = this.getCommit(hash)?.files ?? new Map<string, string>()
+    this.head = hash
+    this.currentBranch = name
+    this.worktree = new Map(tree)
+    this.index = new Map(tree)
+  }
+
   /** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
   listRefs(prefix: string): Array<{ ref: string; hash: string; date: string }> {
     return [...this.refs.entries()]

package/src/twins/Layers.ts

@@ -169,7 +169,13 @@ const makeInMemoryConfigDiscovery = (
 
 /** One scripted `bash` command's canned behavior, keyed by the RENDERED command string a scenario's `Given` step declares. */
 export type ScriptedCommand =
-  | { readonly kind: "exit"; readonly status: number; readonly output: string }
+  | {
+      readonly kind: "exit"
+      readonly status: number
+      readonly output: string
+      /** What the command does to the tree before it exits. */
+      readonly effect?: () => void
+    }
   | {
       readonly kind: "rewrite"
       readonly file: string
@@ -180,6 +186,11 @@ export type ScriptedCommand =
   /** Keyed by the binary's name: it is not on `$PATH`. */
   | { readonly kind: "missing" }
 
+/** The scripted commands, by the exact command a script runs; a `Map` is one. */
+export interface CommandTable {
+  get(command: string): ScriptedCommand | undefined
+}
+
 export interface TestWorldOptions {
   readonly env?: Readonly<Record<string, string | undefined>>
   readonly root?: string

package/src/twins/index.ts

@@ -1,5 +1,10 @@
 export { InMemRepo } from "./InMemRepo.js"
-export { makeInMemoryWorkspaceOps, testLayers, type ScriptedCommand } from "./Layers.js"
+export {
+  makeInMemoryWorkspaceOps,
+  testLayers,
+  type CommandTable,
+  type ScriptedCommand,
+} from "./Layers.js"
 export { makeCapturingCliIo, type CapturedCliResult } from "./cliIo.js"
 export { applyEmittedScript } from "./EmittedScriptRecognizer.js"
 export { applyFlowScript } from "./FlowScripts.js"