@alex-dbs/coderuler 1.3.0 → 1.4.0

package/README.md

@@ -114,14 +114,17 @@ export default class SafeResponseHeaders extends Rule {
   });
 
   check = ai({
-    rule: 'Report a violation only when this function writes request data into an HTTP response header without rejecting CR and LF first. Judge only this function. Do not assume unseen callers or helpers validate the data.',
+    instruction: `Reject CR and LF in untrusted values before inserting them into
+HTTP response headers or status lines.
+This policy covers response construction and writes visible in the selected function. Hidden helper behavior and unseen callers are outside its scope.
+Treat serialization arguments and statusMessage as untrusted. Fixed values and values checked for both CR and LF meet the requirement. Preserve fixed HTTP delimiters.`,
     input: subject => (subject as ScopeSubject).source,
     violationMessage: 'Reject CR and LF in request data before writing a response header.',
   });
 }
 ```
 
-This example shows an AI check for CWE-113. 
+This example shows an AI check for CWE-113.
 
 AI rules require a configured service and can incur charges.
 

package/dist/adapter/cli/commands/test.js

@@ -22,7 +22,7 @@ async function runTest(rulePath, options, context, services) {
         context.write(renderRuleTestHeading(ruleName, context.redact, color));
         previousRuleName = ruleName;
         for (let index = 0; index < failures.length; index += 1) {
-            context.write(renderRuleTestResult(failures[index], context.redact, color, index === failures.length - 1));
+            context.write(renderRuleTestResult(failures[index], context.redact, color, index === failures.length - 1, options.aiScores === true));
         }
         failures.length = 0;
     };
@@ -53,7 +53,7 @@ async function runTest(rulePath, options, context, services) {
                     context.write(renderRuleTestHeading(result.ruleName, context.redact, color));
                     previousRuleName = result.ruleName;
                 }
-                context.write(renderRuleTestResult(result, context.redact, color, lastInRule));
+                context.write(renderRuleTestResult(result, context.redact, color, lastInRule, options.aiScores === true));
             }
             progress?.message(`Running tests (${passed + failed} completed)`);
         }, options.timeout, options.concurrency, options.ai === true);

package/dist/adapter/cli/program.js

@@ -128,6 +128,7 @@ export function createProgram(services) {
         .description('Run the declared test cases for the selected rules')
         .argument('[rule]', 'rule name, module path, or directory')
         .option('--ai', 'include aiTests that use the configured decision backend')
+        .option('--ai-scores', 'show Jev scores for aiTests')
         .option('--failures-only', 'show only failed test cases')
         .addOption(new Option('--timeout <duration>', 'per-test timeout (ms, s, or m)')
         .argParser(parseTimeout)

package/dist/adapter/cli/reports.d.ts

@@ -4,7 +4,7 @@ import type { ViolationComment } from '../../app/violation-comments.js';
 import { type TextRedactor, type TextWriter } from './text.js';
 export type RuleHeadings = (name: string) => readonly string[];
 export declare function renderRuleTestHeading(ruleName: string, redact: TextRedactor, color: boolean): string;
-export declare function renderRuleTestResult(result: RuleTestResult, redact: TextRedactor, color: boolean, lastInRule: boolean): string;
+export declare function renderRuleTestResult(result: RuleTestResult, redact: TextRedactor, color: boolean, lastInRule: boolean, showAIScores?: boolean): string;
 export declare function renderRuleTestSummary(passed: number, failed: number, durationMs: number, redact: TextRedactor, color: boolean): string;
 export declare function createRuleHeadings(rules: readonly LoadedRule[]): RuleHeadings;
 export declare function createMetadataRenderer(write: TextWriter, redact: TextRedactor): (event: RunEvent) => void;

package/dist/adapter/cli/reports.js

@@ -36,7 +36,7 @@ function sourceText(line) {
 export function renderRuleTestHeading(ruleName, redact, color) {
     return `${paint(escapeText(redact(ruleName)), 'bold', color)}\n`;
 }
-export function renderRuleTestResult(result, redact, color, lastInRule) {
+export function renderRuleTestResult(result, redact, color, lastInRule, showAIScores = false) {
     const safe = (text) => escapeText(redact(text));
     const matches = result.expected === result.actual;
     const label = paint(safe(matches ? 'PASS' : 'FAIL'), matches ? 'green' : 'red', color);
@@ -44,8 +44,11 @@ export function renderRuleTestResult(result, redact, color, lastInRule) {
     const detail = matches
         ? ''
         : safe(` (expected ${result.expected}, actual ${result.actual})`);
+    const aiScores = showAIScores && result.aiScores !== undefined && result.aiScores.length > 0
+        ? ` (${result.aiScores.length === 1 ? 'Jev score' : 'Jev scores'}: ${result.aiScores.join(', ')})`
+        : '';
     const duration = paint(safe(` (${formatDuration(result.durationMs)})`), 'dim', color);
-    return `${branch}${label} ${safe(result.name)}${detail}${duration}\n`;
+    return `${branch}${label} ${safe(result.name)}${detail}${aiScores}${duration}\n`;
 }
 export function renderRuleTestSummary(passed, failed, durationMs, redact, color) {
     const safe = (text) => escapeText(redact(text));

package/dist/adapter/cli/services.d.ts

@@ -44,6 +44,7 @@ export interface TestOptions {
     readonly concurrency: number;
     readonly ai?: boolean;
     readonly failuresOnly?: boolean;
+    readonly aiScores?: boolean;
 }
 export interface DependencyOptions {
     readonly global?: boolean;

package/dist/adapter/filesystem/rule-test-worker.d.ts

@@ -8,9 +8,13 @@ export interface RuleTestWorkerRequest {
     readonly ai: boolean;
     readonly dependencies?: PreparedRuleDependencies;
 }
+export interface RuleTestWorkerOutcome {
+    readonly actual: RuleTestCase['expected'];
+    readonly aiScores?: readonly number[];
+}
 export type RuleTestWorkerMessage = {
     readonly id: number;
-    readonly actual: RuleTestCase['expected'];
+    readonly outcome: RuleTestWorkerOutcome;
 } | {
     readonly id: number;
     readonly error: string;

package/dist/adapter/filesystem/rule-test-worker.js

@@ -32,7 +32,15 @@ async function runCase({ root, ruleFile, files, ai, dependencies }) {
     const report = reports[0];
     if (reports.length !== 1 || report === undefined)
         throw new Error('Expected exactly one rule report');
-    return report.status;
+    let aiScores;
+    if (ai) {
+        for (const evaluation of report.evaluations) {
+            const score = evaluation.result.probability;
+            if (score !== undefined)
+                (aiScores ??= []).push(score);
+        }
+    }
+    return { actual: report.status, ...(aiScores === undefined ? {} : { aiScores }) };
 }
 const port = parentPort;
 if (port === null)
@@ -40,7 +48,7 @@ if (port === null)
 port.start();
 port.ref();
 port.on('message', (request) => {
-    void runCase(request).then(actual => port.postMessage({ id: request.id, actual }), error => port.postMessage({
+    void runCase(request).then(outcome => port.postMessage({ id: request.id, outcome }), error => port.postMessage({
         id: request.id,
         error: error instanceof Error ? error.message : String(error),
     }));

package/dist/adapter/filesystem/rule-tests.js

@@ -75,7 +75,7 @@ class RuleTestWorkerSession {
             else if ('error' in message)
                 result.reject(new Error(message.error));
             else
-                result.resolve(message.actual);
+                result.resolve(message.outcome);
         };
         this.rejectPending = error => {
             if (performance.now() >= deadline)
@@ -129,6 +129,7 @@ async function runCase(entry, example, ai, timeoutMs, session, onFailure) {
     try {
         const root = await mkdtemp(join(await realpath(tmpdir()), 'coderuler-test-'));
         let actual;
+        let aiScores;
         let active;
         try {
             if (session.cancelled)
@@ -138,10 +139,16 @@ async function runCase(entry, example, ai, timeoutMs, session, onFailure) {
             else {
                 active = session.current ??= new RuleTestWorkerSession();
                 const dependencies = getRuleDependencies(entry.ruleFile);
-                actual = await active.run({
+                const outcome = await active.run({
                     root, ruleFile: entry.ruleFile, files: example.files, ai,
                     ...(dependencies === undefined ? {} : { dependencies }),
                 }, deadline, failCase);
+                if (typeof outcome === 'string')
+                    actual = outcome;
+                else {
+                    actual = outcome.actual;
+                    aiScores = outcome.aiScores;
+                }
             }
         }
         catch (error) {
@@ -164,6 +171,7 @@ async function runCase(entry, example, ai, timeoutMs, session, onFailure) {
             expected: example.expected,
             actual,
             durationMs: performance.now() - started,
+            ...(aiScores === undefined ? {} : { aiScores }),
         };
     }
     catch (error) {
@@ -196,6 +204,8 @@ export async function runRuleTests(rules, onResult, timeoutMs = 10_000, concurre
         for (const rule of rules) {
             if (failureObserved)
                 throw failure;
+            if (!rule.rule.enabled)
+                continue;
             // Discovery selects the rule module path at runtime.
             const { tests, aiTests } = await import(pathToFileURL(rule.ruleFile).href);
             if (failureObserved)

package/dist/app/evaluators.js

@@ -23,8 +23,11 @@ function assertExampleList(value, label) {
     }
 }
 function assertAiOptions(options) {
-    if (typeof options.rule !== 'string' || options.rule === '') {
-        fail('ai rule must be a non-empty string');
+    if (options.rule !== undefined && options.instruction !== undefined)
+        fail('ai rule and instruction are mutually exclusive');
+    const policy = options.instruction ?? options.rule;
+    if (typeof policy !== 'string' || policy === '') {
+        fail(`ai ${options.instruction === undefined ? 'rule' : 'instruction'} must be a non-empty string`);
     }
     const examples = options.examples;
     if (examples !== undefined) {
@@ -77,9 +80,13 @@ function projectState(subject) {
 function instructionsOf(options) {
     const good = options.examples?.good ?? [];
     const bad = options.examples?.bad ?? [];
+    const instructions = {
+        rule: options.instruction === undefined ? options.rule : options.instruction,
+        question: QUESTION,
+    };
     if (good.length === 0 && bad.length === 0)
-        return { rule: options.rule, question: QUESTION };
-    return { rule: options.rule, question: QUESTION, examples: { good, bad } };
+        return instructions;
+    return { ...instructions, examples: { good, bad } };
 }
 export async function evaluateAi(subject, options, context, runtime, observer) {
     assertAiOptions(options);

package/dist/app/rule-tests.d.ts

@@ -9,6 +9,7 @@ export interface RuleTestResult {
     readonly name: string;
     readonly expected: RuleTestCase['expected'];
     readonly actual: RuleTestCase['expected'] | 'timeout';
+    readonly aiScores?: readonly number[];
     readonly durationMs: number;
 }
 export declare function test(name: string): {

package/dist/app/rule.d.ts

@@ -81,12 +81,18 @@ export interface AiExamples {
     readonly good?: readonly string[];
     readonly bad?: readonly string[];
 }
-export interface AiOptions<T = JsonValue> {
-    readonly rule: string;
+export type AiOptions<T = JsonValue> = {
     readonly examples?: AiExamples;
     readonly violationMessage?: string;
     readonly input?: (subject: Subject<T>, context: ProjectContext) => Awaitable<JsonValue>;
-}
+} & ({
+    /** @deprecated Use `instruction` instead. */
+    readonly rule: string;
+    readonly instruction?: never;
+} | {
+    readonly instruction: string;
+    readonly rule?: never;
+});
 export type Evaluator<T = JsonValue> = (subject: Subject<T>, context: CheckContext<T>) => Awaitable<CheckResult>;
 export interface ProjectContext {
     readonly project: Project;

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@alex-dbs/coderuler",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "Apache-2.0",
+  "keywords": [
+    "ai",
+    "ai-agent",
+    "agent",
+    "rule",
+    "rules",
+    "coding-standards",
+    "standard",
+    "code-quality",
+    "code-review",
+    "security",
+    "linter",
+    "checker",
+    "static-analysis",
+    "policy-as-code",
+    "typescript",
+    "developer-tools"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alex-dbs/coderuler.git"

package/skills/coderuler-new-rule/SKILL.md

@@ -29,7 +29,9 @@ Start the name with its language or technology prefix, such as `go-`, `ts-`, or
 
 Keep rules short, with only a few lines of policy code. Reuse built-in selectors, evaluators, and standard libraries before writing custom logic. Add helpers only for real reuse.
 
-Add a named `tests` export in the same file. Use `.passes()` and `.violates()` cases that exercise the policy. Omit `.skips()` assertions when creating a rule: skipped inputs never reach the check and provide no evidence of policy behavior.
+For a deterministic rule, add a named `tests` export with `.passes()` and `.violates()` cases. For an AI rule, put every test case in `aiTests` and do not add a separate `tests` export. Omit `.skips()` assertions when creating a rule: skipped inputs never reach the check and provide no evidence of policy behavior.
+
+For an AI rule, use `instruction` to state what compliant code does, beginning with a direct requirement. Add only applicability boundaries or real exceptions needed to define the policy; keep one policy per rule. Keep reporting language in `violationMessage`, examples in `examples`, and test cases in `aiTests`—not in the instruction. See [AI instruction style](reference.md#ai-instruction-style).
 
 Run the relevant cases before the policy change and require an assertion mismatch for the intended violation, not a loading error. Implement the policy, then require every case to pass.
 
@@ -97,10 +99,10 @@ Useful test options:
 ```sh
 coderuler test . --failures-only
 coderuler test . --concurrency 4 --timeout 30s
