@pmelab/gtd 13.0.0 → 14.0.0

package/src/flows/runtime.ts

@@ -0,0 +1,295 @@
+// The authoring surface of a gtd workflow. Every function here is a thin
+// facade over the replay context the engine installs on `globalThis` — keyed by
+// a registered symbol, not a module-local variable, so a copy of this file
+// loaded through a user's `gtd.config.ts` (jiti) and the copy bundled into the
+// gtd binary drive the same replay.
+
+/** A steering-file declaration shared by the steps that rest on one. */
+export interface SteeringOptions {
+  /** The steering file — a repository path under `.gtd/`. */
+  readonly file?: string | undefined
+  /** The steering file's mode — a built-in name or a `modes:` entry. Requires `file`. */
+  readonly mode?: string | undefined
+  /** Display name for drivers and viewers. */
+  readonly label?: string | undefined
+  /** The commit this step reviews changes since — what `gtd base` prints while it rests here. */
+  readonly base?: string | undefined
+}
+
+export interface AgentOptions extends SteeringOptions {
+  readonly model?: string | undefined
+  readonly system?: string | undefined
+  /**
+   * A turn that changes nothing completes the step. Without this an empty turn
+   * is an attempt: recorded, but the process stays at the step (a stall).
+   */
+  readonly allowEmpty?: boolean | undefined
+}
+
+export interface HumanOptions extends SteeringOptions {
+  readonly message?: string | undefined
+  /**
+   * A landing that changes nothing completes the gate — accepting as-is.
+   * Without this a clean landing is a no-op: the gate waits for a change.
+   */
+  readonly acceptClean?: boolean | undefined
+}
+
+export interface RunOptions extends SteeringOptions {}
+
+export type JudgePrimitive = "noul" | "choice" | "score"
+
+export interface JudgeQuestion {
+  readonly id: string
+  readonly primitive: JudgePrimitive
+  readonly instructions: string
+  readonly criteria: string
+}
+
+export interface JudgeSpec {
+  readonly questions: readonly JudgeQuestion[]
+  /** What the judge sees. The `judgeBudgetBytes` budget is split evenly across the keys; a value over its share keeps its end. */
+  readonly evidence: Readonly<Record<string, string>>
+  /** The human-facing message a driver unaware of judge gates shows. */
+  readonly message?: string | undefined
+  readonly label?: string | undefined
+}
+
+/** One recorded answer. A `noul`'s boolean reads as `"yes"`/`"no"`, a `score` as its decimal string. */
+export interface JudgeAnswer {
+  readonly answer: string
+  readonly p: number
+}
+
+export interface Judgment {
+  /** Every question's answer, `undefined` when the turn landed without a verdict for it. */
+  readonly answers: Readonly<Record<string, JudgeAnswer | undefined>>
+  /** The evidence keys the budget cut. */
+  readonly truncated: readonly string[]
+}
+
+/** One path the last step changed. */
+export interface Change {
+  readonly path: string
+  readonly status: "added" | "modified" | "deleted"
+  /** The content before the step, `undefined` when the step added the path. */
+  readonly before: string | undefined
+  /** The content the step left, `undefined` when the step deleted the path. */
+  readonly after: string | undefined
+}
+
+export interface Changes extends ReadonlyArray<Change> {
+  readonly paths: readonly string[]
+  readonly get: (path: string) => Change | undefined
+}
+
+export interface ScopeOptions {
+  /** Prefixes every step name inside, and so names their memory scope. */
+  readonly name?: string | undefined
+  /** The model every agent step inside runs with, unless it sets its own. */
+  readonly model?: string | undefined
+  /** The system prompt every agent step inside runs with, unless it sets its own. */
+  readonly system?: string | undefined
+}
+
+export type StepRequest =
+  | {
+      readonly kind: "agent"
+      readonly name: string
+      readonly prompt: string
+      readonly options: AgentOptions
+    }
+  | { readonly kind: "human"; readonly name: string; readonly options: HumanOptions }
+  | {
+      readonly kind: "run"
+      readonly name: string
+      readonly body: string
+      readonly options: RunOptions
+    }
+  | {
+      readonly kind: "judge"
+      readonly name: string
+      readonly questions: readonly JudgeQuestion[]
+      readonly evidence: Readonly<Record<string, string>>
+      readonly options: SteeringOptions & { readonly message?: string | undefined }
+    }
+  | { readonly kind: "restart" }
+
+/** The engine side of the facade — see `installContext`. */
+export interface FlowContext {
+  readonly step: (request: StepRequest) => Promise<unknown>
+  readonly refuse: (message: string) => never
+  readonly pushScope: (scope: ScopeOptions) => void
+  readonly popScope: () => void
+  readonly read: (path: string) => string | undefined
+  readonly glob: (pattern: string) => readonly string[]
+  /** The last step's changes, content read on demand. */
+  readonly changes: () => readonly Change[]
+  readonly matches: (path: string, pattern: string) => boolean
+  readonly sections: (text: string) => readonly string[]
+  readonly sectionBodies: (text: string) => readonly Section[]
+  readonly openQuestions: (text: string) => readonly OpenQuestion[]
+  readonly vars: Readonly<Record<string, string>>
+  readonly head: () => string
+  readonly start: () => string
+}
+
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+
+type ContextHolder = { [CONTEXT_KEY]?: FlowContext | undefined }
+
+/** Engine-only: install the replay context a flow run reads. */
+export const installContext = (context: FlowContext | undefined): void => {
+  ;(globalThis as ContextHolder)[CONTEXT_KEY] = context
+}
+
+const ctx = (): FlowContext => {
+  const context = (globalThis as ContextHolder)[CONTEXT_KEY]
+  if (context === undefined) {
+    throw new Error("gtd: a workflow step or helper was called outside a gtd replay")
+  }
+  return context
+}
+
+// ── Steps ───────────────────────────────────────────────────────────────────
+
+/** An agent turn: `prompt` is emitted, the driver lands the diff. */
+export const agent = (name: string, prompt: string, options: AgentOptions = {}): Promise<void> =>
+  ctx().step({ kind: "agent", name, prompt, options }) as Promise<void>
+
+/** A human gate: the process rests until a person lands a turn. */
+export const human = (name: string, options: HumanOptions = {}): Promise<void> =>
+  ctx().step({ kind: "human", name, options }) as Promise<void>
+
+/** A check: `body` runs at the edge and its effect on the tree is committed. */
+export const run = (name: string, body: string, options: RunOptions = {}): Promise<void> =>
+  ctx().step({ kind: "run", name, body, options }) as Promise<void>
+
+/** A judge gate: resolves to what the judge answered, for the flow to decide on. */
+export const judge = (name: string, spec: JudgeSpec): Promise<Judgment> => {
+  const { questions, evidence, ...options } = spec
+  return ctx().step({ kind: "judge", name, questions, evidence, options }) as Promise<Judgment>
+}
+
+/** End the episode from any depth. The next episode starts the flow afresh. */
+export const restart = (): Promise<never> => ctx().step({ kind: "restart" }) as Promise<never>
+
+/** Refuse the pending turn: nothing lands, the process stays where it rests. */
+export const refuse = (message: string): never => ctx().refuse(message)
+
+// ── Composition ─────────────────────────────────────────────────────────────
+
+/**
+ * Run `fn` inside a scope: `scope("build", fn)` prefixes every step name with
+ * `build.` (also their memory scope); an object may add the model and system
+ * prompt its agent steps run with.
+ */
+export const scope = async <T>(scope: string | ScopeOptions, fn: () => Promise<T>): Promise<T> => {
+  const context = ctx()
+  context.pushScope(typeof scope === "string" ? { name: scope } : scope)
+  try {
+    return await fn()
+  } finally {
+    context.popScope()
+  }
+}
+
+// ── Reads of the commit replay stands on ────────────────────────────────────
+
+export const read = (path: string): string | undefined => ctx().read(path)
+
+/** Every path in the tree matching `pattern` (`*` stays within a segment, `**` crosses them). */
+export const glob = (pattern: string): readonly string[] => ctx().glob(pattern)
+
+/** What the last step changed, optionally only the paths matching a glob. */
+export const changes = (pattern?: string): Changes => {
+  const context = ctx()
+  const all = context.changes()
+  const list = pattern === undefined ? all : all.filter((c) => context.matches(c.path, pattern))
+  return Object.freeze(
+    Object.assign([...list], {
+      paths: list.map((c) => c.path),
+      get: (path: string) => list.find((c) => c.path === path),
+    }),
+  )
+}
+
+/** The commit the process stands on at this point of the flow. */
+export const head = (): string => ctx().head()
+
+/** The process's diff base: the commit before it began, or the base `gtd --entry` fixed. */
+export const start = (): string => ctx().start()
+
+/** The merged workflow variables. */
+export const vars: Readonly<Record<string, string>> = new Proxy(
+  {},
+  {
+    get: (_target, key) => (typeof key === "string" ? ctx().vars[key] : undefined),
+    has: (_target, key) => typeof key === "string" && key in ctx().vars,
+    ownKeys: () => Object.keys(ctx().vars),
+    getOwnPropertyDescriptor: (_target, key) =>
+      typeof key === "string" && key in ctx().vars
+        ? { enumerable: true, configurable: true, value: ctx().vars[key] }
+        : undefined,
+  },
+)
+
+// ── Text utilities ──────────────────────────────────────────────────────────
+
+/** The top-level `## ` heading texts of markdown `text`. */
+export const sections = (text: string): readonly string[] => ctx().sections(text)
+
+export interface Section {
+  readonly title: string
+  /** The section's own markdown, its heading line included. */
+  readonly body: string
+}
+
+/** The top-level `## ` sections of markdown `text`, each with its own markdown. */
+export const sectionBodies = (text: string): readonly Section[] => ctx().sectionBodies(text)
+
+export interface OpenQuestion {
+  readonly question: string
+  /** The 1-based line of the question's heading. */
+  readonly line: number
+}
+
+/** The qa-format questions in `text` that are still unanswered. */
+export const openQuestions = (text: string): readonly OpenQuestion[] => ctx().openQuestions(text)
+
+// ── The workflow ────────────────────────────────────────────────────────────
+
+export interface FlowArgs {
+  /** The name `gtd --entry <name>` started the process with; `undefined` for an ordinary start. */
+  readonly entry: string | undefined
+}
+
+/**
+ * A workflow's one flow. A flow that never reads `entry` accepts no
+ * `--entry`; one that does decides for itself which names it honours,
+ * `refuse()`-ing the rest.
+ */
+export type Flow = (args: FlowArgs) => Promise<void>
+
+export interface SummaryContext {
+  readonly entryCommit: string
+  readonly processBase: string
+  readonly processTip: string
+  readonly humanCommits: readonly { readonly hash: string; readonly state: string }[]
+  readonly processCost: number
+  readonly processCostByModel: readonly { readonly model: string; readonly cost: number }[]
+  readonly vars: Readonly<Record<string, string>>
+}
+
+/** `gtd summary`'s prompt — a workflow module's optional `summary` export. */
+export type Summary = (context: SummaryContext) => string
+
+/**
+ * A workflow module's optional `base` export: the commitish that fixes the
+ * diff base of a process `gtd --entry <entry>` starts, or `undefined` for
+ * none. Runs when the process is entered, with the vars `--var` sets.
+ */
+export type EntryBase = (
+  entry: string,
+  vars: Readonly<Record<string, string>>,
+) => string | undefined

