pi-jev-guard 0.3.1 → 0.3.2

package/README.md

@@ -159,6 +159,19 @@ avvisa e dice di riferirsi al valore per nome; se è un errore, allega il
 consiglio per la classe (`transient` → riprova, `code_bug` → fixa il codice…).
 Non blocca mai; `/jev output` mostra l'ultimo verdetto.
 
+Sempre in `automatic`, il **grounding** (opt-in, default spento) confronta le
+affermazioni sulla sessione — "ho letto il file", "i test passano", "ho
+eseguito X" — con un registro evidenza costruito dai `tool_result`
+(comandi, test, letture, modifiche; redatto, max 30 voci, solo sessione
+corrente). Due domande Jev strette: contraddizione con l'evidenza e
+affermazione non supportata. Senza evidenza non si giudica: "senza
+evidenza" non significa "falso". Una modifica riuscita invalida i test
+precedenti (stale). Tre modalità (`/jev grounding off|warn|repair|hold`):
+`warn` pubblica con nota, `repair` rigenera una volta, `hold` trattiene solo
+le contraddizioni ad alta confidenza. Fail-open: se il verificatore non
+risponde, il testo passa senza nota. `/jev last` mostra anche l'esito
+grounding (`warned`/`repaired`/`held`).
+
 ## Configurazione
 
 `~/.pi/agent/jev-config.json` (o `$JEV_CONFIG`). Env: `JEV_MODE`, `JEV_BACKEND`
@@ -210,3 +223,6 @@ echo '{"requirements":"...","candidate":"..."}' | npm run jev-check
 - Soglie calibrate su 20 casi (`docs/calibration-2026-09-19.md`): buone per
   iniziare, da rivalutare con corpus più ampio.
 - Jev è un giudice probabilistico, non un verificatore formale.
+- Il grounding controlla solo affermazioni verificabili sulla sessione
+  (comandi, file, test, modifiche): niente fact-check di fatti esterni,
+  e con contesti lunghi l'evidenza oltre budget viene elisa.

package/config/jev-config.example.json

@@ -80,5 +80,17 @@
     "minConfidence": 0.5,
     "cacheSeconds": 120,
     "blockWithoutUI": false
+  },
+  "grounding": {
+    "enabled": false,
+    "mode": "warn",
+    "contradictionThreshold": 0.85,
+    "unsupportedThreshold": 0.7,
+    "maxRepairs": 1,
+    "maxEntries": 30,
+    "evidenceChars": 2000,
+    "excerptChars": 300,
+    "cacheSeconds": 120,
+    "invalidateTestsOnEdit": true
   }
 }

package/extensions/index.ts

@@ -51,6 +51,20 @@ import {
   lastUserText,
   type ExfilVerdict,
 } from "../src/exfil.ts";
