pi-warden 0.71.0 → 0.74.0

package/dist/rules-audit.js

@@ -0,0 +1,417 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { discoverSourceFiles } from "./discover.js";
+import { evaluateRules, gitIgnored, projectPath, skipReason } from "./rules.js";
+/**
+ * `/warden rules audit` and `/warden bench`: two plain functions over the rules guard.
+ *
+ * The audit judges existing files against the project rules as if each had just been written, one `write` request per
+ * file. Nothing leaves the machine without the confirm dialog (or `--yes` in a headless run), the results never reach
+ * the rules log, and the only file written is the Markdown copy under `.pi-warden/`. The bench measures what one of
+ * those requests costs on this machine with a fixed built-in sample, so no project content is sent for it at all.
+ */
+/** Files the audit judges unless `--max` says otherwise. */
+export const AUDIT_DEFAULT_MAX = 50;
+/** Requests in flight at once; small so a big audit cannot burst the backend. */
+export const AUDIT_CONCURRENCY = 4;
+/** Source files the discovery walk collects before it stops; the cap counts what it found. */
+export const AUDIT_DISCOVERY_MAX = 5000;
+export const AUDIT_REPORT_FILE = ".pi-warden/rules-audit.md";
+export const RULES_AUDIT_USAGE = "Usage: /warden rules audit [paths...] [--max N] [--yes], where N is a positive integer (default 50) and paths default to the project.";
+export const BENCH_USAGE = "Usage: /warden bench [--runs N], where N is a positive integer (default 10).";
+export function parseRulesAuditArgs(tokens) {
+    const paths = [];
+    let max = AUDIT_DEFAULT_MAX;
+    let yes = false;
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (token === "--max") {
+            const value = tokens[++index];
+            const count = Number(value);
+            if (value === undefined || !Number.isInteger(count) || count < 1)
+                return { paths, max, yes, error: `--max needs a positive integer. ${RULES_AUDIT_USAGE}` };
+            max = count;
+            continue;
+        }
+        if (token.startsWith("-"))
+            return { paths, max, yes, error: `Unknown option ${token}. ${RULES_AUDIT_USAGE}` };
+        paths.push(token);
+    }
+    return { paths: paths.length ? paths : ["."], max, yes };
+}
+export function parseBenchArgs(tokens) {
+    let runs = 10;
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (token === "--runs") {
+            const value = tokens[++index];
+            const count = Number(value);
+            if (value === undefined || !Number.isInteger(count) || count < 1)
+                return { runs, error: `--runs needs a positive integer. ${BENCH_USAGE}` };
+            runs = count;
+            continue;
+        }
+        return { runs, error: `Unknown option ${token}. ${BENCH_USAGE}` };
+    }
+    return { runs };
+}
+/**
+ * The source files under `paths` the audit will judge: found by `discoverSourceFiles`, inside the project, not ignored
+ * by git, not kept out by `rules.exclude` or `rules.skip`, and with at least one rule that applies to them. Capped in
+ * sorted order so the same command judges the same files twice.
+ */
+export function collectAuditFiles(cwd, paths, set, config, max) {
+    const seen = new Set();
+    const candidates = [];
+    const missing = [];
+    for (const raw of paths) {
+        const abs = resolve(cwd, raw);
+        let stat;
+        try {
+            stat = statSync(abs);
+        }
+        catch {
+            stat = undefined;
+        }
+        const rel = stat ? relative(resolve(cwd), abs).split(sep).join("/") : undefined;
+        // The project root is the one path `projectPath` rejects: it is not inside itself.
+        if (!stat || rel === undefined || rel.startsWith("..") || isAbsolute(rel)) {
+            missing.push(raw);
+            continue;
+        }
+        const found = stat.isDirectory()
+            ? discoverSourceFiles(abs, AUDIT_DISCOVERY_MAX).map(name => projectPath(join(abs, name), cwd)).filter((path) => path !== undefined)
+            : rel ? [rel] : [];
+        if (!stat.isDirectory() && !stat.isFile())
+            missing.push(raw);
+        for (const candidate of found) {
+            if (seen.has(candidate))
+                continue;
+            seen.add(candidate);
+            if (gitIgnored(candidate, cwd))
+                continue;
+            if (skipReason({ tool: "write", path: candidate }, set, config))
+                continue;
+            candidates.push(candidate);
+        }
+    }
+    candidates.sort();
+    return { files: candidates.slice(0, max), matched: candidates.length, leftOut: Math.max(0, candidates.length - max), missing };
+}
+/**
+ * One `write` request per selected file, at most AUDIT_CONCURRENCY at a time, after the confirm dialog (or `--yes`).
+ * With no judge nothing is sent and no dialog is shown. The Markdown copy is written to `AUDIT_REPORT_FILE`; the rules
+ * log is never touched.
+ */
+export async function runRulesAudit(options) {
+    if (!options.judge)
+        return { status: "no-judge" };
+    const { set } = options;
+    if (!set)
+        return { status: "no-files", reason: "no rules file resolved, so there is nothing to judge the files against" };
+    if (set.proseOnly)
+        return { status: "no-files", reason: `no rules found in ${set.sources.join(", ")} (prose only)` };
+    const plan = collectAuditFiles(options.cwd, options.paths, set, options.config, options.max);
+    if (!plan.files.length)
+        return { status: "no-files", reason: `no source file under ${options.paths.join(", ")} has a rule that applies to it` };
+    if (!options.yes) {
+        if (!options.confirm)
+            return { status: "needs-yes", files: plan.files.length, leftOut: plan.leftOut };
+        const title = `Send ${plan.files.length} file${plan.files.length === 1 ? "" : "s"} to ${options.destination} for a rules audit?`;
+        const body = [
+            `Each file is judged against the project rules as if it had just been written.`,
+            `What leaves the machine: a redacted sample of each file (up to 6000 characters per file) and the rule text, sent to ${options.destination}.`,
+            plan.leftOut ? `${plan.leftOut} file${plan.leftOut === 1 ? "" : "s"} left out at the --max ${options.max} cap.` : "",
+            "Nothing is written to the rules log.",
+        ].filter(Boolean).join("\n");
+        if (!await options.confirm(title, body))
+            return { status: "cancelled" };
+    }
+    const queue = plan.files.map((path, index) => ({ path, index }));
+    const results = Array.from({ length: plan.files.length });
+    const unreadable = [];
+    const errors = [];
+    const started = Date.now();
+    const worker = async () => {
+        for (;;) {
+            const next = queue.shift();
+            if (!next)
+                return;
+            let content;
+            try {
+                content = readFileSync(join(options.cwd, next.path), "utf8");
+            }
+            catch {
+                unreadable.push(next.path);
+                continue;
+            }
+            if (!content.trim()) {
+                unreadable.push(next.path);
+                continue;
+            }
+            const verdict = await evaluateRules("write", { path: next.path, content }, {
+                cwd: options.cwd, config: options.config, set, judge: options.judge, timeoutMs: options.timeoutMs, ...(options.signal ? { signal: options.signal } : {}),
+            });
+            if (verdict.source === "error")
+                errors.push(next.path);
+            results[next.index] = { path: next.path, verdict };
+        }
+    };
+    await Promise.all(Array.from({ length: AUDIT_CONCURRENCY }, worker));
+    const judged = results.filter((entry) => entry !== undefined);
+    const rows = ruleAuditRows(judged);
+    const outcome = {
+        paths: [...options.paths],
+        max: options.max,
+        selected: plan.files.length,
+        judged: judged.length,
+        leftOut: plan.leftOut,
+        missing: plan.missing,
+        unreadable,
+        errors,
+        results: judged,
+        rows,
+        flagged: judged.filter(entry => entry.verdict.findings.length > 0).length,
+        sources: set.sources,
+        rules: rows.length,
+        aggregate: set.aggregate !== undefined && !set.rules.length,
+        reportPath: AUDIT_REPORT_FILE,
+        elapsedMs: Date.now() - started,
+    };
+    writeRulesAuditReport(options.cwd, rulesAuditMarkdown(outcome));
+    return { status: "done", outcome };
+}
+// ---------------------------------------------------------------------------
+// The Markdown copy
+function usd(value) {
+    return `$${value.toFixed(6)}`;
+}
+function ruleCell(id) {
+    return id.length <= 44 ? id : `${id.slice(0, 43)}…`;
+}
+/** The per-rule table body, flagged rules first. */
+export function formatRulesAuditRows(rows) {
+    const lines = [`${"rule".padEnd(44)}${"judged".padStart(6)}${"flagged".padStart(8)}${"mean".padStart(7)}`];
+    for (const row of rows) {
+        lines.push(`${ruleCell(row.id).padEnd(44)}${String(row.judged).padStart(6)}${String(row.flagged).padStart(8)}${row.mean.toFixed(2).padStart(7)}`);
+    }
+    return lines.join("\n");
+}
+/** Files with findings, worst first (most findings, then the strongest score). */
+export function flaggedAuditFiles(results) {
+    return results
+        .map(entry => ({
+        path: entry.path,
+        findings: entry.verdict.findings.map(finding => ({ name: finding.name, score: finding.violation })),
+        soft: (entry.verdict.softFindings ?? []).map(finding => ({ name: finding.name, score: finding.violation })),
+    }))
+        .filter(entry => entry.findings.length > 0 || entry.soft.length > 0)
+        .sort((a, b) => (b.findings.length - a.findings.length)
+        || (Math.max(0, ...b.findings.map(finding => finding.score)) - Math.max(0, ...a.findings.map(finding => finding.score)))
+        || a.path.localeCompare(b.path));
+}
+/** One line per file, rule names with scores indented under the path. */
+export function formatRulesAuditFiles(results) {
+    const flagged = flaggedAuditFiles(results);
+    if (!flagged.length)
+        return "no file flagged";
+    const lines = [];
+    for (const entry of flagged) {
+        lines.push(entry.path);
+        for (const finding of entry.findings)
+            lines.push(`  ${finding.name} ${finding.score.toFixed(2)}`);
+        for (const finding of entry.soft)
+            lines.push(`  ${finding.name} ${finding.score.toFixed(2)} (double-check)`);
+    }
+    return lines.join("\n");
+}
+/** The terminal output: summary, the table by rule, the file list, and where the Markdown copy went. */
+export function formatRulesAudit(outcome) {
+    const lines = [
+        `Rules audit: ${outcome.judged} file${outcome.judged === 1 ? "" : "s"} judged as new writes against ${outcome.sources.join(", ")} (${outcome.rules} rule${outcome.rules === 1 ? "" : "s"} in play); ${outcome.leftOut} left out at the --max ${outcome.max} cap; ${outcome.flagged} of ${outcome.judged} flagged.`,
+    ];
+    if (outcome.aggregate)
+        lines.push("The rules document has no rule headings, so each file is judged against it as one document.");
+    lines.push(formatRulesAuditRows(outcome.rows));
+    lines.push("flagged files, worst first:");
+    lines.push(formatRulesAuditFiles(outcome.results));
+    if (outcome.missing.length)
+        lines.push(`not found in the project: ${outcome.missing.join("; ")}.`);
+    if (outcome.unreadable.length)
+        lines.push(`not judged (unreadable or empty): ${outcome.unreadable.join("; ")}.`);
+    if (outcome.errors.length)
+        lines.push(`judgment failed for ${outcome.errors.length} file${outcome.errors.length === 1 ? "" : "s"}: ${outcome.errors.join("; ")}.`);
+    lines.push(`Markdown copy: ${outcome.reportPath}. Nothing was recorded in the rules log.`);
+    return lines.join("\n");
+}
+/** The Markdown copy of one audit run. */
+export function rulesAuditMarkdown(outcome, date = new Date()) {
+    const lines = [
+        "# Rules audit",
+        "",
+        `- Date: ${date.toISOString()}`,
+        `- Paths: ${outcome.paths.join(", ")}`,
+        `- Judged: ${outcome.judged} of ${outcome.selected} selected files as new writes (${outcome.leftOut} left out at the --max ${outcome.max} cap)`,
+        `- Rules in force: ${outcome.sources.join(", ")} (${outcome.rules} rule${outcome.rules === 1 ? "" : "s"} in play${outcome.aggregate ? ", judged as one document" : ""})`,
+        `- Flagged: ${outcome.flagged} of ${outcome.judged} files`,
+        "",
+        "## By rule",
+        "",
+        "| rule | judged | flagged | mean |",
+        "| --- | ---: | ---: | ---: |",
+        ...outcome.rows.map(row => `| \`${row.id}\` | ${row.judged} | ${row.flagged} | ${row.mean.toFixed(2)} |`),
+        "",
+        "## Flagged files, worst first",
+        "",
+        ...(flaggedAuditFiles(outcome.results).length
+            ? flaggedAuditFiles(outcome.results).map(entry => `- \`${entry.path}\` — ${[
+                ...entry.findings.map(finding => `${finding.name} ${finding.score.toFixed(2)}`),
+                ...entry.soft.map(finding => `${finding.name} ${finding.score.toFixed(2)} (double-check)`),
+            ].join("; ")}`)
+            : ["- no file flagged"]),
+        "",
+    ];
+    if (outcome.missing.length)
+        lines.push(`Not found in the project: ${outcome.missing.join("; ")}.`, "");
+    if (outcome.unreadable.length)
+        lines.push(`Not judged (unreadable or empty): ${outcome.unreadable.join("; ")}.`, "");
+    if (outcome.errors.length)
+        lines.push(`Judgment failed for ${outcome.errors.length} file${outcome.errors.length === 1 ? "" : "s"}: ${outcome.errors.join("; ")}.`, "");
+    lines.push("Nothing was recorded in the rules log.");
+    return `${lines.join("\n")}\n`;
+}
+/** Write the Markdown copy and return the path it went to. */
+export function writeRulesAuditReport(cwd, markdown) {
+    const path = join(cwd, ...AUDIT_REPORT_FILE.split("/"));
+    mkdirSync(join(cwd, ".pi-warden"), { recursive: true });
+    writeFileSync(path, markdown);
+    return path;
+}
+// ---------------------------------------------------------------------------
+// Per-rule rows
+/** One row per rule asked anywhere in the audit: files judged, files flagged, mean score; flagged first. */
+export function ruleAuditRows(results) {
+    const rows = new Map();
+    for (const entry of results) {
+        for (const score of entry.verdict.scores ?? []) {
+            const row = rows.get(score.id) ?? { id: score.id, name: score.name, judged: 0, flagged: 0, mean: 0, sum: 0 };
+            row.judged += 1;
+            row.sum += score.violation;
+            if (entry.verdict.findings.some(finding => finding.id === score.id))
+                row.flagged += 1;
+            rows.set(score.id, row);
+        }
+    }
+    return [...rows.values()]
+        .map(row => ({ id: row.id, name: row.name, judged: row.judged, flagged: row.flagged, mean: row.judged ? row.sum / row.judged : 0 }))
+        .sort((a, b) => (b.flagged - a.flagged) || (b.mean - a.mean) || a.id.localeCompare(b.id));
+}
+// ---------------------------------------------------------------------------
+// Bench
+/**
+ * The one fixed sample the bench judges. It is built in, so no project content is sent for a bench run; only the
+ * active rule text travels with it.
+ */
+export const BENCH_SAMPLE = {
+    path: "src/warden-bench-sample.ts",
+    content: [
+        "// Built-in so /warden bench measures a rules check without sending project content.",
+        "export interface Sample { id: string; label: string }",
+        "",
+        "export function groupByLabel(items: readonly Sample[]): Map<string, Sample[]> {",
+        "  const groups = new Map<string, Sample[]>();",
+        "  for (const item of items) {",
+        "    const bucket = groups.get(item.label);",
+        "    if (bucket) bucket.push(item);",
+        "    else groups.set(item.label, [item]);",
+        "  }",
+        "  return groups;",
+        "}",
+        "",
+        "export function labels(items: readonly Sample[]): string[] {",
+        "  return [...new Set(items.map((item) => item.label))].sort();",
+        "}",
+        "",
+    ].join("\n"),
+};
+/** Nearest-rank percentile of a sorted, non-empty list of numbers. */
+export function percentile(sorted, p) {
+    if (!sorted.length)
+        return 0;
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[index];
+}
+/**
+ * Judge the built-in sample `runs` times against the active rules, one request at a time so the latency numbers mean
+ * something, and report what the checks cost on this machine. With no judge nothing is sent; a sample the rules keep
+ * out (`rules.exclude`, `rules.skip`) is reported and never sent either.
+ */
+export async function runBench(options) {
+    if (!options.judge)
+        return { status: "no-judge" };
+    const target = { tool: "write", path: BENCH_SAMPLE.path };
+    const reason = skipReason(target, options.set, options.config);
+    if (reason)
+        return { status: "skipped", reason };
+    const now = options.now ?? (() => Date.now());
+    const before = options.getUsage?.();
+    const timings = [];
+    let flagged = 0;
+    let errors = 0;
+    let asked = 0;
+    let aggregate = false;
+    for (let run = 0; run < options.runs; run++) {
+        const started = now();
+        const verdict = await evaluateRules("write", { path: BENCH_SAMPLE.path, content: BENCH_SAMPLE.content }, {
+            cwd: options.cwd, config: options.config, set: options.set, judge: options.judge, timeoutMs: options.timeoutMs, ...(options.signal ? { signal: options.signal } : {}),
+        });
+        timings.push(now() - started);
+        if (verdict.source === "error")
+            errors++;
+        if (verdict.findings.length)
+            flagged++;
+        asked = verdict.asked;
+        aggregate = verdict.aggregate;
+    }
+    const sorted = [...timings].sort((a, b) => a - b);
+    const after = options.getUsage?.();
+    const usage = before && after ? {
+        requests: after.requestsStarted - before.requestsStarted,
+        inputTokens: (after.inputTokens - before.inputTokens) / options.runs,
+        usd: (after.estimatedUsd - before.estimatedUsd) / options.runs,
+    } : undefined;
+    return {
+        status: "done",
+        runs: options.runs,
+        asked,
+        aggregate,
+        flagged,
+        errors,
+        requests: usage?.requests ?? options.runs,
+        p50: Math.round(percentile(sorted, 50)),
+        p95: Math.round(percentile(sorted, 95)),
+        ...(usage ? { meanInputTokens: usage.inputTokens, costPerCheck: usage.usd, costPer100: usage.usd * 100 } : {}),
+    };
+}
+/** The bench output: the numbers, and the line that says no project content was sent. */
+export function formatBench(result) {
+    const lines = [
+        `Bench: ${result.runs} check${result.runs === 1 ? "" : "s"} of one built-in sample file against the active rules (${result.asked} rule${result.asked === 1 ? "" : "s"} per check${result.aggregate ? ", document judged as one rule" : ""}).`,
+        "The sample is built in and no project content is sent, so no confirmation was needed.",
+        `Latency: p50 ${result.p50} ms, p95 ${result.p95} ms; requests ${result.requests}${result.errors ? ` (${result.errors} failed)` : ""}.`,
+    ];
+    if (result.flagged)
+        lines.push(`Findings in ${result.flagged} of ${result.runs} checks (the sample is judged as written code, not as a fixture).`);
+    lines.push(result.meanInputTokens === undefined
+        ? "Input tokens per check: unknown (no usage counters)."
+        : `Input tokens per check: ${Math.round(result.meanInputTokens)} (mean).`);
+    const { costPerCheck, costPer100 } = result;
+    lines.push(costPerCheck === undefined || costPer100 === undefined
+        ? "Estimated cost per check: unknown (no usage counters)."
+        : `Estimated cost per check: ${usd(costPerCheck)}; per 100 edits: ${usd(costPer100)}.`);
+    return lines.join("\n");
+}

