@pmelab/gtd 23.2.0 → 24.1.0

package/src/wire/BeatPlain.ts

@@ -0,0 +1,127 @@
+import type { BeatKind } from "./Demand.js"
+import type { BeatDocument } from "./BeatDocument.js"
+import type { StatusChange } from "./BeatStatus.js"
+import { UNATTRIBUTED_MODEL } from "./constants.js"
+import type { ModelCost } from "./types.js"
+
+/**
+ * True when the per-model breakdown adds information beyond the `Cost:`
+ * total: more than one model, or a single model that carries an actual
+ * `--model` tag (a lone `unspecified` bucket just restates the total, so
+ * it's suppressed).
+ */
+const breakdownIsInformative = (byModel: readonly ModelCost[]): boolean =>
+  byModel.length > 1 || (byModel.length === 1 && byModel[0]!.model !== UNATTRIBUTED_MODEL)
+
+const costStatusLines = (cost: number, byModel: readonly ModelCost[]): string[] => {
+  if (cost <= 0) return []
+  const lines = [`Cost: ${cost}`]
+  if (breakdownIsInformative(byModel)) {
+    for (const m of byModel) lines.push(`  ${m.model}: ${m.cost}`)
+  }
+  return lines
+}
+
+const pendingStatusLines = (statusChanges: readonly StatusChange[]): string[] =>
+  statusChanges.length === 0
+    ? ["Pending: (clean)"]
+    : ["Pending:", ...statusChanges.map((c) => `  ${c.status} ${c.path}`)]
+
+const nextStatusLine = (next: BeatDocument["next"]): string =>
+  next === null ? "Next: (nothing would land)" : `Next: → ${next.target}`
+
+/** Builds `{[key]: value}` for each entry whose value isn't `undefined` — the shared "omit absent optional fields" shape the header uses. */
+const definedFields = (
+  entries: readonly (readonly [string, unknown])[],
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of entries) if (value !== undefined) result[key] = value
+  return result
+}
+
+/**
+ * The header block's own lines — `State:`/`Awaits:`/`Workflow:`/optional `Label:`/
+ * `Model:`/`Memory:`/`File:`/`Mode:`/`Cost:`(+breakdown)/`Pending:`/`Next:`,
+ * in that order. Used by `renderBeatPlain`'s header-showing kinds below.
+ */
+const beatHeaderLines = (document: BeatDocument): string[] => {
+  const optional = definedFields([
+    ["Label", document.label],
+    ["Model", document.model],
+    ["Memory", document.memory],
+    ["File", document.file],
+    ["Mode", document.mode],
+  ])
+  return [
+    `State: ${document.state}`,
+    `Awaits: ${document.actor}`,
+    `Workflow: ${document.workflow}`,
+    ...Object.entries(optional).map(([key, value]) => `${key}: ${value}`),
+    ...costStatusLines(document.cost ?? 0, document.costByModel ?? []),
+    ...pendingStatusLines(document.changes),
+    nextStatusLine(document.next),
+  ]
+}
+
+/** `script`'s plain-output instruction line — a literal constant, never a template. */
+const SCRIPT_INSTRUCTION = "Run this script:"
+
+/** `capture`'s plain-output instruction line — a literal constant, never a template. */
+const CAPTURE_INSTRUCTION = "The edit is already made — run `gtd land` to land it."
+
+/** One `BeatKind`'s plain-render briefing: the instruction line prepended above the header (`undefined` for none), and whether the status header is suppressed entirely (`prompt` alone — those bytes ARE the agent's input). */
+export interface DemandBriefing {
+  readonly instructionLine: string | undefined
+  readonly suppressHeader: boolean
+}
+
+/**
+ * One entry per `BeatKind`, typed as `Record<BeatKind, DemandBriefing>` so
+ * the object literal itself is exhaustive: adding or removing a `BeatKind`
+ * member without updating this map fails `tsc`, the same guarantee
+ * `dispatchFieldsOf`'s switch (`BeatDocument.ts`) gives the JSON side. Exported
+ * so the one cross-cutting exhaustiveness test (`BeatDocument.test.ts`) can
+ * assert against it directly, rather than re-deriving it from
+ * `renderBeatPlain`'s output. Replaces the old `renderBeatPlain`'s hand-written
+ * `if (kind === "script") … if (kind === "capture") …` pair.
+ */
+export const DEMAND_BRIEFING: Record<BeatKind, DemandBriefing> = {
+  capture: { instructionLine: CAPTURE_INSTRUCTION, suppressHeader: false },
+  message: { instructionLine: undefined, suppressHeader: false },
+  script: { instructionLine: SCRIPT_INSTRUCTION, suppressHeader: false },
+  stalled: { instructionLine: undefined, suppressHeader: false },
+  prompt: { instructionLine: undefined, suppressHeader: true },
+}
+
+/**
+ * The self-validation instruction appended to a `prompt` beat's plain output
+ * only — a structured (`--json`) driver runs the `validate` field
+ * itself instead. Advisory either way: `gtd land` refuses a turn whose
+ * steering file is invalid regardless of whether this was followed.
+ */
+const selfValidateInstruction = (command: string, file: string): string =>
+  `\nBefore finishing your turn, run \`${command}\` — it checks ${file} — and fix ` +
+  `every violation it reports until it exits cleanly. Do not finish while it ` +
+  `still reports violations.\n`
+
+/**
+ * `gtd next`'s plain-text encoding, driven by `DEMAND_BRIEFING`. At
+ * `kind === "prompt"` the status header is suppressed and only `content`
+ * plus the self-validation instruction is emitted — those bytes ARE the
+ * agent's input, so gtd's own bookkeeping (state name, edges, pending
+ * changes) must not be prefixed onto it. Every other kind gets the header
+ * plus its instruction line, since its plain output is read by a human or
+ * driver, never an agent. `selfValidateCommand` is already resolved; this
+ * function never resolves it itself.
+ */
+export const renderBeatPlain = (document: BeatDocument, selfValidateCommand?: string): string => {
+  const content = document.content.endsWith("\n") ? document.content : document.content + "\n"
+  const briefing = DEMAND_BRIEFING[document.kind]
+  if (briefing.suppressHeader) {
+    return selfValidateCommand !== undefined && document.file !== undefined
+      ? content + selfValidateInstruction(selfValidateCommand, document.file)
+      : content
+  }
+  const body = beatHeaderLines(document).join("\n") + "\n\n" + content
+  return briefing.instructionLine !== undefined ? `${briefing.instructionLine}\n` + body : body
+}

