@pmelab/gtd 58.0.0 → 58.2.0

package/dist/workflows/cleanup.mjs

@@ -1,6 +1,6 @@
 import { agent, changes, glob, read, refuse, scope, start, vars } from "../flows.mjs";
-import { It as registryEntry, Lt as requireFlag, Pt as flagReferences, St as envDefaults, a as flagShipped, i as skills, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-BzAFXuz_.mjs";
-import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-JQzB21Q3.mjs";
+import { It as registryEntry, Lt as requireFlag, Pt as flagReferences, St as envDefaults, a as flagShipped, i as skills, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff, r as handOffTail } from "../chunks/tail-Bd7L940p.mjs";
 //#region src/workflows/cleanup/cleanup.ts
 const removingPrompt = (name, registry) => `Clean up the release flag "${name}", which is default-on: delete its entry in ${registry}, and remove every \`GTD_FLAG_${name.toUpperCase()}\` check from the shipped sources. Keep the flag-on path; delete code only the off path reached, including tests that pin the off path.`;
 const cleanupFlow = async () => {

package/dist/workflows/feature.mjs

@@ -1,8 +1,8 @@
 import { agent, answered, applyScript, changes, changesSince, check, codeChanges, env, hasThreadFor, head, human, judge, judgeDiffShape, kept, mark, matches, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireThreadsClosed, restoreScript, revertScript, run, scope, start, vars, wrote } from "../flows.mjs";
 import { lensEntriesOf } from "../workflow-kit.mjs";
-import { B as designSystem, Ct as testFileGlobs, D as planner, F as clearCriteriaMessage, I as clearCriteriaQuestion, J as implementBuildingPrompt, L as criterionLine, M as buildReviewCollectingPrompt, P as builderSystem, Q as naiveTryMessage, R as designGateAnswerMessage, S as collecting, St as envDefaults, V as designTriagePrompt, X as naiveApplyFailure, Y as implementFixPrompt, Z as naivePassPrompt, _ as REQUIREMENTS, _t as unwindFailedMessage, at as refactorFixPrompt, d as healthy, et as normaliseCriteriaScript, f as FEEDBACK, g as REFACTOR_NOTE, gt as startGateBlockedMessage, h as REFACTOR, ht as seamSteerMessage, i as skills, it as refactorDroppedRefusal, j as agentWithSkills, l as gate, mt as seamByHandMessage, n as summary, o as naiveTestOn, ot as refactorNotePrompt, p as NAIVE_TEST, pt as reviewerSystem, q as idleMessage, r as access, rt as refactorBuildingPrompt, s as shipped, st as refactorRules, t as steering, vt as unwindFailure, w as fixNits, x as coder, xt as defaults, y as answerReviewQuestions, z as designImpactPrompt } from "../chunks/reserved-BzAFXuz_.mjs";
-import { a as refusePendingHandOff } from "../chunks/tail-JQzB21Q3.mjs";
-import { n as isCode$1, r as reUnwind, t as buildTail } from "../chunks/review-CVqRS0mc.mjs";
+import { B as designSystem, Ct as testFileGlobs, D as planner, F as clearCriteriaMessage, I as clearCriteriaQuestion, J as implementBuildingPrompt, L as criterionLine, M as buildReviewCollectingPrompt, P as builderSystem, Q as naiveTryMessage, R as designGateAnswerMessage, S as collecting, St as envDefaults, V as designTriagePrompt, X as naiveApplyFailure, Y as implementFixPrompt, Z as naivePassPrompt, _ as REQUIREMENTS, _t as unwindFailedMessage, at as refactorFixPrompt, d as healthy, et as normaliseCriteriaScript, f as FEEDBACK, g as REFACTOR_NOTE, gt as startGateBlockedMessage, h as REFACTOR, ht as seamSteerMessage, i as skills, it as refactorDroppedRefusal, j as agentWithSkills, l as gate, mt as seamByHandMessage, n as summary, o as naiveTestOn, ot as refactorNotePrompt, p as NAIVE_TEST, pt as reviewerSystem, q as idleMessage, r as access, rt as refactorBuildingPrompt, s as shipped, st as refactorRules, t as steering, vt as unwindFailure, w as fixNits, x as coder, xt as defaults, y as answerReviewQuestions, z as designImpactPrompt } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff } from "../chunks/tail-Bd7L940p.mjs";
+import { n as isCode$1, r as reUnwind, t as buildTail } from "../chunks/review-Bfaror38.mjs";
 import { posix } from "node:path";
 //#region src/workflows/shared/fences.ts
 const markFenced = (text) => {

package/dist/workflows/fix.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, scope, start } from "../flows.mjs";
 import { b as reviewNotes, x as reviewRisks } from "../chunks/steering-CCNvngSH.mjs";
-import { G as fixReviewNotesPrompt, St as envDefaults, W as finisherSystem, c as baseline, i as skills, j as agentWithSkills, n as summary, r as access, s as shipped, t as steering, v as REVIEW, x as coder, xt as defaults } from "../chunks/reserved-BzAFXuz_.mjs";
-import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-JQzB21Q3.mjs";
+import { G as fixReviewNotesPrompt, St as envDefaults, W as finisherSystem, c as baseline, i as skills, j as agentWithSkills, n as summary, r as access, s as shipped, t as steering, v as REVIEW, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { r as handOffTail, t as REVIEW_ORIG } from "../chunks/tail-Bd7L940p.mjs";
 //#region src/workflows/fix/fix.ts
 /**
 * Fix every note a human left in a handed-off `.gtd/REVIEW.md` and every

package/dist/workflows/review.mjs

@@ -1,7 +1,7 @@
 import { read, refuse, removeScript, run, start } from "../flows.mjs";
-import { St as envDefaults, W as finisherSystem, _ as REQUIREMENTS, dt as reviewGateBlockedMessage, i as skills, j as agentWithSkills, l as gate, n as summary, r as access, s as shipped, t as steering, ut as reviewFeedbackFixPrompt, x as coder, xt as defaults } from "../chunks/reserved-BzAFXuz_.mjs";
-import { a as refusePendingHandOff } from "../chunks/tail-JQzB21Q3.mjs";
-import { r as reUnwind, t as buildTail } from "../chunks/review-CVqRS0mc.mjs";
+import { St as envDefaults, W as finisherSystem, _ as REQUIREMENTS, dt as reviewGateBlockedMessage, i as skills, j as agentWithSkills, l as gate, n as summary, r as access, s as shipped, t as steering, ut as reviewFeedbackFixPrompt, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
+import { a as refusePendingHandOff } from "../chunks/tail-Bd7L940p.mjs";
+import { r as reUnwind, t as buildTail } from "../chunks/review-Bfaror38.mjs";
 //#region src/workflows/review/review.ts
 const fixFeedback = async () => {
 	await agentWithSkills("feedback.fixing", reviewFeedbackFixPrompt(), {

package/dist/workflows/rollout.mjs

@@ -1,5 +1,5 @@
 import { agent, changesSince, glob, head, mark, read, refuse, removeScript, run, scope, vars } from "../flows.mjs";
-import { Ft as flipProblems, Lt as requireFlag, Nt as flagMentions, St as envDefaults, a as flagShipped, f as FEEDBACK, i as skills, l as gate, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-BzAFXuz_.mjs";
+import { Ft as flipProblems, Lt as requireFlag, Nt as flagMentions, St as envDefaults, a as flagShipped, f as FEEDBACK, i as skills, l as gate, n as summary, r as access, t as steering, x as coder, xt as defaults } from "../chunks/reserved-lMYCaapY.mjs";
 //#region src/workflows/rollout/rollout.ts
 const flippingPrompt = (name, registry) => `Roll out the release flag "${name}": in ${registry}, set \`defaultOn: true\` on its entry. Change nothing else — no other entry, no other field, no other file, no comments.`;
 const suiteBlockedMessage = () => "The suite is red after the rollout. Fix it by hand — a rollout may only touch the flag's registry entry — then land.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "58.0.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": {
@@ -66,6 +66,11 @@
       "types": "./src/testkit/index.ts",
       "source": "./src/testkit/index.ts",
       "default": "./dist/testkit.mjs"
+    },
+    "./testkit/gherkin": {
+      "types": "./src/gherkin/index.ts",
+      "source": "./src/gherkin/index.ts",
+      "default": "./dist/testkit/gherkin.mjs"
     }
   },
   "files": [
@@ -76,6 +81,8 @@
     "src/wire/",
     "src/steering/",
     "src/testkit/",
+    "src/twins/",
+    "src/gherkin/",
     "src/cli/",
     "src/edge/",
     "src/emit/",

package/src/cli/Cli.test.ts

@@ -25,7 +25,7 @@ import {
 import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
 import { Host } from "../platform/index.js"
 import { type CommandRequirements } from "./Cli.js"
-import { InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
 
 const FLAG_NAMES = [

package/src/cli/History.test.ts

@@ -1,6 +1,6 @@
 import { Effect, Exit } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { runCli } from "./index.js"
 import { historyEntries, resolveHistoryRef, type HistoryEntry } from "./History.js"
 

package/src/cli/Metrics.test.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
-import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../testkit/index.js"
+import { applyEmittedScript, InMemRepo, makeCapturingCliIo, testLayers } from "../twins/index.js"
 import { runCli } from "./index.js"
 import { processMetrics, readProcessMetrics, totalMetrics, type MetricCommit } from "./Metrics.js"
 

package/src/cli/Program.test.ts

@@ -18,7 +18,7 @@ vi.mock("node:os", async (importOriginal) => ({
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
 import { needsOf, runCommand, SelectorUsageError } from "./Program.js"
-import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
 import {
   commitAll,
   DID_NOT_RUN_COMMENT,

package/src/cli/Strays.test.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_STRAYS_FOUND } from "../wire/index.js"
-import { InMemRepo, makeCapturingCliIo } from "../testkit/index.js"
+import { InMemRepo, makeCapturingCliIo } from "../twins/index.js"
 import { runCli } from "./index.js"
 
 const seed = (): InMemRepo => {

package/src/edge/Edge.test.ts

@@ -31,7 +31,7 @@ import {
   makeCapturingCliIo,
   makeInMemoryWorkspaceOps,
   testLayers,
-} from "../testkit/index.js"
+} from "../twins/index.js"
 
 type Env = Readonly<Record<string, string | undefined>>
 type Files = Readonly<Record<string, string>>

package/src/emit/Emit.ts

@@ -110,7 +110,7 @@ export const emitScripts = (
   optional: assembleScript(optional),
 })
 
-/** Exported so `src/testkit/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
+/** Exported so `src/twins/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
 export const DID_NOT_RUN_COMMENT =
   "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn"
 

package/src/emit/GitScript.ts

@@ -130,7 +130,7 @@ export const fetchHistoryRefs = (remote: string): string =>
 // No test asserts the two stay byte-identical; a drift between them is a
 // review-time risk this boundary accepts.
 
-/** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/testkit/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
+/** Marks an emitted block as print-only — mirrors `OutcomeScript.ts`'s `OUTCOME_MARKER` verbatim, so `src/twins/EmittedScriptRecognizer.ts` recognizes either path's output identically. */
 const OUTCOME_MARKER = "# gtd: outcome (print-only)"
 
 const printfLine = (fmt: string, args: readonly string[]): string =>

package/src/emit/OutcomeScript.ts

@@ -19,7 +19,7 @@ const printfLine = (fmt: string, args: readonly string[]): string =>
 
 /**
  * Marks an emitted block as print-only. Load-bearing beyond documentation:
- * `src/testkit/EmittedScriptRecognizer.ts` recognizes an outcome block by
+ * `src/twins/EmittedScriptRecognizer.ts` recognizes an outcome block by
  * this line, and a bare `printf` would be ambiguous with a workflow
  * `script:` command that happens to start the same way.
  */

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/{testkit/steps.ts → gherkin/index.ts}

@@ -11,7 +11,16 @@ import {
 } from "quickpickle"
 import assert from "node:assert"
 import type { TestContext } from "vitest"
-import { runsItsScript, testRepo, type Actor, type TestRepo } from "./TestRepo.js"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import {
+  runsItsScript,
+  testRepo,
+  type Actor,
+  type CannedCommand,
+  type TestRepo,
+  type WorkflowModule,
+} from "../testkit/index.js"
 
 export class TestkitWorld extends QuickPickleWorld {
   // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
@@ -21,8 +30,9 @@ export class TestkitWorld extends QuickPickleWorld {
     super(context, info)
   }
 
-  private gtdConfig: string | undefined = undefined
+  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>()
@@ -33,7 +43,7 @@ export class TestkitWorld extends QuickPickleWorld {
   // The repository is created on first use and keeps the config and
   // environment it was created with, so a later change to either is refused
   // rather than silently ignored.
-  configure(config: string): void {
+  configure(config: WorkflowModule): void {
     this.assertNotCreated("a gtd config")
     this.gtdConfig = config
   }
@@ -41,9 +51,16 @@ export class TestkitWorld extends QuickPickleWorld {
   extendConfig(tail: string): void {
     this.assertNotCreated("a gtd config")
     if (this.gtdConfig === undefined) throw new Error("no gtd config to extend")
+    if (typeof this.gtdConfig !== "string")
+      throw new Error("a gtd config from a module cannot be extended")
     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
@@ -58,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 {
@@ -108,6 +129,13 @@ Given("a gtd config with:", (world: TestkitWorld, source: string) => {
   world.configure(withNewline(source))
 })
 
+// Imported by the test runner itself, from the working directory: the module and
+// the engine share one `@pmelab/gtd/flows`, and a config source string could
+// import only files written into the in-memory repository.
+Given("a gtd config from the module {string}", async (world: TestkitWorld, path: string) => {
+  world.configure({ ...(await import(pathToFileURL(resolve(path)).href)) })
+})
+
 Given("the gtd config ends with:", (world: TestkitWorld, source: string) => {
   world.extendConfig(withNewline(source))
 })
@@ -119,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/gherkin/module-config.feature

@@ -0,0 +1,24 @@
+@inmem
+Feature: a scenario runs a workflow module from disk
+
+  The test runner imports the module, so it shares the engine's runtime and
+  may import anything on disk. A config written as source can import only
+  files inside the in-memory repository.
+
+  Scenario: the module's default export starts on a change in the tree
+    Given a gtd config from the module "src/gherkin/tiny.fixture.ts"
+    And a file "IDEA.md" with:
+      """
+      a calculator
+      """
+    And step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When the process is driven
+    Then the process rests at "sign-off"
+    And the commit subjects end with:
+      """
+      gtd(agent): plan → sign-off
+      """
+

package/src/gherkin/tiny.fixture.ts

@@ -0,0 +1,8 @@
+import { agent, human } from "../flows/index.js"
+
+export const tiny = async (): Promise<void> => {
+  await agent("plan", "Write PLAN.md.")
+  await human("sign-off")
+}
+
+export default tiny

package/src/platform/Git.test.ts

@@ -7,11 +7,11 @@ import { Cause, Effect, Exit, Option } from "effect"
 import { describe, expect, it } from "vitest"
 import { GitService, InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
 import { Host } from "./index.js"
-import { gitTiers, runGitServiceContract, runGitScriptContract } from "../testkit/index.js"
+import { gitTiers, runGitServiceContract, runGitScriptContract } from "../twins/index.js"
 
 /**
  * The `GitOperations` contract, run identically against both the Live and
- * InMemory tiers (`src/testkit/GitTiers.ts`) — 20 operations × 2 tiers.
+ * InMemory tiers (`src/twins/GitTiers.ts`) — 20 operations × 2 tiers.
  */
 for (const makeTier of gitTiers) {
   const name = makeTier().name

package/src/platform/RetainedHistory.test.ts

@@ -1,6 +1,6 @@
 import { Effect, Option } from "effect"
 import { describe, expect, it, vi } from "vitest"
-import { strictGitOperations as stubGit } from "../testkit/index.js"
+import { strictGitOperations as stubGit } from "../twins/index.js"
 import {
   clearRetainedHistory,
   HISTORY_REF,
@@ -13,7 +13,7 @@ import {
 
 /**
  * Unit coverage for the retention edge module (`src/platform/RetainedHistory.ts`),
- * using `strictGitOperations` (`src/testkit/StrictGitOperations.ts`) as its
+ * using `strictGitOperations` (`src/twins/StrictGitOperations.ts`) as its
  * `GitOperations` double — a Proxy failing on any method a test didn't
  * override, so an unexpected call fails loudly instead of silently succeeding.
  */

package/src/platform/Workspace.test.ts

@@ -15,7 +15,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"
 import { Effect, Layer } from "effect"
 import { NodeContext } from "@effect/platform-node"
 import { GitService, Host, Workspace, type WorkspaceOps } from "./index.js"
-import { InMemRepo, makeInMemoryWorkspaceOps } from "../testkit/index.js"
+import { InMemRepo, makeInMemoryWorkspaceOps } from "../twins/index.js"
 
 // `execFileSync` is a named export of the built-in `node:child_process` ESM
 // module — not configurable, so `vi.spyOn` can't wrap it directly. `vi.mock`
@@ -31,7 +31,7 @@ vi.mock("node:child_process", async (importOriginal) => {
 })
 
 /**
- * One `Workspace` tier, in the shape `src/testkit/GitTiers.ts` establishes
+ * One `Workspace` tier, in the shape `src/twins/GitTiers.ts` establishes
  * for `GitOperations`: a `root`, a way to seed working-tree/committed
  * content, and `provide` to run an Effect against this tier's `Workspace`.
  */

package/src/platform/WorktreeState.test.ts

@@ -16,7 +16,7 @@ import { NodeContext } from "@effect/platform-node"
 import { describe, expect, it } from "vitest"
 import { loopLogPath, worktreeGitDir } from "./WorktreeState.js"
 import { GitService, Host, Workspace } from "./index.js"
-import { InMemRepo, testLayers } from "../testkit/index.js"
+import { InMemRepo, testLayers } from "../twins/index.js"
 
 const provide = <A>(
   eff: Effect.Effect<A, never, Host | Workspace>,

package/src/step/planStart.test.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { planStart, type StartOutcome } from "./planStart.js"
-import { InMemRepo, testLayers } from "../testkit/index.js"
+import { InMemRepo, testLayers } from "../twins/index.js"
 import { ConfigService } from "../workflow/index.js"
 
 const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"

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")
+    })
+  })
 })