@pmelab/gtd 23.2.0 → 24.1.0

package/src/wire/constants.ts

@@ -0,0 +1,22 @@
+// Zero imports on purpose: a leaf both `Edge.ts` and this module's siblings
+// can import, so `"unspecified"` exists exactly once in the codebase.
+
+/**
+ * The top-level `schema` of every JSON document a driver reads. Bumped only
+ * when a field is removed or renamed — never for an added one — and never tied
+ * to the package version, since a driver can be installed apart from gtd.
+ */
+export const WIRE_SCHEMA = 1
+
+/** The bucket a cost with no `--model` tag is grouped under, kept distinct so a mixed history still totals correctly. */
+export const UNATTRIBUTED_MODEL = "unspecified"
+
+/** The plain-text twin of `OutcomeScript.ts`'s `printfLine`. Lives here so `src/wire/`'s encoders reach it without importing out of the leaf. */
+export const renderFormat = (fmt: string, ...args: readonly string[]): string => {
+  let i = 0
+  return fmt.replace(/%s/g, () => args[i++] ?? "")
+}
+
+/** The first line of the landing refusal for a turn that wrote outside its `write` access — a stable marker drivers and tests grep for. */
+export const ACCESS_REFUSAL =
+  "gtd land: this turn wrote outside its write access — revert these paths, then run `gtd land` again:"

package/src/wire/golden/1/beat-capture.json

@@ -0,0 +1,34 @@
+{
+  "schema": 1,
+  "kind": "capture",
+  "content": "fix it",
+  "idle": false,
+  "initial": false,
+  "model": "opus",
+  "system": "You are a careful senior engineer.",
+  "log": ".git/gtd-loop.log",
+  "state": "build.fixing",
+  "actor": "agent",
+  "workflow": "feature",
+  "label": "Fixing",
+  "memory": "build#a1b2c3d",
+  "file": "TODO.md",
+  "mode": "qa",
+  "changes": [
+    {
+      "status": "M",
+      "path": "TODO.md"
+    }
+  ],
+  "next": {
+    "target": "idle"
+  },
+  "cost": 12,
+  "costByModel": [
+    {
+      "model": "opus",
+      "cost": 12
+    }
+  ],
+  "judge": "{\"schema\":1,\"state\":{\"diff\":\"…\"},\"questions\":[{\"id\":\"q1\",\"primitive\":\"noul\",\"instructions\":\"Is the change done?\",\"criteria\":\"yes: every item ticked\"}]}"
+}

package/src/wire/golden/1/beat-message.json

@@ -0,0 +1,34 @@
+{
+  "schema": 1,
+  "kind": "message",
+  "content": "fix it",
+  "idle": false,
+  "initial": false,
+  "model": "opus",
+  "system": "You are a careful senior engineer.",
+  "log": ".git/gtd-loop.log",
+  "state": "build.fixing",
+  "actor": "agent",
+  "workflow": "feature",
+  "label": "Fixing",
+  "memory": "build#a1b2c3d",
+  "file": "TODO.md",
+  "mode": "qa",
+  "changes": [
+    {
+      "status": "M",
+      "path": "TODO.md"
+    }
+  ],
+  "next": {
+    "target": "idle"
+  },
+  "cost": 12,
+  "costByModel": [
+    {
+      "model": "opus",
+      "cost": 12
+    }
+  ],
+  "judge": "{\"schema\":1,\"state\":{\"diff\":\"…\"},\"questions\":[{\"id\":\"q1\",\"primitive\":\"noul\",\"instructions\":\"Is the change done?\",\"criteria\":\"yes: every item ticked\"}]}"
+}

package/src/wire/golden/1/beat-prompt.json

