@pmelab/gtd 24.0.0 → 24.2.0

package/claude/hooks/tools.ts

@@ -0,0 +1,121 @@
+// The only way the main session's model moves gtd: tools the mod serves. Each
+// checks the run before it acts, so a model cannot skip a rest or answer one
+// gtd has already left.
+
+import type { Run } from "../types"
+import { humanVerdicts } from "./judge"
+import type { Judgment } from "./judge"
+
+export const TOOL = {
+  continue: "mcp__gtd__continue",
+  note: "mcp__gtd__note",
+  handoff: "mcp__gtd__handoff",
+  ship: "mcp__gtd__ship",
+  browser: "mcp__gtd__browser",
+} as const
+
+export const TOOLS = [
+  {
+    name: "continue",
+    description:
+      "Moves the gtd process on from the step it waits at. Call it ONLY after the person explicitly said to continue. `rest` is the rest id gtd gave you for this step. `verdicts` only at a step gtd's judge could not decide: each question id mapped to the person's chosen answer. Refused when gtd has moved on, while a step runs, or when the step's file does not validate; the result says why.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        rest: { type: "string" },
+        verdicts: { type: "object", additionalProperties: { type: ["string", "number"] } },
+      },
+      required: ["rest"],
+    },
+  },
+  {
+    name: "note",
+    description:
+      "Records a request the person makes while gtd runs a step (a change, something to consider), for the next step that waits on them. Use it instead of editing files while gtd runs.",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+    },
+  },
+  {
+    name: "handoff",
+    description:
+      "Hands the gtd process to someone else: pushes the branch and opens or refreshes a draft pull request assigned to them. Call it only when the person asks. `to`: their GitHub username; omit it to leave the process for anyone.",
+    inputSchema: { type: "object", properties: { to: { type: "string" } } },
+  },
+  {
+    name: "ship",
+    description:
+      "Combines the finished gtd process into one commit, pushes it and opens or updates its pull request. Call it only after the person agreed. `dryRun` previews without writing anything.",
+    inputSchema: { type: "object", properties: { dryRun: { type: "boolean" } } },
+  },
+  {
+    name: "browser",
+    description:
+      "Starts gtd's browser view of the step it waits at and returns its address. Call it only when the person wants it.",
+    inputSchema: { type: "object", properties: {} },
+  },
+]
+
+// A rest is the state gtd waits at on a given HEAD: once either moves, an
+// answer meant for it no longer applies. Survives a mod reload, unlike a counter.
+export const restId = (head: string, state: string | undefined) =>
+  `${head.slice(0, 12)}:${state ?? "?"}`
+
+export type Proceed = { refuse: string } | { refuse?: undefined; verdict?: string }
+
+export type ContinueIo = {
+  // the rest gtd is at now; undefined when it cannot say
+  current(): Promise<string | undefined>
+  // the rest's own `gtd validate` script, run; ok when there is nothing to check
+  validate(): Promise<{ ok: boolean; out: string }>
+  judgment(): Promise<Judgment | undefined>
+}
+
+// What `continue` may do from here. `rest` undefined is the band's Continue,
+// which always means the rest on screen.
+export async function decideContinue(
+  run: Run,
+  rest: string | undefined,
+  verdicts: unknown,
+  io: ContinueIo,
+): Promise<Proceed> {
+  if (run.isRunning) return { refuse: "gtd is already running a step." }
+  const stop = run.stop
+  if (!stop) return { refuse: "Nothing is waiting: gtd has no rest open. /gtd drives it." }
+  if (stop.kind === "done") {
+    return { refuse: `The process is finished: ${TOOL.ship} opens its pull request.` }
+  }
+  if (rest !== undefined && rest !== run.rest) {
+    return {
+      refuse: "gtd has moved on from that step; it no longer waits there. Nothing was changed.",
+    }
+  }
+  // Another terminal or a branch switch can move gtd under a waiting answer.
+  const now = await io.current()
+  if (now !== undefined && now !== run.rest) {
+    return {
+      refuse:
+        "gtd is no longer at that step (it changed outside this session): /gtd shows where it is.",
+    }
+  }
+  if (stop.kind === "gate" && stop.isJudge) return judged(verdicts, io)
+  if (verdicts !== undefined) return { refuse: "This step takes no verdicts." }
+  if (stop.kind === "gate") {
+    const v = await io.validate()
+    if (!v.ok) return { refuse: `The step's file does not validate yet:\n${v.out}` }
+  }
+  return {}
+}
+
+// No verdicts lands the gate untouched: the cautious default.
+async function judged(verdicts: unknown, io: ContinueIo): Promise<Proceed> {
+  if (verdicts === undefined) return {}
+  const j = await io.judgment()
+  if (!j) return { refuse: "gtd no longer has a judgment open here." }
+  const v = humanVerdicts(j, verdicts)
+  return typeof v === "string"
+    ? { refuse: `Those verdicts don't fit: ${v}` }
+    : { verdict: JSON.stringify(v) }
+}

