@pmelab/gtd 24.2.0 → 24.4.0

package/src/testkit/index.ts

@@ -3,7 +3,7 @@ export { InMemRepo } from "./InMemRepo.js"
 export { makeInMemoryWorkspaceOps, testLayers, type ScriptedCommand } from "./Layers.js"
 export { makeCapturingCliIo } from "./cliIo.js"
 export { applyEmittedScript } from "./EmittedScriptRecognizer.js"
-export { gitTiers, runGitServiceContract, runGitScriptContract } from "./GitTiers.js"
+export { gitTiers, runGitServiceContract, runGitScriptContract, type GitTier } from "./GitTiers.js"
 export { strictGitOperations } from "./StrictGitOperations.js"
 export { fakeGitOperations } from "./FakeGitOperations.js"
 export type { TestkitWorld } from "./steps.js"

package/src/workflow/discovery.test.ts

@@ -0,0 +1,147 @@
+import { execSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { NodeContext } from "@effect/platform-node"
+import { Effect, Layer } from "effect"
+import { afterEach, describe, expect, it } from "vitest"
+import { GitService, Host, Narrator, Workspace } from "../platform/index.js"
+import { InMemRepo, testLayers } from "../testkit/index.js"
+import { ConfigDiscovery, ConfigService } from "./index.js"
+
+// A config and the local modules it imports load the same from disk, where
+// jiti resolves them, and from an in-memory discovery, where the loader
+// resolves them itself — the same workflows, the same fingerprint, the same
+// failure for a module that is not there.
+type Files = Readonly<Record<string, string>>
+
+interface Tier {
+  readonly load: (files: Files) => Promise<{ names: readonly string[]; fingerprint: object }>
+  readonly dispose: () => void
+}
+
+const config = (imports: string): string =>
+  [
+    'import { agent, human } from "@pmelab/gtd/flows"',
+    imports,
+    "export default async () => {",
+    '  await human("idle", { message: "go" })',
+    '  await agent("working", brief)',
+    "}",
+    "export const named = async () => {",
+    '  await agent("working", brief)',
+    "}",
+    "",
+  ].join("\n")
+
+const loadWith = (
+  layer: Layer.Layer<ConfigService | Narrator | Workspace | Host | ConfigDiscovery>,
+) =>
+  Effect.runPromise(
+    Effect.flatMap(ConfigService, (service) => service.load).pipe(
+      Effect.map((loaded) => ({ names: loaded.workflowNames, fingerprint: loaded.fingerprint })),
+      Effect.provide(layer),
+    ),
+  )
+
+const live = (): Tier => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-discovery-")))
+  execSync("git init -q && git commit -q --allow-empty -m init", {
+    cwd: root,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "t",
+      GIT_AUTHOR_EMAIL: "t@t",
+      GIT_COMMITTER_NAME: "t",
+      GIT_COMMITTER_EMAIL: "t@t",
+    },
+  })
+  return {
+    load: (files) => {
+      for (const [path, content] of Object.entries(files)) {
+        mkdirSync(dirname(join(root, path)), { recursive: true })
+        writeFileSync(join(root, path), content)
+      }
+      const host = Host.layer({ root, home: root, env: {} })
+      const git = GitService.Live.pipe(Layer.provide(Layer.merge(host, NodeContext.layer)))
+      const workspace = Workspace.Live.pipe(Layer.provide(Layer.merge(host, git)))
+      return loadWith(
+        Layer.mergeAll(
+          ConfigService.Live,
+          ConfigDiscovery.Live,
+          host,
+          workspace,
+          Narrator.layer(() => {}, false),
+        ),
+      )
+    },
+    dispose: () => rmSync(root, { recursive: true, force: true }),
+  }
+}
+
+const inMemory = (): Tier => ({
+  load: (files) => {
+    const repo = new InMemRepo()
+    for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
+    repo.commitAllWithPrefix("chore: init")
+    return loadWith(testLayers(repo))
+  },
+  dispose: () => {},
+})
+
+for (const make of [live, inMemory]) {
+  describe(`a config's local modules [${make.name}]`, () => {
+    let t: Tier
+    afterEach(() => t.dispose())
+
+    it("loads an import by its .js spelling, and one it imports in turn", async () => {
+      t = make()
+      const loaded = await t.load({
+        "gtd.config.ts": config('import { brief } from "./lib/brief.js"'),
+        "lib/brief.ts": 'import { word } from "./word"\nexport const brief = `do ${word}`\n',
+        "lib/word.ts": 'export const word = "it"\n',
+      })
+      expect(loaded.names).toEqual(["named"])
+      expect(Object.keys(loaded.fingerprint).sort()).toEqual([
+        "gtd.config.ts",
+        "lib/brief.ts",
+        "lib/word.ts",
+      ])
+    })
+
+    it("hashes each file's content the same way", async () => {
+      t = make()
+      const loaded = await t.load({
+        "gtd.config.ts": config('import { brief } from "./brief.js"'),
+        "brief.ts": 'export const brief = "do the work"\n',
+      })
+      expect(loaded.fingerprint).toEqual({
+        "brief.ts": "c59960854e8032b7",
+        "gtd.config.ts": expect.stringMatching(/^[0-9a-f]{16}$/),
+      })
+    })
+
+    it("leaves a specifier in a string alone, and loads a skipped require never", async () => {
+      t = make()
+      const loaded = await t.load({
+        "gtd.config.ts": config(
+          [
+            "const brief = \"look from './word.js'\"",
+            'if (brief === "") require("./optional.js")',
+          ].join("\n"),
+        ),
+        "word.ts": "export const word = 1\n",
+        "optional.ts": 'throw new Error("optional ran")\n',
+      })
+      expect(loaded.names).toEqual(["named"])
+      expect(Object.keys(loaded.fingerprint)).toEqual(["gtd.config.ts"])
+    })
+
+    it("fails on an import that is not there, naming it", async () => {
+      t = make()
+      await expect(
+        t.load({ "gtd.config.ts": config('import { brief } from "./missing.js"') }),
+      ).rejects.toThrow(/Cannot find module '\.\/missing\.js'/)
+    })
+  })
+}

