@gaunt-sloth/core 2.0.0-alpha.23 → 2.0.0-alpha.25

package/README.md

@@ -1,35 +1,60 @@
 # @gaunt-sloth/core
 
-Core utilities and types for Gaunt Sloth.
+The foundation layer of Gaunt Sloth: the configuration system (`GthConfig`, config discovery and
+loading, the JSON schema), the LLM provider factory (anthropic, deepseek, google-genai, groq,
+huggingface, ollama, openai, openrouter, vertexai, xai, fake), the lean LangChain agent runtime
+(`GthAgentRunner`), session history, and the shared utility modules (`consoleUtils`,
+`systemUtils`, `fileUtils`, `llmUtils`, …).
 
-## Contents
+**When to depend on this package** — you are embedding a piece of Gaunt Sloth (or building your
+own front-end on its infrastructure) and need its config resolution and provider wiring without
+the CLI. Every other `@gaunt-sloth/*` package builds on it. If you just want to use Gaunt Sloth
+from the terminal, install the [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) app
+instead.
 
-- Configuration system (`GthConfig`, `RawGthConfig`, config loading and post-processing)
-- Agent infrastructure: `GthLangChainAgent`, `GthAgentRunner`
-- LLM provider wrappers: anthropic, deepseek, google-genai, groq, openai, openrouter, vertexai, xai, fake
-- Utility modules: `consoleUtils`, `debugUtils`, `fileUtils`, `llmUtils`, `systemUtils`, `stringUtils`, `aiignoreUtils`, `binaryOutputUtils`, `vertexaiUtils`, `globalConfigUtils`, `ProgressIndicator`
-- State and artifact storage: `artifactStore`
-- Shared constants and types
+## Installation
 
-AI vendor packages are not direct dependencies. Each vendor package is an optional peer dependency, resolved at runtime by whichever consumer (e.g. `gaunt-sloth`) pulls them in.
+AI vendor packages are optional peer dependencies — install the provider(s) your configuration
+uses alongside core:
 
-## Dependencies
-
-No other `@gaunt-sloth/*` packages.
+```bash
+npm install @gaunt-sloth/core @langchain/anthropic
+```
 
-## Exports
+## Embedding: resolve config into a live model
 
-All modules are exported via the `./` export map pattern (`./*.js`), e.g.:
+I want my script to honour the user's `.gsloth.config.*` (provider, model, API keys) instead of
+hard-coding a vendor SDK. With a `.gsloth.config.json` such as
+`{ "llm": { "type": "anthropic", "model": "claude-sonnet-4-5" } }` in the working directory:
 
 ```js
-import { GthAgentRunner } from '@gaunt-sloth/core/agentRunner.js';
-import { display } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { initConfig } from '@gaunt-sloth/core';
+
+const config = await initConfig({}); // discovers .gsloth.config.* up-tree from cwd
+// config.llm is a live LangChain chat model built from that config
+const response = await config.llm.invoke('Say hello');
+console.log(response.text);
 ```
 
+All config keys (providers, prompts, tools, per-command settings) are documented in
+[the configuration guide](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/configuration/index.md).
+
+## Exports
+
+- `@gaunt-sloth/core` (the root export) is the public API: config
+  (`initConfig`, `GthConfig`, defaults), constants, core types, the lean agent factory, model
+  discovery, and session history.
+- `@gaunt-sloth/core/<path>.js` deep paths (e.g. `@gaunt-sloth/core/config.js`,
+  `@gaunt-sloth/core/utils/consoleUtils.js`) mirror the internal `dist/` layout 1:1 and are a
+  deliberate part of the contract — the other `@gaunt-sloth/*` packages and downstream consumers
+  import them directly. They are supported at your own risk: internal files can move between
+  alpha/minor versions without a deprecation cycle. Prefer the root export where it suffices.
+
+This package ships no binaries.
+
 ## Related packages
 
