pi-warden 0.71.0 → 0.74.0

package/dist/rules.d.ts

@@ -9,10 +9,12 @@ import type { RulesConfig } from "./config.js";
  */
 /** How badly a rule matters; used only to order findings, never to decide whether a rule fires. */
 export type RuleSeverity = "high" | "normal" | "low";
+/** When a rule is judged: `edit` on each write or edit (the default), `turn` once at the end of a run against the whole diff. */
+export type RuleWhen = "edit" | "turn";
 export interface Rule {
     id: string;
     name: string;
-    /** Rule text under the heading, fences included, `paths:`/`threshold:`/`severity:` lines removed. */
+    /** Rule text under the heading, fences included, `paths:`/`threshold:`/`severity:`/`source:` lines removed. */
     body: string;
     /** Globs the rule applies to; empty means every file. */
     paths: string[];
@@ -20,6 +22,13 @@ export interface Rule {
     threshold?: number;
     /** Ordering only; absent means `normal`. */
     severity?: RuleSeverity;
+    /** The `source: <file>:<line>` header: the instruction line the rule's wording came from. */
+    sourceRef?: {
+        file: string;
+        line: number;
+    };
+    /** `turn` rules are judged once per run against the whole diff, never per edit; absent means `edit`. */
+    when?: RuleWhen;
     /** Header lines that carried a bad value, reported by `/warden rules`; the line is dropped either way. */
     headerWarnings?: string[];
     /** Project-relative source file when the rule came from a resolved RuleSet. */
@@ -50,6 +59,11 @@ 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;
+export declare const EDIT_TEXT_LIMIT = 1500;
+export declare const EDIT_CONTEXT_LINES = 20;
+export declare const MAX_EDITS = 6;
+export declare const RULE_BODY_LIMIT = 400;
+export declare const STEER_BODY_LIMIT = 200;
 /**
  * A fallback document cut to `limit` characters while keeping its shape: every heading stays and each section keeps its
  * head, so a rule stated in the last section of a very long AGENTS.md is still seen. Code inside fences is treated as text.
@@ -84,6 +98,10 @@ export declare class RuleStore {
 }
 /** Rules that apply to a path: unscoped rules plus those whose `paths` match. */
 export declare function rulesFor(set: RuleSet, path: string): Rule[];
+/** Rules asked about a write or edit: those that apply to the path without a `when: turn` header. */
+export declare function editRulesFor(set: RuleSet, path: string): Rule[];
+/** Rules judged once per run against the whole diff: those with a `when: turn` header. */
+export declare function turnRulesFor(set: RuleSet): Rule[];
 export declare function describeRuleSet(set: RuleSet | undefined): string;
 /** Detailed local-only view for `/warden rules`; nothing here is sent to Jev. */
 export declare function formatRuleSetDetails(set: RuleSet | undefined, tier: RulesTier, exclude?: readonly string[]): string;
@@ -107,10 +125,11 @@ export interface RulesTarget {
 /** The redacted content of a write or edit as Jev sees it, or undefined when the call carries nothing to judge. */
 export declare function describeTarget(tool: string, input: Record<string, unknown>, cwd: string): RulesTarget | undefined;
 export type RuleOutcome = "compliant" | "violation" | "not_applicable" | "insufficient_context";
+export declare const OUTCOMES: Record<RuleOutcome, string>;
 export declare const AGGREGATE_QUESTION = "rules";
 export declare const LOCATOR_QUESTION = "which_edit";
 export declare function ruleQuestion(rule: Rule): import("pi-typesafe").ChoiceQuestion<Record<RuleOutcome, string>>;
-/** The rules asked about for a write: scoped to its path first, then cut to the request cap in file order. */
+/** The rules asked about for a write: scoped to its path first, `when: turn` rules excluded, then cut to the request cap in file order. */
 export declare function buildRulesRequest(target: RulesTarget, set: RuleSet): {
     firstDropped?: string;
     state: {
@@ -138,14 +157,38 @@ export interface RuleScore {
     threshold?: number;
     /** The rule's severity when it set one; absent means `normal`. */
     severity?: RuleSeverity;
+    /** The instruction line the rule's wording came from when its `source:` header set one. */
+    sourceRef?: {
+        file: string;
+        line: number;
+    };
 }
 export interface RuleFinding extends RuleScore {
     body: string;
 }
+/** One answer of the judge as the scoring reads it: the choice it picked and the probabilities behind it. */
+export type RuleAnswer = {
+    type: string;
+    choice?: string;
+    probabilities?: Record<string, number>;
+} | undefined;
+export interface RuleScoring {
+    scores: RuleScore[];
+    /** Violations at or above the rule's cutoff, severity first then strongest. */
+    findings: RuleFinding[];
+    /** Scores at or above `rules.softThreshold` but below the rule's cutoff. */
+    softFindings: RuleFinding[];
+}
+/**
+ * Score the judge's answers rule by rule: one score each, a finding at the rule's own cutoff (or `rules.threshold` when
+ * the rule sets none), and a soft finding between `rules.softThreshold` and that cutoff. An aggregate document is one
+ * rule under its source's name. Shared by the live guard and history replays, so both respect the same cutoffs.
+ */
+export declare function scoreRuleAnswers(applicable: readonly Rule[], answers: Record<string, RuleAnswer>, config: RulesConfig, aggregateName?: string): RuleScoring;
 export interface RulesVerdict {
     source: "skipped" | "typesafe" | "error";
     path: string;
-    tool: "write" | "edit";
+    tool: "write" | "edit" | "turn";
     sources: string[];
     /** Rules asked about, after path scoping and the cap; 1 for an aggregate document. */
     asked: number;
@@ -175,11 +218,35 @@ export interface RulesOptions {
     timeoutMs: number;
     signal?: AbortSignal | undefined;
 }
-/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd`. Returns false when git is unavailable or the path cannot be checked. */
-export declare function gitIgnored(projectRel: string, cwd: string): boolean;
+/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd` (with `--no-index`, so a force-added ignored file still counts as ignored). Returns false when git is unavailable or the path cannot be checked. */
+export declare function gitIgnored(projectRel: string, cwd: string, noIndex?: boolean): boolean;
 /** Why a write or edit is not judged against the rules: nothing to judge, no rules, or a path the config keeps out. */
 export declare function skipReason(target: RulesTarget | undefined, set: RuleSet | undefined, config: RulesConfig): string | undefined;
+/** One request's answer payload as Jev returns it. */
+/** One question in a rules request: its key, the rule it came from, and the body quoted in a steer. */
+export interface RuleScoreEntry {
+    key: string;
+    id: string;
+    name: string;
+    body: string;
+    /** The rule's own cutoff, severity, and source citation when it set them. */
+    rule?: Pick<Rule, "threshold" | "severity" | "sourceRef">;
+}
+/**
+ * Scores and findings for one request's answers: a finding needs the rule's own cutoff when it set one, else the global
+ * threshold, and the soft tier sits under that cutoff. Findings are ordered severity first, then the strongest score.
+ */
+export declare function scoreAnswers(answers: Record<string, RuleAnswer | undefined>, entries: readonly RuleScoreEntry[], config: RulesConfig): {
+    scores: RuleScore[];
+    findings: RuleFinding[];
+    softFindings: RuleFinding[];
+};
 export declare function evaluateRules(tool: string, input: Record<string, unknown>, options: RulesOptions): Promise<RulesVerdict>;
+/**
+ * The judgment half of `evaluateRules` for a prepared target: skip reasons, one request, scores, findings. A caller that
+ * builds its own target (the end-of-run pass judges a file's diff as one edit) gets the same question and scoring.
+ */
+export declare function evaluateRulesTarget(target: RulesTarget | undefined, tool: string, shownPath: string, options: RulesOptions): Promise<RulesVerdict>;
 /** Names each violated rule with a short quote of its text; the third hit of one rule in a session makes it a standing rule. */
 export declare function rulesSteer(verdict: RulesVerdict, counts: ReadonlyMap<string, number>): string;
 export declare function formatRules(verdict: RulesVerdict, template?: string): string;

package/dist/rules.js

@@ -12,11 +12,11 @@ export const FALLBACK_FILES = ["AGENTS.md", "CLAUDE.md", "README.md"];
 /** TypeSafe answers at most 32 questions per request; one is kept for the edit locator. */
 export const MAX_RULES = 31;
 const CONTENT_LIMIT = 6000;
-const EDIT_TEXT_LIMIT = 1500;
-const EDIT_CONTEXT_LINES = 20;
-const MAX_EDITS = 6;
-const RULE_BODY_LIMIT = 400;
-const STEER_BODY_LIMIT = 200;
+export const EDIT_TEXT_LIMIT = 1500;
+export const EDIT_CONTEXT_LINES = 20;
+export const MAX_EDITS = 6;
+export const RULE_BODY_LIMIT = 400;
+export const STEER_BODY_LIMIT = 200;
 const ID_LIMIT = 64;
 const RULE_SHAPE_CONTEXT_LINES = 15;
 const MODAL_WORDS = /^(?:must|shall|never|always|do not|don't|cannot|can't|avoid|prefer|require|should not|shouldn't|no |not )/i;
@@ -28,7 +28,10 @@ const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
 const PATHS_LINE = /^\s*(?:paths?|applies to|files?)\s*:\s*(.+?)\s*$/i;
 const THRESHOLD_LINE = /^\s*threshold\s*:\s*(.+?)\s*$/i;
 const SEVERITY_LINE = /^\s*severity\s*:\s*(.+?)\s*$/i;
+const SOURCE_REF_LINE = /^\s*source\s*:\s*(.+?)\s*$/i;
+const WHEN_LINE = /^\s*when\s*:\s*(.+?)\s*$/i;
 const SEVERITIES = ["high", "normal", "low"];
+const WHENS = ["edit", "turn"];
 function slug(name, used) {
     const full = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
     // Cut at a word boundary so a long heading keeps whole words in its id.
@@ -109,10 +112,14 @@ export function parseRules(markdown) {
         let paths = [];
         let threshold;
         let severity;
+        let sourceRef;
+        let when;
         const headerWarnings = [];
         let seenPaths = false;
         let seenThreshold = false;
         let seenSeverity = false;
+        let seenSource = false;
+        let seenWhen = false;
         // Header lines may sit in any order and at most once. A bad value is dropped with a warning; the line never stays in the body.
         for (;;) {
             const first = lines.findIndex(text => text.trim());
@@ -159,12 +166,46 @@ export function parseRules(markdown) {
                 }
                 continue;
             }
+            // One small block for the `source: <file>:<line>` citation header, beside the other header lines.
+            const cited = SOURCE_REF_LINE.exec(line);
+            if (cited) {
+                lines.splice(first, 1);
+                const raw = cited[1].replace(/^`|`$/g, "").trim();
+                const ref = /^(.+):(\d+)$/.exec(raw);
+                const file = ref?.[1]?.trim();
+                const at = ref ? Number(ref[2]) : 0;
+                if (seenSource)
+                    headerWarnings.push("source: appears more than once; the first is kept");
+                else if (!file || !at)
+                    headerWarnings.push(`source: ${raw || "(empty)"} is not a file:line reference; ignored`);
+                else {
+                    sourceRef = { file, line: at };
+                    seenSource = true;
+                }
+                continue;
+            }
+            const timing = WHEN_LINE.exec(line);
+            if (timing) {
+                lines.splice(first, 1);
+                const raw = timing[1].trim().toLowerCase();
+                if (seenWhen)
+                    headerWarnings.push("when: appears more than once; the first is kept");
+                else if (!WHENS.includes(raw))
+                    headerWarnings.push(`when: ${timing[1].trim() || "(empty)"} is not edit or turn; ignored`);
+                else {
+                    when = raw;
+                    seenWhen = true;
+                }
+                continue;
+            }
             break;
         }
         return {
             id: slug(draft.name, used), name: draft.name.trim(), body: lines.join("\n").trim(), paths,
             ...(threshold === undefined ? {} : { threshold }),
             ...(severity === undefined ? {} : { severity }),
+            ...(sourceRef === undefined ? {} : { sourceRef }),
+            ...(when === undefined ? {} : { when }),
             ...(headerWarnings.length ? { headerWarnings } : {}),
         };
     });
@@ -321,6 +362,14 @@ function ruleSet(sources, texts, maxChars) {
 export function rulesFor(set, path) {
     return set.rules.filter(rule => !rule.paths.length || matchGlob(path, rule.paths) !== undefined);
 }
+/** Rules asked about a write or edit: those that apply to the path without a `when: turn` header. */
+export function editRulesFor(set, path) {
+    return rulesFor(set, path).filter(rule => rule.when !== "turn");
+}
+/** Rules judged once per run against the whole diff: those with a `when: turn` header. */
+export function turnRulesFor(set) {
+    return set.rules.filter(rule => rule.when === "turn");
+}
 export function describeRuleSet(set) {
     if (!set)
         return "none found";
@@ -350,6 +399,8 @@ export function formatRuleSetDetails(set, tier, exclude = []) {
             `paths: ${rule.paths.length ? rule.paths.join(", ") : "(all)"}`,
             ...(rule.threshold === undefined ? [] : [`threshold: ${rule.threshold}`]),
             ...(rule.severity === undefined ? [] : [`severity: ${rule.severity}`]),
+            ...(rule.sourceRef === undefined ? [] : [`source: ${rule.sourceRef.file}:${rule.sourceRef.line}`]),
+            ...(rule.when === undefined || rule.when === "edit" ? [] : [`when: ${rule.when}`]),
         ].join(", ");
         lines.push(`${index + 1}. ${rule.id}${from} ${settings}`);
         if (rule.headerWarnings?.length)
@@ -431,7 +482,7 @@ export function describeTarget(tool, input, cwd) {
     const more = input.edits.length - MAX_EDITS;
     return { tool, path, edits, ...(more > 0 ? { moreEdits: more } : {}) };
 }
-const OUTCOMES = {
+export const OUTCOMES = {
     compliant: "The change follows this rule, or leaves an earlier violation as it was.",
     violation: "The change introduces a violation of this rule.",
     not_applicable: "This rule does not concern the kind of content written: another language, file type, or subject.",
@@ -443,9 +494,9 @@ export const LOCATOR_QUESTION = "which_edit";
 export function ruleQuestion(rule) {
     return choice(`${FRAME}\nRule: ${rule.name}\n${rule.body ? clip(rule.body, RULE_BODY_LIMIT) : "(no further detail beyond the heading)"}`, OUTCOMES);
 }
-/** The rules asked about for a write: scoped to its path first, then cut to the request cap in file order. */
+/** The rules asked about for a write: scoped to its path first, `when: turn` rules excluded, then cut to the request cap in file order. */
 export function buildRulesRequest(target, set) {
-    const scoped = rulesFor(set, target.path);
+    const scoped = editRulesFor(set, target.path);
     const applicable = scoped.slice(0, MAX_RULES);
     const dropped = scoped.length - applicable.length;
     const questions = {};
@@ -476,10 +527,21 @@ export function buildRulesRequest(target, set) {
         ...(dropped ? { firstDropped: scoped[MAX_RULES].id } : {}),
     };
 }
-/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd`. Returns false when git is unavailable or the path cannot be checked. */
-export function gitIgnored(projectRel, cwd) {
+/**
+ * Score the judge's answers rule by rule: one score each, a finding at the rule's own cutoff (or `rules.threshold` when
+ * the rule sets none), and a soft finding between `rules.softThreshold` and that cutoff. An aggregate document is one
+ * rule under its source's name. Shared by the live guard and history replays, so both respect the same cutoffs.
+ */
+export function scoreRuleAnswers(applicable, answers, config, aggregateName) {
+    const entries = aggregateName !== undefined
+        ? [{ key: AGGREGATE_QUESTION, id: AGGREGATE_QUESTION, name: aggregateName, body: "" }]
+        : applicable.map(rule => ({ key: `rule_${rule.id}`, id: rule.id, name: rule.name, body: rule.body, rule }));
+    return scoreAnswers(answers, entries, config);
+}
+/** Check whether a project-relative path is ignored by the project's gitignore rules. Uses `git check-ignore -q` run from `cwd` (with `--no-index`, so a force-added ignored file still counts as ignored). Returns false when git is unavailable or the path cannot be checked. */
+export function gitIgnored(projectRel, cwd, noIndex = false) {
     try {
-        execFileSync("git", ["check-ignore", "-q", projectRel], { cwd, timeout: 2000, stdio: "pipe" });
+        execFileSync("git", ["check-ignore", ...(noIndex ? ["--no-index"] : []), "-q", projectRel], { cwd, timeout: 2000, stdio: "pipe" });
         return true;
     }
     catch {
@@ -500,16 +562,54 @@ export function skipReason(target, set, config) {
         return `rules do not apply by rules.skip (${skipped})`;
     if (set.proseOnly)
         return `no rules found in ${set.sources.join(", ")} (prose only)`;
-    if (set.rules.length && !rulesFor(set, target.path).length)
+    if (set.rules.length && !editRulesFor(set, target.path).length)
         return "no rule's paths match this file";
     return undefined;
 }
 function skipped(target, tool, path, set, reason) {
     return { source: "skipped", tool: target?.tool ?? (tool === "edit" ? "edit" : "write"), path, sources: set?.sources ?? [], asked: 0, aggregate: false, findings: [], skippedReason: reason };
 }
+/**
+ * Scores and findings for one request's answers: a finding needs the rule's own cutoff when it set one, else the global
+ * threshold, and the soft tier sits under that cutoff. Findings are ordered severity first, then the strongest score.
+ */
+export function scoreAnswers(answers, entries, config) {
+    const scores = [];
+    const findings = [];
+    const softFindings = [];
+    const softThreshold = config.softThreshold ?? 0;
+    for (const entry of entries) {
+        const answer = answers[entry.key];
+        if (!answer || typeof answer.choice !== "string")
+            continue;
+        const violation = answer.probabilities?.violation ?? (answer.choice === "violation" ? 1 : 0);
+        const outcome = (answer.choice in OUTCOMES ? answer.choice : "insufficient_context");
+        const score = {
+            id: entry.id, name: entry.name, outcome, violation,
+            ...(entry.rule?.threshold === undefined ? {} : { threshold: entry.rule.threshold }),
+            ...(entry.rule?.severity === undefined ? {} : { severity: entry.rule.severity }),
+            ...(entry.rule?.sourceRef === undefined ? {} : { sourceRef: entry.rule.sourceRef }),
+        };
+        const cutoff = entry.rule?.threshold ?? config.threshold;
+        scores.push(score);
+        if (score.violation >= cutoff)
+            findings.push({ ...score, body: entry.body });
+        else if (softThreshold > 0 && score.violation >= softThreshold)
+            softFindings.push({ ...score, body: entry.body });
+    }
+    findings.sort(bySeverityThenScore);
+    softFindings.sort(bySeverityThenScore);
+    return { scores, findings, softFindings };
+}
 export async function evaluateRules(tool, input, options) {
     const target = describeTarget(tool, input, options.cwd);
-    const shownPath = target?.path ?? (typeof input.path === "string" ? input.path : tool);
+    return evaluateRulesTarget(target, tool, typeof input.path === "string" ? input.path : tool, options);
+}
+/**
+ * The judgment half of `evaluateRules` for a prepared target: skip reasons, one request, scores, findings. A caller that
+ * builds its own target (the end-of-run pass judges a file's diff as one edit) gets the same question and scoring.
+ */
+export async function evaluateRulesTarget(target, tool, shownPath, options) {
     const { set } = options;
     const reason = skipReason(target, set, options.config);
     if (reason || !target || !set)
@@ -523,46 +623,7 @@ export async function evaluateRules(tool, input, options) {
     if (!result.ok)
         return { source: "error", ...base, findings: [], error: result.error, ...(result.errorCode ? { errorCode: result.errorCode } : {}) };
     const answers = result.answers;
-    const read = (key, id, name) => {
-        const answer = answers[key];
-        if (!answer || typeof answer.choice !== "string")
-            return undefined;
-        const violation = answer.probabilities?.violation ?? (answer.choice === "violation" ? 1 : 0);
-        const outcome = (answer.choice in OUTCOMES ? answer.choice : "insufficient_context");
-        return { id, name, outcome, violation };
-    };
-    const scores = [];
-    const findings = [];
-    const softFindings = [];
-    const softThreshold = options.config.softThreshold ?? 0;
-    // A finding needs the rule's own cutoff when it set one, else the global threshold. The soft tier sits under that cutoff.
-    const scoreRule = (score, rule, body) => {
-        const cutoff = rule?.threshold ?? options.config.threshold;
-        const scored = {
-            ...score,
-            ...(rule?.threshold === undefined ? {} : { threshold: rule.threshold }),
-            ...(rule?.severity === undefined ? {} : { severity: rule.severity }),
-        };
-        scores.push(scored);
-        if (scored.violation >= cutoff)
-            findings.push({ ...scored, body });
-        else if (softThreshold > 0 && scored.violation >= softThreshold)
-            softFindings.push({ ...scored, body });
-    };
-    if (aggregate) {
-        const score = read(AGGREGATE_QUESTION, AGGREGATE_QUESTION, `the project's ${set.sources[0]}`);
-        if (score)
-            scoreRule(score, undefined, "");
-    }
-    else {
-        for (const rule of request.applicable) {
-            const score = read(`rule_${rule.id}`, rule.id, rule.name);
-            if (score)
-                scoreRule(score, rule, rule.body);
-        }
-    }
-    findings.sort(bySeverityThenScore);
-    softFindings.sort(bySeverityThenScore);
+    const { scores, findings, softFindings } = scoreRuleAnswers(request.applicable, answers, options.config, aggregate ? `the project's ${set.sources[0]}` : undefined);
     const verdict = { source: "typesafe", ...base, scores, findings, ...(softFindings.length ? { softFindings } : {}), model: result.model, elapsedMs: result.elapsedMs };
     const locator = answers[LOCATOR_QUESTION];
     if (findings.length && typeof locator?.choice === "string") {
@@ -590,7 +651,8 @@ export function rulesSteer(verdict, counts) {
         const count = counts.get(finding.id) ?? 0;
         const repeat = count >= 3 ? `; ${count}${count === 3 ? "rd" : "th"} time this session` : "";
         const body = finding.body ? `: ${clip(finding.body.replace(/\s+/g, " ").trim(), STEER_BODY_LIMIT).replace(/[.;:,]+$/, "")}` : "";
-        return `"${finding.name}" (${finding.violation.toFixed(2)}${repeat})${body}`;
+        const from = finding.sourceRef ? ` (from ${finding.sourceRef.file} line ${finding.sourceRef.line})` : "";
+        return `"${finding.name}"${from} (${finding.violation.toFixed(2)}${repeat})${body}`;
     }).join("; ");
     // The steer names the rule and the written file only: a named rules or config file sends a weak model off to read it.
     const what = verdict.aggregate ? "breaks a project rule" : `violates project rule${verdict.findings.length === 1 ? "" : "s"}`;

package/dist/shape.js

@@ -1,5 +1,5 @@
 import { isMode } from "./config.js";
-import { resolveBackend } from "./backend.js";
+import { resolveJudgmentBackend } from "./backend.js";
 import { redact } from "./redact.js";
 import { DEFAULT_TEMPLATES } from "./widget.js";
 /** The config layout this extension build expects; compared with the loaded config module's CONFIG_SCHEMA. */
@@ -8,6 +8,10 @@ const off = { enabled: false };
 // Duplicated from defaultConfig(): this file must work when the config module is stale and lacks the key.
 const coreTools = () => ["read", "bash", "edit", "write", "grep", "find", "ls"];
 const proseOff = () => ({ ...off, audience: "technical", threshold: 1, trend: 3, minChars: 1 });
+// A stale config module hands back either its own resolution or a raw value; both end up resolved here.
+const resolveSetting = (source) => source.backendRefusal !== undefined
+    ? { typesafeBackend: source.typesafeBackend, backendRefusal: source.backendRefusal }
+    : resolveJudgmentBackend(source.typesafeBackend);
 /**
  * `loadConfig()` always returns a complete object, yet live sessions crashed at `config.slop.prose.enabled` after a package
  * update. A partially updated module graph (extension from one version, config from another) is the only known way to get
@@ -23,10 +27,12 @@ export function completeConfig(loaded) {
         missing.push(key);
         return fallback;
     };
+    const backend = resolveSetting(source);
     const config = {
         enabled: source.enabled ?? true,
         typesafe: source.typesafe ?? false,
-        typesafeBackend: resolveBackend(source.typesafeBackend),
+        typesafeBackend: backend.typesafeBackend,
+        backendRefusal: backend.backendRefusal,
         mode: isMode(source.mode) ? source.mode : "steer",
         timeoutMs: source.timeoutMs ?? 5000,
         maxRequests: source.maxRequests ?? 500,

package/dist/turn-rules.d.ts

@@ -0,0 +1,86 @@
+import type { Judge } from "pi-typesafe";
+import type { RulesConfig } from "./config.js";
+import type { Rule, RulesVerdict, RuleSet } from "./rules.js";
+import type { ShellSkip } from "./shell-writes.js";
+/** The verdict path for a judgment about the whole run; the rules log keys clears by path, so it must not look like a file. */
+export declare const TURN_PATH = "(whole turn)";
+export declare const TURN_QUESTION_PREFIX = "turn_";
+/** The files judged per shell command and per run; beyond the cap the files are named in the trace and left out. */
+export declare const SHELL_RULES_CHECKS = 5;
+export type SnapshotResult = {
+    tree: string;
+    reason?: undefined;
+} | {
+    tree?: undefined;
+    reason: string;
+};
+/** The run's baseline; `reason` says why turn rules are skipped this run and earns one trace line in the caller. */
+export declare function snapshotTree(cwd: string): Promise<SnapshotResult>;
+export interface TurnFileDiff {
+    /** Project-relative path with forward slashes. */
+    path: string;
+    /** `M`, `A`, or `D`, as git reports it between the two trees. */
+    status: string;
+    /** This file's unified diff, capped at `maxChars` with an inline note when cut. */
+    diff: string;
+}
+export interface TurnDiff {
+    files: TurnFileDiff[];
+    /** The whole change for the turn question: every file's diff joined, capped at `maxChars` in total. */
+    text: string;
+    /** What the caps cut, named per file, so the request and the trace say what the judge does not see. */
+    cuts: string[];
+}
+/**
+ * The working-tree change since the snapshot: the files git reports and each one's unified diff, capped per file and
+ * in total at `maxChars` (the `rules.maxChars` cap), each cut named. Untracked non-ignored files are in both trees, so
+ * they appear here like any other change. Undefined when the end-of-run snapshot fails.
+ */
+export declare function diffSince(cwd: string, startTree: string, maxChars: number): Promise<TurnDiff | undefined>;
+export declare function turnRuleQuestion(rule: Rule): import("pi-typesafe").ChoiceQuestion<Record<import("./rules.js").RuleOutcome, string>>;
+export declare function buildTurnRequest(task: string, diff: string, rules: readonly Rule[], cuts?: readonly string[]): {
+    state: {
+        truncated?: string;
+        task: string;
+        diff: string;
+    };
+    questions: Record<string, import("pi-typesafe").ChoiceQuestion<import("@typesafe-ai/sdk").ChoiceCriteria>>;
+};
+export interface TurnRulesOptions {
+    judge: Judge;
+    config: RulesConfig;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    sources: readonly string[];
+}
+/** One request that judges the turn rules against the whole diff and the task. */
+export declare function evaluateTurnRules(task: string, diff: string, rules: readonly Rule[], options: TurnRulesOptions): Promise<RulesVerdict>;
+export interface TurnRunOptions {
+    cwd: string;
+    config: RulesConfig;
+    set: RuleSet | undefined;
+    judge?: Judge | undefined;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    /** The user's request for this run. */
+    task?: string | undefined;
+    /** The snapshot tree taken at the start of the run. */
+    startTree: string;
+    /** Project-relative paths a `write`, `edit`, or literal shell write already judged during this run. */
+    alreadyJudged: ReadonlySet<string>;
+}
+export interface TurnRunResult {
+    /** The turn verdict first (when turn rules exist), then one per file a per-edit judgment never saw. */
+    verdicts: RulesVerdict[];
+    /** What the caps cut from the diff, named per file. */
+    cuts: string[];
+    /** Files the per-run request cap left unjudged, named for the trace like the shell path's skips. */
+    skips: ShellSkip[];
+    /** Why nothing was judged, when the pass was skipped; absent when there was nothing to judge or it ran. */
+    skipped?: string;
+}
+/** Which files of the diff no per-edit judgment saw: in-place and generated changes, and subagent writes. */
+export declare function unjudgedFiles(diff: TurnDiff, alreadyJudged: ReadonlySet<string>): TurnFileDiff[];
+export declare function evaluateTurnRun(options: TurnRunOptions): Promise<TurnRunResult>;
+/** Names each violated rule like the per-edit steer; one message covers the turn verdict and the missed files. */
+export declare function turnSteer(verdicts: readonly RulesVerdict[], counts: ReadonlyMap<string, number>): string | undefined;