package/dist/rules-calibrate.d.ts

@@ -0,0 +1,196 @@
+import type { Judge } from "pi-typesafe";
+import type { RulesConfig } from "./config.js";
+import type { RulesCheckResult } from "./rules-lint.js";
+import type { RuleRecord } from "./rules-log.js";
+import type { RuleFlag } from "./rules-report.js";
+import type { EditView, Rule, RuleSet, RulesTarget } from "./rules.js";
+/**
+ * `/warden rules calibrate`: replay recent git history through the project rules and find the rules that fire on
+ * everything or cannot decide. A rule the sample never caught shows `no violation in sample` and is not flagged: the
+ * replayed commits are mostly reviewed, compliant code, so a rule that never fires there is often a rule people follow. The core is a plain function of the history and the rule set: the history in, per-rule
+ * results out. The caller collects the history (`collectHistory`, read-only `git log -p`), shows the confirm dialog, and
+ * writes the scores to the local rules log; nothing here sends anything on its own and nothing here writes a file.
+ *
+ * Each changed file of each commit becomes one `edit` input: the hunk's removed lines are `oldText`, its added lines are
+ * `newText`, and the file after the commit supplies the surrounding context (`before`/`after` around the change). Binary,
+ * generated, gitignored files and anything under `rules.exclude` or `rules.skip` are skipped, and the requests are capped
+ * at `--max`. `/warden rules tune` reads the flagged rules from the result (and from `/warden rules check`) and asks the
+ * session's agent to rewrite them; that prompt is the only thing tune sends.
+ */
+/** Non-merge commits read when `--commits` is absent. */
+export declare const CALIBRATE_DEFAULT_COMMITS = 20;
+/** Requests sent when `--max` is absent. */
+export declare const CALIBRATE_DEFAULT_MAX = 40;
+export interface HistoryHunk {
+    /** Removed lines of the hunk, newline-joined: the edit's `oldText`. */
+    oldText: string;
+    /** Added lines of the hunk, newline-joined: the edit's `newText`. */
+    newText: string;
+    /** The hunk as the diff shows it: context plus removed lines, the file before the change. */
+    before: string;
+    /** The hunk as the diff shows it: context plus added lines, the file after the change. */
+    after: string;
+    /** 1-based first line of the hunk on the file's after side. */
+    start: number;
+    /** Lines the hunk has on the after side (context plus added). */
+    count: number;
+}
+export interface HistoryFile {
+    /** Project-relative path with forward slashes, as the commit changed it. */
+    path: string;
+    /** A binary patch carries no lines to judge. */
+    binary: boolean;
+    hunks: HistoryHunk[];
+    /** The file's text after the commit, when it still exists there; the edit's context. */
+    after?: string;
+}
+export interface HistoryCommit {
+    hash: string;
+    /** ISO timestamp of the commit. */
+    at: string;
+    files: HistoryFile[];
+}
+/**
+ * The changed files of each commit in one `git log -p` output: one record per commit, one per changed file, and one
+ * `oldText`/`newText` pair per hunk. Pure: the caller runs git and passes the text.
+ */
+export declare function parseHistory(log: string): HistoryCommit[];
+/**
+ * The last `commits` non-merge commits with their patches, and the file after each commit as the edit's context. Read-only:
+ * `git log -p` and `git show`, nothing else. Throws when git cannot read the history (no commits yet, not a repository).
+ */
+export declare function collectHistory(cwd: string, commits: number): HistoryCommit[];
+/** A file the history replay skips, with the same reason wording the live guard reports. */
+export interface CalibrateSkip {
+    path: string;
+    commit: string;
+    reason: string;
+}
+/** Why a changed file is not replayed, or undefined when it is judged. Binary and generated are decided here. */
+export declare function changeSkipReason(file: HistoryFile): string | undefined;
+/** The hunk's `oldText`/`newText` pairs as one `edit` input: the file after the commit around each change is the context. */
+export declare function editViews(file: HistoryFile, contextLines?: number, maxEdits?: number): {
+    edits: EditView[];
+    moreEdits: number;
+};
+export interface CalibrateSample {
+    commit: string;
+    /** ISO timestamp of the commit the change came from. */
+    at: string;
+    path: string;
+    target: RulesTarget;
+}
+export interface CalibratePlan {
+    /** One `edit` input per judged change, in history order (newest first), at most `maxRequests`. */
+    samples: CalibrateSample[];
+    /** Samples past `maxRequests`, not sent. */
+    dropped: CalibrateSample[];
+    /** Requests the run would send: `samples.length`. */
+    requests: number;
+    skipped: CalibrateSkip[];
+}
+export interface PlanOptions {
+    set: RuleSet;
+    config: RulesConfig;
+    /** The project root the paths are relative to; also decides `gitignore` skips. */
+    cwd: string;
+    maxRequests: number;
+}
+/** Which changed files of the history are judged, in what shape, and which are skipped and why. Pure apart from `git check-ignore`. */
+export declare function planCalibration(history: readonly HistoryCommit[], options: PlanOptions): CalibratePlan;
+export interface RuleCalibration {
+    id: string;
+    name: string;
+    /** How often the rule was asked: its `paths` matched a judged file. */
+    applied: number;
+    fired: number;
+    /** fired / applied. */
+    firedRate: number;
+    meanViolation: number;
+    /**
+     * True when the sample held no violation of this rule. Not a flag: replayed commits are mostly reviewed, compliant
+     * code, so a rule that never fires there is often a rule people follow. The line says `no violation in sample`.
+     */
+    unfired: boolean;
+    /** The `/warden report` flags with the same thresholds, without `never fires`: see `unfired`. */
+    flags: RuleFlag[];
+}
+export interface Calibration {
+    rows: RuleCalibration[];
+    /** Rules in the current rule set that no judged file reached. */
+    neverApplied: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Requests sent. */
+    requests: number;
+    /** Requests that came back without an answer; their files are not scored. */
+    failed: number;
+    skipped: CalibrateSkip[];
+    /** Judged changes past the cap, not sent. */
+    dropped: number;
+    /** One record per scored rule, `source: "calibrate"`, for the local rules log. */
+    records: RuleRecord[];
+    commits: number;
+}
+export interface CalibrateOptions extends PlanOptions {
+    judge?: Judge | undefined;
+    timeoutMs: number;
+    /** Session id for the log records; replays default to `calibrate`. */
+    session?: string;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Replay the history through every rule of the set and return per-rule results, worst first: how often the rule applied,
+ * fired, its mean score, and the flags `/warden report` uses. The rules the sample never reached are listed apart. Each
+ * score also comes back as a `RuleRecord` with `source: "calibrate"` for the local rules log. Never throws; a request
+ * that fails is counted in `failed` and leaves its file unscored. With no judge nothing is sent and nothing is scored.
+ */
+export declare function calibrate(history: readonly HistoryCommit[], options: CalibrateOptions): Promise<Calibration>;
+/** One line per rule, worst first: how often it applied and fired, the mean score, and the flags; then the unheard rules. */
+export declare function formatCalibration(result: Calibration): string;
+export type CalibrateGate = {
+    kind: "send";
+} | {
+    kind: "confirm";
+} | {
+    kind: "refuse";
+    reason: string;
+};
+/**
+ * Nothing leaves the machine before the user sees what it is: a UI shows the confirm dialog, and a headless run needs the
+ * explicit `--yes`. `--yes` stands in for the dialog in either case.
+ */
+export declare function calibrateGate(options: {
+    hasUI: boolean;
+    yes: boolean;
+}): CalibrateGate;
+/** What the confirm dialog shows: how many requests go out and what leaves the machine, as redacted diff samples. */
+export declare function calibrationNotice(plan: CalibratePlan): string;
+export interface TuneRule {
+    id: string;
+    name: string;
+    /** The rule's current text as the agent sees it in the rules file. */
+    body: string;
+    /** One line per flag: why this rule is up for a rewrite. */
+    reasons: string[];
+}
+/** The rules the latest calibrate flagged, plus the ones `/warden rules check` flagged this session, with the reasons. */
+export declare function tuneTargets(options: {
+    calibration?: Calibration | undefined;
+    check?: RulesCheckResult | undefined;
+    rules: readonly Rule[];
+}): TuneRule[];
+/** One prompt for the session's agent: each flagged rule, why it was flagged, and the ask for a concrete rewrite. */
+export declare function buildTunePrompt(targets: readonly TuneRule[]): string;
+export type TuneRequest = {
+    prompt: string;
+} | {
+    reason: string;
+};
+/** The prompt to send, or the reason to say so and send nothing when no rule is flagged. */
+export declare function tuneRequest(options: {
+    calibration?: Calibration | undefined;
+    check?: RulesCheckResult | undefined;
+    rules: readonly Rule[];
+}): TuneRequest;