package/src/workflow/discovery.ts

@@ -6,6 +6,11 @@ import { Context, Effect, Layer } from "effect"
 export interface WorkflowModule {
   readonly filepath: string
   readonly source: string
+  /**
+   * The modules the config imports, by absolute path, for a discovery with no
+   * disk behind it. Absent, they are read from disk like any module import.
+   */
+  readonly read?: (path: string) => string | undefined
 }
 
 /** A leftover rc file, and whether the user running gtd owns it — and so can delete it. */

package/src/workflow/fingerprint.test.ts

@@ -1,9 +1,24 @@
-import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs"
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { describe, expect, it } from "vitest"
 import { changedConfigFiles, configFingerprint } from "./fingerprint.js"
 
+const read = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
 describe("the config fingerprint", () => {
   it("hashes each file under its root-relative path, skipping one that cannot be read", () => {
     const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
@@ -14,6 +29,7 @@ describe("the config fingerprint", () => {
     const fingerprint = configFingerprint(
       [join(root, "gtd.config.ts"), join(root, "lib", "flow.ts"), join(root, "gone.ts")],
       root,
+      read,
     )
 
     expect(Object.keys(fingerprint).sort()).toEqual(["gtd.config.ts", "lib/flow.ts"])
@@ -22,7 +38,7 @@ describe("the config fingerprint", () => {
     expect(
       changedConfigFiles(
         fingerprint,
-        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root),
+        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root, read),
       ),
     ).toEqual(["lib/flow.ts"])
   })
@@ -34,7 +50,7 @@ describe("the config fingerprint", () => {
     symlinkSync(real, link)
 
     expect(
-      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link)),
+      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link, read)),
     ).toEqual(["gtd.config.ts"])
   })
 