package/src/wire/BeatStatus.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest"
+import { statusOf } from "./BeatStatus.js"
+import type { RenderedDemandSource } from "./index.js"
+
+const rendered = (overrides: Partial<RenderedDemandSource> = {}): RenderedDemandSource => ({
+  state: "build.fixing",
+  actor: "agent",
+  content: "fix it",
+  ...overrides,
+})
+
+const baseInput = (overrides: Partial<RenderedDemandSource> = {}) => ({
+  rendered: rendered(overrides),
+  idle: false,
+  initial: false,
+  workflow: "feature",
+  log: "log",
+  changes: [],
+  next: null,
+  cost: 0,
+  costByModel: [],
+})
+
+describe("statusOf", () => {
+  it("carries model through verbatim, including the empty string", () => {
+    expect(statusOf(baseInput({ model: "" })).model).toBe("")
+  })
+
+  it("omits system when its rendered value is the empty string, unlike model", () => {
+    const status = statusOf(baseInput({ model: "", system: "" }))
+    expect(status.system).toBeUndefined()
+    expect(status.model).toBe("")
+  })
+
+  it("carries system through when non-empty", () => {
+    expect(statusOf(baseInput({ system: "a persona" })).system).toBe("a persona")
+  })
+
+  it("carries idle/log/changes/next/cost/costByModel through unchanged (ungated — beatDocument applies the wire's omission rules)", () => {
+    const status = statusOf({
+      rendered: rendered(),
+      idle: true,
+      initial: true,
+      workflow: "feature",
+      log: ".git/gtd-loop.log",
+      changes: [{ status: "M", path: "TODO.md" }],
+      next: { target: "idle" },
+      cost: 12,
+      costByModel: [{ model: "opus", cost: 12 }],
+    })
+    expect(status.workflow).toBe("feature")
+    expect(status.idle).toBe(true)
+    expect(status.log).toBe(".git/gtd-loop.log")
+    expect(status.changes).toEqual([{ status: "M", path: "TODO.md" }])
+    expect(status.next).toEqual({ target: "idle" })
+    expect(status.cost).toBe(12)
+    expect(status.costByModel).toEqual([{ model: "opus", cost: 12 }])
+  })
+})

package/src/wire/BeatStatus.ts