-coderuler test .coderuler/k8s-semantic-policy.rule.ts --ai --timeout 45s
+coderuler test .coderuler/semantic-policy.rule.ts --ai --ai-scores --timeout 45s
 ```
 
-Replace the semantic-policy filename with the actual AI rule. `--ai` authorizes live provider calls for `aiTests`, requires provider configuration, and may incur charges. Outcomes can vary; provider errors are errors, not passes.
+Replace the semantic-policy filename with the actual AI rule. `--ai` authorizes live provider calls for `aiTests`, requires provider configuration, and can incur charges. `--ai-scores` displays each Jev probability; use it with `--ai`. A test marked `PASS` means its expectation matched, not that its code is compliant. Expected violations need scores near `0`; compliant cases need scores near `1`. For wording changes, compare both groups on the same fixtures and configuration. Follow [the comparison procedure](reference.md#ai-instruction-style) rather than changing fixtures or thresholds to make a candidate pass.
 
 ## 4. Inspect the rule on the project
 

package/skills/coderuler-new-rule/reference.md

@@ -1,4 +1,4 @@
-# Rule API reference
+ # Rule API reference
 
 Read the branch needed for the rule; use [SKILL.md](SKILL.md) for the authoring, test, and inspection workflow. All imports below use the public `@alex-dbs/coderuler` SDK.
 
@@ -318,7 +318,7 @@ Results validate; supplied messages survive reporting. Violations without a mess
 | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
 | `ProjectContext`                                       | `readonly project: Project`; `trace(message: string, details?: JsonValue): void`. |
 | `SelectionContext extends ProjectContext`              | `select<T>(selection: Selection<T>): Promise<readonly ScopeSubject<T>[]>`.        |
-| `CheckContext<T = JsonValue> extends SelectionContext` | `readonly ruleName: string`; `ai(options: AiOptions<T>): Promise<CheckResult>`.   |
+| `CheckContext<T = JsonValue> extends SelectionContext` | `readonly ruleName: string`; `ai(options: AiOptions<T>): Promise<CheckResult>`. |
 
 
 Use `trace` for decision evidence visible during inspection; keep normal execution free of ad-hoc console output. AI/regex projection callbacks receive only `ProjectContext`, not the full check context.
@@ -344,85 +344,139 @@ Default input is `String(data)` for scalar/null data, otherwise source text. `in
 
 ## AI options, examples, and settings
 