-- [`@gaunt-sloth/core`](https://www.npmjs.com/package/@gaunt-sloth/core) — Core utilities, config, and agent infrastructure (this package) ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/core))
 - [`@gaunt-sloth/agent`](https://www.npmjs.com/package/@gaunt-sloth/agent) — Agent runtime: built-in tools, filesystem toolkit, middleware registry, API server, AG-UI, MCP, and A2A integration ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/agent))
-- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review and Q&A modules with standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
+- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review engine with content/requirement sources (GitHub, Jira, file, text) and standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
 - [`@gaunt-sloth/batch`](https://www.npmjs.com/package/@gaunt-sloth/batch) — Batch / eval / workflow runtime ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch))
 - [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) — Main CLI application ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/app))

package/dist/config/colour.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/** Everything the colour decision depends on. See {@link resolveUseColour}. */
+export interface UseColourInput {
+    /**
+     * Raw `FORCE_COLOR` environment value; `undefined` when the variable is not set at all.
+     * The empty string is a SET value (`FORCE_COLOR=` on the command line) and means colour on.
+     */
+    forceColor?: string;
+    /** Raw `NO_COLOR` environment value; `undefined` when the variable is not set at all. */
+    noColor?: string;
+    /**
+     * `useColour` as the user actually wrote it — read from the RAW config, BEFORE `DEFAULT_CONFIG`
+     * is merged in. `undefined` means the user set nothing, which is what rung 3 tests for; after the
+     * default merge an explicit `true` is indistinguishable from the default `true`, so this value
+     * must be captured pre-merge or the rung collapses.
+     */
+    explicitUseColour?: boolean;
+    /** Whether stdout is a terminal. Rung 4's auto-detection; stdout, not stdin. */
+    stdoutIsTTY: boolean;
+}
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export declare function resolveUseColour(input: UseColourInput): boolean;

package/dist/config/colour.js

@@ -0,0 +1,36 @@
+/**
+ * CFG-30 — the single place that decides whether Gaunt Sloth emits ANSI colour.
+ *
+ * Everything this decision depends on arrives as an argument: no `process.env`, no `stdout`, no
+ * config merge. That keeps the ladder unit-testable rung by rung without touching process globals,
+ * and keeps the one mutation site ({@link setUseColour}, called from `mergeConfig`) unchanged.
+ */
+/**
+ * Resolve the effective colour setting from the four-rung precedence ladder, highest wins:
+ *
+ *   1. `FORCE_COLOR` is set — `"0"` or `"false"` turn colour OFF, ANY other value (including the
+ *      empty string) turns it ON. This rung outranks everything below it, `NO_COLOR` included.
+ *   2. `NO_COLOR` is set and non-empty — colour OFF (the no-color.org convention: the variable's
+ *      presence is the signal, its value is not, but an empty value does not count as set).
+ *   3. `useColour` was set explicitly in config — use it verbatim.
+ *   4. Otherwise auto-detect — colour ON when stdout is a terminal, OFF when it is piped or
+ *      redirected, so captured output stays clean without any configuration.
+ */
+export function resolveUseColour(input) {
+    // Rung 1 — FORCE_COLOR, the deliberate "I know what I am doing" override. Checked first so a
+    // user can force colour through a NO_COLOR inherited from their shell profile or a CI image.
+    if (input.forceColor !== undefined) {
+        return !(input.forceColor === '0' || input.forceColor === 'false');
+    }
+    // Rung 2 — NO_COLOR (no-color.org), honoured by chalk, ripgrep, fd and delta.
+    if (input.noColor !== undefined && input.noColor !== '') {
+        return false;
+    }
+    // Rung 3 — the user's own config. Only reachable with an explicit value, never the default.
+    if (input.explicitUseColour !== undefined) {
+        return input.explicitUseColour;
+    }
+    // Rung 4 — auto-detect.
+    return input.stdoutIsTTY;
+}
+//# sourceMappingURL=colour.js.map

package/dist/config/colour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colour.js","sourceRoot":"","sources":["../../src/config/colour.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,6FAA6F;IAC7F,6FAA6F;IAC7F,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,8EAA8E;IAC9E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4FAA4F;IAC5F,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC,iBAAiB,CAAC;IACjC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,CAAC,WAAW,CAAC;AAC3B,CAAC"}

package/dist/config/defaults.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @packageDocumentation
+ * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
+ * the former `config.ts` god-file; values are unchanged.
+ */
 import { StatusLevel } from '#src/core/types.js';
 /**
  * Default config
@@ -5,17 +10,10 @@ import { StatusLevel } from '#src/core/types.js';
 export declare const DEFAULT_CONFIG: {
     readonly contentSource: 'file';
     readonly requirementSource: 'file';
-    /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
-     */
-    readonly projectGuidelines: ".gsloth.guidelines.md";
     /**
      * Whether to include the current date in the project review instructions or not.
      */
     readonly includeCurrentDateAfterGuidelines: false;
-    readonly projectReviewInstructions: ".gsloth.review.md";
     readonly filesystem: 'none';
     readonly builtInTools: string[];
     readonly debugLog: false;
@@ -76,6 +74,7 @@ export declare const DEFAULT_CONFIG: {
     readonly writeOutputToFile: false;
     readonly writeBinaryOutputsToFile: true;
     readonly useColour: true;
+    readonly useMouse: true;
     readonly streamSessionInferenceLog: true;
     readonly canInterruptInferenceWithEsc: true;
     readonly aiignore: {

package/dist/config/defaults.js

@@ -3,7 +3,6 @@
  * Default Gaunt Sloth configuration ({@link DEFAULT_CONFIG}). Extracted verbatim from
  * the former `config.ts` god-file; values are unchanged.
  */
-import { PROJECT_GUIDELINES, PROJECT_REVIEW_INSTRUCTIONS } from '#src/constants.js';
 import { StatusLevel } from '#src/core/types.js';
 /**
  * Default config
@@ -11,17 +10,13 @@ import { StatusLevel } from '#src/core/types.js';
 export const DEFAULT_CONFIG = {
     contentSource: 'file',
     requirementSource: 'file',
-    /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
-     */
-    projectGuidelines: PROJECT_GUIDELINES,
+    // GS2-43: prompt segments (backstory/guidelines/system/chat/code/exec/review) are configured
+    // via the optional `prompts` object and DEFAULTED AT THE READ SITE (`readPromptSegment` falls
+    // back to each segment's default-named file), so `prompts` is intentionally absent here.
     /**
      * Whether to include the current date in the project review instructions or not.
      */
     includeCurrentDateAfterGuidelines: false,
-    projectReviewInstructions: PROJECT_REVIEW_INSTRUCTIONS,
     filesystem: 'none',
     // Enabled built-in tools. `gth_checklist` (the lean agent's planning/todo tool) and `gth_grep`
     // (the permission-light content-search tool, GS2-51) are on by default across commands; a user
@@ -87,6 +82,7 @@ export const DEFAULT_CONFIG = {
     writeOutputToFile: false,
     writeBinaryOutputsToFile: true,
     useColour: true,
+    useMouse: true,
     streamSessionInferenceLog: true,
     canInterruptInferenceWithEsc: true,
     aiignore: {

package/dist/config/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB;;;;OAIG;IACH,iBAAiB,EAAE,kBAAkB;IACrC;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,yBAAyB,EAAE,2BAA2B;IACtD,UAAU,EAAE,MAAM;IAClB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,6FAA6F;IAC7F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,CAAa;IACvD,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;IACzB,6FAA6F;IAC7F,8FAA8F;IAC9F,yFAAyF;IACzF;;OAEG;IACH,iCAAiC,EAAE,KAAK;IACxC,UAAU,EAAE,MAAM;IAClB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,6FAA6F;IAC7F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,eAAe,EAAE,UAAU,CAAa;IACvD,QAAQ,EAAE,KAAK;IACf,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,mCAAmC;IACnE;;;;;;;;OAQG;IACH,QAAQ,EAAE;QACR,EAAE,EAAE;YACF,aAAa,EAAE,QAAQ;YACvB,iBAAiB,EAAE,QAAQ;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,CAAC;gBAChB,SAAS,EAAE,CAAC;gBACZ,SAAS,EAAE,EAAE;gBACb,iBAAiB,EAAE,IAAI;aACxB;SACF;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK;SAClB;QACD,GAAG,EAAE;YACH,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,IAAI;YACV,IAAI,EAAE;gBACJ,WAAW,EAAE,uBAAuB;gBACpC,YAAY,EAAE,oBAAoB;gBAClC,YAAY,EAAE,sBAAsB;aACrC;SACF;KACF;IACD,YAAY,EAAE,IAAI;IAClB,iBAAiB,EAAE,KAAK;IACxB,wBAAwB,EAAE,IAAI;IAC9B,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,IAAI;IACd,yBAAyB,EAAE,IAAI;IAC/B,4BAA4B,EAAE,IAAI;IAClC,QAAQ,EAAE;QACR,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,SAAS;KACpB;CACO,CAAC;AAEX;;;GAGG;AACH,oEAAoE;AACpE,cAA2B,CAAC"}

package/dist/config/loader.d.ts

@@ -66,6 +66,40 @@ export declare function resolveIdentityProfileConfigPath(identityProfile: string
  * @returns The raw global config object, or `undefined` when no global config exists.
  */
 export declare function loadGlobalRawConfig(): Promise<Partial<RawGthConfig> | undefined>;
+/**
+ * GS2-41 — resolve a named profile's `extends` inheritance into a single composed raw config,
+ * riding the SAME GS2-1 deep-merge the config LAYERS use (NO second merge engine). When the given
+ * profile config declares `extends: "<base>"`, the base profile's config resolves FIRST
+ * (recursively — a base may itself extend another, so base-of-base resolves first), then this
+ * profile's own fields merge on top with last-wins semantics: the child overrides the base, nested
+ * objects merge, arrays REPLACE except the additive-array fields (`allowDirs`, `aiignore.patterns`
+ * and the three `approvals` rule lists, see {@link isAdditiveArrayField}) which accumulate
+ * base+child. The `extends` key itself is consumed and never leaks into the composed output.
+ *
+ * A config WITHOUT `extends` is returned UNCHANGED — every non-inheriting config (the vast
+ * majority) is untouched and behaves exactly as before.
+ *
+ * Composition is CONFINED to the profile-dir layer: it produces the single raw config that then
+ * acts as the project-file layer the global config underlays and CLI flags overlay, preserving
+ * GS2-33's outer precedence `CLI flags > profile (base+child composed) > global > defaults`. It is
+ * therefore invoked in {@link initConfig} on the loaded project/profile config BEFORE
+ * {@link applyGlobalConfigBase}.
+ *
+ * The base profile is discovered with {@link resolveIdentityProfileConfigPath} (the SAME strict
+ * up-tree profile walk `--profile` uses), so `extends` names a profile exactly as a user selects
+ * one; a name with no config dir is a hard, clearly-named error.
+ *
+ * CYCLE GUARD: the chain of profile NAMES is tracked (seeded with the selected profile's own name);
+ * because `extends` is single-valued the chain is linear, so a repeated name — `A extends B extends
+ * A`, or a self-extend — is an unambiguous cycle and fails fast with a clear error NAMING the cycle,
+ * never infinite-looping / stack-overflowing. A hard {@link MAX_EXTENDS_CHAIN_DEPTH} cap backstops
+ * it regardless of how the base path was derived.
+ *
+ * @param rawConfig   the just-loaded, schema-validated raw config that MAY declare `extends`.
+ * @param profileLabel the selected profile's own name (for cycle detection + messages); undefined
+ *                     for a plain (non-profile) project config.
+ */
+export declare function resolveConfigExtends(rawConfig: Record<string, unknown>, profileLabel: string | undefined): Promise<Record<string, unknown>>;
 /**
  * ORDERING INVARIANT (GS2-11): detection ({@link hasProjectConfig}/{@link hasAnyConfig}) MUST run
  * before {@link initConfig} in a given process. Both resolve cwd-level candidates via
@@ -107,11 +141,18 @@ export declare function initConfig(commandLineConfigOverrides: CommandLineConfig
 export declare function tryJsonConfig(jsonConfig: RawGthConfig, commandLineConfigOverrides: CommandLineConfigOverrides): Promise<GthConfig>;
 /**
  * Resolve a fully-merged {@link GthConfig} from a partial config + CLI overrides WITHOUT
- * any global side effects (a pure transform). It deep-merges defaults, applies CLI overrides,
- * resolves the numeric `consoleLevel` (warning + defaulting to INFO on an invalid value), and
- * computes `canInterruptInferenceWithEsc`. The process-global setters (`setUseColour` /
+ * any global side effects. It deep-merges defaults, applies CLI overrides, resolves the numeric
+ * `consoleLevel` (warning + defaulting to INFO on an invalid value), and computes
+ * `canInterruptInferenceWithEsc` and `useColour`. The process-global setters (`setUseColour` /
  * `setConsoleLevel`) are applied separately by {@link mergeConfig}, so this function can be
  * reasoned about and reused without touching global state.
+ *
+ * It WRITES nothing globally, but it does READ the environment: `canInterruptInferenceWithEsc`
+ * consults stdin's TTY status, and (CFG-30) `useColour` consults `FORCE_COLOR`, `NO_COLOR` and
+ * stdout's TTY status. So it is deterministic for a given environment rather than a pure function
+ * of its arguments — a test that pins a resolved config should declare the terminal and the colour
+ * environment it expects in its setup. The ladder itself is a pure helper
+ * ({@link resolveUseColour}) so it can be tested rung by rung without process globals.
  */
 export declare function resolveConfig(partialConfig: Omit<Partial<GthConfig>, 'consoleLevel'> & {
     consoleLevel?: ConsoleLevelInput;
@@ -165,5 +206,11 @@ export interface ConfigValidationReport {
  * global (no layer added) but is surfaced with a `displayWarning` — exactly as a run does (it
  * warns the user while ignoring the broken global's value) — see {@link
  * loadGlobalRawConfigUnvalidated}.
+ *
+ * GS2-73 — for the PROJECT layer it also walks the GS2-41 profile `extends` chain (via the SAME
+ * {@link composeExtends}/{@link resolveExtendsChain} the run path uses), so a cycle or a missing
+ * base — which fail a real run — is reported here as a not-ok layer instead of passing OK and only
+ * failing at run time. The GLOBAL layer is NOT walked, mirroring the run (`resolveConfigExtends`
+ * runs on the project/profile layer only).
  */
 export declare function validateConfig(commandLineConfigOverrides: CommandLineConfigOverrides): Promise<ConfigValidationReport>;