@@ -0,0 +1,44 @@
+{
+  "schema": 1,
+  "kind": "prompt",
+  "content": "fix it",
+  "idle": false,
+  "initial": false,
+  "session": {
+    "id": "8f2c",
+    "resume": true
+  },
+  "model": "opus",
+  "system": "You are a careful senior engineer.",
+  "validate": "gtd check qa 'TODO.md'",
+  "log": ".git/gtd-loop.log",
+  "state": "build.fixing",
+  "actor": "agent",
+  "workflow": "feature",
+  "label": "Fixing",
+  "memory": "build#a1b2c3d",
+  "file": "TODO.md",
+  "mode": "qa",
+  "changes": [
+    {
+      "status": "M",
+      "path": "TODO.md"
+    }
+  ],
+  "next": {
+    "target": "idle"
+  },
+  "cost": 12,
+  "costByModel": [
+    {
+      "model": "opus",
+      "cost": 12
+    }
+  ],
+  "judge": "{\"schema\":1,\"state\":{\"diff\":\"…\"},\"questions\":[{\"id\":\"q1\",\"primitive\":\"noul\",\"instructions\":\"Is the change done?\",\"criteria\":\"yes: every item ticked\"}]}",
+  "skills": ["code-review"],
+  "access": {
+    "read": null,
+    "write": [".gtd/TODO.md"]
+  }
+}

package/src/wire/golden/1/beat-script.json

@@ -0,0 +1,34 @@
+{
+  "schema": 1,
+  "kind": "script",
+  "content": "fix it",
+  "idle": false,
+  "initial": false,
+  "model": "opus",
+  "system": "You are a careful senior engineer.",
+  "log": ".git/gtd-loop.log",
+  "state": "build.fixing",
+  "actor": "agent",
+  "workflow": "feature",
+  "label": "Fixing",
+  "memory": "build#a1b2c3d",
+  "file": "TODO.md",
+  "mode": "qa",
+  "changes": [
+    {
+      "status": "M",
+      "path": "TODO.md"
+    }
+  ],
+  "next": {
+    "target": "idle"
+  },
+  "cost": 12,
+  "costByModel": [
+    {
+      "model": "opus",
+      "cost": 12
+    }
+  ],
+  "judge": "{\"schema\":1,\"state\":{\"diff\":\"…\"},\"questions\":[{\"id\":\"q1\",\"primitive\":\"noul\",\"instructions\":\"Is the change done?\",\"criteria\":\"yes: every item ticked\"}]}"
+}

package/src/wire/golden/1/beat-stalled.json

@@ -0,0 +1,34 @@
+{
+  "schema": 1,
+  "kind": "stalled",
+  "content": "stalled at \"build.fixing\": the last gtd(agent): build.fixing turn landed an empty attempt, the tree is clean, and another dispatch would repeat it.\n\nTwo 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",
+  "idle": false,
+  "initial": false,
+  "model": "opus",
+  "system": "You are a careful senior engineer.",
+  "log": ".git/gtd-loop.log",
+  "state": "build.fixing",
+  "actor": "agent",
+  "workflow": "feature",
+  "label": "Fixing",
+  "memory": "build#a1b2c3d",
+  "file": "TODO.md",
+  "mode": "qa",
+  "changes": [
+    {
+      "status": "M",
+      "path": "TODO.md"
+    }
+  ],
+  "next": {
+    "target": "idle"
+  },
+  "cost": 12,
+  "costByModel": [
+    {
+      "model": "opus",
+      "cost": 12
+    }
+  ],
+  "judge": "{\"schema\":1,\"state\":{\"diff\":\"…\"},\"questions\":[{\"id\":\"q1\",\"primitive\":\"noul\",\"instructions\":\"Is the change done?\",\"criteria\":\"yes: every item ticked\"}]}"
+}

package/src/wire/golden/1/judge.json

@@ -0,0 +1,14 @@
+{
+  "schema": 1,
+  "state": {
+    "diff": "…"
+  },
+  "questions": [
+    {
+      "id": "q1",
+      "primitive": "noul",
+      "instructions": "Is the change done?",
+      "criteria": "yes: every item ticked"
+    }
+  ]
+}

package/src/wire/golden/1/land-noop.json

@@ -0,0 +1,10 @@
+{
+  "schema": 1,
+  "script": "printf '%s\\n' 'nothing to do at \"idle\"'\n",
+  "settled": true,
+  "idle": true,
+  "state": "idle",
+  "subject": null,
+  "cost": null,
+  "model": null
+}

