@cad0p/pi-steering 0.1.0 → 0.2.0

package/src/loader.test.ts

@@ -2,28 +2,30 @@
 // Part of pi-steering.
 
 /**
- * Walk-up discovery + merge tests for {@link loadConfigs},
+ * Two-layer discovery + merge tests for {@link loadConfigs},
  * {@link buildConfig}, and {@link loadSteeringConfig}.
  *
  * Uses the same scratch-HOME + `mkdtempSync` pattern as the v1 JSON
  * loader tests (`../loader.test.ts`) to keep global config leakage
- * out of the test run. Fixtures are written fresh per test so runs
- * are reproducible without repo-committed scratch files.
+ * out of the test run — the isolated `$HOME` also points the global
+ * layer at a scratch `<tmp>/.pi/agent/steering/`. Fixtures are
+ * written fresh per test so runs are reproducible without
+ * repo-committed scratch files.
  */
 
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import { useIsolatedHome } from "./__test-helpers__.ts";
 import {
-  ancestorChain,
   buildConfig,
   configCandidates,
   findConfigFile,
   loadConfigs,
   loadSteeringConfig,
+  resolveAgentDir,
 } from "./loader.ts";
 import type { Plugin, SteeringConfig } from "./schema.ts";
 
@@ -57,63 +59,46 @@ describe("loader: configCandidates", () => {
     assert.equal(a, "/tmp/x/.pi/steering/index.ts");
     assert.equal(b, "/tmp/x/.pi/steering.ts");
   });
-});
 
