@pmelab/gtd 24.1.0 → 24.3.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)

package/dist/chunks/{Schema-Dh-mkwkq.mjs → Schema-B5yK7QrT.mjs}

@@ -12242,6 +12242,7 @@ const mapErrorCause = /*#__PURE__*/ dual(2, (self, f) => matchCauseEffect$2(self
 	onSuccess: succeed$5
 }));
 const negate$1 = (self) => map$5(self, (b) => !b);
+const orElseSucceed$1 = /*#__PURE__*/ dual(2, (self, evaluate) => orElse$2(self, () => sync$1(evaluate)));
 const patchFiberRefs = (patch) => updateFiberRefs((fiberId, fiberRefs) => pipe(patch, patch$2(fiberId, fiberRefs)));
 const promise$1 = (evaluate) => evaluate.length >= 1 ? async_((resolve, signal) => {
 	try {
@@ -21189,6 +21190,51 @@ const orDie = orDie$1;
 */
 const orElse$1 = orElse$2;
 /**
+* Ensures the effect always succeeds by replacing failures with a default
+* success value.
+*
+* **Details**
+*
+* This function transforms an effect that may fail into one that cannot fail by
+* replacing any failure with a provided success value. If the original effect
+* fails, the failure is "swallowed," and the specified success value is
+* returned instead. If the original effect succeeds, its value remains
+* unchanged.
+*
+* **When to Use**
+*
+* This is especially useful for providing default values in case of failure,
+* ensuring that an effect always completes successfully. By using this
+* function, you can avoid the need for complex error handling and guarantee a
+* fallback result.
+*
+* **Example**
+*
+* ```ts
+* import { Effect } from "effect"
+*
+* const validate = (age: number): Effect.Effect<number, string> => {
+*   if (age < 0) {
+*     return Effect.fail("NegativeAgeError")
+*   } else if (age < 18) {
+*     return Effect.fail("IllegalAgeError")
+*   } else {
+*     return Effect.succeed(age)
+*   }
+* }
+*
+* const program = Effect.orElseSucceed(validate(-1), () => 18)
+*
+* console.log(Effect.runSyncExit(program))
+* // Output:
+* // { _id: 'Exit', _tag: 'Success', value: 18 }
+* ```
+*
+* @since 2.0.0
+* @category Fallback
+*/
+const orElseSucceed = orElseSucceed$1;
+/**
 * Returns an effect that accesses the runtime, which can be used to (unsafely)
 * execute tasks.
 *
@@ -25350,4 +25396,4 @@ Struct({
 	description: "Represents an issue returned by the ArrayFormatter formatter"
 });
 //#endregion
-export { makeSemaphore as $, equals$2 as $i, match$3 as $n, get$4 as $r, scoped$1 as $t, catchTag as A, omit$1 as Ai, _await as An, interruptAsFiber as Ar, tap as At, flatten as B, map$11 as Bi, modify as Bn, uninterruptible$1 as Br, when as Bt, all as C, unsafeGet as Ci, map$3 as Cn, exitSucceed$1 as Cr, scopeWith as Ct, async as D, add$2 as Di, forEachConcurrentDiscard as Dn, fiberRefLocally as Dr, succeed$1 as Dt, asVoid as E, Tag as Ei, ensuring$1 as En, fiberId as Er, serviceOption as Et, exit as F, flatMap$6 as Fi, bind as Fn, scopeClose as Fr, try_ as Ft, forkScoped as G, left as Gi, spanTag as Gn, zipRight$2 as Gr, zipWith as Gt, forEach as H, none$4 as Hi, update$1 as Hn, void_$2 as Hr, zip as Ht, fail$1 as I, fromNullable as Ii, bindTo as In, succeed$5 as Ir, uninterruptible as It, interrupt as J, pipeArguments as Ji, fail$4 as Jn, combine$5 as Jr, tagged as Jt, gen as K, match$7 as Ki, all$2 as Kn, DeferredTypeId as Kr, spaced as Kt, failCause as L, getOrElse as Li, sleep as Ln, suspend$3 as Lr, uninterruptibleMask as Lt, dieMessage as M, fromIterable$6 as Mi, interruptAllAs as Mn, interruptible$2 as Mr, timeout as Mt, either as N, splitAt as Ni, join as Nn, map$5 as Nr, tryMap as Nt, catchAll as O, get$7 as Oi, scopeMake as On, flatMap$3 as Or, suspend$1 as Ot, ensuring as P, filter$3 as Pi, sequential$1 as Pn, onInterrupt as Pr, tryPromise as Pt, logWarning as Q, toJSON as Qi, mapBoth$2 as Qn, none$2 as Qr, provideMerge as Qt, fiberIdWith as R, isNone as Ri, get as Rn, sync$1 as Rr, unsafeMakeLatch as Rt, addFinalizer as S, unsafeFromArray as Si, isInterruptedOnly as Sn, exitFailCause$1 as Sr, scope as St, as as T, GenericTag as Ti, squash as Tn, exitZipRight as Tr, scopedWith as Tt, forkDaemon as U, some as Ui, TypeId$4 as Un, whenEffect as Ur, zipLeft as Ut, fnUntraced as V, match$6 as Vi, set as Vn, uninterruptibleMask$2 as Vr, withFiberRuntime as Vt, forkIn as W, isLeft as Wi, Class as Wn, withFiberRuntime$1 as Wr, zipRight as Wt, intoDeferred as X, NodeInspectSymbol as Xi, isFailure as Xn, ids as Xr, mergeAll as Xt, interruptible as Y, BaseProto as Yi, failCause$2 as Yn, combineAll as Yr, fromEffect as Yt, isEffect as Z, format$4 as Zi, map$4 as Zn, make$20 as Zr, provide$1 as Zt, decodeSync as _, reduce$6 as _i, flipCauseOption as _n, deferredSucceed as _r, retry as _t, Literal as a, dual as aa, isFinite as ai, unsafeMakeSemaphore$1 as an, asVoid$1 as ar, matchCauseEffect as at, acquireRelease as b, takeRight as bi, isDieType as bn, exitAs as br, runtime as bt, String$ as c, drop as ci, addFinalizerExit as cn, currentContext as cr, onError as ct, Union as d, fromIterable$5 as di, fork as dn, deferredFail as dr, promise as dt, hasProperty as ea, make$22 as ei, succeed$2 as en, succeed$4 as er, map$1 as et, between as f, isChunk as fi, make$2 as fn, deferredFailCause as fr, provide as ft, standardSchemaV1 as g, prepend$1 as gi, failureOrCause as gn, deferredMake as gr, repeat as gt, optionalWith as h, of$1 as hi, fail$2 as hn, deferredIsDone as hr, raceWith as ht, Defect as i, constVoid as ia, decode as ii, forkIn$1 as in, as$1 as ir, matchCause as it, die as j, empty$22 as ji, inheritAll as jn, interruptFiber as jr, tapErrorCause as jt, catchAllCause as k, getOption as ki, scopeTag as kn, interrupt$2 as kr, sync as kt, Struct as l, empty$19 as li, close as ln, deferredAwait as lr, orDie as lt, optional as m, map$9 as mi, die$1 as mn, deferredInterruptWith as mr, race as mt, Boolean$ as n, constTrue as na, has$1 as ni, unsafeRunPromiseExit as nn, zip$1 as nr, mapError$1 as nt, Never as o, identity as oa, append as oi, Scope as on, asyncInterrupt as or, matchEffect as ot, decodeUnknown as p, isEmpty$5 as pi, NoSuchElementException as pn, deferredInterrupt as pr, provideService as pt, ignore as q, right as qi, die$2 as qn, empty$15 as qr, TaggedError$1 as qt, Cause as r, constUndefined as ra, size$2 as ri, updateContext as rn, zipRight$1 as rr, match as rt, Number$ as s, pipe as sa, appendAll$1 as si, addFinalizer$1 as sn, catchAll$1 as sr, negate as st, Array$ as t, constFalse as ta, set$3 as ti, unsafeFork as tn, void_$1 as tr, mapBoth$1 as tt, TaggedError as u, filter$1 as ui, extend$1 as un, deferredComplete as ur, orElse$1 as ut, encodeSync as v, reverse$1 as vi, interrupt$1 as vn, deferredUnsafeDone as vr, runPromise as vt, annotateLogs as w, unsafeHead as wi, reduceWithContext as wn, exitVoid$1 as wr, scoped as wt, acquireUseRelease as x, toArray$1 as xi, isInterrupted as xn, exitFail as xr, sandbox as xt, _void as y, take as yi, interruptors as yn, deferredUnsafeMake as yr, runPromiseExit as yt, flatMap$1 as z, isSome as zi, make$12 as zn, tap$1 as zr, unsafeMakeSemaphore as zt };
+export { makeSemaphore as $, toJSON as $i, mapBoth$2 as $n, none$2 as $r, provideMerge as $t, catchTag as A, getOption as Ai, scopeTag as An, interrupt$2 as Ar, sync as At, flatten as B, isSome as Bi, make$12 as Bn, tap$1 as Br, unsafeMakeSemaphore as Bt, all as C, unsafeFromArray as Ci, isInterruptedOnly as Cn, exitFailCause$1 as Cr, scope as Ct, async as D, Tag as Di, ensuring$1 as Dn, fiberId as Dr, serviceOption as Dt, asVoid as E, GenericTag as Ei, squash as En, exitZipRight as Er, scopedWith as Et, exit as F, filter$3 as Fi, sequential$1 as Fn, onInterrupt as Fr, tryPromise as Ft, forkScoped as G, isLeft as Gi, Class as Gn, withFiberRuntime$1 as Gr, zipRight as Gt, forEach as H, match$6 as Hi, set as Hn, uninterruptibleMask$2 as Hr, withFiberRuntime as Ht, fail$1 as I, flatMap$6 as Ii, bind as In, scopeClose as Ir, try_ as It, interrupt as J, right as Ji, die$2 as Jn, empty$15 as Jr, TaggedError$1 as Jt, gen as K, left as Ki, spanTag as Kn, zipRight$2 as Kr, zipWith as Kt, failCause as L, fromNullable as Li, bindTo as Ln, succeed$5 as Lr, uninterruptible as Lt, dieMessage as M, empty$22 as Mi, inheritAll as Mn, interruptFiber as Mr, tapErrorCause as Mt, either as N, fromIterable$6 as Ni, interruptAllAs as Nn, interruptible$2 as Nr, timeout as Nt, catchAll as O, add$2 as Oi, forEachConcurrentDiscard as On, fiberRefLocally as Or, succeed$1 as Ot, ensuring as P, splitAt as Pi, join as Pn, map$5 as Pr, tryMap as Pt, logWarning as Q, format$4 as Qi, map$4 as Qn, make$20 as Qr, provide$1 as Qt, fiberIdWith as R, getOrElse as Ri, sleep as Rn, suspend$3 as Rr, uninterruptibleMask as Rt, addFinalizer as S, toArray$1 as Si, isInterrupted as Sn, exitFail as Sr, sandbox as St, as as T, unsafeHead as Ti, reduceWithContext as Tn, exitVoid$1 as Tr, scoped as Tt, forkDaemon as U, none$4 as Ui, update$1 as Un, void_$2 as Ur, zip as Ut, fnUntraced as V, map$11 as Vi, modify as Vn, uninterruptible$1 as Vr, when as Vt, forkIn as W, some as Wi, TypeId$4 as Wn, whenEffect as Wr, zipLeft as Wt, intoDeferred as X, BaseProto as Xi, failCause$2 as Xn, combineAll as Xr, fromEffect as Xt, interruptible as Y, pipeArguments as Yi, fail$4 as Yn, combine$5 as Yr, tagged as Yt, isEffect as Z, NodeInspectSymbol as Zi, isFailure as Zn, ids as Zr, mergeAll as Zt, decodeSync as _, prepend$1 as _i, failureOrCause as _n, deferredMake as _r, repeat as _t, Literal as a, constVoid as aa, decode as ai, forkIn$1 as an, as$1 as ar, matchCauseEffect as at, acquireRelease as b, take as bi, interruptors as bn, deferredUnsafeMake as br, runPromiseExit as bt, String$ as c, pipe as ca, appendAll$1 as ci, addFinalizer$1 as cn, catchAll$1 as cr, onError as ct, Union as d, filter$1 as di, extend$1 as dn, deferredComplete as dr, orElseSucceed as dt, equals$2 as ea, get$4 as ei, scoped$1 as en, match$3 as er, map$1 as et, between as f, fromIterable$5 as fi, fork as fn, deferredFail as fr, promise as ft, standardSchemaV1 as g, of$1 as gi, fail$2 as gn, deferredIsDone as gr, raceWith as gt, optionalWith as h, map$9 as hi, die$1 as hn, deferredInterruptWith as hr, race as ht, Defect as i, constUndefined as ia, size$2 as ii, updateContext as in, zipRight$1 as ir, matchCause as it, die as j, omit$1 as ji, _await as jn, interruptAsFiber as jr, tap as jt, catchAllCause as k, get$7 as ki, scopeMake as kn, flatMap$3 as kr, suspend$1 as kt, Struct as l, drop as li, addFinalizerExit as ln, currentContext as lr, orDie as lt, optional as m, isEmpty$5 as mi, NoSuchElementException as mn, deferredInterrupt as mr, provideService as mt, Boolean$ as n, constFalse as na, set$3 as ni, unsafeFork as nn, void_$1 as nr, mapError$1 as nt, Never as o, dual as oa, isFinite as oi, unsafeMakeSemaphore$1 as on, asVoid$1 as or, matchEffect as ot, decodeUnknown as p, isChunk as pi, make$2 as pn, deferredFailCause as pr, provide as pt, ignore as q, match$7 as qi, all$2 as qn, DeferredTypeId as qr, spaced as qt, Cause as r, constTrue as ra, has$1 as ri, unsafeRunPromiseExit as rn, zip$1 as rr, match as rt, Number$ as s, identity as sa, append as si, Scope as sn, asyncInterrupt as sr, negate as st, Array$ as t, hasProperty as ta, make$22 as ti, succeed$2 as tn, succeed$4 as tr, mapBoth$1 as tt, TaggedError as u, empty$19 as ui, close as un, deferredAwait as ur, orElse$1 as ut, encodeSync as v, reduce$6 as vi, flipCauseOption as vn, deferredSucceed as vr, retry as vt, annotateLogs as w, unsafeGet as wi, map$3 as wn, exitSucceed$1 as wr, scopeWith as wt, acquireUseRelease as x, takeRight as xi, isDieType as xn, exitAs as xr, runtime as xt, _void as y, reverse$1 as yi, interrupt$1 as yn, deferredUnsafeDone as yr, runPromise as yt, flatMap$1 as z, isNone as zi, get as zn, sync$1 as zr, unsafeMakeLatch as zt };

package/dist/chunks/{reserved-ejn-LVYO.mjs → reserved-DJwU5C4z.mjs}

@@ -1,6 +1,6 @@
 import { accessFor, agent, answered, check, codeThreads, defineWorkflow, env, head, human, judge, numeric, quote, read, refuse, removeScript, run, scope, skillsFor, start, vars } from "../flows.mjs";
 import { escalation as escalation$1, fixFindings, gate as gate$1, healthy as healthy$1, holdWording as holdWording$1, lensScopes, lensesOf, qualityLap as qualityLap$1, reviewToHandOff, untilSettled } from "../workflow-kit.mjs";
-import { c as String$, g as standardSchemaV1, h as optionalWith, l as Struct } from "./Schema-Dh-mkwkq.mjs";
+import { c as String$, g as standardSchemaV1, h as optionalWith, l as Struct } from "./Schema-B5yK7QrT.mjs";
 import { dirname } from "node:path";
 //#region src/workflows/shared/prose.ts
 const skillsPreamble = `- Load whatever's listed here that your harness actually has installed,