package/src/wire/golden/1/land.json

@@ -0,0 +1,10 @@
+{
+  "schema": 1,
+  "script": "git commit ...\n",
+  "settled": false,
+  "idle": false,
+  "state": "build.review.closing",
+  "subject": "gtd(agent): build.fixing",
+  "cost": 0.42,
+  "model": "smart"
+}

package/src/wire/index.ts

@@ -0,0 +1,12 @@
+export * from "./constants.js"
+export * from "./ExitCodes.js"
+export * from "./types.js"
+export * from "./Demand.js"
+export * from "./BeatStatus.js"
+export * from "./BeatDocument.js"
+export * from "./BeatPlain.js"
+export * from "./Land.js"
+export * from "./Judge.js"
+export { selectPath } from "./Select.js"
+export { resolveSession } from "./Sessions.js"
+export { globMatches } from "./Glob.js"

package/src/wire/types.ts

@@ -0,0 +1,46 @@
+// Zero imports on purpose — this is the wire's own vocabulary tier, so
+// `wire` stays a leaf every other module may import.
+
+/** No closed vocabulary of "kinds" — any workflow-defined string. */
+export type Actor = string
+
+/** Defined by whatever keys `WorkflowDefinition.states` declares — not a closed vocabulary. */
+export type StateName = string
+
+/** The three content kinds a state can carry — exactly one per state. */
+export type ContentKind = "script" | "prompt" | "message"
+
+/** The name of a steering-file mode. Not a closed vocabulary: the valid set derives from the active definition (`BUILT_IN_MODES` plus whatever `modes:` declares). */
+export type StateMode = string
+
+/** One model's summed token cost — the shape `gtd summary`'s template iterates as `it.processCostByModel`, and `gtd next --json`'s `costByModel` entries. */
+export interface ModelCost {
+  readonly model: string
+  readonly cost: number
+}
+
+/**
+ * The subset of `Edge.ts`'s `RenderedRest` the beat builders below read,
+ * expressed structurally so this module never imports `RenderedRest` itself
+ * — that import (even type-only) would be a Sheriff edge back to root.
+ * `RenderedRest` satisfies this shape today and must keep doing so.
+ */
+export interface StepAccess {
+  readonly read: readonly string[] | null
+  readonly write: readonly string[] | null
+}
+
+export interface RenderedDemandSource {
+  readonly state: StateName
+  readonly actor: Actor
+  readonly content: string
+  readonly model?: string
+  readonly system?: string
+  readonly label?: string
+  readonly memory?: string
+  readonly file?: string
+  readonly mode?: StateMode
+  readonly judge?: string
+  readonly skills?: readonly string[]
+  readonly access?: StepAccess
+}

