@alisio/core 0.6.0 → 0.8.0

package/dist/plan/exit-plan.js

@@ -15,10 +15,30 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { textResult } from "@alisio/sdk";
 import { EXIT_PLAN_TOOL } from "../core/opt-in.js";
+import { newUuid } from "../runtime/ids.js";
 import { objectSchema } from "../tools/standard.js";
+import { applyCriteriaSelection, validateCriteriaDrafts, } from "./criteria.js";
 import { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, validateDiagrams, } from "./diagrams.js";
 import { buildPlanManifest } from "./manifest.js";
-import { currentPlan, decidePlan, nextPlanRevision, PLAN_CONTEXT_MAX_CHARS, PLAN_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, planTitle, proposePlan, withdrawPendingPlan, } from "./state.js";
+import { currentPlan, decidePlan, nextPlanRevision, PLAN_CONTEXT_MAX_CHARS, PLAN_CRITERIA_KEY, PLAN_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, planTitle, proposePlan, withdrawPendingPlan, } from "./state.js";
+const CRITERIA_SCHEMA = {
+    type: "array",
+    description: "Optional acceptance criteria you PROPOSE for this plan. They are drafts: they only become " +
+        "active if the user approves the plan, and a criterion with no verifier stays unchecked.",
+    items: {
+        type: "object",
+        properties: {
+            text: { type: "string", description: "A verifiable statement, e.g. 'Unit tests pass'" },
+            required: { type: "boolean", description: "Must hold before the work counts as done" },
+            verifier: {
+                type: "object",
+                description: "How to check it: {kind:'command', command:'pnpm test'}, {kind:'file', path} or {kind:'manual'}",
+            },
+            scope: { type: "array", items: { type: "string" }, description: "Globs it covers" },
+        },
+        required: ["text"],
+    },
+};
 const DIAGRAM_SCHEMA = {
     type: "array",
     description: `Optional Mermaid diagrams; see the plan agent's instructions`,
@@ -96,7 +116,13 @@ export function registerExitPlan(registry, deps) {
             description: "The whole plan in Markdown",
         },
     }, ["plan"]);
-    const withDiagrams = objectSchema({ ...plain.properties, diagrams: DIAGRAM_SCHEMA }, ["plan"]);
+    const withCriteria = deps.proof ? { acceptanceCriteria: CRITERIA_SCHEMA } : {};
+    const plainCriteria = objectSchema({ ...plain.properties, ...withCriteria }, ["plan"]);
+    const withDiagrams = objectSchema({
+        ...plain.properties,
+        ...withCriteria,
+        diagrams: DIAGRAM_SCHEMA,
+    }, ["plan"]);
     // The input is always VALIDATED with `diagrams` allowed (a call made while they were switched
     // off must not fail), but the model is only OFFERED the field while diagrams are on: the
     // registry compiles the schema once, while the provider reads it on every request.