package/claude/hooks/wording.ts

@@ -1,46 +1,13 @@
-// Everything the mod says to a person. Plain words: no gtd state ids, no tool
-// names, and options that say what choosing them does.
+// Everything the mod itself shows a person. Plain words: no gtd state ids.
 
-import type { Run, Stop } from "../types"
+import type { Stop } from "../types"
 import type { Beat } from "./drive"
 
-export const CONTINUE = "I'm done, continue"
-export const SAFE = "Continue with the safe choice"
-export const HANDOFF = "Hand off to someone else"
-export const LATER = "Not now"
-export const SHIP = "Yes, open the pull request"
-export const ANYONE = "Anyone on the team"
-export const CANCEL = "Cancel"
-export const CLOSE = "Close"
-
-export const gateOptions = (stop: Stop) => [stop.isJudge ? SAFE : CONTINUE, HANDOFF, LATER]
-
 const step = (s: { label?: string; state?: string }) => s.label ?? s.state ?? "the next step"
 
-export function question(r: Run) {
-  const stop = r.stop as Stop
-  if (stop.isJudge) {
-    return `gtd can't decide this step on its own: ${step(stop)}. Continue with the safe choice, or hand it to someone who can decide?`
-  }
-  const how = r.url
-    ? `Open it in your browser: ${r.url}`
-    : `Make your changes in ${stop.file ?? "the files it names"}.`
-  const again = r.isRepeat ? "You haven't changed anything yet, so gtd is still waiting. " : ""
-  return `${again}gtd needs your input: ${step(stop)}. ${how} Ready to continue?`
-}
-
-export const STALE =
-  "This question is out of date: gtd has already moved on. Choose Close to dismiss it."
-
 export const RELOAD_CUT_SCRIPT =
   "a reload cut a script off mid-run — check the working tree, then Continue to run it again"
 
-export const handoffQuestion =
-  "Who should take over from here? Type their GitHub username, or let anyone on the team pick it up."
-
-export const shipQuestion = (branch: string) =>
-  `gtd has finished the work on ${branch}. Combine it into a single commit and open (or update) its pull request for review?`
-
 export function headline(s: Stop) {
   const where = step(s)
   switch (s.kind) {

package/claude/types/index.d.ts

@@ -6,6 +6,8 @@ export type Stop = {
   isJudge?: boolean
   // the steering file the rest asks a person to edit
   file?: string
+  // the steering file's mode (`qa`, `review`), which bounds what may be written at the rest
+  mode?: string
 }
 
 export type Run = {
@@ -14,6 +16,13 @@ export type Run = {
   state?: string
   label?: string
   stop?: Stop
+  // the rest a person is helped at: HEAD and state, so an answer to an older one is refused
+  rest?: string
+  // a continue the model asked for, started once its turn ends (and only if
+  // gtd still rests at `rest`); kept here so a reload does not lose a verdict
+  pending?: { rest: string; isAnswered?: boolean; verdict?: string | undefined }
+  // requests a person made while a step ran, for the next rest's assistant
+  notes?: string[]
   // `gtd ui`'s address while it serves the current rest
   url?: string
   // why `gtd ui` is not serving it (refused, crashed)