-`ai<T = JsonValue>(options: AiOptions<T>): Evaluator<T>` accepts:
+`ai<T = JsonValue>(options: AiOptions<T>): Evaluator<T>` accepts exactly one of `rule` or `instruction`:
 
-- `rule: string`: nonempty semantic policy; include exceptions and what visible evidence permits a violation.
+- `rule: string`: nonempty policy text. This option is deprecated; use `instruction` for new rules.
+- `instruction: string`: nonempty text describing the expected behavior of the selected code. Write a direct requirement that Jev can judge as respected or broken.
 - `examples?: { readonly good?: readonly string[]; readonly bad?: readonly string[] }`: conditioning examples, dense arrays of nonempty strings; omitted/empty lists are valid.
 - `violationMessage?: string`: nonempty reporting-only message, not sent as instructions.
 - `input?: (subject: Subject<T>, context: ProjectContext) => Awaitable<JsonValue>`: replace the default projection; output validates as JSON-compatible.
 
-```ts
-import { Rule, ai, test } from '@alex-dbs/coderuler';
-import type { RuleSettings } from '@alex-dbs/coderuler';
+Jev uses the fixed question "Is the rule respected?" Yes/true means no problems. No/false means at least one violation. The configured threshold decides pass or violation.
 
-export default class ActionableInstructions extends Rule {
-  files = ['guides/**/*.md'];
-  settings: RuleSettings = { model: 'jev-latest', threshold: 0.5 };
-  check = ai({
-    rule: 'Instructions name a concrete action and its observable completion condition.',
-    examples: { good: ['Run the migration until it exits successfully.'], bad: ['Handle the migration.'] },
-    violationMessage: 'Name the action and how to recognize completion',
-  });
-}
-export const aiTests = [
-  test('an independent concrete instruction passes').withFiles({
-    'guides/cache.md': 'Delete the cache directory; finish when it no longer exists.',
-  }).passes(),
-];
-```
+### AI instruction style
 
