@cad0p/pi-steering 0.1.0

package/src/schema.ts

@@ -0,0 +1,1963 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * v2 config schema - TS-first rules, plugins, observers, predicates.
+ *
+ * Additive to the v1 schema (see `../schema.ts`). The existing evaluator
+ * continues to drive the pi extension runtime on the v1 types; v2 types
+ * live in parallel and power the new `defineConfig` / TS loader path.
+ * Phase 3 rewrites the evaluator on top of this module and retires v1.
+ *
+ * Design references (see the accepted ADR, linked from PR #2's
+ * description):
+ *   - "Design → Rule schema"         → {@link Rule}, {@link TopLevelWhenClause},
+ *                                       {@link Pattern}, {@link PredicateFn},
+ *                                       {@link PredicateHandler}.
+ *   - "Design → Observer schema"     → {@link Observer},
+ *                                       {@link ObserverContext}.
+ *   - "Design → Plugin schema"       → {@link Plugin}.
+ *   - "Design → Predicate context"   → {@link PredicateContext}.
+ *   - "Design → Override default"    → {@link SteeringConfig.defaultNoOverride}
+ *                                       (default `true`, fail-closed).
+ *
+ * Nothing in this module executes rules, observers, or predicates. It
+ * only defines shapes. Evaluation is Phase 3's concern.
+ */
+
+import type { EnvState, Tracker, Word } from "@cad0p/unbash-walker";
+
+// ---------------------------------------------------------------------------
+// Primitive predicate types
+// ---------------------------------------------------------------------------
+
+/**
+ * Static or regex pattern accepted by all built-in string-valued
+ * predicates (`when.cwd`, `when.branch`, `when.upstream`, ...).
+ *
+ * A plain string is treated as a regex source (compiled once at load
+ * time by the evaluator - users escape literals themselves). A RegExp
+ * is used as-is.
+ *
+ * See ADR "Design → Rule schema" → Pattern.
+ *
+ * @see {@link Patterns} for the OR-of-matches shorthand used by
+ * pattern-leaf predicate registry augmentations.
+ */
+export type Pattern = string | RegExp;
+
+/**
+ * The OR-of-patterns shorthand for pattern-leaf predicate
+ * registrations: a single {@link Pattern} or an array of
+ * {@link Pattern}s (interpreted as OR-of-matches: any pattern
+ * matching counts as a hit).
+ *
+ * Use as the bare-type parameter of {@link PredicateShape} when
+ * registering a pattern-leaf predicate that accepts both bare
+ * shorthand (`when: { myPredicate: /^foo$/ }`) and explicit object
+ * form (`when: { myPredicate: { pattern: /^foo$/ } }`):
+ *
+ * @example
+ * ```ts
+ * import type { Patterns, PredicateShape } from "@cad0p/pi-steering";
+ *
+ * declare global {
+ *   interface PiSteeringPredicates {
+ *     myPredicate: PredicateShape<Patterns>;
+ *   }
+ * }
+ * ```
+ */
+export type Patterns = Pattern | Pattern[];
+
+/**
+ * Escape-hatch predicate: arbitrary user-supplied logic evaluated with a
+ * {@link PredicateContext}. Returned value gates whether the surrounding
+ * rule fires. Async OK - evaluator awaits it.
+ *
+ * Used as the value of `when.condition`, and as the fallback shape for
+ * plugin-registered custom keys on a {@link TopLevelWhenClause}.
+ *
+ * See ADR "Design → Rule schema" → PredicateFn.
+ */
+export type PredicateFn = (ctx: PredicateContext) => boolean | Promise<boolean>;
+
+/**
+ * Dynamic block-reason function. When {@link Rule.reason} is a
+ * function, the evaluator invokes it with the same
+ * {@link PredicateContext} the predicates saw and prefixes the
+ * returned string with `[steering:<rule>@<source>] `. Async OK
+ * (evaluator awaits); thrown errors are logged to `console.warn` and
+ * replaced with a fail-safe fallback (`(reason failed to format;
+ * see log)`) so a broken reason doesn't leak its raw error message
+ * to the LLM.
+ *
+ * Use the function form when the block's human-readable context
+ * depends on runtime state — e.g. "Could not verify upstream at
+ * effective cwd \${ctx.walkerState.cwd}". Plain string reasons are
+ * preferred when the reason is static; they avoid the evaluator's
+ * extra  await + try/catch.
+ *
+ * @example
+ *   // Inject the current branch name into the reason when the walker
+ *   // resolved it statically; fall back to a generic message when the
+ *   // walker bails or the tracker's initial-sentinel flows through.
+ *   reason: (ctx) => {
+ *     const raw = ctx.walkerState?.branch;
+ *     const branch =
+ *       typeof raw === "string" && raw !== "" && raw !== "unknown"
+ *         ? raw
+ *         : undefined;
+ *     const onClause = branch ? ` You are on '${branch}'.` : "";
+ *     return `Don't commit directly to a protected branch.${onClause}`;
+ *   };
+ */
+export type ReasonFn = (ctx: PredicateContext) => string | Promise<string>;
+
+/**
+ * Plugin-registered predicate *handler*. Differs from {@link PredicateFn}
+ * only in that the first argument is the structured argument the user
+ * supplied under their custom `when.<key>` slot. Example:
+ *
+ * ```ts
+ * // user config
+ * when: { commitsAhead: { wrt: "origin/main", eq: 1 } }
+ *
+ * // plugin registration
+ * predicates: {
+ *   commitsAhead: (args: { wrt: string; eq: number }, ctx) => { ... }
+ * }
+ * ```
+ *
+ * `args` is whatever the rule author put under that key - the handler is
+ * responsible for validating its shape. `ctx` is the same
+ * {@link PredicateContext} the escape-hatch form receives.
+ *
+ * Returns a {@link PredicateVerdict} (`true | false | "unknown"`).
+ * Pre-trinary handlers returning plain `boolean` remain source-compatible:
+ * `boolean` is a subtype of `PredicateVerdict`, so existing handlers assign
+ * unchanged. Handlers that need to surface walker-unknown state to the
+ * engine return the literal string `"unknown"`; the engine then applies
+ * the leaf's `onUnknown:` modifier (or, inside `not:`, the block-level
+ * `onUnknown:`) to produce the leaf's verdict for downstream composition.
+ *
+ * Throwing inside a handler is equivalent to returning `"unknown"`: the
+ * engine catches and treats the leaf as unknown, then applies the
+ * `onUnknown:` policy. Prefer explicit returns; the catch exists so a
+ * buggy handler can't silently fail-OPEN by skipping its rule.
+ *
+ * See ADR "Design → Rule schema" → PredicateHandler.
+ */
+export type PredicateHandler<A = unknown> = (
+  args: A,
+  ctx: PredicateContext,
+) => PredicateVerdict | Promise<PredicateVerdict>;
+
+// ---------------------------------------------------------------------------
+// Per-predicate typing — registry, modifiers, mapped types
+// ---------------------------------------------------------------------------
+
+/**
+ * Trinary verdict surfaced by predicate handlers. `true` / `false` are
+ * the definite answers; the literal string `"unknown"` signals the
+ * predicate could not resolve its value (typically because some piece
+ * of walker-tracked state — cwd, branch, etc. — wasn't statically
+ * resolvable). The engine then applies the leaf's `onUnknown:` policy
+ * (or, inside `not:`, the block-level policy) to project the trinary
+ * verdict back to a definite boolean for rule-level composition.
+ */
+export type PredicateVerdict = boolean | "unknown";
+
+/**
+ * Predicate modifiers — optional fields that can be added to a
+ * predicate's spread form (outer leaf level) OR to the not-block top
+ * level. Single source of truth for what predicate authors and users
+ * can configure beyond the bare value. Adding a new modifier here
+ * propagates everywhere in the schema (every predicate's spread form,
+ * every not-block top level) and automatically reserves its key name
+ * via {@link ReservedPredicateKey}.
+ */
+export interface PredicateModifiers {
+  /**
+   * Walker-unknown policy. When the predicate's value can't be
+   * resolved at walker time (dynamic cwd / branch via `cd "$VAR"`,
+   * `git checkout $VAR`, etc.), this policy decides the predicate's
+   * verdict:
+   *   - `"block"` (default): treat as fail-CLOSED — predicate fires.
+   *   - `"allow"`: treat as fail-OPEN — predicate skips.
+   *
+   * At the leaf level (outer when-clause), this is per-predicate.
+   * At the not-block top level, this applies to ALL leaves in the
+   * not-block — leaf-level `onUnknown:` is forbidden inside `not:`
+   * (type-level error) so the user can't write the silent
+   * fail-OPEN `not: { cwd: P }` shape.
+   */
+  onUnknown?: "allow" | "block";
+}
+
+/**
+ * Default spread BASE (without modifiers) inferred from `Bare`'s shape:
+ *   - `Bare extends object`   → `Bare` directly (intersection at use site).
+ *   - `Bare extends Patterns` → `{ pattern: Bare }` wrapper.
+ *   - else (primitive)        → `{ value: Bare }` wrapper.
+ *
+ * Note the order: object check FIRST so a pure-object predicate
+ * auto-detects to intersection (clean sibling-modifier UX). Pattern
+ * check second to capture the built-in `string | RegExp | array`
+ * family. Primitive fallback for `boolean`, `number`, etc.
+ *
+ * The tuple-wrap (`[Bare] extends [...]`) prevents distributive
+ * conditional behavior across union members of `Bare`.
+ */
+export type DefaultSpreadBase<Bare> = [Bare] extends [object]
+  ? Bare
+  : [Bare] extends [Patterns]
+    ? { pattern: Bare }
+    : { value: Bare };
+
+/**
+ * Shape of a single entry in the {@link PiSteeringPredicates} registry.
+ * Each predicate declares its `bare` form and (optionally) an explicit
+ * `spreadBase` — the spread's object form WITHOUT modifiers.
+ *
+ * - `bare`: the value users write at the leaf (Pattern, boolean,
+ *           number, etc.).
+ * - `SpreadBase` (param): the spread's object form WITHOUT modifiers;
+ *           defaults to {@link DefaultSpreadBase} from `Bare`.
+ * - `spread` (derived at use site): `spreadBase & PredicateModifiers`
+ *           — the form users write at the leaf to specify modifiers.
+ *           Inner `not:` form omits modifiers (leaf-level `onUnknown:`
+ *           inside `not:` is forbidden); outer leaf form intersects
+ *           with `PredicateModifiers`.
+ *
+ * @see PredicateModifiers for the modifier surface available on every
+ *      predicate's spread form.
+ * @see DefaultSpreadBase for how the SpreadBase auto-detects from Bare.
+ */
+export interface PredicateShape<Bare, SpreadBase = DefaultSpreadBase<Bare>> {
+  /**
+   * The bare value users write at the leaf (no wrapper, no modifiers).
+   *
+   * For primitive {@link Bare} types (Pattern, boolean, number) this
+   * is the shorthand authors reach for first — `cwd: /work/`,
+   * `isClean: true`, `commitsAhead: 2`. The {@link spreadBase} form
+   * mirrors the bare value as `{ value: Bare }` (or an explicit
+   * `SpreadBase` shape for mixed-bare predicates like `commitsAhead`'s
+   * comparator bag) when authors need to attach leaf-level modifiers
+   * via `& PredicateModifiers`.
+   *
+   * For object {@link Bare} types the bare form IS the object shape
+   * directly (no `value:` wrapper); the {@link spreadBase} adds
+   * modifier slots without changing the structural shape.
+   */
+  bare: Bare;
+  /**
+   * The object form WITHOUT modifiers. Modifiers are added at use site
+   * via `& PredicateModifiers` (outer leaf level) or at the not-block
+   * top level (inside `not:`).
+   */
+  spreadBase: SpreadBase;
+}
+
+declare global {
+  /**
+   * Plugin-registered predicate registry. Empty by default; plugins
+   * extend via TypeScript module augmentation (`declare global { interface
+   * PiSteeringPredicates { ... } }`) to register typed predicates with
+   * autocomplete + JSDoc.
+   *
+   * Keys must NOT collide with {@link ReservedPredicateKey} (the
+   * operator-field union plus modifier keys); the type-level filter
+   * via {@link Exclude} drops collisions silently, and the engine
+   * throws at plugin-registration time with a concrete error message
+   * pointing the plugin author at the collision.
+   *
+   * Do NOT add an index signature (e.g. `[k: string]: PredicateShape<unknown>`)
+   * to this interface — it would widen `keyof PiSteeringPredicates` to
+   * `string`, defeating the reserved-key filter (`Exclude<string,
+   * "not" | "onUnknown">` is just `string` again).
+   *
+   * @example Plugin author registering a typed predicate
+   * ```ts
+   * import type { Plugin, PredicateShape } from "@cad0p/pi-steering";
+   * import { workItemFormat } from "./predicates/work-item-format.ts";
+   * import type { WorkItemFormatArgs } from "./predicates/work-item-format.ts";
+   *
+   * declare global {
+   *   interface PiSteeringPredicates {
+   *     workItemFormat: PredicateShape<WorkItemFormatArgs>;
+   *   }
+   * }
+   *
+   * const myPlugin = {
+   *   name: "work-item",
+   *   predicates: { workItemFormat },
+   * } as const satisfies Plugin;
+   * ```
+   *
+   * @see {@link PredicateShape} for the bare / spreadBase shape contract.
+   * @see {@link DefaultSpreadBase} for how spreadBase auto-detects from `bare`.
+   * @see {@link PredicateModifiers} for available leaf-level modifier fields.
+   * @see The `gitPlugin` declaration in `plugins/git/index.ts` for a
+   *      multi-predicate registry block (branch, upstream, remote,
+   *      isClean, hasStagedChanges, commitsAhead).
+   * @see `examples/work-item-plugin/` for an end-to-end external-plugin
+   *      reference: handler module, predicate-bare-shape registration,
+   *      and a worked rule + tests.
+   */
+  interface PiSteeringPredicates {
+    // Empty by default. Plugins augment via `declare global`.
+  }
+}
+
+/**
+ * Operator fields on `TopLevelWhenClause`. Currently just `"not"`;
+ * future v0.2 may add `"or"` / `"and"` operators. Kept as a separate
+ * union so reserved-key derivation stays lockstep with operator
+ * additions.
+ */
+export type OperatorField = "not";
+
+/**
+ * Reserved predicate keys derived from `OperatorField | keyof
+ * PredicateModifiers`. Plugin authors cannot register predicates with
+ * these names — they collide with the schema's `not?:` operator field
+ * and the `& PredicateModifiers` intersection on spread forms.
+ *
+ * Adding a new modifier to {@link PredicateModifiers} automatically
+ * reserves its key (lockstep via `keyof`); adding a new operator
+ * requires extending {@link OperatorField}.
+ *
+ * The type-level filter via {@link PluginPredicateKey} removes these
+ * names from the mapped types; the runtime constant
+ * `RESERVED_PREDICATE_KEYS` (in `evaluator-internals/predicates.ts`)
+ * mirrors this set so the engine throws at plugin-registration time
+ * with a concrete error message.
+ */
+export type ReservedPredicateKey = OperatorField | keyof PredicateModifiers;
+
+/**
+ * Plugin-registered predicate keys with reserved names filtered out.
+ * Used as the value-position constraint on {@link OuterValue} /
+ * {@link InnerValue}, and as the `K & PluginPredicateKey`
+ * intersection narrowing inside {@link TopLevelWhenClause} /
+ * {@link TopLevelWhenClauseNoRecurse}. NOT used as the mapped-type
+ * iteration source — those mapped types iterate `keyof
+ * PiSteeringPredicates` directly with an `as`-filter, see their
+ * mapping-shape note for why.
+ */
+export type PluginPredicateKey = Exclude<
+  keyof PiSteeringPredicates,
+  ReservedPredicateKey
+>;
+
+/**
+ * Outer leaf value: the bare form OR the spreadBase intersected with
+ * {@link PredicateModifiers}. Used at the top-level `when:` clause
+ * where each plugin-registered predicate accepts modifiers per-leaf.
+ *
+ * @see TopLevelWhenClause for the surface that consumes this mapped
+ *      type.
+ */
+export type OuterValue<K extends PluginPredicateKey> =
+  | PiSteeringPredicates[K]["bare"]
+  | (PiSteeringPredicates[K]["spreadBase"] & PredicateModifiers);
+
+/**
+ * Inner leaf value (inside `not:`): bare form OR spreadBase WITHOUT
+ * modifiers. Modifiers live at the not-block top level — leaf-level
+ * modifiers inside `not:` are forbidden so the silent fail-OPEN
+ * `not: { cwd: P }` shape can't be reproduced via leaf-level
+ * `onUnknown:` placement.
+ *
+ * @see TopLevelWhenClauseNoRecurse for the surface that consumes this
+ *      mapped type.
+ */
+export type InnerValue<K extends PluginPredicateKey> =
+  | PiSteeringPredicates[K]["bare"]
+  | PiSteeringPredicates[K]["spreadBase"];
+
+/**
+ * Built-in non-registry leaves attached to a {@link Rule.when}
+ * clause — outer flavor.
+ *
+ * These predicates ship with the engine itself (not via a plugin),
+ * so they aren't in {@link PiSteeringPredicates} but DO need to
+ * surface on {@link TopLevelWhenClause} as typed fields.
+ *
+ * The `Writes` generic threads through {@link defineConfig} so that
+ * `when.happened.event` / `when.happened.since` references are
+ * compile-time-checked against the union of declared `writes`
+ * arrays across plugins + observers.
+ *
+ * Currently three non-registry leaves: `happened?:`, `condition?:`,
+ * `cwd?:`. The shape is pinned in tests (a future widening — e.g.,
+ * adding a new built-in `tool?:` leaf — fails the type-pin and
+ * forces a deliberate decision).
+ *
+ * ## Outer / Inner split
+ *
+ * `cwd:`'s spread form differs depending on placement:
+ *
+ * - Outer (rule-level `when:`) — leaf-level `onUnknown?:` allowed,
+ *   honored by the engine's `evaluateCwd` + `projectVerdict` flow.
+ * - Inner (inside `not:`) — leaf-level `onUnknown?:` forbidden
+ *   (parity with registry-driven inner predicates per
+ *   {@link InnerValue}). Walker-unknown cwd inside `not:` projects
+ *   via the block-level `onUnknown:` modifier (default `"block"`).
+ *
+ * Two parallel interfaces formalize this split: this type
+ * (`BuiltInWhenLeavesOuter`) and {@link BuiltInWhenLeavesInner}. The
+ * legacy `BuiltInWhenLeaves` symbol is preserved as a deprecated
+ * alias to `Outer` for backward compatibility — new code should
+ * import the explicit Outer / Inner flavor.
+ *
+ * This is the outer-flavor interface. `cwd?:` accepts
+ * `Pattern | Pattern[] | { pattern, onUnknown? }` (leaf-level
+ * `onUnknown:` honored at the outer when-level via `evaluateCwd` /
+ * `projectVerdict`).
+ *
+ * @see BuiltInWhenLeavesInner for the parallel inner-flavor type
+ *      used inside `not:`.
+ */
+export interface BuiltInWhenLeavesOuter<Writes extends string = string> {
+  /**
+   * Rule fires when the given `event` has NOT happened in the given
+   * scope. Typical usage: "block `cr` unless sync has happened" -
+   * `happened: { event: "rds-ws-sync-done", in: "agent_loop" }`.
+   *
+   * Scopes:
+   *   - `"agent_loop"` - filter session entries by
+   *     `entry.data._agentLoopIndex === ctx.agentLoopIndex`. The engine
+   *     auto-injects that tag on every `appendEntry` write, so plugin
+   *     authors don't have to remember to tag manually.
+   *   - `"session"`    - no scope filter. Any entry of `event` present
+   *     in the session JSONL satisfies.
+   *   - `"tool_call"`  - only consider speculative entries synthesized
+   *     for THIS tool_call's `&&`-chain. Real (persisted) entries are
+   *     ignored entirely. Use when the rule requires the event to be
+   *     CHAINED directly before the guarded command (e.g. `sync && cr`)
+   *     rather than merely "somewhere this agent loop". Pairs naturally
+   *     with observer `writes:` declarations on observers whose
+   *     watch-matched refs produce speculative entries; no-op when no
+   *     observer writes the event.
+   *
+   * Inversion: place inside `not` to flip the clause-level boolean -
+   * `not: { happened: { event, in } }` fires when the event HAS
+   * happened. See ADR §5.
+   *
+   * Optional `since` sentinel (temporal ordering): when present,
+   * `event` is considered "happened" only if its most-recent entry
+   * in scope is newer than the most-recent `since` entry in scope.
+   * If `since` has never been written, the clause behaves as if
+   * `since` were absent (simple presence check on `event`).
+   *
+   * Use for invalidation semantics: "rule fires when sync has not
+   * happened in this agent_loop, OR the last sync is older than the
+   * last upstream-fail." Pattern:
+   *   `happened: { event: SYNC_DONE_EVENT, in: "agent_loop",
+   *                since: UPSTREAM_FAILED_EVENT }`.
+   *
+   * Optional `notIn` (set subtraction over scopes): when present,
+   * entries in `notIn` scope are excluded from the `in`-scoped entry
+   * stream BEFORE the `ts_max` comparison runs. Typical use:
+   * `happened: { event, in: "agent_loop", notIn: "tool_call" }` -
+   * "happened in a prior tool_call in this agent loop". Excludes
+   * same-tool_call speculative entries so `someCmd && guardedCmd`
+   * can't bypass the rule via tool_call-scope speculative synthesis.
+   *
+   * Distinct from the clause-level {@link TopLevelWhenClause.not},
+   * which is boolean negation of a sub-clause. `notIn` is set
+   * subtraction; separate keyword so the two operators can't be
+   * confused.
+   *
+   * Invalid scope combinations throw at evaluation time with the
+   * rule name prefixed:
+   *   - Supersets (e.g. `in: "agent_loop", notIn: "session"`) - the
+   *     subtraction is always empty.
+   *   - Identicals (`notIn === in`) - the subtraction is always empty.
+   *
+   * Compile-time constraint: inside {@link defineConfig}, both the
+   * `event` and `since` fields are narrowed to the union of all
+   * `writes` declared across plugin rules, plugin observers, user
+   * rules, and user observers. Typos become compile errors. Outside
+   * `defineConfig` the `Writes` parameter defaults to `string` so the
+   * check is skipped.
+   */
+  happened?: {
+    event: Writes;
+    in: "agent_loop" | "session" | "tool_call";
+    since?: Writes;
+    notIn?: "agent_loop" | "session" | "tool_call";
+  };
+
+  /**
+   * Escape-hatch predicate for one-off logic. Prefer plugin-registered
+   * predicates when the logic is reusable; use `condition` for
+   * genuinely local checks that don't warrant a plugin.
+   *
+   * Throws (sync or rejected promise) are caught and treated as
+   * `"unknown"`. Outer-level `condition:` is bare-`PredicateFn`-typed
+   * (no spread shape), so the projection always uses the default
+   * `"block"` policy: a throwing condition fires the rule fail-CLOSED.
+   * Authors needing fail-OPEN wrap inside
+   * `not: { condition: fn, onUnknown: "allow" }` (block-level
+   * modifier) OR catch the throw inside the callback body. Mirrors
+   * the plugin-handler exception contract.
+   */
+  condition?: PredicateFn;
+
+  /**
+   * Constrain the rule to commands whose *effective* cwd matches
+   * the given pattern. For bash, the walker's `cwdTracker` resolves
+   * the effective cwd per extracted command (so
+   * `cd ~/personal && git commit --amend` evaluates against
+   * `~/personal`). For write / edit, the session cwd is used directly.
+   *
+   * Bare form: a single {@link Pattern} or an OR-of-patterns array.
+   * Spread form: `{ pattern, onUnknown? }` — the object lets authors
+   * opt into `onUnknown: "allow"` when a command's cwd can't be
+   * statically resolved (e.g. `cd $VAR && ...`). Default is `"block"`
+   * — fail-closed.
+   *
+   * Array form (`Pattern[]` or `{ pattern: Pattern[]; onUnknown? }`)
+   * matches OR-of-patterns: the predicate fires when the resolved cwd
+   * matches ANY of the listed patterns. Empty arrays are invalid (rule
+   * skips); arrays containing non-Pattern values are invalid (rule
+   * skips). Array form sugars vault-path or workspace-tree exemptions:
+   *
+   *   ```ts
+   *   when: { cwd: [/\/Goldmine\//, /\/\.cache\/napkin-distill\//] }
+   *   when: { cwd: { pattern: [/\.test$/, /\.spec$/], onUnknown: "allow" } }
+   *   ```
+   *
+   * `cwd:` is the sole walker-tied built-in leaf; all other dimensions
+   * (`branch`, `upstream`, ...) come from plugins. It lives on
+   * {@link BuiltInWhenLeaves} (not the registry) so authors can write
+   * `when: { cwd: /work/ }` against pi-steering core without needing
+   * gitPlugin's module augmentation in scope.
+   *
+   * See ADR "Design → Override default and `onUnknown`".
+   */
+  cwd?:
+    | Pattern
+    | Pattern[]
+    | { pattern: Pattern | Pattern[]; onUnknown?: "allow" | "block" };
+}
+
+/**
+ * Inner-flavor non-registry built-in leaves. Lives on
+ * {@link TopLevelWhenClauseNoRecurse} (the body of `not:`). `cwd?:`
+ * accepts `Pattern | Pattern[] | { pattern }` — NO leaf-level
+ * `onUnknown?:`. Modifiers live at the not-block level via
+ * `& PredicateModifiers`, matching the constraint registry-driven
+ * inner predicates already enforce via `InnerValue<K>`.
+ *
+ * `happened?:` and `condition?:` are identical to
+ * {@link BuiltInWhenLeavesOuter}; only `cwd:` differs. The engine
+ * reads block-level `onUnknown:` inside `not:` regardless of leaf
+ * shape, so this type formalizes that constraint at the authoring
+ * surface (preventing the silent fail-OPEN class where leaf-level
+ * `onUnknown:` looks meaningful but is ignored at runtime).
+ *
+ * @see BuiltInWhenLeavesOuter for the design rationale, the
+ *      Outer/Inner split, and the parallel outer-flavor type.
+ */
+export interface BuiltInWhenLeavesInner<Writes extends string = string> {
+  /** Identical to {@link BuiltInWhenLeavesOuter.happened}. */
+  happened?: BuiltInWhenLeavesOuter<Writes>["happened"];
+
+  /** Identical to {@link BuiltInWhenLeavesOuter.condition}. */
+  condition?: BuiltInWhenLeavesOuter<Writes>["condition"];
+
+  /**
+   * Same `cwd:` semantics as {@link BuiltInWhenLeavesOuter.cwd} but
+   * the spread form's `onUnknown?:` is dropped — modifiers live at
+   * the not-block level via `& PredicateModifiers`. Walker-unknown
+   * cwd inside `not:` projects via the block-level `onUnknown:`
+   * (default `"block"` = fail-CLOSED, rule fires).
+   */
+  cwd?: Pattern | Pattern[] | { pattern: Pattern | Pattern[] };
+}
+
+/**
+ * Backward-compatible alias for {@link BuiltInWhenLeavesOuter}.
+ *
+ * Retained so external code importing `BuiltInWhenLeaves` (and the
+ * public-surface shape pin in `not-block-onunknown.test.ts`) keeps
+ * working after the Outer/Inner split.
+ *
+ * @deprecated Use {@link BuiltInWhenLeavesOuter} for outer-level
+ * authoring or {@link BuiltInWhenLeavesInner} for `not:` block
+ * bodies. This alias is retained for backward compatibility and may
+ * be removed in a future release.
+ */
+export type BuiltInWhenLeaves<Writes extends string = string> =
+  BuiltInWhenLeavesOuter<Writes>;
+
+/**
+ * Top-level when-clause attached to a {@link Rule}. Each
+ * plugin-registered predicate (filtered for reserved keys) gets a
+ * leaf-level field accepting the bare or spread form. The `not?:`
+ * operator allows one level of negation (no recursion).
+ *
+ * Generic over `Writes` so the built-in `happened?:` leaf's `event` /
+ * `since` references narrow to the union of declared `writes` strings
+ * threaded through by {@link defineConfig}.
+ *
+ * Mapping shape note: the constraint is `keyof PiSteeringPredicates`
+ * with an `as`-filter excluding {@link ReservedPredicateKey}, rather
+ * than the pre-computed alias `[K in PluginPredicateKey]`. Both shapes
+ * produce the same keyset, but only the homomorphic-with-filter form
+ * propagates JSDoc on hover from `PiSteeringPredicates.<key>` source
+ * declarations onto the synthesized field. The `& PluginPredicateKey`
+ * intersection in the value position narrows `K` back to the
+ * constraint expected by {@link OuterValue}. Keep both the constraint
+ * and the `as`-filter inlined — extracting either to a type alias
+ * silently regresses the propagation.
+ *
+ * Hover-on-`defineConfig`-inline-rules caveat: passing rule literals
+ * directly into `defineConfig({ rules: [{ ... }] })` bypasses the
+ * mapped-type linkage — the `const R extends readonly Rule[]`
+ * signature narrows the literal to its `const`-inferred shape.
+ * Factor rules out (`const myRule = { ... } as const satisfies Rule`)
+ * when hover-rich authoring matters; see the {@link defineConfig} JSDoc.
+ *
+ * @see TopLevelWhenClauseNoRecurse for the body of `not:`.
+ * @see PredicateModifiers for available leaf-level modifier fields.
+ * @see BuiltInWhenLeaves for the engine's non-registry leaf set.
+ */
+export type TopLevelWhenClause<Writes extends string = string> = {
+  [K in keyof PiSteeringPredicates as K extends ReservedPredicateKey
+    ? never
+    : K]?: OuterValue<K & PluginPredicateKey>;
+} & BuiltInWhenLeavesOuter<Writes> & {
+    /**
+     * Logical NOT: rule fires when the inner predicates' AND is false.
+     *
+     * Multi-leaf semantics: leaves AND together with Kleene 3-valued
+     * logic. Walker-unknown leaves resolve via the block-level
+     * `onUnknown:` modifier (default `"block"` = fail-CLOSED, rule
+     * fires).
+     *
+     * No leaf-level `onUnknown:` here (forbidden at type level —
+     * modifiers live at the not-block level). No `not:` recursion
+     * (forbidden at type level — semantically equivalent to the
+     * unwrapped form). Nested `not:` is also rejected at runtime by
+     * `validateWhenClauseShape` for JSON / `as any` escape hatches.
+     *
+     * @see TopLevelWhenClauseNoRecurse
+     * @see PredicateModifiers
+     */
+    not?: TopLevelWhenClauseNoRecurse<Writes>;
+  };
+
+/**
+ * Body of a `not:` block: predicates with their bare / spreadBase
+ * forms (NO leaf-level modifiers — modifiers live at this block's top
+ * level via `& PredicateModifiers`). No nested `not:` (no recursion).
+ *
+ * Generic over `Writes` so the built-in `happened?:` leaf inherits
+ * the same compile-time event-narrowing as the outer level.
+ *
+ * Same homomorphic-with-filter mapping shape as
+ * {@link TopLevelWhenClause} (and the same `defineConfig`-inline
+ * caveat). See the mapping-shape note there for the rationale.
+ *
+ * @see TopLevelWhenClause for the rule-attached when-clause.
+ * @see PredicateModifiers for block-level modifier fields.
+ */
+export type TopLevelWhenClauseNoRecurse<Writes extends string = string> = {
+  [K in keyof PiSteeringPredicates as K extends ReservedPredicateKey
+    ? never
+    : K]?: InnerValue<K & PluginPredicateKey>;
+} & BuiltInWhenLeavesInner<Writes> &
+  PredicateModifiers;
+
+/**
+ * Type-erased alias for {@link PredicateHandler} used at registry
+ * boundaries (notably {@link Plugin.predicates}).
+ *
+ * TypeScript treats function-argument types as contravariant: a
+ * `PredicateHandler<CommitsAheadArgs>` is **not** assignable to a
+ * `PredicateHandler<unknown>` because the handler needs to *accept*
+ * `unknown`, while the specialized handler only accepts a narrower
+ * shape. Using `any` at the registry slot leverages TS's bivariance
+ * fallback — specifically-typed handlers assign without a cast, and
+ * the engine's generic call site stays safe because it passes the
+ * matching `when.<name>` value straight through to the handler
+ * (the handler already validates its own arg shape).
+ *
+ * Prefer this alias at any `Record<string, PredicateHandler<…>>`
+ * boundary where the value shape is per-key heterogeneous.
+ *
+ * ## Write-through registry slot, not a safe read type
+ *
+ * This alias exists so heterogeneous handler maps accept typed
+ * handlers cast-free on the WRITE side (plugin author stuffs a
+ * `PredicateHandler<FooArgs>` into `Plugin.predicates`). On the READ
+ * side (a consumer iterating `plugin.predicates`, or a decorator /
+ * middleware layering over a plugin's handlers) the retrieved value
+ * carries `args: any` — no compile-time narrowing. Consumers that
+ * want typed reads should narrow back to `PredicateHandler<TArgs>`
+ * at their call site.
+ *
+ * ## Handler authors: declare `PredicateHandler<YourArgs>`, not this
+ *
+ * Do NOT use `AnyPredicateHandler` as the type annotation for a
+ * handler declaration:
+ *
+ *   // wrong — `args` is `any`, no narrowing inside the body.
+ *   const myHandler: AnyPredicateHandler = (args, ctx) => { ... };
+ *
+ *   // right — narrow `args` at the declaration; the result still
+ *   // assigns cast-free into `Plugin.predicates`.
+ *   const myHandler: PredicateHandler<MyArgs> = (args, ctx) => { ... };
+ *
+ * Also note: because `any` at the boundary disables compile-time
+ * narrowing on the engine's CALL site too, typed handlers MUST
+ * still validate their own `args` shape at the top of the function
+ * body. The engine passes the verbatim `when.<name>` value, so TS
+ * can't protect you from a user writing
+ * `when: { myPredicate: "not-the-shape-you-expected" }`.
+ * (See `isClean`'s `if (typeof args !== "boolean") return false`
+ * pattern for the canonical guard.)
+ */
+export type AnyPredicateHandler = PredicateHandler<any>;
+
+// ---------------------------------------------------------------------------
+// When clause
+// ---------------------------------------------------------------------------
+
+/**
+ * Legacy v0.0.x predicate block; see {@link TopLevelWhenClause} for
+ * the authoring surface attached to {@link Rule.when}.
+ *
+ * The legacy interface is retained as an internal type for the JSON
+ * v1→v2 path in `compat.ts`, where the loose `[customKey: string]:
+ * unknown` index signature is needed to accept arbitrary plugin keys
+ * during deserialization. Plugin authors should NOT type their
+ * helpers against `WhenClause` — use {@link TopLevelWhenClause} for
+ * outer when-clauses or {@link TopLevelWhenClauseNoRecurse} for
+ * not-block bodies (both are registry-driven and enforce the
+ * five compile-time constraints documented on {@link BaseRule.when}).
+ *
+ * Note: even though this legacy interface permits `not: { not: ... }`
+ * recursion at the type level, the engine's runtime
+ * `validateWhenClauseShape` rejects nested-`not` shapes at
+ * `buildEvaluator` time. Authors smuggling depth-2 recursion through
+ * JSON v1 / `as any` casts hit the runtime guard, not silent
+ * acceptance.
+ *
+ * @deprecated Internal v1-compat type. Use {@link TopLevelWhenClause}
+ *             at authoring sites; this interface is preserved only
+ *             for the JSON v1→v2 conversion path in `compat.ts`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export interface WhenClause<Writes extends string = string> {
+  /**
+   * @deprecated Use {@link TopLevelWhenClause}'s `cwd?:` leaf (lifted
+   *             onto {@link BuiltInWhenLeaves}). Retained for v1
+   *             JSON→v2 conversion compatibility only.
+   * @see BuiltInWhenLeaves.cwd
+   */
+  cwd?:
+    | Pattern
+    | Pattern[]
+    | { pattern: Pattern | Pattern[]; onUnknown?: "allow" | "block" };
+
+  /**
+   * @deprecated Use {@link TopLevelWhenClause}'s `happened?:` leaf
+   *             (lifted onto {@link BuiltInWhenLeaves}). Retained for
+   *             v1 JSON→v2 conversion compatibility only.
+   * @see BuiltInWhenLeaves.happened for the canonical semantics
+   *      (scopes, `since`, `notIn`, runtime errors).
+   */
+  happened?: {
+    event: Writes;
+    in: "agent_loop" | "session" | "tool_call";
+    since?: Writes;
+    notIn?: "agent_loop" | "session" | "tool_call";
+  };
+
+  /**
+   * @deprecated Use {@link TopLevelWhenClause}'s `not?:` operator field.
+   */
+  not?: WhenClause<Writes>;
+
+  /**
+   * @deprecated Use {@link TopLevelWhenClause}'s `condition?:` leaf
+   *             (lifted onto {@link BuiltInWhenLeaves}). Retained for
+   *             v1 JSON→v2 conversion compatibility only.
+   * @see BuiltInWhenLeaves.condition
+   */
+  condition?: PredicateFn;
+
+  /**
+   * @deprecated v1-compat loose index signature — plugin-registered
+   *             predicates now live on {@link PiSteeringPredicates}
+   *             with per-key compile-time typing via
+   *             {@link OuterValue} / {@link InnerValue}. Retained for
+   *             v1 JSON→v2 conversion compatibility only.
+   */
+  [customKey: string]:
+    | Pattern
+    | Pattern[]
+    | PredicateFn
+    | WhenClause
+    | { pattern: Pattern; onUnknown?: "allow" | "block" }
+    | { pattern: Pattern | Pattern[]; onUnknown?: "allow" | "block" }
+    | unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Rule (discriminated union by `tool`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fields common to every tool-specific rule variant.
+ *
+ * `BaseRule` is the shared slice - everything except the `tool`
+ * discriminant and the tool-specific {@link BashRule.field} /
+ * {@link WriteRule.field} / {@link EditRule.field} sub-unions. The
+ * exported user-facing type is {@link Rule}, the discriminated union
+ * over the three tool variants; authors should reach for `Rule`
+ * unless they're writing generic rule-handling code that already
+ * knows the tool at its call site.
+ *
+ * Generic parameter `ObsName` constrains the string form of the
+ * {@link observer} field. {@link defineConfig} threads through the union
+ * of observer names gathered from plugins + inline observers, producing
+ * compile-time errors on typos. When authoring rules outside
+ * `defineConfig` (with plain `satisfies SteeringConfig`), the default
+ * `string` flows through and cross-reference checking is skipped.
+ *
+ * See ADR "Design → Rule schema".
+ */
+export interface BaseRule<
+  ObsName extends string = string,
+  Writes extends string = string,
+> {
+  /** Unique rule identifier. Used in override comments and audit logs. */
+  name: string;
+
+  /**
+   * Main match predicate. See {@link Pattern}. The rule fires only
+   * if this matches the chosen `field` value (for bash, the
+   * AST-extracted command string per ref).
+   */
+  pattern: Pattern;
+
+  /**
+   * Optional extra AND predicate - when provided, the rule fires
+   * only if this also matches. Accepts a pattern or a function so
+   * plugins can layer structured checks on top of the main match.
+   */
+  requires?: Pattern | PredicateFn;
+
+  /**
+   * Exemption predicate - when provided and matches, the rule does
+   * NOT fire. Same shape choice as {@link requires}.
+   */
+  unless?: Pattern | PredicateFn;
+
+  /**
+   * Composable predicate block. See {@link TopLevelWhenClause}.
+   *
+   * `Writes` is the union of session-entry event literals the rule's
+   * `when.happened.event` is allowed to reference. Threaded through by
+   * {@link defineConfig} from all declared `writes` arrays in scope.
+   *
+   * The five compile-time constraints from the not-block onUnknown
+   * design land here:
+   *   1. Each plugin-registered predicate is shape-checked against
+   *      its `PiSteeringPredicates[K]` registry entry (bare /
+   *      spreadBase). Typos / unknown predicates surface as
+   *      compile errors at the rule definition.
+   *   2. Reserved keys (`not`, `onUnknown`, plus future modifiers)
+   *      are dropped from the registry-driven mapped type via
+   *      {@link PluginPredicateKey} so a plugin author can't shadow
+   *      the operator/modifier surface.
+   *   3. Leaf-level `onUnknown:` inside `not:` is forbidden (the
+   *      inner mapped type uses {@link InnerValue} which excludes
+   *      modifiers — those live at the not-block top level).
+   *   4. `not: not:` recursion is forbidden
+   *      ({@link TopLevelWhenClauseNoRecurse} has no `not?:` field).
+   *      Belt-and-suspenders runtime guard in
+   *      {@link validateWhenClauseShape} catches JSON / `as any`
+   *      escape hatches.
+   *   5. Rule-level `onUnknown:` is forbidden
+   *      ({@link TopLevelWhenClause} doesn't intersect with
+   *      {@link PredicateModifiers}; only the inner `not:` body does).
+   */
+  when?: TopLevelWhenClause<Writes>;
+
+  /**
+   * Message shown to the agent when blocked.
+   *
+   * A plain string is the most common shape and should be actionable
+   * (e.g. "Use `git commit --no-verify` to bypass"). The evaluator
+   * prefixes every block reason with `[steering:<rule>@<source>] `
+   * so the agent sees which rule fired and where it came from
+   * (ADR §11).
+   *
+   * A {@link ReasonFn} is invoked with the same
+   * {@link PredicateContext} the predicates saw. Use the function
+   * form when the reason text depends on runtime state - e.g. the
+   * walker's effective cwd, a resolved branch name, or a count
+   * pulled from `ctx.findEntries`. The evaluator awaits the return
+   * and applies the source-tag prefix identically to the string form.
+   *
+   * Fail-safe on throw: if the reason function throws synchronously
+   * or its returned promise rejects, the evaluator logs the error
+   * with `console.warn` and emits a fallback message
+   * (`[steering:<rule>@<source>] (reason failed to format; see log)`).
+   * The block verdict still lands - a broken reason doesn't release
+   * the rule's guard or leak raw error text to the LLM.
+   *
+   * Tag→body separator is paragraph-aware: a body containing `\n\n`
+   * (or its CRLF equivalent `\r\n\r\n`, defensive against bodies
+   * imported from Windows line-ending sources — CRLF templating
+   * layers, hand-typed Windows-IDE strings) renders with the
+   * `[steering:...]` tag on its own line followed by a paragraph
+   * break (`\n\n`); otherwise the tag and body share a single
+   * space-separated line. The trigger is double-newline
+   * specifically — single `\n` characters inside an otherwise
+   * single-paragraph body keep the single-space layout. The emitted
+   * separator is always normalized to `\n\n` regardless of which
+   * form (`\n\n` or `\r\n\r\n`) triggered it. Multi-paragraph
+   * reasons get the prefix-on-its-own-line layout automatically
+   * without the rule author managing leading whitespace.
+   *
+   * Body→override-hint separator mirrors the same paragraph-aware
+   * rule. Single-paragraph bodies keep a single-space prefix on the
+   * override hint (byte-identical to the pre-paragraph-aware
+   * rendering); multi-paragraph bodies promote the override hint
+   * to its own paragraph (`${body}\n\n${hint}`) so a safety
+   * paragraph stays visually standalone rather than running on
+   * into an inline "To override" sentence.
+   */
+  reason: string | ReasonFn;
+
+  /**
+   * If `true`, no override escape hatch. If `false`, override always
+   * allowed. Omitted: falls back to
+   * {@link SteeringConfig.defaultNoOverride} (defaults to `true` -
+   * fail-closed).
+   */
+  noOverride?: boolean;
+
+  /**
+   * Observer to attach to this rule. The observer fires on matching
+   * `tool_result` events and can record per-turn state the rule
+   * consults via {@link PredicateContext.findEntries}.
+   *
+   * Either an inline {@link Observer} or a string referencing an
+   * observer registered on a plugin or at the config's top level.
+   * String references are constrained to the union of observer names
+   * known at {@link defineConfig} call sites (typo → compile error).
+   */
+  observer?: Observer | ObsName;
+
+  /**
+   * Session-entry custom types this rule's {@link onFire} may write.
+   *
+   * **Compile-time effect (via {@link defineConfig}):** the union of
+   * all `writes` literals declared across plugin rules, plugin
+   * observers, user rules, and user observers constrains the `event`
+   * field of every {@link BuiltInWhenLeavesOuter.happened} inside the same config.
+   * Declaring a write here makes it referenceable from
+   * `when.happened.event` anywhere in that config; omitting it leaves
+   * the string out of the union and downstream references to it are
+   * rejected as typos.
+   *
+   * **Authoring pattern.** Enforcement depends on TypeScript preserving
+   * the literal types of your `writes` arrays. Use one of:
+   *   - `as const satisfies Rule` on a rule object literal, OR
+   *   - `const satisfies Rule` on an object literal, OR
+   *   - declaring the rule INSIDE the `defineConfig({ rules: [...] })`
+   *     call so inference flows directly through the `const P`, `const R`
+   *     generics.
+   *
+   * **Footgun: bare `: Rule` / `: Observer` / `: Plugin` annotations
+   * widen the literal `writes` array to `readonly string[]`. The engine
+   * can no longer project string-literal members, so `AllWrites`
+   * collapses to `never` - meaning EVERY `when.happened.event`
+   * reference in the config is rejected as a typo, not silently
+   * accepted.
+   *
+   * **Runtime effect:** none. `writes` is purely documentation +
+   * type-level plumbing - the engine does NOT verify that `onFire`
+   * only calls `ctx.appendEntry` with declared types.
+   *
+   * **Opt-out:** authors who build their config via
+   * `satisfies SteeringConfig` instead of `defineConfig` lose the
+   * compile-time check - the `SteeringConfig` shape defaults the
+   * {@link Rule} generics to `string`, so `when.happened.event` is
+   * unconstrained. `defineConfig` is the entry point that enforces.
+   *
+   * The wider warning - "name" / "plugin" literals widening to
+   * `string` - causes the opposite failure: typos in `disabledRules`
+   * / `disabledPlugins` start compiling silently. Always use
+   * `as const satisfies` for reusable constants.
+   */
+  writes?: readonly string[];
+
+  /**
+   * Side-effect hook invoked when the rule decides to fire (all
+   * predicates passed) and BEFORE the block verdict is returned.
+   *
+   * Use for self-marking patterns where the rule's fire IS the event
+   * (e.g. `cr-description-check` - first attempt per agent loop blocks
+   * as reminder, self-marks via `onFire` so subsequent attempts pass).
+   * Anything written via `ctx.appendEntry` gets auto-tagged with the
+   * current `_agentLoopIndex` so a follow-up `when.happened:
+   * { in: "agent_loop" }` check can detect it.
+   *
+   * Timing guarantees:
+   *   - Runs after `pattern` / `requires` / `unless` / `when` have all
+   *     evaluated favourably. If `when.cwd` or any other predicate
+   *     fails, the rule doesn't fire and `onFire` doesn't run.
+   *   - Runs for rules that will actually BLOCK. Rules suppressed by an
+   *     inline override comment do NOT trigger `onFire` - the agent
+   *     overrode the rule, so its side effects are bypassed too.
+   *   - Fail-closed rules (noOverride omitted or true) ignore override
+   *     comments entirely, so `onFire` runs on every fire even when
+   *     the agent wrote an override comment the engine rejected.
+   *
+   * Error handling: `onFire` is a best-effort side effect. If it
+   * throws (sync) or its returned promise rejects, the engine logs
+   * the error with `console.warn` and proceeds to return the block
+   * verdict. The block is not affected by an `onFire` failure - the
+   * block decision already passed every predicate, and a broken
+   * self-mark must not invalidate it. Mirrors the observer
+   * dispatcher's per-observer isolation.
+   *
+   * Async OK: the evaluator awaits.
+   */
+  onFire?: (ctx: PredicateContext) => void | Promise<void>;
+}
+
+/**
+ * Bash rule: gates pi's `bash` tool.
+ *
+ * `field` is constrained to `"command"` - the evaluator always runs
+ * bash rules against the extracted command string per ref (see
+ * `evaluator.ts` bash branch). There is no useful "test a bash rule
+ * against a path" mode: bash has no path. `field: "path"` /
+ * `field: "content"` on a bash rule silently misbehaved in the
+ * previous (non-discriminated) schema; the union here makes the
+ * mistake a compile error.
+ *
+ * Inside a rule's predicates / `onFire`, the context exposes the
+ * extracted command plus `args` (quote-aware `Word[]`) and
+ * `basename` - those are populated per-ref by the evaluator, not by
+ * the rule author.
+ */
+export interface BashRule<
+  ObsName extends string = string,
+  Writes extends string = string,
+> extends BaseRule<ObsName, Writes> {
+  tool: "bash";
+  field: "command";
+}
+
+/**
+ * Write rule: gates pi's `write` tool (whole-file writes).
+ *
+ * `field` picks the input slot the {@link pattern} tests against:
+ *   - `"path"`    - the target path (regex-gate paths a file may be
+ *                  written to).
+ *   - `"content"` - the full file contents the agent is writing.
+ */
+export interface WriteRule<
+  ObsName extends string = string,
+  Writes extends string = string,
+> extends BaseRule<ObsName, Writes> {
+  tool: "write";
+  field: "path" | "content";
+}
+
+/**
+ * Edit rule: gates pi's `edit` tool (targeted oldText/newText patches).
+ *
+ * `field` picks the input slot the {@link pattern} tests against:
+ *   - `"path"`    - the target path.
+ *   - `"content"` - the concatenated `newText` of every edit in the
+ *                  tool call (evaluator joins with `\n`). This mirrors
+ *                  `write.content` so authors can use one rule class
+ *                  for both file surfaces.
+ */
+export interface EditRule<
+  ObsName extends string = string,
+  Writes extends string = string,
+> extends BaseRule<ObsName, Writes> {
+  tool: "edit";
+  field: "path" | "content";
+}
+
+/**
+ * A single steering rule - discriminated union over the three
+ * gatable tools. The `tool` discriminant determines which `field`
+ * values are legal: bash rules test against `"command"`, write / edit
+ * rules test against `"path"` or `"content"`. Invalid combinations
+ * (`{ tool: "bash", field: "path" }`, `{ tool: "write", field:
+ * "command" }`, ...) are TS errors.
+ *
+ * Shape refinements vs. v1:
+ *   - `pattern` accepts `RegExp` in addition to `string`.
+ *   - `requires` / `unless` accept `Pattern | PredicateFn`.
+ *   - `when` is a {@link TopLevelWhenClause} — registry-driven
+ *     mapped type with one level of `not:` allowed (no nested
+ *     `not: not: ...`).
+ *   - `observer` references an {@link Observer} by name (string) or
+ *     inline definition.
+ *   - `Rule` is a discriminated union by `tool`.
+ *
+ * See ADR "Design → Rule schema".
+ */
+export type Rule<
+  ObsName extends string = string,
+  Writes extends string = string,
+> =
+  | BashRule<ObsName, Writes>
+  | WriteRule<ObsName, Writes>
+  | EditRule<ObsName, Writes>;
+
+// ---------------------------------------------------------------------------
+// Observer
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter applied to `tool_result` events before {@link Observer.onResult}
+ * runs. Omitted: the observer fires on every result the engine sees.
+ *
+ * See ADR "Design → Observer schema".
+ */
+export interface ObserverWatch {
+  /**
+   * Only fire on results from this tool. Use to narrow observers that
+   * only care about a specific tool surface (e.g. `read` results).
+   */
+  toolName?: "bash" | "read" | "write" | "edit" | (string & {});
+
+  /**
+   * Per-field regex constraints on the tool INPUT. Observer fires only
+   * when every listed field matches. Keys are tool-input field names
+   * (e.g. `path` for `read`, `command` for `bash`).
+   */
+  inputMatches?: Record<string, Pattern>;
+
+  /**
+   * Constrain by tool exit-code / success-failure classification.
+   *   - `"success"` / `"failure"` - string classification
+   *   - `number`                  - exact exit code match (bash)
+   *   - `"any"`                   - explicit no-filter
+   */
+  exitCode?: number | "success" | "failure" | "any";
+}
+
+/**
+ * Context passed to an observer's {@link Observer.onResult} callback.
+ *
+ * See ADR "Design → Observer schema".
+ */
+export interface ObserverContext {
+  /** Session cwd at the time the tool_result arrived. */
+  cwd: string;
+
+  /**
+   * Monotonically-increasing agent-loop counter maintained by the
+   * engine. Bumped on each `agent_start` pi event (one agent loop =
+   * one user prompt + its tool calls). Observers writing session
+   * entries get this tag auto-injected into the payload so rules
+   * using `when.happened` with `in: "agent_loop"` can filter by it.
+   */
+  agentLoopIndex: number;
+
+  /**
+   * Append a typed entry into pi's session JSONL. Observers
+   * typically use this to record "the agent did X in turn N" so
+   * later predicates can gate on it via
+   * {@link PredicateContext.findEntries}.
+   */
+  appendEntry: <T>(customType: string, data?: T) => void;
+
+  /**
+   * Read all prior typed entries of the given custom type from pi's
+   * session JSONL. Handy for observers that need to coalesce state
+   * across turns (e.g. "has the agent read the CR description yet?").
+   */
+  findEntries: <T>(customType: string) => Array<{ data: T; timestamp: number }>;
+}
+
+/**
+ * A reactive hook: runs on `tool_result` events, typically to record
+ * per-turn state for later predicates to consult.
+ *
+ * Observers are named + deduped (first-registered wins; later
+ * declarations log a WARN). A rule may reference an observer by name
+ * via {@link Rule.observer}, letting plugins ship reusable observers
+ * and multiple rules share a single entry-producing observer.
+ *
+ * See ADR "Design → Observer schema" and "Precedence: first-wins
+ * everywhere".
+ */
+export interface Observer {
+  /**
+   * Unique name. Used for dedup across plugins + inline observers.
+   * Referenced from {@link Rule.observer} as a string.
+   */
+  name: string;
+
+  /**
+   * Session-entry custom types this observer's {@link onResult} may
+   * write.
+   *
+   * **Compile-time effect (via {@link defineConfig}):** the union of
+   * all `writes` literals declared across plugin rules, plugin
+   * observers, user rules, and user observers constrains the `event`
+   * field of every {@link BuiltInWhenLeavesOuter.happened} inside the same config.
+   * Declaring a write here makes it referenceable from
+   * `when.happened.event` anywhere in that config; omitting it leaves
+   * the string out of the union and downstream references to it are
+   * rejected as typos.
+   *
+   * **Authoring pattern.** See {@link Rule.writes} for the full
+   * footgun note - TL;DR: use `as const satisfies Observer` on
+   * reusable observer constants, or declare them inline inside
+   * `defineConfig({ observers: [...] })`. Bare `: Observer` annotations
+   * widen `writes` to `readonly string[]` and collapse `AllWrites` to
+   * `never`, rejecting every `when.happened.event` reference.
+   *
+   * **Runtime effect:** none. `writes` is purely documentation +
+   * type-level plumbing - the engine does NOT verify that `onResult`
+   * only calls `ctx.appendEntry` with declared types.
+   *
+   * **Opt-out:** authors who build their config via
+   * `satisfies SteeringConfig` instead of `defineConfig` lose the
+   * compile-time check. `defineConfig` is the entry point that
+   * enforces.
+   */
+  writes?: readonly string[];
+
+  /**
+   * Filter narrowing which tool_result events trigger this observer.
+   * Omitted: every tool_result fires onResult.
+   */
+  watch?: ObserverWatch;
+
+  /**
+   * Called on every matching tool_result event. Typically writes an
+   * entry via `ctx.appendEntry(customType, data)`; occasionally
+   * performs side effects (logging). Must be idempotent - the same
+   * event MAY fire the observer more than once across pi's
+   * lifecycle (e.g. session restart mid-turn).
+   */
+  onResult: (
+    event: ToolResultEvent,
+    ctx: ObserverContext,
+  ) => void | Promise<void>;
+}
+
+/**
+ * Shape of a tool_result event as observed by an {@link Observer}.
+ *
+ * Intentionally minimal: the fields the schema commits to are the
+ * ones every tool_result carries. Tool-specific `input` / `output`
+ * fields are `unknown` here - observer authors cast to the known
+ * shape for the tool they're watching.
+ */
+export interface ToolResultEvent {
+  /** Tool name the result pertains to (e.g. `"bash"`, `"read"`). */
+  toolName: string;
+  /** Tool input as originally passed to the tool. Shape varies by tool. */
+  input: unknown;
+  /** Tool output / result payload. Shape varies by tool. */
+  output: unknown;
+  /** Exit code (bash) or undefined for non-command tools. */
+  exitCode?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Predicate context
+// ---------------------------------------------------------------------------
+
+/**
+ * Tool input signature reduced to the fields a predicate may read.
+ *
+ * Predicates are tool-agnostic (the same predicate can gate bash, write,
+ * or edit rules). `tool` tells the predicate which discriminator applies;
+ * the evaluator populates whichever fields belong to that tool.
+ *
+ * Bash note (per ADR §9): `command`, `basename`, and `args` are
+ * populated PER extracted command ref - a bash invocation of
+ * `git push --force && ls` runs the predicate once per ref, with
+ * `command: "git push --force"` (flattened for pattern matching),
+ * `basename: "git"`, and `args: [<Word>, <Word>]` (suffix `Word[]`
+ * with quote-aware `.value`). `rawCommand` and full AST node access
+ * are deliberately NOT exposed - the wrapper context would be wrong
+ * for inner refs, and AST walking belongs in plugin code that imports
+ * unbash-walker directly.
+ */
+export interface PredicateToolInput {
+  tool: "bash" | "write" | "edit";
+  /** bash: flattened `basename + args` string, per extracted ref. */
+  command?: string;
+  /**
+   * bash: extracted ref basename (e.g. `"git"` for `/usr/bin/git`).
+   * Sugar over `command.split(/\s+/)[0]` that handles path stripping
+   * correctly. Undefined for non-bash tools.
+   */
+  basename?: string;
+  /**
+   * bash: suffix `Word[]` for the extracted ref - quote-aware
+   * structured access with `.value` giving the lexical value and
+   * `.text` the raw source. Prefer this over splitting `command`
+   * when the predicate needs to preserve quoting (e.g. reading a
+   * `-m "conventional: subject"` message without munging spaces).
+   *
+   * Sourced from `CommandRef.node.suffix` via unbash-walker; the
+   * walker already parses into Word[] so we expose it directly.
+   * Undefined for non-bash tools.
+   */
+  args?: readonly Word[];
+  /**
+   * bash: shell env-assignment prefix for the extracted ref -
+   * `AWS_PROFILE=dev aws s3 ls` exposes `[W("AWS_PROFILE=dev")]`
+   * here (with `args` still `[W("s3"), W("ls")]`). Multiple
+   * assignments come through in source order. Enables plugins to
+   * inspect shell env vars via structured access instead of
+   * regex-on-raw-command.
+   *
+   * Sourced from `CommandRef.node.prefix` via unbash-walker. Each
+   * prefix element is projected into a `Word` whose `.text` preserves
+   * the full `KEY=VALUE` source token (with quoting, if any);
+   * consumers split on `=` to separate key from value. Dynamic
+   * values like `A=$VAR` come through as-is - the token syntax is
+   * visible in `.text`, so callers can detect the expansion
+   * themselves.
+   *
+   * Always an empty array for `write` / `edit` tools (shell env
+   * assignments don't apply to file-surface tools); shaped as
+   * `[]` rather than `undefined` so plugin authors can treat the
+   * field uniformly.
+   */
+  envAssignments?: readonly Word[];
+  /** write / edit: the target path. */
+  path?: string;
+  /** write: the file content being written. */
+  content?: string;
+  /** edit: the replacement edits. Shape preserved from pi's edit tool. */
+  edits?: ReadonlyArray<{ oldText: string; newText: string }>;
+}
+
+/**
+ * Options forwarded to {@link PredicateContext.exec} - narrow surface
+ * over child_process, scoped to the handful of knobs predicates need.
+ */
+export interface ExecOpts {
+  /** Working directory. Defaults to the session cwd. */
+  cwd?: string;
+  /** Max runtime in ms. Predicates should cap this. */
+  timeoutMs?: number;
+}
+
+/**
+ * Return value of {@link PredicateContext.exec}.
+ */
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Shape of the walker-state snapshot the evaluator populates on
+ * {@link PredicateContext.walkerState} for bash rules. Consumed by
+ * the built-in `when.cwd` / `when.happened` predicates and by
+ * plugin-authored predicates that read per-ref tracker state.
+ *
+ * All fields are read-only. The evaluator assembles a fresh object
+ * per extracted command ref - mutation has no effect on subsequent
+ * refs or on any persisted state.
+ *
+ * The type is open-ended (`readonly [key: string]: unknown`) because
+ * plugins register new trackers at config-build time; the schema
+ * can't commit to the complete key set. Plugin authors documenting
+ * their own predicates should narrow via their tracker's known
+ * value type (e.g. the git plugin's branch predicate reads
+ * `ctx.walkerState.branch` as a string | "unknown" sentinel).
+ *
+ * For `write` / `edit` rules there's no walker invocation and
+ * {@link PredicateContext.walkerState} is `undefined`. Bash rules
+ * always see at minimum `{ cwd, env, events }`.
+ */
+export interface WhenWalkerState {
+  /**
+   * Effective cwd at this ref, per the walker's `cwdTracker`. For
+   * dynamic cd targets the walker couldn't resolve statically
+   * (unknown `$VAR`, command substitution, arithmetic), this is the
+   * literal string `"unknown"` - the cwdTracker's sentinel. The
+   * built-in `when.cwd` predicate applies its `onUnknown: 'allow' |
+   * 'block'` policy on that sentinel (default `'block'`, fail-
+   * closed). Plugin predicates reading this field directly should
+   * check for the sentinel before pattern-matching, or use the
+   * sugar form `when.cwd: { pattern, onUnknown }` via the engine.
+   */
+  readonly cwd: string;
+
+  /**
+   * Env map at this ref, per the walker's `envTracker`. Carries
+   * statically-resolved bare assignments (`FOO=bar`), `export`
+   * writes, and `unset` deletions from the current scope, seeded
+   * from `process.env.{HOME, USER, PWD}` at tracker initialization.
+   *
+   * Plugin predicates consume this to expand `$VAR` / `~` in
+   * user-supplied patterns, or to implement a `when.envVar`-style
+   * predicate. Read via `ctx.walkerState.env.get("NAME")`. Returns
+   * `undefined` for any name the walker hasn't seen - callers apply
+   * their own fallback (or route through the `resolveWord` helper
+   * re-exported from the package root for word-level resolution).
+   */
+  readonly env: EnvState;
+
+  /**
+   * Additional tracker-registered fields (e.g. the git plugin's
+   * `branch`) and reserved keys (`events`). Indexed loosely so
+   * plugins adding new trackers don't need a schema amendment.
+   */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Context passed to a predicate (either {@link PredicateFn} or a
+ * plugin's {@link PredicateHandler}).
+ *
+ * Rationale per ADR "Design → Predicate context":
+ *   - `cwd`, `tool`, `input` - what the agent is about to do.
+ *   - `agentLoopIndex` - engine-maintained counter bumped on each
+ *     pi `agent_start` event (one agent loop = one user prompt + its
+ *     tool calls). Rules gate "since the user's last message" state
+ *     by comparing entries' auto-tagged `_agentLoopIndex` against
+ *     `ctx.agentLoopIndex`, which is what `when.happened` with
+ *     `in: "agent_loop"` does internally.
+ *   - `exec` - shell escape hatch. The evaluator memoizes results per
+ *     `(cmd, args, cwd)` within a single tool_call; no cross-call cache.
+ *     This schema commits to the TYPE only - memoization is the
+ *     evaluator's concern (Phase 3).
+ *   - `appendEntry` / `findEntries` - pi's session JSONL mirror of
+ *     what observers write. Predicates consult prior entries to
+ *     implement turn-state checks.
+ */
+export interface PredicateContext {
+  /** Session cwd (or, for bash rules, the effective cwd of the command). */
+  cwd: string;
+
+  /** Which pi tool is being gated. */
+  tool: "bash" | "write" | "edit";
+
+  /** Tool input - evaluator populates whichever fields apply to `tool`. */
+  input: PredicateToolInput;
+
+  /**
+   * Engine-maintained agent-loop counter (bumped on each pi
+   * `agent_start` event). See {@link ObserverContext.agentLoopIndex}.
+   */
+  agentLoopIndex: number;
+
+  /**
+   * Run a command and return its result. Memoized by the evaluator
+   * per `(cmd, args, cwd)` within a single tool_call evaluation.
+   *
+   * Stability guarantee: across rules evaluated for the SAME
+   * tool_call, identical `(cmd, args, cwd)` tuples return the same
+   * ExecResult without re-executing. Across tool_calls, no cache -
+   * the world can change between turns.
+   */
+  exec: (cmd: string, args: string[], opts?: ExecOpts) => Promise<ExecResult>;
+
+  /**
+   * Append a typed entry into pi's session JSONL. Parallels
+   * {@link ObserverContext.appendEntry} so predicates can record
+   * decisions (though typically writing is an observer's job).
+   */
+  appendEntry: <T>(customType: string, data?: T) => void;
+
+  /**
+   * Read all prior typed entries of the given custom type. Used for
+   * turn-state predicates.
+   */
+  findEntries: <T>(customType: string) => Array<{ data: T; timestamp: number }>;
+
+  /**
+   * Walker state snapshot for the command being evaluated. Populated
+   * only for bash rules - the walker runs once per tool_call over the
+   * full command and produces a per-ref snapshot of every registered
+   * tracker (`cwd`, `env`, plus plugin-registered dimensions like
+   * `branch`). For `write` / `edit` rules there is no walker, so this
+   * is `undefined`.
+   *
+   * Plugin predicates consult `walkerState[<tracker-name>]` to read
+   * statically-resolved values (branch after `git checkout X`, cwd
+   * after `cd /path`, env after `FOO=bar` / `export FOO=bar`) without
+   * re-running the tracker's work. When the tracker can't resolve
+   * statically the value is the tracker's `unknown` sentinel -
+   * handlers apply their `onUnknown` policy.
+   *
+   * Typed as {@link WhenWalkerState} (open-ended string-indexed) so
+   * the schema commits to the two built-in keys (`cwd`, `env`) plus
+   * the reserved `events` slot while leaving room for plugin
+   * extensions.
+   *
+   * Reserved key `events`: `Record<customType, SyntheticEntry[]>`.
+   * Populated by the walker-level speculative-entry synthesis pass
+   * (see `evaluator-internals/speculative-synthesis.ts`). Carries
+   * per-ref speculative entries representing "events about to happen"
+   * via continuous `&&` chains from observers' `writes:` declarations.
+   * Each entry carries a `{ data, timestamp, speculative: true }`
+   * shape; timestamps are in a reserved range (above any real entry)
+   * monotonic in AST order. The built-in `when.happened` predicate
+   * merges these with real entries via timestamp comparison;
+   * plugin-authored predicates can opt out by filtering
+   * `e.speculative === true`. Trackers cannot claim the `events`
+   * key - plugin registration rejects it as reserved.
+   */
+  walkerState?: Readonly<WhenWalkerState>;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * A plugin - distribution unit for rule packs and extension points.
+ *
+ * Plugins register zero or more of:
+ *   - {@link predicates}        - new `when.<key>` slots
+ *   - {@link rules}             - bundled rules users can enable/disable
+ *   - {@link observers}         - reusable observer definitions
+ *   - {@link trackers}          - new walker state dimensions
+ *   - {@link trackerExtensions} - modifiers for existing trackers
+ *
+ * See ADR "Design → Plugin schema". Plugin loading precedence is
+ * "first-wins" (project-local → user's `plugins` array → built-in
+ * defaults); name collisions on predicates / rules / observers /
+ * tracker-extensions log a WARN and keep the first-registered entry.
+ * Tracker-*name* collisions are a hard error - two plugins claiming the
+ * same state dimension is always a bug.
+ */
+export interface Plugin {
+  /** Unique plugin identifier. Used for `disabledPlugins` + warning messages. */
+  name: string;
+
+  /**
+   * Predicate handlers keyed by the `when.<key>` slot they register.
+   * See {@link PredicateHandler}.
+   */
+  predicates?: Record<string, AnyPredicateHandler>;
+
+  /** Rules the plugin suggests. Users can opt out via `disabledRules: [...]`. */
+  rules?: readonly Rule[];
+
+  /** Observers the plugin ships. Referenced by name from rules. */
+  observers?: readonly Observer[];
+
+  /**
+   * NEW trackers the plugin introduces. Keys are tracker names (e.g.
+   * `branch`). A name collision between plugins is a hard error.
+   */
+  trackers?: Record<string, Tracker<unknown>>;
+
+  /**
+   * Modifiers added to an EXISTING tracker. Outer key is the tracker
+   * name (e.g. `cwd`), inner key is the command basename the modifier
+   * triggers on (e.g. `git` - to register a `--git-dir=...` parser on
+   * top of the built-in cwd tracker).
+   *
+   * The inner value accepts either a single {@link Modifier} or a
+   * readonly array of them, mirroring {@link Tracker.modifiers} on the
+   * walker side. Plugins can register multiple modifiers under one
+   * `(tracker, basename)` pair - e.g. distinct parsers for different
+   * subcommands of the same CLI that all share a basename.
+   *
+   * Collisions on a `(tracker, basename)` pair log a WARN and keep
+   * the first-registered entry.
+   *
+   * Typed as `unknown` at this schema level - concrete plugins
+   * declare their own modifier types tied to the tracker value they
+   * extend.
+   */
+  trackerExtensions?: Record<
+    string,
+    Record<
+      string,
+      | import("@cad0p/unbash-walker").Modifier<unknown>
+      | readonly import("@cad0p/unbash-walker").Modifier<unknown>[]
+    >
+  >;
+}
+
+// ---------------------------------------------------------------------------
+// SteeringConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Top-level v2 config shape. What a user's `.pi/steering.ts` /
+ * `.pi/steering/index.ts` file default-exports (possibly via
+ * {@link defineConfig} or `satisfies SteeringConfig`).
+ *
+ * The loader walks up from the session cwd to `$HOME`, collects every
+ * layer, and merges them into a single effective config with inner
+ * (closer to cwd) layers taking precedence on name collisions.
+ *
+ * The five array-typed fields (`disabledRules`, `disabledPlugins`,
+ * `plugins`, `rules`, `observers`) are all `readonly`. This is load-
+ * bearing: {@link DefineConfigInput} extends `SteeringConfig` and
+ * narrows each array field with a const-generic-aware subtype (e.g.
+ * `disabledRules` becomes `readonly AllRuleNames<P, R>[]`). TypeScript's
+ * interface-extension check runs on assignability, and `readonly T[]`
+ * is not assignable to `T[]` — demoting any of these fields to a
+ * mutable array would break every typed-name override on
+ * `DefineConfigInput`. The compiler will catch the regression at
+ * the `extends` site, but the choice originates here.
+ *
+ * See ADR "Design → File layout and loader behavior" and
+ * "Design → Override default and `onUnknown`".
+ */
+export interface SteeringConfig {
+  /**
+   * Default value for {@link Rule.noOverride} when a rule doesn't
+   * specify its own. Defaults to `true` (fail-closed - overrides
+   * must be explicit opt-in per rule).
+   *
+   * Walk-up merge: inner layer wins when specified; missing layer
+   * leaves the running value alone.
+   *
+   * `buildConfig` preserves `undefined` in the merged output so
+   * downstream evaluators can distinguish "user didn't specify" from
+   * "user explicitly chose false". The fail-closed `?? true` coercion
+   * happens at evaluator time.
+   *
+   * See ADR "Design → Override default".
+   */
+  defaultNoOverride?: boolean;
+
+  /**
+   * Rules to disable by name. Additive union across layers.
+   *
+   * Past-participle form (`disabledRules`) reads as a predicate on
+   * state - "these are the rules that are disabled." Distinct from
+   * the imperative flag {@link disableDefaults} (action: disable
+   * the default plugins + rules).
+   *
+   * Disabling a rule is by-design behavior, not a configuration
+   * issue — it does NOT contribute to the diagnostic stream. See
+   * {@link SteeringDiagnosticKind} for the by-design-vs-issue carveout.
+   *
+   * **Navigation note:** these are string literals projected from
+   * `DEFAULT_RULES` (engine defaults), `plugin.rules[*].name`, and
+   * inline `rules[*].name`. Ctrl+Click on a literal jumps to the
+   * `AllRuleNames` union, NOT the rule's source — TypeScript-language
+   * limitation on string-literal union members. To inspect a shipped
+   * default's `reason` / `pattern`, import `DEFAULT_RULES` directly:
+   *
+   * ```ts
+   * import { DEFAULT_RULES } from "@cad0p/pi-steering";
+   * // hover DEFAULT_RULES[0] to see the rule body
+   * ```
+   */
+  disabledRules?: readonly string[];
+
+  /**
+   * Plugins to disable by name. Additive union across layers.
+   * A disabled plugin contributes NOTHING - no rules, no observers,
+   * no predicates, no trackers.
+   *
+   * Disabling a plugin is by-design behavior, not a configuration
+   * issue — it does NOT contribute to the diagnostic stream. See
+   * {@link SteeringDiagnosticKind} for the by-design-vs-issue carveout.
+   *
+   * **Navigation note:** same TypeScript-language limitation as
+   * {@link disabledRules} — Ctrl+Click on a string literal jumps to
+   * the `AllPluginNames` union, not the plugin's source. To inspect a
+   * shipped default plugin, import `DEFAULT_PLUGINS` directly:
+   *
+   * ```ts
+   * import { DEFAULT_PLUGINS } from "@cad0p/pi-steering";
+   * // hover DEFAULT_PLUGINS[0] to see the plugin body
+   * ```
+   */
+  disabledPlugins?: readonly string[];
+
+  /**
+   * Skip the package's built-in default plugins + default rules.
+   * Handy for isolated test harnesses or strict minimal configs.
+   *
+   * Kept in imperative form (action flag: "disable the defaults")
+   * to distinguish shape at a glance from the past-participle
+   * {@link disabledRules} / {@link disabledPlugins} lists.
+   *
+   * Walk-up merge: inner layer wins when specified.
+   */
+  disableDefaults?: boolean;
+
+  /**
+   * Strict-mode opt-out. When `true` (default), any warning-class
+   * {@link SteeringDiagnostic} produced while loading the config
+   * escalates to a thrown error that disables the bridge for the
+   * session. When explicitly set to `false`, warnings fall through
+   * to `console.warn` and the bridge keeps running with whatever
+   * subset of plugins / rules / observers loaded successfully.
+   *
+   * Error-class diagnostics ALWAYS throw regardless of this flag
+   * (e.g. tracker name collision, reserved name violation) — the
+   * engine cannot operate safely with those issues present.
+   *
+   * Walk-up merge: inner layer wins when specified, identical to
+   * {@link disableDefaults}.
+   *
+   * Prior art: Rollup's `failAfterWarnings`, Maven's `failOnWarning`.
+   */
+  failOnWarnings?: boolean;
+
+  /** Plugins to load. Order matters for first-wins name collisions. */
+  plugins?: readonly Plugin[];
+
+  /** User-authored rules. */
+  rules?: readonly Rule[];
+
+  /** Inline observers (rules reference by name). */
+  observers?: readonly Observer[];
+}
+
+// ---------------------------------------------------------------------------
+// SteeringDiagnostic
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminator categorizing what kind of issue a diagnostic
+ * describes. Stable across versions so tooling and tests can dispatch
+ * on `kind` without parsing the human-readable {@link
+ * SteeringDiagnostic.message}.
+ *
+ * The set is split between two surfaces:
+ *   - LOADER (`layer-form-coexistence`, `layer-import-failed`,
+ *     `layer-stray-file`, `plugin-name-collision`,
+ *     `rule-name-collision`, `observer-name-collision`,
+ *     `tracker-name-collision`) — produced while walking up the
+ *     filesystem, importing per-layer config files, and merging
+ *     layers into a single effective config. The collision kinds in
+ *     this group flag duplicates surfaced during layer merge — most
+ *     are user-authored (`plugin-name-collision`, `rule-name-collision`,
+ *     `observer-name-collision`), but `tracker-name-collision` flags
+ *     duplicate plugin-shipped trackers when those plugins surface
+ *     together via the merge.
+ *   - PLUGIN-MERGER (`predicate-collision`, `observer-collision`,
+ *     `rule-collision`, `extension-orphan`, `reserved-tracker-name`,
+ *     `reserved-predicate-key`, `invalid-name`) — produced while
+ *     resolving plugin shapes into the runtime registry. The
+ *     collision kinds in this group flag duplicates among
+ *     plugin-author-shipped declarations across the active plugin
+ *     set; `invalid-name` flags a plugin / rule / observer name
+ *     containing characters that are disallowed in source-tagged
+ *     block reasons.
+ *
+ * Disabling a plugin via `config.disabledPlugins` or a plugin-shipped
+ * rule via `config.disabledRules` is by-design behavior, not a
+ * configuration issue, so neither contributes to the diagnostic
+ * stream. Both surface as `console.info` breadcrumbs from
+ * `resolvePlugins` for plugin authors debugging "why isn't my plugin
+ * firing?" — mirrors the unused-observer drop pattern in
+ * `internal/session-runtime.ts`.
+ */
+export type SteeringDiagnosticKind =
+  /**
+   * Both `.pi/steering/index.ts` AND `.pi/steering.ts` exist at the
+   * same directory. The directory form wins; the flat form is
+   * ignored. Almost always a forgotten cleanup; delete the unused
+   * file to silence the diagnostic.
+   */
+  | "layer-form-coexistence"
+  /**
+   * A layer's `.pi/steering/index.ts` (or `.pi/steering.ts`) was
+   * found on disk but its dynamic import threw — typically a syntax
+   * error or a missing default export. The layer is skipped; outer
+   * layers continue to load.
+   */
+  | "layer-import-failed"
+  /**
+   * A non-`.ts` file lives under `<dir>/.pi/steering/` (e.g.
+   * `rules.json`, `rules.mjs`). Helpers ending in `.ts` are allowed;
+   * other extensions are flagged so the user can rename or delete
+   * the stray file.
+   */
+  | "layer-stray-file"
+  /**
+   * Two layers register a plugin with the same `name`. The inner
+   * (closer to cwd) layer wins; the outer layer's plugin is dropped.
+   */
+  | "plugin-name-collision"
+  /**
+   * A single layer declares two rules under the same `name`. The
+   * first-declared rule survives; subsequent duplicates are dropped.
+   * Cross-layer rule shadowing is intentional and not flagged.
+   */
+  | "rule-name-collision"
+  /**
+   * A single layer declares two observers under the same `name`.
+   * The first-declared observer survives; subsequent duplicates are
+   * dropped. Cross-layer observer shadowing is intentional and not
+   * flagged.
+   */
+  | "observer-name-collision"
+  /**
+   * Two plugins both register a tracker under the same name. Always
+   * an error — two plugins claiming the same state dimension is a
+   * bug, not a soft override. Rename one tracker or disable one
+   * plugin.
+   */
+  | "tracker-name-collision"
+  /**
+   * Two plugins both register a predicate handler under the same
+   * `when.<key>`. The first-registered handler wins; the later
+   * plugin's handler is dropped.
+   */
+  | "predicate-collision"
+  /**
+   * Two plugins both register an observer with the same `name`.
+   * The first-registered observer wins; the later plugin's observer
+   * is dropped. Distinct from `observer-name-collision` which
+   * applies to within-layer duplicates in user-authored config.
+   */
+  | "observer-collision"
+  /**
+   * Two plugins both ship a rule with the same `name`. The
+   * first-registered rule wins; the later plugin's rule is dropped.
+   * Distinct from `rule-name-collision` which applies to
+   * within-layer duplicates in user-authored config.
+   */
+  | "rule-collision"
+  /**
+   * A plugin's `trackerExtensions` references a tracker name that
+   * no plugin (and no built-in walker tracker) registers. The
+   * extension is ignored.
+   */
+  | "extension-orphan"
+  /**
+   * A plugin attempts to register a tracker under a reserved name
+   * (e.g. `events`). Always an error — reserved names are owned by
+   * the engine. Rename the tracker.
+   */
+  | "reserved-tracker-name"
+  /**
+   * A plugin attempts to register a predicate handler under a
+   * reserved key (an operator field like `not` or a modifier key
+   * like `onUnknown`). Always an error — reserved keys collide
+   * with the schema's operator/modifier surface. Rename the
+   * predicate.
+   */
+  | "reserved-predicate-key"
+  /**
+   * A plugin / rule / observer name contains characters that are
+   * disallowed in the `[steering:<name>@<source>]` block-reason
+   * tag shown to the LLM, in `disabledRules` / `disabledPlugins`
+   * config references, or in override-comment targets. Always an
+   * error — names flow into user-visible strings and a malformed
+   * (or maliciously-crafted) name lets a config author forge
+   * block reasons that deceive the agent. Allowed: letters,
+   * digits, underscores, dashes; must start with a letter or
+   * digit. Rename the offending object in source.
+   */
+  | "invalid-name";
+
+/**
+ * Structured issue surfaced while loading a steering config.
+ *
+ * Diagnostics flow up from the loader and the plugin merger into the
+ * bridge runtime, which decides whether to throw or log per the user's
+ * strict-mode preference. The shape is stable so tests and future
+ * tooling can dispatch on {@link kind} without scanning {@link message}
+ * substrings.
+ *
+ * Channel-ownership split (loader / merger vs. runtime). Diagnostics
+ * captured in this stream are by-design surfaced to the strict-mode
+ * runtime so it can decide whether to throw or pass through to
+ * `console.warn`. The loader (`loader.ts`) does not call
+ * `console.*` directly — the runtime owns the policy decision.
+ * However, by-design info breadcrumbs that are NOT configuration
+ * issues (`disabledPlugins` and `disabledRules` opt-outs from
+ * `resolvePlugins`, dropped-observer notices from
+ * `dropUnusedObservers`) go directly to `console.info` from where
+ * they're produced. They're not in this kind union because they
+ * describe normal behavior the user opted into, not problems that
+ * need actioning.
+ *
+ * Render-format matrix — the same diagnostic surfaces in two
+ * shapes depending on which renderer the runtime picks:
+ *
+ *   - Multi-line aggregate (thrown `Error` from `buildSessionRuntime`):
+ *     a header line ("N config issues:") followed by a per-line bullet
+ *     `  - [type] <path: >?<message>`. One `Error.message`, multi-line.
+ *     Used when at least one diagnostic must abort the session.
+ *     Produced by `formatAggregatedDiagnostics`.
+ *   - Single-line per-diagnostic (`formatSingleLineDiagnostic`):
+ *     `[pi-steering] [<severity>] <path: >?<message>` per diagnostic.
+ *     Severity tag (`[error]` / `[warning]`) follows the same
+ *     bracketed convention as the multi-line aggregate's per-line
+ *     bullets. Routed to `console.warn` for legacy fail-soft mode
+ *     (`failOnWarnings: false`). Only warnings reach this route in
+ *     practice — error-class diagnostics escalate to a thrown error
+ *     via the aggregated form before warnings are flushed. Also
+ *     routed to stderr for the CLI `pi-steering list` pre-flight
+ *     surface (both warnings and errors render here; the bracketed
+ *     severity tag distinguishes them). The function itself accepts
+ *     both severities; the warnings-only narrowing is a property of
+ *     the `console.warn` route's caller, not the formatter.
+ *
+ * The CLI prints diagnostics inline as the loader yields them, rather
+ * than aggregating into a thrown error — the single-line shape
+ * gives `pi-steering list` users immediate per-issue feedback.
+ */
+export interface SteeringDiagnostic {
+  /**
+   * Severity of the diagnostic.
+   *
+   *   - `"warning"` — informational; safe to ignore in legacy
+   *     fail-soft mode.
+   *   - `"error"` — pi-steering cannot operate safely with this
+   *     issue present (e.g. tracker name collision); always escalates
+   *     to a thrown error regardless of the user's strict-mode
+   *     preference.
+   */
+  type: "warning" | "error";
+
+  /** Discriminator for programmatic dispatch and test assertions. */
+  kind: SteeringDiagnosticKind;
+
+  /** Agent-facing message; includes context like layer path or names. */
+  message: string;
+
+  /**
+   * Source path, when applicable. Per kind:
+   *   - `layer-import-failed`: the source file the loader couldn't import.
+   *   - `layer-stray-file`: the stray file under `.pi/steering/`.
+   *   - `layer-form-coexistence`: the directory holding both forms
+   *     (`.pi/steering.ts` AND `.pi/steering/index.ts`); the dir is
+   *     intentional rather than picking one of the two coexisting files
+   *     arbitrarily.
+   *   - Within-layer collisions (`rule-name-collision`,
+   *     `observer-name-collision`): unset (the diagnostic names the
+   *     offending object inside `message`).
+   *   - Cross-layer collisions and plugin-shipped diagnostics
+   *     (`plugin-name-collision`, `tracker-name-collision`,
+   *     `predicate-collision`, `observer-collision`, `rule-collision`,
+   *     `extension-orphan`, `reserved-tracker-name`,
+   *     `reserved-predicate-key`, `invalid-name`): unset by design.
+   *     These diagnostics name the participants (layer paths or
+   *     plugin names) inside `message` because there is no single
+   *     source path — the collision spans multiple layers or
+   *     plugins.
+   */
+  path?: string;
+}