package/src/flows/scripts.ts

@@ -0,0 +1,116 @@
+// The shell a step hands the driver, rendered from values the flow computed.
+// Every script here is POSIX sh and runs from the repository root; none of
+// them writes to git beyond the working tree.
+
+/** POSIX single-quoting: `value` survives the shell as one word, verbatim. */
+export const quote = (value: string): string => `'${value.replace(/'/g, "'\\''")}'`
+
+export interface CheckScriptOptions {
+  /** Where a failing run's output goes, removed again by a passing one. */
+  readonly report: string
+  /** Written after the output, so a repeat of the same failure still changes the report. */
+  readonly stamp: string
+  /** Paths removed before the command runs. */
+  readonly sweep?: readonly string[] | undefined
+  /** Paths removed once it passes. */
+  readonly sweepOnGreen?: readonly string[] | undefined
+}
+
+const removal = (paths: readonly string[]): string[] =>
+  paths.length === 0 ? [] : [`rm -rf -- ${paths.map(quote).join(" ")}`]
+
+/**
+ * Run `command` and keep its outcome in the tree: on failure its output (or
+ * a note that there was none) lands in `report`, on success `report` goes.
+ */
+export const checkScript = (command: string, options: CheckScriptOptions): string => {
+  const report = quote(options.report)
+  const output = quote(`${options.report}.output`)
+  return [
+    "#!/usr/bin/env sh",
+    "set +e",
+    ...removal(options.sweep ?? []),
+    `mkdir -p "$(dirname ${report})"`,
+    // A subshell, so an `exit` inside the command ends only the command.
+    "(",
+    command,
+    `) > ${output} 2>&1`,
+    "code=$?",
+    'if [ "$code" -ne 0 ]; then',
+    `  if [ -s ${output} ]; then`,
+    `    mv ${output} ${report}`,
+    "  else",
+    `    rm -f ${output}`,
+    `    printf 'the test command failed with exit code %s and produced no output.' "$code" > ${report}`,
+    "  fi",
+    `  printf '\\n<!-- gtd check %s -->\\n' ${quote(options.stamp)} >> ${report}`,
+    "else",
+    `  rm -f ${output} ${report}`,
+    ...removal(options.sweepOnGreen ?? []).map((line) => `  ${line}`),
+    "fi",
+    "",
+  ].join("\n")
+}
+
+/**
+ * Reverse-apply `commit`'s changes to the working tree. A failure — the
+ * patch no longer applies — writes `failure` and git's error to `report`,
+ * since a failed revert and one with nothing to undo both leave the tree clean.
+ */
+export const revertScript = (commit: string, report: string, failure: string): string => {
+  const range = `${quote(`${commit}^`)} ${quote(commit)}`
+  const error = quote(`${report}.output`)
+  return [
+    "#!/usr/bin/env sh",
+    "set +e",
+    `if ! git diff --quiet ${range} --; then`,
+    `  mkdir -p "$(dirname ${quote(report)})"`,
+    `  git diff --binary ${range} -- | git apply -R 2> ${error}`,
+    "  code=$?",
+    '  if [ "$code" -ne 0 ]; then',
+    "    {",
+    `      printf '%s\\n\\n' ${quote(failure)}`,
+    `      if [ -s ${error} ]; then cat ${error}; else printf 'Reverting it exited %s and produced no output.\\n' "$code"; fi`,
+    `    } > ${quote(report)}`,
+    "  fi",
+    `  rm -f ${error}`,
+    "fi",
+    "",
+  ].join("\n")
+}
+
+/**
+ * Undo the edits one commit made to `paths`: each goes back to its content
+ * before `commit` — or away, when `commit` added it — but only while it is
+ * still exactly as `commit` left it. A path changed since is left alone.
+ */
+export const restoreScript = (
+  commit: string,
+  paths: { readonly restore: readonly string[]; readonly remove: readonly string[] },
+): string => {
+  const unchanged = (path: string): string => `git diff --quiet ${quote(commit)} -- ${quote(path)}`
+  return [
+    "#!/usr/bin/env sh",
+    "set +e",
+    ...paths.restore.map(
+      (path) =>
+        `${unchanged(path)} && git restore --source=${quote(`${commit}~1`)} --worktree -- ${quote(path)}`,
+    ),
+    ...paths.remove.map((path) => `${unchanged(path)} && rm -f -- ${quote(path)}`),
+    "",
+  ].join("\n")
+}
+
+/** Remove `paths` from the working tree; absent ones are fine. */
+export const removeScript = (paths: readonly string[]): string =>
+  ["#!/usr/bin/env sh", ...removal(paths), ""].join("\n")
+
+/** Move `from` to `to`, creating `to`'s directory. */
+export const moveScript = (from: string, to: string): string =>
+  [
+    "#!/usr/bin/env sh",
+    "set -e",
+    `mkdir -p "$(dirname ${quote(to)})"`,
+    `mv -- ${quote(from)} ${quote(to)}`,
+    "",
+  ].join("\n")