@@ -42,7 +58,7 @@ describe("the config fingerprint", () => {
     const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
     writeFileSync(join(root, "a\x1b.ts"), "export const a = 1\n")
 
-    expect(configFingerprint([join(root, "a\x1b.ts")], root)).toEqual({})
+    expect(configFingerprint([join(root, "a\x1b.ts")], root, read)).toEqual({})
   })
 
   it("names a file only one side has as changed", () => {

package/src/workflow/fingerprint.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto"
-import { readFileSync, realpathSync } from "node:fs"
+import { realpathSync } from "node:fs"
 import { relative, sep } from "node:path"
 
 /** Path (relative to `root`) → content hash of every file a config load touched. */
@@ -27,19 +27,18 @@ const realOr = (path: string): string => {
 // feeds a warning, and the load that listed the file already read it.
 // Paths are real paths: a loader may report `/private/var/…` for a root
 // reached through the `/var` symlink, and the two must still relate.
-export const configFingerprint = (files: readonly string[], root: string): ConfigFingerprint => {
+export const configFingerprint = (
+  files: readonly string[],
+  root: string,
+  read: (path: string) => string | undefined,
+): ConfigFingerprint => {
   const fingerprint: Record<string, string> = {}
   const realRoot = realOr(root)
   for (const file of files) {
     const path = relative(realRoot, realOr(file)).split(sep).join("/")
     if (CONTROL_CHARACTER.test(path)) continue
-    let content: Buffer
-    try {
-      content = readFileSync(file)
-    } catch {
-      continue
-    }
-    fingerprint[path] = contentHash(content)
+    const content = read(file)
+    if (content !== undefined) fingerprint[path] = contentHash(content)
   }
   return fingerprint
 }

package/src/workflow/index.ts

@@ -25,9 +25,4 @@ export {
   type StateMode,
   type StateName,
 } from "./Workflow.js"
-export {
-  changedConfigFiles,
-  configFingerprint,
-  contentHash,
-  type ConfigFingerprint,
-} from "./fingerprint.js"
+export { changedConfigFiles, contentHash, type ConfigFingerprint } from "./fingerprint.js"

package/src/workflow/load.test.ts

@@ -1,13 +1,5 @@
 import { execSync } from "node:child_process"
-import {
-  existsSync,
-  readFileSync,
-  mkdtempSync,
-  realpathSync,
-  rmSync,
-  writeFileSync,
-  mkdirSync,
-} from "node:fs"
+import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs"
 import { join } from "node:path"
 import { tmpdir } from "node:os"
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
@@ -310,7 +302,7 @@ describe("ConfigService", () => {
     expect(cfg.workflow.steering).toEqual({ ".gtd/PLAN.md": "qa" })
   })
 
-  it("workflowFiles names gtd.config.ts AND a sibling module it imports from — a caller watching only gtd.config.ts's own path misses that module's edits", async () => {
+  it("the fingerprint covers gtd.config.ts AND a sibling module it imports from", async () => {
     writeFileSync(
       join(projectDir, "steps.ts"),
       [`export const steering = { ".gtd/PLAN.md": "qa" }`, ``].join("\n"),
@@ -323,19 +315,13 @@ describe("ConfigService", () => {
     const cfg = await getConfig()
 
     expect(cfg.workflow.steering[".gtd/PLAN.md"]).toBe("qa")
-    expect(cfg.workflowFiles.map((f) => realpathSync(f))).toEqual(
-      expect.arrayContaining([
-        realpathSync(join(projectDir, "gtd.config.ts")),
-        realpathSync(join(projectDir, "steps.ts")),
-      ]),
-    )
+    expect(Object.keys(cfg.fingerprint).sort()).toEqual(["gtd.config.ts", "steps.ts"])
   })
 
-  it("workflowFiles names gtd.config.ts but no shipped module it imports", async () => {
+  it("the fingerprint covers gtd.config.ts but no shipped module it imports", async () => {
     const cfg = await getConfig()
 
-    expect(cfg.workflowFiles).toHaveLength(1)
-    expect(cfg.workflowFiles[0]).toMatch(/\/gtd\.config\.ts$/)
+    expect(Object.keys(cfg.fingerprint)).toEqual(["gtd.config.ts"])
   })
 
   it.each([

package/src/workflow/load.ts

@@ -12,6 +12,7 @@ import { Host, Workspace, type WorkspaceOps } from "../platform/index.js"
 import { compileConfig, type CompiledConfig } from "./compile.js"
 import { SETTING_NAME_RULE, isSettingName } from "./vars.js"
 import { ConfigDiscovery, WORKFLOW_MODULE, type WorkflowModule } from "./discovery.js"
+import { configFingerprint, type ConfigFingerprint } from "./fingerprint.js"
 import {
   dedupeDiagnostics,
   formatDiagnostic,
@@ -41,8 +42,8 @@ export interface ConfigOperations {
   readonly ui?: flows.UiSettings
   /** Non-fatal findings, formatted through `formatDiagnostic` like an error. */
   readonly warnings: readonly Diagnostic[]
-  /** Every real file `gtd.config.ts`'s evaluation touched (itself plus any relative import). A caller that must know when `workflow` might have changed (the LSP's steering-map memo) watches all of them; watching `gtd.config.ts`'s own path alone misses an edit to a module it imports. */
-  readonly workflowFiles: readonly string[]
+  /** The content hash of every file `gtd.config.ts`'s evaluation touched — itself plus any relative import — by path relative to the root. */
+  readonly fingerprint: ConfigFingerprint
 }
 
 // Everything lives in `message` (not `GtdError.detail`) — `renderFailure`
@@ -175,10 +176,22 @@ export const load: Effect.Effect<
     },
     ...(compiled.ui !== undefined ? { ui: compiled.ui } : {}),
     warnings: diagnostics.filter((d) => d.severity === "warning"),
-    workflowFiles: loaded.file.dependencyFiles,
+    fingerprint: configFingerprint(
+      loaded.file.dependencyFiles,
+      host.root,
+      module.read ?? readFromDisk,
+    ),
   }
 })
 
+const readFromDisk = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
 interface Settings {
   readonly defaults: Readonly<Record<string, string>>
   readonly envDefaults: Readonly<Record<string, string>>
@@ -253,7 +266,14 @@ const memoized = (transform: Transform): Transform => {
 
 let jitiModule: JitiModule | undefined
 let transform: Transform | undefined
-const jiti = (shipped: ShippedModules): JitiInstance => {
+/** Relative specifiers a module imports, served from somewhere other than the disk. */
+interface LocalModules {
+  /** The path a specifier names, or nothing when it names no module. */
+  readonly resolve: (specifier: string) => string | undefined
+  readonly load: (path: string) => unknown
+}
+
+const jiti = (shipped: ShippedModules, local?: LocalModules): JitiInstance => {
   const require = createRequire(import.meta.url)
   jitiModule ??= require("jiti") as JitiModule
   // jiti's own Babel transform, which its package exports don't name.
@@ -261,7 +281,16 @@ const jiti = (shipped: ShippedModules): JitiInstance => {
     require(join(dirname(require.resolve("jiti/package.json")), "dist", "babel.cjs")) as Transform,
   )
   return jitiModule.createJiti(import.meta.url, {
-    virtualModules: shipped.modules,
+    // Consulted when a module is required, so a local module is evaluated
+    // only once an import actually runs.
+    virtualModules: new Proxy(shipped.modules, {
+      has: (modules, id) =>
+        id in modules || (typeof id === "string" && local?.resolve(id) !== undefined),
+      get: (modules, id) => {
+        const path = typeof id === "string" ? local?.resolve(id) : undefined
+        return path === undefined ? modules[id as string] : local!.load(path)
+      },
+    }),
     alias: shipped.missing,
     // No transpile cache on disk, and a fresh module every load — nothing a
     // later command could read back instead of the source.
@@ -572,11 +601,12 @@ const namespaceOf = (exported: unknown): Record<string, unknown> =>
  * pulled in, transitively.
  */
 const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded => {
-  const cache: Record<string, unknown> = {}
-  const exports = namespaceOf(
-    jiti(shipped).evalModule(module.source, { filename: module.filepath, cache }),
-  )
-  const file = fileFrom(exports, module.filepath, Object.keys(cache))
+  const { exports: evaluated, files } =
+    module.read === undefined
+      ? evaluateFromDisk(module, shipped)
+      : evaluateRead(module, module.read, shipped)
+  const exports = namespaceOf(evaluated)
+  const file = fileFrom(exports, module.filepath, files)
   const exported = Object.entries(exports).filter(
     ([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value),
   )
@@ -611,6 +641,60 @@ const loadWorkflows = (module: WorkflowModule, shipped: ShippedModules): Loaded
   }
 }
 
+const evaluateFromDisk = (
+  module: WorkflowModule,
+  shipped: ShippedModules,
+): { readonly exports: unknown; readonly files: readonly string[] } => {
+  const cache: Record<string, unknown> = {}
+  const exports = jiti(shipped).evalModule(module.source, { filename: module.filepath, cache })
+  return { exports, files: Object.keys(cache) }
+}
+
+// How jiti finds a TypeScript module behind a specifier: as written, its
+// `.js` spelling as `.ts`, with `.ts` appended, or as a directory index.
+const moduleCandidates = (path: string): readonly string[] => [
+  path,
+  path.replace(/\.js$/, ".ts"),
+  path.replace(/\.mjs$/, ".mts"),
+  `${path}.ts`,
+  join(path, "index.ts"),
+]
+
+/**
+ * Evaluates the config with every local module it imports taken from `read`
+ * instead of the disk. jiti matches a virtual module on the specifier as
+ * written, so each module gets its own instance resolving against its own
+ * directory. A specifier `read` cannot serve falls through to the disk, and
+ * fails the way a missing file does.
+ */
+const evaluateRead = (
+  module: WorkflowModule,
+  read: (path: string) => string | undefined,
+  shipped: ShippedModules,
+): { readonly exports: unknown; readonly files: readonly string[] } => {
+  const files = [module.filepath]
+  const evaluated = new Map<string, unknown>()
+  const evaluate = (filepath: string, source: string): unknown =>
+    jiti(shipped, {
+      resolve: (specifier) =>
+        /^\.\.?\//.test(specifier)
+          ? moduleCandidates(join(dirname(filepath), specifier)).find(
+              (candidate) => read(candidate) !== undefined,
+            )
+          : undefined,
+      load: (path) => {
+        if (!evaluated.has(path)) {
+          // A placeholder first, so an import cycle ends here.
+          evaluated.set(path, {})
+          files.push(path)
+          evaluated.set(path, evaluate(path, read(path)!))
+        }
+        return evaluated.get(path)
+      },
+    }).evalModule(source, { filename: filepath })
+  return { exports: evaluate(module.filepath, module.source), files }
+}
+
 const isWorkflow = (value: unknown): boolean =>
   typeof value === "function" || flows.isFactoryWorkflow(value)
 

package/src/workflow-kit/review.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+const state = vi.hoisted(() => ({ feedback: undefined as string | undefined, head: "h1" }))
+
+vi.mock("../flows/index.js", () => ({
+  changes: () => [],
+  changesSince: () => [],
+  hasThreadFor: () => false,
+  head: () => state.head,
+  read: () => state.feedback,
+  refuse: (m: string) => {
+    throw new Error(m)
+  },
+  requireReplies: () => {},
+  requireThreadsClosed: () => {},
+}))
+
+import { routeNotes, type ReviewPolicy, type Verdict } from "./review.js"
+import type { ReviewNote } from "../steering/index.js"
+
+const note = (id: string) => ({ id }) as unknown as ReviewNote
+
+const setup = (verdicts: Record<string, Verdict>) => {
+  const calls: string[] = []
+  const deferred: string[][] = []
+  const collected: ReviewNote[][] = []
+  const p = {
+    file: "r.md",
+    feedback: "f.md",
+    triage: async () => new Map(Object.entries(verdicts)),
+    answerQuestions: async () => void calls.push("answer"),
+    fixNits: async () => void calls.push("nits"),
+    keepGreen: async () => void calls.push("green"),
+    collecting: async () => {
+      calls.push("collect")
+      state.feedback = "x"
+    },
+    captures: {
+      editNotes: (_r: string, edits: readonly ReviewNote[]) => {
+        collected.push([...edits])
+        return "cap"
+      },
+    },
+    defer: async (ns: readonly ReviewNote[]) => {
+      calls.push("defer")
+      deferred.push(ns.map((n) => n.id))
+    },
+  } as unknown as ReviewPolicy
+  const r = {
+    round: "r1",
+    close: async () => void calls.push("close"),
+    outcome: (verdict: "signoff" | "feedback") => ({ verdict }) as never,
+    unfolded: async () => ({ verdict: "signoff" }) as never,
+  }
+  return { p, r, calls, deferred, collected }
+}
+
+beforeEach(() => {
+  state.feedback = undefined
+})
+
+describe("routeNotes defer", () => {
+  it("defer-only round awaits again, no collecting turn", async () => {
+    const t = setup({ a: "defer", b: "defer" })
+    const res = await routeNotes(t.p, [note("a"), note("b")], t.r)
+    expect(res).toEqual({ next: "await", reviewed: "r1" })
+    expect(t.deferred).toEqual([["a", "b"]])
+    expect(t.calls).toEqual(["defer"])
+  })
+
+  it("defer + edit collects only the edits and ends feedback", async () => {
+    const t = setup({ a: "defer", b: "edit" })
+    const res = await routeNotes(t.p, [note("a"), note("b")], t.r)
+    expect(res).toEqual({ verdict: "feedback" })
+    expect(t.calls).toEqual(["defer", "close", "collect"])
+    expect(t.collected[0]!.map((n) => n.id)).toEqual(["b"])
+  })
+
+  it("runs after nit fixes and before the collecting turn", async () => {
+    const t = setup({ a: "nit", b: "defer", c: "edit" })
+    await routeNotes(t.p, [note("a"), note("b"), note("c")], t.r)
+    expect(t.calls).toEqual(["nits", "green", "defer", "close", "collect"])
+  })
+})

package/src/workflow-kit/review.ts

@@ -24,7 +24,7 @@ export type ReviewOutcome =
       readonly edited: readonly Change[]
     }
 
-export type Verdict = "edit" | "question" | "nit" | "praise"
+export type Verdict = "edit" | "question" | "nit" | "praise" | "defer"
 
 export type ReviewRisk = ReturnType<typeof reviewRisks>[number]
 
@@ -49,6 +49,8 @@ export interface ReviewPolicy {
   readonly triage: (notes: readonly ReviewNote[]) => Promise<ReadonlyMap<string, Verdict>>
   readonly answerQuestions: (notes: readonly ReviewNote[]) => Promise<void>
   readonly fixNits: (notes: readonly ReviewNote[]) => Promise<void>
+  /** Leave `defer` notes out of the round. */
+  readonly defer: (notes: readonly ReviewNote[]) => Promise<void>
   /** Remove `file` at the end of a round at commit `round`. */
   readonly close: (round: string) => Promise<void>
   /** What a collecting turn reads. */
@@ -127,16 +129,16 @@ interface Round {
   readonly unfolded: () => Promise<Finish>
 }
 
-/** Judge every note, then run each verdict's route: answers, then nit fixes, then the edits' lap. */
-const routeNotes = async (
+/** Judge every note, then run each verdict's route: answers, then nit fixes, then deferrals, then the edits' lap. */
+export const routeNotes = async (
   p: ReviewPolicy,
   notes: readonly ReviewNote[],
   r: Round,
 ): Promise<Finish> => {
   const verdicts = await p.triage(notes)
   const of = (v: Verdict): ReviewNote[] => notes.filter((n) => (verdicts.get(n.id) ?? "edit") === v)
-  const [edits, questions, nits] = [of("edit"), of("question"), of("nit")]
-  if (edits.length + questions.length + nits.length === 0) return r.unfolded()
+  const [edits, questions, nits, deferred] = [of("edit"), of("question"), of("nit"), of("defer")]
+  if (edits.length + questions.length + nits.length + deferred.length === 0) return r.unfolded()
 
   let answeredAt: string | undefined
   if (questions.length > 0) {
@@ -147,6 +149,7 @@ const routeNotes = async (
     await p.fixNits(nits)
     await p.keepGreen()
   }
+  if (deferred.length > 0) await p.defer(deferred)
   if (edits.length > 0) {
     await r.close()
     return r.outcome(await collect(p, p.captures.editNotes(r.round, edits, answeredAt)))
@@ -155,7 +158,7 @@ const routeNotes = async (
     await r.close()
     return { next: "rereview", carry: answeredAt }
   }
-  return { next: "await", reviewed: answeredAt! }
+  return { next: "await", reviewed: answeredAt ?? r.round }
 }
 
 /** A code edit, not a thread-only change: lines that only add, answer or remove code threads don't count. */