package/src/workflow/Diagnostic.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest"
+import {
+  compareConfigPaths,
+  dedupeDiagnostics,
+  formatDiagnostic,
+  sortDiagnostics,
+  type Diagnostic,
+} from "./Diagnostic.js"
+
+const diag = (over: Partial<Diagnostic>): Diagnostic => ({
+  severity: "error",
+  message: "boom",
+  path: [],
+  origin: "/repo/gtd.config.ts",
+  ...over,
+})
+
+describe("compareConfigPaths", () => {
+  it("orders numeric segments numerically, not lexicographically", () => {
+    expect(compareConfigPaths(["on", 2], ["on", 10])).toBeLessThan(0)
+  })
+
+  it("orders string segments lexicographically", () => {
+    expect(compareConfigPaths(["a"], ["b"])).toBeLessThan(0)
+  })
+
+  it("orders a shorter path before a longer one sharing a common prefix", () => {
+    expect(
+      compareConfigPaths(["machines", "design"], ["machines", "design", "states"]),
+    ).toBeLessThan(0)
+  })
+
+  it("is zero for identical paths", () => {
+    expect(compareConfigPaths(["machines", "design"], ["machines", "design"])).toBe(0)
+  })
+})
+
+describe("sortDiagnostics", () => {
+  it("sorts by config path", () => {
+    const a = diag({ path: ["on", 2] })
+    const b = diag({ path: ["on", 10] })
+    expect(sortDiagnostics([b, a])).toEqual([a, b])
+  })
+})
+
+describe("dedupeDiagnostics", () => {
+  it("collapses two findings identical in all four fields to one", () => {
+    const first = diag({ origin: "/repo/gtd.config.ts" })
+    const second = diag({ origin: "/repo/gtd.config.ts" })
+    expect(dedupeDiagnostics([first, second])).toEqual([first])
+  })
+
+  it("keeps two findings that differ only by path", () => {
+    const a = diag({ path: ["a"] })
+    const b = diag({ path: ["b"] })
+    expect(dedupeDiagnostics([a, b])).toEqual([a, b])
+  })
+
+  it("keeps two findings that differ only by severity", () => {
+    const a = diag({ severity: "error" })
+    const b = diag({ severity: "warning" })
+    expect(dedupeDiagnostics([a, b])).toEqual([a, b])
+  })
+})
+
+describe("formatDiagnostic", () => {
+  it("renders `<origin>: <config.path>: <message>`", () => {
+    const d = diag({
+      origin: "/repo/gtd.config.ts",
+      path: ["machines", "root", "states", "idle", "on", "* **"],
+      message: 'state "idle": "on" target "nowhere" is not a defined state',
+    })
+    expect(formatDiagnostic(d)).toBe(
+      '/repo/gtd.config.ts: machines.root.states.idle.on.* **: state "idle": "on" target "nowhere" is not a defined state',
+    )
+  })
+
+  it("renders a top-level (path-less) finding with a `(top level)` path placeholder", () => {
+    const d = diag({
+      origin: "/repo/gtd.config.ts",
+      path: [],
+      message: "unknown top-level key(s) foo",
+    })
+    expect(formatDiagnostic(d)).toBe(
+      "/repo/gtd.config.ts: (top level): unknown top-level key(s) foo",
+    )
+  })
+
+  it("joins a numeric path segment the same as a string one", () => {
+    const d = diag({ origin: "/repo/gtd.config.ts", path: ["on", 2], message: "boom" })
+    expect(formatDiagnostic(d)).toBe("/repo/gtd.config.ts: on.2: boom")
+  })
+})

package/src/workflow/Diagnostic.ts