@@ -0,0 +1,81 @@
+import type { Actor, ModelCost, RenderedDemandSource, StateMode, StateName } from "./types.js"
+
+/** One pending change — `gtd next --json`'s `changes` entries. */
+export interface StatusChange {
+  readonly status: string
+  readonly path: string
+}
+
+/** The step landing the pending change would leave the process at. */
+export interface NextMatch {
+  readonly target: string
+}
+
+/**
+ * Everything a `gtd next` beat carries that no driver `case`-arm branches on
+ * — the doc-tested minimal driver never reads any of these except
+ * `model`/`system` (read unconditionally, not gated to a `kind`) and never
+ * switches behavior on them. Ungated: `cost`/`costByModel`/`next` here carry
+ * their raw values; `beatDocument` applies the wire's own
+ * present-vs-omitted rules when flattening.
+ */
+export interface BeatStatus {
+  readonly idle: boolean
+  /** No process is underway, whatever the tree holds — `idle` additionally needs a clean tree. */
+  readonly initial: boolean
+  readonly model: string | undefined
+  readonly system: string | undefined
+  readonly log: string
+  readonly state: StateName
+  readonly actor: Actor
+  /** The workflow the process runs: its pinned name, or the default's display name. */
+  readonly workflow: string
+  readonly label: string | undefined
+  readonly memory: string | undefined
+  readonly file: string | undefined
+  readonly mode: StateMode | undefined
+  readonly changes: readonly StatusChange[]
+  readonly next: NextMatch | null
+  readonly cost: number
+  readonly costByModel: readonly ModelCost[]
+  readonly judge: string | undefined
+}
+
+/**
+ * Assemble one `BeatStatus`. `system` is omitted (not just falsy) when its
+ * rendered value is the empty string, unlike `model`: an empty
+ * `--system-prompt ""` would silently delete the harness's own default
+ * instead of failing loudly.
+ */
+export const statusOf = (input: {
+  readonly rendered: RenderedDemandSource
+  readonly idle: boolean
+  readonly initial: boolean
+  readonly workflow: string
+  readonly log: string
+  readonly changes: readonly StatusChange[]
+  readonly next: NextMatch | null
+  readonly cost: number
+  readonly costByModel: readonly ModelCost[]
+}): BeatStatus => {
+  const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input
+  return {
+    idle,
+    initial,
+    model: rendered.model,
+    system: rendered.system !== undefined && rendered.system !== "" ? rendered.system : undefined,
+    log,
+    state: rendered.state,
+    actor: rendered.actor,
+    workflow,
+    label: rendered.label,
+    memory: rendered.memory,
+    file: rendered.file,
+    mode: rendered.mode,
+    changes,
+    next,
+    cost,
+    costByModel,
+    judge: rendered.judge,
+  }
+}

