@sous-io/sous 0.1.1 → 0.2.0

package/src/lib/settings.ts

@@ -2,23 +2,33 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
 import { inferGlobBase, type CompilationConfig, type CompilationTarget, type ResolvedRuntimeContext } from "./markdown-compiler.js";
-import { buildAliasMap, type AliasMap } from "./include-resolver.js";
-import { ENV_DEFAULTS_NAME, ENV_LOCAL_NAME, SOUS_DIR_NAME } from "./config-discovery.js";
+import { buildAliasMap, resolveAliasPrefix, type AliasMap } from "./include-resolver.js";
+import {
+  CONFD_DIR_NAME,
+  ENV_DEFAULTS_NAME,
+  ENV_LOCAL_NAME,
+  SOUS_DIR_NAME,
+  type DiscoveredConfig,
+} from "./config-discovery.js";
+import { ConfigError } from "./errors.js";
+import { resolveSousHome } from "./sous-home.js";
+import { validateSettings } from "./config-schema.js";
+import { applyRepoDefaults } from "./repos/defaults.js";
+import type { RecipeConfigLayer } from "./repos/recipe-config-layers.js";
 import { warning } from "../utils/formatting.js";
 
-const __filename = fileURLToPath(import.meta.url);
+// Re-exported for backwards compatibility: ConfigError moved to ./errors.ts so
+// config-discovery.ts can throw it without importing this module (cycle).
+export { ConfigError, isConfigError } from "./errors.js";
 
-/** Resolved path to the cli/ package root (two levels up from src/lib/) */
-export const CLI_ROOT = path.resolve(path.dirname(__filename), "../..");
-
-/** Version string read from package.json at module load time. */
-const _pkgJson = JSON.parse(
-  fs.readFileSync(path.join(CLI_ROOT, "package.json"), "utf8")
-) as { version: string };
-export const SOUS_VERSION: string = _pkgJson.version;
+// CLI_ROOT and SOUS_VERSION live in their own module so that modules this one
+// imports can read them without importing this one back. Re-exported here under
+// the names everything already uses.
+import { CLI_ROOT, SOUS_VERSION } from "./package-info.js";
+export { CLI_ROOT, SOUS_VERSION };
 
 // --- Variable scope ------------------------------------------------------------------------------
 
@@ -70,6 +80,88 @@ type RawProjectCompilation = {
   targets: RawTarget[];
 };
 
