@pmelab/gtd 27.7.1 → 27.8.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -649,7 +649,7 @@ gtd is one package, `@pmelab/gtd`, and every entrypoint shares its version and
 
 | Import                                                                                                                                                         | What it is                                                                                                                                                                                             |
 | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@pmelab/gtd/flows`                                                                                                                                            | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                                                                |
+| `@pmelab/gtd/flows`                                                                                                                                            | The flow API a workflow is written in: the steps (`agent`, `human`, `run`, …), `scope` and `slice` (named spans of a process), workflow factories, `defineConfig` and `FLOWS_PROTOCOL`.                |
 | `@pmelab/gtd/wire`                                                                                                                                             | The driver protocol: `WIRE_SCHEMA`, the exit codes and the types of every `--json` document.                                                                                                           |
 | `@pmelab/gtd/steering`                                                                                                                                         | The steering-file formats (`qa`, `review`) and the review-note readers.                                                                                                                                |
 | `@pmelab/gtd/workflow-kit`                                                                                                                                     | Policy-free building blocks to compose a workflow from: health checks, quality laps, scenario freezing, review tails.                                                                                  |

package/dist/flows.mjs

@@ -86,6 +86,20 @@ const scope = async (scope, fn) => {
 		context.popScope();
 	}
 };
+/**
+* Mark the span `fn` covers as one named slice of the process. Lands no
+* commit, prefixes no step name, opens no memory scope.
+*/
+const slice = async (name, fn) => {
+	const context = ctx();
+	if (typeof context.enterSlice !== "function") return fn();
+	context.enterSlice(name);
+	try {
+		return await fn();
+	} finally {
+		context.leaveSlice?.();
+	}
+};
 const read = (path) => ctx().read(path);
 /** Every path in the tree matching `pattern` (`*` stays within a segment, `**` crosses them). */
 const glob = (pattern) => ctx().glob(pattern);
@@ -652,10 +666,11 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	sections: () => sections,
 	showScript: () => showScript,
 	skillsFor: () => skillsFor,
+	slice: () => slice,
 	start: () => start,
 	threads: () => threads,
 	vars: () => vars,
 	wrote: () => wrote
 });
 //#endregion
-export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, displayPath, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, judgeDiffShape, kept, mark, matches, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, seamGate, sectionBodies, sections, showScript, skillsFor, start, flows_exports as t, threads, vars, wrote };
+export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, displayPath, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, judgeDiffShape, kept, mark, matches, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, seamGate, sectionBodies, sections, showScript, skillsFor, slice, start, flows_exports as t, threads, vars, wrote };

package/dist/gtd.bundle.mjs

@@ -21724,6 +21724,20 @@ const scope = async (scope, fn) => {
 		context.popScope();
 	}
 };
+/**
+* Mark the span `fn` covers as one named slice of the process. Lands no
+* commit, prefixes no step name, opens no memory scope.
+*/
+const slice = async (name, fn) => {
+	const context = ctx();
+	if (typeof context.enterSlice !== "function") return fn();
+	context.enterSlice(name);
+	try {
+		return await fn();
+	} finally {
+		context.leaveSlice?.();
+	}
+};
 const read = (path) => ctx().read(path);
 /** Every path in the tree matching `pattern` (`*` stays within a segment, `**` crosses them). */
 const glob = (pattern) => ctx().glob(pattern);
@@ -22290,6 +22304,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	sections: () => sections,
 	showScript: () => showScript,
 	skillsFor: () => skillsFor,
+	slice: () => slice,
 	start: () => start,
 	threads: () => threads,
 	vars: () => vars,
@@ -37670,6 +37685,32 @@ const refNameFault = (name) => {
 	}
 };
 //#endregion
+//#region src/replay/Slices.ts
+const IMPLICIT_SLICE = "main";
+/** Same shape as mark()'s name rule; kept local so @pmelab/gtd/flows publishes no regex. */
+const SLICE_NAME = /^[a-z][a-z0-9-]*$/;
+/**
+* Folds boundaries into ranges: each kept span's base is the previous kept
+* span's `leftAt`, so a gap before a span belongs to it, and the last span
+* runs to the episode tip. A closed span that landed nothing is dropped.
+*/
+const sliceRanges = (spans, episode) => {
+	if (spans.some((s) => s.enteredAt === "" || s.leftAt === "")) throw new Error("sliceRanges: a pending turn's \"\" hash is not a commit");
+	const kept = spans.filter((s) => s.leftAt === void 0 || s.enteredAt !== s.leftAt);
+	if (kept.length === 0) return [{
+		name: IMPLICIT_SLICE,
+		base: episode.base,
+		tip: episode.tip,
+		open: true
+	}];
+	return kept.map((s, i) => ({
+		name: s.name,
+		base: i === 0 ? episode.base : kept[i - 1].leftAt ?? episode.base,
+		tip: i === kept.length - 1 ? episode.tip : s.leftAt ?? episode.tip,
+		open: i === kept.length - 1
+	}));
+};
+//#endregion
 //#region src/replay/Tree.ts
 const treeFromRecord = (files) => ({
 	paths: () => Object.keys(files).sort(),
@@ -38017,6 +38058,7 @@ const replay = async (input) => {
 	const keptTips = /* @__PURE__ */ new Map();
 	let landed;
 	const marks = [];
+	const slices = [];
 	let outcome;
 	let signal;
 	const settled = new Promise((resolve) => {
@@ -38223,7 +38265,8 @@ const replay = async (input) => {
 			rest: step,
 			trace,
 			landed,
-			marks
+			marks,
+			slices: slices.map((s) => ({ ...s }))
 		});
 		return landPending(step, input.pending);
 	};
@@ -38287,6 +38330,31 @@ const replay = async (input) => {
 			scopes.pop();
 			scopeCallIds.pop();
 		},
+		enterSlice: (name) => {
+			if (outcome !== void 0) return;
+			const fail = (message) => {
+				finish({
+					kind: "failed",
+					message
+				});
+				throw new Stop();
+			};
+			if (typeof name !== "string" || !SLICE_NAME.test(name)) fail(`gtd: slice "${name}": name must match ${SLICE_NAME}`);
+			if (name === "main") fail(`gtd: slice "${IMPLICIT_SLICE}" is reserved for the implicit slice`);
+			const open = slices.find((s) => s.leftAt === void 0);
+			if (open !== void 0) fail(`gtd: slice "${name}" is entered inside slice "${open.name}" — slices do not nest`);
+			if (slices.some((s) => s.name === name)) fail(`gtd: slice "${name}" is entered twice in this episode — a loop must sit inside its slice`);
+			slices.push({
+				name,
+				enteredAt: position.hash,
+				leftAt: void 0
+			});
+		},
+		leaveSlice: () => {
+			if (outcome !== void 0) return;
+			const open = slices.find((s) => s.leftAt === void 0);
+			if (open !== void 0) open.leftAt = position.hash;
+		},
 		read: (path) => position.tree.read(path),
 		glob: (pattern) => position.tree.paths().filter((path) => globMatches(path, pattern)),
 		changes: () => changesBetween(previousPosition.tree, position.tree),
@@ -39976,6 +40044,10 @@ const pendingChanges = (git, withIndex) => gen(function* () {
 	const seen = new Set(worktree.map((e) => e.path));
 	return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))];
 });
+const sliceRangesOf = (slices, run) => sliceRanges(slices, {
+	base: run.startParentHash,
+	tip: run.trace.at(-1)?.hash ?? run.startParentHash
+});
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 const restAt = (ref, startOverrides = {}) => gen(function* () {
 	const git = yield* GitService;
@@ -40018,7 +40090,8 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 			total: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
 			byModel: costByModel(run.costEntries)
 		},
-		setup
+		setup,
+		slices: sliceRangesOf(outcome.slices, run)
 	};
 });
 const currentRest = restAt(void 0);

package/dist/testkit.mjs

@@ -6817,6 +6817,32 @@ const refNameFault = (name) => {
 	}
 };
 //#endregion
+//#region src/replay/Slices.ts
+const IMPLICIT_SLICE = "main";
+/** Same shape as mark()'s name rule; kept local so @pmelab/gtd/flows publishes no regex. */
+const SLICE_NAME = /^[a-z][a-z0-9-]*$/;
+/**
+* Folds boundaries into ranges: each kept span's base is the previous kept
+* span's `leftAt`, so a gap before a span belongs to it, and the last span
+* runs to the episode tip. A closed span that landed nothing is dropped.
+*/
+const sliceRanges = (spans, episode) => {
+	if (spans.some((s) => s.enteredAt === "" || s.leftAt === "")) throw new Error("sliceRanges: a pending turn's \"\" hash is not a commit");
+	const kept = spans.filter((s) => s.leftAt === void 0 || s.enteredAt !== s.leftAt);
+	if (kept.length === 0) return [{
+		name: IMPLICIT_SLICE,
+		base: episode.base,
+		tip: episode.tip,
+		open: true
+	}];
+	return kept.map((s, i) => ({
+		name: s.name,
+		base: i === 0 ? episode.base : kept[i - 1].leftAt ?? episode.base,
+		tip: i === kept.length - 1 ? episode.tip : s.leftAt ?? episode.tip,
+		open: i === kept.length - 1
+	}));
+};
+//#endregion
 //#region src/replay/Tree.ts
 const treeFromRecord = (files) => ({
 	paths: () => Object.keys(files).sort(),
@@ -7164,6 +7190,7 @@ const replay = async (input) => {
 	const keptTips = /* @__PURE__ */ new Map();
 	let landed;
 	const marks = [];
+	const slices = [];
 	let outcome;
 	let signal;
 	const settled = new Promise((resolve) => {
@@ -7370,7 +7397,8 @@ const replay = async (input) => {
 			rest: step,
 			trace,
 			landed,
-			marks
+			marks,
+			slices: slices.map((s) => ({ ...s }))
 		});
 		return landPending(step, input.pending);
 	};
@@ -7434,6 +7462,31 @@ const replay = async (input) => {
 			scopes.pop();
 			scopeCallIds.pop();
 		},
+		enterSlice: (name) => {
+			if (outcome !== void 0) return;
+			const fail = (message) => {
+				finish({
+					kind: "failed",
+					message
+				});
+				throw new Stop();
+			};
+			if (typeof name !== "string" || !SLICE_NAME.test(name)) fail(`gtd: slice "${name}": name must match ${SLICE_NAME}`);
+			if (name === "main") fail(`gtd: slice "${IMPLICIT_SLICE}" is reserved for the implicit slice`);
+			const open = slices.find((s) => s.leftAt === void 0);
+			if (open !== void 0) fail(`gtd: slice "${name}" is entered inside slice "${open.name}" — slices do not nest`);
+			if (slices.some((s) => s.name === name)) fail(`gtd: slice "${name}" is entered twice in this episode — a loop must sit inside its slice`);
+			slices.push({
+				name,
+				enteredAt: position.hash,
+				leftAt: void 0
+			});
+		},
+		leaveSlice: () => {
+			if (outcome !== void 0) return;
+			const open = slices.find((s) => s.leftAt === void 0);
+			if (open !== void 0) open.leftAt = position.hash;
+		},
 		read: (path) => position.tree.read(path),
 		glob: (pattern) => position.tree.paths().filter((path) => globMatches(path, pattern)),
 		changes: () => changesBetween(previousPosition.tree, position.tree),
@@ -9112,6 +9165,10 @@ const pendingChanges = (git, withIndex) => gen(function* () {
 	const seen = new Set(worktree.map((e) => e.path));
 	return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))];
 });
+const sliceRangesOf = (slices, run) => sliceRanges(slices, {
+	base: run.startParentHash,
+	tip: run.trace.at(-1)?.hash ?? run.startParentHash
+});
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 const restAt = (ref, startOverrides = {}) => gen(function* () {
 	const git = yield* GitService;
@@ -9154,7 +9211,8 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 			total: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
 			byModel: costByModel(run.costEntries)
 		},
-		setup
+		setup,
+		slices: sliceRangesOf(outcome.slices, run)
 	};
 });
 const currentRest = restAt(void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "27.7.1",
+  "version": "27.8.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/edge/Edge.test.ts

@@ -596,6 +596,34 @@ export const summary = (it) => it.marks.map((m) => m.name + "=" + m.value).join(
   })
 })
 
+describe("Rest.slices", () => {
+  const SLICED = `import { agent, human, slice } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle", { message: "idle-message" })
+  await slice("build", async () => {
+    await agent("building", "build-prompt")
+  })
+  await slice("verify", async () => {
+    await agent("checking", "check-prompt")
+  })
+}
+`
+
+  it("folds the replay's spans over the run's base and its last commit", async () => {
+    const repo = repoWith(SLICED)
+    const boundary = headOf(repo)
+    await land(repo, { "a.txt": "a\n" })
+    const checking = await land(repo, { "b.txt": "b\n" })
+    const rest = await provide(currentRest, repo)
+    expect(rest.state).toBe("checking")
+    expect(rest.slices).toEqual([
+      { name: "build", base: boundary, tip: checking, open: false },
+      { name: "verify", base: checking, tip: checking, open: true },
+    ])
+  })
+})
+
 describe("restAt", () => {
   it("restAt(ref) resolves where the process rested at that commit", async () => {
     const repo = repoWith(LINEAR)

package/src/edge/Edge.ts

@@ -37,11 +37,13 @@ import {
   isRecordableApproval,
   parseCommitMessage,
   replay,
+  sliceRanges,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
   type ReachedStep,
   type ReplayOutcome,
+  type SliceRange,
   type TreeView,
 } from "../replay/index.js"
 import type { Mark, ScopeAccess } from "../flows/index.js"
@@ -895,6 +897,7 @@ interface Rest extends ResolvedRest {
   /** Total recorded cost of the process, and its per-model breakdown. */
   readonly cost: { readonly total: number; readonly byModel: readonly ModelCost[] }
   readonly setup: ReplaySetup
+  readonly slices: readonly SliceRange[]
 }
 
 /** Per-model token totals, highest-cost first (ties broken by model name). */
@@ -987,6 +990,15 @@ const pendingChanges = (git: GitOperations, withIndex: boolean) =>
     return [...worktree, ...(yield* git.stagedPaths()).filter((e) => !seen.has(e.path))]
   })
 
+const sliceRangesOf = (
+  slices: Parameters<typeof sliceRanges>[0],
+  run: { readonly startParentHash: string; readonly trace: readonly { readonly hash: string }[] },
+) =>
+  sliceRanges(slices, {
+    base: run.startParentHash,
+    tip: run.trace.at(-1)?.hash ?? run.startParentHash,
+  })
+
 /** Resolve the rest at `ref`, or at HEAD when `ref` is `undefined`. */
 export const restAt = (
   ref: string | undefined,
@@ -1060,6 +1072,7 @@ export const restAt = (
         byModel: costByModel(run.costEntries),
       },
       setup,
+      slices: sliceRangesOf(outcome.slices, run),
     }
   })
 

package/src/flows/runtime.test.ts

@@ -7,6 +7,7 @@ import {
   kept,
   mark,
   protocolMismatch,
+  slice,
   type FlowContext,
 } from "./runtime.js"
 
@@ -127,3 +128,29 @@ describe("kept()", () => {
     expect(FLOWS_PROTOCOL).toBe(1)
   })
 })
+
+describe("slice()", () => {
+  const withSlices = () => {
+    const calls: string[] = []
+    installContext({
+      enterSlice: (n: string) => calls.push(`enter ${n}`),
+      leaveSlice: () => calls.push("leave"),
+    } as unknown as FlowContext)
+    return calls
+  }
+
+  it("brackets fn with enter and leave and resolves to its value", async () => {
+    const calls = withSlices()
+    const value = await slice("refactor", async () => {
+      calls.push("fn")
+      return 42
+    })
+    expect(value).toBe(42)
+    expect(calls).toEqual(["enter refactor", "fn", "leave"])
+  })
+
+  it("runs fn unsliced on a context without enterSlice", async () => {
+    installContext(context)
+    expect(await slice("refactor", async () => "ran")).toBe("ran")
+  })
+})

package/src/flows/runtime.ts

@@ -150,6 +150,9 @@ export interface FlowContext {
   readonly refuse: (message: string) => never
   readonly pushScope: (scope: ScopeOptions) => void
   readonly popScope: () => void
+  /** Absent on an engine older than `slice`; FLOWS_PROTOCOL stays 1. */
+  readonly enterSlice?: (name: string) => void
+  readonly leaveSlice?: () => void
   readonly read: (path: string) => string | undefined
   readonly glob: (pattern: string) => readonly string[]
   /** The last step's changes, content read on demand. */
@@ -284,6 +287,21 @@ export const scope = async <T>(scope: string | ScopeOptions, fn: () => Promise<T
   }
 }
 
+/**
+ * Mark the span `fn` covers as one named slice of the process. Lands no
+ * commit, prefixes no step name, opens no memory scope.
+ */
+export const slice = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+  const context = ctx()
+  if (typeof context.enterSlice !== "function") return fn()
+  context.enterSlice(name)
+  try {
+    return await fn()
+  } finally {
+    context.leaveSlice?.()
+  }
+}
+
 // ── Reads of the commit replay stands on ────────────────────────────────────
 
 export const read = (path: string): string | undefined => ctx().read(path)

package/src/replay/Replay.test.ts

@@ -15,6 +15,7 @@ import {
   restart,
   run,
   scope,
+  slice,
   threads,
   type Flow,
   type ScopeAccess,
@@ -1210,3 +1211,139 @@ describe("human({ approve })", () => {
     expect(outcome.kind).toBe("rest")
   })
 })
+
+describe("slice()", () => {
+  const spansOf = (o: ReplayOutcome) => (o as { slices: unknown }).slices
+
+  it("records enteredAt and leftAt as the commit replay stood on", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("refactor", async () => {
+        await human("b")
+      })
+      await human("c")
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "c")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "rest" })
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(1), leftAt: hashOf(2) },
+    ])
+  })
+
+  it("keeps leftAt undefined when the process rests inside the slice", async () => {
+    const wf = async () => {
+      await slice("refactor", async () => {
+        await human("a")
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(0), leftAt: undefined },
+    ])
+  })
+
+  it("records enteredAt === leftAt for a slice that landed no commit", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("empty", async () => undefined)
+      await human("b")
+    }
+    const h = new History().land("human", "a", 1, "b")
+    expect(spansOf(await replayOf(wf, h))).toEqual([
+      { name: "empty", enteredAt: hashOf(1), leftAt: hashOf(1) },
+    ])
+  })
+
+  it("prefixes no step name and ignores an enclosing scope", async () => {
+    const wf = async () => {
+      await scope("build", async () => {
+        await slice("refactor", async () => {
+          await human("gate")
+        })
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(outcome).toMatchObject({ kind: "rest", rest: { name: "build.gate" } })
+    expect((spansOf(outcome) as { name: string }[])[0]!.name).toBe("refactor")
+  })
+
+  const failed = async (wf: Flow) => {
+    const outcome = await replayOf(wf, new History())
+    expect(outcome.kind).toBe("failed")
+    return (outcome as { message: string }).message
+  }
+
+  it.each(["Refactor", "step_1", "v2.api", ""])("refuses the name %j", async (name) => {
+    expect(await failed(async () => slice(name, async () => human("a")))).toBe(
+      `gtd: slice "${name}": name must match /^[a-z][a-z0-9-]*$/`,
+    )
+  })
+
+  it("accepts refactor-2", async () => {
+    const outcome = await replayOf(
+      async () => slice("refactor-2", async () => human("a")),
+      new History(),
+    )
+    expect(outcome.kind).toBe("rest")
+  })
+
+  it("refuses the reserved name main", async () => {
+    expect(await failed(async () => slice("main", async () => human("a")))).toBe(
+      'gtd: slice "main" is reserved for the implicit slice',
+    )
+  })
+
+  it("refuses nesting, also through scope()", async () => {
+    const message = 'gtd: slice "inner" is entered inside slice "outer" — slices do not nest'
+    expect(
+      await failed(async () => slice("outer", async () => slice("inner", async () => human("a")))),
+    ).toBe(message)
+    expect(
+      await failed(async () =>
+        slice("outer", async () => scope("s", async () => slice("inner", async () => human("a")))),
+      ),
+    ).toBe(message)
+  })
+
+  it("checks the name rule before main and nesting", async () => {
+    expect(
+      await failed(async () => slice("outer", async () => slice("Main", async () => human("a")))),
+    ).toBe('gtd: slice "Main": name must match /^[a-z][a-z0-9-]*$/')
+  })
+
+  it("lets a flow that caught an error from a slice enter another", async () => {
+    const wf = async () => {
+      try {
+        await slice("a", async () => {
+          throw new Error("boom")
+        })
+      } catch {}
+      await slice("b", async () => human("x"))
+    }
+    expect(await replayOf(wf, new History())).toMatchObject({ kind: "rest" })
+  })
+
+  it("refuses a non-string name", async () => {
+    expect(
+      await failed(async () => slice(undefined as unknown as string, async () => human("a"))),
+    ).toContain("name must match")
+  })
+
+  it("refuses a name entered twice, sequentially and from a loop", async () => {
+    const message =
+      'gtd: slice "again" is entered twice in this episode — a loop must sit inside its slice'
+    expect(
+      await failed(async () => {
+        await slice("again", async () => undefined)
+        await slice("again", async () => human("a"))
+      }),
+    ).toBe(message)
+    expect(
+      await failed(async () => {
+        for (let i = 0; i < 2; i++) await slice("again", async () => undefined)
+        await human("a")
+      }),
+    ).toBe(message)
+  })
+})

package/src/replay/Replay.ts

@@ -23,6 +23,7 @@ import {
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
+import { IMPLICIT_SLICE, SLICE_NAME, type SliceSpan } from "./Slices.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
 import {
   formatStepId,
@@ -117,6 +118,7 @@ export type ReplayOutcome =
       readonly landed: ReachedStep | undefined
       /** Marks the flow made after the pending turn's step resolved; [] without a pending turn. */
       readonly marks: readonly Mark[]
+      readonly slices: readonly SliceSpan[]
     }
   | {
       readonly kind: "ended"
@@ -297,6 +299,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   >()
   let landed: ReachedStep | undefined
   const marks: Mark[] = []
+  const slices: { name: string; enteredAt: string; leftAt: string | undefined }[] = []
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
   const settled = new Promise<void>((resolve) => {
@@ -558,7 +561,14 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
-      return finish({ kind: "rest", rest: step, trace, landed, marks })
+      return finish({
+        kind: "rest",
+        rest: step,
+        trace,
+        landed,
+        marks,
+        slices: slices.map((s) => ({ ...s })),
+      })
     }
     return landPending(step, input.pending)
   }
@@ -630,6 +640,34 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
       scopes.pop()
       scopeCallIds.pop()
     },
+    enterSlice: (name) => {
+      if (outcome !== undefined) return
+      const fail = (message: string): never => {
+        void finish({ kind: "failed", message })
+        throw new Stop()
+      }
+      if (typeof name !== "string" || !SLICE_NAME.test(name)) {
+        fail(`gtd: slice "${name}": name must match ${SLICE_NAME}`)
+      }
+      if (name === IMPLICIT_SLICE) {
+        fail(`gtd: slice "${IMPLICIT_SLICE}" is reserved for the implicit slice`)
+      }
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) {
+        fail(`gtd: slice "${name}" is entered inside slice "${open.name}" — slices do not nest`)
+      }
+      if (slices.some((s) => s.name === name)) {
+        fail(
+          `gtd: slice "${name}" is entered twice in this episode — a loop must sit inside its slice`,
+        )
+      }
+      slices.push({ name, enteredAt: position.hash, leftAt: undefined })
+    },
+    leaveSlice: () => {
+      if (outcome !== undefined) return
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) open.leftAt = position.hash
+    },
     read: (path) => position.tree.read(path),
     glob: (pattern) => position.tree.paths().filter((path) => globMatches(path, pattern)),
     changes: () => changesBetween(previousPosition.tree, position.tree),

package/src/replay/Slices.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest"
+import { sliceRanges, type SliceSpan } from "./Slices.js"
+
+const span = (name: string, enteredAt: string, leftAt?: string): SliceSpan => ({
+  name,
+  enteredAt,
+  leftAt,
+})
+const running = { base: "B", tip: "T" }
+
+describe("sliceRanges", () => {
+  it("two adjacent spans: first from episode.base to its leftAt, second from there to episode.tip", () => {
+    expect(sliceRanges([span("a", "B", "c2"), span("b", "c2", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c2", open: false },
+      { name: "b", base: "c2", tip: "T", open: true },
+    ])
+  })
+
+  it("a leading gap folds into the first range via episode.base", () => {
+    expect(sliceRanges([span("a", "c1", "c2")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("an inner gap folds into the next range: its base is the previous leftAt", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c3", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+  })
+
+  it("a trailing gap folds back: the last range's tip is the episode tip, and it stays open", () => {
+    expect(sliceRanges([span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("drops a closed empty span, first, middle and last, its neighbours absorbing the gap", () => {
+    expect(sliceRanges([span("e", "B", "B"), span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+    expect(
+      sliceRanges([span("a", "B", "c1"), span("e", "c2", "c2"), span("b", "c2", "c4")], running),
+    ).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("a", "B", "c1"), span("e", "c1", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("no spans, and only empty closed spans, each yield one open main range over the whole episode", () => {
+    const main = [{ name: "main", base: "B", tip: "T", open: true }]
+    expect(sliceRanges([], running)).toEqual(main)
+    expect(sliceRanges([span("e", "c1", "c1")], running)).toEqual(main)
+  })
+
+  it("an unleft empty span is kept and open", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("b", "T")], running)).toEqual([
+      { name: "b", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("rejects a pending turn's empty hash", () => {
+    expect(() => sliceRanges([span("a", "", "c1")], running)).toThrow("not a commit")
+    expect(() => sliceRanges([span("a", "c1", "")], running)).toThrow("not a commit")
+  })
+})

package/src/replay/Slices.ts

@@ -0,0 +1,45 @@
+export const IMPLICIT_SLICE = "main"
+
+/** Same shape as mark()'s name rule; kept local so @pmelab/gtd/flows publishes no regex. */
+export const SLICE_NAME = /^[a-z][a-z0-9-]*$/
+
+/** One slice() call as replay saw it. Hashes are the commit replay stood on; "" is a pending turn. */
+export interface SliceSpan {
+  readonly name: string
+  readonly enteredAt: string
+  /** undefined: the flow never left it — the process rests inside, or restart() fired inside. */
+  readonly leftAt: string | undefined
+}
+
+export interface SliceRange {
+  readonly name: string
+  /** Exclusive: the range is base..tip in git's sense. */
+  readonly base: string
+  readonly tip: string
+  /** The tip can still move: only the last range, since a rest is never past the episode's end. */
+  readonly open: boolean
+}
+
+/**
+ * Folds boundaries into ranges: each kept span's base is the previous kept
+ * span's `leftAt`, so a gap before a span belongs to it, and the last span
+ * runs to the episode tip. A closed span that landed nothing is dropped.
+ */
+export const sliceRanges = (
+  spans: readonly SliceSpan[],
+  episode: { readonly base: string; readonly tip: string },
+): readonly SliceRange[] => {
+  if (spans.some((s) => s.enteredAt === "" || s.leftAt === "")) {
+    throw new Error('sliceRanges: a pending turn\'s "" hash is not a commit')
+  }
+  const kept = spans.filter((s) => s.leftAt === undefined || s.enteredAt !== s.leftAt)
+  if (kept.length === 0) {
+    return [{ name: IMPLICIT_SLICE, base: episode.base, tip: episode.tip, open: true }]
+  }
+  return kept.map((s, i) => ({
+    name: s.name,
+    base: i === 0 ? episode.base : (kept[i - 1]!.leftAt ?? episode.base),
+    tip: i === kept.length - 1 ? episode.tip : (s.leftAt ?? episode.tip),
+    open: i === kept.length - 1,
+  }))
+}

package/src/replay/index.ts

@@ -12,3 +12,4 @@ export {
 export { accessShapeFault, foldAccess } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"
+export { sliceRanges, type SliceRange } from "./Slices.js"