package/src/wire/Demand.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest"
+import { BEAT_KINDS, beatKindOf, demandOf, stallDiagnosis } from "./Demand.js"
+import type { RenderedDemandSource } from "./index.js"
+
+const rendered = (overrides: Partial<RenderedDemandSource> = {}): RenderedDemandSource => ({
+  state: "build.fixing",
+  actor: "agent",
+  content: "fix it",
+  ...overrides,
+})
+
+describe("beatKindOf", () => {
+  it("is stalled whenever stalled is true, regardless of content kind or dirtiness", () => {
+    for (const contentKind of ["script", "prompt", "message"] as const) {
+      for (const dirty of [true, false]) {
+        expect(beatKindOf({ contentKind, dirty, stalled: true })).toBe("stalled")
+      }
+    }
+  })
+
+  it("is capture at a dirty message rest", () => {
+    expect(beatKindOf({ contentKind: "message", dirty: true, stalled: false })).toBe("capture")
+  })
+
+  it("is message at a clean message rest", () => {
+    expect(beatKindOf({ contentKind: "message", dirty: false, stalled: false })).toBe("message")
+  })
+
+  it("is script at a script rest, dirty or clean", () => {
+    expect(beatKindOf({ contentKind: "script", dirty: true, stalled: false })).toBe("script")
+    expect(beatKindOf({ contentKind: "script", dirty: false, stalled: false })).toBe("script")
+  })
+
+  it("is prompt at a prompt rest, dirty or clean", () => {
+    expect(beatKindOf({ contentKind: "prompt", dirty: true, stalled: false })).toBe("prompt")
+    expect(beatKindOf({ contentKind: "prompt", dirty: false, stalled: false })).toBe("prompt")
+  })
+})
+
+describe("stallDiagnosis", () => {
+  it("names the step and mentions both escapes", () => {
+    const text = stallDiagnosis("build.working", "agent")
+    expect(text).toContain('stalled at "build.working"')
+    expect(text).toContain("gtd(agent): build.working")
+    expect(text).toMatch(/escalation/)
+    expect(text).toMatch(/allowEmpty: true/)
+    expect(text).toMatch(/prompt so the turn has something concrete/)
+  })
+})
+
+describe("demandOf", () => {
+  it("uses the rendered content verbatim at every non-stalled kind", () => {
+    for (const kind of BEAT_KINDS.filter((k) => k !== "stalled")) {
+      const demand = demandOf({ rendered: rendered(), kind })
+      expect(demand.content).toBe("fix it")
+    }
+  })
+
+  it("uses the stall diagnosis as content, never the rendered content, at kind stalled", () => {
+    const demand = demandOf({ rendered: rendered(), kind: "stalled" })
+    expect(demand.content).toBe(stallDiagnosis("build.fixing", "agent"))
+    expect(demand.content).not.toBe("fix it")
+  })
+
+  it("carries session/validate only on the prompt variant — no other kind's Demand shape can hold them", () => {
+    const session = { id: "8f2c", resume: true }
+    for (const kind of BEAT_KINDS.filter((k) => k !== "prompt")) {
+      const demand = demandOf({
+        rendered: rendered(),
+        kind,
+        session,
+        validate: "gtd check qa 'TODO.md'",
+      })
+      expect("session" in demand).toBe(false)
+      expect("validate" in demand).toBe(false)
+    }
+  })
+
+  it("carries session/validate at kind prompt when supplied", () => {
+    const session = { id: "8f2c", resume: true }
+    const demand = demandOf({
+      rendered: rendered(),
+      kind: "prompt",
+      session,
+      validate: "gtd check qa 'TODO.md'",
+    })
+    expect(demand.kind).toBe("prompt")
+    if (demand.kind !== "prompt") throw new Error("unreachable")
+    expect(demand.session).toEqual(session)
+    expect(demand.validate).toBe("gtd check qa 'TODO.md'")
+  })
+
+  it("carries session/validate present-with-undefined (not omitted) at kind prompt when the caller supplied none", () => {
+    const demand = demandOf({ rendered: rendered(), kind: "prompt" })
+    expect(demand.kind).toBe("prompt")
+    if (demand.kind !== "prompt") throw new Error("unreachable")
+    expect("session" in demand).toBe(true)
+    expect(demand.session).toBeUndefined()
+    expect("validate" in demand).toBe(true)
+    expect(demand.validate).toBeUndefined()
+  })
+
+  it("carries skills at kind prompt when the rendered source has a non-empty list", () => {
+    const demand = demandOf({ rendered: rendered({ skills: ["a", "b"] }), kind: "prompt" })
+    expect(demand.kind).toBe("prompt")
+    if (demand.kind !== "prompt") throw new Error("unreachable")
+    expect(demand.skills).toEqual(["a", "b"])
+  })
+
+  it("normalizes an empty or absent skills list to undefined at kind prompt, never []", () => {
+    const empty = demandOf({ rendered: rendered({ skills: [] }), kind: "prompt" })
+    const absent = demandOf({ rendered: rendered(), kind: "prompt" })
+    if (empty.kind !== "prompt" || absent.kind !== "prompt") throw new Error("unreachable")
+    expect(empty.skills).toBeUndefined()
+    expect(absent.skills).toBeUndefined()
+  })
+
+  it("carries access at kind prompt, unrestricted on both sides when the source has none", () => {
+    const bare = demandOf({ rendered: rendered(), kind: "prompt" })
+    const restricted = demandOf({
+      rendered: rendered({ access: { read: ["docs/**"], write: [] } }),
+      kind: "prompt",
+    })
+    if (bare.kind !== "prompt" || restricted.kind !== "prompt") throw new Error("unreachable")
+    expect(bare.access).toEqual({ read: null, write: null })
+    expect(restricted.access).toEqual({ read: ["docs/**"], write: [] })
+  })
+
+  it("carries no access field at any non-prompt kind", () => {
+    for (const kind of BEAT_KINDS.filter((k) => k !== "prompt")) {
+      const demand = demandOf({ rendered: rendered({ access: { read: null, write: [] } }), kind })
+      expect("access" in demand).toBe(false)
+    }
+  })
+
+  it("carries no skills field at any non-prompt kind, even when the rendered source has one", () => {
+    for (const kind of BEAT_KINDS.filter((k) => k !== "prompt")) {
+      const demand = demandOf({ rendered: rendered({ skills: ["a"] }), kind })
+      expect("skills" in demand).toBe(false)
+    }
+  })
+})