@@ -105,12 +131,15 @@ export function registerExitPlan(registry, deps) {
         name: EXIT_PLAN_TOOL,
         effect: "read",
         get description() {
-            return offered()
-                ? `${BASE_DESCRIPTION} Optional \`diagrams\`: up to ${settings().max} small Mermaid diagrams (see your instructions).`
+            const base = deps.proof
+                ? `${BASE_DESCRIPTION} Optional \`acceptanceCriteria\`: drafts the user approves together with the plan.`
                 : BASE_DESCRIPTION;
+            return offered()
+                ? `${base} Optional \`diagrams\`: up to ${settings().max} small Mermaid diagrams (see your instructions).`
+                : base;
         },
         get inputSchema() {
-            return registering || offered() ? withDiagrams : plain;
+            return registering || offered() ? withDiagrams : plainCriteria;
         },
         async execute(input, context) {
             const plan = String(input.plan ?? "").trim();
@@ -118,7 +147,7 @@ export function registerExitPlan(registry, deps) {
                 throw new Error("exit_plan needs the whole plan in the `plan` field");
             const sessionId = context.session;
             const title = planTitle(plan, input.title);
-            const planId = crypto.randomUUID();
+            const planId = newUuid();
             const reviewable = !!sessionId && deps.ui.interactive() && !deps.readOnly;
             const revision = sessionId ? nextPlanRevision(deps.store, sessionId) : 1;
             const previous = sessionId
@@ -144,6 +173,15 @@ export function registerExitPlan(registry, deps) {
                     outcome.dropped = validated.dropped;
                 }
             }
+            // Acceptance criteria are DRAFTS here (O3): validated, shown in the review, stored in the plan
+            // state, and turned into real criteria only by the user's approval below. Nothing in this
+            // block writes the ledger.
+            const rawCriteria = deps.proof ? input.acceptanceCriteria : undefined;
+            const proposed = rawCriteria === undefined || (Array.isArray(rawCriteria) && !rawCriteria.length)
+                ? undefined
+                : validateCriteriaDrafts(rawCriteria);
+            const drafts = proposed?.accepted ?? [];
+            const droppedCriteria = proposed?.dropped ?? [];
             const preManifest = buildPlanManifest({
                 planId,
                 revision,
@@ -152,11 +190,12 @@ export function registerExitPlan(registry, deps) {
                 markdown: plan,
                 diagrams: outcome.accepted,
                 ...(previous ? { previous } : {}),
+                ...(drafts.length ? { acceptanceCriteria: drafts } : {}),
             });
             outcome.removed = preManifest.removed;
             if (outcome.removed.length)
                 outcome.involved = true;
-            const hash = planHash(plan, preManifest.diagrams.map((d) => ({ id: d.id, hash: d.hash })));
+            const hash = planHash(plan, preManifest.diagrams.map((d) => ({ id: d.id, hash: d.hash })), drafts);
             const manifest = { ...preManifest, hash };
             const diagrams = manifest.diagrams.map((entry, index) => ({
                 id: entry.id,
@@ -175,7 +214,7 @@ export function registerExitPlan(registry, deps) {
             const publisher = context.artifacts;
             if (publisher) {
                 // A folder (plan.md + plan.json + diagrams) when diagrams are involved, else plan.md alone.
-                if (outcome.accepted.length || outcome.removed.length)
+                if (outcome.accepted.length || outcome.removed.length || drafts.length)
                     try {
                         artifact = await publishPlanFolder(publisher, [
                             { path: "plan.md", text: `${plan}\n` },
@@ -208,12 +247,23 @@ export function registerExitPlan(registry, deps) {
                 title,
                 ...(context.callId ? { callId: context.callId } : {}),
                 ...(artifact ? { artifactId: artifact.id } : {}),
+                ...(drafts.length ? { criteria: drafts } : {}),
                 ...(manifest.diagrams.length
                     ? {
                         diagrams: manifest.diagrams.map((d) => ({ id: d.id, title: d.title, hash: d.hash })),
                     }
                     : {}),
             };
+            const criteriaReport = (activated) => drafts.length || droppedCriteria.length
+                ? {
+                    criteria: {
+                        proposed: drafts.length,
+                        ...(droppedCriteria.length ? { dropped: droppedCriteria } : {}),
+                        ...(activated === undefined ? {} : { activated }),
+                        ...(rejectedDrafts ? { rejected: rejectedDrafts } : {}),
+                    },
+                }
+                : {};
             const report = diagramReport(outcome);
             if (!reviewable) {
                 // Nobody to ask: keep the revision count honest and tell the model what to do instead.
@@ -238,6 +288,7 @@ export function registerExitPlan(registry, deps) {
                 markdown: plan,
                 ...(artifact ? { artifact } : {}),
                 ...(diagrams.length ? { diagrams } : {}),
+                ...(drafts.length ? { acceptanceCriteria: drafts } : {}),
             };
             const result = await deps.ui.askQuestions({
                 questions: [
@@ -270,16 +321,47 @@ export function registerExitPlan(registry, deps) {
                 hash,
                 decision,
             });
+            // The only place a draft becomes a criterion: the user's own approval, applied once by the
+            // compare-and-set above, of exactly the drafts stored with that proposal.
+            let activated;
+            let rejectedDrafts = 0;
+            if (decision === "approve" && deps.proof && decided.criteria?.length) {
+                // The user may approve, edit or reject each draft (`plan:criteria`); a selection that is
+                // not clean activates none of them.
+                const picked = applyCriteriaSelection(decided.criteria, result[PLAN_CRITERIA_KEY]);
+                rejectedDrafts = picked ? picked.rejected : decided.criteria.length;
+                try {
+                    for (const draft of picked?.kept ?? [])
+                        deps.proof.addCriterion({
+                            sessionId,
+                            text: draft.text,
+                            origin: draft.origin,
+                            required: draft.required,
+                            ...(draft.verifier ? { verifier: draft.verifier } : {}),
+                            ...(draft.scope ? { scope: draft.scope } : {}),
+                        });
+                    activated = picked?.kept.length ?? 0;
+                }
+                catch {
+                    activated = "failed";
+                }
+            }
             const base = {
                 planId,
                 revision,
                 ...(artifact ? { artifactId: artifact.id } : {}),
                 ...report,
+                ...criteriaReport(activated),
             };
             const body = decision === "approve"
                 ? answer("approved", "The user approved the plan. The build agent will implement exactly this plan in the " +
                     "next turn. Do not implement anything yourself: reply with one short sentence and " +
-                    "call no more tools.", base)
+                    "call no more tools." +
+                    (typeof activated === "number"
+                        ? ` ${activated} acceptance criteria are now active.`
+                        : activated === "failed"
+                            ? " The acceptance criteria could not be saved; they are not active."
+                            : ""), base)
                 : decision === "context"
                     ? answer("feedback", "The user added context instead of deciding. Revise the plan to account for it and " +
                         "call exit_plan again with the complete updated plan" +

package/dist/plan/manifest.d.ts

@@ -1,4 +1,4 @@
-import type { PlanDiagramStatus, PlanManifest } from "@alisio/sdk";
+import type { PlanCriterionDraft, PlanDiagramStatus, PlanManifest } from "@alisio/sdk";
 import { type PlanDiagram } from "./diagrams.ts";
 export interface PlanHeading {
     id: string;
@@ -31,6 +31,8 @@ export interface ManifestInput {
     diagrams: PlanDiagram[];
     /** Diagrams of the previous revision (from the plan state), when there was one. */
     previous?: DiagramRecord[];
+    /** Acceptance-criteria drafts of this revision (specs/011); absent or empty = none. */
+    acceptanceCriteria?: PlanCriterionDraft[];
 }
 /** The diff of this revision's diagrams against the previous one. */
 export declare function diffDiagrams(diagrams: Array<{
@@ -50,4 +52,4 @@ export declare function buildPlanManifest(input: ManifestInput): PlanManifest;
 export declare function planContentHash(markdown: string, diagrams: Array<{
     id: string;
     hash: string;
-}>): string;
+}>, criteria?: PlanCriterionDraft[]): string;

package/dist/plan/manifest.js

@@ -308,12 +308,17 @@ export function buildPlanManifest(input) {
             };
         }),
         removed,
+        ...(input.acceptanceCriteria?.length ? { acceptanceCriteria: input.acceptanceCriteria } : {}),
     };
 }
 /** The hash of a plan revision: the Markdown alone, or the Markdown plus its diagrams. */
-export function planContentHash(markdown, diagrams) {
+export function planContentHash(markdown, diagrams, criteria = []) {
     const hash = createHash("sha256").update(markdown, "utf8");
     if (diagrams.length)
         hash.update(`\n--diagrams--\n${diagrams.map((d) => `${d.id}:${d.hash}`).join("\n")}`, "utf8");
+    // The criteria are part of what the user approves, so they are part of the hash (only when
+    // present: a plan without criteria keeps the hash it always had).
+    if (criteria.length)
+        hash.update(`\n--criteria--\n${JSON.stringify(criteria.map((c) => [c.text, c.required, c.verifier ?? null, c.scope ?? null]))}`, "utf8");
     return hash.digest("hex");
 }

package/dist/plan/state.d.ts

@@ -8,12 +8,18 @@
  *    ├────skip──────▶ skipped          └─discard─▶ cancelled (the run was cancelled)
  *    └────context───▶ feedback         (a later `exit_plan` call starts a new revision)
  */
-import type { QuestionOption } from "@alisio/sdk";
+import type { PlanCriterionDraft, QuestionOption } from "@alisio/sdk";
 import { type DiagramRecord } from "./manifest.ts";
 /** The decision screen title (web: localized; the TUI prints it as is). */
 export declare const PLAN_REVIEW_TITLE = "Plan complete. What would you like to do?";
 export declare const PLAN_QUESTION_ID = "plan";
 export declare const PLAN_TEXT_KEY = "plan:text";
+/**
+ * Per-draft decisions on the acceptance criteria (specs/011 phase 5): a JSON object
+ * `{reject?: number[], edit?: {"<index>": "text"}, required?: {"<index>": boolean}}` over the
+ * drafts as the review lists them. Only read together with `approve`.
+ */
+export declare const PLAN_CRITERIA_KEY = "plan:criteria";
 /** The agent an approved plan is handed to. */
 export declare const IMPLEMENTATION_AGENT_ID = "build";
 export declare const PLAN_MAX_CHARS = 60000;
@@ -33,6 +39,11 @@ export interface PlanState {
     artifactId?: string;
     /** The accepted diagrams of this revision (absent without any): what the next one is diffed against. */
     diagrams?: DiagramRecord[];
+    /**
+     * Acceptance-criteria DRAFTS of this revision (specs/011, O3). They are not criteria: they only
+     * become active when the user approves this plan (`exit-plan.ts`), and a later revision replaces them.
+     */
+    criteria?: PlanCriterionDraft[];
     /** The approved snapshot; kept only while `approved` (afterwards it lives in the user message). */
     plan?: string;
     updatedAt: number;
@@ -54,7 +65,7 @@ export interface PlanStore {
 export declare const planHash: (plan: string, diagrams?: Array<{
     id: string;
     hash: string;
-}>) => string;
+}>, criteria?: PlanCriterionDraft[]) => string;
 /** The plan state stored in `options`, or undefined when absent or malformed. */
 export declare function readPlanState(options: Record<string, unknown> | undefined): PlanState | undefined;
 export declare const currentPlan: (store: PlanStore, sessionId: string) => PlanState | undefined;

package/dist/plan/state.js

@@ -3,6 +3,12 @@ import { planContentHash } from "./manifest.js";
 export const PLAN_REVIEW_TITLE = "Plan complete. What would you like to do?";
 export const PLAN_QUESTION_ID = "plan";
 export const PLAN_TEXT_KEY = `${PLAN_QUESTION_ID}:text`;
+/**
+ * Per-draft decisions on the acceptance criteria (specs/011 phase 5): a JSON object
+ * `{reject?: number[], edit?: {"<index>": "text"}, required?: {"<index>": boolean}}` over the
+ * drafts as the review lists them. Only read together with `approve`.
+ */
+export const PLAN_CRITERIA_KEY = `${PLAN_QUESTION_ID}:criteria`;
 /** The agent an approved plan is handed to. */
 export const IMPLEMENTATION_AGENT_ID = "build";
 export const PLAN_MAX_CHARS = 60_000;
@@ -22,7 +28,7 @@ export const PLAN_OPTIONS = [
  * The hash of a plan revision. Without diagrams it is the SHA-256 of the Markdown (as before);
  * with diagrams it also covers them, so a change in a diagram alone is a different plan.
  */
-export const planHash = (plan, diagrams = []) => planContentHash(plan, diagrams);
+export const planHash = (plan, diagrams = [], criteria = []) => planContentHash(plan, diagrams, criteria);
 const STATUSES = new Set([
     "pending",
     "approved",

package/dist/plugins/host.d.ts

@@ -5,6 +5,7 @@ import type { ToolRegistry } from "../core/registry.ts";
 import type { DecisionRegistry } from "../decisions/registry.ts";
 import type { DecisionService, DecisionsConfig } from "../decisions/service.ts";
 import { ExtensionRegistry } from "../extensions/registry.ts";
+import type { ProofVerifierRegistry } from "../proof/plugin-verifiers.ts";
 import type { ProviderRegistry } from "../providers/registry.ts";
 export declare const pluginPrefix: (id: string) => string;
 export interface PluginHostOptions {
@@ -165,6 +166,12 @@ export declare class PluginHost implements RunnerExtensions {
      * Binds the directories and options plugins receive (`api.paths`, `api.options`). Plugins
      * activated before this call, or on a host without it, see neither member.
      */
+    /**
+     * Binds the Proof verifier registry. Plugins activated afterwards see `api.proof`; without it
+     * the member is absent, exactly like on a core that predates Proof.
+     */
+    setProofVerifiers(registry: ProofVerifierRegistry): void;
+    private proofVerifiers?;
     setPluginEnvironment(environment: PluginEnvironment): void;
     private environment?;
     /** Binds credential-free model discovery/resolution after provider startup is complete. */

package/dist/plugins/host.js

@@ -178,6 +178,14 @@ export class PluginHost {
      * Binds the directories and options plugins receive (`api.paths`, `api.options`). Plugins
      * activated before this call, or on a host without it, see neither member.
      */
+    /**
+     * Binds the Proof verifier registry. Plugins activated afterwards see `api.proof`; without it
+     * the member is absent, exactly like on a core that predates Proof.
+     */
+    setProofVerifiers(registry) {
+        this.proofVerifiers = registry;
+    }
+    proofVerifiers;
     setPluginEnvironment(environment) {
         this.environment = environment;
     }
@@ -428,6 +436,13 @@ export class PluginHost {
                     };
                 })(this.environment)
                 : {}),
+            ...(this.proofVerifiers
+                ? {
+                    proof: ((registry) => ({
+                        registerVerifier: (verifier) => track(registry.register(plugin.id, verifier)),
+                    }))(this.proofVerifiers),
+                }
+                : {}),
             ...(this.decisionsImpl
                 ? {
                     decisions: (({ registry, service, activation }) => ({

package/dist/proof/command.d.ts

@@ -0,0 +1,24 @@
+export type CommandTool = "run_process" | "shell";
+/** The canonical workspace-relative directory: forward slashes, no `./` prefix, `.` when empty. */
+export declare function normalizeCwd(cwd: string): string;
+/** Directory of a call relative to the workspace (`.` when it is the workspace itself). */
+export declare function relativeCwd(workspace: string, cwd: string | undefined): string;
+export declare function commandFingerprint(argv: readonly string[], cwd: string): string;
+/** Trims and collapses whitespace runs OUTSIDE single/double quotes; quoted text stays verbatim. */
+export declare function normalizeShell(command: string): string;
+/** Fingerprint of a call as the tool received it. */
+export declare function callFingerprint(tool: CommandTool, input: {
+    command: string;
+    args?: readonly string[];
+}, cwd: string): string;
+/**
+ * Splits a plain command line into an argv (single and double quotes group words). Returns
+ * undefined when the line needs a shell (operators, expansions, unbalanced quotes): only the
+ * shell form can then match it.
+ */
+export declare function splitCommand(command: string): string[] | undefined;
+/**
+ * Every fingerprint a call may have to satisfy the criterion command `command` run in `cwd`: the
+ * `shell` form always and the `run_process` form when the line is a plain argv.
+ */
+export declare function criterionFingerprints(command: string, cwd: string): string[];

package/dist/proof/command.js

@@ -0,0 +1,109 @@
+/**
+ * Command fingerprint v1 (specs/011, Fase 0 decision): `sha256(JSON.stringify({v:1, argv, cwd}))`.
+ * `run_process` uses `[command, ...args]`; `shell` and `bg_run` use `["sh","-c", normalized]`; the
+ * working directory is relative to the workspace with `/` and `.` by default. No environment.
+ */
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve } from "node:path";
+/** The canonical workspace-relative directory: forward slashes, no `./` prefix, `.` when empty. */
+export function normalizeCwd(cwd) {
+    return (cwd
+        .split("\\")
+        .join("/")
+        .replace(/^(\.\/)+/, "")
+        .replace(/\/+$/, "") || ".");
+}
+/** Directory of a call relative to the workspace (`.` when it is the workspace itself). */
+export function relativeCwd(workspace, cwd) {
+    if (!cwd)
+        return ".";
+    const abs = isAbsolute(cwd) ? cwd : resolve(workspace, cwd);
+    return normalizeCwd(relative(workspace, abs));
+}
+export function commandFingerprint(argv, cwd) {
+    return createHash("sha256")
+        .update(JSON.stringify({ v: 1, argv, cwd: normalizeCwd(cwd) }))
+        .digest("hex");
+}
+/** Trims and collapses whitespace runs OUTSIDE single/double quotes; quoted text stays verbatim. */
+export function normalizeShell(command) {
+    let out = "";
+    let quote;
+    let pendingSpace = false;
+    for (const ch of command.trim()) {
+        if (quote) {
+            out += ch;
+            if (ch === quote)
+                quote = undefined;
+        }
+        else if (/\s/.test(ch)) {
+            pendingSpace = true;
+        }
+        else {
+            if (pendingSpace)
+                out += " ";
+            pendingSpace = false;
+            out += ch;
+            if (ch === '"' || ch === "'")
+                quote = ch;
+        }
+    }
+    return out;
+}
+/** Fingerprint of a call as the tool received it. */
+export function callFingerprint(tool, input, cwd) {
+    const argv = tool === "run_process"
+        ? [input.command, ...(input.args ?? [])]
+        : ["sh", "-c", normalizeShell(input.command)];
+    return commandFingerprint(argv, cwd);
+}
+const SHELL_OPERATORS = /[|&;<>()$`\\*?~#{}!\n]/;
+/**
+ * Splits a plain command line into an argv (single and double quotes group words). Returns
+ * undefined when the line needs a shell (operators, expansions, unbalanced quotes): only the
+ * shell form can then match it.
+ */
+export function splitCommand(command) {
+    const argv = [];
+    let word;
+    let quote;
+    for (const ch of command.trim()) {
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            else
+                word += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            word ??= "";
+        }
+        else if (/\s/.test(ch)) {
+            if (word !== undefined)
+                argv.push(word);
+            word = undefined;
+        }
+        else if (SHELL_OPERATORS.test(ch)) {
+            return undefined;
+        }
+        else {
+            word = (word ?? "") + ch;
+        }
+    }
+    if (quote)
+        return undefined;
+    if (word !== undefined)
+        argv.push(word);
+    return argv.length ? argv : undefined;
+}
+/**
+ * Every fingerprint a call may have to satisfy the criterion command `command` run in `cwd`: the
+ * `shell` form always and the `run_process` form when the line is a plain argv.
+ */
+export function criterionFingerprints(command, cwd) {
+    const out = [callFingerprint("shell", { command }, cwd)];
+    const argv = splitCommand(command);
+    if (argv)
+        out.unshift(commandFingerprint(argv, cwd));
+    return out;
+}

package/dist/proof/coverage.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure parser and judge of the `coverage` verifier (specs/011 3.1, Fase 7). They read the text a
+ * coverage command printed and say whether the overall percentage reaches `minPercent`; they never
+ * run anything and never generate tests. The evidence itself is captured by the recorder from the
+ * RAW result of a call the runner executed under its gate (D3, D6).
+ *
+ * Formats, tried from the most explicit overall figure to the least:
+ *  1. `coverage.py` / pytest-cov: the `TOTAL` row (last percentage) or `Total coverage: N%`.
+ *  2. A text table (vitest, c8, istanbul): the `All files` row, `% Lines` column.
+ *  3. An istanbul `text-summary`: the `Lines : N%` row.
+ *  4. `lcov --summary`: the `lines......: N%` row.
+ *  5. Raw `lcov` tracefile: sum of `LH` over sum of `LF`.
+ * Per-file rows never stand in for the total: a missing overall figure is "not found", so an
+ * unparseable output can never verify a criterion. Several matches of one format: the last wins.
+ */
+import type { ProofVerifierSpec } from "@alisio/sdk";
+export type CoverageSpec = Extract<ProofVerifierSpec, {
+    kind: "coverage";
+}>;
+export type CoverageFormat = "coverage.py" | "table" | "summary" | "lcov-summary" | "lcov";
+export interface ParsedCoverage {
+    percent: number;
+    format: CoverageFormat;
+}
+/** The overall coverage percentage a command printed, or undefined when there is none to trust. */
+export declare function parseCoverage(output: string): ParsedCoverage | undefined;
+/** What a coverage judgement concluded: the verdict and a short, secret-free sentence about it. */
+export interface CoverageJudgement {
+    ok: boolean;
+    summary: string;
+}
+/**
+ * Judges what the coverage command did. It verifies only when the command exited 0 AND an overall
+ * percentage was found AND it reaches `minPercent` (inclusive); every other case is a failure with
+ * a reason, so an unparseable output or a crashed run is never silently verified.
+ */
+export declare function judgeCoverage(spec: CoverageSpec, run: {
+    exitCode: number;
+    output: string;
+}): CoverageJudgement;

package/dist/proof/coverage.js

@@ -0,0 +1,102 @@
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+const NUMBER = String.raw `(\d{1,3}(?:\.\d+)?)`;
+const valid = (value) => Number.isFinite(value) && value >= 0 && value <= 100;
+const lastMatch = (text, pattern) => {
+    let found;
+    for (const match of text.matchAll(pattern))
+        found = match;
+    return found;
+};
+function pythonTotal(text) {
+    // pytest-cov prints the precise figure on its own line; prefer it over the rounded TOTAL row.
+    const line = lastMatch(text, new RegExp(String.raw `Total coverage:\s*${NUMBER}%`, "gi"));
+    if (line?.[1])
+        return Number(line[1]);
+    const row = lastMatch(text, new RegExp(String.raw `^\s*TOTAL\b[^\n]*?(?<![\d.])${NUMBER}%[ \t]*$`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function tableTotal(text) {
+    const lines = text.split("\n");
+    let column = -1;
+    let result;
+    for (const line of lines) {
+        if (!line.includes("|"))
+            continue;
+        const cells = line.split("|").map((cell) => cell.trim());
+        const header = cells.findIndex((cell) => /^%\s*lines?$/i.test(cell));
+        if (header >= 0) {
+            column = header;
+            continue;
+        }
+        if (column < 0 || !/^all files$/i.test(cells[0] ?? ""))
+            continue;
+        const raw = (cells[column] ?? "").replace(/%$/, "");
+        result = /^\d{1,3}(?:\.\d+)?$/.test(raw) ? Number(raw) : undefined;
+    }
+    return result;
+}
+function summaryLines(text) {
+    const row = lastMatch(text, new RegExp(String.raw `^\s*Lines\s*:\s*${NUMBER}%`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function lcovSummary(text) {
+    const row = lastMatch(text, new RegExp(String.raw `^\s*lines\.+:\s*${NUMBER}%`, "gim"));
+    return row?.[1] ? Number(row[1]) : undefined;
+}
+function lcovTracefile(text) {
+    let found = 0;
+    let hit = 0;
+    for (const match of text.matchAll(/^(LF|LH):(\d+)\s*$/gm)) {
+        if (match[1] === "LF")
+            found += Number(match[2]);
+        else
+            hit += Number(match[2]);
+    }
+    return found > 0 ? (hit / found) * 100 : undefined;
+}
+const PARSERS = [
+    ["coverage.py", pythonTotal],
+    ["table", tableTotal],
+    ["summary", summaryLines],
+    ["lcov-summary", lcovSummary],
+    ["lcov", lcovTracefile],
+];
+/** The overall coverage percentage a command printed, or undefined when there is none to trust. */
+export function parseCoverage(output) {
+    const text = output.replace(ANSI, "");
+    for (const [format, parse] of PARSERS) {
+        const percent = parse(text);
+        if (percent !== undefined && valid(percent))
+            return { percent, format };
+    }
+    return undefined;
+}
+const shown = (value) => String(Math.round(value * 100) / 100);
+/**
+ * Judges what the coverage command did. It verifies only when the command exited 0 AND an overall
+ * percentage was found AND it reaches `minPercent` (inclusive); every other case is a failure with
+ * a reason, so an unparseable output or a crashed run is never silently verified.
+ */
+export function judgeCoverage(spec, run) {
+    const parsed = parseCoverage(run.output);
+    if (!parsed)
+        return {
+            ok: false,
+            summary: `no coverage percentage found in the output (command exited ${run.exitCode}); expected lcov, a vitest/istanbul table or coverage.py report`,
+        };
+    const percent = `${shown(parsed.percent)}%`;
+    if (run.exitCode !== 0)
+        return {
+            ok: false,
+            summary: `the coverage command exited ${run.exitCode} (reported ${percent}, ${parsed.format})`,
+        };
+    if (parsed.percent < spec.minPercent)
+        return {
+            ok: false,
+            summary: `coverage ${percent} is below the minimum ${shown(spec.minPercent)}% (${parsed.format})`,
+        };
+    return {
+        ok: true,
+        summary: `coverage ${percent} reaches the minimum ${shown(spec.minPercent)}% (${parsed.format})`,
+    };
+}

package/dist/proof/divergence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Claim/evidence divergence (specs/011 3.5, D7, D8). `detectDivergence` is pure: it reads closed
+ * EN/ES claim patterns in a final answer ("tests pass", "typecheck ok", "lint clean", "los tests
+ * pasan"...), cross-references them with the criteria of an equivalent kind and reports the ones
+ * the ledger does not back. It never edits text or statuses; it is a heuristic signal, not a
+ * guarantee, and claims inside quotes and code are ignored to limit false positives.
+ */
+import type { ProofLedger, ProofStatus } from "@alisio/sdk";
+export type ClaimKind = "test" | "typecheck" | "lint";
+export interface Divergence {
+    /** The matched wording, whitespace-collapsed and capped. */
+    claim: string;
+    kind: ClaimKind;
+    /** What would have backed the claim. */
+    expected: "verified";
+    /** The status of the equivalent criterion (`not_checked` when there is none). */
+    actualState: ProofStatus;
+    criterionId?: string;
+}
+/**
+ * The claims of `finalText` that `ledger` does not back, in order of appearance. An empty ledger
+ * yields nothing (D7: without criteria Proof stays out of the way).
+ */
+export declare function detectDivergence(finalText: string, ledger: ProofLedger): Divergence[];