+import {
+  buildEvidenceDigest,
+  buildGroundingHoldText,
+  buildGroundingState,
+  decideGroundingAction,
+  evaluateGrounding,
+  groundingKey,
+  recordEvidence,
+  recordToolResult,
+  GROUNDING_QUESTIONS,
+  type EvidenceEntry,
+  type GroundingEvaluation,
+} from "../src/grounding.ts";
+import type { PostPublishCheckFn } from "../src/automatic/guardian.ts";
 
 export interface GateStatus {
   active: boolean;
@@ -83,6 +97,11 @@ export default function (pi: ExtensionAPI) {
   let typedHandle = createTypedAsk(configSnapshot(config));
   let outputCache = createVerdictCache<OutputVerdict>({ ttlSeconds: config.outputJudge.cacheSeconds });
   let exfilCache = createVerdictCache<ExfilVerdict>({ ttlSeconds: config.exfilCheck.cacheSeconds });
+  let groundingCache = createVerdictCache<GroundingEvaluation>({ ttlSeconds: config.grounding.cacheSeconds });
+  // Ledger evidenza per sessione: effetti osservati (tool_result), redatti.
+  // Resettato a ogni session_start; solo automatic lo alimenta e lo usa.
+  let evidenceLedger: EvidenceEntry[] = [];
+  let evidenceSeq = 0;
   let lastOutput: { tool: string; verdict: OutputVerdict; at: number } | undefined;
   let lastGate: { report: GateVerdictReport; at: number } | undefined;
 
@@ -91,6 +110,7 @@ export default function (pi: ExtensionAPI) {
   }
   let lastOutputErrorAt = 0;
   let lastExfilErrorAt = 0;
+  let lastGroundingErrorAt = 0;
   const metrics = createMetrics();
 
   // Twin attivi, uno o più per provider. Nessun overlay finché la config non
@@ -170,6 +190,7 @@ export default function (pi: ExtensionAPI) {
     typedHandle = createTypedAsk(configSnapshot(config));
     outputCache = createVerdictCache<OutputVerdict>({ ttlSeconds: config.outputJudge.cacheSeconds });
     exfilCache = createVerdictCache<ExfilVerdict>({ ttlSeconds: config.exfilCheck.cacheSeconds });
+    groundingCache = createVerdictCache<GroundingEvaluation>({ ttlSeconds: config.grounding.cacheSeconds });
     return getConfig();
   }
 
@@ -211,6 +232,7 @@ export default function (pi: ExtensionAPI) {
       getConfig,
       getReview: getGateReview,
       onVerdict: recordGateVerdict,
+      createPostCheck: createGroundingCheck,
     });
     pi.registerProvider(overlay);
     overlays.set(providerId, {
@@ -440,6 +462,23 @@ export default function (pi: ExtensionAPI) {
     removeTwin,
     switchToGuarded,
     getLastOutput: () => lastOutput,
+    groundingStatus: () => ({
+      enabled: config.grounding.enabled,
+      mode: config.grounding.mode,
+      entries: evidenceLedger.length,
+      hasStaleTests: evidenceLedger.some((e) => e.kind === "test" && e.stale),
+    }),
+    setGrounding: (mode) => {
+      const next = configSnapshot(config);
+      if (mode === "off") {
+        next.grounding.enabled = false;
+      } else {
+        next.grounding.enabled = true;
+        next.grounding.mode = mode;
+      }
+      saveConfig(next);
+      return refresh();
+    },
     getLastGate: () => lastGate,
   });
 
@@ -494,6 +533,9 @@ export default function (pi: ExtensionAPI) {
 
   async function startSession(ctx: ExtensionContext): Promise<void> {
     restoreMode(ctx);
+    // Nuova sessione = nuova evidenza: il ledger non attraversa le sessioni.
+    evidenceLedger = [];
+    evidenceSeq = 0;
     const auto = process.env.JEV_AUTO_UPSTREAM?.trim();
     if (auto && auto !== "0" && auto.toLowerCase() !== "off") {
       try {
@@ -797,11 +839,161 @@ export default function (pi: ExtensionAPI) {
     return allow ? undefined : { block: true, reason: `Bloccato da jev exfil check (${summary}) (declined).` };
   }
 
+  /** Registra un tool_result nel ledger evidenza (solo automatic, mai bloccare). */
+  function recordGroundingResult(event: {
+    toolName: string;
+    input: unknown;
+    content: unknown;
+    isError: boolean;
+  }): void {
+    try {
+      if (sessionMode !== "automatic") return;
+      if (!config.grounding.enabled) return;
+      const entry = recordToolResult({
+        toolName: event.toolName,
+        input: event.input,
+        content: event.content,
+        isError: event.isError,
+        seq: ++evidenceSeq,
+        at: Date.now(),
+        excerptChars: config.grounding.excerptChars,
+      });
+      if (!entry) return;
+      recordEvidence(evidenceLedger, entry, {
+        maxEntries: config.grounding.maxEntries,
+        invalidateTestsOnEdit: config.grounding.invalidateTestsOnEdit,
+      });
+    } catch {
+      // Mai rompere i risultati tool per il ledger.
+    }
+  }
+
+  function throttledGroundingError(error: unknown): void {
+    const now = Date.now();
+    if (now - lastGroundingErrorAt < 60_000) return;
+    lastGroundingErrorAt = now;
+    try {
+      pi.appendEntry("jev-grounding-error", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } catch {
+      // solo diagnostica
+    }
+  }
+
+  /**
+   * Factory per-richiesta del controllo grounding: il budget repair vive
+   * nella closure (una per runGuardedStream). Ritorna undefined quando il
+   * controllo non si applica: il gate pubblica senza nota (fail-open).
+   */
+  function createGroundingCheck(): PostPublishCheckFn | undefined {
+    try {
+      if (sessionMode !== "automatic") return undefined;
+      if (!config.grounding.enabled) return undefined;
+      if (!resolveBackend(config).apiKeyPresent) return undefined;
+      const g = config.grounding;
+      const mode = g.mode;
+      const maxRepairs = g.maxRepairs;
+      let repairsUsed = 0;
+      return async ({ text, attempts }) => {
+        const digest = buildEvidenceDigest(evidenceLedger, {
+          maxEntries: g.maxEntries,
+          evidenceChars: g.evidenceChars,
+        });
+        // Senza evidenza non si giudica: "senza evidenza" ≠ "falso".
+        if (digest.entries.length === 0) return { action: "publish" };
+        const state = buildGroundingState(text, digest, {
+          maxCandidateChars: config.limits.maxCandidateChars,
+        });
+        let evaluation: GroundingEvaluation | undefined;
+        try {
+          evaluation = await groundingCache.getOr(
+            groundingKey(text, state),
+            async () => {
+              const asked = await typedHandle.ask(state, GROUNDING_QUESTIONS, undefined);
+              return evaluateGrounding(asked, {
+                contradictionThreshold: g.contradictionThreshold,
+                unsupportedThreshold: g.unsupportedThreshold,
+              });
+            },
+          );
+        } catch (error) {
+          throttledGroundingError(error);
+          return { action: "publish" };
+        }
+        if (!evaluation) return { action: "publish" };
+        const decision = decideGroundingAction({
+          evaluation,
+          mode,
+          repairsUsed,
+          maxRepairs,
+        });
+        if (decision.action === "regenerate") {
+          repairsUsed++;
+          try {
+            pi.appendEntry("jev-grounding-repair", { reasons: evaluation.reasons });
+          } catch {
+            // solo diagnostica
+          }
+          return {
+            action: "regenerate",
+            feedback: decision.feedback,
+            grounding: { action: "repaired", reasons: evaluation.reasons },
+          };
+        }
+        if (decision.action === "hold") {
+          try {
+            pi.appendEntry("jev-grounding-hold", {
+              reasons: evaluation.reasons,
+              mode,
+            });
+          } catch {
+            // solo diagnostica
+          }
+          return {
+            action: "hold",
+            holdText: buildGroundingHoldText({ reasons: evaluation.reasons, attempts }),
+            grounding: { action: "held", reasons: evaluation.reasons },
+          };
+        }
+        if (decision.notice) {
+          try {
+            pi.appendEntry("jev-grounding-warn", {
+              reasons: evaluation.reasons,
+              mode,
+            });
+          } catch {
+            // solo diagnostica
+          }
+          return {
+            action: "publish",
+            notice: decision.notice,
+            grounding:
+              repairsUsed > 0
+                ? { action: "repaired", reasons: evaluation.reasons }
+                : { action: "warned", reasons: evaluation.reasons },
+          };
+        }
+        return {
+          action: "publish",
+          grounding:
+            repairsUsed > 0
+              ? { action: "repaired", reasons: evaluation.reasons }
+              : undefined,
+        };
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
   // Giudice output (solo automatic, fail-open): dopo l'esecuzione cerca
   // secret nel testo e classifica i fallimenti. Non blocca mai: allega
   // una riga al risultato che il modello legge.
   pi.on("tool_result", async (event, ctx) => {
     try {
+      // Ledger prima di tutto: vale anche con outputJudge disattivato.
+      recordGroundingResult(event);
       if (sessionMode !== "automatic") return;
       if (!config.outputJudge.enabled) return;
       if (!config.outputJudge.tools.includes(event.toolName)) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jev-guard",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "Jev validation guard for pi: on-demand tool + automatic provider gate. Dual backend: TypeSafe direct + OpenRouter.",
   "keywords": [

package/src/automatic/guardian.ts

@@ -9,6 +9,7 @@ import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
 import type { JevConfig } from "../config.ts";
 import type { ReviewFn, ReviewResult } from "../reviewer.ts";
 import { reviewWithCoverage } from "../reviewer.ts";
+import { buildGroundingRepairContext } from "../grounding.ts";
 import {
   aggregateUsage,
   buildRepairContext,
@@ -34,6 +35,33 @@ export interface GuardianDeps {
   publishedModel: string;
   /** Chiamato una volta per esito finale con verdetto Jev (pass e hold). */
   onVerdict?: (report: GateVerdictReport) => void;
+  /**
+   * Controllo post-safety sul candidato approvato (es. grounding evidenza).
+   * Opzionale; se assente o se solleva, il candidato viene pubblicato
+   * (fail-open: il safety ha già deciso). Rigenerazioni bounded dal loop.
+   */
+  postPublishCheck?: PostPublishCheckFn;
+}
+
+/** Controllo post-safety: una chiamata per ogni candidato approvato. */
+export type PostPublishCheckFn = (args: {
+  message: AssistantMessage;
+  text: string;
+  /** Tentativo upstream corrente (1-based). */
+  attempts: number;
+}) => Promise<PostPublishCheckResult>;
+
+/** Esito di un controllo post-safety sul candidato approvato. */
+export interface PostPublishCheckResult {
+  action: "publish" | "regenerate" | "hold";
+  /** Nota di trasparenza accodata (publish). */
+  notice?: string;
+  /** Feedback per la rigenerazione (regenerate). */
+  feedback?: string;
+  /** Testo sicuro da pubblicare (hold): mai il candidato. */
+  holdText?: string;
+  /** Dettaglio per il report (publish con nota, hold). */
+  grounding?: GateVerdictReport["grounding"];
 }
 
 /** Esito finale del gate con verdetto, per `/jev last` e diagnostica. */
@@ -43,6 +71,11 @@ export interface GateVerdictReport {
   attempts: number;
   /** Come si è chiuso: pubblicato dopo ok, o trattenuto. */
   outcome: "published" | "held";
+  /** Dettaglio grounding quando un post-check è intervenuto. */
+  grounding?: {
+    action: "warned" | "repaired" | "held";
+    reasons: string[];
+  };
 }
 
 export class GuardianLimitError extends Error {
@@ -248,8 +281,16 @@ export function runGuardedStream(
         }
         signal?.throwIfAborted();
 
-        const publishCandidate = async (notice?: string): Promise<void> => {
-          deps.onVerdict?.({ verdict, attempts: attempt + 1, outcome: "published" });
+        const publishCandidate = async (
+          notice?: string,
+          grounding?: GateVerdictReport["grounding"],
+        ): Promise<void> => {
+          deps.onVerdict?.({
+            verdict,
+            attempts: attempt + 1,
+            outcome: "published",
+            ...(grounding ? { grounding } : {}),
+          });
           const approved = notice ? withNotice(candidate, notice) : candidate;
           const aggregated = aggregateUsage(usages);
           const replayed = replayApproved(approved, {
@@ -266,9 +307,84 @@ export function runGuardedStream(
           out.end(final);
         };
 
+        /** Pubblica un testo sicuro (hold): mai il candidato bocciato. */
+        const publishHoldText = async (safeText: string): Promise<void> => {
+          const aggregated = aggregateUsage(usages);
+          const safeMessage: AssistantMessage = {
+            role: "assistant",
+            content: [{ type: "text", text: "" }],
+            api: candidate.api,
+            provider: deps.publishedProvider as AssistantMessage["provider"],
+            model: deps.publishedModel,
+            responseModel: candidate.model,
+            usage: aggregated,
+            stopReason: "stop",
+            timestamp: Date.now(),
+          };
+          out.push({ type: "start", partial: safeMessage });
+          out.push({ type: "text_start", contentIndex: 0, partial: safeMessage });
+          const block = safeMessage.content[0];
+          if (block && block.type === "text") block.text = safeText;
+          out.push({ type: "text_delta", contentIndex: 0, delta: safeText, partial: safeMessage });
+          out.push({ type: "text_end", contentIndex: 0, content: safeText, partial: safeMessage });
+          out.push({ type: "done", reason: "stop", message: safeMessage });
+          out.end(safeMessage);
+        };
+
+        /**
+         * Controllo post-safety sul candidato approvato. Ritorna "published"
+         * o "held" (stream già chiuso) oppure undefined per rigenerare
+         * (attemptContext aggiornato, il loop continua). Fail-open.
+         */
+        const runPostCheck = async (
+          baseNotice?: string,
+        ): Promise<"published" | "held" | undefined> => {
+          if (!deps.postPublishCheck) {
+            await publishCandidate(baseNotice);
+            return "published";
+          }
+          let check: PostPublishCheckResult;
+          try {
+            check = await deps.postPublishCheck({
+              message: candidate,
+              text: rawCandidate,
+              attempts: attempt + 1,
+            });
+          } catch {
+            await publishCandidate(baseNotice);
+            return "published";
+          }
+          signal?.throwIfAborted();
+          if (check.action === "publish") {
+            const notice = [baseNotice, check.notice].filter(Boolean).join("") || undefined;
+            await publishCandidate(notice, check.grounding);
+            return "published";
+          }
+          if (check.action === "hold") {
+            const attempts = attempt + 1;
+            deps.onVerdict?.({
+              verdict,
+              attempts,
+              outcome: "held",
+              ...(check.grounding ? { grounding: check.grounding } : {}),
+            });
+            await publishHoldText(check.holdText ?? "[JEV — OUTPUT NON PUBBLICATO]");
+            return "held";
+          }
+          attemptContext = buildGroundingRepairContext({
+            attemptContext,
+            rejectedText: rawCandidate,
+            feedback:
+              check.feedback ??
+              "Grounding check failed; only assert session activities supported by evidence.",
+          });
+          return undefined;
+        };
+
         if (verdict.status === "pass") {
-          await publishCandidate();
-          return;
+          const outcome = await runPostCheck();
+          if (outcome !== undefined) return;
+          continue;
         }
 
         const canRepair =
@@ -291,8 +407,9 @@ export function runGuardedStream(
         const unavailablePass =
           verdict.status === "unavailable" && deps.config.policy.onUnavailable === "pass";
         if (uncertainPass || unavailablePass) {
-          await publishCandidate(uncertainNotice(verdict));
-          return;
+          const outcome = await runPostCheck(uncertainNotice(verdict));
+          if (outcome !== undefined) return;
+          continue;
         }
 
         // Hold: pubblica failure sicura, mai il candidato bocciato.
@@ -305,26 +422,7 @@ export function runGuardedStream(
             ? "Input troncato per la verifica: Jev ha visto solo una parte (vedi truncated)."
             : undefined,
         });
-        const aggregated = aggregateUsage(usages);
-        const safeMessage: AssistantMessage = {
-          role: "assistant",
-          content: [{ type: "text", text: "" }],
-          api: candidate.api,
-          provider: deps.publishedProvider as AssistantMessage["provider"],
-          model: deps.publishedModel,
-          responseModel: candidate.model,
-          usage: aggregated,
-          stopReason: "stop",
-          timestamp: Date.now(),
-        };
-        out.push({ type: "start", partial: safeMessage });
-        out.push({ type: "text_start", contentIndex: 0, partial: safeMessage });
-        const block = safeMessage.content[0];
-        if (block && block.type === "text") block.text = safeText;
-        out.push({ type: "text_delta", contentIndex: 0, delta: safeText, partial: safeMessage });
-        out.push({ type: "text_end", contentIndex: 0, content: safeText, partial: safeMessage });
-        out.push({ type: "done", reason: "stop", message: safeMessage });
-        out.end(safeMessage);
+        await publishHoldText(safeText);
         return;
       }
     } catch (error) {

package/src/automatic/overlay.ts

@@ -10,6 +10,7 @@
  * per i soli modelli scelti. Gli stream dei gemelli passano dal gate.
  */
 import type {
+  AssistantMessage,
   AssistantMessageEventStream,
   Context,
   Credential,
@@ -25,7 +26,7 @@ import { emptyUsage } from "./serialize.ts";
 import type { JevConfig } from "../config.ts";
 import { configSnapshot } from "../config.ts";
 import type { ReviewFn } from "../reviewer.ts";
-import { runGuardedStream, type GateVerdictReport } from "./guardian.ts";
+import { runGuardedStream, type GateVerdictReport, type PostPublishCheckFn } from "./guardian.ts";
 
 export const TWIN_SUFFIX = "__jev";
 
@@ -80,6 +81,11 @@ export interface OverlayDeps {
   getReview: () => ReviewFn;
   /** Riceve l'esito finale di ogni turno sul twin (per `/jev last`). */
   onVerdict?: (report: GateVerdictReport) => void;
+  /**
+   * Factory del controllo post-safety, una per richiesta: il budget repair
+   * vive nella closure restituita, non nel loop del guardian.
+   */
+  createPostCheck?: () => PostPublishCheckFn | undefined;
   /** Override streams upstream per test (altrimenti delega al provider). */
   upstreamStreams?: {
     streamSimple: (
@@ -206,6 +212,12 @@ export function buildOverlaidProvider(deps: OverlayDeps): Provider {
       publishedProvider: model.provider,
       publishedModel: model.id,
       ...(deps.onVerdict ? { onVerdict: deps.onVerdict } : {}),
+      ...(deps.createPostCheck
+        ? (() => {
+            const check = deps.createPostCheck();
+            return check ? { postPublishCheck: check } : {};
+          })()
+        : {}),
     });
   }
 

package/src/commands.ts

@@ -72,6 +72,13 @@ export interface JevCommandDeps {
   }>;
   getLastOutput: () => { tool: string; verdict: OutputVerdict; at: number } | undefined;
   getLastGate: () => { report: GateVerdictReport; at: number } | undefined;
+  groundingStatus: () => {
+    enabled: boolean;
+    mode: "warn" | "repair" | "hold";
+    entries: number;
+    hasStaleTests: boolean;
+  };
+  setGrounding: (mode: "off" | "warn" | "repair" | "hold") => JevConfig;
 }
 
 export const JEV_SUBCOMMANDS = [
@@ -88,6 +95,7 @@ export const JEV_SUBCOMMANDS = [
   "reload",
   "output",
   "last",
+  "grounding",
   "backend",
   "save-key",
   "help",
@@ -111,6 +119,8 @@ export const JEV_HELP_TEXT = [
   "  /jev stats               Conteggi pass/block/review/unavailable + latenze",
   "  /jev output              Ultimo output giudicato: leak + classe errore",
   "  /jev last                Ultimo verdetto del gate (twin): esito e controlli",
+  "  /jev grounding off|warn|repair|hold",
+  "                           Grounding affermazioni sessione (solo automatic, opt-in)",
   "  /jev backend             Mostra backend attivo e chiavi rilevate",
   "  /jev backend auto|openrouter|typesafe",
   "                           Cambia backend (salvato in jev-config.json)",
@@ -239,6 +249,7 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
             `Tool policy: ${cfg.toolsPolicy.enabled ? "attiva in automatic (bash/powershell/write/edit)" : "disattiva (config)"}`,
             `Exfil check: ${cfg.exfilCheck.enabled ? "attivo in automatic (confirm in TUI, fail-open)" : "disattivo (config)"}`,
             `Output judge: ${cfg.outputJudge.enabled ? `attivo in automatic (tool: ${cfg.outputJudge.tools.join(",") || "—"}, fail-open)` : "disattivo (config)"}`,
+            `Grounding: ${cfg.grounding.enabled ? `attivo in automatic (mode=${cfg.grounding.mode}, evidenza=${deps.groundingStatus().entries}${deps.groundingStatus().hasStaleTests ? ", test stale" : ""})` : "disattivo (opt-in: /jev grounding warn)"}`,
             cfg.mode === "automatic"
               ? "ATTENZIONE: in automatic testo/codice vengono inviati al verificatore. Crea il twin con /jev upstream e seleziona il modello __jev per enforcement."
               : "on-demand: nessuna verifica automatica.",
@@ -451,6 +462,9 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
           [
             `Gate: ${last.report.outcome === "published" ? "pubblicato" : "trattenuto"} dopo ${last.report.attempts} tentativ${last.report.attempts === 1 ? "o" : "i"}`,
             `stato: ${v.status}${top ? ` — ${top.ruleId} p=${top.pFlaw.toFixed(2)}` : ""}`,
+            last.report.grounding
+              ? `grounding: ${last.report.grounding.action} (${last.report.grounding.reasons.join(", ") || "n/a"})`
+              : "grounding: non intervenuto",
             v.errorCode ? `errore: ${v.errorCode}` : `backend: ${v.backend ?? "?"} · modello: ${v.model ?? "?"}`,
             v.truncated ? `troncato: ${JSON.stringify(v.truncated)}` : "copertura intera",
             `tempo verifica: ${Math.round(v.elapsedMs)}ms`,
@@ -480,6 +494,33 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
         return;
       }
 
+      if (sub === "grounding") {
+        const value = parts[1];
+        if (value === undefined) {
+          const st = deps.groundingStatus();
+          ctx.ui.notify(
+            st.enabled
+              ? `Grounding attivo in automatic (mode=${st.mode}, voci evidenza=${st.entries}${st.hasStaleTests ? ", test stale presenti" : ""}). Cambia con /jev grounding off|warn|repair|hold.`
+              : "Grounding disattivo (opt-in). Attiva con /jev grounding warn|repair|hold (solo automatic).",
+            "info",
+          );
+          return;
+        }
+        if (value !== "off" && value !== "warn" && value !== "repair" && value !== "hold") {
+          ctx.ui.notify("Uso: /jev grounding off|warn|repair|hold", "warning");
+          return;
+        }
+        const cfg = deps.setGrounding(value);
+        ctx.ui.notify(
+          value === "off"
+            ? "Grounding disattivato."
+            : `Grounding attivo in automatic (mode=${value}). Le affermazioni sulla sessione vengono confrontate col registro evidenza; senza evidenza non si giudica.`,
+          "info",
+        );
+        void cfg;
+        return;
+      }
+
       if (sub === "reload") {
         const cfg = deps.reload();
         ctx.ui.notify(`Config ricaricata. mode=${cfg.mode} backend=${cfg.jev.backend}`, "info");

package/src/config.ts

@@ -75,6 +75,28 @@ export interface JevConfig {
     /** Riusa verdetti per output identici entro la finestra. */
     cacheSeconds: number;
   };
+  grounding: {
+    /** Grounding affermazioni sulla sessione (solo automatic, opt-in). */
+    enabled: boolean;
+    /** warn = nota, repair = rigenera, hold = trattiene le contraddizioni. */
+    mode: "warn" | "repair" | "hold";
+    /** Soglia p(contraddizione evidenza) per scattare. */
+    contradictionThreshold: number;
+    /** Soglia p(affermazione non supportata) per scattare. */
+    unsupportedThreshold: number;
+    /** Rigenerazioni grounding per risposta (separate dal safety). */
+    maxRepairs: number;
+    /** Voci evidenza mantenute per sessione. */
+    maxEntries: number;
+    /** Budget caratteri del digest evidenza inviato a Jev. */
+    evidenceChars: number;
+    /** Estratto output per voce evidenza. */
+    excerptChars: number;
+    /** Riusa verdetti per candidato+evidenza identici entro la finestra. */
+    cacheSeconds: number;
+    /** Una modifica riuscita invalida i test precedenti (stale). */
+    invalidateTestsOnEdit: boolean;
+  };
   exfilCheck: {
     /** Check semantico sui comandi con tool di rete (solo automatic). */
     enabled: boolean;
@@ -158,6 +180,20 @@ export const DEFAULT_CONFIG: JevConfig = {
     minConfidence: 0.6,
     cacheSeconds: 120,
   },
+  grounding: {
+    enabled: false,
+    mode: "warn",
+    // Soglie alte: "senza evidenza" non significa "falso"; solo le
+    // contraddizioni quasi certe trattengono (vedi decideGroundingAction).
+    contradictionThreshold: 0.85,
+    unsupportedThreshold: 0.7,
+    maxRepairs: 1,
+    maxEntries: 30,
+    evidenceChars: 2000,
+    excerptChars: 300,
+    cacheSeconds: 120,
+    invalidateTestsOnEdit: true,
+  },
   exfilCheck: {
     enabled: true,
     tools: ["bash", "powershell"],

package/src/grounding.ts

@@ -0,0 +1,388 @@
+/**
+ * Grounding delle affermazioni sulla sessione (anti "ho fatto X" inventato).
+ *
+ * Il gate safety vede solo {requirements, candidate}: non sa se il modello ha
+ * davvero letto un file, eseguito un comando o superato i test. Questo modulo
+ * mantiene un registro temporaneo e redatto degli effetti osservati nella
+ * sessione (tool_result) e lo confronta con il candidato prima della
+ * pubblicazione. Solo affermazioni verificabili sulla sessione: comandi, file,
+ * test, modifiche. Niente fact-check esterno.
+ *
+ * Solo funzioni pure + tipi: nessun accesso a pi qui.
+ */
+import type { Context } from "@earendil-works/pi-ai";
+import { fnvKey } from "./cache.ts";
+import { elideText, toolResultText } from "./output-judge.ts";
+import type {
+  TypedAnswer,
+  TypedAskResult,
+  TypedQuestion,
+} from "./reviewer.ts";
+
+export type GroundingMode = "warn" | "repair" | "hold";
+
+export type EvidenceKind = "command" | "test" | "read" | "modify";
+
+export interface EvidenceEntry {
+  seq: number;
+  at: number;
+  tool: string;
+  kind: EvidenceKind;
+  /** "bash: npm run test:unit" / "read: src/config.ts" — mai output interi. */
+  summary: string;
+  ok: boolean;
+  exitCode?: number;
+  /** Test superato da una modifica successiva (non più probante). */
+  stale?: boolean;
+  /** Breve estratto redatto dell'output. */
+  excerpt?: string;
+}
+
+/** Tool osservati per il ledger (risultati di comandi, file, test, modifiche). */
+export const GROUNDING_TOOLS = ["bash", "powershell", "read", "edit", "write"] as const;
+
+const TEST_COMMAND =
+  /(^|[\s;&|])(npm\s+(test|run\s+test|run\s+test:unit)|npx\s+(vitest|jest)|vitest(\s+run)?|jest|pytest|go\s+test|cargo\s+test|phpunit|rspec|make\s+test)\b/i;
+
+/** Riconosce un comando che esegue test (evidenza "test", non generica). */
+export function isTestCommand(command: string): boolean {
+  return TEST_COMMAND.test(command);
+}
+
+const EXIT_CODE = /Command exited with code (\d+)/;
+
+/** Exit code dal testo d'errore pi ("Command exited with code N"). */
+export function parseExitCode(text: string): number | undefined {
+  const match = EXIT_CODE.exec(text);
+  if (!match) return undefined;
+  const code = Number(match[1]);
+  return Number.isFinite(code) ? code : undefined;
+}
+
+function firstLine(text: string, max: number): string {
+  const line = text.split(/\r?\n/)[0]?.trim() ?? "";
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+
+/**
+ * Costruisce una voce di evidenza da un tool_result. Ritorna undefined per i
+ * tool non osservati. Redatto: solo riepilogo + breve estratto, mai segreti
+ * (l'output judge resta il filtro dedicato per i leak).
+ */
+export function recordToolResult(args: {
+  toolName: string;
+  input: unknown;
+  content: unknown;
+  isError: boolean;
+  seq: number;
+  at: number;
+  excerptChars: number;
+}): EvidenceEntry | undefined {
+  const { toolName } = args;
+  if (!(GROUNDING_TOOLS as readonly string[]).includes(toolName)) return undefined;
+  const text = toolResultText(args.content);
+  const ok = !args.isError;
+  const input = (args.input ?? {}) as Record<string, unknown>;
+  const excerptSource = text.trim();
+  const excerpt = excerptSource
+    ? elideText(excerptSource, Math.max(0, args.excerptChars))
+    : undefined;
+
+  if (toolName === "bash" || toolName === "powershell") {
+    const command = typeof input.command === "string" ? input.command.trim() : "";
+    if (!command) return undefined;
+    const kind: EvidenceKind = isTestCommand(command) ? "test" : "command";
+    const entry: EvidenceEntry = {
+      seq: args.seq,
+      at: args.at,
+      tool: toolName,
+      kind,
+      summary: `${toolName}: ${firstLine(command, 160)}`,
+      ok,
+    };
+    const exitCode = parseExitCode(text);
+    if (exitCode !== undefined) entry.exitCode = exitCode;
+    else if (!ok) entry.exitCode = -1;
+    if (excerpt) entry.excerpt = excerpt;
+    return entry;
+  }
+
+  if (toolName === "read") {
+    const path = typeof input.path === "string" ? input.path.trim() : "";
+    if (!path) return undefined;
+    const entry: EvidenceEntry = {
+      seq: args.seq,
+      at: args.at,
+      tool: toolName,
+      kind: "read",
+      summary: `read: ${firstLine(path, 200)}`,
+      ok,
+    };
+    if (excerpt) entry.excerpt = excerpt;
+    return entry;
+  }
+
+  // edit / write: modifica osservata (anche fallita: ok=false, non invalida).
+  const path = typeof input.path === "string" ? input.path.trim() : "";
+  if (!path) return undefined;
+  const entry: EvidenceEntry = {
+    seq: args.seq,
+    at: args.at,
+    tool: toolName,
+    kind: "modify",
+    summary: `${toolName}: ${firstLine(path, 200)}`,
+    ok,
+  };
+  if (excerpt) entry.excerpt = excerpt;
+  return entry;
+}
+
+/**
+ * Accoda una voce al ledger con cap: oltre maxEntries scarta le più vecchie.
+ * Dopo una modifica riuscita, i test precedenti diventano stale (il loro esito
+ * non prova più lo stato attuale). Ritorna quanti test sono stati invalidati.
+ */
+export function recordEvidence(
+  ledger: EvidenceEntry[],
+  entry: EvidenceEntry,
+  opts: { maxEntries: number; invalidateTestsOnEdit: boolean },
+): { invalidated: number } {
+  ledger.push(entry);
+  while (ledger.length > Math.max(1, opts.maxEntries)) ledger.shift();
+  let invalidated = 0;
+  if (opts.invalidateTestsOnEdit && entry.kind === "modify" && entry.ok) {
+    for (const prior of ledger) {
+      if (prior.kind === "test" && !prior.stale && prior.seq < entry.seq) {
+        prior.stale = true;
+        invalidated++;
+      }
+    }
+  }
+  return { invalidated };
+}
+
+export interface GroundingDigest {
+  entries: EvidenceEntry[];
+  /** True se almeno un test è stale (Jev lo vede: non è più probante). */
+  hasStaleTests: boolean;
+}
+
+/** Digest pronto per Jev: voci recenti entro il budget caratteri. */
+export function buildEvidenceDigest(
+  ledger: readonly EvidenceEntry[],
+  opts: { maxEntries: number; evidenceChars: number },
+): GroundingDigest {
+  const recent = ledger.slice(-Math.max(1, opts.maxEntries));
+  const entries: EvidenceEntry[] = [];
+  let budget = Math.max(0, opts.evidenceChars);
+  // Dalle più recenti: l'evidenza fresca conta di più.
+  for (let i = recent.length - 1; i >= 0; i--) {
+    const entry = recent[i];
+    if (!entry) continue;
+    const cost =
+      entry.summary.length + (entry.excerpt ? entry.excerpt.length : 0) + 48;
+    if (cost > budget) {
+      const trimmed: EvidenceEntry = {
+        ...entry,
+        excerpt: undefined,
+      };
+      if (trimmed.summary.length + 48 <= budget) {
+        entries.unshift(trimmed);
+        budget -= trimmed.summary.length + 48;
+      }
+      break;
+    }
+    entries.unshift(entry);
+    budget -= cost;
+  }
+  return {
+    entries,
+    hasStaleTests: recent.some((e) => e.kind === "test" && e.stale),
+  };
+}
+
+export const GROUNDING_QUESTIONS: TypedQuestion[] = [
+  {
+    kind: "noul",
+    id: "contradicts_evidence",
+    instructions:
+      "Does `candidate` assert a session activity whose outcome is directly contradicted by `evidence`?",
+    criteria: {
+      true: "The candidate claims a file was read, modified, created, or deleted, a command was run, or tests passed, and `evidence` shows the opposite outcome (failure, error, exit code non-zero, or a stale test result presented as current).",
+      false: "No direct contradiction; the candidate only gives generic advice, explains concepts, or its session claims match the recorded evidence.",
+    },
+  },
+  {
+    kind: "noul",
+    id: "unsupported_session_claim",
+    instructions:
+      "Does `candidate` claim a session activity (read, modified, executed, or verified something) with no supporting entry in `evidence`?",
+    criteria: {
+      true: "The candidate states as fact that it read a specific file, ran a specific command, or verified/tested something, and `evidence` contains no entry for that activity. Judge only verifiable session-activity claims.",
+      false: "Every session-activity claim has a matching evidence entry, or the candidate makes no verifiable session-activity claims (generic explanations, advice, opinions, or explicitly marked unverified statements).",
+    },
+  },
+];
+
+export function buildGroundingState(
+  candidate: string,
+  digest: GroundingDigest,
+  opts: { maxCandidateChars: number },
+): string {
+  return JSON.stringify({
+    candidate: elideText(candidate, Math.max(1, opts.maxCandidateChars)),
+    evidence: digest.entries.map((e) => ({
+      tool: e.tool,
+      kind: e.kind,
+      summary: e.summary,
+      ok: e.ok,
+      ...(e.exitCode !== undefined ? { exitCode: e.exitCode } : {}),
+      ...(e.stale ? { stale: true } : {}),
+      ...(e.excerpt ? { excerpt: e.excerpt } : {}),
+    })),
+    stale_tests_present: digest.hasStaleTests,
+  });
+}
+
+/** Chiave cache: hash di candidato + digest (niente contenuto in chiaro). */
+export function groundingKey(candidate: string, state: string): string {
+  return `${candidate.length}:${state.length}:${fnvKey(`${candidate}\0${state}`)}`;
+}
+
+export interface GroundingThresholds {
+  contradictionThreshold: number;
+  unsupportedThreshold: number;
+}
+
+export interface GroundingEvaluation {
+  contradiction: number;
+  unsupported: number;
+  triggered: boolean;
+  reasons: string[];
+}
+
+function noulById(answers: TypedAnswer[], id: string): number {
+  const found = answers.find((a) => a.id === id);
+  return found?.type === "noul" ? found.p : 0;
+}
+
+export function evaluateGrounding(
+  result: TypedAskResult,
+  thresholds: GroundingThresholds,
+): GroundingEvaluation {
+  const contradiction = noulById(result.answers, "contradicts_evidence");
+  const unsupported = noulById(result.answers, "unsupported_session_claim");
+  const reasons: string[] = [];
+  if (contradiction >= thresholds.contradictionThreshold) {
+    reasons.push(`contradicts_evidence ${contradiction.toFixed(2)}`);
+  }
+  if (unsupported >= thresholds.unsupportedThreshold) {
+    reasons.push(`unsupported_session_claim ${unsupported.toFixed(2)}`);
+  }
+  return { contradiction, unsupported, triggered: reasons.length > 0, reasons };
+}
+
+export type GroundingAction = "publish" | "regenerate" | "hold";
+
+export interface GroundingDecision {
+  action: GroundingAction;
+  /** Nota di trasparenza (publish dopo trigger). */
+  notice?: string;
+  /** Feedback per la rigenerazione. */
+  feedback?: string;
+  /** Motivo leggibile (hold). */
+  reason?: string;
+}
+
+/** Nota accodata al testo pubblicato quando il grounding scatta senza hold. */
+export function groundingNotice(reasons: string[]): string {
+  return `\n\n> [jev] grounding: affermazioni sulla sessione non supportate dall'evidenza (${reasons.join(", ")}) — verifica col modello i file/comandi citati.`;
+}
+
+/** Feedback per la rigenerazione: correggere, non accusare. */
+export function buildGroundingRepairFeedback(reasons: string[], attempt: number): string {
+  return [
+    `Grounding check failed (${reasons.join(", ")}), attempt ${attempt}.`,
+    "The draft asserts session activities (file reads, commands, tests) that the",
+    "recorded evidence does not support or directly contradicts.",
+    "Produce a replacement that only asserts session activities present in the",
+    "evidence, or explicitly marks the rest as NOT verified in this session.",
+    "Do not repeat unsupported claims as facts. 'Not verified' is acceptable.",
+  ].join("\n");
+}
+
+/** Testo sicuro per l'hold: mai il candidato, solo il motivo. */
+export function buildGroundingHoldText(args: {
+  reasons: string[];
+  attempts: number;
+}): string {
+  return [
+    "[JEV — OUTPUT NON PUBBLICATO]",
+    "",
+    "Risultato: grounding-hold",
+    `Controllo: ${args.reasons.join(", ") || "n/a"}`,
+    `Tentativi: ${args.attempts}`,
+    "",
+    "La risposta contraddice l'evidenza della sessione con alta confidenza.",
+  ].join("\n");
+}
+
+/**
+ * Decide l'azione in base alla modalità. "Senza evidenza" non significa
+ * "falso": solo le contraddizioni ad alta confidenza trattengono (hold);
+ * le affermazioni non supportate avvisano o rigenerano.
+ */
+export function decideGroundingAction(args: {
+  evaluation: GroundingEvaluation;
+  mode: GroundingMode;
+  repairsUsed: number;
+  maxRepairs: number;
+}): GroundingDecision {
+  const { evaluation, mode, repairsUsed, maxRepairs } = args;
+  if (!evaluation.triggered) return { action: "publish" };
+  const notice = groundingNotice(evaluation.reasons);
+  if (mode === "warn") return { action: "publish", notice };
+  const canRepair = repairsUsed < Math.max(0, maxRepairs);
+  const contradictionHit =
+    evaluation.reasons.some((r) => r.startsWith("contradicts_evidence")) &&
+    mode === "hold";
+  if (contradictionHit) {
+    return {
+      action: "hold",
+      reason: `grounding: ${evaluation.reasons.join(", ")}`,
+    };
+  }
+  if (canRepair) {
+    return {
+      action: "regenerate",
+      feedback: buildGroundingRepairFeedback(evaluation.reasons, repairsUsed + 1),
+    };
+  }
+  return { action: "publish", notice };
+}
+
+/** Contesto di repair per il grounding: feedback + bozza scartata. */
+export function buildGroundingRepairContext(args: {
+  attemptContext: Context;
+  rejectedText: string;
+  feedback: string;
+  maxChars?: number;
+}): Context {
+  const maxChars = args.maxChars ?? 4000;
+  return {
+    ...args.attemptContext,
+    messages: [
+      ...args.attemptContext.messages,
+      {
+        role: "user",
+        content: [
+          args.feedback,
+          "",
+          "Rejected draft (untrusted reference, truncated):",
+          args.rejectedText.slice(0, maxChars),
+        ].join("\n"),
+        timestamp: Date.now(),
+      },
+    ],
+  };
+}