@pmelab/gtd 21.0.0 → 21.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "21.0.0",
+  "version": "21.1.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -414,20 +414,22 @@ noted in steps 3 and 4 below.
    users only; model `haiku`, `--model <name>` overrides) and reuses its login.
    With no `--provider`, `gtd judge run` picks jev when `TYPESAFE_API_KEY` is
    set and non-empty and no `--model` is given, else llm — never falling back
-   across them; a `.gtdrc` `judge: { provider, model }` key and the
-   `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment variables choose the
-   judge without editing the driver (flags win over both); `--model` with
-   `--provider fixed`/`jev` is refused. jev and llm exit 1 with nothing on
-   stdout when they cannot answer every question):
+   across them; the `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment
+   variables, a user-level `~/.config/gtd/judge.json` `{ provider, model }`, and
+   a `.gtdrc` `judge:` key choose the judge without editing the driver (flags
+   win over all three, in that order); `--model` with `--provider fixed`/`jev`
+   is refused. jev and llm exit 1 with nothing on stdout when they cannot answer
+   every question):
    - Every red round after the first: was the failure identical, new, or
      progress?
    - After you review: is each of your notes an edit, a question, a nit or
      praise?
 
-   The reference driver answers these itself (`gtd judge run`, auto selection:
-   jev when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model
-   haiku, `--model <name>` overrides); if that fails it shows you the message
-   and stops. **The `llm` provider's `p` is self-reported by the model, not a
+   gtd itself never calls a judge: `gtd loop`, the Claude Code mod and the
+   reference driver answer these through `gtd judge run` (auto selection: jev
+   when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model haiku,
+   `--model <name>` overrides); if that fails it shows you the message and
+   stops. **The `llm` provider's `p` is self-reported by the model, not a
    measured probability, so a confidently wrong verdict can clear the 0.7 floor
    and skip a gate unattended.**
 

package/claude/hooks/drive.ts

