@cad0p/pi-steering 0.1.0 → 0.2.0

package/examples/work-item-plugin/src/observers/npm-test-tracker.ts

@@ -25,7 +25,11 @@
  * downstream typos become compile errors.
  */
 
-import type { Observer, ObserverContext, PredicateContext } from "@cad0p/pi-steering";
+import type {
+  Observer,
+  ObserverContext,
+  PredicateContext,
+} from "@cad0p/pi-steering";
 
 /**
  * Session-entry type written when `npm test` succeeds. Rules gate via

package/examples/work-item-plugin/src/observers/retest-required-tracker.ts

@@ -28,7 +28,11 @@
  * from downstream rules.
  */
 
-import type { Observer, ObserverContext, PredicateContext } from "@cad0p/pi-steering";
+import type {
+  Observer,
+  ObserverContext,
+  PredicateContext,
+} from "@cad0p/pi-steering";
 
 /**
  * Session-entry event written when `git pull` succeeds. Rules that

package/examples/work-item-plugin/src/rules/commit-requires-work-item.test.ts

@@ -12,7 +12,11 @@
 
 import { describe, it } from "node:test";
 import type { Plugin } from "@cad0p/pi-steering";
-import { expectAllows, expectBlocks, loadHarness } from "@cad0p/pi-steering/testing";
+import {
+  expectAllows,
+  expectBlocks,
+  loadHarness,
+} from "@cad0p/pi-steering/testing";
 import { workItemFormat } from "../predicates/work-item-format.ts";
 import { commitRequiresWorkItem } from "./commit-requires-work-item.ts";
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cad0p/pi-steering",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
-  "description": "AST-backed steering hooks for pi \u2014 deterministic tool-call guardrails with command-level effective-cwd scoping.",
+  "description": "AST-backed steering hooks for pi — deterministic tool-call guardrails with command-level effective-cwd scoping.",
   "keywords": [
     "pi-package",
     "extension",

package/src/__test-helpers__.ts

@@ -53,9 +53,10 @@ import type { EvaluatorHost } from "./evaluator-internals/context.ts";
  *   - restore `process.env["HOME"]` and recursively remove the temp
  *     dir on teardown.
  *
- * Used by every test surface that exercises the loader walk-up
- * (`index.test.ts`, `loader.test.ts`, `internal/session-runtime.test.ts`)
- * so the per-file scratch-HOME boilerplate stays in one place.
+ * Used by every test surface that exercises the loader's two-layer
+ * discovery (`index.test.ts`, `loader.test.ts`,
+ * `internal/session-runtime.test.ts`) so the per-file scratch-HOME
+ * boilerplate stays in one place.
  *
  * The temp dir path is exposed via the optional `onReady` callback,
  * fired inside `beforeEach`; tests typically stash it in a
@@ -81,7 +82,7 @@ export function useIsolatedHome(
 }
 
 /**
- * Like {@link useIsolatedHome} but also chdirs into the scratch dir, so factory-time tests find the per-test config via the loader walk-up. macOS tmpdir is a symlink; canonicalized via `realpathSync` so cwd-mismatch tests don't see false-divergence.
+ * Like {@link useIsolatedHome} but also chdirs into the scratch dir, so factory-time tests find the per-test config via the loader's project layer. macOS tmpdir is a symlink; canonicalized via `realpathSync` so cwd-mismatch tests don't see false-divergence.
  */
 export function useScratchHome(
   prefix: string,

package/src/bin/pi-steering.test.ts

@@ -50,8 +50,8 @@ interface RunResult {
  * non-zero exit codes — the caller asserts on `code`.
  *
  * Accepts an optional `cwd` so tests for the `list` subcommand can
- * point the walk-up loader at a scratch directory without polluting
- * the project.
+ * point the loader's project layer at a scratch directory and isolate
+ * HOME so no real global config leaks, without polluting the project.
  */
 function runCli(...args: string[]): Promise<RunResult>;
 function runCli(opts: { cwd?: string }, ...args: string[]): Promise<RunResult>;
@@ -67,6 +67,12 @@ function runCli(
   } else {
     args = first === undefined ? [...rest] : [first, ...rest];
   }
+  // The child CLI reads the global layer from `$HOME`; without
+  // isolation the developer's real `~/.pi/agent/steering/` would
+  // leak into the tests. `PI_CODING_AGENT_DIR` must be removed (an
+  // empty string still overrides the default agent dir).
+  const env: NodeJS.ProcessEnv = { ...process.env, HOME: scratch };
+  delete env.PI_CODING_AGENT_DIR;
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(
       process.execPath,
@@ -74,6 +80,7 @@ function runCli(
       {
         stdio: ["ignore", "pipe", "pipe"],
         ...(cwd !== undefined ? { cwd } : {}),
+        env,
       },
     );
     let stdout = "";
@@ -229,7 +236,10 @@ describe("pi-steering import-json: conversion", () => {
     const r = await runCli("import-json", path);
     assert.equal(r.code, 0);
     assert.equal(r.stderr.trim(), "");
-    assert.match(r.stdout, /import \{ defineConfig \} from "@cad0p\/pi-steering"/);
+    assert.match(
+      r.stdout,
+      /import \{ defineConfig \} from "@cad0p\/pi-steering"/,
+    );
     assert.match(r.stdout, /export default defineConfig\(/);
     assert.match(r.stdout, /"no-amend"/);
     assert.match(r.stdout, /"Don't rewrite history\."/);
@@ -345,7 +355,7 @@ describe("pi-steering list", () => {
     assert.match(r.stdout, /Resolved config: 1 plugin, 2 rules, 0 observers\./);
     assert.match(r.stdout, /git\s+\[pi-steering\/plugins\/git\]/);
     assert.match(r.stdout, /no-main-commit\s+bash\s+when: branch/);
-    assert.match(r.stdout, /User \(\.pi\/steering\/index\.ts\):/);
+    assert.match(r.stdout, /User \(project \+ global\):/);
     assert.match(r.stdout, /my-rule\s+bash/);
     assert.match(r.stdout, /Disabled rules: some-disabled-rule/);
   });

package/src/bin/pi-steering.ts

@@ -9,7 +9,8 @@
  *     Convert a v1 JSON config to the v2 TS config shape.
  *
  *   pi-steering list [--format=text|json]
- *     Resolve the walk-up config from the CWD and print the
+ *     Resolve the two-layer config (project `<cwd>/.pi/steering/` +
+ *     global `<agentDir>/steering/`) from the CWD and print the
  *     effective plugins / rules / observers / disables.
  *
  * Exit codes:
@@ -75,10 +76,12 @@ SUBCOMMANDS
       the JSON-to-TS conversion surface and rejected features.
 
   list [--format=text|json]
-      Load the effective config for the current directory (walk-up
-      from cwd) and print the resolved plugins, rules, and observers,
-      grouped by source. Useful for answering "which rules are
-      active here?" without reading the config files by hand.
+      Load the effective config for the current directory (project
+      layer at <cwd>/.pi/steering/ + global layer at
+      <agentDir>/steering/) and print the resolved plugins, rules,
+      and observers, grouped by source. Useful for answering "which
+      rules are active here?" without reading the config files by
+      hand.
 
 OPTIONS
   -h, --help    Show this help.
@@ -214,8 +217,9 @@ async function runList(args: string[]): Promise<number> {
     }
   }
 
-  // Walk up from cwd and merge. CLI deliberately omits
-  // DEFAULT_PLUGINS / DEFAULT_RULES; runtime injects them.
+  // Load project layer (cwd) + global layer (agent dir) and merge.
+  // CLI deliberately omits DEFAULT_PLUGINS / DEFAULT_RULES; runtime
+  // injects them.
   let layers: readonly SteeringConfig[];
   let loaderDiagnostics: readonly SteeringDiagnostic[] = [];
   try {
@@ -280,10 +284,11 @@ async function runList(args: string[]): Promise<number> {
 /**
  * CLI variant of the merge pipeline. Redirects `console.info`
  * breadcrumbs (disabled-plugin / disabled-rule / dropped-observer)
- * onto stderr so stdout stays clean for `--format=json`. After
- * {@link runMergerPipeline}, mirrors {@link buildSessionRuntime}'s
- * `disabledRules` filter + `finalizePluginState` so `pi-steering
- * list` reports the same observer-drop set production sees.
+ * onto stderr so stdout stays clean for `--format=json`. Loads the
+ * project + global layers and merges them inner-first (project wins),
+ * then mirrors {@link buildSessionRuntime}'s `disabledRules` filter +
+ * `finalizePluginState` so `pi-steering list` reports the same
+ * observer-drop set production sees.
  */
 function runCliMergeWithInfoCapture(layers: readonly SteeringConfig[]): {
   config: SteeringConfig;
@@ -333,9 +338,10 @@ function printListHelp(): void {
 USAGE
   pi-steering list [--format=text|json]
 
-Walks up from the current directory looking for .pi/steering/index.ts
-(or .pi/steering.ts) at each ancestor. Merges the layers inner-first
-and prints the effective plugins, rules, and observers.
+Loads the project layer (<cwd>/.pi/steering/) and the global layer
+(~/.pi/agent/steering/, or $PI_CODING_AGENT_DIR/steering) and prints
+the effective plugins, rules, and observers. Project layer wins on
+rule-name collision.
 
 FLAGS
   --format=text   (default) human-readable grouped output
@@ -443,7 +449,7 @@ function observerJSON(o: Observer): unknown {
  *     no-main-commit     bash  when: branch
  *     ...
  *
- *   User (.pi/steering/index.ts):
+ *   User (project + global):
  *     (none)
  *
  *   Disabled: (none)
@@ -484,7 +490,7 @@ function renderListText(config: SteeringConfig): string {
   }
 
   // User block.
-  lines.push("User (.pi/steering/index.ts):");
+  lines.push("User (project + global):");
   if (userRules.length === 0 && userObservers.length === 0) {
     lines.push("  (none)");
   } else {

package/src/evaluator.ts

@@ -43,12 +43,6 @@
  * `evaluateCandidate` stays tool-agnostic.
  */
 
-import type {
-  ExtensionContext,
-  ToolCallEvent,
-  ToolCallEventResult,
-} from "@earendil-works/pi-coding-agent";
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import {
   type CommandRef,
   cwdTracker,
@@ -63,6 +57,12 @@ import {
   type Word,
   walk,
 } from "@cad0p/unbash-walker";
+import type {
+  ExtensionContext,
+  ToolCallEvent,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import {
   createAppendEntry,
   createExecCache,

package/src/factory-time-load.test.ts

@@ -26,7 +26,7 @@
  *   - aggregated render snapshot pins the multi-line format.
  *
  * The bridge factory is async; tests `chdir` into a fresh scratch
- * `$HOME` so the loader walk-up reads the per-test config.
+ * `$HOME` so the loader's global layer reads the per-test config.
  */
 
 import assert from "node:assert/strict";
@@ -224,24 +224,27 @@ describe("register(): factory throws on diagnostics", () => {
   });
 
   it("throws on plugin-name-collision (warning-class, failOnWarnings default)", async () => {
-    // Two layers ship the same plugin name. The collision is
-    // warning-class but escalates under the default
+    // Project and global layers ship the same plugin name. The
+    // collision is warning-class but escalates under the default
     // `failOnWarnings: true`.
-    mkdirSync(join(tmpHome, "inner"), { recursive: true });
+    const inner = join(tmpHome, "inner");
+    mkdirSync(inner, { recursive: true });
     writeSteeringSingleFileConfig(
-      tmpHome,
+      inner,
       `export default {
-				disableDefaults: true,
 				plugins: [{ name: "shared" }],
 			};`,
     );
-    writeSteeringSingleFileConfig(
-      join(tmpHome, "inner"),
+    mkdirSync(join(tmpHome, ".pi", "agent"), { recursive: true });
+    writeFileSync(
+      join(tmpHome, ".pi", "agent", "steering.ts"),
       `export default {
+				disableDefaults: true,
 				plugins: [{ name: "shared" }],
 			};`,
+      "utf8",
     );
-    process.chdir(join(tmpHome, "inner"));
+    process.chdir(inner);
     await expectRegisterThrow([/\[warning\]/, /plugin "shared"/]);
   });
 
@@ -385,26 +388,29 @@ describe("register(): factory does NOT throw", () => {
   });
 
   it("disabledPlugins resolves plugin-name-collision before the check runs", async () => {
-    // The outer layer's `disabledPlugins: ["shared"]` removes
+    // The global layer's `disabledPlugins: ["shared"]` removes
     // the would-be collision before cross-layer detection,
     // matching the disable-then-detect ordering. No throw, no
     // warn.
-    mkdirSync(join(tmpHome, "inner"), { recursive: true });
+    const inner = join(tmpHome, "inner");
+    mkdirSync(inner, { recursive: true });
     writeSteeringSingleFileConfig(
-      tmpHome,
+      inner,
       `export default {
-				disableDefaults: true,
-				disabledPlugins: ["shared"],
 				plugins: [{ name: "shared" }],
 			};`,
     );
-    writeSteeringSingleFileConfig(
-      join(tmpHome, "inner"),
+    mkdirSync(join(tmpHome, ".pi", "agent"), { recursive: true });
+    writeFileSync(
+      join(tmpHome, ".pi", "agent", "steering.ts"),
       `export default {
+				disableDefaults: true,
+				disabledPlugins: ["shared"],
 				plugins: [{ name: "shared" }],
 			};`,
+      "utf8",
     );
-    process.chdir(join(tmpHome, "inner"));
+    process.chdir(inner);
     const mock = makeMockPi();
     await register(mock.api as ExtensionAPI);
     const collisionWarn = capturedWarns.find((m) => /plugin "shared"/i.test(m));
@@ -448,7 +454,7 @@ describe("register(): cwd-mismatch session_start warn", () => {
 
   it("emits console.warn when ctx.cwd !== launchCwd; engine continues evaluating", async () => {
     // A user-defined rule lives in the launch-cwd config (tmpHome) but
-    // not in foreignCwd's walk-up; if it still fires after the
+    // not in foreignCwd's project layer; if it still fires after the
     // cwd-mismatch warn, launch-cwd config remained in force.
     writeSteeringSingleFileConfig(
       tmpHome,

package/src/index.test.ts

@@ -14,8 +14,8 @@
  *   - the audit-log side effect for accepted overrides,
  *   - the observer-dispatcher side effect on matching tool_result
  *     events,
- *   - the walk-up TS-config loader: {@link buildSessionRuntime} reads
- *     `.pi/steering.ts` from an isolated `$HOME`.
+ *   - the two-layer TS-config loader: {@link buildSessionRuntime}
+ *     reads `.pi/steering.ts` from an isolated `$HOME`.
  *
  * The bridge factory's lifecycle wiring + config-loading glue isn't
  * covered by the unit suites; this file is the only end-to-end check.
@@ -180,8 +180,8 @@ let tmpHome: string;
  * Bind a fresh `$HOME` per test AND chdir into it via the shared
  * {@link useScratchHome} helper. The bridge factory eagerly loads
  * from `process.cwd()` at register time, so tests must launch from
- * the scratch home for the loader walk-up to find the per-test
- * config.
+ * the scratch home for the loader's project + global layers to find
+ * the per-test config.
  */
 function useRegisterScratchHome(): void {
   useScratchHome("pi-steering-register-", (t) => {

package/src/index.ts

@@ -141,7 +141,7 @@ export { AGENT_LOOP_INDEX_KEY } from "./evaluator-internals/context.ts";
 // `if (ctx.walkerState?.cwd === "unknown") return "unknown";`,
 // then the engine projects via `onUnknown:` policy).
 export { walkerUnknownCwdReason } from "./helpers/walker-unknown-cwd-reason.ts";
-// Loader — walk-up config discovery + merge.
+// Loader — two-layer config discovery + merge.
 export { buildConfig, loadConfigs, loadSteeringConfig } from "./loader.ts";
 // Schema types — the public authoring surface.
 export type {

package/src/internal/ref-text.ts

@@ -9,7 +9,11 @@
  * @internal — not part of the public pi-steering surface.
  */
 
-import { type CommandRef, getBasename, getCommandArgs } from "@cad0p/unbash-walker";
+import {
+  type CommandRef,
+  getBasename,
+  getCommandArgs,
+} from "@cad0p/unbash-walker";
 
 /** Render a ref as `"{basename} {args joined by space}"`, trimmed. */
 export function refToText(ref: CommandRef): string {

package/src/internal/session-runtime.test.ts

@@ -13,8 +13,8 @@
  *   - the aggregated error message follows the rule-based spec
  *     (header + bullets, errors first, optional path prefix).
  *
- * Uses a tmp `$HOME` so the walk-up loader's `$HOME` ceiling is
- * scoped to the test directory.
+ * Uses a tmp `$HOME` so the loader's global layer is scoped to the
+ * test directory.
  */
 
 import assert from "node:assert/strict";

package/src/internal/session-runtime.ts

@@ -5,8 +5,9 @@
  * Internal module — not part of the package's public API.
  *
  * This module holds the wiring that the bridge factory in `index.ts`
- * uses to spin up an evaluator + observer dispatcher from a walk-up
- * steering config. It is intentionally NOT re-exported from
+ * uses to spin up an evaluator + observer dispatcher from the
+ * two-layer config (project layer at `cwd`, global layer at the
+ * agent dir). It is intentionally NOT re-exported from
  * `index.ts` or any other public entry point; consumers building
  * their own extensions should go through `loadHarness` (subpath
  * `@cad0p/pi-steering/testing`) or call `buildEvaluator` /