-`examples` condition the model; `aiTests` assert outcomes on independent datasets. Ordinary `tests` are offline; live `aiTests` require explicit AI opt-in as described in [SKILL.md](SKILL.md). Keep deterministic applicability out of the prompt.
+Write the instruction as a requirement for the code, not directions for the reviewer. A direct requirement names the behavior compliant code must have. Add a boundary only when it says where the policy applies; include exceptions only when they are genuinely allowed. Keep each rule to one policy.
 
-Default AI input is `{ filepath, scope: { id, data, captures? } }` when data exists, or `{ filepath, scope: { id, source, captures? } }` otherwise. Data presence includes `null`, `false`, `0`, and `''`. Groups become `{ files: [{ filepath, scopes: [...] }] }`. Good: select enough context to judge meaning, or project a deliberate JSON input. Bad: expect source text alongside structured data without providing it via `input`.
+Weak: "Report a violation when a Go pointer is dereferenced without a nil check."
 
-Inside a custom check, `return context.ai({ rule: '...' })` evaluates its current subject with effective settings and preserves AI result metadata. Replacing that result requires intentionally preserving probability/model/threshold metadata; token accounting is automatic across all `context.ai` calls, even when returning a different result. `ai(...)` validates options when constructed but performs no loading-time network I/O.
+Better: "Check each Go pointer for nil before dereferencing it." For nested fields, add the needed boundary: "Check every pointer in the field path before dereferencing the field."
 