@@ -119,7 +119,9 @@ async function act(
 
 async function message(io: Io, b: Beat, beat: number, judged: string | undefined): Promise<Acted> {
   const verdict = b.judge && judged !== b.state ? await io.judge() : undefined
-  if (verdict || beat === 1) return { verdict }
+  // An unanswered judge gate never lands on its own, opening beat included:
+  // that would take the conservative default unseen.
+  if (verdict || (beat === 1 && !b.judge)) return { verdict }
   // Any later beat is a gate this run produced and the human has not read yet.
   const stop: Stop = { kind: "gate", text: b.content ?? "", ...where(b) }
   if (b.judge) stop.isJudge = true

package/claude/hooks/judge.ts

@@ -1,7 +1,8 @@
-// gtd's `llm` judge provider, answered by a subagent instead of `claude -p`.
-// A port of src/judges/providers/llm.ts (which needs Node, which a mod has
-// not): claude/hooks/judge.test.ts pins the prompt to gtd's own, so the two
-// cannot drift apart unnoticed.
+// A judge gate is answered by `gtd judge run`, except where its own
+// configuration would pick the `llm` provider: that one is answered by a
+// subagent instead of `claude -p`. A port of src/judges/providers/llm.ts
+// (which needs Node, which a mod has not): claude/hooks/judge.test.ts pins the
+// prompt to gtd's own, so the two cannot drift apart unnoticed.
 
 type Question = {
   id: string
@@ -14,6 +15,19 @@ export type Judgment = { state?: Record<string, string>; questions: Question[] }
 
 type Verdict = { id: string; answer: string | number; p: number }
 
+// The env a `gtd judge run` spawn adds to the inherited one, or `undefined` to
+// put the gate to the in-session subagent. A provider configured only in a
+// file is invisible here, so no variable and no key means the llm, as `gtd
+// judge run`'s own automatic pick does.
+export function judgeRunEnv(env: {
+  provider?: string | undefined
+  key?: string | undefined
+}): Record<string, string> | undefined {
+  const provider = env.provider || undefined
+  if (provider === "llm" || (provider === undefined && !env.key)) return undefined
+  return env.key ? { TYPESAFE_API_KEY: env.key } : {}
+}
+
 export const JUDGE_SYSTEM =
   "You are a strict, impartial judge. Answer each question from the supplied evidence alone.\n" +
   "Reply only with the structured answer; never use tools or ask questions."

package/claude/hooks/register.tsx

@@ -9,7 +9,7 @@ import type { Io, Turn, TurnEnd } from "./drive"
 import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
 import { personaSpec, resumable } from "./persona"
-import { JUDGE_SYSTEM, judgePrompt, toVerdicts } from "./judge"
+import { JUDGE_SYSTEM, judgePrompt, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
 import { documents } from "./schema"
@@ -153,13 +153,16 @@ function io($: $): Io {
     },
     judge: () =>
       docs($).judge(async (doc, j) => {
-        const key = (await $.env.get("TYPESAFE_API_KEY")) ?? (await $.env.get("TYPESAFE_AI_KEY"))
-        if (!key) return judgeInSession($, j)
+        const env = judgeRunEnv({
+          provider: await $.env.get("GTD_JUDGE_PROVIDER"),
+          key: (await $.env.get("TYPESAFE_API_KEY")) || (await $.env.get("TYPESAFE_AI_KEY")),
+        })
+        if (env === undefined) return judgeInSession($, j)
         try {
-          const r = await $.process.run(["gtd", "judge", "run", "--provider", "jev"], {
+          const r = await $.process.run(["gtd", "judge", "run"], {
             cwd: root,
             stdin: doc,
-            env: { TYPESAFE_API_KEY: key },
+            env,
             timeoutMs: TEN_MINUTES,
           })
           return r.exitCode === 0 && r.stdout.trim() ? r.stdout : undefined
@@ -511,8 +514,8 @@ async function writer($: $, prompt: string) {
   return delegate($, SHIPPER, prompt, model, "Your final answer, exactly as you would print it.")
 }
 
-// Without a TypeSafe key a judge gate is put to a small model, as gtd's own
-// llm provider does, but as a subagent of this session. Any doubt leaves the
+// Where `gtd judge run` would pick its llm, a judge gate is put to a small
+// model as that provider does, but as a subagent of this session. Any doubt leaves the
 // gate to the person, which routes the workflow its cautious way.
 async function judgeInSession($: $, j: Judgment) {
   try {

package/dist/gtd.bundle.mjs

@@ -49676,9 +49676,9 @@ const UiSchema = Struct({
 	format: optional$2(String$.annotations({ description: "Shell command run after every UI write, before it resolves ($GTD_FILE is the written file's absolute path). A non-zero exit or missing binary never reverts the write or refuses it — it's reported to the client as a notice naming the command and its exit code. Absent means no command runs at all." }))
 }).annotations({ description: "Settings for `gtd ui`: where it listens, and optional TLS." });
 const JudgeSchema = Struct({
-	provider: optional$2(Literal("fixed", "jev", "llm").annotations({ description: "Judge provider `gtd judge run` uses when no --provider flag and no GTD_JUDGE_PROVIDER is set. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm." })),
-	model: optional$2(String$.annotations({ description: "Model for provider llm, used when no --model flag and no GTD_JUDGE_MODEL is set. Pairing it with another provider is an error." }))
-}).annotations({ description: "Which judge `gtd judge run` uses, when no flag or GTD_JUDGE_* variable says." });
+	provider: optional$2(Literal("fixed", "jev", "llm").annotations({ description: "Judge provider `gtd judge run` uses when no --provider flag, no GTD_JUDGE_PROVIDER and no user-level judge.json says. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm." })),
+	model: optional$2(String$.annotations({ description: "Model for provider llm, used when no --model flag, no GTD_JUDGE_MODEL and no user-level judge.json says. Pairing it with another provider is an error." }))
+}).annotations({ description: "Which judge `gtd judge run` uses, when no flag, GTD_JUDGE_* variable or user-level judge.json says." });
 const ConfigSchema = Struct({
 	vars: optional$2(Unknown.annotations({ jsonSchema: varsJsonSchema })),
 	env: optional$2(Unknown.annotations({ jsonSchema: envJsonSchema })),
@@ -57748,23 +57748,73 @@ const envProvider = (env) => {
 	return value;
 };
 const checkPairing = (resolved) => resolved.model !== void 0 && resolved.provider !== void 0 && resolved.provider !== "llm" ? fail(`a model only applies to provider llm, not ${resolved.provider}`) : resolved;
+const userConfigPath = (env) => {
+	const xdg = env["XDG_CONFIG_HOME"];
+	if (xdg) return `${xdg}/gtd/judge.json`;
+	const home = env["HOME"];
+	return home ? `${home}/.config/gtd/judge.json` : void 0;
+};
+const readText = async (path) => {
+	try {
+		return await readFile(path, "utf8");
+	} catch (e) {
+		if (e.code === "ENOENT") return void 0;
+		return fail(`cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+	}
+};
+const parseObject = (path, text) => {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		return fail(`${path} is not valid JSON`);
+	}
+	return typeof json === "object" && json !== null && !Array.isArray(json) ? json : fail(`${path} must be a JSON object`);
+};
+const decodeUserConfig = (path, text) => {
+	const { provider, model, ...rest } = parseObject(path, text);
+	const [extra] = Object.keys(rest);
+	if (extra !== void 0) return fail(`${path}: unknown key "${extra}"`);
+	if (provider !== void 0 && !PROVIDERS.includes(provider)) return fail(`${path}: "provider" must be one of ${PROVIDERS.join(", ")}`);
+	if (model !== void 0 && typeof model !== "string") return fail(`${path}: "model" must be a string`);
+	return {
+		provider,
+		model
+	};
+};
+const readUserConfig = async (env) => {
+	const path = userConfigPath(env);
+	const text = path === void 0 ? void 0 : await readText(path);
+	return path === void 0 || text === void 0 ? void 0 : decodeUserConfig(path, text);
+};
 /**
 * Per field, the first one set wins: flag, then `GTD_JUDGE_PROVIDER` /
-* `GTD_JUDGE_MODEL` (empty counts as unset), then `.gtdrc` `judge:`. The
-* provider/model pairing is checked on the resolved pair, whichever layer
-* supplied each half.
+* `GTD_JUDGE_MODEL` (empty counts as unset), then the user file, then `.gtdrc`
+* `judge:`. The provider/model pairing is checked on the resolved pair,
+* whichever layer supplied each half.
 */
-const selectJudge = ({ provider, model, configured, env }) => {
-	const resolved = {
-		provider: provider ?? envProvider(env) ?? configured?.provider,
-		model: model ?? (env["GTD_JUDGE_MODEL"] || void 0) ?? configured?.model
-	};
-	return checkPairing(resolved);
+const selectJudge = ({ provider, model, configured, env }, user) => {
+	const layers = [
+		{
+			provider,
+			model
+		},
+		{
+			provider: envProvider(env),
+			model: env["GTD_JUDGE_MODEL"] || void 0
+		},
+		user ?? {},
+		configured ?? {}
+	];
+	return checkPairing({
+		provider: layers.find((l) => l.provider !== void 0)?.provider,
+		model: layers.find((l) => l.model !== void 0)?.model
+	});
 };
 /** The only place auto selection lives; it never falls back across providers. */
-const answererFor = (opts) => {
+const answererFor = async (opts) => {
 	const { answers, env, cwd } = opts;
-	const { provider, model } = selectJudge(opts);
+	const { provider, model } = selectJudge(opts, await readUserConfig(env));
 	if (provider === "fixed") return fixed({
 		answersPath: answers,
 		env
@@ -57785,7 +57835,7 @@ const runJudge = async (opts) => {
 	}
 	const { questions, state } = doc ?? {};
 	if (!Array.isArray(questions)) return fail("stdin has no \"questions\" array");
-	const verdicts = await answererFor(opts)(questions, typeof state === "object" && state !== null ? state : {});
+	const verdicts = await (await answererFor(opts))(questions, typeof state === "object" && state !== null ? state : {});
 	return JSON.stringify(verdicts) + "\n";
 };
 //#endregion
@@ -75762,7 +75812,8 @@ const Beat = Struct({
 	model: optional$2(String$),
 	system: optional$2(String$),
 	validate: optional$2(String$),
-	label: optional$2(String$)
+	label: optional$2(String$),
+	judge: optional$2(String$)
 });
 const Land = Struct({
 	schema: Number$,
@@ -75958,10 +76009,11 @@ const gitRoot = gen(function* () {
 	if (exit.code !== 0) return yield* fail$7(/* @__PURE__ */ new Error("not inside a git repository"));
 	return exit.stdout.trim();
 });
-const gtd = (ctx, args) => flatMap$4(ctx.host.spawn({
+const gtd = (ctx, args, stdin) => flatMap$4(ctx.host.spawn({
 	command: ctx.gtd[0],
 	args: [...ctx.gtd.slice(1), ...args],
 	cwd: ctx.root,
+	...stdin === void 0 ? {} : { stdin },
 	output: "capture"
 }), (exit) => exit.code === 0 ? succeed$3(exit.stdout) : fail$7(/* @__PURE__ */ new Error(`\`gtd ${args.join(" ")}\` failed (exit ${exit.code})\n${exit.stderr.trimEnd()}`)));
 const readBeat = (ctx) => flatMap$4(gtd(ctx, ["next", "--json"]), (stdout) => fromEither(decodeBeat(stdout)));
@@ -76044,29 +76096,41 @@ const runScript = (ctx, content) => as(ctx.host.spawn({
 	output: { log: ctx.log }
 }), LAND);
 const stop = (ctx, sgr, headline, prose) => as(zipRight$1(ctx.host.appendLog(ctx.log, prose), rest(ctx, sgr, headline)), "stop");
-const messageBeat = (ctx, beat, doc) => {
-	if (beat === 1) return succeed$3(LAND);
+const judgeGate = (ctx, doc) => gtd(ctx, ["judge", "run"], doc.judge).pipe(flatMap$4((verdict) => gtd(ctx, [
+	"judge",
+	"answer",
+	"--json"
+], verdict)), tap(() => ctx.host.say(`  ${paint(ctx.host, "2", "⚖ judged")}\n`)), catchAll((error) => as(ctx.host.appendLog(ctx.log, `${error.message}\n`), void 0)));
+const messageBeat = (ctx, beat, doc, judged) => gen(function* () {
+	const isJudge = doc.judge !== void 0 && doc.judge !== "";
+	const landing = isJudge && judged !== doc.state ? yield* judgeGate(ctx, doc) : void 0;
+	if (landing !== void 0) return {
+		...LAND,
+		landing
+	};
+	if (beat === 1 && !isJudge) return LAND;
 	const label = doc.label === void 0 ? "" : ` (${doc.label})`;
-	return stop(ctx, "33", `your turn — ${doc.state}${label}`, doc.content);
-};
-const kindBeat = (ctx, beat, doc) => {
+	return yield* stop(ctx, "33", `your turn — ${doc.state}${label}`, doc.content);
+});
+const kindBeat = (ctx, beat, doc, judged) => {
 	switch (doc.kind) {
 		case "stalled": return zipRight$1(ctx.host.appendLog(ctx.log, doc.content), fail$7(new Error(doc.content.trimEnd())));
-		case "message": return messageBeat(ctx, beat, doc);
+		case "message": return messageBeat(ctx, beat, doc, judged);
 		case "capture": return succeed$3(LAND);
 		case "script": return runScript(ctx, doc.content);
 		case "prompt": return promptBeat(ctx, doc);
 		default: return fail$7(/* @__PURE__ */ new Error(`unknown beat kind "${doc.kind}"`));
 	}
 };
-const runBeat = (ctx, beat, doc) => beat > 1 && doc.idle ? flatMap$4(gtd(ctx, ["next"]), (message) => stop(ctx, "32", `done — ${doc.state}`, message)) : kindBeat(ctx, beat, doc);
+const runBeat = (ctx, beat, doc, judged) => beat > 1 && doc.idle ? flatMap$4(gtd(ctx, ["next"]), (message) => stop(ctx, "32", `done — ${doc.state}`, message)) : kindBeat(ctx, beat, doc, judged);
 const costFlags = (outcome) => outcome.cost > 0 ? [`--cost=${outcome.cost.toFixed(6)}`, ...outcome.model === void 0 ? [] : [`--model=${outcome.model}`]] : [];
 const land = (ctx, outcome) => gen(function* () {
-	const doc = yield* fromEither(decodeLand(yield* gtd(ctx, [
+	const landed = outcome.landing ?? (yield* gtd(ctx, [
 		"land",
 		"--json",
 		...costFlags(outcome)
-	])));
+	]));
+	const doc = yield* fromEither(decodeLand(landed));
 	const exit = yield* ctx.host.spawn({
 		command: "sh",
 		args: [],
@@ -76106,11 +76170,13 @@ const runLoop = (options) => gen(function* () {
 		log: resolve(root, doc.log)
 	};
 	yield* host.resetLog(ctx.log);
+	let judged;
 	for (let beat = 1;; beat++) {
 		if (beat > 1) doc = yield* readBeat(ctx);
 		yield* header(ctx, beat, doc);
-		const outcome = yield* runBeat(ctx, beat, doc);
+		const outcome = yield* runBeat(ctx, beat, doc, judged);
 		if (outcome === "stop" || (yield* land(ctx, outcome))) return;
+		judged = outcome.landing === void 0 ? void 0 : doc.state;
 	}
 });
 //#endregion
@@ -76897,8 +76963,8 @@ const FLAGS = [
 		valueHint: "<name>",
 		help: [
 			"(gtd judge run only) the answerer: fixed | jev | llm;",
-			"omitted: GTD_JUDGE_PROVIDER, then .gtdrc judge:, then jev",
-			"when TYPESAFE_API_KEY is set, else llm"
+			"omitted: GTD_JUDGE_PROVIDER, then judge.json, then .gtdrc",
+			"judge:, then jev when TYPESAFE_API_KEY is set, else llm"
 		]
 	},
 	{
@@ -76936,7 +77002,8 @@ const FLAGS = [
 		help: [
 			"(gtd land, with --cost) tag that cost's model",
 			"(gtd judge run, llm answerer) the claude model; omitted:",
-			"GTD_JUDGE_MODEL, then .gtdrc judge:, then haiku"
+			"GTD_JUDGE_MODEL, then judge.json, then .gtdrc judge:, then",
+			"haiku"
 		]
 	},
 	{
@@ -77336,11 +77403,11 @@ const COMMAND_ROWS = [
 			"does not cover are left out. --provider jev asks TypeSafe",
 			"(TYPESAFE_API_KEY). --provider llm asks the `claude` CLI",
 			"on PATH (Claude Code only), model haiku unless --model.",
-			"No --provider: GTD_JUDGE_PROVIDER, then .gtdrc judge:",
-			"provider, else jev when TYPESAFE_API_KEY is set and no",
-			"model is given, else llm; --model likewise falls back to",
-			"GTD_JUDGE_MODEL, then judge: model. Needs no repository,",
-			"only .gtdrc files. jev and",
+			"No --provider: GTD_JUDGE_PROVIDER, then ~/.config/gtd/",
+			"judge.json, then .gtdrc judge: provider, else jev when",
+			"TYPESAFE_API_KEY is set and no model is given, else llm;",
+			"--model likewise falls back to GTD_JUDGE_MODEL, then the",
+			"file's and judge:'s model. Needs no repository. jev and",
 			"llm exit 1 when they cannot answer every question, with",
 			"nothing on stdout"
 		]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "21.0.0",
+  "version": "21.1.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/schema.json

@@ -36,15 +36,15 @@
             "jev",
             "llm"
           ],
-          "description": "Judge provider `gtd judge run` uses when no --provider flag and no GTD_JUDGE_PROVIDER is set. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm."
+          "description": "Judge provider `gtd judge run` uses when no --provider flag, no GTD_JUDGE_PROVIDER and no user-level judge.json says. Absent means auto: jev when TYPESAFE_API_KEY is set, otherwise llm."
         },
         "model": {
           "type": "string",
-          "description": "Model for provider llm, used when no --model flag and no GTD_JUDGE_MODEL is set. Pairing it with another provider is an error."
+          "description": "Model for provider llm, used when no --model flag, no GTD_JUDGE_MODEL and no user-level judge.json says. Pairing it with another provider is an error."
         }
       },
       "additionalProperties": false,
-      "description": "Which judge `gtd judge run` uses, when no flag or GTD_JUDGE_* variable says."
+      "description": "Which judge `gtd judge run` uses, when no flag, GTD_JUDGE_* variable or user-level judge.json says."
     },
     "modes": {
       "type": "object",