@@ -0,0 +1,54 @@
+/**
+ * One config-compile finding. `path` mirrors the raw config's own JSON shape
+ * (e.g. `["machines","design","states","triage","on",0]`) so a user can find
+ * exactly where to fix it; `origin` is the file it came from.
+ */
+export interface Diagnostic {
+  readonly severity: "error" | "warning"
+  readonly message: string
+  readonly path: readonly (string | number)[]
+  readonly origin: string
+}
+
+const compareSegment = (a: string | number, b: string | number): number => {
+  if (typeof a === "number" && typeof b === "number") return a - b
+  if (typeof a === "number") return -1
+  if (typeof b === "number") return 1
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+/** Element-wise path comparison, numbers ordered numerically so `["on", 2]` precedes `["on", 10]`. */
+export const compareConfigPaths = (
+  a: readonly (string | number)[],
+  b: readonly (string | number)[],
+): number => {
+  const len = Math.min(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const c = compareSegment(a[i]!, b[i]!)
+    if (c !== 0) return c
+  }
+  return a.length - b.length
+}
+
+/** Sort by config path, so a report lists findings in the order of the file's shape. */
+export const sortDiagnostics = (diagnostics: readonly Diagnostic[]): Diagnostic[] =>
+  [...diagnostics].sort((a, b) => compareConfigPaths(a.path, b.path))
+
+/** One finding, printable: `<origin>: <path>: <message>` — the structured replacement for the old prose bullet list. */
+export const formatDiagnostic = (d: Diagnostic): string => {
+  const path = d.path.length > 0 ? d.path.join(".") : "(top level)"
+  return `${d.origin}: ${path}: ${d.message}`
+}
+
+/** Dedup by `(severity, path, message, origin)`, first occurrence wins. */
+export const dedupeDiagnostics = (diagnostics: readonly Diagnostic[]): Diagnostic[] => {
+  const seen = new Set<string>()
+  const out: Diagnostic[] = []
+  for (const d of diagnostics) {
+    const key = JSON.stringify([d.severity, d.path, d.message, d.origin])
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(d)
+  }
+  return out
+}

package/src/workflow/SteeringFormats.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import { isSeededValidateCommand, seededValidateCommand } from "./SteeringFormats.js"
+import { BUILT_IN_MODE_NAMES } from "../steering/index.js"
+
+describe("seededValidateCommand / isSeededValidateCommand", () => {
+  it("recognizes its own seeded command for every built-in mode", () => {
+    fc.assert(
+      fc.property(fc.constantFrom(...BUILT_IN_MODE_NAMES), (mode) => {
+        expect(isSeededValidateCommand(mode, seededValidateCommand(mode))).toBe(true)
+      }),
+    )
+  })
+
+  it("rejects a hand-written command", () => {
+    expect(isSeededValidateCommand("qa", "npx prettier --check $GTD_FILE")).toBe(false)
+  })
+
+  it("rejects another mode's seeded command", () => {
+    expect(isSeededValidateCommand("review", seededValidateCommand("qa"))).toBe(false)
+  })
+
+  it("rejects near-miss whitespace/quoting variants", () => {
+    expect(isSeededValidateCommand("qa", "gtd check qa  '$GTD_FILE'")).toBe(false)
+    expect(isSeededValidateCommand("qa", "gtd check qa $GTD_FILE")).toBe(false)
+  })
+})

package/src/workflow/SteeringFormats.ts

@@ -0,0 +1,6 @@
+/** The unrendered `validate:` template a workflow compiler seeds for a built-in mode — quoted so a path with spaces survives interpolation. */
+export const seededValidateCommand = (mode: string): string => `gtd check ${mode} "$GTD_FILE"`
+
+/** True when `command` is exactly `mode`'s seeded template (compared literally, not rendered) — distinguishes gtd's own seeding from a user override. */
+export const isSeededValidateCommand = (mode: string, command: string): boolean =>
+  command === seededValidateCommand(mode)

package/src/workflow/Workflow.ts

@@ -0,0 +1,77 @@
+import type { WorkflowBase, Flow, ScopeAccess, Summary } from "../flows/index.js"
+import type { Actor, ContentKind, StateMode, StateName, StepAccess } from "../wire/index.js"
+
+export type { Actor, ContentKind, StateMode, StateName }
+
+export type ChangeStatus = "A" | "M" | "D"
+
+export interface PendingChange {
+  readonly status: ChangeStatus
+  readonly path: string
+}
+
+/**
+ * One steering-file mode: shell commands (reading the file from `$GTD_FILE`) that
+ * format and validate a file of this format. Both run at the edge, never in
+ * the engine.
+ */
+export interface ModeDef {
+  readonly format?: string
+  readonly validate?: string
+}
+
+/**
+ * The rest a process waits at, described for the edge: who acts, its one
+ * content kind, and the steering-file options the guards and the wire read.
+ * Built from the step replay reached — never authored.
+ */
+export interface StepDef {
+  readonly actor: Actor
+  readonly kind: ContentKind
+  readonly content: string
+  readonly label?: string
+  readonly file?: string
+  readonly mode?: StateMode
+  readonly model?: string
+  readonly system?: string
+  readonly judge?: string
+  readonly requireProgress?: boolean
+  readonly answerGate?: boolean
+  readonly requireRevert?: boolean
+  readonly allowEmpty?: boolean
+  readonly acceptClean?: boolean
+  readonly skills?: readonly string[]
+  readonly access?: StepAccess
+}
+
+/**
+ * The loaded workflow module: its default export is the flow, and `summary`
+ * and `base` are the optional named exports the engine reads. Every other
+ * export is the module's own business — helpers other workflows import.
+ */
+export interface WorkflowDefinition {
+  readonly flow: Flow
+  readonly summary?: Summary | undefined
+  readonly base?: WorkflowBase | undefined
+  /** Steering files by path, with their mode — what the LSP knows before a step declaring one is reached. */
+  readonly steering: Readonly<Record<string, StateMode>>
+  /** Every mode a step may name: the built-in registry merged with `config.modes`. */
+  readonly modes: Readonly<Record<StateMode, ModeDef>>
+  /** Bundled skill lists keyed by scope full name, given the process's resolved vars — the fallback beneath `configuredSkills` and a `scope()` option. */
+  readonly skills: (
+    vars: Readonly<Record<string, string>>,
+  ) => Readonly<Record<string, readonly string[]>>
+  /** `config.skills` entries by scope full name; they outrank a `scope()` option, which outranks `skills`. Their keys are checked against `skills` once the process's settings are known. */
+  readonly configuredSkills: Readonly<Record<string, readonly string[]>>
+  /** Bundled access keyed by scope full name, given the process's resolved vars — the fallback beneath `configuredAccess` and a `scope()` option. */
+  readonly access: (vars: Readonly<Record<string, string>>) => Readonly<Record<string, ScopeAccess>>
+  /** `config.access` entries by scope full name; they outrank a `scope()` option, which outranks `access`. */
+  readonly configuredAccess: Readonly<Record<string, ScopeAccess>>
+  /** The file the `skills`, `access` and `config` exports came from, for error reports. */
+  readonly skillsOrigin: string
+  /** The flow's first step on an ordinary start — where a finished episode waits. */
+  readonly initial: StateName
+}
+
+export const knownModes = (def: Pick<WorkflowDefinition, "modes">): readonly StateMode[] =>
+  Object.keys(def.modes)

package/src/workflow/compile.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest"
+import { compileConfig } from "./compile.js"
+import { seededValidateCommand } from "./index.js"
+
+const FILE = "/repo/gtd.config.ts"
+
+describe("compileConfig", () => {
+  it("compiles no config export to the built-in modes alone", () => {
+    expect(compileConfig(undefined, FILE)).toEqual({
+      modes: {
+        qa: { validate: seededValidateCommand("qa") },
+        review: { validate: seededValidateCommand("review") },
+      },
+      skills: {},
+      access: {},
+      diagnostics: [],
+    })
+  })
+
+  it("layers a mode over a built-in one per half, and adds a new one", () => {
+    const { modes } = compileConfig(
+      { modes: { qa: { format: "fmt" }, adr: { validate: "v" } } },
+      FILE,
+    )
+    expect(modes["qa"]).toEqual({ format: "fmt", validate: seededValidateCommand("qa") })
+    expect(modes["adr"]).toEqual({ validate: "v" })
+  })
+
+  it("keeps a built-in half a mode leaves undefined", () => {
+    const { modes } = compileConfig({ modes: { qa: { format: "fmt", validate: undefined } } }, FILE)
+    expect(modes["qa"]).toEqual({ format: "fmt", validate: seededValidateCommand("qa") })
+  })
+
+  it("reports every problem at the file, under config, and compiles nothing else", () => {
+    const compiled = compileConfig({ vars: {}, skills: { a: "x" } }, FILE)
+    expect(compiled.skills).toEqual({})
+    expect(compiled.diagnostics).toEqual([
+      { severity: "error", path: ["config", "vars"], message: "is not a known key", origin: FILE },
+      {
+        severity: "error",
+        path: ["config", "skills", "a"],
+        message: "must be an array of skill names",
+        origin: FILE,
+      },
+    ])
+  })
+
+  it("keeps a __proto__ skills key as a plain entry", () => {
+    const skills = JSON.parse('{ "__proto__": ["x"], "build": ["y"] }') as Record<string, string[]>
+    const compiled = compileConfig({ skills }, FILE)
+    expect(Object.keys(compiled.skills).sort()).toEqual(["__proto__", "build"])
+  })
+})