-`RuleSettings` supports backend `'jev'`, model (default `'jev-latest'`), finite threshold in `[0, 1]` (default `0.4`), and finite nonnegative `inputCostPerMillion` / `outputCostPerMillion` prices (USD per million tokens; defaults `0.042` / `0`). Threshold precedence is CLI override → rule setting → `RK_THRESHOLD` → default; backend/model use rule setting → environment (`RK_BACKEND` / `TYPESAFE_DEFAULT_MODEL`) → default. AI passes only when probability is **strictly greater** than threshold; equality violates. Results include the effective threshold. Provider environment/key resolution is lazy at the first AI call; deterministic/skipped/filtered paths need no key. Live calls require `TYPESAFE_API_KEY`; use release configuration guidance for transport setup.
+Keep reporting language in `violationMessage`, conditioning examples in `examples`, and test fixtures in `aiTests`; they do not belong in the instruction. Use selectors and filters for deterministic applicability, and include enough input for the semantic decision.
 
-Inspection reports per-verification `usage: AiUsage` and a final recap: `calls`, `unreportedCalls`, `inputTokens`, `outputTokens`, `inputCost`, and `outputCost` (USD). Counts come from provider responses; missing counts remain unreported and totals cover reported calls only. Configure prices through rule settings or `RK_INPUT_COST_PER_MILLION` / `RK_OUTPUT_COST_PER_MILLION`; inspect flags `--input-cost-per-million` / `--output-cost-per-million` override both. Prices change estimates, not decisions.
+Compare wording with the policy and dataset held fixed:
 