-describe("loader: ancestorChain", () => {
-  it("returns innermost first", () => {
-    const prior = process.env["HOME"];
-    process.env["HOME"] = "/home/user";
-    try {
-      const chain = ancestorChain("/home/user/projects/foo/bar");
-      assert.deepEqual(chain, [
-        "/home/user/projects/foo/bar",
-        "/home/user/projects/foo",
-        "/home/user/projects",
-        "/home/user",
-      ]);
-    } finally {
-      if (prior === undefined) delete process.env["HOME"];
-      else process.env["HOME"] = prior;
-    }
+  it("honors a custom slot", () => {
+    const [a, b] = configCandidates("/tmp/x", "steering");
+    assert.equal(a, "/tmp/x/steering/index.ts");
+    assert.equal(b, "/tmp/x/steering.ts");
   });
+});
 
-  it("stops at filesystem root if $HOME is unset", () => {
-    const prior = process.env["HOME"];
-    delete process.env["HOME"];
+describe("loader: resolveAgentDir", () => {
+  useIsolatedHome("pi-steering-v2-agentdir-");
+
+  it("falls back to ~/.pi/agent when PI_CODING_AGENT_DIR is unset", () => {
+    const prior = process.env["PI_CODING_AGENT_DIR"];
+    delete process.env["PI_CODING_AGENT_DIR"];
     try {
-      const chain = ancestorChain("/a/b");
-      assert.deepEqual(chain, ["/a/b", "/a", "/"]);
+      assert.equal(resolveAgentDir(), join(homedir(), ".pi", "agent"));
     } finally {
-      if (prior !== undefined) process.env["HOME"] = prior;
+      if (prior !== undefined) process.env["PI_CODING_AGENT_DIR"] = prior;
     }
   });
 
-  it("cwd === $HOME returns [$HOME] only", () => {
-    const prior = process.env["HOME"];
-    const home = mkdtempSync(join(tmpdir(), "pi-steering-v2-chain-home-"));
-    process.env["HOME"] = home;
+  it("treats an empty-string PI_CODING_AGENT_DIR as unset", () => {
+    const prior = process.env["PI_CODING_AGENT_DIR"];
+    process.env["PI_CODING_AGENT_DIR"] = "";
     try {
-      const chain = ancestorChain(home);
-      assert.deepEqual(chain, [home]);
+      assert.equal(resolveAgentDir(), join(homedir(), ".pi", "agent"));
     } finally {
-      if (prior === undefined) delete process.env["HOME"];
-      else process.env["HOME"] = prior;
-      rmSync(home, { recursive: true, force: true });
+      if (prior === undefined) delete process.env["PI_CODING_AGENT_DIR"];
+      else process.env["PI_CODING_AGENT_DIR"] = prior;
     }
   });
 
-  it("cwd OUTSIDE $HOME tree walks to filesystem root", () => {
-    const prior = process.env["HOME"];
-    process.env["HOME"] = "/home/user";
+  it("expands a bare ~ PI_CODING_AGENT_DIR to homedir", () => {
+    const prior = process.env["PI_CODING_AGENT_DIR"];
+    process.env["PI_CODING_AGENT_DIR"] = "~";
     try {
-      // cwd is in /other/path — no shared prefix with $HOME, so the
-      // walk should run to filesystem root rather than terminating
-      // at the (never-reached) $HOME sentinel.
-      const chain = ancestorChain("/other/path");
-      assert.deepEqual(chain, ["/other/path", "/other", "/"]);
+      assert.equal(resolveAgentDir(), homedir());
     } finally {
-      if (prior === undefined) delete process.env["HOME"];
-      else process.env["HOME"] = prior;
+      if (prior === undefined) delete process.env["PI_CODING_AGENT_DIR"];
+      else process.env["PI_CODING_AGENT_DIR"] = prior;
     }
   });
 });
@@ -165,10 +150,23 @@ describe("loader: findConfigFile", () => {
       /both .pi\/steering.ts and .pi\/steering\/index.ts/,
     );
   });
+
+  it("finds the global slot (steering) under the agent dir", () => {
+    writeConfig(join(tmp, "steering.ts"), configModule("{}"));
+    writeConfig(join(tmp, "steering", "index.ts"), configModule("{}"));
+    const { file, diagnostic } = findConfigFile(tmp, "steering");
+    assert.equal(file, join(tmp, "steering", "index.ts"));
+    assert.ok(
+      diagnostic,
+      "expected a coexistence diagnostic for the global slot",
+    );
+    assert.match(diagnostic.message, /steering\.ts and steering\/index\.ts/);
+  });
 });
 
 // ---------------------------------------------------------------------------
-// loadConfigs — walk-up, stray-file diagnostic, bad layer handling
+// loadConfigs — two-layer discovery, stray-file diagnostic, bad layer
+// handling
 // ---------------------------------------------------------------------------
 
 describe("loader: loadConfigs", () => {
@@ -185,24 +183,131 @@ describe("loader: loadConfigs", () => {
     assert.deepEqual(diagnostics, []);
   });
 
-  it("collects ancestor configs inner-first", async () => {
-    const outer = join(tmp, "a");
-    const inner = join(tmp, "a", "b");
-    mkdirSync(inner, { recursive: true });
+  it("loads the project layer first, then the global layer", async () => {
+    const proj = join(tmp, "proj");
+    mkdirSync(proj, { recursive: true });
     writeConfig(
-      join(outer, ".pi", "steering.ts"),
-      configModule("{ disabledRules: ['outer-only'] }"),
+      join(proj, ".pi", "steering.ts"),
+      configModule("{ disabledRules: ['project'] }"),
     );
     writeConfig(
-      join(inner, ".pi", "steering.ts"),
-      configModule("{ disabledRules: ['inner-only'] }"),
+      join(tmp, ".pi", "agent", "steering", "index.ts"),
+      configModule("{ disabledRules: ['global'] }"),
     );
-    const { layers } = await loadConfigs(inner);
-    // Inner (b) → outer (a) order.
+    const { layers } = await loadConfigs(proj);
+    // Project (inner) → global (outer) order.
     assert.deepEqual(
       layers.map((l) => l.disabledRules?.[0]),
-      ["inner-only", "outer-only"],
+      ["project", "global"],
+    );
+  });
+
+  it("does not collect intermediate ancestor layers (walk-up removed)", async () => {
+    // Pins the breaking change: a config in an ancestor directory
+    // between cwd and HOME is no longer discovered — only the cwd
+    // project layer and the agent-dir global layer load.
+    const cwd = join(tmp, "a", "b");
+    mkdirSync(cwd, { recursive: true });
+    writeConfig(
+      join(tmp, "a", ".pi", "steering.ts"),
+      configModule("{ disabledRules: ['ancestor'] }"),
+    );
+    const { layers, diagnostics } = await loadConfigs(cwd);
+    assert.deepEqual(layers, []);
+    assert.deepEqual(diagnostics, []);
+  });
+
+  it("loads legacy ~/.pi/steering/ only when cwd is home", async () => {
+    // The old global location still works in exactly one situation:
+    // launching from $HOME itself, where the project layer
+    // `<cwd>/.pi/steering/` IS the legacy `~/.pi/steering/` path.
+    const sub = join(tmp, "sub");
+    mkdirSync(sub, { recursive: true });
+    writeConfig(
+      join(tmp, ".pi", "steering.ts"),
+      configModule("{ disabledRules: ['legacy'] }"),
+    );
+    writeConfig(
+      join(tmp, ".pi", "agent", "steering", "index.ts"),
+      configModule("{ disabledRules: ['global'] }"),
+    );
+    const fromSub = await loadConfigs(sub);
+    assert.deepEqual(
+      fromSub.layers.map((l) => l.disabledRules?.[0]),
+      ["global"],
+      "legacy ~/.pi/steering/ must NOT load below home",
+    );
+    const fromHome = await loadConfigs(tmp);
+    assert.deepEqual(
+      fromHome.layers.map((l) => l.disabledRules?.[0]),
+      ["legacy", "global"],
+      "at cwd === home the project layer is the legacy path",
+    );
+  });
+
+  it("honors PI_CODING_AGENT_DIR for the global layer", async () => {
+    const prior = process.env["PI_CODING_AGENT_DIR"];
+    process.env["PI_CODING_AGENT_DIR"] = join(tmp, "custom-agent");
+    try {
+      const proj = join(tmp, "proj");
+      mkdirSync(proj, { recursive: true });
+      writeConfig(
+        join(tmp, "custom-agent", "steering", "index.ts"),
+        configModule("{ disabledRules: ['custom'] }"),
+      );
+      const { layers } = await loadConfigs(proj);
+      assert.deepEqual(
+        layers.map((l) => l.disabledRules?.[0]),
+        ["custom"],
+      );
+    } finally {
+      if (prior === undefined) delete process.env["PI_CODING_AGENT_DIR"];
+      else process.env["PI_CODING_AGENT_DIR"] = prior;
+    }
+  });
+
+  it("tilde-expands a ~/… PI_CODING_AGENT_DIR under HOME", async () => {
+    const prior = process.env["PI_CODING_AGENT_DIR"];
+    process.env["PI_CODING_AGENT_DIR"] = "~/my-agent";
+    try {
+      const proj = join(tmp, "proj");
+      mkdirSync(proj, { recursive: true });
+      writeConfig(
+        join(tmp, "my-agent", "steering", "index.ts"),
+        configModule("{ disabledRules: ['tilde'] }"),
+      );
+      const { layers } = await loadConfigs(proj);
+      assert.deepEqual(
+        layers.map((l) => l.disabledRules?.[0]),
+        ["tilde"],
+      );
+    } finally {
+      if (prior === undefined) delete process.env["PI_CODING_AGENT_DIR"];
+      else process.env["PI_CODING_AGENT_DIR"] = prior;
+    }
+  });
+
+  it("records a layer-import-failed diagnostic for the GLOBAL layer under the agent dir", async () => {
+    // Mirrors the project-layer import-failed pin: the shared
+    // loadLayer path must surface the same diagnostic shape when the
+    // failing module lives at `<agentDir>/steering.ts` (default agent
+    // dir under the isolated HOME).
+    const proj = join(tmp, "proj");
+    mkdirSync(proj, { recursive: true });
+    writeConfig(
+      join(tmp, ".pi", "agent", "steering.ts"),
+      "export default { rules: {{ not valid ts }} };",
+    );
+    const { layers, diagnostics } = await loadConfigs(proj);
+    assert.deepEqual(layers, []);
+    const hit = diagnostics.find((d) => d.kind === "layer-import-failed");
+    assert.ok(
+      hit,
+      `expected a layer-import-failed diagnostic; got: ${JSON.stringify(diagnostics)}`,
     );
+    assert.equal(hit.type, "warning");
+    assert.equal(hit.path, join(tmp, ".pi", "agent", "steering.ts"));
+    assert.match(hit.message, /failed to import/);
   });
 
   it("prefers index.ts over steering.ts at the same layer", async () => {
@@ -403,30 +508,52 @@ describe("loader: loadConfigs", () => {
     );
   });
 
-  it("handles heterogeneous config forms across layers (inner flat + outer dir)", async () => {
-    // Inner (session cwd) uses the single-file form .pi/steering.ts;
-    // outer ancestor uses the directory form .pi/steering/index.ts.
-    // Both layers should be collected inner-first without the
-    // loader tripping on the form mismatch.
-    const outer = join(tmp, "a");
-    const inner = join(tmp, "a", "b");
-    mkdirSync(inner, { recursive: true });
+  it("handles heterogeneous forms across the two layers (project flat + global dir)", async () => {
+    // Project (session cwd) uses the single-file form
+    // .pi/steering.ts; global layer uses the directory form
+    // <agentDir>/steering/index.ts. Both layers should be collected
+    // project-first without the loader tripping on the form mismatch.
+    const proj = join(tmp, "proj");
+    mkdirSync(proj, { recursive: true });
     writeConfig(
-      join(inner, ".pi", "steering.ts"),
-      configModule("{ disabledRules: ['inner-flat'] }"),
+      join(proj, ".pi", "steering.ts"),
+      configModule("{ disabledRules: ['project-flat'] }"),
     );
     writeConfig(
-      join(outer, ".pi", "steering", "index.ts"),
-      configModule("{ disabledRules: ['outer-dir'] }"),
+      join(tmp, ".pi", "agent", "steering", "index.ts"),
+      configModule("{ disabledRules: ['global-dir'] }"),
     );
-    const { layers } = await loadConfigs(inner);
+    const { layers } = await loadConfigs(proj);
     assert.deepEqual(
       layers.map((l) => l.disabledRules?.[0]),
-      ["inner-flat", "outer-dir"],
-      "expected inner-first ordering regardless of per-layer form",
+      ["project-flat", "global-dir"],
+      "expected project-first ordering regardless of per-layer form",
     );
   });
 
+  it("emits global-layer stray-file diagnostics with paths under the agent dir", async () => {
+    const cwd = join(tmp, "proj");
+    mkdirSync(cwd, { recursive: true });
+    // Stray non-.ts file in the GLOBAL layer's steering/ dir, with no
+    // index.ts — the stray-file scan must run for both layers, not
+    // just the project one.
+    mkdirSync(join(tmp, ".pi", "agent", "steering"), { recursive: true });
+    writeFileSync(
+      join(tmp, ".pi", "agent", "steering", "rules.mjs"),
+      "// not ts",
+      "utf8",
+    );
+    const { diagnostics } = await loadConfigs(cwd);
+    const stray = diagnostics.filter((d) => d.kind === "layer-stray-file");
+    assert.equal(stray.length, 1);
+    assert.equal(
+      stray[0]?.path,
+      join(tmp, ".pi", "agent", "steering", "rules.mjs"),
+    );
+    assert.equal(stray[0]?.type, "warning");
+    assert.match(stray[0]?.message ?? "", /under steering\//);
+  });
+
   it("re-imports config when file content changes between calls", async () => {
     // Regression: Node's ESM module map is keyed on URL and caches
     // indefinitely within a process. Without cache-busting, an edit
@@ -954,6 +1081,31 @@ describe("loader: loadSteeringConfig", () => {
     assert.deepEqual(diagnostics, []);
   });
 
+  it("project rule overrides global rule by name", async () => {
+    // End-to-end: the project layer's rule shadows the global layer's
+    // same-named rule (project wins on name-keyed merge), with no
+    // collision diagnostic — cross-layer override is the documented
+    // customization path.
+    const cwd = join(tmp, "proj");
+    mkdirSync(cwd, { recursive: true });
+    writeConfig(
+      join(cwd, ".pi", "steering.ts"),
+      configModule(
+        `{ rules: [{ name: "dup", tool: "bash", field: "command", pattern: /^PROJECT/, reason: "project" }] }`,
+      ),
+    );
+    writeConfig(
+      join(tmp, ".pi", "agent", "steering", "index.ts"),
+      configModule(
+        `{ rules: [{ name: "dup", tool: "bash", field: "command", pattern: /^GLOBAL/, reason: "global" }] }`,
+      ),
+    );
+    const { config: merged, diagnostics } = await loadSteeringConfig(cwd);
+    assert.equal(merged.rules?.length, 1);
+    assert.equal(merged.rules?.[0]?.reason, "project");
+    assert.deepEqual(diagnostics, []);
+  });
+
   it("surfaces both loader-side and merge-side diagnostics in a single array", async () => {
     // Stage a dual-form coexistence (loader-side warning) plus a
     // within-layer rule-name collision (merge-side warning) so we

package/src/loader.ts

@@ -2,15 +2,17 @@
 // Part of pi-steering.
 
 /**
- * TS config loader. Walk up cwd → `$HOME`, find `.pi/steering/index.ts`
- * or `.pi/steering.ts` per layer, dynamic-import each, merge
- * inner-first. Per-symbol JSDoc carries the contract; see also the
- * {@link SteeringDiagnostic} / {@link SteeringDiagnosticKind} JSDoc
- * for the diagnostic stream.
+ * TS config loader. Two fixed layers: the project layer at
+ * `<cwd>/.pi/steering/` (or `.pi/steering.ts`) and the global layer
+ * at `<agentDir>/steering/`, dynamic-import each, merge inner-first
+ * (project layer wins on name-keyed collisions). Per-symbol JSDoc
+ * carries the contract; see also the {@link SteeringDiagnostic} /
+ * {@link SteeringDiagnosticKind} JSDoc for the diagnostic stream.
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { EVALUATOR_BUILTIN_TRACKERS } from "./evaluator.ts";
 import { runMergerPipeline } from "./internal/session-runtime.ts";
@@ -53,25 +55,25 @@ function assertNodeVersion(): void {
 // ---------------------------------------------------------------------------
 
 /**
- * Candidate file paths for a given directory's `.pi/steering/...` slot,
- * in priority order. First existing file wins.
+ * Candidate file paths for a given directory's `slot` (default
+ * `.pi/steering`), in priority order. First existing file wins.
  *
  * Exported for tests — not part of the library's public API.
  */
-export function configCandidates(dir: string): string[] {
-  return [
-    join(dir, ".pi", "steering", "index.ts"),
-    join(dir, ".pi", "steering.ts"),
-  ];
+export function configCandidates(dir: string, slot = ".pi/steering"): string[] {
+  return [join(dir, slot, "index.ts"), join(dir, `${slot}.ts`)];
 }
 
 /**
- * Return the non-`.ts` files that exist under `<dir>/.pi/steering/` so
+ * Return the non-`.ts` files that exist under `<dir>/<slot>` so
  * callers can warn about them. Uses a best-effort fs read: a missing
  * directory returns an empty list.
  */
-function unexpectedFilesUnderSteering(dir: string): string[] {
-  const steeringDir = join(dir, ".pi", "steering");
+function unexpectedFilesUnderSteering(
+  dir: string,
+  slot = ".pi/steering",
+): string[] {
+  const steeringDir = join(dir, slot);
   if (!existsSync(steeringDir)) return [];
   try {
     const entries = readdirSync(steeringDir);
@@ -95,42 +97,40 @@ function unexpectedFilesUnderSteering(dir: string): string[] {
 }
 
 /**
- * Walk up from `cwd` to `$HOME` (inclusive, or to the filesystem root
- * if HOME is unset / outside the cwd's ancestry), returning the list
- * of directories INNER-FIRST — so `[cwd, cwd/parent, ..., HOME]`.
+ * Resolve the pi agent directory: `$PI_CODING_AGENT_DIR` when set
+ * (tilde-expanded: `"~"` → home, `"~/x"` → `<home>/x`, anything else
+ * as-is), else `<home>/.pi/agent`. Mirrors pi's `getAgentDir()` in
+ * @earendil-works/pi-coding-agent.
  *
  * Exported for tests.
  */
-export function ancestorChain(cwd: string): string[] {
-  const home = process.env["HOME"] ?? "";
-  const out: string[] = [];
-  const seen = new Set<string>();
-  let current = resolve(cwd);
-  while (true) {
-    if (seen.has(current)) break; // symlink-loop guard
-    seen.add(current);
-    out.push(current);
-    if (current === home || current === "/") break;
-    const parent = dirname(current);
-    if (parent === current) break; // filesystem root
-    current = parent;
+export function resolveAgentDir(): string {
+  const envDir = process.env["PI_CODING_AGENT_DIR"];
+  if (envDir !== undefined && envDir !== "") {
+    // mirror pi's expandTildePath: "~" -> homedir, "~/x" -> homedir/x, else as-is
+    if (envDir === "~") return homedir();
+    if (envDir.startsWith("~/")) return join(homedir(), envDir.slice(2));
+    return envDir;
   }
-  return out;
+  return join(homedir(), ".pi", "agent");
 }
 
 /**
  * Find the config file (if any) for a single layer. Returns the
  * resolved file path and a `layer-form-coexistence` diagnostic when
- * both `.pi/steering/index.ts` and `.pi/steering.ts` coexist in the
- * same directory (the directory form wins).
+ * both `<slot>/index.ts` and `<slot>.ts` coexist in the same
+ * directory (the directory form wins).
  *
  * Exported for tests.
  */
-export function findConfigFile(dir: string): {
+export function findConfigFile(
+  dir: string,
+  slot = ".pi/steering",
+): {
   file: string | null;
   diagnostic: SteeringDiagnostic | null;
 } {
-  const [indexForm, flatForm] = configCandidates(dir);
+  const [indexForm, flatForm] = configCandidates(dir, slot);
   const indexExists = indexForm !== undefined && existsSync(indexForm);
   const flatExists = flatForm !== undefined && existsSync(flatForm);
   let diagnostic: SteeringDiagnostic | null = null;
@@ -144,8 +144,8 @@ export function findConfigFile(dir: string): {
       kind: "layer-form-coexistence",
       path: dir,
       message:
-        "both .pi/steering.ts and .pi/steering/index.ts exist; using " +
-        "directory form. Delete .pi/steering.ts to remove this warning.",
+        `both ${slot}.ts and ${slot}/index.ts exist; using ` +
+        `directory form. Delete ${slot}.ts to remove this warning.`,
     };
   }
   if (indexExists) return { file: indexForm ?? null, diagnostic };
@@ -223,12 +223,15 @@ async function importConfigFile(path: string): Promise<SteeringConfig> {
 }
 
 /**
- * Walk up from `cwd` collecting config layers. Returns INNER-FIRST
- * (caller passes to {@link buildConfig}, which expects inner-first so
- * early entries take precedence on collisions).
+ * Load the two fixed config layers for `cwd`: the project layer at
+ * `<cwd>/.pi/steering/` (or `.pi/steering.ts`) and the global layer
+ * at `<agentDir>/steering/` (see {@link resolveAgentDir}). Returns
+ * the layers INNER-FIRST (project first, then global; caller passes
+ * to {@link buildConfig}, which expects inner-first so early entries
+ * take precedence on collisions).
  *
  * Issues encountered along the way (per-layer import failure, dual
- * form coexistence, stray non-`.ts` file under `.pi/steering/`)
+ * form coexistence, stray non-`.ts` file under the layer directory)
  * surface as structured {@link SteeringDiagnostic} entries on the
  * returned object. The loader does not log to `console.warn` directly
  * — the bridge runtime owns the policy decision (throw vs. log) once
@@ -242,46 +245,59 @@ export async function loadConfigs(cwd: string): Promise<{
 }> {
   assertNodeVersion();
 
-  const dirs = ancestorChain(cwd);
   const layers: SteeringConfig[] = [];
   const diagnostics: SteeringDiagnostic[] = [];
-  for (const dir of dirs) {
-    const { file, diagnostic } = findConfigFile(dir);
-    if (diagnostic !== null) diagnostics.push(diagnostic);
-    if (file === null) {
-      // Surface stray files under `.pi/steering/` that the loader
-      // won't pick up. Only check when the directory exists but has
-      // no `index.ts` — otherwise a project without any steering
-      // directory would emit noise.
-      const steeringDir = join(dir, ".pi", "steering");
-      if (existsSync(steeringDir)) {
-        for (const stray of unexpectedFilesUnderSteering(dir)) {
-          diagnostics.push({
-            type: "warning",
-            kind: "layer-stray-file",
-            path: stray,
-            message: "ignoring non-.ts file under .pi/steering/",
-          });
-        }
+  await loadLayer(cwd, ".pi/steering", layers, diagnostics);
+  await loadLayer(resolveAgentDir(), "steering", layers, diagnostics);
+  return { layers, diagnostics };
+}
+
+/**
+ * Load a single layer: `slot` under `dir` (candidate file discovery,
+ * coexistence diagnostic, stray-file scan, dynamic import). Shared by
+ * the project layer (`cwd` + `.pi/steering`) and the global layer
+ * (`agentDir` + `steering`).
+ */
+async function loadLayer(
+  dir: string,
+  slot: string,
+  layers: SteeringConfig[],
+  diagnostics: SteeringDiagnostic[],
+): Promise<void> {
+  const { file, diagnostic } = findConfigFile(dir, slot);
+  if (diagnostic !== null) diagnostics.push(diagnostic);
+  if (file === null) {
+    // Surface stray files under `<slot>/` that the loader won't pick
+    // up. Only check when the directory exists but has no `index.ts`
+    // — otherwise a project without any steering directory would
+    // emit noise.
+    const slotDir = join(dir, slot);
+    if (existsSync(slotDir)) {
+      for (const stray of unexpectedFilesUnderSteering(dir, slot)) {
+        diagnostics.push({
+          type: "warning",
+          kind: "layer-stray-file",
+          path: stray,
+          message: `ignoring non-.ts file under ${slot}/`,
+        });
       }
-      continue;
-    }
-    try {
-      layers.push(await importConfigFile(file));
-    } catch (err) {
-      // Use err.message to drop the `Error: ` class prefix; native
-      // runtime errors (jiti syntax errors) may embed their path inside
-      // the message and we accept that duplication.
-      const body = err instanceof Error ? err.message : String(err);
-      diagnostics.push({
-        type: "warning",
-        kind: "layer-import-failed",
-        path: file,
-        message: `failed to import: ${body}`,
-      });
     }
+    return;
+  }
+  try {
+    layers.push(await importConfigFile(file));
+  } catch (err) {
+    // Use err.message to drop the `Error: ` class prefix; native
+    // runtime errors (jiti syntax errors) may embed their path inside
+    // the message and we accept that duplication.
+    const body = err instanceof Error ? err.message : String(err);
+    diagnostics.push({
+      type: "warning",
+      kind: "layer-import-failed",
+      path: file,
+      message: `failed to import: ${body}`,
+    });
   }
-  return { layers, diagnostics };
 }
 
 // ---------------------------------------------------------------------------
@@ -428,10 +444,11 @@ function mergeStringUnion(
 }
 
 /**
- * Inner-wins boolean merge over walked-up layers. Walks left-to-right
- * (inner-first); returns the first explicit boolean or `undefined`.
- * Used by `buildConfig` and the session runtime for the inner-wins
- * boolean fields. Internal — not in the package's `exports` surface.
+ * Inner-wins boolean merge over the inner-first layers. Walks
+ * left-to-right (inner-first); returns the first explicit boolean or
+ * `undefined`. Used by `buildConfig` and the session runtime for the
+ * inner-wins boolean fields. Internal — not in the package's
+ * `exports` surface.
  */
 export function mergeBool(
   layers: readonly SteeringConfig[],