@pmelab/gtd 16.0.0 → 17.0.0

package/README.md

@@ -21,7 +21,9 @@ npm install -g @pmelab/gtd
 
 Or run without installing (prefix every `gtd` below with `npx`) — see
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md)
-for the settings most projects tune.
+for the settings most projects tune. A process setting's value is committed to
+Git history; keep secrets in an environment setting (see
+[Settings](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#settings)).
 
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See
@@ -359,8 +361,11 @@ noted in steps 2, 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; `--model` with `--provider fixed`/`jev` is refused. jev and llm
-   exit 1 with nothing on stdout when they cannot answer every question):
+   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):
    - Every red round after the first: was the failure identical, new, or
      progress?
    - Before spending a review turn on a package: does the code already satisfy

package/dist/gtd.bundle.mjs

@@ -30968,17 +30968,24 @@ const head = () => ctx().head();
 const start = () => ctx().start();
 /** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. See `FlowContext.skillsFor` for `ownSkills`. */
 const skillsFor = (localName, ownSkills) => ctx().skillsFor(localName, ownSkills);
-/** The merged workflow variables. */
-const vars = new Proxy({}, {
-	get: (_target, key) => typeof key === "string" ? ctx().vars[key] : void 0,
-	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 ? {
+const settingsProxy = (read) => new Proxy({}, {
+	get: (_target, key) => typeof key === "string" ? read()[key] : void 0,
+	has: (_target, key) => typeof key === "string" && key in read(),
+	ownKeys: () => Object.keys(read()),
+	getOwnPropertyDescriptor: (_target, key) => typeof key === "string" && key in read() ? {
 		enumerable: true,
 		configurable: true,
-		value: ctx().vars[key]
+		value: read()[key]
 	} : void 0
 });
+/** The process settings: pinned at process start, so flow code may branch on them. */
+const vars = settingsProxy(() => ctx().vars);
+/**
+* The environment settings: resolved live on every invocation. Flow code must
+* read them only where they cannot change the next step (step options, script
+* bodies) — replay cannot enforce this.
+*/
+const env = settingsProxy(() => ctx().env);
 /** The top-level `## ` heading texts of markdown `text`. */
 const sections = (text) => ctx().sections(text);
 /** The top-level `## ` sections of markdown `text`, each with its own markdown. */
@@ -31162,6 +31169,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	checkScript: () => checkScript,
 	codeChanges: () => codeChanges,
 	codeThreads: () => codeThreads,
+	env: () => env,
 	glob: () => glob,
 	hasThreadFor: () => hasThreadFor,
 	head: () => head,
@@ -47614,7 +47622,7 @@ const formatCommitMessage = (spec) => {
 	const lines = [];
 	if (spec.step !== void 0) lines.push(`Gtd-Step: ${formatStepId(spec.step)}`);
 	if (spec.reviewBase !== void 0) lines.push(`Gtd-Review-Base: ${spec.reviewBase}`);
-	for (const [name, value] of Object.entries(spec.vars ?? {})) lines.push(`Gtd-Var: ${name}=${value}`);
+	for (const [name, value] of Object.entries(spec.vars ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) lines.push(`Gtd-Var: ${name}=${value}`);
 	if (spec.cost !== void 0) lines.push(`Gtd-Cost: ${spec.cost.cost}${spec.cost.model !== void 0 ? ` ${spec.cost.model}` : ""}`);
 	for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`);
 	const subject = formatSubject(spec.actor, spec.to, spec.from);
@@ -47975,6 +47983,7 @@ const replay = async (input) => {
 			}));
 		}),
 		vars: input.vars,
+		env: input.env,
 		start: () => input.start,
 		skillsFor: (localName, ownSkills) => resolveSkills(scoped(localName), ownSkills) ?? [],
 		head: () => {
@@ -48387,7 +48396,7 @@ ${questionBarReturn}
   never re-open one. A genuinely open PRODUCT point may still
   raise a fresh \`## Open Questions\` entry: the product gate sits
   on this path exactly as on the first lap
-- Before grouping anything, run \`${vars.testCommand}\`
+- Before grouping anything, run \`${env.testCommand}\`
   yourself — a loop-back runs no green-baseline gate, so the
   tree may already be red (reverting the edit can undo a fix it
   made). If red, make that breakage the first concern, ahead of
@@ -48932,8 +48941,8 @@ const ARCHITECTURE = ".gtd/ARCHITECTURE.md";
 const REVIEW = ".gtd/REVIEW.md";
 const QUALITY = ".gtd/QUALITY.md";
 const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md";
-const planner = () => vars.plannerModel ?? "";
-const coder = () => vars.coderModel ?? "";
+const planner = () => env.plannerModel ?? "";
+const coder = () => env.coderModel ?? "";
 /** Turn the sketch since `base` into `.gtd/REQUIREMENTS.md`. */
 const triage$1 = (base) => agentWithSkills("triage", designTriagePrompt(base), {
 	label: "Triaging the change",
@@ -49087,7 +49096,7 @@ const collecting = (capture) => agentWithSkills("review.collecting", buildReview
 	allowEmpty: true
 });
 /** Run the suite as step `name`; resolves `true` when it passed. A failure is in `.gtd/FEEDBACK.md`. */
-const baseline = (name, label = "Checking the baseline") => check(name, vars.testCommand ?? "", {
+const baseline = (name, label = "Checking the baseline") => check(name, env.testCommand ?? "", {
 	report: FEEDBACK,
 	label
 });
@@ -49139,7 +49148,7 @@ const healthy = async (fix, options = {}) => {
 	let fixes = options.fixesSoFar ?? 0;
 	let previous;
 	for (;;) {
-		if (await check("health.check", vars.testCommand ?? "", {
+		if (await check("health.check", env.testCommand ?? "", {
 			report: ".gtd/FEEDBACK.md",
 			label: "Running checks",
 			sweepOnGreen: [".gtd/ESCALATION.md"]
@@ -49766,10 +49775,8 @@ const buildTail = (fixFirst, base) => scope("build", async () => {
 });
 //#endregion
 //#region src/workflows/vars.ts
+/** Process settings. */
 const defaults = {
-	testCommand: "npm test",
-	plannerModel: "smart",
-	coderModel: "base",
 	reviewBase: "",
 	judgeBudgetBytes: "32768",
 	judgeIdenticalMinP: "0.7",
@@ -49778,6 +49785,12 @@ const defaults = {
 	architectureSkipMinP: "0.85",
 	qualityReviews: "owasp-security, ponytail-review, test-audit"
 };
+/** Environment settings. */
+const envDefaults = {
+	testCommand: "npm test",
+	plannerModel: "smart",
+	coderModel: "base"
+};
 //#endregion
 //#region src/workflows/skills.ts
 const skills = {
@@ -49832,6 +49845,7 @@ var unified_exports = /* @__PURE__ */ __exportAll({
 	defaults: () => defaults,
 	describeEscalation: () => describeEscalation,
 	design: () => design,
+	envDefaults: () => envDefaults,
 	escalate: () => escalate,
 	escalation: () => escalation,
 	escalationExhausted: () => escalationExhausted,
@@ -50646,7 +50660,17 @@ var Workspace = class Workspace extends Tag("Workspace")() {
 /** The `vars:` shape: a flat name -> scalar map (`compileVarsMap` coerces every scalar to a string). */
 const varsJsonSchema = {
 	type: "object",
-	description: "Flat name -> scalar map merged into the workflow's vars. Scalars are coerced to strings.",
+	description: "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. Scalars are coerced to strings.",
+	additionalProperties: { type: [
+		"string",
+		"number",
+		"boolean"
+	] }
+};
+/** The `env:` shape: environment settings, read live on every invocation and never pinned to a process. */
+const envJsonSchema = {
+	type: "object",
+	description: "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine, like the test command or a model hint. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
 	additionalProperties: { type: [
 		"string",
 		"number",
@@ -50700,13 +50724,46 @@ const UiSchema = Struct({
 	key: optional$1(String$.annotations({ description: "Path to a TLS private key file, enabling HTTPS. Requires `cert` too." })),
 	format: optional$1(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$1(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$1(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." });
 const ConfigSchema = Struct({
 	vars: optional$1(Unknown.annotations({ jsonSchema: varsJsonSchema })),
+	env: optional$1(Unknown.annotations({ jsonSchema: envJsonSchema })),
+	judge: optional$1(JudgeSchema),
 	modes: optional$1(Unknown.annotations({ jsonSchema: modesJsonSchema })),
 	ui: optional$1(UiSchema),
 	skills: optional$1(Unknown.annotations({ jsonSchema: skillsJsonSchema }))
 });
 //#endregion
+//#region src/workflow/vars.ts
+const PREFIX = "GTD_";
+/**
+* One kind of setting, later wins: the workflow's own defaults, the `.gtdrc`
+* map (`vars:` or `env:`), `--var` overrides (process settings only; environment
+* settings pass `{}`), then `GTD_<NAME>` for any name an earlier layer declared
+* (a shell variable never introduces a name).
+*/
+const resolveVars = (workflowVars, rcVars, entryVars, env) => {
+	const merged = {
+		...workflowVars,
+		...rcVars,
+		...entryVars
+	};
+	for (const name of Object.keys(merged)) {
+		const value = env[PREFIX + name.toUpperCase()];
+		if (value !== void 0) merged[name] = value;
+	}
+	return merged;
+};
+/** The first process setting whose value spans lines — a `Gtd-Var:` trailer cannot carry it. */
+const multilineSetting = (vars) => Object.keys(vars).sort().find((name) => /[\r\n]/.test(vars[name]));
+const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name is written verbatim into a `Gtd-Var: <name>=<value>` trailer, so `=` or a newline would corrupt it. */
+const isSettingName = (name) => SETTING_NAME.test(name);
+const SETTING_NAME_RULE = "a setting name is a letter or \"_\", then letters, digits or \"_\"";
+//#endregion
 //#region src/SteeringFormats.ts
 /** The unrendered `validate:` template a workflow compiler seeds for a built-in mode — quoted so a path with spaces survives interpolation. */
 const seededValidateCommand = (mode) => `gtd check ${mode} "$GTD_FILE"`;
@@ -50791,14 +50848,14 @@ const err = (path, message) => ({
 	origin: ""
 });
 /** A flat `name -> scalar` map; a malformed value is a load error and is dropped. */
-const compileVarsMap = (raw) => {
+const compileVarsMap = (raw, keyName) => {
 	const diagnostics = [];
 	if (raw === void 0) return {
 		vars: {},
 		diagnostics
 	};
 	if (!isPlainObject$3(raw)) {
-		diagnostics.push(err(["vars"], `"vars" must be a mapping of name -> scalar value, got ${describeType(raw)}`));
+		diagnostics.push(err([keyName], `"${keyName}" must be a mapping of name -> scalar value, got ${describeType(raw)}`));
 		return {
 			vars: {},
 			diagnostics
@@ -50806,8 +50863,12 @@ const compileVarsMap = (raw) => {
 	}
 	const vars = {};
 	for (const [key, value] of Object.entries(raw)) {
+		if (!isSettingName(key)) {
+			diagnostics.push(err([keyName], `"${keyName}" key ${JSON.stringify(key)} is not a valid setting name — ${SETTING_NAME_RULE}`));
+			continue;
+		}
 		if (!isScalar(value)) {
-			diagnostics.push(err(["vars", key], `"vars.${key}" must be a string, number, or boolean, got ${describeType(value)}`));
+			diagnostics.push(err([keyName, key], `"${keyName}.${key}" must be a string, number, or boolean, got ${describeType(value)}`));
 			continue;
 		}
 		vars[key] = String(value);
@@ -51002,9 +51063,16 @@ const withOrigin = (diagnostics, lookup) => diagnostics.map((d) => ({
 	...d,
 	origin: lookup(d.path)
 }));
+const layerKeys = (layers, name) => layers.flatMap((layer) => {
+	const own = isPlainObject$3(layer.value) ? layer.value[name] : void 0;
+	return isPlainObject$3(own) ? Object.keys(own).map((key) => ({
+		key,
+		origin: layer.origin
+	})) : [];
+});
 /**
 * Merge every layer outermost→innermost and compile what a `.gtdrc` may carry:
-* `vars`, `modes` and `ui`. A workflow is defined only in `gtd.config.ts`, so a
+* `vars`, `env`, `judge`, `modes` and `ui`. A workflow is defined only in `gtd.config.ts`, so a
 * leftover `workflow:` key is an error pointing there. Pure and total.
 */
 const compileConfig = (layers) => {
@@ -51021,8 +51089,13 @@ const compileConfig = (layers) => {
 	const mergedConfig = merged;
 	const lookupIn = (path) => originAt(originTree, path);
 	const ui = mergedConfig["ui"];
-	const { vars: rcVars, diagnostics: varsDiagnostics } = compileVarsMap(mergedConfig["vars"]);
+	const judge = mergedConfig["judge"];
+	const { vars: rcVars, diagnostics: varsDiagnostics } = compileVarsMap(mergedConfig["vars"], "vars");
 	diagnostics.push(...withOrigin(varsDiagnostics, lookupIn));
+	const { vars: rcEnv, diagnostics: envDiagnostics } = compileVarsMap(mergedConfig["env"], "env");
+	diagnostics.push(...withOrigin(envDiagnostics, lookupIn));
+	const varsKeys = layerKeys(layers, "vars");
+	const envKeys = layerKeys(layers, "env");
 	diagnostics.push(...withOrigin(deadSkillsVarDiagnostics(mergedConfig["vars"]), lookupIn));
 	const { modes: rcModes, diagnostics: modesDiagnostics } = compileModesMap(mergedConfig["modes"]);
 	diagnostics.push(...withOrigin(modesDiagnostics, lookupIn));
@@ -51043,6 +51116,10 @@ const compileConfig = (layers) => {
 	const seeded = Object.fromEntries(BUILT_IN_MODE_NAMES.map((name) => [name, { validate: seededValidateCommand(name) }]));
 	return {
 		rcVars,
+		rcEnv,
+		varsKeys,
+		envKeys,
+		...judge !== void 0 ? { judge } : {},
 		modes: mergeModes(seeded, rcModes),
 		...ui !== void 0 ? { ui } : {},
 		rcSkills,
@@ -51108,26 +51185,6 @@ const interpolate = (config, env) => {
 	};
 };
 //#endregion
-//#region src/workflow/vars.ts
-const PREFIX = "GTD_";
-/**
-* The merged vars, later wins: the workflow's own defaults, `.gtdrc` `vars:`,
-* the process's entry vars, then `GTD_<NAME>` for any name an earlier layer
-* declared (an env var never introduces a name).
-*/
-const resolveVars = (workflowVars, rcVars, entryVars, env) => {
-	const merged = {
-		...workflowVars,
-		...rcVars,
-		...entryVars
-	};
-	for (const name of Object.keys(merged)) {
-		const value = env[PREFIX + name.toUpperCase()];
-		if (value !== void 0) merged[name] = value;
-	}
-	return merged;
-};
-//#endregion
 //#region node_modules/yaml/dist/nodes/identity.js
 var require_identity = /* @__PURE__ */ __commonJSMin(((exports) => {
 	const ALIAS = Symbol.for("yaml.alias");
@@ -57932,31 +57989,49 @@ const decodeLevel = (level, env) => gen(function* () {
 		}))
 	};
 });
+/** Everything the `.gtdrc` half of a load reads, findings not yet judged. */
+const readRc = gen(function* () {
+	const narrator = yield* Narrator;
+	const host = yield* Host;
+	const levels = yield* (yield* ConfigDiscovery).levels(host.root, host.home);
+	for (const level of levels) yield* narrator.narrate(`config: layer ${level.filepath}`);
+	const decoded = yield* forEach$2(levels, (level) => decodeLevel(level, host.env));
+	return {
+		levels,
+		compiled: compileConfig(decoded.flatMap((d) => d.layer !== void 0 ? [d.layer] : [])),
+		decodeDiagnostics: decoded.flatMap((d) => d.diagnostics)
+	};
+});
+const failOnErrors = (diagnostics) => {
+	const fatal = diagnostics.filter((d) => d.severity === "error");
+	if (fatal.length === 0) return _void;
+	const lines = fatal.map(formatDiagnostic);
+	return fail$6(new GtdError(`gtd config:\n${lines.map((line) => `  - ${line}`).join("\n")}`));
+};
+/**
+* The `.gtdrc` half of `load`: no repository, no `gtd.config.ts` evaluation.
+* Any error diagnostic fails it.
+*/
+const loadRcConfig = gen(function* () {
+	const { levels, compiled, decodeDiagnostics } = yield* readRc;
+	yield* failOnErrors(dedupeDiagnostics(sortDiagnostics([...decodeDiagnostics, ...compiled.diagnostics], levels.map((level) => level.filepath))));
+	return compiled;
+});
 /**
 * Build the whole config pipeline — discover levels by walking `Host`'s
 * cwd→home chain (`ConfigDiscovery`, kept behind a `Context.Tag` since its
 * production implementation reads real disk through cosmiconfig directly,
 * incompatible with an in-memory `@inmem` `Workspace`), decode each level
-* individually against `ConfigSchema`, then hand every successfully-decoded
-* layer to the pure `compileWorkflow` boundary (`src/workflow/compile.ts`),
-* which does its own merging and `./`/`../` file-ref inlining (through
-* `Workspace`, which — unlike discovery — both production and an in-memory
-* scenario back identically). A decode failure never short-circuits the
+* individually against `ConfigSchema`, then compile every successfully-decoded
+* layer (`src/workflow/compile.ts`). A decode failure never short-circuits the
 * whole load: every level's own findings — decode AND compile alike — are
-* sorted/deduped together (`levels`' own order is the layer order, decode
-* failures included) into ONE report, so a config broken at two ancestor
+* sorted/deduped together into ONE report, so a config broken at two ancestor
 * layers reports both instead of just the first one reached.
 */
 const load = gen(function* () {
-	const narrator = yield* Narrator;
 	const host = yield* Host;
 	const discovery = yield* ConfigDiscovery;
-	const levels = yield* discovery.levels(host.root, host.home);
-	for (const level of levels) yield* narrator.narrate(`config: layer ${level.filepath}`);
-	const decoded = yield* forEach$2(levels, (level) => decodeLevel(level, host.env));
-	const layers = decoded.flatMap((d) => d.layer !== void 0 ? [d.layer] : []);
-	const decodeDiagnostics = decoded.flatMap((d) => d.diagnostics);
-	const compiled = compileConfig(layers);
+	const { levels, compiled, decodeDiagnostics } = yield* readRc;
 	const module = yield* discovery.workflowModule(host.root, host.home);
 	const loaded = yield* try_({
 		try: () => loadWorkflow(module),
@@ -57973,14 +58048,11 @@ const load = gen(function* () {
 	const diagnostics = dedupeDiagnostics(sortDiagnostics([
 		...decodeDiagnostics,
 		...compiled.diagnostics,
-		...unknownSkillDiagnostics
+		...unknownSkillDiagnostics,
+		...wrongKindDiagnostics(loaded, compiled)
 	], layerOrder));
-	const fatal = diagnostics.filter((d) => d.severity === "error");
-	if (fatal.length > 0) {
-		const lines = fatal.map(formatDiagnostic);
-		return yield* fail$6(new GtdError(`gtd config:\n${lines.map((line) => `  - ${line}`).join("\n")}`));
-	}
-	const initial = yield* firstStep(loaded, resolveVars(loaded.defaults, compiled.rcVars, {}, host.env), headTree(yield* Workspace));
+	yield* failOnErrors(diagnostics);
+	const initial = yield* firstStep(loaded, headTree(yield* Workspace));
 	return {
 		workflow: {
 			flow: loaded.flow,
@@ -57994,12 +58066,30 @@ const load = gen(function* () {
 		},
 		workflowVars: { ...loaded.defaults },
 		rcVars: compiled.rcVars,
+		workflowEnv: { ...loaded.envDefaults },
+		rcEnv: compiled.rcEnv,
 		...compiled.ui !== void 0 ? { ui: compiled.ui } : {},
 		warnings: diagnostics.filter((d) => d.severity === "warning"),
 		configFiles: levels.map((level) => level.filepath),
 		workflowFiles: loaded.dependencyFiles
 	};
 });
+/** A name under the wrong key (or under both) in a `.gtdrc` layer: each is an error at its own origin. */
+const wrongKindDiagnostics = (loaded, compiled) => {
+	const error = (path, message, origin) => ({
+		severity: "error",
+		path,
+		message,
+		origin
+	});
+	const diagnostics = [];
+	for (const { key, origin } of compiled.varsKeys) if (Object.hasOwn(loaded.envDefaults, key)) diagnostics.push(error(["vars", key], `"vars.${key}" is an environment setting — move it under "env:"`, origin));
+	for (const { key, origin } of compiled.envKeys) {
+		if (Object.hasOwn(loaded.defaults, key)) diagnostics.push(error(["env", key], `"env.${key}" is a process setting — move it under "vars:"`, origin));
+		if (compiled.varsKeys.some((v) => v.key === key)) diagnostics.push(error(["env", key], `"${key}" is declared under both "vars:" and "env:" — a setting is one kind or the other`, origin));
+	}
+	return diagnostics;
+};
 const TRANSFORM_MEMO_SIZE = 512;
 const memoized = (transform) => {
 	const memo = /* @__PURE__ */ new Map();
@@ -58051,15 +58141,24 @@ const optionalFunction = (exports, name) => {
 };
 /**
 * Read a workflow module: the default export is the flow; `defaults`,
-* `summary`, `base` and `steering` are optional; any other export is ignored.
+* `envDefaults`, `summary`, `base` and `steering` are optional; any other export is ignored.
 */
 const fromModule = (exported, origin, dependencyFiles) => {
 	const exports = typeof exported === "object" && exported !== null ? exported : {};
 	const flow = exports.default;
 	if (typeof flow !== "function") throw new Error("the default export is not a flow — export default an async function");
+	const defaults = stringRecord(exports, "defaults");
+	const envDefaults = stringRecord(exports, "envDefaults");
+	for (const [exportName, record] of [["defaults", defaults], ["envDefaults", envDefaults]]) {
+		const bad = Object.keys(record).find((name) => !isSettingName(name));
+		if (bad !== void 0) throw new Error(`the "${exportName}" export declares ${JSON.stringify(bad)}, not a valid setting name — ${SETTING_NAME_RULE}`);
+	}
+	const both = Object.keys(defaults).filter((name) => Object.hasOwn(envDefaults, name));
+	if (both.length > 0) throw new Error(`${both.map((name) => `"${name}"`).join(", ")} declared in both "defaults" and "envDefaults" — a setting is a process setting or an environment setting, not both`);
 	return {
 		flow,
-		defaults: stringRecord(exports, "defaults"),
+		defaults,
+		envDefaults,
 		steering: stringRecord(exports, "steering"),
 		skills: skillsRecord(exports),
 		summary: optionalFunction(exports, "summary"),
@@ -58106,7 +58205,38 @@ const watchedEmptyTree = () => {
 		read: () => read
 	};
 };
-const replayToFirstStep = (loaded, vars, tree) => flatMap$4(promise(() => replay({
+/** An empty settings record that logs every read: a named `get`/`has`, or an enumeration. */
+const watchedEmptySettings = () => {
+	const names = /* @__PURE__ */ new Set();
+	let enumerated = false;
+	return {
+		settings: new Proxy({}, {
+			get: (_target, key) => {
+				if (typeof key === "string") names.add(key);
+			},
+			has: (_target, key) => {
+				if (typeof key === "string") names.add(key);
+				return false;
+			},
+			ownKeys: () => {
+				enumerated = true;
+				return [];
+			}
+		}),
+		names,
+		enumerated: () => enumerated
+	};
+};
+const settingReads = (kind, watch) => {
+	const reads = [];
+	if (watch.names.size > 0) {
+		const sorted = [...watch.names].sort().map((name) => JSON.stringify(name));
+		reads.push(`the ${kind} setting${sorted.length > 1 ? "s" : ""} ${sorted.join(", ")}`);
+	}
+	if (watch.enumerated()) reads.push(`every ${kind} setting`);
+	return reads;
+};
+const replayToFirstStep = (loaded, vars, env, tree) => flatMap$4(promise(() => replay({
 	flow: loaded.flow,
 	episode: {
 		entry: void 0,
@@ -58117,6 +58247,7 @@ const replayToFirstStep = (loaded, vars, tree) => flatMap$4(promise(() => replay
 		commits: []
 	},
 	vars,
+	env,
 	start: "",
 	budgetBytes: Number.MAX_SAFE_INTEGER
 })), (outcome) => {
@@ -58127,15 +58258,22 @@ const replayToFirstStep = (loaded, vars, tree) => flatMap$4(promise(() => replay
 /**
 * The default entry's first step — where a finished process waits — found the
 * only way a flow can be read: by replaying it over an empty history. Episode
-* boundaries are that step's commits, so it must not move with the tree: a
-* flow that reads the repository before reaching it is replayed again over
-* HEAD, and must reach the same step there.
+* boundaries are that step's commits, so it must depend on neither a setting
+* (edited mid-process, it would move the boundary before pinned values are
+* read) nor the tree: a flow that reads the repository before reaching it is
+* replayed again over HEAD, and must reach the same step there.
 */
-const firstStep = (loaded, vars, head) => gen(function* () {
+const firstStep = (loaded, head) => gen(function* () {
 	const empty = watchedEmptyTree();
-	const name = yield* replayToFirstStep(loaded, vars, empty.tree);
+	const vars = watchedEmptySettings();
+	const env = watchedEmptySettings();
+	const outcome = yield* either(replayToFirstStep(loaded, vars.settings, env.settings, empty.tree));
+	const reads = [...settingReads("process", vars), ...settingReads("environment", env)];
+	if (reads.length > 0) return yield* fail$6(new GtdError(`gtd config:\n  - ${loaded.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`));
+	if (outcome._tag === "Left") return yield* fail$6(outcome.left);
+	const name = outcome.right;
 	if (!empty.read()) return name;
-	const atHead = yield* replayToFirstStep(loaded, vars, head);
+	const atHead = yield* replayToFirstStep(loaded, vars.settings, env.settings, head);
 	if (atHead === name) return name;
 	return yield* fail$6(new GtdError(`gtd config:\n  - ${loaded.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`));
 });
@@ -58145,14 +58283,14 @@ var ConfigService = class ConfigService extends Tag("ConfigService")() {
 //#endregion
 //#region src/workflow/init.ts
 const SCHEMA_URL = "https://cdn.jsdelivr.net/npm/@pmelab/gtd/schema.json";
-const INIT_VARS = { testCommand: "npm test" };
+const INIT_ENV = { testCommand: "npm test" };
 const MODES_SUGGESTION = {
 	qa: { format: "npx prettier --write \"$GTD_FILE\"" },
 	review: { format: "npx prettier --write \"$GTD_FILE\"" }
 };
 const renderInitScaffold = () => ({ config: JSON.stringify({
 	$schema: SCHEMA_URL,
-	vars: INIT_VARS,
+	env: INIT_ENV,
 	modes: MODES_SUGGESTION
 }, null, 2) + "\n" });
 //#endregion
@@ -58449,12 +58587,37 @@ const llm = ({ env, cwd, model = DEFAULT_MODEL, timeoutMs = TIMEOUT_MS }) => asy
 };
 //#endregion
 //#region src/judges/run.ts
+const PROVIDERS = [
+	"fixed",
+	"jev",
+	"llm"
+];
 const fail = (message) => {
 	throw new Error(`gtd judge run: ${message}`);
 };
+const envProvider = (env) => {
+	const value = env["GTD_JUDGE_PROVIDER"] || void 0;
+	if (value !== void 0 && !PROVIDERS.includes(value)) return fail(`GTD_JUDGE_PROVIDER must be one of ${PROVIDERS.join(", ")} — got "${value}"`);
+	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;
+/**
+* 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.
+*/
+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);
+};
 /** The only place auto selection lives; it never falls back across providers. */
-const answererFor = ({ provider, answers, env, model, cwd }) => {
-	if (model !== void 0 && provider !== void 0 && provider !== "llm") return fail(`--model only applies to --provider llm, not ${provider}`);
+const answererFor = (opts) => {
+	const { answers, env, cwd } = opts;
+	const { provider, model } = selectJudge(opts);
 	if (provider === "fixed") return fixed({
 		answersPath: answers,
 		env
@@ -63801,7 +63964,7 @@ const runOf = (history, location, closingHash = void 0) => {
 		trace: processCommits.map((c, i) => traceEntryOf(c.hash, parsed[i])),
 		costEntries: parsed.flatMap(costEntriesOf),
 		judgeVerdicts: parsed.flatMap((m) => m.judge),
-		entryVars: location.entry === void 0 ? {} : { ...first?.vars },
+		pinnedVars: { ...first?.vars },
 		headTurn: headTurnOf(head),
 		closingHash,
 		episode: {
@@ -63957,6 +64120,20 @@ const pendingTree = (workspace, entries, rewrite) => {
 	};
 };
 /**
+* The one resolver of both setting kinds. Process settings: the recorded
+* (pinned) value wins per name, anything unrecorded resolves live — the
+* fallback for a process started before pinning existed. Environment settings
+* are always live. `entryOverrides` are `--var` values, passed only while a
+* process is being entered.
+*/
+const settingsFor = (config, pinnedVars, hostEnv, entryOverrides = {}) => ({
+	vars: {
+		...resolveVars(config.workflowVars, config.rcVars, entryOverrides, hostEnv),
+		...pinnedVars
+	},
+	env: resolveVars(config.workflowEnv, config.rcEnv, {}, hostEnv)
+});
+/**
 * `judgeBudgetBytes` is the one var that refuses rather than disabling its
 * mechanism when blanked: without a bound the judge payload is rejected
 * anyway. Absent falls back to a conservative default.
@@ -63977,6 +64154,7 @@ const replayFor = (setup, pending) => replay({
 		commits: setup.episode
 	},
 	vars: setup.vars,
+	env: setup.env,
 	start: setup.run.diffBase,
 	startTree: setup.run.diffBase === EMPTY_TREE$1 ? treeFromRecord({}) : commitTree(setup.workspace, setup.run.diffBase),
 	budgetBytes: setup.budget,
@@ -64119,7 +64297,7 @@ const restAt = (ref) => gen(function* () {
 	const host = yield* Host;
 	const def = config.workflow;
 	const run = yield* computeProcessRun(git, def, ref);
-	const vars = resolveVars(config.workflowVars, config.rcVars, run.entryVars, host.env);
+	const { vars, env } = settingsFor(config, run.pinnedVars, host.env);
 	const budget = yield* try_({
 		try: () => judgeBudgetBytes(vars),
 		catch: (e) => e instanceof Error ? e : new Error(String(e))
@@ -64142,6 +64320,7 @@ const restAt = (ref) => gen(function* () {
 		def,
 		run,
 		vars,
+		env,
 		budget,
 		workspace,
 		base,
@@ -64169,6 +64348,7 @@ const restAt = (ref) => gen(function* () {
 		trace: outcome.trace,
 		run,
 		vars,
+		env,
 		changes,
 		memory: memory.key,
 		memoryResumed: memory.resumed,
@@ -64189,7 +64369,7 @@ const currentRest = restAt(void 0);
 const entryRefusal = (rest, name, entryVars) => gen(function* () {
 	const config = yield* (yield* ConfigService).load;
 	const host = yield* Host;
-	const vars = resolveVars(config.workflowVars, config.rcVars, entryVars, host.env);
+	const { vars, env } = settingsFor(config, {}, host.env, entryVars);
 	const workspace = rest.setup.workspace;
 	const outcome = yield* promise(() => replay({
 		flow: rest.def.flow,
@@ -64202,6 +64382,7 @@ const entryRefusal = (rest, name, entryVars) => gen(function* () {
 			commits: []
 		},
 		vars,
+		env,
 		start: "",
 		budgetBytes: rest.setup.budget,
 		skills: rest.def.skills,
@@ -64254,28 +64435,29 @@ const reviewGateRewrite = (def) => {
 		apply: (content) => reviewFormat.clearTicks(content)
 	};
 };
-/**
-* What landing the pending turn at `rest` does — a pure decision from a
-* replay with the working tree as the pending turn. The target step is
-* computed by replaying, never matched.
-*/
-const decideLanding = (rest, verdicts) => gen(function* () {
-	const early = cleanLanding(rest);
-	if (early !== void 0) return early;
-	const outcome = yield* promise(() => replayFor(rest.setup, {
-		tree: pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), reviewGateRewrite(rest.stepDef)),
-		...verdicts !== void 0 ? { verdicts } : {}
-	}));
-	if (outcome.kind === "refused") return {
+const multilineRefusal = (vars) => {
+	const multiline = multilineSetting(vars);
+	return multiline === void 0 ? void 0 : {
 		kind: "refusal",
-		message: outcome.message
+		message: `gtd: process setting "${multiline}" spans several lines — a process setting is pinned in a commit trailer and must be a single line`
 	};
-	if (outcome.kind === "divergence" || outcome.kind === "failed") return yield* fail$6(new Error(outcome.message));
-	const to = outcome.kind === "rest" ? outcome.rest.name : rest.def.initial;
+};
+const landingTarget = (outcome, rest) => {
+	if (outcome.kind === "refused") return succeed$3({
+		kind: "refusal",
+		message: outcome.message
+	});
+	if (outcome.kind === "divergence" || outcome.kind === "failed") return fail$6(new Error(outcome.message));
+	return succeed$3(outcome.kind === "rest" ? outcome.rest.name : rest.def.initial);
+};
+const landingTo = (rest, to) => {
 	if (rest.changes.length === 0 && rest.stepDef.kind === "script" && to === rest.state) return {
 		kind: "noop",
 		settled: true
 	};
+	const starts = noProcessUnderway(rest) && to !== rest.def.initial;
+	const refused = starts ? multilineRefusal(rest.vars) : void 0;
+	if (refused !== void 0) return refused;
 	return {
 		kind: "commit",
 		to,
@@ -64283,9 +64465,26 @@ const decideLanding = (rest, verdicts) => gen(function* () {
 			actor: rest.actor,
 			from: rest.state,
 			to,
-			step: rest.step.id
+			step: rest.step.id,
+			...starts ? { vars: rest.vars } : {}
 		}
 	};
+};
+/**
+* What landing the pending turn at `rest` does — a pure decision from a
+* replay with the working tree as the pending turn. The target step is
+* computed by replaying, never matched.
+*/
+const decideLanding = (rest, verdicts) => gen(function* () {
+	const early = cleanLanding(rest);
+	if (early !== void 0) return early;
+	const outcome = yield* promise(() => replayFor(rest.setup, {
+		tree: pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), reviewGateRewrite(rest.stepDef)),
+		...verdicts !== void 0 ? { verdicts } : {}
+	}));
+	const to = yield* landingTarget(outcome, rest);
+	if (typeof to !== "string") return to;
+	return landingTo(rest, to);
 });
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
 const previewLanding = (rest) => decideLanding(rest, void 0).pipe(map$4((landing) => landing.kind === "commit" ? landing.to : void 0), catchAll(() => succeed$3(void 0)));
@@ -64318,7 +64517,7 @@ const summaryFor = (run) => gen(function* () {
 		})),
 		processCost: run.costEntries.reduce((sum, entry) => sum + entry.cost, 0),
 		processCostByModel: costByModel(run.costEntries),
-		vars: resolveVars(config.workflowVars, config.rcVars, run.entryVars, host.env)
+		...settingsFor(config, run.pinnedVars, host.env)
 	});
 });
 //#endregion
@@ -64417,9 +64616,15 @@ const refusal = (message) => ({
 	kind: "refusal",
 	message
 });
+const checkOverrides = (commandLabel, varOverrides, declaredNames, envNames) => gen(function* () {
+	const environmentOnly = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n) && envNames.includes(n));
+	if (environmentOnly.length > 0) return yield* fail$6(new GtdUsageError(`${commandLabel}: --var pins process settings only; ${environmentOnly.join(", ")} ${environmentOnly.length === 1 ? "is an environment setting" : "are environment settings"} — set it under "env:" in .gtdrc or with a GTD_<NAME> environment variable`));
+	const undeclared = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n));
+	if (undeclared.length > 0) return refusal(`${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(", ")} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`);
+});
 /**
 * `gtd --entry <name>`: start a brand NEW process at a workflow entry, writing
-* an opening commit that carries zero or more `Gtd-Var:` trailers, plus a
+* an opening commit that carries every process setting as a `Gtd-Var:` trailer, plus a
 * `Gtd-Review-Base:` trailer when the entry fixes the process's diff base.
 * All validation is a REFUSAL, not an Effect failure.
 */
@@ -64432,11 +64637,16 @@ const planEntry = (current, actor, entry) => gen(function* () {
 		...config.workflowVars,
 		...config.rcVars
 	});
-	const undeclared = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n));
-	if (undeclared.length > 0) return refusal(`${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(", ")} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`);
+	const overrideRefusal = yield* checkOverrides(commandLabel, varOverrides, declaredNames, Object.keys({
+		...config.workflowEnv,
+		...config.rcEnv
+	}));
+	if (overrideRefusal !== void 0) return overrideRefusal;
 	let base;
 	const baseOf = current.def.base;
 	const vars = resolveVars(config.workflowVars, config.rcVars, varOverrides, (yield* Host).env);
+	const multiline = multilineSetting(vars);
+	if (multiline !== void 0) return refusal(`${commandLabel}: process setting "${multiline}" spans several lines — a process setting is pinned in a commit trailer and must be a single line`);
 	const template = yield* try_({
 		try: () => baseOf?.(name, vars),
 		catch: (e) => /* @__PURE__ */ new Error(`${commandLabel}: ${e instanceof Error ? e.message : String(e)}`)
@@ -64459,7 +64669,7 @@ const planEntry = (current, actor, entry) => gen(function* () {
 					actor,
 					to: name,
 					...base !== void 0 ? { reviewBase: base } : {},
-					vars: varOverrides
+					vars
 				})
 			}
 		}, {
@@ -77045,10 +77255,12 @@ const readStdin = () => tryPromise({
 /** Stdout is written once, after the answerer resolves — a rejection leaves it empty. */
 const runJudgeRunCommand = (command, out) => gen(function* () {
 	const host = yield* Host;
+	const { judge } = yield* loadRcConfig;
 	const input = yield* readStdin();
 	const verdict = yield* tryPromise({
 		try: () => runJudge({
 			provider: command.provider,
+			configured: judge,
 			answers: command.answers,
 			model: command.model,
 			cwd: host.scratchDir,
@@ -77616,7 +77828,11 @@ const FLAGS = [
 		decode: ([raw]) => raw === "fixed" || raw === "jev" || raw === "llm" ? right(raw) : left(`gtd: --provider must be one of fixed, jev, llm — got "${raw ?? ""}"`),
 		scopeError: "gtd: --provider is only valid for `gtd judge run`",
 		valueHint: "<name>",
-		help: ["(gtd judge run only) the answerer: fixed | jev | llm;", "omitted: jev when TYPESAFE_API_KEY is set, else llm"]
+		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"
+		]
 	},
 	{
 		name: "--answers",
@@ -77650,7 +77866,11 @@ const FLAGS = [
 		decode: ([raw]) => raw === void 0 || raw.trim() === "" || /[\r\n]/.test(raw) ? left("gtd: --model must be a non-empty, single-line value") : right(raw),
 		scopeError: "gtd: --model is only valid for `gtd land` (with --cost) or `gtd judge run`",
 		valueHint: "<name>",
-		help: ["(gtd land, with --cost) tag that cost's model", "(gtd judge run, llm answerer) the claude model; default haiku"]
+		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"
+		]
 	},
 	{
 		name: "--entry",
@@ -77679,6 +77899,7 @@ const FLAGS = [
 				if (eq <= 0) return left(`gtd: --var must be <name>=<value> with a non-empty name — got "${raw}"`);
 				const name = raw.slice(0, eq);
 				const value = raw.slice(eq + 1);
+				if (!isSettingName(name)) return left(`gtd: --var ${JSON.stringify(name)} is not a valid setting name — ${SETTING_NAME_RULE}`);
 				if (/[\r\n]/.test(value)) return left(`gtd: --var ${name} must be a single-line value`);
 				if (seen.has(name)) return left(`gtd: --var ${name} specified more than once`);
 				seen.add(name);
@@ -77689,9 +77910,10 @@ const FLAGS = [
 		scopeError: "gtd: --var requires --entry",
 		valueHint: "<name>=<value>",
 		help: [
-			"(with --entry; repeatable) supply a fixed variable",
-			"override for the new process; the name must already be",
-			"declared by the workflow's defaults or the .gtdrc vars:"
+			"(with --entry; repeatable) pin a process setting for the",
+			"new process; the name must already be declared by the",
+			"workflow's defaults or the .gtdrc vars: (environment",
+			"settings are not pinnable)"
 		]
 	},
 	{
@@ -77764,8 +77986,8 @@ const COMMAND_ROWS = [
 		arity: "none",
 		details: [
 			"Scaffold a minimal .gtdrc.json for this repo, seeding the",
-			"default variables you are most likely to change (the test",
-			"command) and a Prettier formatting suggestion. gtd runs its",
+			"environment setting you are most likely to change (the test",
+			"command, under env:) and a Prettier formatting suggestion. gtd runs its",
 			"built-in workflow by default, so no workflow is written —",
 			"write a gtd.config.ts only to customize the workflow itself.",
 			"Takes no argument. Run once per repo; refuses if a gtd",
@@ -78009,8 +78231,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: jev when TYPESAFE_API_KEY is set and no",
-			"--model is given, else llm. Needs no repository. jev and",
+			"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",
 			"llm exit 1 when they cannot answer every question, with",
 			"nothing on stdout"
 		]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "16.0.0",
+  "version": "17.0.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

@@ -5,7 +5,7 @@
   "properties": {
     "vars": {
       "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's vars. Scalars are coerced to strings.",
+      "description": "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. Scalars are coerced to strings.",
       "additionalProperties": {
         "type": [
           "string",
@@ -14,6 +14,38 @@
         ]
       }
     },
+    "env": {
+      "type": "object",
+      "description": "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine, like the test command or a model hint. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean"
+        ]
+      }
+    },
+    "judge": {
+      "type": "object",
+      "required": [],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": [
+            "fixed",
+            "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."
+        },
+        "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."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Which judge `gtd judge run` uses, when no flag or GTD_JUDGE_* variable says."
+    },
     "modes": {
       "type": "object",
       "description": "Steering-file modes a workflow step's mode: may name. Each entry declares at least one of format/validate: shell commands gtd runs via bash with $GTD_FILE set to the steering file's path. format rewrites the file in place; validate exits 0 when valid, non-zero with findings on stdout/stderr otherwise. The halves layer independently, so naming a built-in mode (qa/review) and declaring only format: adds formatting while keeping gtd's own validation. gtd ships no formatter — bring your own (prettier, dprint, a script).",

package/src/flows/runtime.ts

@@ -136,6 +136,7 @@ export interface FlowContext {
   readonly threads: (text: string) => readonly ThreadInfo[]
   readonly codeThreads: () => readonly CodeThreadInfo[]
   readonly vars: Readonly<Record<string, string>>
+  readonly env: Readonly<Record<string, string>>
   readonly head: () => string
   readonly start: () => string
   /**
@@ -256,19 +257,31 @@ export const start = (): string => ctx().start()
 export const skillsFor = (localName: string, ownSkills?: readonly string[]): readonly string[] =>
   ctx().skillsFor(localName, ownSkills)
 
-/** 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,
-  },
-)
+const settingsProxy = (
+  read: () => Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> =>
+  new Proxy(
+    {},
+    {
+      get: (_target, key) => (typeof key === "string" ? read()[key] : undefined),
+      has: (_target, key) => typeof key === "string" && key in read(),
+      ownKeys: () => Object.keys(read()),
+      getOwnPropertyDescriptor: (_target, key) =>
+        typeof key === "string" && key in read()
+          ? { enumerable: true, configurable: true, value: read()[key] }
+          : undefined,
+    },
+  )
+
+/** The process settings: pinned at process start, so flow code may branch on them. */
+export const vars: Readonly<Record<string, string>> = settingsProxy(() => ctx().vars)
+
+/**
+ * The environment settings: resolved live on every invocation. Flow code must
+ * read them only where they cannot change the next step (step options, script
+ * bodies) — replay cannot enforce this.
+ */
+export const env: Readonly<Record<string, string>> = settingsProxy(() => ctx().env)
 
 // ── Text utilities ──────────────────────────────────────────────────────────
 
@@ -343,6 +356,7 @@ export interface SummaryContext {
   readonly processCost: number
   readonly processCostByModel: readonly { readonly model: string; readonly cost: number }[]
   readonly vars: Readonly<Record<string, string>>
+  readonly env: Readonly<Record<string, string>>
 }
 
 /** `gtd summary`'s prompt — a workflow module's optional `summary` export. */

package/src/workflows/health.ts

@@ -1,6 +1,7 @@
 import {
   answered,
   check,
+  env,
   human,
   judge,
   numeric,
@@ -17,7 +18,7 @@ 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 })
+  check(name, env.testCommand ?? "", { report: FEEDBACK, label })
 
 /** How many escalation rounds a run of red checks has spent — reset once the suite goes green. */
 export interface EscalationCount {
@@ -95,7 +96,7 @@ export const healthy = async (
   let fixes = options.fixesSoFar ?? 0
   let previous: string | undefined
   for (;;) {
-    const green = await check("health.check", vars.testCommand ?? "", {
+    const green = await check("health.check", env.testCommand ?? "", {
       report: FEEDBACK,
       label: "Running checks",
       // Swept only on green: an unresolved analysis survives every retry.

package/src/workflows/steps.ts

@@ -1,4 +1,4 @@
-import { human, vars } from "../flows/index.js"
+import { env, human } from "../flows/index.js"
 import * as t from "./text.js"
 
 // The bundled workflow's single steps. A step's name is relative to the
@@ -14,8 +14,8 @@ export const REVIEW = ".gtd/REVIEW.md"
 export const QUALITY = ".gtd/QUALITY.md"
 export const SPEC_FEEDBACK = ".gtd/SPEC_FEEDBACK.md"
 
-const planner = (): string => vars.plannerModel ?? ""
-const coder = (): string => vars.coderModel ?? ""
+const planner = (): string => env.plannerModel ?? ""
+const coder = (): string => env.coderModel ?? ""
 
 // ── Planning ────────────────────────────────────────────────────────────────
 

package/src/workflows/text.fixture.ts

@@ -5,10 +5,11 @@ import {
   type StepRequest,
 } from "../flows/index.js"
 import { skills as bundledSkills } from "./skills.js"
-import { defaults } from "./vars.js"
+import { defaults, envDefaults } from "./vars.js"
 
 export interface TextContext {
   readonly vars?: Readonly<Record<string, string>>
+  readonly env?: Readonly<Record<string, string>>
   readonly head?: string
   readonly start?: string
   readonly codeThreads?: readonly CodeThreadInfo[]
@@ -73,6 +74,7 @@ export const fixtureContext = (
   threads: () => [],
   codeThreads: () => context.codeThreads ?? [],
   vars: { ...defaults, ...context.vars },
+  env: { ...envDefaults, ...context.env },
   head: () => context.head ?? "",
   start: () => context.start ?? "",
   skillsFor: skillsForOf(context),

package/src/workflows/text.test.ts

@@ -129,6 +129,7 @@ describe("summaryPrompt", () => {
         { model: "base", cost: 7 },
       ],
       vars: {},
+      env: {},
     })
     expect(prompt).toContain("Token cost: 12\n- smart: 5\n- base: 7\n\nPrint the closing message")
   })

package/src/workflows/text.ts

@@ -1,10 +1,10 @@
 import {
   agent,
   codeThreads,
+  env,
   head,
   skillsFor,
   start,
-  vars,
   type AgentOptions,
   type SummaryContext,
 } from "../flows/index.js"
@@ -195,7 +195,7 @@ ${questionBarReturn}
   never re-open one. A genuinely open PRODUCT point may still
   raise a fresh \`## Open Questions\` entry: the product gate sits
   on this path exactly as on the first lap
-- Before grouping anything, run \`${vars.testCommand}\`
+- Before grouping anything, run \`${env.testCommand}\`
   yourself — a loop-back runs no green-baseline gate, so the
   tree may already be red (reverting the edit can undo a fix it
   made). If red, make that breakage the first concern, ahead of

package/src/workflows/unified.ts

@@ -31,7 +31,7 @@ import * as t from "./text.js"
 // re-exported below.
 
 export { threads, type ThreadInfo } from "../flows/index.js"
-export { defaults } from "./vars.js"
+export { defaults, envDefaults } from "./vars.js"
 export { skills } from "./skills.js"
 export { agentWithSkills } from "./text.js"
 export * from "./steps.js"

package/src/workflows/vars.ts

@@ -1,21 +1,27 @@
-// The bundled workflow's variable defaults. `.gtdrc` `vars:`, `--var` and
-// `GTD_<NAME>` override any of them.
+// The bundled workflow's settings, in two kinds. A process setting changes
+// which step comes next, so it is pinned for the whole process at its start;
+// an environment setting only changes how a step runs on this machine, so it
+// is read live on every invocation. `.gtdrc` `vars:`/`env:`, `--var` (process
+// settings only) and `GTD_<NAME>` override either.
+
+/** Process settings. */
 export const defaults: Readonly<Record<string, string>> = {
-  testCommand: "npm test",
-  plannerModel: "smart",
-  coderModel: "base",
   reviewBase: "",
   judgeBudgetBytes: "32768",
   judgeIdenticalMinP: "0.7",
   specPreJudge: "0.9",
   reviewNoteActionable: "0.7",
   architectureSkipMinP: "0.85",
-  // The per-step skill lists formerly declared here as `*Skills` vars now
-  // live in `./skills.ts`, addressed per step by `.gtdrc` `skills:`.
-  // `qualityReviews` is the one exception: it fans out into one turn per
-  // entry (`qualityLenses`, in `./review.ts`) rather than naming one step's
-  // skill list, so it stays a var — pairing with `build.quality.reviewing`'s
-  // entry in `./skills.ts`, which replaces the lens on every one of those
-  // turns.
+  // `qualityReviews` fans out into one turn per entry (`qualityLenses`, in
+  // `./review.ts`) rather than naming one step's skill list, so it is a
+  // setting — pairing with `build.quality.reviewing`'s entry in
+  // `./skills.ts`, which replaces the lens on every one of those turns.
   qualityReviews: "owasp-security, ponytail-review, test-audit",
 }
+
+/** Environment settings. */
+export const envDefaults: Readonly<Record<string, string>> = {
+  testCommand: "npm test",
+  plannerModel: "smart",
+  coderModel: "base",
+}