package/src/wire/Demand.ts

@@ -0,0 +1,108 @@
+import type { Actor, ContentKind, RenderedDemandSource, StateName, StepAccess } from "./types.js"
+
+/** The whole beat vocabulary a driver acts on — what to DO with a rest, not merely whether dispatching it is safe. */
+export type BeatKind = "capture" | "message" | "script" | "prompt" | "stalled"
+
+/**
+ * `BeatKind`'s own member list, as a value — the ONE place the five kinds are
+ * enumerated. Every test that needs to loop "every kind" (the JSON document,
+ * `DEMAND_BRIEFING`, the plain header) imports this instead of re-typing its
+ * own `as const satisfies readonly BeatKind[]` literal, so the type and the
+ * loop can never drift apart.
+ */
+export const BEAT_KINDS: readonly BeatKind[] = ["capture", "message", "script", "prompt", "stalled"]
+
+/**
+ * A resting content kind: `renderRest` never resolves a `Rest` at a commit
+ * state, so `beatKindOf` is never handed `"commit"` — narrowing the
+ * parameter here (rather than switching on all four `ContentKind`s) makes
+ * that case unwritable instead of merely untested.
+ */
+export type RestingContentKind = Exclude<ContentKind, "commit">
+
+/**
+ * The beat kind for a rest, in precedence order:
+ *
+ * 1. `stalled` — `Edge.ts`'s `stalledAt` verdict, passed in as a plain
+ *    boolean (this module never resolves it itself). `stalledAt` already
+ *    requires a clean tree, so this can never collide with `capture` below.
+ * 2. `capture` — a `message` rest with a DIRTY tree: the human already
+ *    acted; a driver lands it immediately.
+ * 3. Otherwise, the content kind verbatim (`script`/`prompt`, or `message`
+ *    on a clean tree).
+ */
+export const beatKindOf = (input: {
+  readonly contentKind: RestingContentKind
+  readonly dirty: boolean
+  readonly stalled: boolean
+}): BeatKind => {
+  if (input.stalled) return "stalled"
+  if (input.contentKind === "message" && input.dirty) return "capture"
+  return input.contentKind
+}
+
+/**
+ * The `stalled` beat's own content: a diagnosis naming the stuck step and
+ * the ways out. The first line is shaped so a stderr grep for
+ * `stalled at "<state>"` stays a stable substring (see
+ * `tests/integration/features/driver-doc.feature`).
+ */
+export const stallDiagnosis = (state: StateName, actor: Actor): string =>
+  `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty ` +
+  `attempt, the tree is clean, and another dispatch would repeat it.\n\n` +
+  `Two ways out:\n` +
+  `  - sharpen the step's prompt so the turn has something concrete to author\n` +
+  `  - pass allowEmpty: true to the step, so an empty turn completes it and the\n` +
+  `    flow decides what follows — finishing, or an escalation step after N\n` +
+  `    empty turns\n`
+
+/** One dispatch session — `resume`'s own meaning lives with `src/wire/Sessions.ts`'s `resolveSession`, which produces it. */
+export interface DemandSession {
+  readonly id: string
+  readonly resume: boolean
+}
+
+/**
+ * One driver `case` arm's whole demand: what to DO, and (only at `prompt`)
+ * the dispatch bookkeeping (`session`/`validate`) no other kind carries.
+ * Replaces `BeatFields`' flat `session`/`validate` fields (gated at
+ * `kind === "prompt"` by a runtime check) with a shape where a non-`prompt`
+ * variant cannot HOLD a session at all.
+ */
+export type Demand =
+  | { readonly kind: "capture"; readonly content: string }
+  | { readonly kind: "message"; readonly content: string }
+  | { readonly kind: "script"; readonly content: string }
+  | { readonly kind: "stalled"; readonly content: string }
+  | {
+      readonly kind: "prompt"
+      readonly content: string
+      readonly session: DemandSession | undefined
+      readonly validate: string | undefined
+      readonly skills: readonly string[] | undefined
+      readonly access: StepAccess
+    }
+
+/**
+ * Assemble one `Demand` — the ONLY place a rest's resolved content becomes
+ * `Demand.content` (`stallDiagnosis` at `kind === "stalled"`, the rendered
+ * content otherwise), and the only place `session`/`validate`/`skills`/`access` are
+ * attached, which the `prompt` variant's own type makes impossible to do at
+ * any other kind.
+ */
+export const demandOf = (input: {
+  readonly rendered: Pick<RenderedDemandSource, "actor" | "content" | "state" | "skills" | "access">
+  readonly kind: BeatKind
+  readonly session?: DemandSession
+  readonly validate?: string
+}): Demand => {
+  const { rendered, kind, session, validate } = input
+  const content =
+    kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content
+  const skills =
+    rendered.skills !== undefined && rendered.skills.length > 0 ? rendered.skills : undefined
+  const access = rendered.access ?? { read: null, write: null }
+  return kind === "prompt"
+    ? { kind, content, session, validate, skills, access }
+    : { kind, content }
+}

