pi-warden 0.40.1 → 0.40.2

package/CHANGELOG.md

@@ -8,6 +8,13 @@ How to keep this current: add the entry in the same pull request as the change,
 
 <!-- Empty. Next release starts here. -->
 
+## 0.40.2
+
+### Fixed
+
+- The first-run notice no longer names a fallback document when `rules.files` is what resolved. It was decided by whether `pi-warden.md` existed, so a project whose rules come from `rules.files` was told `AGENTS.md` was judging it while its own configured files were the ones in force — and the notice's remedy, creating a `pi-warden.md`, is the one thing that shadows those files. The notice now asks the rule store which tier answered and fires only when a fallback document really is in force, listing `rules.files` among the tiers it looked at.
+- The escalation request carries the rules the config resolves, not a document of the resolver's own choosing. It walked `pi-warden.md` and then `AGENTS.md` / `CLAUDE.md` / `README.md` while the rules guard was judging with `rules.files`, so a project with configured rules sent `AGENTS.md` prose as its rules, or no rules at all when it had no such file. It now takes every file in `rules.files`, in order, before the fallback names, and honors `rules.fallback: false`.
+
 ## 0.40.1
 
 ### Fixed

package/README.md

@@ -68,7 +68,7 @@ paths: src/**/*.ts
 Every exported function declares its return type.
 ```
 
-Jev judges every write and quotes violations back. Rules can be things no linter checks: "a TODO must name a ticket", "comments must not restate the code". Without `pi-warden.md`, the first of `README.md`/`CLAUDE.md`/`AGENTS.md` is judged instead. [Examples and config details.](docs/configuration.md)
+Jev judges every write and quotes violations back. Rules can be things no linter checks: "a TODO must name a ticket", "comments must not restate the code". Without `pi-warden.md`, the first of `AGENTS.md`/`CLAUDE.md`/`README.md` is judged instead. [Examples and config details.](docs/configuration.md)
 
 ## Does it actually help?
 

package/dist/action-guard.d.ts

@@ -1,5 +1,5 @@
-import type { ActionGuardConfig, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
-import type { PreviousAction, TaskMessage, Verdict } from "./guard.js";
+import type { ActionGuardConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { EvaluateOptions, PreviousAction, TaskMessage, Verdict } from "./guard.js";
 import type { Judge } from "pi-typesafe";
 /** One tool call as the agent proposed it. `id` is Pi's tool call id, stable across hooks and retries. */
 export interface ToolCallRef {
@@ -25,8 +25,8 @@ export interface InspectOptions {
     signal?: AbortSignal | undefined;
     slop?: SlopGuardConfig | undefined;
     security?: SecurityConfig | undefined;
-    /** The rules guard's switch; off keeps the rules file content out of the action request. Omitted, it is sent as before. */
-    rules?: Pick<RulesConfig, "enabled"> | undefined;
+    /** The rules guard's switch, forwarded to `evaluateAction`: off keeps the rules content out of the request. */
+    rules?: EvaluateOptions["rules"];
     /** Calls allowed in the previous turn; the regret question about them rides this call's request, never a sibling's. */
     previousActions?: readonly PreviousAction[] | undefined;
 }

package/dist/extension.js

@@ -20,7 +20,7 @@ import { evaluateProse, proseNudge, ProseTrend, RESTATE_MIN_SENTENCES, RESTATE_S
 import { compressOutput, duplicateNote, evaluateOutput, mergeOutput, outputKey, saveOutput, securityNotice, CompressionLearner } from "./output.js";
 import { classifyRecall, detectSearchTool, recallInstruction } from "./recall.js";
 import { redact } from "./redact.js";
-import { formatRules, pathNoteSteer, RulesGuard, rulesSteer } from "./rules.js";
+import { formatRules, pathNoteSteer, RulesGuard, rulesSteer, RULES_FILE, FALLBACK_FILES } from "./rules.js";
 import { checkPiWardenMissing } from "./rules-file.js";
 import { writeStarterRules, buildInitPrompt } from "./init.js";
 import { buildAuditPrompt, findProjects, snapshotReport, reportOutcome } from "./audit.js";
@@ -1060,14 +1060,17 @@ export default function wardenExtension(pi) {
         if (!config.action.enabled || !config.action.tools.includes(event.toolName))
             return;
         stats.inspected++;
-        // First-run warning: pi-warden.md missing, one time per session.
+        // First-run warning: no project rules file resolved, one time per session.
         if (!warnedMissingRules && config.rules.enabled) {
-            const { missing, fallbackSource } = checkPiWardenMissing(ctx.cwd);
+            const { missing, fallbackSource } = checkPiWardenMissing(ctx.cwd, config.rules);
             if (missing && ctx.hasUI) {
                 warnedMissingRules = true;
+                // The tiers still in play, in resolution order: naming README/CLAUDE/AGENTS to someone who
+                // turned the fallback off would send them to a document pi-warden will not read.
+                const tiers = [RULES_FILE, "rules.files", ...(config.rules.fallback ? FALLBACK_FILES : [])].join(", ");
                 const msg = fallbackSource
-                    ? `No pi-warden.md detected. Using ${fallbackSource} as active fallback rules. Run /warden init to create project-specific rules.`
-                    : `No rules file detected (pi-warden.md, README.md, CLAUDE.md, or AGENTS.md). Run /warden init to create project-specific rules.`;
+                    ? `No pi-warden.md or rules.files entry here. Using ${fallbackSource} as active fallback rules. Run /warden init to create project-specific rules.`
+                    : `No rules file detected (${tiers}). Run /warden init to create project-specific rules.`;
                 ctx.ui.notify(msg, "warning");
             }
         }

package/dist/guard.d.ts

@@ -1,5 +1,6 @@
 import type { IntegrationErrorCode, Judge, Questions } from "pi-typesafe";
 import type { ActionGuardConfig, ArmingRule, CommandRule, PathRule, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { RulesSourceConfig } from "./rules.js";
 export type Level = "allow" | "warn" | "confirm" | "deny";
 export type Severity = "destructive" | "risky" | "sensitive" | "deny";
 export type ViolationSource = "pattern" | "rules-guard" | "security-guard" | "slop-guard";
@@ -171,11 +172,12 @@ export interface EvaluateOptions {
     slop?: SlopGuardConfig | undefined;
     security?: SecurityConfig | undefined;
     /**
-     * The rules guard's switch. The active rules file rides every judged action request, so `enabled: false` is what keeps
-     * that content on this machine. Omitted, the file is sent as before, so a library caller that passes no rules config
-     * keeps today's behaviour.
+     * The rules guard's switch. The rules the active config resolves ride every judged action request, so
+     * `enabled: false` is what keeps that content on this machine. `files` and `fallback` say which documents
+     * those are; omitting them sends what the config would resolve unfiltered, so a library caller that passes
+     * no rules config keeps today's behaviour.
      */
-    rules?: Pick<RulesConfig, "enabled"> | undefined;
+    rules?: Pick<RulesConfig, "enabled"> & Partial<RulesSourceConfig> | undefined;
     /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
     retryAfterHold?: boolean | undefined;
     /** Calls allowed in the previous turn: ask whether the user's latest message regrets one of them (rides this request). */

package/dist/guard.js

@@ -877,8 +877,9 @@ export async function evaluateAction(action, options) {
     if (!judge)
         return withPlan({ level, source: "pattern", summary, patterns, reasons });
     // Resolve the rules file once per call for the Jev request state. With the rules guard off, no rules content leaves
-    // the machine at all: no question names the field, so an absent one costs nothing.
-    const resolved = options.rules?.enabled === false ? null : resolveRulesFile(action.cwd);
+    // the machine at all: no question names the field, so an absent one costs nothing. The config decides which files
+    // count, so the content sent here is the content the guard judges with.
+    const resolved = options.rules?.enabled === false ? null : resolveRulesFile(action.cwd, options.rules);
     const floorHits = builtInHits.length ? builtInHits.join("; ") : "none";
     const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context, previousActions: options.previousActions, plan, questions: options.questions, rules: resolved?.content, rulesSource: resolved?.source, violations: remainingViolations, floorHits });
     const result = await ask(judge, request, { timeoutMs: config.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export type { WidgetConfig, WidgetPlacement, WidgetBarMode, Tokens } from "./wid
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";
 export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
-export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef } from "./rules.js";
+export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef, RulesTier, RulesSourceConfig } from "./rules.js";
 export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
 export type { ResolvedRulesFile } from "./rules-file.js";
 export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";

package/dist/rules-file.d.ts

@@ -1,18 +1,33 @@
+import type { RulesConfig } from "./config.js";
+import type { RulesSourceConfig } from "./rules.js";
 /**
- * Resolved active rules file for escalation and context.
- * Resolution order: pi-warden.md → AGENTS.md → CLAUDE.md → README.md.
+ * The rules content for escalation and context. The order is the rules guard's: pi-warden.md alone, else the files in
+ * `rules.files`, in order, else the fallback names while `rules.fallback` is on. An empty document counts where the
+ * guard counts it: a configured file is a source whatever it holds, a fallback document has to say something.
  */
 export interface ResolvedRulesFile {
-    path: string;
     content: string;
+    /** The file name, or the configured names joined by commas, as the config spells them. */
     source: string;
 }
 /** Token-aware truncation: extract heading blocks, cap at maxTokens (1 token ≈ 4 chars). */
 export declare function extractRules(content: string, maxTokens?: number): string;
-/** Resolve the active rules file. Returns the first existing file, or null. Content is redacted before it leaves this machine. */
-export declare function resolveRulesFile(cwd: string): ResolvedRulesFile | null;
-/** Returns missing status and the fallback source if pi-warden.md is absent. */
-export declare function checkPiWardenMissing(cwd: string): {
+/**
+ * Resolve the rules content the escalation request carries. Returns null when the config reaches no document.
+ *
+ * `RuleStore` judges with the documents this returns, in this order, so the request names the rules in force. What
+ * differs is the cap: the request carries one budget for the whole field (`MAX_CHARS`) where the guard spends
+ * `rules.maxChars` per resolution.
+ */
+export declare function resolveRulesFile(cwd: string, config?: Partial<RulesSourceConfig>): ResolvedRulesFile | null;
+/**
+ * Whether the first-run "no project rules" notice should fire, and which document is being judged.
+ *
+ * RuleStore.loadTiered owns the resolution order, so ask it which tier answered instead of walking
+ * the filesystem here. Inferring one warns while the configured files are the ones in force, names a
+ * fallback document the config turned off, or names a `rules.files` entry after the file it points at.
+ */
+export declare function checkPiWardenMissing(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): {
     missing: boolean;
-    fallbackSource?: string;
+    fallbackSource?: string | undefined;
 };

package/dist/rules-file.js

@@ -1,12 +1,20 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { resolve } from "node:path";
 import { redact } from "./redact.js";
-import { RULES_FILE, FALLBACK_FILES } from "./rules.js";
-const RULES_CANDIDATES = [
-    { path: RULES_FILE, source: RULES_FILE },
-    ...FALLBACK_FILES.map(f => ({ path: f, source: f })),
-];
+import { RuleStore, RULES_FILE, FALLBACK_FILES } from "./rules.js";
 const MAX_CHARS = 16_000; // ~4000 tokens
+/** A rules file's text, or undefined when it is missing, unreadable, or a directory. */
+function readRules(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        // Unreadable or non-file entries (e.g., directories matching a candidate name) are skipped.
+        return undefined;
+    }
+}
 /** Token-aware truncation: extract heading blocks, cap at maxTokens (1 token ≈ 4 chars). */
 export function extractRules(content, maxTokens = 4000) {
     const lines = content.split("\n");
@@ -41,32 +49,54 @@ export function extractRules(content, maxTokens = 4000) {
     }
     return result.join("\n\n");
 }
-/** Resolve the active rules file. Returns the first existing file, or null. Content is redacted before it leaves this machine. */
-export function resolveRulesFile(cwd) {
-    for (const candidate of RULES_CANDIDATES) {
-        const fullPath = join(cwd, candidate.path);
-        if (existsSync(fullPath)) {
-            let raw;
-            try {
-                raw = readFileSync(fullPath, "utf8");
-            }
-            catch {
-                // Unreadable or non-file entries (e.g., directories matching a candidate name) are skipped.
-                continue;
-            }
-            const content = raw.length > MAX_CHARS ? redact(extractRules(raw)) : redact(raw);
-            return { path: fullPath, content, source: candidate.source };
-        }
+/** Content is redacted before it leaves this machine, and capped once it is past the budget. */
+function redactAndCap(source, raw) {
+    return { content: raw.length > MAX_CHARS ? redact(extractRules(raw)) : redact(raw), source };
+}
+/**
+ * Resolve the rules content the escalation request carries. Returns null when the config reaches no document.
+ *
+ * `RuleStore` judges with the documents this returns, in this order, so the request names the rules in force. What
+ * differs is the cap: the request carries one budget for the whole field (`MAX_CHARS`) where the guard spends
+ * `rules.maxChars` per resolution.
+ */
+export function resolveRulesFile(cwd, config) {
+    const root = resolve(cwd, RULES_FILE);
+    const rootContent = readRules(root);
+    if (rootContent !== undefined)
+        return redactAndCap(RULES_FILE, rootContent);
+    const configured = [];
+    for (const entry of config?.files ?? []) {
+        const content = readRules(resolve(cwd, entry));
+        if (content !== undefined)
+            configured.push({ source: entry, content });
+    }
+    if (configured.length) {
+        return redactAndCap(configured.map(file => file.source).join(", "), configured.map(file => file.content).join("\n\n"));
+    }
+    if (config?.fallback === false)
+        return null;
+    for (const file of FALLBACK_FILES) {
+        const content = readRules(resolve(cwd, file));
+        // A blank fallback document is not a source: the store walks on to the next name, so this does too.
+        if (content?.trim())
+            return redactAndCap(file, content);
     }
     return null;
 }
-/** Returns missing status and the fallback source if pi-warden.md is absent. */
-export function checkPiWardenMissing(cwd) {
-    if (existsSync(join(cwd, "pi-warden.md")))
-        return { missing: false };
-    for (const candidate of RULES_CANDIDATES.slice(1)) {
-        if (existsSync(join(cwd, candidate.path)))
-            return { missing: true, fallbackSource: candidate.source };
-    }
-    return { missing: true };
+const missingStore = new RuleStore();
+/**
+ * Whether the first-run "no project rules" notice should fire, and which document is being judged.
+ *
+ * RuleStore.loadTiered owns the resolution order, so ask it which tier answered instead of walking
+ * the filesystem here. Inferring one warns while the configured files are the ones in force, names a
+ * fallback document the config turned off, or names a `rules.files` entry after the file it points at.
+ */
+export function checkPiWardenMissing(cwd, config) {
+    const { set, tier } = missingStore.loadTiered(cwd, config);
+    if (tier === "none")
+        return { missing: true };
+    // A project that has a rules source of its own is not missing one, empty file or not: /warden init
+    // would name the file the project already has, and a pi-warden.md would shadow a bound `rules.files`.
+    return tier === "fallback" ? { missing: true, fallbackSource: set?.sources[0] } : { missing: false };
 }

package/dist/rules.d.ts

@@ -5,7 +5,7 @@ import type { RulesConfig } from "./config.js";
  * agent is steered, never held, with the violated rule. Path scoping and sensitive-path notes are code only.
  *
  * Sources, in order: `pi-warden.md` at the project root; else the files in `rules.files`; else, with `rules.fallback`, the
- * first of README.md, CLAUDE.md, AGENTS.md as one aggregate rule set. Files are re-read when their mtime or size changes.
+ * first of AGENTS.md, CLAUDE.md, README.md as one aggregate rule set. Files are re-read when their mtime or size changes.
  */
 export interface Rule {
     id: string;
@@ -27,6 +27,13 @@ export interface RuleSet {
     proseOnly?: boolean;
 }
 export declare const RULES_FILE = "pi-warden.md";
+/** Which tier of the resolution order answered; `none` means no source resolved. */
+export type RulesTier = "root" | "configured" | "fallback" | "none";
+/**
+ * The parts of `rules` that decide which document is in force. A caller that cannot supply them gets
+ * the default fallback behaviour, the same as a project config that omits the keys.
+ */
+export type RulesSourceConfig = Pick<RulesConfig, "files" | "fallback">;
 export declare const FALLBACK_FILES: string[];
 /** TypeSafe answers at most 32 questions per request; one is kept for the edit locator. */
 export declare const MAX_RULES = 31;
@@ -54,6 +61,11 @@ export declare function projectPath(target: string, cwd: string): string | undef
 export declare class RuleStore {
     private readonly cache;
     private read;
+    /** Where a rule set came from; the order is the resolution order. */
+    loadTiered(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): {
+        set: RuleSet | undefined;
+        tier: RulesTier;
+    };
     /** The active rule set for a project, or undefined when no source exists. Never throws. */
     load(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): RuleSet | undefined;
 }

package/dist/rules.js

@@ -218,26 +218,30 @@ export class RuleStore {
             return undefined;
         }
     }
-    /** The active rule set for a project, or undefined when no source exists. Never throws. */
-    load(cwd, config) {
+    /** Where a rule set came from; the order is the resolution order. */
+    loadTiered(cwd, config) {
         const root = this.read(resolve(cwd, RULES_FILE));
         if (root !== undefined)
-            return ruleSet([RULES_FILE], [root], config.maxChars);
+            return { set: ruleSet([RULES_FILE], [root], config.maxChars), tier: "root" };
         const configured = config.files.map(file => ({ file, text: this.read(resolve(cwd, file)) })).filter((entry) => entry.text !== undefined);
         if (configured.length)
-            return ruleSet(configured.map(entry => entry.file), configured.map(entry => entry.text), config.maxChars);
+            return { set: ruleSet(configured.map(entry => entry.file), configured.map(entry => entry.text), config.maxChars), tier: "configured" };
         if (!config.fallback)
-            return undefined;
+            return { set: undefined, tier: "none" };
         for (const file of FALLBACK_FILES) {
             const text = this.read(resolve(cwd, file));
             if (text !== undefined && text.trim()) {
                 const redacted = redact(text);
                 if (isRuleShaped(text))
-                    return { sources: [file], rules: [], aggregate: condense(redacted, config.maxChars), dropped: 0 };
-                return { sources: [file], rules: [], dropped: 0, proseOnly: true };
+                    return { set: { sources: [file], rules: [], aggregate: condense(redacted, config.maxChars), dropped: 0 }, tier: "fallback" };
+                return { set: { sources: [file], rules: [], dropped: 0, proseOnly: true }, tier: "fallback" };
             }
         }
-        return undefined;
+        return { set: undefined, tier: "none" };
+    }
+    /** The active rule set for a project, or undefined when no source exists. Never throws. */
+    load(cwd, config) {
+        return this.loadTiered(cwd, config).set;
     }
 }
 function ruleSet(sources, texts, maxChars) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "Makes the Pi agent follow your project's rules. Jev judges every write against your pi-warden.md and quotes the broken rule back to the agent, names slop, breaks stuck loops, calls out unverified done claims, compresses large tool output, and holds the rare destructive command. Built on pi-typesafe.",
   "type": "module",
   "license": "MIT",