package/src/workflows/health.ts

@@ -0,0 +1,126 @@
+import {
+  answered,
+  check,
+  human,
+  judge,
+  numeric,
+  read,
+  scope,
+  vars,
+  type JudgeQuestion,
+} from "../flows/index.js"
+import { describeEscalation, escalate, escalationExhausted, ESCALATION, FEEDBACK } from "./steps.js"
+import * as t from "./text.js"
+
+/** Fix turns a run of red checks gets before it escalates. */
+export const FIX_CAP = 3
+
+/** Run the suite as step `name`; resolves `true` when it passed. A failure is in `.gtd/FEEDBACK.md`. */
+export const baseline = (name: string, label = "Checking the baseline"): Promise<boolean> =>
+  check(name, vars.testCommand ?? "", { report: FEEDBACK, label })
+
+/** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
+export interface EscalationCount {
+  rounds: number
+}
+
+/**
+ * Hand a red suite that repeated attempts could not fix to a person: an
+ * agent writes `.gtd/ESCALATION.md`, a human narrows it. From the third round
+ * on, the human is told the budget is spent instead.
+ */
+export const escalation = async (count: EscalationCount): Promise<void> => {
+  if (count.rounds >= 2) return escalationExhausted()
+  count.rounds++
+  await describeEscalation()
+  await escalate()
+}
+
+const STAMP = /\n<!-- gtd check [0-9a-f]+ -->\n?$/
+const stripStamp = (text: string): string => text.replace(STAMP, "\n")
+
+/** "Is this red round the same failure as the last one?" — asked of two reports, or of nothing when one is empty. */
+const retryQuestion = (comparable: boolean): JudgeQuestion =>
+  comparable
+    ? {
+        id: "verdict",
+        primitive: "choice",
+        instructions:
+          "Compare this round's failing check output (current) against the previous round's (previous), both in state. Classify the change.",
+        criteria:
+          "identical: the same failure restated, byte-for-byte or the same root cause — the trailing `<!-- gtd check <sha> -->` stamp is already stripped from both, but ignore it too if it ever reappears. new-failure: a materially different symptom than previous. progress: still red, but measurably closer to green (fewer failures, a later stage reached).",
+      }
+    : {
+        id: "verdict",
+        primitive: "choice",
+        instructions:
+          "state carries tailsNotComparable: one of the two check reports came back empty. There is nothing to compare here; answer from criteria alone.",
+        criteria:
+          "identical is FORBIDDEN here — answer new-failure or progress instead, defaulting to progress if genuinely unsure.",
+      }
+
+const sameFailure = async (previous: string, current: string): Promise<boolean> => {
+  const comparable = current.trim() !== "" && previous.trim() !== ""
+  const { answers, truncated } = await judge("health.judge", {
+    questions: [retryQuestion(comparable)],
+    evidence: comparable ? { current, previous } : { tailsNotComparable: "true" },
+    message: t.healthJudgeMessage(),
+    label: "Judging the retry",
+  })
+  // Evidence the budget cut can make two different reports look alike: never sameness.
+  return (
+    comparable &&
+    truncated.length === 0 &&
+    answered(answers.verdict, "identical", numeric(vars.judgeIdenticalMinP, Infinity))
+  )
+}
+
+export interface HealthOptions {
+  /** Fix turns already spent before this call. */
+  readonly fixesSoFar?: number
+  /** Escalation rounds shared with other callers in the same run of red checks. */
+  readonly escalations?: EscalationCount
+}
+
+/**
+ * Loop until the suite is green: check, and on red run `fix` — escalating
+ * first once `FIX_CAP` fixes are spent, or a judge calls the failure
+ * identical to the previous round's.
+ */
+export const healthy = async (
+  fix: () => Promise<void>,
+  options: HealthOptions = {},
+): Promise<void> => {
+  const escalations = options.escalations ?? { rounds: 0 }
+  let fixes = options.fixesSoFar ?? 0
+  let previous: string | undefined
+  for (;;) {
+    const green = await check("health.check", vars.testCommand ?? "", {
+      report: FEEDBACK,
+      label: "Running checks",
+      // Swept only on green: an unresolved analysis survives every retry.
+      sweepOnGreen: [ESCALATION],
+    })
+    if (green) {
+      escalations.rounds = 0
+      return
+    }
+    const current = stripStamp(read(FEEDBACK) ?? "")
+    const stuck = previous !== undefined && (await sameFailure(previous, current))
+    previous = current
+    if (stuck || fixes >= FIX_CAP) {
+      await escalation(escalations)
+      fixes = 0
+    }
+    fixes++
+    await fix()
+  }
+}
+
+/** Hold the process at `<name>.blocked` until the suite is green. */
+export const gate = (name: string, message: string): Promise<void> =>
+  scope(name, async () => {
+    while (!(await baseline("check"))) {
+      await human("blocked", { message, label: "Baseline is red", file: FEEDBACK })
+    }
+  })

