@pmelab/gtd 15.10.0 → 17.0.0

package/dist/gtd.bundle.mjs

@@ -30966,17 +30966,26 @@ const changesSince = (hash, pattern) => {
 const head = () => ctx().head();
 /** The process's diff base: the commit before it began, or the base `gtd --entry` fixed. */
 const start = () => ctx().start();
-/** 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 ? {
+/** 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);
+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. */
@@ -31160,6 +31169,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	checkScript: () => checkScript,
 	codeChanges: () => codeChanges,
 	codeThreads: () => codeThreads,
+	env: () => env,
 	glob: () => glob,
 	hasThreadFor: () => hasThreadFor,
 	head: () => head,
@@ -31185,6 +31195,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	scope: () => scope,
 	sectionBodies: () => sectionBodies,
 	sections: () => sections,
+	skillsFor: () => skillsFor,
 	start: () => start,
 	threads: () => threads,
 	vars: () => vars,
@@ -47611,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);
@@ -47773,7 +47784,11 @@ const replay = async (input) => {
 		truncated: judgeCuts.get(request) ?? []
 	} : void 0;
 	const judgeCuts = /* @__PURE__ */ new WeakMap();
-	const resolve = (request) => {
+	const resolveSkills = (name, ownSkills) => {
+		const resolved = input.configuredSkills?.[name] ?? ownSkills ?? input.skills?.[name];
+		return resolved !== void 0 && resolved.length === 0 ? void 0 : resolved;
+	};
+	const resolve = (request, name) => {
 		if (request.kind === "agent") {
 			const persona = {};
 			for (const s of scopes) {
@@ -47784,7 +47799,8 @@ const replay = async (input) => {
 				...request,
 				options: {
 					...persona,
-					...request.options
+					...request.options,
+					skills: resolveSkills(name, request.options.skills)
 				}
 			};
 		}
@@ -47803,7 +47819,7 @@ const replay = async (input) => {
 		const name = scoped(request.name);
 		const occurrence = (occurrences.get(name) ?? 0) + 1;
 		occurrences.set(name, occurrence);
-		const resolved = resolve(request);
+		const resolved = resolve(request, name);
 		const reached = {
 			id: {
 				name,
@@ -47967,7 +47983,9 @@ const replay = async (input) => {
 			}));
 		}),
 		vars: input.vars,
+		env: input.env,
 		start: () => input.start,
+		skillsFor: (localName, ownSkills) => resolveSkills(scoped(localName), ownSkills) ?? [],
 		head: () => {
 			const rest = commits.slice(cursor);
 			return rest.length > 0 && rest.every((c) => c.parsed.step === void 0) ? rest[rest.length - 1].hash : position.hash;
@@ -48241,21 +48259,18 @@ const withSkills = (skills, prompt) => {
 	if (skills === void 0 || skills.trim() === "") return prompt;
 	return `${skillsPreamble.replaceAll("{skills}", skills)}\n\n${prompt}`;
 };
-/** `skills:` split on `,`, each name trimmed, empty entries dropped — `[]` for `undefined`, `""`, or blank. */
-const splitSkills = (raw) => (raw ?? "").split(",").map((name) => name.trim()).filter((name) => name.length > 0);
 /**
-* An `agent()` step declaring `skills`: the raw, comma-separated var feeds
-* both the `skills` option (the wire's `skills` key, split) and, re-joined
-* with `", "`, `withSkills`'s preamble — one declaration, so the two can
-* never drift apart.
+* An `agent()` step whose preamble names its resolved skills: `skillsFor`
+* resolves `name` (scoped from here, same as `agent()`'s own resolver) for
+* the preamble prose, passing `options.skills` through as `ownSkills` — the
+* same precedence tier `agent()`'s own wire resolver gives a call's own
+* `skills` option, so a step that declares one (`reviewQuality`'s per-turn
+* lens) gets it in the preamble too, not just on the wire, whenever no
+* bundled or configured entry outranks it. Both reads share one resolver
+* (`Replay.ts`'s `resolveSkills`), so the preamble and the wire can't drift
+* apart.
 */
-const agentWithSkills = (name, skills, prompt, options = {}) => {
-	const list = splitSkills(skills);
-	return agent(name, withSkills(list.join(", "), prompt), {
-		...options,
-		skills: list
-	});
-};
+const agentWithSkills = (name, prompt, options = {}) => agent(name, withSkills(skillsFor(name, options.skills).join(", "), prompt), options);
 const unwindFailure = (commit) => `gtd could not unwind ${commit} out of your working tree.`;
 const idleMessage = () => `No active gtd process.
 
@@ -48381,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
@@ -48899,10 +48914,13 @@ every commit is machine-authored.
   high-level architectural changes — never which files changed; \`git
   diff --stat\` is for that, not this message
 - If the range removes or renames a documented config key, CLI flag, or
-  workflow state — a public surface, not an internal one — add a literal
-  \`BREAKING CHANGE:\` footer naming what disappears. A \`!\` on the type
-  prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's own
-  commit-analyzer has missed that marker before, cutting no release
+  workflow state, OR makes a previously-accepted config value now fail to
+  load (a stricter validation, an escape a value must now spell differently)
+  — a public surface, not an internal one, either way — add a literal
+  \`BREAKING CHANGE:\` footer naming what breaks and, for the second case,
+  the exact escape or rewrite a committed \`.gtdrc\` needs. A \`!\` on the
+  type prefix alone (\`feat!:\`/\`refactor!:\`) is NOT enough: this repo's
+  own commit-analyzer has missed that marker before, cutting no release
   until a follow-up commit carried the literal footer instead
 
 The process's entry commit is \`${it.entryCommit}\`. ${human}Inspect the range: \`git log ${it.processBase}..${it.processTip}\`
@@ -48923,24 +48941,24 @@ 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", vars.triageSkills, designTriagePrompt(base), {
+const triage$1 = (base) => agentWithSkills("triage", designTriagePrompt(base), {
 	label: "Triaging the change",
 	file: REQUIREMENTS,
 	mode: "qa",
 	model: planner(),
 	system: designSystem()
 });
-const author = () => agentWithSkills("author", vars.architectureSkills, architectureAuthorPrompt(), {
+const author = () => agentWithSkills("author", architectureAuthorPrompt(), {
 	label: "Refining the technical plan",
 	file: ARCHITECTURE,
 	mode: "qa",
 	model: planner(),
 	system: architectSystem()
 });
-const decompose = () => agentWithSkills("decompose", vars.decomposeSkills, architectureDecomposePrompt(), {
+const decompose = () => agentWithSkills("decompose", architectureDecomposePrompt(), {
 	label: "Decomposing into packages",
 	model: planner(),
 	system: architectSystem()
@@ -48959,37 +48977,37 @@ const answerTechnicalQuestions = () => human("gate.answer", {
 	mode: "qa",
 	acceptClean: true
 });
-const build = (pkg) => agentWithSkills("building", vars.buildSkills, packagesItemBuildingPrompt(pkg), {
+const build = (pkg) => agentWithSkills("building", packagesItemBuildingPrompt(pkg), {
 	label: "Building",
 	model: coder(),
 	system: builderSystem()
 });
-const fixSuite = () => agentWithSkills("fix-suite", vars.fixSkills, packagesItemFixSuitePrompt(), {
+const fixSuite = () => agentWithSkills("fix-suite", packagesItemFixSuitePrompt(), {
 	label: "Fixing the check",
 	file: FEEDBACK,
 	model: coder(),
 	system: builderSystem()
 });
-const fixSpec = (pkg) => agentWithSkills("fix-spec", vars.reviewFixSkills, packagesItemFixSpecPrompt(pkg), {
+const fixSpec = (pkg) => agentWithSkills("fix-spec", packagesItemFixSpecPrompt(pkg), {
 	label: "Fixing review feedback",
 	file: SPEC_FEEDBACK,
 	model: coder(),
 	system: builderSystem()
 });
 /** Review `pkg` against its spec, focused on the `failing` sections the pre-judge could not clear. */
-const reviewPackage = (pkg, failing = []) => agentWithSkills("spec.review", vars.specReviewSkills, packagesItemSpecReviewPrompt(pkg, failing), {
+const reviewPackage = (pkg, failing = []) => agentWithSkills("spec.review", packagesItemSpecReviewPrompt(pkg, failing), {
 	label: "Reviewing the package",
 	model: planner(),
 	system: specReviewerSystem(),
 	allowEmpty: true
 });
-const fix = () => agentWithSkills("fix", vars.fixSkills, buildFixPrompt(), {
+const fix = () => agentWithSkills("fix", buildFixPrompt(), {
 	label: "Fixing the check",
 	file: FEEDBACK,
 	model: coder(),
 	system: finisherSystem()
 });
-const describeEscalation = () => agentWithSkills("health.describe", vars.escalateSkills, healthDescribePrompt(), {
+const describeEscalation = () => agentWithSkills("health.describe", healthDescribePrompt(), {
 	label: "Describing the escalation",
 	file: FEEDBACK,
 	model: coder(),
@@ -49008,15 +49026,21 @@ const escalationExhausted = () => human("health.exhausted", {
 	file: ESCALATION,
 	acceptClean: true
 });
-/** One quality review, through the skill `lens`. */
-const reviewQuality = (lens) => agentWithSkills("quality.reviewing", lens, buildQualityReviewingPrompt(lens), {
+/**
+* One quality review, through the skill `lens`. `lens` rides as this turn's
+* own `skills` option — a `.gtdrc` `build.quality.reviewing` entry still
+* overrides it (config beats a flow-supplied list same as any other step),
+* but absent one the lens itself is what the turn loads by default.
+*/
+const reviewQuality = (lens) => agentWithSkills("quality.reviewing", buildQualityReviewingPrompt(lens), {
 	label: "Reviewing (one quality lens)",
 	file: QUALITY,
 	model: planner(),
 	system: reviewerSystem(),
-	allowEmpty: true
+	allowEmpty: true,
+	skills: [lens]
 });
-const fixQuality = () => agentWithSkills("fix-quality", vars.reviewFixSkills, buildFixQualityPrompt(), {
+const fixQuality = () => agentWithSkills("fix-quality", buildFixQualityPrompt(), {
 	label: "Fixing quality findings",
 	file: QUALITY,
 	model: coder(),
@@ -49024,7 +49048,7 @@ const fixQuality = () => agentWithSkills("fix-quality", vars.reviewFixSkills, bu
 	allowEmpty: true
 });
 /** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
-const reviewing = (base, carry) => agentWithSkills("review.reviewing", vars.reviewSkills, buildReviewReviewingPrompt(base, carry), {
+const reviewing = (base, carry) => agentWithSkills("review.reviewing", buildReviewReviewingPrompt(base, carry), {
 	label: "Reviewing",
 	file: REVIEW,
 	mode: "review",
@@ -49033,7 +49057,7 @@ const reviewing = (base, carry) => agentWithSkills("review.reviewing", vars.revi
 	base
 });
 /** Answer every `question` note inline in `.gtd/REVIEW.md`. */
-const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-questions", vars.reviewSkills, buildReviewAnswerQuestionsPrompt(notes), {
+const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-questions", buildReviewAnswerQuestionsPrompt(notes), {
 	label: "Answering your questions",
 	file: REVIEW,
 	mode: "review",
@@ -49044,7 +49068,7 @@ const answerReviewQuestions = (notes) => agentWithSkills("review.answer-review-q
 * Fix every `nit` note in one turn. Its name puts it in the `build.review`
 * conversation, which has one identity — so it runs as the reviewer, not the coder.
 */
-const fixNits = (notes) => agentWithSkills("review.fix-nits", vars.reviewFixSkills, buildReviewFixNitsPrompt(notes), {
+const fixNits = (notes) => agentWithSkills("review.fix-nits", buildReviewFixNitsPrompt(notes), {
 	label: "Fixing your nits",
 	file: REVIEW,
 	model: planner(),
@@ -49063,7 +49087,7 @@ const reviewMissing = (round) => human("review.review-missing", {
 	label: "Nothing to review"
 });
 /** Turn the review round `capture` describes into `.gtd/REQUIREMENTS.md`, or change nothing. */
-const collecting = (capture) => agentWithSkills("review.collecting", vars.reviewSkills, buildReviewCollectingPrompt(capture), {
+const collecting = (capture) => agentWithSkills("review.collecting", buildReviewCollectingPrompt(capture), {
 	label: "Collecting your feedback",
 	file: REQUIREMENTS,
 	mode: "qa",
@@ -49072,7 +49096,7 @@ const collecting = (capture) => agentWithSkills("review.collecting", vars.review
 	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
 });
@@ -49124,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"]
@@ -49528,8 +49552,8 @@ const architecturePass = async () => {
 };
 //#endregion
 //#region src/workflows/review.ts
-/** The skills the quality lap reviews with, one turn each: the `qualityReviews` var. */
-const qualityLenses = () => splitSkills(vars.qualityReviews);
+/** The lenses the quality lap reviews with, one turn each: the `qualityReviews` var, split on `,` and trimmed. Unlike a `skills:` entry, this fans out into one whole turn per entry rather than naming one step's skill list — see `build.quality.reviewing` in `./skills.ts` for the (separate) skills a lens turn itself loads. */
+const qualityLenses = () => (vars.qualityReviews ?? "").split(",").map((lens) => lens.trim()).filter((lens) => lens.length > 0);
 /**
 * One review turn per lens over the whole change, each appending what it
 * finds blocking to `.gtd/QUALITY.md`. Resolves `"findings"` when that file
@@ -49751,27 +49775,46 @@ 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",
 	specPreJudge: "0.9",
 	reviewNoteActionable: "0.7",
 	architectureSkipMinP: "0.85",
-	triageSkills: "spec-driven-development, planning-and-task-breakdown",
-	architectureSkills: "api-and-interface-design, documentation-and-adrs, ponytail",
-	decomposeSkills: "incremental-implementation, planning-and-task-breakdown",
-	buildSkills: "test-driven-development, incremental-implementation",
-	fixSkills: "debugging-and-error-recovery",
-	reviewFixSkills: "incremental-implementation, code-simplification",
-	reviewSkills: "code-review-and-quality",
-	specReviewSkills: "code-review-and-quality, spec-driven-development",
-	escalateSkills: "debugging-and-error-recovery",
 	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 = {
+	"design.triage": ["spec-driven-development", "planning-and-task-breakdown"],
+	"architecture.author": [
+		"api-and-interface-design",
+		"documentation-and-adrs",
+		"ponytail"
+	],
+	"architecture.decompose": ["incremental-implementation", "planning-and-task-breakdown"],
+	"packages.item.building": ["test-driven-development", "incremental-implementation"],
+	"packages.item.fix-suite": ["debugging-and-error-recovery"],
+	"packages.item.fix-spec": ["incremental-implementation", "code-simplification"],
+	"packages.item.spec.review": ["code-review-and-quality", "spec-driven-development"],
+	"packages.item.health.describe": ["debugging-and-error-recovery"],
+	"build.fix": ["debugging-and-error-recovery"],
+	"build.health.describe": ["debugging-and-error-recovery"],
+	"build.quality.reviewing": [],
+	"build.fix-quality": ["incremental-implementation", "code-simplification"],
+	"build.review.reviewing": ["code-review-and-quality"],
+	"build.review.answer-review-questions": ["code-review-and-quality"],
+	"build.review.fix-nits": ["incremental-implementation", "code-simplification"],
+	"build.review.collecting": ["code-review-and-quality"]
+};
 //#endregion
 //#region src/workflows/unified.ts
 var unified_exports = /* @__PURE__ */ __exportAll({
@@ -49802,6 +49845,7 @@ var unified_exports = /* @__PURE__ */ __exportAll({
 	defaults: () => defaults,
 	describeEscalation: () => describeEscalation,
 	design: () => design,
+	envDefaults: () => envDefaults,
 	escalate: () => escalate,
 	escalation: () => escalation,
 	escalationExhausted: () => escalationExhausted,
@@ -49827,6 +49871,7 @@ var unified_exports = /* @__PURE__ */ __exportAll({
 	reviewPackage: () => reviewPackage,
 	reviewQuality: () => reviewQuality,
 	reviewing: () => reviewing,
+	skills: () => skills,
 	specReview: () => specReview,
 	steering: () => steering,
 	summary: () => summary,
@@ -50615,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",
@@ -50643,6 +50698,15 @@ const modesJsonSchema = {
 		}
 	}
 };
+/** The `skills:` shape: full step name -> its skill list (`compileSkillsMap`). An entry REPLACES the step's bundled list wholesale, never adds to it — and the schema can validate an entry's VALUE but never its KEY, since step names come from the workflow in play, not a fixed set. */
+const skillsJsonSchema = {
+	type: "object",
+	description: "Flat step full-name -> skill-name array map. Each entry REPLACES the named step's bundled skill list wholesale (never merges into it); [] means no skills at all for that step, and no preamble. A key naming a step the workflow in play does not declare is a load error listing the known names — the schema itself cannot validate a key, only a value's shape.",
+	additionalProperties: {
+		type: "array",
+		items: { type: "string" }
+	}
+};
 /**
 * A real (not `Unknown`) schema, unlike `vars`/`modes`: it is a flat settings
 * struct with no per-mode map to compile, so its JSON Schema derives from the
@@ -50660,12 +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)
+	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"`;
@@ -50736,7 +50834,7 @@ const dedupeDiagnostics = (diagnostics) => {
 };
 //#endregion
 //#region src/workflow/compile.ts
-const isPlainObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isPlainObject$3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const describeType = (v) => {
 	if (v === null) return "null";
 	if (Array.isArray(v)) return "array";
@@ -50750,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$2(raw)) {
-		diagnostics.push(err(["vars"], `"vars" must be a mapping of name -> scalar value, got ${describeType(raw)}`));
+	if (!isPlainObject$3(raw)) {
+		diagnostics.push(err([keyName], `"${keyName}" must be a mapping of name -> scalar value, got ${describeType(raw)}`));
 		return {
 			vars: {},
 			diagnostics
@@ -50765,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);
@@ -50776,10 +50878,75 @@ const compileVarsMap = (raw) => {
 		diagnostics
 	};
 };
+const isStringArray$1 = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
+/** A flat `step full name -> skill list` map; a malformed value is a load error and is dropped. */
+const compileSkillsMap = (raw) => {
+	const diagnostics = [];
+	if (raw === void 0) return {
+		skills: {},
+		diagnostics
+	};
+	if (!isPlainObject$3(raw)) {
+		diagnostics.push(err(["skills"], `"skills" must be a mapping of step name -> array of skill names, got ${describeType(raw)}`));
+		return {
+			skills: {},
+			diagnostics
+		};
+	}
+	const skills = Object.create(null);
+	for (const [key, value] of Object.entries(raw)) {
+		if (!isStringArray$1(value)) {
+			diagnostics.push(err(["skills", key], `"skills.${key}" must be an array of skill names (strings), got ${describeType(value)}`));
+			continue;
+		}
+		skills[key] = value;
+	}
+	return {
+		skills,
+		diagnostics
+	};
+};
+/**
+* The nine `*Skills` workflow vars this package deletes, each naming the
+* `.gtdrc` `skills:` step key(s) that replace it — four of the nine fan out to
+* several keys, because a var once shared between steps now addresses
+* them independently. Deliberately the only place gtd special-cases a var
+* name by string; meant to be deleted a major release after this ships.
+*/
+const DEAD_SKILLS_VARS = {
+	triageSkills: ["design.triage"],
+	architectureSkills: ["architecture.author"],
+	decomposeSkills: ["architecture.decompose"],
+	buildSkills: ["packages.item.building"],
+	fixSkills: ["packages.item.fix-suite", "build.fix"],
+	reviewFixSkills: [
+		"packages.item.fix-spec",
+		"build.fix-quality",
+		"build.review.fix-nits"
+	],
+	reviewSkills: [
+		"build.review.reviewing",
+		"build.review.answer-review-questions",
+		"build.review.collecting"
+	],
+	specReviewSkills: ["packages.item.spec.review"],
+	escalateSkills: ["packages.item.health.describe", "build.health.describe"]
+};
+/** `vars:` entries naming one of the nine deleted `*Skills` vars — scoped to `.gtdrc` `vars:` only; there is no environment scan anywhere in this check, so a `GTD_BUILDSKILLS` gets neither this diagnostic nor any other. */
+const deadSkillsVarDiagnostics = (rawVars) => {
+	if (!isPlainObject$3(rawVars)) return [];
+	const diagnostics = [];
+	for (const key of Object.keys(rawVars)) {
+		const replacement = DEAD_SKILLS_VARS[key];
+		if (replacement === void 0) continue;
+		diagnostics.push(err(["vars", key], `"vars.${key}" was removed — skills are now configured per step, under the "skills:" key, addressed by: ${replacement.join(", ")}`));
+	}
+	return diagnostics;
+};
 const MODE_COMMAND_KEYS = ["format", "validate"];
 /** One `modes:` entry; malformed entries are load errors and are dropped. */
 const compileMode = (name, entry, diagnostics) => {
-	if (!isPlainObject$2(entry)) {
+	if (!isPlainObject$3(entry)) {
 		diagnostics.push(err(["modes", name], `mode "${name}": must be an object with "format" and/or "validate", got ${describeType(entry)}`));
 		return;
 	}
@@ -50809,7 +50976,7 @@ const compileModesMap = (raw) => {
 		modes: {},
 		diagnostics
 	};
-	if (!isPlainObject$2(raw)) {
+	if (!isPlainObject$3(raw)) {
 		diagnostics.push(err(["modes"], `"modes" must be a mapping of mode name -> { format, validate }, got ${describeType(raw)}`));
 		return {
 			modes: {},
@@ -50838,7 +51005,7 @@ const mergeModes = (base, override) => {
 };
 /** Stamp a whole (possibly deeply nested) value with ONE origin, recursively — used when `inner` replaces `base` wholesale: every key inside still needs its own node, or a LATER layer partially overriding just one nested key would silently lose the rest of this subtree's origin. */
 const uniformOrigin = (value, origin) => {
-	if (!isPlainObject$2(value)) return { self: origin };
+	if (!isPlainObject$3(value)) return { self: origin };
 	const children = {};
 	for (const [key, v] of Object.entries(value)) children[key] = uniformOrigin(v, origin);
 	return {
@@ -50856,7 +51023,7 @@ const uniformOrigin = (value, origin) => {
 * findings, not one origin for the whole merged key.
 */
 const mergeWithOrigin = (base, baseOrigin, inner, innerOrigin) => {
-	if (!isPlainObject$2(base) || !isPlainObject$2(inner)) return {
+	if (!isPlainObject$3(base) || !isPlainObject$3(inner)) return {
 		value: inner,
 		origin: uniformOrigin(inner, innerOrigin)
 	};
@@ -50896,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) => {
@@ -50907,7 +51081,7 @@ const compileConfig = (layers) => {
 	let merged = {};
 	let originTree = { self: BUILT_IN_ORIGIN };
 	for (const layer of layers) {
-		const value = isPlainObject$2(layer.value) ? layer.value : {};
+		const value = isPlainObject$3(layer.value) ? layer.value : {};
 		const step = mergeWithOrigin(merged, originTree, value, layer.origin);
 		merged = step.value;
 		originTree = step.origin;
@@ -50915,37 +51089,100 @@ 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));
+	const skillsKeys = [];
+	for (const layer of layers) {
+		if (!isPlainObject$3(layer.value)) continue;
+		const own = compileSkillsMap(layer.value["skills"]);
+		diagnostics.push(...own.diagnostics.map((d) => ({
+			...d,
+			origin: layer.origin
+		})));
+		skillsKeys.push(...Object.keys(own.skills).map((key) => ({
+			key,
+			origin: layer.origin
+		})));
+	}
+	const { skills: rcSkills } = compileSkillsMap(mergedConfig["skills"]);
 	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,
+		skillsKeys,
 		diagnostics: dedupeDiagnostics(sortDiagnostics(diagnostics, layerOrder))
 	};
 };
 //#endregion
-//#region src/workflow/vars.ts
-const PREFIX = "GTD_";
+//#region src/workflow/interpolate.ts
+const VAR_PATTERN = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+const isPlainObject$2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /**
-* 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).
+* `modes.*.format`, `modes.*.validate` and `ui.format` — gtd hands these
+* straight to bash, where `$` already means the shell's own expansion. The
+* predicate reads only the config PATH shape, never the value: sniffing for
+* `$GTD_FILE` would exempt whichever command happens not to name it, and
+* silently interpolate one that names something else instead.
 */
-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;
+const isBashExemptPath = (path) => {
+	if (path.length === 3 && path[0] === "modes" && (path[2] === "format" || path[2] === "validate")) return true;
+	if (path.length === 2 && path[0] === "ui" && path[1] === "format") return true;
+	return false;
+};
+const interpolateString = (value, path, env, diagnostics) => value.replace(VAR_PATTERN, (match, braced, bare) => {
+	if (match === "$$") return "$";
+	const name = braced ?? bare;
+	if (name === void 0) return match;
+	const resolved = env[name];
+	if (resolved !== void 0) return resolved;
+	diagnostics.push({
+		severity: "error",
+		path,
+		message: `"${match}" references environment variable "${name}", which is not set`,
+		origin: ""
+	});
+	return match;
+});
+const walk = (value, path, env, diagnostics) => {
+	if (typeof value === "string") return isBashExemptPath(path) ? value : interpolateString(value, path, env, diagnostics);
+	if (Array.isArray(value)) return value.map((v, i) => walk(v, [...path, i], env, diagnostics));
+	if (isPlainObject$2(value)) {
+		const out = {};
+		for (const [key, v] of Object.entries(value)) out[key] = walk(v, [...path, key], env, diagnostics);
+		return out;
 	}
-	return merged;
+	return value;
+};
+/**
+* Expand `$NAME`/`${NAME}` from `env` over every string leaf of a decoded
+* `.gtdrc` layer, except the three paths gtd hands to bash. `$$` yields a
+* literal `$`; any other `$` not followed by a valid name (a trailing `$`,
+* `$1`, `$-`, `$ `) is left untouched. Exactly one pass: `String.replace`
+* never rescans a replacement's own text, so an environment variable's value
+* can never be read back as config syntax. An unset name is a load-error
+* `Diagnostic` naming the config path; the original `$NAME` text is left in
+* place rather than blanked.
+*/
+const interpolate = (config, env) => {
+	const diagnostics = [];
+	return {
+		value: walk(config, [], env, diagnostics),
+		diagnostics
+	};
 };
 //#endregion
 //#region node_modules/yaml/dist/nodes/identity.js
@@ -57718,7 +57955,7 @@ const dropOptionalUndefinedArtifacts = (all) => {
 * findings surface together through `load`'s single sorted/deduped report,
 * the same as every other producer in this package.
 */
-const decodeLevel = (level) => gen(function* () {
+const decodeLevel = (level, env) => gen(function* () {
 	if (!isPlainObject$1(level.config)) return {
 		layer: void 0,
 		diagnostics: [{
@@ -57739,53 +57976,83 @@ const decodeLevel = (level) => gen(function* () {
 			origin: level.filepath
 		}))
 	};
+	const interpolated = interpolate(result.right, env);
 	return {
 		layer: {
 			origin: level.filepath,
 			dir: dirname(level.filepath),
-			value: result.right
+			value: interpolated.value
 		},
-		diagnostics: []
+		diagnostics: interpolated.diagnostics.map((d) => ({
+			...d,
+			origin: level.filepath
+		}))
 	};
 });
+/** 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, decodeLevel);
-	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),
 		catch: (e) => new GtdError(`gtd config:\n  - ${module?.filepath ?? "(built-in default)"}: ${e instanceof Error ? e.message : String(e)}`)
 	});
 	const layerOrder = [...levels.map((level) => level.filepath), ...module ? [module.filepath] : []];
-	const diagnostics = dedupeDiagnostics(sortDiagnostics([...decodeDiagnostics, ...compiled.diagnostics], 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));
+	const knownSkillNames = Object.keys(loaded.skills).sort();
+	const unknownSkillDiagnostics = compiled.skillsKeys.filter(({ key }) => !Object.hasOwn(loaded.skills, key)).map(({ key, origin }) => ({
+		severity: "error",
+		path: ["skills", key],
+		message: `"skills.${key}" names a step this workflow does not declare — known step names: ${knownSkillNames.join(", ")}`,
+		origin
+	}));
+	const diagnostics = dedupeDiagnostics(sortDiagnostics([
+		...decodeDiagnostics,
+		...compiled.diagnostics,
+		...unknownSkillDiagnostics,
+		...wrongKindDiagnostics(loaded, compiled)
+	], layerOrder));
+	yield* failOnErrors(diagnostics);
+	const initial = yield* firstStep(loaded, headTree(yield* Workspace));
 	return {
 		workflow: {
 			flow: loaded.flow,
@@ -57793,16 +58060,36 @@ const load = gen(function* () {
 			base: loaded.base,
 			steering: loaded.steering,
 			modes: compiled.modes,
+			skills: loaded.skills,
+			configuredSkills: compiled.rcSkills,
 			initial
 		},
 		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();
@@ -57839,6 +58126,13 @@ const stringRecord = (exports, name) => {
 	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => typeof entry !== "string")) throw new Error(`the "${name}" export is not a record of strings`);
 	return value;
 };
+const isStringArray = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
+/** Read a module's optional `skills` export: full step name -> skill list, mirroring `stringRecord` for the vars-shaped exports. */
+const skillsRecord = (exports) => {
+	const value = exports["skills"] ?? {};
+	if (typeof value !== "object" || value === null || Object.values(value).some((entry) => !isStringArray(entry))) throw new Error(`the "skills" export is not a record of skill-name arrays`);
+	return value;
+};
 const optionalFunction = (exports, name) => {
 	const value = exports[name];
 	if (value === void 0) return void 0;
@@ -57847,16 +58141,26 @@ 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"),
 		base: optionalFunction(exports, "base"),
 		origin,
@@ -57901,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,
@@ -57912,6 +58247,7 @@ const replayToFirstStep = (loaded, vars, tree) => flatMap$4(promise(() => replay
 		commits: []
 	},
 	vars,
+	env,
 	start: "",
 	budgetBytes: Number.MAX_SAFE_INTEGER
 })), (outcome) => {
@@ -57922,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`));
 });
@@ -57940,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
@@ -58244,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
@@ -63596,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: {
@@ -63752,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.
@@ -63772,9 +64154,12 @@ 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,
+	skills: setup.def.skills,
+	configuredSkills: setup.def.configuredSkills,
 	...pending !== void 0 ? { pending } : {}
 });
 const replayError = (outcome) => {
@@ -63912,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))
@@ -63935,6 +64320,7 @@ const restAt = (ref) => gen(function* () {
 		def,
 		run,
 		vars,
+		env,
 		budget,
 		workspace,
 		base,
@@ -63962,6 +64348,7 @@ const restAt = (ref) => gen(function* () {
 		trace: outcome.trace,
 		run,
 		vars,
+		env,
 		changes,
 		memory: memory.key,
 		memoryResumed: memory.resumed,
@@ -63982,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,
@@ -63995,8 +64382,11 @@ const entryRefusal = (rest, name, entryVars) => gen(function* () {
 			commits: []
 		},
 		vars,
+		env,
 		start: "",
-		budgetBytes: rest.setup.budget
+		budgetBytes: rest.setup.budget,
+		skills: rest.def.skills,
+		configuredSkills: rest.def.configuredSkills
 	}));
 	if (outcome.kind === "refused") return outcome.message;
 	if (outcome.kind === "rest") return outcome.entryRead ? void 0 : `"${name}" is not an enterable state — this workflow reads no entry`;
@@ -64045,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,
@@ -64074,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)));
@@ -64109,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
@@ -64208,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.
 */
@@ -64223,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)}`)
@@ -64250,7 +64669,7 @@ const planEntry = (current, actor, entry) => gen(function* () {
 					actor,
 					to: name,
 					...base !== void 0 ? { reviewBase: base } : {},
-					vars: varOverrides
+					vars
 				})
 			}
 		}, {
@@ -76836,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,
@@ -77407,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",
@@ -77441,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",
@@ -77470,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);
@@ -77480,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)"
 		]
 	},
 	{
@@ -77555,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",
@@ -77800,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"
 		]