-AI rules, under the hood, are using TypeSafe Jev model and `noul` question (yes/no probabilistc answer). The rule must clearly explain what is checked. A global/generic rule won't match. A dedicated rule will perform better. The example bellow will check a particular usage of go slice `append` function.
+1. Save the current instruction and its scores as the baseline.
+2. Change only the instruction. Keep the model version, examples, input, fixtures, and threshold unchanged.
+3. Run every affected `aiTests` case with `--ai --ai-scores`. Include compliant cases and violations, especially policy boundaries.
+4. Compare compliant scores toward `1` and violation scores toward `0` separately. Inspect individual regressions and the weakest score in each group, not just averages.
+5. Keep wording that improves separation without changing the policy or introducing wrong decisions. Repeat a close comparison before treating a small gain as reliable.
 
-```
-import { Rule, ai, scopes, test } from '@alex-dbs/coderuler';
+`PASS` in test output means the expected result matched. A passing violation test still needs a low Jev score. Do not lower the threshold, relabel fixtures, or copy test cases into the instruction to improve the comparison. Results on a tuning dataset do not prove performance on unseen code.
+
+
+This rule checks Go pointer dereferences, including nested fields:
+
+```ts
+import { Rule, ai, scopes, test, type ScopeSubject } from '@alex-dbs/coderuler';
 