+/**
+ * One trusted repository, keyed in `Settings.repos` by the short name refs use
+ * in their `repo:` qualifier. Adding a repo is what trusts it.
+ */
+export type RepoEntry = {
+  /** Where the repository lives. */
+  url: string;
+  /**
+   * Whether the repository takes part in anything. Defaults to true; setting it
+   * to false is how a project opts out of a repository sous provides itself,
+   * without deleting an entry it does not own.
+   */
+  enabled?: boolean;
+  /**
+   * Which provider handles it. Inferred from the URL when omitted. `local` is a
+   * repository on this machine, for local development and tests.
+   */
+  provider?: "github" | "gitlab" | "local";
+  /** Install a newer in-range version whenever one exists, rather than holding the lock. */
+  alwaysPull?: boolean;
+  /** When the repo was added. */
+  addedAt?: string;
+  /** Who required it: "user", or the ref of the recipe whose dependency pulled it in. */
+  addedBy?: string;
+};
+
+/**
+ * One subscription, keyed in `Settings.subscriptions` by a ref key: a bare
+ * namespace, or `namespace/recipe`.
+ */
+export type SubscriptionEntry = {
+  /**
+   * Whether the subscription takes part in anything. Defaults to true; setting
+   * it to false is how a project opts out of the `core` namespace sous
+   * subscribes it to.
+   */
+  enabled?: boolean;
+  /** The semantic version range to resolve within. Defaults to "*". */
+  range?: string;
+  /** Let prerelease versions take part in range matching. */
+  prerelease?: boolean;
+  /** Per-subscription form of the repo-level always-pull flag. */
+  alwaysPull?: boolean;
+  /** When the subscription was added. */
+  addedAt?: string;
+  /** Who required it: "user", or the ref of the recipe that co-subscribed it. */
+  addedBy?: string;
+};
+
+/**
+ * Knobs for the machine-wide recipe store. Defaults are applied by the store
+ * itself, not here; see config-schema.ts for the values sous ships.
+ */
+type StoreConfig = {
+  /** Size cap, past which least-recently-used entries are collected. */
+  maxBytes?: number;
+  /** How long a fetched index stays fresh before sous re-checks upstream. */
+  freshnessSeconds?: number;
+  /** How often watch mode polls upstream. */
+  watchPollSeconds?: number;
+};
+
+/**
+ * Where the files a subscribed recipe contributes are written, one list of
+ * destination directories per content kind. Each destination is `${var}`
+ * substituted like any other config path, and a kind may name several so the
+ * same recipe feeds more than one agent directory.
+ *
+ * Only `skills` has a default (`<project root>/.claude/skills`, the project root
+ * being the parent of `.sous/`). A kind with no destination is skipped, with one
+ * warning naming this config key, because sous cannot guess where a project
+ * wants its memories or its prompts.
+ */
+type RecipeOutputs = {
+  /** Where recipe skill bundles are written. */
+  skills?: string[];
+  /** Where recipe memory files are written. */
+  memories?: string[];
+  /** Where recipe prompt files are written. */
+  prompts?: string[];
+};
+
 /** Configuration for a launchable tool (e.g. claude, codex). */
 type ToolConfig = {
   /** The executable command to run. */
@@ -83,72 +175,139 @@ type ToolConfig = {
   promptFile?: string;
 };
 
-export type RawProject = {
+export type Settings = {
+  /** Config schema version. Optional; when present must be 1 (validated at load). */
+  version?: number;
+  _env?: Record<string, string>;
   /**
-   * Project-level variables. A few names are read by Sous itself:
+   * Config variables. A few names are read by Sous itself:
    * `stateFilePath` overrides where the build state file is written (see
    * StateService.getFilePath), and `pidFilePath` does the same for the watcher
-   * PID file. Both resolve through the PROJECT scope.
+   * PID file. Both resolve through the settings scope.
    */
   _vars?: Record<string, string>;
   _aliases?: Record<string, string | string[]>;
-  name: string;
+  /** Optional display name for the configured project. */
+  name?: string;
   compilation?: RawProjectCompilation;
   runtimeContext?: RawRuntimeContext;
   tools?: Record<string, ToolConfig>;
+  /** Trusted repositories, keyed by the short name refs use. */
+  repos?: Record<string, RepoEntry>;
+  /** Subscriptions, keyed by ref key (`namespace` or `namespace/recipe`). */
+  subscriptions?: Record<string, SubscriptionEntry>;
+  /** Knobs for the machine-wide recipe store. */
+  store?: StoreConfig;
+  /**
+   * Where the files subscribed recipes contribute are written, per content kind.
+   */
+  recipeOutputs?: RecipeOutputs;
+  /**
+   * Variable mapping records, keyed by environment variable name, each bound to
+   * one recipe variable written as `namespace/recipe/variableName` with an
+   * optional `repo:` qualifier. The top rung of the answer resolution ladder.
+   */
+  varMappings?: Record<string, string>;
 };
 
-export type Settings = {
-  _env?: Record<string, string>;
-  _vars?: Record<string, string>;
-  _aliases?: Record<string, string | string[]>;
-  defaultProject?: string;
-  projects: Record<string, RawProject>;
+// --- Loader -------------------------------------------------------------------------------------
+
+/** Options accepted by loadSettings / loadSettingsWithLayers. */
+export type LoadSettingsOptions = {
+  /**
+   * When true, the kernel returns one cumulative-config snapshot per top-level
+   * layer (the provenance seam behind `sous config get --layers`).
+   */
+  trace?: boolean;
 };
 
-// --- Loader -------------------------------------------------------------------------------------
+/** One trace-mode snapshot: the cumulative config AFTER `path` was merged. */
+export type SettingsLayer = {
+  path: string;
+  config: unknown;
+};
+
+/** Absolute path to the config kernel subprocess entry (plain .mjs, ships in src/). */
+const CONFIG_KERNEL_PATH = path.join(CLI_ROOT, "src", "lib", "config-kernel.mjs");
 
 /**
- * Loads settings from the given config file path.
- * Supports .js / .mjs (ES module with a `config` or `default` export)
- * and .json (plain JSON matching the Settings shape).
+ * Loads settings from a discovered config (primary file + conf.d layers) and
+ * returns the merged result together with any trace-mode layer snapshots.
  *
- * A JS/MJS config is imported in a FRESH Node subprocess that serialises it to
- * JSON. Two attempts are made, in this order:
+ * Every layer — .js, .mjs, .json and .yaml alike — is loaded by ONE kernel
+ * subprocess (src/lib/config-kernel.mjs), which parses/imports each file in
+ * order, JSON-forces it, deep-merges it into a live cumulative config, runs
+ * `configure(currentConfig, builder)` exports, and serialises the final JSON
+ * once. Uniform kernel semantics beat the spawn cost, so there is no
+ * parent-side shortcut for plain JSON.
+ *
+ * Two spawn attempts are made, in this order:
  *
  *   1. Plain Node, no loader. This is what a normal ESM config needs, and it is
  *      the only thing that works for a `.sous/sous.config.js` sitting in a repo
  *      whose package.json has no `"type": "module"` (under the tsx loader such a
  *      file is treated as CJS and dies with ERR_REQUIRE_CYCLE_MODULE).
  *   2. The tsx loader, so a config may use TypeScript syntax and extensionless
- *      relative imports.
+ *      relative imports. (The kernel itself is plain .mjs and runs under both.)
  *
  * The subprocess (rather than a direct `import()`) avoids the require(esm) cycle
- * that tsx triggers in the parent process. Because the result is round-tripped
+ * that tsx triggers in the parent process. Because every layer is round-tripped
  * through JSON, functions, RegExp, Date and undefined values are dropped.
+ *
+ * @param source - The full DiscoveredConfig, or a bare config file path. A bare
+ *   string means exactly that one file: no conf.d scan is performed (back-compat
+ *   for tests and direct callers).
+ * @param options - `{ trace }` — see LoadSettingsOptions.
  */
-/* c8 ignore next 60 */
-export async function loadSettings(configPath: string): Promise<Settings> {
+/* c8 ignore next 75 */
+export async function loadSettingsWithLayers(
+  source: DiscoveredConfig | string,
+  options: LoadSettingsOptions = {}
+): Promise<{ settings: Settings; layers: SettingsLayer[] }> {
+  let configPath: string;
+  let sousDir: string;
+  let confDir: string;
+  let layerPaths: string[];
+  let recipeLayers: RecipeConfigLayer[];
+
+  if (typeof source === "string") {
+    configPath = path.resolve(source);
+    sousDir = path.dirname(configPath);
+    confDir = path.join(sousDir, CONFD_DIR_NAME);
+    layerPaths = [configPath];
+    recipeLayers = [];
+  } else {
+    ({ configPath, sousDir, confDir, layerPaths } = source);
+    recipeLayers = source.recipeLayers ?? [];
+  }
+
   if (!fs.existsSync(configPath)) {
     throw new Error(`Settings file not found: ${configPath}`);
   }
 
-  if (configPath.endsWith(".json")) {
-    try {
-      const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
-      return raw as Settings;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to parse settings JSON at ${configPath}: ${message}`);
-    }
-  }
+  // A recipe layer is handed to the kernel as content, not as a path, because
+  // it has already been read and filtered down to the keys a recipe may set
+  // (see `repos/recipe-config-layers.ts`). The kernel never opens the file, so
+  // there is no second, unfiltered reading of it.
+  const recipeLayerByPath = new Map(recipeLayers.map((layer) => [layer.path, layer]));
+  const sources = layerPaths.map((layerPath) => {
+    const recipeLayer = recipeLayerByPath.get(layerPath);
+    if (recipeLayer === undefined) return layerPath;
+    return { path: recipeLayer.path, config: recipeLayer.config };
+  });
+
+  const kernelInput = JSON.stringify({
+    sources,
+    context: {
+      sousDir,
+      confDir,
+      sousRootPath: CLI_ROOT,
+      sousVersion: SOUS_VERSION,
+      configPath,
+    },
+    trace: options.trace === true,
+  });
 
-  const settingsUrl = pathToFileURL(configPath).href;
-  const loaderScript = `
-    const mod = await import(${JSON.stringify(settingsUrl)});
-    const raw = mod.config ?? mod.default ?? mod;
-    process.stdout.write(JSON.stringify(raw));
-  `;
   // Resolve tsx via module resolution so this works when npm hoists the
   // dependency (local install, npx) as well as when it nests it (global,
   // repo clone).
@@ -160,67 +319,119 @@ export async function loadSettings(configPath: string): Promise<Settings> {
   }
 
   const attempts: { label: string; args: string[] }[] = [
-    { label: "node", args: ["--input-type=module"] },
-    { label: "tsx", args: ["--import", tsxPath, "--input-type=module"] },
+    { label: "node", args: [CONFIG_KERNEL_PATH] },
+    { label: "tsx", args: ["--import", tsxPath, CONFIG_KERNEL_PATH] },
   ];
 
-  const failures: string[] = [];
+  const failures: { label: string; message: string }[] = [];
 
   for (const attempt of attempts) {
     const result = spawnSync(process.execPath, attempt.args, {
-      input: loaderScript,
+      input: kernelInput,
       encoding: "utf8",
     });
 
     if (result.status === 0) {
+      let parsed: { config: unknown; layers?: SettingsLayer[] };
       try {
-        return JSON.parse(result.stdout) as Settings;
+        parsed = JSON.parse(result.stdout) as { config: unknown; layers?: SettingsLayer[] };
       } catch {
         throw new Error(
-          `Config at ${configPath} did not produce valid JSON. It must export a plain ` +
-            `object (as \`config\` or \`default\`).\n  Got: ${result.stdout.slice(0, 300)}`
+          `Config at ${configPath} did not produce valid JSON. Every layer must resolve ` +
+            `to a plain object (a \`config\`/default export, or a \`configure\` function).\n` +
+            `  Got: ${result.stdout.slice(0, 300)}`
         );
       }
+      // assertFlatConfig runs FIRST: its multi-project migration message is more
+      // actionable than a generic unknown-key error. validateSettings then checks
+      // the MERGED config against the zod schema (version, strict keys, shapes).
+      const flat = assertFlatConfig(parsed.config, configPath);
+      // The built-in repository and the implicit `core` subscription are added
+      // UNDER whatever the layers produced, and BEFORE validation, so that the
+      // shortest opt-out a project can write (`{ enabled: false }`) is a
+      // complete, valid entry once the built-in fields are underneath it. See
+      // `repos/defaults.ts`.
+      return {
+        settings: validateSettings(applyRepoDefaults(flat), configPath),
+        layers: parsed.layers ?? [],
+      };
     }
 
-    failures.push(`  [via ${attempt.label}] ${result.stderr?.trim() || "unknown error"}`);
+    failures.push({ label: attempt.label, message: result.stderr?.trim() || "unknown error" });
   }
 
-  throw new Error(`Failed to load config from ${configPath}\n${failures.join("\n\n")}`);
+  // Kernel-side errors (bad JSON/YAML, old schema, configure() throw, cycle,
+  // bad builder var, non-object layer) are raised inside the .mjs kernel, which
+  // runs identically under both the `node` and `tsx` attempts — so both stderrs
+  // are the same. Collapse identical messages so a single config error is not
+  // printed twice as if it were two distinct failures.
+  //
+  // The tsx attempt re-imports an ESM `.js` config that the `node` attempt
+  // already loaded and reported a real error for; on the tsx attempt this
+  // surfaces as a spurious "Cannot require() ES Module … in a cycle"
+  // (ERR_REQUIRE_CYCLE_MODULE) that is never a real user-config problem. Drop it
+  // whenever another attempt produced a genuine error, so the real message is
+  // not buried under an unrelated require(esm)-cycle warning.
+  const isTsxCycleArtifact = (message: string): boolean =>
+    /ERR_REQUIRE_CYCLE_MODULE/.test(message) ||
+    /Cannot require\(\) ES Module .* in a cycle/.test(message);
+  const meaningfulFailures = failures.filter((f) => !isTsxCycleArtifact(f.message));
+  const effectiveFailures = meaningfulFailures.length > 0 ? meaningfulFailures : failures;
+
+  const uniqueMessages = [...new Set(effectiveFailures.map((f) => f.message))];
+  const detail =
+    uniqueMessages.length === 1
+      ? `  ${uniqueMessages[0]}`
+      : effectiveFailures.map((f) => `  [via ${f.label}] ${f.message}`).join("\n\n");
+
+  throw new ConfigError(`Failed to load config from ${configPath}\n${detail}`);
 }
 
-// --- Variable Resolution -------------------------------------------------------------------------
-
 /**
- * Substitutes ${varName} references in a string using the provided scope.
- * Unknown variable references are left as-is.
+ * Loads the merged settings for a discovered config (or a bare config file
+ * path). Thin wrapper over loadSettingsWithLayers for callers that do not need
+ * the trace-mode layer snapshots.
  */
-export function substituteVars(str: string, scope: VarScope): string {
-  return str.replace(/\$\{([^}]+)\}/g, (match, name: string) => scope[name] ?? match);
+export async function loadSettings(
+  source: DiscoveredConfig | string,
+  options: LoadSettingsOptions = {}
+): Promise<Settings> {
+  const { settings } = await loadSettingsWithLayers(source, options);
+  return settings;
 }
 
 /**
- * A user-facing configuration error: the config file (or environment) is wrong,
- * not the CLI. Commands render these as a plain message with no stack trace,
- * since the stack points at Sous internals and tells the user nothing.
+ * Rejects configs written in the removed multi-project schema. One config now
+ * describes exactly one project; the fields that used to live inside a
+ * `projects.<key>` entry sit at the top level instead.
  */
-export class ConfigError extends Error {
-  readonly isConfigError = true;
-
-  constructor(message: string) {
-    super(message);
-    this.name = "ConfigError";
+function assertFlatConfig(raw: unknown, configPath: string): Settings {
+  if (
+    raw !== null &&
+    typeof raw === "object" &&
+    ("projects" in raw || "defaultProject" in raw)
+  ) {
+    throw new ConfigError(
+      `Config at ${configPath} uses the removed multi-project schema ` +
+        `('projects' / 'defaultProject').\n` +
+        `  A sous config now describes exactly one project. To migrate:\n` +
+        `    1. Move your single project's fields (name, _vars, _aliases, compilation,\n` +
+        `       runtimeContext, tools) to the top level of the config.\n` +
+        `    2. Delete the 'projects' and 'defaultProject' keys.\n` +
+        `  A config with several projects must be split into one config per project.`
+    );
   }
+  return raw as Settings;
 }
 
-/** True when the value is a ConfigError (safe across module instances). */
-export function isConfigError(error: unknown): boolean {
-  return (
-    error instanceof ConfigError ||
-    (typeof error === "object" &&
-      error !== null &&
-      (error as { isConfigError?: boolean }).isConfigError === true)
-  );
+// --- Variable Resolution -------------------------------------------------------------------------
+
+/**
+ * Substitutes ${varName} references in a string using the provided scope.
+ * Unknown variable references are left as-is.
+ */
+export function substituteVars(str: string, scope: VarScope): string {
+  return str.replace(/\$\{([^}]+)\}/g, (match, name: string) => scope[name] ?? match);
 }
 
 /** Returns the names of every `${var}` reference left unresolved in a string. */
@@ -258,7 +469,7 @@ export function normalizeConfigPath(value: string): string {
  * @param str - The raw value from the config.
  * @param scope - The resolved variable scope.
  * @param context - Where the value came from, e.g.
- *   `project 'foundry' → compilation.targets[0].entryPoint`. Named in the error.
+ *   `compilation.targets[0].entryPoint`. Named in the error.
  * @returns The fully substituted string.
  * @throws When one or more `${var}` references are unresolved.
  */
@@ -284,10 +495,20 @@ export function substituteVarsStrict(str: string, scope: VarScope, context: stri
 }
 
 /**
- * Resolves a _vars block into a new scope by:
- * 1. Merging the inherited scope with the block (block keys take precedence)
- * 2. Topologically sorting intra-block dependencies so vars can reference each other
- * 3. Substituting all variable references in topological order
+ * Resolves a _vars block into a new scope with a FIXPOINT loop:
+ *
+ * 1. Start from the inherited scope. Every block entry begins unresolved.
+ * 2. Each round, substitute every still-unresolved entry against the current
+ *    scope (inherited vars + entries already finalized this pass). An entry
+ *    whose `${refs}` all resolve is finalized and added to the scope.
+ * 3. Repeat until a round finalizes nothing.
+ *
+ * Because each round re-scans every unresolved entry, declaration order does not
+ * matter: `{ file: "${root}/x", root: "/data" }` resolves as readily as the
+ * reverse. When progress stops with entries still unresolved, that is a hard
+ * error (see buildUnresolvedScopeError): a `${ref}` that never resolves — a typo,
+ * a cycle, or a name defined nowhere — is a config mistake, not a literal to be
+ * passed through silently.
  */
 export function resolveScope(block: Record<string, string>, inherited: VarScope): VarScope {
   const blockKeys = Object.keys(block);
@@ -299,45 +520,158 @@ export function resolveScope(block: Record<string, string>, inherited: VarScope)
     }
   }
 
-  // Build intra-block dependency map (only deps on other block keys, not inherited)
-  const deps = new Map<string, Set<string>>();
-  for (const key of blockKeys) {
-    const refs = [...block[key].matchAll(/\$\{([^}]+)\}/g)].map(m => m[1]);
-    deps.set(key, new Set(refs.filter(r => blockKeys.includes(r))));
+  const scope: VarScope = { ...inherited };
+  const unresolved = new Set(blockKeys);
+
+  let progressed = true;
+  while (progressed && unresolved.size > 0) {
+    progressed = false;
+    for (const key of unresolved) {
+      const substituted = substituteVars(block[key], scope);
+      if (findUnresolvedVars(substituted).length === 0) {
+        scope[key] = substituted;
+        unresolved.delete(key);
+        progressed = true;
+      }
+    }
+  }
+
+  if (unresolved.size > 0) {
+    throw buildUnresolvedScopeError(block, scope, unresolved);
+  }
+
+  return scope;
+}
+
+/**
+ * Builds the ConfigError thrown when resolveScope's fixpoint stops with entries
+ * still unresolved. The message names each unresolved entry and the exact
+ * `${names}` it still needs, then separates the two failure modes: reference
+ * CYCLES (entries that depend on each other, no starting point) and UNDEFINED
+ * references (names defined nowhere). It closes with the variables that ARE in
+ * scope, so a typo is obvious at a glance.
+ *
+ * @param block - The raw _vars block being resolved.
+ * @param scope - The working scope (inherited vars + every entry that DID
+ *   resolve); its keys are the "in scope" list.
+ * @param unresolved - The block keys that never resolved.
+ */
+function buildUnresolvedScopeError(
+  block: Record<string, string>,
+  scope: VarScope,
+  unresolved: Set<string>
+): ConfigError {
+  // For each unresolved entry, the ${names} still missing after fixpoint. Every
+  // such name is either another unresolved block key (an intra-block edge) or a
+  // name defined nowhere (resolvable block keys and inherited vars are already
+  // in `scope`, so they never appear here).
+  const needs = new Map<string, string[]>();
+  for (const key of unresolved) {
+    needs.set(key, findUnresolvedVars(substituteVars(block[key], scope)));
+  }
+
+  // Dependency graph among unresolved entries: u -> v when u still needs the
+  // still-unresolved block key v. SCCs of this graph are the reference cycles.
+  const edges = new Map<string, string[]>();
+  for (const key of unresolved) {
+    edges.set(key, (needs.get(key) ?? []).filter((n) => unresolved.has(n)));
+  }
+  const cycles = findCycles([...unresolved], edges);
+
+  // Undefined references: needed names that are not block keys at all.
+  const undefinedRefs = new Map<string, string[]>();
+  for (const key of unresolved) {
+    for (const name of needs.get(key) ?? []) {
+      if (!unresolved.has(name)) {
+        const referrers = undefinedRefs.get(name) ?? [];
+        referrers.push(key);
+        undefinedRefs.set(name, referrers);
+      }
+    }
+  }
+
+  const lines: string[] = [
+    "Unresolved variables after fixpoint resolution of a _vars block:",
+  ];
+  for (const key of [...unresolved].sort()) {
+    const names = (needs.get(key) ?? []).map((n) => `\${${n}}`).join(", ");
+    lines.push(`  - ${key} still needs ${names || "(nothing resolvable)"}`);
   }
 
-  // Topological sort (DFS with cycle guard)
-  const sorted: string[] = [];
-  const visited = new Set<string>();
-  const visiting = new Set<string>();
-
-  function visit(key: string): void {
-    if (visited.has(key)) return;
-    if (visiting.has(key)) {
-      // Circular dep — add as-is to avoid infinite loop
-      sorted.push(key);
-      return;
+  if (cycles.length > 0) {
+    lines.push("");
+    lines.push("Reference cycles (these variables reference each other):");
+    for (const cycle of cycles) {
+      const sorted = [...cycle].sort();
+      lines.push(`  - ${[...sorted, sorted[0]].join(" -> ")}`);
     }
-    visiting.add(key);
-    for (const dep of deps.get(key) ?? []) {
-      visit(dep);
+  }
+
+  if (undefinedRefs.size > 0) {
+    lines.push("");
+    lines.push("Undefined references (names defined nowhere — no _vars, _env, or auto-var):");
+    for (const name of [...undefinedRefs.keys()].sort()) {
+      const referrers = [...new Set(undefinedRefs.get(name) ?? [])].sort();
+      lines.push(`  - \${${name}} (needed by ${referrers.join(", ")})`);
     }
-    visiting.delete(key);
-    visited.add(key);
-    sorted.push(key);
   }
 
-  for (const key of blockKeys) {
-    visit(key);
+  const inScope = Object.keys(scope).sort();
+  lines.push("");
+  lines.push(`Variables in scope here: ${inScope.length > 0 ? inScope.join(", ") : "(none)"}`);
+
+  return new ConfigError(lines.join("\n"));
+}
+
+/**
+ * Finds reference cycles in a directed graph via Tarjan's strongly-connected-
+ * component algorithm. A cycle is an SCC with more than one member, or a single
+ * node that references itself. Returns each cycle as its member list.
+ */
+function findCycles(nodes: string[], edges: Map<string, string[]>): string[][] {
+  const index = new Map<string, number>();
+  const low = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const sccs: string[][] = [];
+  let counter = 0;
+
+  function strongconnect(v: string): void {
+    index.set(v, counter);
+    low.set(v, counter);
+    counter++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of edges.get(v) ?? []) {
+      if (!index.has(w)) {
+        strongconnect(w);
+        low.set(v, Math.min(low.get(v)!, low.get(w)!));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v)!, index.get(w)!));
+      }
+    }
+
+    if (low.get(v) === index.get(v)) {
+      const component: string[] = [];
+      let w: string;
+      do {
+        w = stack.pop()!;
+        onStack.delete(w);
+        component.push(w);
+      } while (w !== v);
+      sccs.push(component);
+    }
   }
 
-  // Resolve in topological order, starting from the inherited scope
-  const scope: VarScope = { ...inherited };
-  for (const key of sorted) {
-    scope[key] = substituteVars(block[key], scope);
+  for (const v of nodes) {
+    if (!index.has(v)) strongconnect(v);
   }
 
-  return scope;
+  return sccs.filter(
+    (component) =>
+      component.length > 1 || (edges.get(component[0]) ?? []).includes(component[0])
+  );
 }
 
 /**
@@ -348,8 +682,12 @@ export function resolveScope(block: Record<string, string>, inherited: VarScope)
 export type ConfigContext = {
   /** Absolute path to the `.sous/` directory holding the config. */
   sousDir: string;
-  /** Absolute path to the config file itself. */
+  /** Absolute path to the primary config file itself. */
   configPath: string;
+  /** Absolute path to the `conf.d/` drop-in directory (may not exist). */
+  confDir?: string;
+  /** Ordered absolute paths of every loaded config layer (primary first). */
+  layerPaths?: string[];
 };
 
 /**
@@ -357,18 +695,26 @@ export type ConfigContext = {
  * and injected first, before _env and _vars.
  * The 'sous*' namespace is reserved — warns if user defines a var starting with 'sous'.
  *
+ * `sousHome` is resolved from `process.env` on every call rather than captured
+ * once, because `SOUS_HOME` is file-settable: `.sous/.env.local` and
+ * `.sous/.env` are loaded into `process.env` before settings resolve.
+ *
  * @param context - The discovered config location. When supplied, adds
- *   `sousDir` and `sousConfigPath` so configs can build paths relative to
- *   their own `.sous/` directory.
+ *   `sousDir` and `sousConfigPath` (plus `sousConfDir` when known) so configs
+ *   can build paths relative to their own `.sous/` directory.
  */
 export function buildAutoVars(context?: ConfigContext): VarScope {
   return {
     sousRootPath: CLI_ROOT,
     sousVersion: SOUS_VERSION,
+    sousHome: resolveSousHome(),
     ...(context !== undefined && {
       sousDir: context.sousDir,
       sousConfigPath: context.configPath,
     }),
+    ...(context?.confDir !== undefined && {
+      sousConfDir: context.confDir,
+    }),
   };
 }
 
@@ -428,39 +774,36 @@ export function resolveRootScope(settings: Settings, context?: ConfigContext): V
 /**
  * Built-in `@include` aliases, always available and reserved (their names begin
  * with `~` so user `_aliases` can never shadow them). Add new entries here as
- * needed — keep names kebab-case.
+ * needed; keep names kebab-case.
  *
- * - `~sous-shared` → the Sous CLI's `shared-prompts` directory (the only dir
- *   downstream projects consume; path into it, e.g. `@~sous-shared/skills/...`).
- * - `~project`     → the consuming project's root (`projectRoot`).
+ * - `~project` → the consuming project's root (`projectRoot`).
+ *
+ * There is exactly one, on purpose. Files that used to be reached through a
+ * built-in alias pointing inside the sous package are published as recipes now,
+ * and a recipe's files are addressed by its namespace (`@~workflow/task-files/
+ * _partials/resume-task.md`), resolved against what the project has pinned. A
+ * `~namespace` reference is NOT an alias: it is resolved separately, after the
+ * alias map has been tried; see `locked-namespace-resolver.ts`.
  */
 export function buildBuiltInAliases(scope: VarScope): AliasMap {
-  const sousRoot = scope.sousRootPath ?? CLI_ROOT;
-  const builtIns: AliasMap = {
-    "~sous-shared": [path.join(sousRoot, "shared-prompts")],
-  };
+  const builtIns: AliasMap = {};
   if (scope.projectRoot) builtIns["~project"] = [scope.projectRoot];
   return builtIns;
 }
 
 /**
- * Resolve the full `@include` alias map for a project: built-ins, then root
- * `_aliases`, then project `_aliases` (later prepends to earlier so user entries
- * are tried first and fall through to built-in bases). User alias names starting
+ * Resolve the full `@include` alias map: built-ins, then the config's
+ * `_aliases` block (user entries prepend, so they are tried first and fall
+ * through to built-in bases of the same name). User alias names starting
  * with `~` are rejected (reserved).
  *
- * @param settings - The root settings (for root-level `_aliases`).
- * @param project - The project (for project-level `_aliases`).
- * @param scope - The resolved project scope (for ${var} substitution + projectRoot).
+ * @param settings - The loaded settings (for the `_aliases` block).
+ * @param scope - The resolved settings scope (for ${var} substitution + projectRoot).
  */
-export function resolveAliases(
-  settings: Settings,
-  project: RawProject,
-  scope: VarScope
-): AliasMap {
+export function resolveAliases(settings: Settings, scope: VarScope): AliasMap {
   return buildAliasMap({
     builtIns: buildBuiltInAliases(scope),
-    userAliases: [settings._aliases, project._aliases],
+    userAliases: [settings._aliases],
     scope,
     onError: warning,
   });
@@ -474,20 +817,20 @@ export type ResolvedToolConfig = {
 };
 
 /**
- * Resolves a project's tools config, substituting vars in promptFile paths.
+ * Resolves the config's tools block, substituting vars in promptFile paths.
  * Returns an empty object if no tools are configured.
+ *
+ * @param settings - The loaded settings.
+ * @param scope - The resolved settings scope (from resolveRootScope).
  */
-export function resolveProjectTools(
-  project: RawProject,
-  rootScope: VarScope = {},
-  projectKey = project.name
+export function resolveTools(
+  settings: Settings,
+  scope: VarScope = {}
 ): Record<string, ResolvedToolConfig> {
-  if (!project.tools) return {};
-
-  const projectScope = resolveScope(project._vars ?? {}, rootScope);
+  if (!settings.tools) return {};
 
   return Object.fromEntries(
-    Object.entries(project.tools).map(([name, tool]) => [
+    Object.entries(settings.tools).map(([name, tool]) => [
       name,
       {
         command: tool.command,
@@ -495,8 +838,8 @@ export function resolveProjectTools(
         ...(tool.promptFile !== undefined && {
           promptFile: substituteVarsStrict(
             tool.promptFile,
-            projectScope,
-            `project '${projectKey}' → tools.${name}.promptFile`
+            scope,
+            `tools.${name}.promptFile`
           ),
         }),
       },
@@ -524,30 +867,27 @@ function resolveRuntimeContext(
 }
 
 /**
- * Resolves a project's compilation config into the shape the compiler expects.
- * Walks the config tree resolving _vars at each level (root → project → target → output).
- * Pass rootScope from resolveRootScope(settings) to thread root vars down.
- * Returns null if the project has no compilation config.
+ * Resolves the config's compilation block into the shape the compiler expects.
+ * Walks the config tree resolving _vars at each level (settings → compilation → target → output).
+ * Pass scope from resolveRootScope(settings) to thread the settings vars down.
+ * Returns null if the config has no compilation block.
  */
-export function resolveProjectCompilation(
-  project: RawProject,
-  rootScope: VarScope = {},
-  settings: Settings = { projects: {} },
-  projectKey = project.name
+export function resolveCompilation(
+  settings: Settings,
+  scope: VarScope = {}
 ): CompilationConfig | null {
-  if (!project.compilation) return null;
+  if (!settings.compilation) return null;
 
-  const projectScope = resolveScope(project._vars ?? {}, rootScope);
-  const compilationScope = resolveScope(project.compilation._vars ?? {}, projectScope);
-  const aliases = resolveAliases(settings, project, projectScope);
+  const compilationScope = resolveScope(settings.compilation._vars ?? {}, scope);
+  const aliases = resolveAliases(settings, scope);
 
   return {
-    includeSourceComments: project.compilation.includeSourceComments,
+    includeSourceComments: settings.compilation.includeSourceComments,
     aliases,
-    includeScope: projectScope,
-    targets: project.compilation.targets.flatMap((target, targetIndex): CompilationTarget[] => {
+    includeScope: scope,
+    targets: settings.compilation.targets.flatMap((target, targetIndex): CompilationTarget[] => {
       const targetScope = resolveScope(target._vars ?? {}, compilationScope);
-      const where = `project '${projectKey}' → compilation.targets[${targetIndex}]`;
+      const where = `compilation.targets[${targetIndex}]`;
       const hasSingle = target.entryPoint !== undefined;
       const hasGlob = target.entryGlob !== undefined;
 
@@ -600,12 +940,8 @@ export function resolveProjectCompilation(
 
       if (hasSingle) {
         const runtimeContext =
-          target.generateRuntimeContext && project.runtimeContext
-            ? resolveRuntimeContext(
-                project.runtimeContext,
-                projectScope,
-                `project '${projectKey}' → runtimeContext`
-              )
+          target.generateRuntimeContext && settings.runtimeContext
+            ? resolveRuntimeContext(settings.runtimeContext, scope, "runtimeContext")
             : undefined;
         return [{
           rootInputPath: normalizeConfigPath(
@@ -617,13 +953,26 @@ export function resolveProjectCompilation(
       }
 
       /* c8 ignore start */
-      // Glob target: expand pattern into one CompilationTarget per matched file, skipping dirs
-      const pattern = substituteVarsStrict(target.entryGlob!, targetScope, `${where}.entryGlob`);
-      const matchedFiles = globSync(pattern, { absolute: true })
-        .filter(filePath => fs.statSync(filePath).isFile());
+      // Glob target: expand pattern into one CompilationTarget per matched file, skipping dirs.
+      // A leading alias (`~project/skills/**`) expands to one candidate pattern per alias
+      // base; the first base that matches any files wins, mirroring the first-existing-wins
+      // rule of @include resolution.
+      const rawPattern = substituteVarsStrict(target.entryGlob!, targetScope, `${where}.entryGlob`);
+      const patternCandidates = resolveAliasPrefix(rawPattern, aliases);
+      let pattern = patternCandidates[0];
+      let matchedFiles: string[] = [];
+      for (const candidate of patternCandidates) {
+        const matches = globSync(candidate, { absolute: true })
+          .filter(filePath => fs.statSync(filePath).isFile());
+        if (matches.length > 0) {
+          pattern = candidate;
+          matchedFiles = matches;
+          break;
+        }
+      }
 
       if (matchedFiles.length === 0) {
-        warning(`Glob pattern matched no files:\n${pattern}`);
+        warning(`Glob pattern matched no files:\n${patternCandidates.join("\n")}`);
       }
 
       const globBase = normalizeConfigPath(
@@ -658,33 +1007,41 @@ export type WatchConfig = {
 };
 
 /**
- * Returns the watch configuration for a project's compilation targets.
+ * Returns the watch configuration for the config's compilation targets.
  *
  * - entryPoint targets → exact file path in `files`.
  * - entryGlob targets → resolved glob string in `globs`.
+ *
+ * Alias prefixes in entryGlob patterns are expanded (every base of the alias
+ * is watched, matching compile's fall-through resolution).
  */
-export function resolveWatchConfig(
-  project: RawProject,
-  rootScope: VarScope = {},
-  projectKey = project.name
-): WatchConfig {
-  if (!project.compilation) return { files: [], globs: [] };
-
-  const projectScope = resolveScope(project._vars ?? {}, rootScope);
-  const compilationScope = resolveScope(project.compilation._vars ?? {}, projectScope);
+export function resolveWatchConfig(settings: Settings, scope: VarScope = {}): WatchConfig {
+  if (!settings.compilation) return { files: [], globs: [] };
+
+  const compilationScope = resolveScope(settings.compilation._vars ?? {}, scope);
+  const aliases = resolveAliases(settings, scope);
   const files: string[] = [];
   const globs: string[] = [];
 
-  for (const [targetIndex, target] of project.compilation.targets.entries()) {
+  for (const [targetIndex, target] of settings.compilation.targets.entries()) {
     const targetScope = resolveScope(target._vars ?? {}, compilationScope);
-    const where = `project '${projectKey}' → compilation.targets[${targetIndex}]`;
+    const where = `compilation.targets[${targetIndex}]`;
 
     if (target.entryPoint) {
-      files.push(substituteVarsStrict(target.entryPoint, targetScope, `${where}.entryPoint`));
+      // Normalize to match the compilation path (rootInputPath) and, more
+      // importantly, chokidar's change events: chokidar reports the OS-normalized
+      // path, so an unnormalized `${sousDir}/../prompts/A.md` entry would never
+      // string-match the `/prompts/A.md` event and the partial rebuild would never fire.
+      files.push(
+        normalizeConfigPath(
+          substituteVarsStrict(target.entryPoint, targetScope, `${where}.entryPoint`)
+        )
+      );
     }
 
     if (target.entryGlob) {
-      globs.push(substituteVarsStrict(target.entryGlob, targetScope, `${where}.entryGlob`));
+      const pattern = substituteVarsStrict(target.entryGlob, targetScope, `${where}.entryGlob`);
+      globs.push(...resolveAliasPrefix(pattern, aliases).map(normalizeConfigPath));
     }
   }