pi-warden 0.71.0 → 0.74.0

package/dist/guard.d.ts

@@ -3,6 +3,7 @@ import type { IntegrationErrorCode, Judge, Questions } from "pi-typesafe";
 import type { ActionGuardConfig, ArmingRule, CommandRule, LargeOutputConfig, PathRule, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
 import type { TaskSpine } from "./shape.js";
 import type { RulesSourceConfig } from "./rules.js";
+import type { HostDirs } from "./host-dirs.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";
@@ -279,7 +280,7 @@ export declare function hostPaths(env?: NodeJS.ProcessEnv): string[];
  * write. The rest of Pi's agent directory stays held: `auth.json`, `settings.json`, pi-warden's own `config.json`, and
  * other extensions' data.
  */
-export declare function wardenHostPaths(env?: NodeJS.ProcessEnv): string[];
+export declare function wardenHostPaths(env?: NodeJS.ProcessEnv, dirs?: HostDirs): string[];
 /** The temp root a real path lies strictly under; a temp root itself has none. */
 export declare function tempRootOf(real: string, roots?: string[]): string | undefined;
 /** How much of the target trees one rm segment may walk: entries seen, and the clock time it must finish by. */

package/dist/guard.js

@@ -468,16 +468,16 @@ export function hostPaths(env = process.env) {
  * write. The rest of Pi's agent directory stays held: `auth.json`, `settings.json`, pi-warden's own `config.json`, and
  * other extensions' data.
  */
-export function wardenHostPaths(env = process.env) {
-    const index = safeIndexDir(env);
+export function wardenHostPaths(env = process.env, dirs) {
+    const index = safeIndexDir(env, dirs);
     return [...new Set([...hostPaths(env), ...(index ? [index] : [])])];
 }
 /**
  * The real index directory, or undefined when a symlink could move it: the index directory or a directory between it
  * and the agent directory is a symlink, or its real path is not inside the real agent directory.
  */
-function safeIndexDir(env) {
-    const index = resolve(indexDir(env));
+function safeIndexDir(env, dirs) {
+    const index = resolve(indexDir(env, dirs));
     // indexDir is `<agent dir>/pi-warden/index`.
     const agent = dirname(dirname(index));
     for (let dir = index; dir !== agent && dirname(dir) !== dir; dir = dirname(dir)) {

package/dist/holds.d.ts

@@ -134,7 +134,7 @@ export declare function formatHolds(snapshot: HoldSnapshot, logPath?: string): s
 /** The session id as a file name part: no separators or dots, so it cannot leave the directory it is joined to. */
 export declare function sessionFileId(sessionId: string): string;
 /** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
-export declare function holdLogPath(sessionId: string, at?: Date): string;
+export declare function holdLogPath(sessionId: string, at?: Date, dirs?: import("./host-dirs.js").HostDirs): string;
 /** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */
 export declare class HoldLog {
     readonly path: string;

package/dist/holds.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { userConfigPath } from "./config.js";
+import { defaultHostDirs } from "./host-dirs.js";
 const REGRET_THRESHOLD = 0.7;
 function scoresOf(verdict) {
     const { judgment } = verdict;
@@ -211,9 +212,9 @@ export function sessionFileId(sessionId) {
     return sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || String(process.pid);
 }
 /** Per-session file beside the user config: `<agent dir>/pi-warden/holds/<date>-<session>.jsonl`. */
-export function holdLogPath(sessionId, at = new Date()) {
+export function holdLogPath(sessionId, at = new Date(), dirs = defaultHostDirs()) {
     const day = at.toISOString().slice(0, 10);
-    return join(dirname(userConfigPath()), "holds", `${day}-${sessionFileId(sessionId)}.jsonl`);
+    return join(dirname(userConfigPath(dirs)), "holds", `${day}-${sessionFileId(sessionId)}.jsonl`);
 }
 /** Rewrites the session's records as JSON lines, owner-only, one write at a time so outcomes never interleave. */
 export class HoldLog {

package/dist/host-compat.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function adaptHost(pi: ExtensionAPI): ExtensionAPI;

package/dist/host-compat.js

@@ -0,0 +1,132 @@
+/** Bind-through view: overrides win, functions bind to the target so `this` keeps working. */
+function overlay(target, overrides) {
+    return new Proxy(target, {
+        get(target, property) {
+            if (Object.hasOwn(overrides, property))
+                return overrides[property];
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+export function adaptHost(pi) {
+    const session = pi.pi;
+    const getActiveSkills = session?.getActiveSkills;
+    if (typeof getActiveSkills !== "function")
+        return pi;
+    const systemPromptOptions = () => ({ skills: getActiveSkills.call(session).map(toPiSkill) });
+    const register = pi.on.bind(pi);
+    const asyncWorkEnds = new WeakSet();
+    // Capture the async-work pause before later agent_end handlers can await I/O. A job may
+    // cancel during one of those handlers and leave no snapshot or follow-up agent_end.
+    register("agent_end", (event, ctx) => {
+        if (event?.willContinue !== true)
+            return;
+        const snapshot = asyncJobSnapshot(ctx);
+        if (snapshot && hasAsyncWork(snapshot))
+            asyncWorkEnds.add(event);
+    });
+    let endGeneration = 0;
+    // Pi emits agent_settled once per prompt, after every agent_end handler and continuation.
+    // Register its host stand-in after extension setup. omp then owns each callback's timeout
+    // and error report, and advances to the stand-in even if one callback times out.
+    // Other extensions may still have agent_end handlers after ours; the stand-in reads only
+    // pi-warden's state.
+    const on = (event, handler) => {
+        if (event === "before_agent_start")
+            return register(event, (e, ctx) => beforeAgentStart(e, ctx, handler, systemPromptOptions()));
+        if (event === "input")
+            return register(event, async (e, ctx) => inputResult(await handler(e, ctx)));
+        if (event === "agent_settled") {
+            queueMicrotask(() => register("agent_end", (e, ctx) => {
+                const generation = ++endGeneration;
+                if (e?.willContinue === true) {
+                    // A cancelled background job can drain without another agent_end. The host drops
+                    // awaitingAsyncWork before extensions see the event, so an earlier extension may
+                    // drain it before our observer runs. Give an empty snapshot one host-dispatch grace
+                    // period; a later agent_end or a running continuation suppresses the fallback.
+                    const snapshot = asyncJobSnapshot(ctx);
+                    if (snapshot) {
+                        const hadAsyncWork = asyncWorkEnds.has(e) || hasAsyncWork(snapshot);
+                        watchAsyncWork(ctx, handler, () => generation === endGeneration, hadAsyncWork ? 500 : 1000);
+                    }
+                    return;
+                }
+                setImmediate(() => {
+                    if (generation === endGeneration)
+                        settle(handler, ctx);
+                });
+            }));
+            return;
+        }
+        return register(event, handler);
+    };
+    const registerCommand = (name, options) => pi.registerCommand(name, { ...options, handler: (args, ctx) => options.handler(args, withSystemPromptOptions(ctx, systemPromptOptions)) });
+    return overlay(pi, { on, registerCommand });
+}
+function toPiSkill(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        filePath: skill.filePath,
+        baseDir: skill.baseDir ?? "",
+        disableModelInvocation: skill.hide === true,
+    };
+}
+async function beforeAgentStart(event, ctx, handler, options) {
+    const result = await handler({ ...event, systemPromptOptions: options }, ctx);
+    if (!options.appendSystemPrompt)
+        return result;
+    const prompt = systemPromptOf(result) ?? systemPromptOf(event) ?? [];
+    return { ...result, systemPrompt: [...(Array.isArray(prompt) ? prompt : [prompt]), options.appendSystemPrompt] };
+}
+function systemPromptOf(value) {
+    if (!value || typeof value !== "object" || !("systemPrompt" in value))
+        return undefined;
+    const prompt = value.systemPrompt;
+    return typeof prompt === "string" || Array.isArray(prompt) ? prompt : undefined;
+}
+function inputResult(result) {
+    const action = result?.action;
+    return action === "handled" ? { ...result, handled: true } : result;
+}
+function asyncJobSnapshot(ctx) {
+    const get = ctx?.getAsyncJobSnapshot;
+    if (typeof get !== "function")
+        return undefined;
+    const snapshot = get.call(ctx);
+    return snapshot && Array.isArray(snapshot.running) ? snapshot : undefined;
+}
+function hasAsyncWork(snapshot) {
+    return snapshot.running.length > 0 || (snapshot.delivery?.queued ?? 0) > 0 || snapshot.delivery?.delivering === true;
+}
+function watchAsyncWork(ctx, handler, isCurrent, delayMs) {
+    const check = () => {
+        if (!isCurrent())
+            return;
+        const snapshot = asyncJobSnapshot(ctx);
+        if (snapshot && hasAsyncWork(snapshot)) {
+            setTimeout(check, 500).unref();
+            return;
+        }
+        settle(handler, ctx);
+    };
+    setTimeout(check, delayMs).unref();
+}
+function settle(handler, ctx) {
+    if (!isIdle(ctx))
+        return;
+    void Promise.resolve()
+        .then(() => handler({ type: "agent_settled" }, ctx))
+        .catch(error => console.error("pi-warden: agent_settled handler failed:", error));
+}
+/** A context without isIdle() cannot report a continuation, so it counts as idle. */
+function isIdle(ctx) {
+    const check = ctx?.isIdle;
+    return typeof check === "function" ? check.call(ctx) !== false : true;
+}
+function withSystemPromptOptions(ctx, options) {
+    if (typeof ctx.getSystemPromptOptions === "function")
+        return ctx;
+    return overlay(ctx, { getSystemPromptOptions: options });
+}

package/dist/host-dirs.d.ts

@@ -0,0 +1,10 @@
+export interface HostDirs {
+    /** The host's agent directory: `~/.pi/agent` on Pi, `~/.omp/agent` on oh-my-pi. */
+    agentDir: string;
+    /** The project config directory name: `.pi` on Pi, `.omp` on oh-my-pi. */
+    configDirName: string;
+}
+/** Expand a leading `~` or `~/` to the home directory; anything else comes back trimmed. */
+export declare function expandHome(value: string): string;
+/** Resolve the agent directory the way the host would: `PI_CODING_AGENT_DIR`, else Pi's default. */
+export declare function defaultHostDirs(env?: NodeJS.ProcessEnv): HostDirs;

package/dist/host-dirs.js

@@ -0,0 +1,21 @@
+/**
+ * Host directories for pi-warden's own data. The library carries no runtime import of the optional
+ * Pi peer; the extension (src/extension.ts) builds these once from the host and passes them to every
+ * path call. `defaultHostDirs` covers the plain-library and test cases: `PI_CODING_AGENT_DIR` wins,
+ * `~` expands to the home directory, and the fallback matches Pi's own agent directory.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Expand a leading `~` or `~/` to the home directory; anything else comes back trimmed. */
+export function expandHome(value) {
+    const configured = value.trim();
+    return configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured;
+}
+/** Resolve the agent directory the way the host would: `PI_CODING_AGENT_DIR`, else Pi's default. */
+export function defaultHostDirs(env = process.env) {
+    const configured = env.PI_CODING_AGENT_DIR?.trim();
+    return {
+        agentDir: configured ? expandHome(configured) : join(homedir(), ".pi", "agent"),
+        configDirName: ".pi",
+    };
+}

package/dist/index-cmd.d.ts

@@ -1,5 +1,6 @@
 import type { Skill } from "@earendil-works/pi-coding-agent";
 import type { CapabilityRole } from "./conscience.js";
+import type { HostDirs } from "./host-dirs.js";
 export { fileContentHash, toolSourceHash } from "./hashing.js";
 export type SourceQuality = "strong" | "weak" | "thin";
 export interface IndexEntry {
@@ -28,10 +29,10 @@ export interface IndexFile {
     model: string;
     entries: IndexEntry[];
 }
-/** The directory `/warden index` asks the agent to write its index files into. */
-export declare function indexDir(env?: NodeJS.ProcessEnv): string;
-export declare function indexPath(kind: "global" | "project", projectRoot?: string): string;
-export declare function ensureIndexDir(kind: "global" | "project"): void;
+/** The index directory: `PI_WARDEN_INDEX_DIR` wins, then `PI_CODING_AGENT_DIR`, then the host directories. A `~` or `~/` prefix expands to the home directory. */
+export declare function indexDir(env?: NodeJS.ProcessEnv, dirs?: HostDirs): string;
+export declare function indexPath(kind: "global" | "project", projectRoot?: string, env?: NodeJS.ProcessEnv, dirs?: HostDirs): string;
+export declare function ensureIndexDir(kind: "global" | "project", env?: NodeJS.ProcessEnv, dirs?: HostDirs): void;
 /** Compute a sourceHash for a skill from its file content. */
 export declare function skillSourceHash(skill: Skill): string;
 export declare function readIndex(filePath: string): IndexFile | undefined;
@@ -76,7 +77,7 @@ export declare function buildIndexPrompt(cwd: string, skills: Array<{
 }>, outputPaths: {
     global: string;
     project: string;
-}): string;
+}, dirs?: HostDirs): string;
 /** Find an index entry by name and sourceHash. */
 export declare function findEntry(name: string, sourceHash: string, globalIndex: IndexFile | undefined, projectIndex: IndexFile | undefined): IndexEntry | undefined;
 /** Check whether all cached skills have matching entries in the index. */

package/dist/index-cmd.js

@@ -4,39 +4,30 @@
  * entries in a fixed format; the extension validates and sanitizes them.
  */
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { createHash } from "node:crypto";
-import { homedir } from "node:os";
 import { sanitizeDescription } from "./conscience.js";
 import { fileContentHash, toolSourceHash } from "./hashing.js";
+import { PACKAGE_NAME } from "./config.js";
+import { defaultHostDirs, expandHome } from "./host-dirs.js";
 export { fileContentHash, toolSourceHash } from "./hashing.js";
 /* ─── Path resolution ───────────────────────────────────────────────── */
-/** Resolve Pi's agent directory (mirrors config.ts userConfigPath logic). */
-function resolveAgentDir(env = process.env) {
-    const configured = env.PI_WARDEN_INDEX_DIR?.trim()
-        ?? env.PI_CODING_AGENT_DIR?.trim();
-    if (configured) {
-        const expanded = configured === "~" || configured.startsWith("~/")
-            ? join(homedir(), configured.slice(1))
-            : configured;
-        return expanded;
-    }
-    return join(homedir(), ".pi", "agent");
-}
-/** The directory `/warden index` asks the agent to write its index files into. */
-export function indexDir(env = process.env) {
-    return join(resolveAgentDir(env), "pi-warden", "index");
+/** The index directory: `PI_WARDEN_INDEX_DIR` wins, then `PI_CODING_AGENT_DIR`, then the host directories. A `~` or `~/` prefix expands to the home directory. */
+export function indexDir(env = process.env, dirs = defaultHostDirs(env)) {
+    const configured = env.PI_WARDEN_INDEX_DIR?.trim() || env.PI_CODING_AGENT_DIR?.trim();
+    const base = configured ? expandHome(configured) : dirs.agentDir;
+    return join(base, PACKAGE_NAME, "index");
 }
-export function indexPath(kind, projectRoot) {
-    const base = indexDir();
+export function indexPath(kind, projectRoot, env = process.env, dirs) {
+    const base = indexDir(env, dirs);
     if (kind === "global")
         return join(base, "global.json");
     // Project index keyed by first 12 hex chars of SHA-256(projectRoot)
     const hash = createHash("sha256").update(projectRoot ?? "").digest("hex").slice(0, 12);
     return join(base, "projects", `${hash}.json`);
 }
-export function ensureIndexDir(kind) {
-    const dir = kind === "global" ? indexDir() : join(indexDir(), "projects");
+export function ensureIndexDir(kind, env = process.env, dirs) {
+    const dir = kind === "global" ? indexDir(env, dirs) : join(indexDir(env, dirs), "projects");
     mkdirSync(dir, { recursive: true });
 }
 /* ─── Content hashing ───────────────────────────────────────────────── */
@@ -58,7 +49,8 @@ export function readIndex(filePath) {
     }
 }
 export function writeIndex(filePath, index) {
-    ensureIndexDir(filePath.includes("/projects/") ? "project" : "global");
+    // The target's parent: `<index dir>/projects` for a project file, the index dir for the global one.
+    mkdirSync(dirname(filePath), { recursive: true });
     writeFileSync(filePath, JSON.stringify(index, null, 2), "utf8");
 }
 function isIndexFile(value) {
@@ -237,7 +229,7 @@ const WRITING_RULES = `## Entry writing rules
  * Build the user message that asks the session model to produce index entries.
  * The prompt includes the format spec, writing rules, and both absolute output paths.
  */
-export function buildIndexPrompt(cwd, skills, tools, outputPaths) {
+export function buildIndexPrompt(cwd, skills, tools, outputPaths, dirs = defaultHostDirs()) {
     const skillLines = skills.map(s => `- ${s.name}: ${s.description} (file: ${s.filePath})`).join("\n");
     const toolLines = tools.map(t => `- ${t.name}: ${t.description}`).join("\n");
     return [
@@ -280,7 +272,7 @@ export function buildIndexPrompt(cwd, skills, tools, outputPaths) {
         "```",
         "",
         "## Scope",
-        "- Skills from ~/.pi/agent/skills/ and user-level directories: scope `global`",
+        `- Skills from ${dirs.agentDir}/skills/ and user-level directories: scope \`global\``,
         "- Skills from the project directory: scope `project`",
         "- All tools: scope `global`",
         "",

package/dist/index.d.ts

@@ -32,20 +32,26 @@ export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, setNestedValue, getNestedValue, parseConfigValue, PACKAGE_NAME } from "./config.js";
 export type { ActionGuardConfig, OffTaskThreshold, StuckGuardConfig, DoneGuardConfig, VisualToolsConfig, SlopGuardConfig, ProseConfig, SecurityConfig, RulesConfig, ContextConfig, LargeOutputConfig, RunawayConfig, NotifyConfig, SubagentConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export { defaultHostDirs } from "./host-dirs.js";
+export type { HostDirs } from "./host-dirs.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export type { CommandView } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, SENTENCE_TEMPLATES, pickSentenceTemplate, TOKEN_NAMES } from "./widget.js";
 export type { WidgetConfig, WidgetPlacement, WidgetBarMode, Tokens } from "./widget.js";
 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, formatRuleSetDetails, 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, RulesTier, RulesSourceConfig } from "./rules.js";
-export { checkRules, formatRulesCheck, formatRuleCheck, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, formatRuleSetDetails, describeTarget, buildRulesRequest, ruleQuestion, scoreRuleAnswers, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, MAX_EDITS, EDIT_TEXT_LIMIT, EDIT_CONTEXT_LINES, AGGREGATE_QUESTION, LOCATOR_QUESTION, editRulesFor, turnRulesFor, evaluateRulesTarget, scoreAnswers } from "./rules.js";
+export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RuleAnswer, RuleScoring, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef, RulesTier, RulesSourceConfig, RuleWhen, RuleScoreEntry } from "./rules.js";
+export { snapshotTree, diffSince, unjudgedFiles, evaluateTurnRules, evaluateTurnRun, buildTurnRequest, turnRuleQuestion, turnSteer, TURN_PATH, TURN_QUESTION_PREFIX } from "./turn-rules.js";
+export type { SnapshotResult, TurnDiff, TurnFileDiff, TurnRunOptions, TurnRunResult, TurnRulesOptions } from "./turn-rules.js";
+export { checkRules, formatRulesCheck, formatRuleCheck, checkReasons, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
 export type { RuleCheck, RuleCheckView, RuleJudgeability, RulesCheckOptions, RulesCheckRequest, RulesCheckResult, RulesCheckSource } from "./rules-lint.js";
 export { rulesLogPath, readRulesLog, trimRecords, RuleClearTracker, RulesLog, RULES_LOG_MAX_RECORDS } from "./rules-log.js";
 export type { RuleRecord, RuleObservation, RulesLogOptions } from "./rules-log.js";
 export { buildRulesReport, formatRulesReport, compareRows, REPORT_DEFAULT_DAYS, NEVER_FIRES_MIN, FIRES_RATE_MAX, UNDECIDED_LOW, UNDECIDED_HIGH } from "./rules-report.js";
-export type { RuleFlag, RuleReportRow, RulesReport } from "./rules-report.js";
+export type { RuleFlag, RuleReportRow, RulesReport, ReportSource } from "./rules-report.js";
+export { parseHistory, collectHistory, changeSkipReason, editViews, planCalibration, calibrate, formatCalibration, calibrateGate, calibrationNotice, tuneTargets, buildTunePrompt, tuneRequest, CALIBRATE_DEFAULT_COMMITS, CALIBRATE_DEFAULT_MAX } from "./rules-calibrate.js";
+export type { HistoryHunk, HistoryFile, HistoryCommit, CalibrateSkip, CalibrateSample, CalibratePlan, PlanOptions, RuleCalibration, Calibration, CalibrateOptions, CalibrateGate, TuneRule, TuneRequest } from "./rules-calibrate.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";
@@ -54,3 +60,5 @@ export { initSchema, recordHold, recordOutcome as recordHoldOutcome, querySmartH
 export type { HoldRecord, HoldScores, HoldLevel, HoldOutcome, HoldContext, SmartHistory, ConfidenceResult, SkipResult, ThresholdAdjustment, PatternInsight, ContextRecommendation, SteerEffectivenessReport } from "./learning.js";
 export { buildAuditPrompt, snapshotReport, reportOutcome } from "./audit.js";
 export type { ReportSnapshot } from "./audit.js";
+export { parseRulesAuditArgs, parseBenchArgs, collectAuditFiles, runRulesAudit, ruleAuditRows, flaggedAuditFiles, formatRulesAuditRows, formatRulesAuditFiles, formatRulesAudit, rulesAuditMarkdown, writeRulesAuditReport, runBench, formatBench, percentile, BENCH_SAMPLE, AUDIT_DEFAULT_MAX, AUDIT_CONCURRENCY, AUDIT_REPORT_FILE, RULES_AUDIT_USAGE, BENCH_USAGE } from "./rules-audit.js";
+export type { RulesAuditArgs, BenchArgs, AuditFilePlan, RulesAuditFileResult, RulesAuditRow, RulesAuditOutcome, RulesAuditResult, RulesAuditOptions, RulesAuditFlag, RulesAuditFileFlags, BenchUsage, BenchOptions, BenchResult } from "./rules-audit.js";

package/dist/index.js

@@ -16,14 +16,18 @@ export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
 export { HoldLedger, HoldLog, holdLogPath, formatHolds, outcomeNote, regretsAt, textRegrets } from "./holds.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, setNestedValue, getNestedValue, parseConfigValue, PACKAGE_NAME } from "./config.js";
+export { defaultHostDirs } from "./host-dirs.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, SENTENCE_TEMPLATES, pickSentenceTemplate, TOKEN_NAMES } from "./widget.js";
 export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
-export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, formatRuleSetDetails, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
-export { checkRules, formatRulesCheck, formatRuleCheck, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
+export { parseRules, condense, isRuleShaped, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, formatRuleSetDetails, describeTarget, buildRulesRequest, ruleQuestion, scoreRuleAnswers, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, MAX_EDITS, EDIT_TEXT_LIMIT, EDIT_CONTEXT_LINES, AGGREGATE_QUESTION, LOCATOR_QUESTION, editRulesFor, turnRulesFor, evaluateRulesTarget, scoreAnswers } from "./rules.js";
+export { snapshotTree, diffSince, unjudgedFiles, evaluateTurnRules, evaluateTurnRun, buildTurnRequest, turnRuleQuestion, turnSteer, TURN_PATH, TURN_QUESTION_PREFIX } from "./turn-rules.js";
+export { checkRules, formatRulesCheck, formatRuleCheck, checkReasons, buildRulesCheckRequest, ruleCheckView, judgeableQuestion, mechanicalQuestion, MECHANICAL_CUTOFF, CHECK_ABOUT, JUDGEABILITY_REASONS, JUDGEABLE_PREFIX, MECHANICAL_PREFIX } from "./rules-lint.js";
 export { rulesLogPath, readRulesLog, trimRecords, RuleClearTracker, RulesLog, RULES_LOG_MAX_RECORDS } from "./rules-log.js";
 export { buildRulesReport, formatRulesReport, compareRows, REPORT_DEFAULT_DAYS, NEVER_FIRES_MIN, FIRES_RATE_MAX, UNDECIDED_LOW, UNDECIDED_HIGH } from "./rules-report.js";
+export { parseHistory, collectHistory, changeSkipReason, editViews, planCalibration, calibrate, formatCalibration, calibrateGate, calibrationNotice, tuneTargets, buildTunePrompt, tuneRequest, CALIBRATE_DEFAULT_COMMITS, CALIBRATE_DEFAULT_MAX } from "./rules-calibrate.js";
 export { resolveRulesFile, extractRules, checkPiWardenMissing } from "./rules-file.js";
 export { writeStarterRules, generateStarterRules, detectProjectType, buildProjectContext, buildInitPrompt } from "./init.js";
 export { initSchema, recordHold, recordOutcome as recordHoldOutcome, querySmartHistory, calculateSmartConfidence, shouldSkipHold, analyzeThresholds, analyzePatterns, generateRecommendations, analyzeSteerEffectivenessReport } from "./learning.js";
 export { buildAuditPrompt, snapshotReport, reportOutcome } from "./audit.js";
+export { parseRulesAuditArgs, parseBenchArgs, collectAuditFiles, runRulesAudit, ruleAuditRows, flaggedAuditFiles, formatRulesAuditRows, formatRulesAuditFiles, formatRulesAudit, rulesAuditMarkdown, writeRulesAuditReport, runBench, formatBench, percentile, BENCH_SAMPLE, AUDIT_DEFAULT_MAX, AUDIT_CONCURRENCY, AUDIT_REPORT_FILE, RULES_AUDIT_USAGE, BENCH_USAGE } from "./rules-audit.js";

package/dist/init.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { FALLBACK_FILES } from "./rules.js";
+import { FALLBACK_FILES, MAX_RULES } from "./rules.js";
+/** Fallback files whose content is instruction text to compile into small rules; a README-style file stays whole text. */
+const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
 /** Paths to scan for project context when generating a starter rules file. */
 const CONTEXT_CANDIDATES = [
     "package.json",
@@ -100,6 +102,26 @@ function readExistingPiWarden(cwd) {
         return null;
     }
 }
+/** The first instruction file's lines with their 1-based line numbers, or null when none exists. */
+function readNumberedInstructions(cwd) {
+    for (const file of INSTRUCTION_FILES) {
+        const fullPath = join(cwd, file);
+        if (!existsSync(fullPath))
+            continue;
+        try {
+            const lines = readFileSync(fullPath, "utf8").split(/\r\n|\r|\n/);
+            if (lines.at(-1) === "")
+                lines.pop();
+            if (!lines.some(line => line.trim()))
+                continue;
+            return { file, text: lines.map((line, index) => `${index + 1}: ${line}`).join("\n") };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 /** Standard safety rules that ship in every starter pi-warden.md. */
 const SAFETY_RULES = `# No hardcoded secrets
 Source code must not contain passwords, API keys, tokens, or connection URLs with credentials.
@@ -174,8 +196,14 @@ export function buildInitPrompt(cwd) {
     if (existingPiWarden) {
         lines.push("", "## Existing pi-warden.md rules (preserve these)", existingPiWarden, "");
     }
-    else if (existingRules) {
-        lines.push("", "## Existing project rules (preserve these)", existingRules, "");
+    else {
+        const instructions = readNumberedInstructions(cwd);
+        if (instructions) {
+            lines.push("", `## Existing instructions to compile (from ${instructions.file}, each line prefixed with its line number)`, instructions.text, "", "Compile these instructions into rules: one small rule per instruction that can be judged from one changed file alone, without other files, repository history, or the task.", "- Give each rule a `source: <file>:<line>` header naming the instruction line it came from, for example `source: AGENTS.md:65`.", "- Add a `paths:` header when the instruction concerns certain files only.", "- Keep each rule's wording close to the source instruction.", "- Name the concrete pattern that shows a violation: a symbol, a comment phrase, a command, a file shape.", `- Stay under the rule cap: at most ${MAX_RULES} rules.`, "", "Leave these instructions out of pi-warden.md, and list each left-out instruction in your reply with the reason:", "- an instruction that needs other files, repository history, or the task to judge", "- an instruction that a linter, formatter, or type checker already enforces", "", "In your reply, suggest running `/warden rules check` when the user has a TypeSafe key. Suggest it only; never run it as part of this task.", "");
+        }
+        else if (existingRules) {
+            lines.push("", "## Existing project rules (preserve these)", existingRules, "");
+        }
     }
     if (projectType === "typescript" || projectType === "javascript") {
         lines.push("## Type-specific rules", "- No explicit `any` in **/*.ts, **/*.tsx", "- Exported functions declare their return type in src/**/*.ts", "");

package/dist/learning.d.ts

@@ -1,6 +1,7 @@
+import type { HostDirs } from "./host-dirs.js";
 import type { CallScores } from "./holds.js";
 export declare const HOLDS_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS holds (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    timestamp INTEGER NOT NULL,\n    project_root TEXT NOT NULL,\n    tool TEXT NOT NULL,\n    signature_hash TEXT NOT NULL,\n    command_preview TEXT,\n    task TEXT,\n    plan TEXT,\n    context_summary TEXT,\n    preceding_actions TEXT,\n    scores TEXT NOT NULL,\n    level TEXT NOT NULL,\n    held INTEGER NOT NULL,\n    reasons TEXT,\n    agent_reason TEXT,\n    outcome TEXT,\n    outcome_at INTEGER,\n    confidence REAL\n  );\n  CREATE INDEX IF NOT EXISTS idx_holds_project_signature ON holds(project_root, signature_hash);\n  CREATE INDEX IF NOT EXISTS idx_holds_outcome ON holds(outcome);\n  CREATE INDEX IF NOT EXISTS idx_holds_timestamp ON holds(timestamp);\n";
-export declare function initSchema(retentionDays?: number): Promise<void>;
+export declare function initSchema(retentionDays?: number, dirs?: HostDirs): Promise<void>;
 export interface HoldScores {
     irreversible: number;
     /** Reason categories from the verdict, used for same-reason queries and destructive-pattern detection. */
@@ -66,12 +67,12 @@ export declare function toHoldRecord(item: {
     scores?: CallScores | undefined;
     held?: boolean | undefined;
 }, projectRoot: string, ctx?: HoldContext): HoldRecord;
-export declare function recordHold(hold: HoldRecord): Promise<number>;
-export declare function recordOutcome(id: number, outcome: string): Promise<void>;
+export declare function recordHold(hold: HoldRecord, dirs?: HostDirs): Promise<number>;
+export declare function recordOutcome(id: number, outcome: string, dirs?: HostDirs): Promise<void>;
 /** Query holds by project and held value. Used by tests and future analytics. */
 export declare function queryHoldsForProject(projectRoot: string, options?: {
     held?: boolean;
-}): Promise<Record<string, unknown>[]>;
+}, dirs?: HostDirs): Promise<Record<string, unknown>[]>;
 /** Lifetime hold statistics for one project root. Matches the precision formula in holds.ts: (declined + replanned) / (approved + declined + replanned). */
 export interface HoldStats {
     /** held = 1 rows for this root. */
@@ -94,10 +95,10 @@ export interface HoldStats {
     oldest: number;
     newest: number;
 }
-export declare function holdStats(projectRoot: string): Promise<HoldStats>;
-export declare function querySmartHistory(tool: string, scores: HoldScores, projectRoot: string): Promise<SmartHistory>;
+export declare function holdStats(projectRoot: string, dirs?: HostDirs): Promise<HoldStats>;
+export declare function querySmartHistory(tool: string, scores: HoldScores, projectRoot: string, dirs?: HostDirs): Promise<SmartHistory>;
 export declare function calculateSmartConfidence(history: SmartHistory): ConfidenceResult;
-export declare function shouldSkipHold(tool: string, scores: HoldScores, projectRoot: string): Promise<SkipResult>;
+export declare function shouldSkipHold(tool: string, scores: HoldScores, projectRoot: string, dirs?: HostDirs): Promise<SkipResult>;
 /** Learn from past outcomes to suggest threshold adjustments. */
 export interface ThresholdAdjustment {
     guard: string;
@@ -107,7 +108,7 @@ export interface ThresholdAdjustment {
     confidence: number;
 }
 /** Analyze hold outcomes to suggest threshold adjustments. */
-export declare function analyzeThresholds(projectRoot: string): Promise<ThresholdAdjustment[]>;
+export declare function analyzeThresholds(projectRoot: string, dirs?: HostDirs): Promise<ThresholdAdjustment[]>;
 /** Learn which patterns are most likely to be false positives. */
 export interface PatternInsight {
     pattern: string;
@@ -115,14 +116,14 @@ export interface PatternInsight {
     sampleSize: number;
     suggestion: string;
 }
-export declare function analyzePatterns(projectRoot: string): Promise<PatternInsight[]>;
+export declare function analyzePatterns(projectRoot: string, dirs?: HostDirs): Promise<PatternInsight[]>;
 export interface ContextRecommendation {
     type: 'threshold' | 'exempt' | 'pattern';
     message: string;
     priority: 'high' | 'medium' | 'low';
 }
 /** Generate recommendations based on learning data. */
-export declare function generateRecommendations(projectRoot: string): Promise<ContextRecommendation[]>;
+export declare function generateRecommendations(projectRoot: string, dirs?: HostDirs): Promise<ContextRecommendation[]>;
 /** Analyze which types of steers are most effective at changing agent behavior. */
 export interface SteerEffectivenessReport {
     /** Overall effectiveness rate (0-1). */
@@ -143,4 +144,4 @@ export interface SteerEffectivenessReport {
     }>;
 }
 /** Analyze steer effectiveness from hold outcomes. */
-export declare function analyzeSteerEffectivenessReport(projectRoot: string): Promise<SteerEffectivenessReport>;
+export declare function analyzeSteerEffectivenessReport(projectRoot: string, dirs?: HostDirs): Promise<SteerEffectivenessReport>;