-export default class GoAppendSlice extends Rule {
+export default class GoDereferenceGuard extends Rule {
   files = ['**/*.go'];
+  settings = { threshold: 0.7 };
 
   scope = scopes.astGrep({
     language: 'go',
     rule: {
       any: [{ kind: 'function_declaration' }, { kind: 'method_declaration' }],
       has: {
-        kind: 'for_statement',
+        kind: 'unary_expression',
         stopBy: 'end',
         has: {
-          pattern: 'append($SLICE,$$$ARGS)',
-          stopBy: 'end',
+          field: 'operator',
+          regex: '^\\*$',
         },
       },
     },
   });
 
   check = ai({
-    rule: `A slice freshly allocated for a loop whose final element count is exactly known must be allocated at that final length and filled by index or with copy;
-growing it with append is a violation even when capacity was preallocated with make([]T, 0, n)
-and even when it was first created with make([]T, n) and then reset to length zero.
-
-Append in a loop is valid only when the final count is not known before the loop,
-such as elements appended under a condition so the count varies within an upper bound that capacity merely reserves,
-or when the slice already holds a deliberately assigned prefix written before the loop.
-
-Appending after a length that was allocated but never assigned,
-or assigning elements by index and also appending them, is a violation.`,
+    instruction: `Check each Go pointer for nil before dereferencing it. For nested fields, check every pointer in the field path.`,
     examples: {
-      good: [/* Some examples, not shown here to keep it short*/],
-      bad: [/* Some examples, not shown here to keep it short*/],
+      good: [
+        `func configName(config *Config) string {
+    if config != nil {
+        return (*config).Name
+    }
+    return ""
+}`,
+        `func (config *Config) name() string {
+    if config == nil {
+        return ""
+    }
+    return (*config).Name
+}`
+      ],
+      bad: [
+        `func configName(config *Config) string {
+    return (*config).Name
+}`,
+        `func configName(config *Config) string {
+    if config == nil {
+        logMissingConfig()
+    }
+    return (*config).Name
+}`
+      ],
+    },
+    input: async (subject, { project }) => {
+      const scope = subject as ScopeSubject;
+      return {
+        function: scope.source,
+        file: await project.readText(scope.filepath),
+      };
     },
+    violationMessage: 'Check each pointer for nil before using *.',
   });
 }
+
+export const aiTests = [
+  test('an early return guards a pointer parameter').withFiles({
+    'quota.go': `package example
+
+func remainingQuota(quota *int, used int) int {
+    if quota == nil {
+        return 0
+    }
+    return *quota - used
+}`,
+  }).passes(),
+  test('a root nil check does not guard a nested pointer field').withFiles({
+    'config.go': `package example
+
+type Config struct { Child *Child }
+type Child struct { Value *int }
+
+func nestedValue(config *Config) int {
+    if config == nil {
+        return 0
+    }
+    return *config.Child.Value
+}`,
+  }).violates(),
+] as const;
 ```
 
+`examples` condition the model; `aiTests` assert outcomes on independent datasets. Put every test case for an AI rule in `aiTests`, without a separate `tests` export. Ordinary `tests` are offline; live `aiTests` require `--ai`. Use `instruction` and follow [AI instruction style](#ai-instruction-style). Add `--ai-scores` to inspect probabilities, not just test outcomes.
+
+Default AI input is `{ filepath, scope: { id, data, captures? } }` when data exists, or `{ filepath, scope: { id, source, captures? } }` otherwise. Data presence includes `null`, `false`, `0`, and `''`. Groups become `{ files: [{ filepath, scopes: [...] }] }`. Good: select enough context to judge meaning, or project a deliberate JSON input. Bad: expect source text alongside structured data without providing it via `input`.
+
+Inside a custom check, `return context.ai({ instruction: '...' })` evaluates its current subject with effective settings and preserves AI result metadata. The deprecated `rule` option remains accepted for existing rules. Replacing that result requires intentionally preserving probability/model/threshold metadata; token accounting is automatic across all `context.ai` calls, even when returning a different result. `ai(...)` validates options when constructed but performs no loading-time network I/O.
+
+`RuleSettings` supports backend `'jev'`, model (default `'jev-latest'`), finite threshold in `[0, 1]` (default `0.4`), and finite nonnegative `inputCostPerMillion` / `outputCostPerMillion` prices (USD per million tokens; defaults `0.042` / `0`). Threshold precedence is CLI override → rule setting → `RK_THRESHOLD` → default; backend/model use rule setting → environment (`RK_BACKEND` / `TYPESAFE_DEFAULT_MODEL`) → default. AI passes only when probability is **strictly greater** than threshold; equality violates. Results include the effective threshold. Provider environment/key resolution is lazy at the first AI call; deterministic/skipped/filtered paths need no key. Live calls require `TYPESAFE_API_KEY`; use release configuration guidance for transport setup.
+
+Inspection reports per-verification `usage: AiUsage` and a final recap: `calls`, `unreportedCalls`, `inputTokens`, `outputTokens`, `inputCost`, and `outputCost` (USD). Counts come from provider responses; missing counts remain unreported and totals cover reported calls only. Configure prices through rule settings or `RK_INPUT_COST_PER_MILLION` / `RK_OUTPUT_COST_PER_MILLION`; inspect flags `--input-cost-per-million` / `--output-cost-per-million` override both. Prices change estimates, not decisions.
+
+
 ## Project readers
 
 Public signatures (import `Project`, `CsvOptions`, `CsvRow`, and `JsonValue` as types from `@alex-dbs/coderuler`):