package/src/workflows/index.ts

@@ -0,0 +1 @@
+export * as unified from "./unified.js"

package/src/workflows/packages.ts

@@ -0,0 +1,93 @@
+import {
+  answered,
+  changes,
+  glob,
+  judge,
+  numeric,
+  read,
+  refuse,
+  removeScript,
+  run,
+  scope,
+  sectionBodies,
+  start,
+  vars,
+  wrote,
+  type JudgeQuestion,
+} from "../flows/index.js"
+import { healthy } from "./health.js"
+import { ARCHITECTURE, build, fixSpec, fixSuite, reviewPackage, SPEC_FEEDBACK } from "./steps.js"
+import * as t from "./text.js"
+
+const MAX_SECTIONS = 8
+
+const sectionQuestion = (id: string, title: string): JudgeQuestion => ({
+  id,
+  primitive: "noul",
+  instructions: `Is the requirement "${title}" already fully satisfied by the code on the range from ${start()} to the working tree?`,
+  criteria:
+    "Judge from the package markdown plus that range, read yourself. Only answer yes at a probability clearing the threshold below if genuinely confident nothing in this section is missing.",
+})
+
+/**
+ * Review one freshly built package against its spec: a pre-judge per
+ * section, then an agent review of the sections it did not confidently
+ * clear. Resolves `true` when approved.
+ */
+export const specReview = async (pkg: string): Promise<boolean> => {
+  const found = sectionBodies(read(pkg) ?? "")
+  const titles = found.map((section) => section.title)
+  const judged = titles.length > 0 && titles.length <= MAX_SECTIONS
+  const evidence: Record<string, string> = {}
+  const questions: JudgeQuestion[] = []
+  if (judged) {
+    found.forEach(({ title, body }, i) => {
+      evidence[`section-${i + 1}`] = body
+      questions.push(sectionQuestion(`section-${i + 1}`, title))
+    })
+  }
+  const { answers, truncated } = await judge("spec.pre", {
+    questions,
+    evidence,
+    message: t.packagesItemSpecPreMessage(),
+    label: "Judging spec coverage",
+  })
+  // A section is cleared only by a confident yes on evidence that was not cut.
+  const clearMinP = numeric(vars.specPreJudge, Infinity)
+  const failing = titles.filter((_, i) => {
+    const id = `section-${i + 1}`
+    return !judged || truncated.includes(id) || !answered(answers[id], "yes", clearMinP)
+  })
+  if (titles.length > 0 && failing.length === 0) return true
+  await reviewPackage(pkg, failing)
+  if (wrote(SPEC_FEEDBACK)) return false
+  if (changes(SPEC_FEEDBACK).length > 0 || changes().length === 0) return true
+  return refuse(
+    "gtd land: no declared pattern matches the pending changes — write .gtd/SPEC_FEEDBACK.md to request changes, or change nothing to approve",
+  )
+}
+
+/** Build `pkg`, keep the suite green, review it against its spec, and close it out, which removes it. */
+export const packageItem = async (pkg: string): Promise<void> => {
+  await build(pkg)
+  for (;;) {
+    await healthy(fixSuite)
+    if (await specReview(pkg)) break
+    await fixSpec(pkg)
+  }
+  // The spent technical plan goes with the first package built from it.
+  await run("closing", removeScript([pkg, SPEC_FEEDBACK, ".gtd/SATISFIED.md", ARCHITECTURE]), {
+    label: "Closing out the package",
+  })
+}
+
+/** The first queued package — the one a package step works on. */
+export const nextPackage = (): string | undefined => [...glob(".gtd/packages/*.md")].sort()[0]
+
+/** Build every package file under `.gtd/packages/`, in name order. */
+export const packages = (): Promise<void> =>
+  scope("packages", async () => {
+    for (let pkg = nextPackage(); pkg !== undefined; pkg = nextPackage()) {
+      await scope("item", () => packageItem(pkg))
+    }
+  })