package/src/wire/ExitCodes.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest"
+import {
+  EXIT_CODES,
+  EXIT_OK,
+  EXIT_RUNTIME_ERROR,
+  EXIT_SIGINT,
+  EXIT_SIGTERM,
+  EXIT_USAGE_ERROR,
+} from "./index.js"
+
+describe("EXIT_CODES", () => {
+  it("is frozen at exactly {0, 1, 2, 130, 143} — a new code breaks every driver", () => {
+    expect(EXIT_CODES).toEqual(new Set([0, 1, 2, 130, 143]))
+  })
+
+  it("each named constant is a member of the set", () => {
+    for (const code of [EXIT_OK, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR, EXIT_SIGINT, EXIT_SIGTERM]) {
+      expect(EXIT_CODES.has(code)).toBe(true)
+    }
+  })
+})

package/src/wire/ExitCodes.ts

@@ -0,0 +1,16 @@
+export const EXIT_OK = 0
+/** Something failed that was never a matter of how gtd was invoked — a refusal or an unexpected error. */
+export const EXIT_RUNTIME_ERROR = 1
+/** gtd was invoked wrong — an unknown option/command, bad arity, a scope violation, a decode failure. */
+export const EXIT_USAGE_ERROR = 2
+export const EXIT_SIGINT = 130
+export const EXIT_SIGTERM = 143
+
+/** Frozen: adding a code is a driver-protocol break, the same as removing a wire field. */
+export const EXIT_CODES: ReadonlySet<number> = new Set([
+  EXIT_OK,
+  EXIT_RUNTIME_ERROR,
+  EXIT_USAGE_ERROR,
+  EXIT_SIGINT,
+  EXIT_SIGTERM,
+])

package/src/wire/Glob.ts

@@ -0,0 +1,29 @@
+// `*` stays within one path segment, `**` crosses any number of them (zero
+// included), and dotfiles are not special: this matches repository paths, not
+// a shell's filename expansion.
+
+const ESCAPE_RE = /[.+^${}()|[\]\\?]/g
+
+const compile = (glob: string): RegExp => {
+  let pattern = "^"
+  let i = 0
+  while (i < glob.length) {
+    const char = glob[i]!
+    if (char !== "*") {
+      pattern += char.replace(ESCAPE_RE, "\\$&")
+      i += 1
+    } else if (glob[i + 1] !== "*") {
+      pattern += "[^/]*"
+      i += 1
+    } else if (glob[i + 2] === "/") {
+      pattern += "(?:.*/)?"
+      i += 3
+    } else {
+      pattern += ".*"
+      i += 2
+    }
+  }
+  return new RegExp(`${pattern}$`)
+}
+
+export const globMatches = (path: string, glob: string): boolean => compile(glob).test(path)

package/src/wire/Judge.ts

@@ -0,0 +1,22 @@
+import { WIRE_SCHEMA } from "./constants.js"
+
+export type JudgePrimitive = "noul" | "choice" | "score"
+
+export interface JudgeQuestion {
+  readonly id: string
+  readonly primitive: JudgePrimitive
+  readonly instructions: string
+  readonly criteria: string
+}
+
+/** Everything a judge needs: a judge gate's beat carries it, stringified, in `judge`; `gtd judge run` reads it on stdin. */
+export interface JudgeDocument {
+  readonly schema: number
+  readonly state: Readonly<Record<string, string>>
+  readonly questions: readonly JudgeQuestion[]
+}
+
+export const judgeJson = (
+  state: JudgeDocument["state"],
+  questions: JudgeDocument["questions"],
+): string => JSON.stringify({ schema: WIRE_SCHEMA, state, questions } satisfies JudgeDocument)