jev-agent-tools 0.1.4 → 0.3.0

package/dist/tools/spec-check.js

@@ -0,0 +1,263 @@
+import { resolveEvidenceContext, withEvidenceContext, } from "../adapters/evidence-context.js";
+import { collectFiles } from "../adapters/files.js";
+import { collectUnits } from "../adapters/git.js";
+import { resolveBase } from "../adapters/git-base.js";
+import { CHOICE_MAX_OPTIONS, STATE_MAX_CHARS, TIMEOUT_MS, } from "../constants.js";
+import { buildEnvelope, } from "../core/output.js";
+import { known, } from "../core/result-report.js";
+import { prepareSpecCheck, readSpecJudgment, } from "../presets/spec.js";
+import { NOT_CONFIGURED } from "../texts/configuration.js";
+import { ReviewReport, reportMetrics } from "./review-report.js";
+export async function runSpecCheck(deps, input) {
+    const started = performance.now();
+    const report = new ReviewReport();
+    const admission = input.evidenceContext
+        ? undefined
+        : await resolveEvidenceContext(input.cwd, undefined, {
+            exec: deps.exec,
+            signal: input.signal,
+            origin: deps.evidenceOrigin,
+        });
+    const evidenceContext = input.evidenceContext ?? admission?.context;
+    if (!evidenceContext)
+        throw new Error("Evidence context was not established");
+    evidenceContext.requestedBase = input.base ?? "HEAD";
+    const judgments = [];
+    const findings = [];
+    const limitations = [];
+    const unchecked = [];
+    let budget;
+    let sent = 0;
+    let incomplete = false;
+    let emptyBase;
+    const finish = (refusal, cause = "internal_error") => {
+        const answers = findings.map((finding) => ({
+            label: finding.kind === "requirement"
+                ? `${input.specPath}:${finding.requirement?.start}-${finding.requirement?.end} ${finding.label} — requirement violated`
+                : `${finding.unit?.file}:${finding.unit?.afterRange?.start ?? finding.unit?.beforeRange?.start}-${finding.unit?.afterRange?.end ?? finding.unit?.beforeRange?.end} ${finding.label} — external behavior absent from the specification`,
+            value: {
+                head: finding.kind === "requirement" ? "violates" : finding.label,
+                p: finding.probability,
+            },
+            band: incomplete ? "unsure" : "verdict",
+            ...(incomplete
+                ? { reason: "incomplete change evidence: read the omitted pieces" }
+                : {}),
+        }));
+        const envelope = buildEnvelope({
+            answers,
+            limitations: emptyBase !== undefined && !refusal
+                ? [
+                    ...limitations,
+                    {
+                        fact: `no changed units against ${emptyBase}`,
+                        next: "nothing judged; pass base= or check the working directory",
+                    },
+                ]
+                : limitations,
+            unchecked,
+            refusal,
+            budget,
+            ...(!refusal &&
+                !budget &&
+                !unchecked.length &&
+                !findings.length &&
+                emptyBase === undefined &&
+                report.items.size > 0 &&
+                [...report.items.values()].every((item) => item.treatment === "judged")
+                ? {
+                    lines: [
+                        {
+                            type: "list",
+                            title: "spec: no violations or drift reported",
+                            items: [],
+                        },
+                    ],
+                }
+                : {}),
+            yield: {
+                calls: judgments.reduce((n, j) => n + (j.calls ?? 0), 0),
+                questions: judgments.reduce((n, j) => n + (j.questions ?? 0), 0),
+                costUsd: judgments.length && judgments.every((j) => j.usage !== undefined)
+                    ? judgments.reduce((n, j) => n + (j.usage?.costUsd ?? 0), 0)
+                    : undefined,
+                cacheHits: judgments.reduce((n, j) => n + (j.cacheHits ?? 0), 0),
+                cacheRequests: judgments.reduce((n, j) => n + (j.cacheRequests ?? 0), 0),
+                elapsedMs: performance.now() - started,
+            },
+        });
+        if (emptyBase !== undefined)
+            report.diagnose("no_changed_units", `No changed units against ${emptyBase}`, emptyBase, [], false);
+        if (refusal) {
+            report.refusal = cause !== "not_configured";
+            report.diagnose(cause, refusal, input.specPath);
+        }
+        const result = report.build("jev_check_diff", evidenceContext, reportMetrics(envelope));
+        return { ok: !refusal, envelope, judgments, findings, result };
+    };
+    if (!input.specPath)
+        return finish("spec_path required: no specification to check against.", "missing_required");
+    if (!deps.client)
+        return finish(NOT_CONFIGURED, "not_configured");
+    const comparison = await resolveBase(deps.exec, input.cwd, input.base, input.signal);
+    if (!comparison.ok)
+        return finish(comparison.error, comparison.cause ?? "invalid_base");
+    const base = comparison.base;
+    evidenceContext.resolvedBase = base;
+    const root = await deps.exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd: input.cwd,
+        timeout: TIMEOUT_MS,
+        signal: input.signal,
+    });
+    if (root.code || root.killed)
+        return finish("Repository root not found.", root.killed ? "cancelled" : "git_failure");
+    const cwd = root.stdout.trim();
+    if (evidenceContext.effectiveRoot)
+        evidenceContext.effectiveRoot.path = cwd;
+    const [collected, specification] = await Promise.all([
+        collectUnits(deps.exec, { cwd, base, signal: input.signal }),
+        collectFiles(cwd, [input.specPath], input.signal, { exec: deps.exec }),
+    ]);
+    if (!collected.ok)
+        return finish(collected.error, collected.cause ?? "git_failure");
+    if (!specification.ok)
+        return finish(specification.error, specification.cause ?? "file_unavailable");
+    const text = Object.values(specification.files)[0];
+    if (!text)
+        return finish("The specification is empty: nothing to check.", "empty_required");
+    for (const limit of collected.limits)
+        limitations.push({
+            fact: `${limit.file} : ${limit.kind}`,
+            next: "Read the complete change before concluding.",
+        });
+    const unavailableUnits = collected.units.filter((unit) => unit.before === null && unit.after === null);
+    const units = collected.units.filter((unit) => unit.before !== null || unit.after !== null);
+    for (const unit of unavailableUnits)
+        unchecked.push(`${unit.file} ${unit.name} (changed source unavailable)`);
+    const prepared = prepareSpecCheck(text, units);
+    for (const requirement of prepared.requirements)
+        report.expect(`spec:${requirement.id}`, requirement.label, "requirement");
+    report.expect("spec:drift", "Specification drift pointer", "pointer");
+    report.inventories.push({
+        id: "spec-requirements",
+        kind: "sections",
+        rules: ["### REQ- headings in the supplied specification"],
+        restrictions: [input.specPath],
+        discovered: known(prepared.requirements.length),
+        considered: known(prepared.requirements.length),
+        scopeRestricted: true,
+        criteria: [],
+    });
+    report.inventories.push({
+        id: "changed-units",
+        kind: "units",
+        rules: ["Changed source units against resolved base"],
+        restrictions: [],
+        discovered: known(collected.units.length),
+        considered: known(units.length),
+        scopeRestricted: false,
+        criteria: [],
+    });
+    if (!collected.units.length && prepared.requirements.length)
+        report.items.clear();
+    const reportIds = [...report.items.keys()];
+    for (const unit of unavailableUnits)
+        report.diagnose("binary_or_non_utf8", "Changed source unavailable", unit.file, reportIds, units.length === 0, [`${unit.file} ${unit.name}`]);
+    for (const limit of collected.limits)
+        report.diagnose(limit.kind === "secret_pattern" ? "secret_pattern" : "collection_omitted", limit.kind, limit.file, reportIds, units.length === 0, ["unit" in limit ? `${limit.file} ${limit.unit}` : limit.file]);
+    report.missingWork =
+        unavailableUnits.length > 0 || collected.limits.length > 0;
+    if (!prepared.requirements.length)
+        return finish("No ### REQ-… requirements in the specification: nothing to check.", "missing_required");
+    if (!collected.units.length) {
+        emptyBase = base;
+        return finish();
+    }
+    if (unchecked.length) {
+        unchecked.push(...prepared.requirements.map((requirement) => `${requirement.label} (changed source unavailable)`), "drift (changed source unavailable)");
+    }
+    if (prepared.tableWarning) {
+        report.diagnose("unsupported_syntax", "Specification Markdown table interpretation is uncalibrated", input.specPath, [], false);
+        limitations.push({
+            fact: "The specification contains a Markdown table.",
+            next: "Read the table requirements: their interpretation is uncalibrated.",
+        });
+    }
+    incomplete = report.missingWork;
+    const state = withEvidenceContext(prepared.state, evidenceContext);
+    if (units.length + 1 > CHOICE_MAX_OPTIONS ||
+        JSON.stringify(state).length > STATE_MAX_CHARS)
+        return finish(`State or spec pointer exceeds the limits; compare against a closer base (STATE_MAX_CHARS=${STATE_MAX_CHARS}).`, "evidence_too_large");
+    if (!units.length)
+        return finish();
+    const judgment = await deps.client.judge(state, prepared.questions, {
+        signal: input.signal,
+        ...deps.runtime.session.requestGate(),
+        admissionCause: () => budget?.kind === "session" ? "session_budget" : "call_budget",
+        beforeRequest(questionCount) {
+            if (input.maxCalls !== undefined && sent >= input.maxCalls) {
+                budget = {
+                    kind: "max_calls",
+                    message: `max_calls=${input.maxCalls} reached`,
+                };
+                return { ok: false, error: budget.message };
+            }
+            const admitted = deps.runtime.session.admit(questionCount);
+            if (!admitted.ok)
+                budget = { kind: "session", message: admitted.error };
+            else
+                sent++;
+            return admitted;
+        },
+        onUsage: (usage) => deps.runtime.session.recordUsage(usage),
+    });
+    judgments.push(judgment);
+    if (!judgment.ok)
+        report.failure(judgment, reportIds, budget
+            ? budget.kind === "session"
+                ? "session_budget"
+                : "call_budget"
+            : undefined);
+    else {
+        for (const requirement of prepared.requirements)
+            report.answer(`spec:${requirement.id}`, judgment.answers[requirement.id], { band: incomplete ? "unsure" : "verdict" });
+        const driftAnswer = judgment.answers.drift;
+        const selectedUnit = driftAnswer?.type === "choice"
+            ? units.find((unit) => unit.id === driftAnswer.choice)
+            : undefined;
+        const pointer = report.items.get("spec:drift");
+        if (pointer && selectedUnit)
+            report.items.set("spec:drift", {
+                ...pointer,
+                label: `${selectedUnit.file} ${selectedUnit.name} specification drift`,
+            });
+        const selectedProbability = driftAnswer?.type === "choice"
+            ? driftAnswer.probabilities[driftAnswer.choice]
+            : undefined;
+        report.answer("spec:drift", driftAnswer, {
+            band: incomplete ? "unsure" : "verdict",
+            ...(driftAnswer?.type === "choice" && selectedProbability !== undefined
+                ? {
+                    value: {
+                        head: driftAnswer.choice,
+                        p: selectedProbability,
+                    },
+                }
+                : {}),
+        });
+    }
+    if (!judgment.ok) {
+        unchecked.push(...prepared.requirements.map((req) => `${req.label} (${judgment.error})`), `drift (${judgment.error})`);
+        return finish();
+    }
+    for (const requirement of prepared.requirements) {
+        const answer = judgment.answers[requirement.id];
+        if (!answer || answer.type === "unjudged")
+            unchecked.push(requirement.label);
+    }
+    const drift = judgment.answers.drift;
+    if (!drift || drift.type === "unjudged")
+        unchecked.push("drift");
+    findings.push(...readSpecJudgment(prepared, judgment.answers));
+    return finish();
+}

package/docs/adr/0001-strict-typescript-pure-core-offline-tests.md

@@ -0,0 +1,31 @@
+# 0001 — Strict TypeScript, a pure core and offline conformance tests
+
+Status: Accepted
+
+## Context
+
+The same extension runs inside pi and omp. Host-specific implementations would duplicate judgment policy and make deterministic checks harder to maintain. Optional native capabilities must not become mandatory runtime dependencies.
+
+## Decision
+
+Use one strict TypeScript package with erasable syntax, Node APIs and fetch rather than Bun-only APIs. Pure core transformations and question compilation consume and return values; thin adapters own host, filesystem, Git, network and clock effects. Tools compose collection, evidence construction, requests and result rendering. Discriminated unions represent expected refusals, unjudged work and abstention as values rather than exceptional control flow.
+
+Keep limits and thresholds in src/constants.ts. Batch questions for the same evidence state, run independent work concurrently under the shared limiter, and bound reads before loading content into memory.
+
+Enforce downward import layers, including erased type dependencies:
+
+- core/ imports core/, constants.ts, result.ts, result-types.ts and type-only contracts from jev/types.ts.
+- presets/ and adapters/ each import their own layer, core/ and those neutral modules; adapters/ does not import presets/ or tools/.
+- jev/ imports its own layer, core/, constants.ts, result.ts and result-types.ts.
+- texts/ imports its own layer, constants.ts and presets/; it has no external dependencies.
+- constants.ts and result-types.ts import nothing. result.ts may import the dependency-free result-types.ts contract. Root integration modules and tools/ compose the layers.
+
+Reject all cycles, including type-only cycles, and nonliteral module loading. Shared contracts belong below their consumers. Pure layers do not import external modules, with explicit core exceptions for pure node:path functions and erased import type contracts from @ast-grep/napi. Inline type specifiers that retain runtime loading do not qualify. Filesystem, process and network modules, direct fetch calls and Node builtin-module loaders are forbidden in the core; import checks are not an exhaustive proof against indirect global effects.
+
+Keep @ast-grep/napi, @ast-grep/lang-python and @ff-labs/fff-node optional. Load native parsing and search at the edges, use the available fallback and report missing capabilities rather than claiming equivalent syntax precision.
+
+Run deterministic offline conformance checks with tsc --noEmit, the import checker, Biome and node --test. Use constructed behavior and boundary cases and local HTTP fixtures for transport failures, retries and timeouts; no Jev credentials are required.
+
+## Consequences
+
+This separates effects from policy and makes host-independent behavior reproducible. Missing optional acceleration can reduce parsing or search capability, so limits stay visible. Native optimization is not a reason to introduce a separate judgment path or an extension-specific daemon.

package/docs/adr/0002-one-http-protocol-across-hosts.md

@@ -0,0 +1,17 @@
+# 0002 — One HTTP protocol across hosts
+
+Status: Accepted
+
+## Context
+
+pi and omp provide different integration APIs. Delegating judgment to a host's chat model would change the protocol and behavior according to the host.
+
+## Decision
+
+Use one HTTP client compatible with the Jev API format in both hosts. Read the user-supplied endpoint and Bearer credential from JEV_TOOLS_URL and JEV_TOOLS_API_KEY and the requested model from JEV_TOOLS_MODEL, defaulting to openjev.
+
+Without the endpoint or key, keep tools registered and explain the missing configuration; disable the automatic documentation check. Never fall back to a chat model or a host-internal judgment service.
+
+## Consequences
+
+Users choose the service and must review which evidence it receives. Host adapters manage registration and lifecycle, not a second judgment implementation. Configuration failures remain explicit rather than producing superficially equivalent answers.

package/docs/adr/0003-explicit-scope-conservative-automation.md

@@ -0,0 +1,19 @@
+# 0003 — Explicit scope and conservative automation
+
+Status: Accepted
+
+## Context
+
+Repository navigation, change review and test selection involve different evidence and next actions. Broad automatic suggestions could be mistaken for complete knowledge of the repository.
+
+## Decision
+
+Expose six explicit tools: jev_ask for one combined situation, jev_ask_files for independent judgments of files, jev_find_files for discovery, jev_locate_in_file for ranges, jev_check_diff for fixed reviews and jev_select_tests for existing test plans. Hide jev_find_files in omp when its native find tool is active.
+
+Allow only one automatic run-end documentation check of a dirty tree. A flagged stale sentence can request another turn; errors do not block the host or cause an automatic review loop. JEV_TOOLS_AUTO_DOCS=0 disables the hook.
+
+Do not infer required new test scenarios, missing documentation or arbitrary companion edits from incomplete collection. Test selection and residual coverage checks describe only the discovered inventory.
+
+## Consequences
+
+Callers retain control of consequential actions and must read or execute the evidence indicated by results. A clean review is not a completeness guarantee. Automatic documentation checking targets existing sentences, not an inferred obligation to write new documentation.

package/docs/adr/0004-compiled-typed-intents.md

@@ -0,0 +1,19 @@
+# 0004 — Compile typed intents instead of accepting raw question maps
+
+Status: Accepted
+
+## Context
+
+Caller-written question wording and option sets can drift even when the intended judgment is the same. A typed declaration can enforce a consistent shape without establishing the truth of its answer.
+
+## Decision
+
+Accept typed asks and compile verify, classify, rate, decide and locate intents into canonical questions and options. Accept an array, a single intent object or its JSON representation; reject invalid intent contracts with guidance. Fix substantive option order by template and add applicable other and cannot_tell outcomes.
+
+Preserve the exact supplied claim text in verification results. Warn about negation or compound claims without silently rewriting or reversing their polarity. jev_ask verification combines issue outcomes with an exact-statement boolean cross-check.
+
+Retain free for custom bool, choice or score questions, visibly marked uncalibrated. The compiler supplies required structural safeguards but does not turn arbitrary wording into a calibrated preset.
+
+## Consequences
+
+Consumers get consistent result structure and explicit escape-hatch limits. Canonical compilation is a form and policy guarantee, not proof of better accuracy. Typed asks remain distinct from the fixed review questions described in [Evidence construction before judgment](0005-evidence-construction-before-judgment.md).

package/docs/adr/0005-evidence-construction-before-judgment.md

@@ -0,0 +1,19 @@
+# 0005 — Evidence construction before judgment
+
+Status: Accepted
+
+## Context
+
+A confident answer can still be wrong when a required dependency or the object named by a question is absent. Waiting for uncertainty before collecting context cannot repair that failure reliably.
+
+## Decision
+
+Prepare bounded discriminating evidence before judgment. Include the failing test and the code it exercises when distinguishing a bug from a wrong test; recover a named test from command output when identifiable. Add statically resolved declarations through a depth-one import closure under its own budget and report what was added or omitted. An absent or empty named part prevents its question; a uniquely resolvable orphan reference can be added before asking.
+
+For diff checks, construct before-and-after evidence units from declarations, slices, files or hunks. Use fixed outcome or pointer choices when one answer is expected and boolean matrices when multiple units can be relevant. Keep test evidence separate from risk units. Keep policy thresholds in code rather than caller-written questions.
+
+For eligible replaced member accesses, prepare isolated local-caller judgments alongside the risk matrix, using statically resolved callers and providers and including coordinated migrations. Apply the same evidence construction policy to supported Python syntax, imports and test fixtures, with missing grammar capabilities visible.
+
+## Consequences
+
+Static source evidence is never reported as execution. Import closure, local-caller collection and an empty finding list cannot prove completeness of dynamic dependencies or repository-wide safety. Required evidence that cannot fit together remains explicitly unjudged; [bounded evidence](0007-bounded-evidence-visible-limits.md) takes precedence over a plausible verdict.

package/docs/adr/0006-visible-uncertainty-constrained-controls.md

@@ -0,0 +1,21 @@
+# 0006 — Visible uncertainty and constrained controls
+
+Status: Accepted
+
+## Context
+
+Probability alone does not establish correctness, and a control can reveal missing evidence or sensitivity without identifying the right answer. Hiding those outcomes would encourage stronger conclusions than the evidence supports.
+
+## Decision
+
+Use visible verdict, unsure and abstain outcomes. Apply policy bands to leading-option probabilities, not the response's separate confidence field. Preserve missing-evidence outcomes before ordinary verdict bands and identify the piece to add.
+
+Reverse substantive choice order only for applicable ambiguous choices, keeping canonical template order otherwise. Use decoy and known-reference witnesses on supported preset matrices, not on every arbitrary caller ask. Keep controls specialized: rival hypotheses belong to decide; attribution removes a selected pointer's evidence when that pointer drives an action.
+
+In jev_ask verify, compare the issue outcome and exact-claim boolean in the same request group. Substantive disagreement, or an unknown issue outcome opposed by a strong boolean yes, becomes unsure with both values and the exact claim. A failed order check, witness or cross-check never promotes a verdict.
+
+Share result marks, visible limits and calls/cost/cache/time reporting across tools. Custom questions remain marked uncalibrated.
+
+## Consequences
+
+Controls detect a limited class of evidence or setup problems; passing them does not prove correctness. An exact boolean cannot override an issue outcome into a contradiction. Callers must distinguish unconfirmed conclusions from their own subsequent verification.

package/docs/adr/0007-bounded-evidence-visible-limits.md

@@ -0,0 +1,21 @@
+# 0007 — Bounded evidence without silent truncation
+
+Status: Accepted
+
+## Context
+
+Evidence collection, transport and display each require bounds. Silently trimming required evidence or splitting a control away from its judgment would change the question while appearing to answer it.
+
+## Decision
+
+Keep character admission limits separate from heuristic token estimates: admission does not guarantee provider acceptance. Subdivide requests only between indivisible judgment groups, keeping exact-claim cross-checks and contrastive controls together and repeating applicable witnesses. Refuse a group that cannot fit, or required pieces that cannot be admitted together, with explicit unjudged work; do not retry an identical rejected request indefinitely.
+
+Apply shared throughput and concurrency limits, bounded transport retries, per-tool call caps and session call/cost budgets. Report exhausted budgets and work not judged.
+
+Capture optional command output privately with bounded execution time and stream bookkeeping. Compress repetitive line shapes by rarity while preserving failure evidence; if it still cannot fit, use bounded passage selection before the caller's judgment. Report overlong lines, shape limits and oversized streams explicitly. The stream-size refusal occurs after execution and is not a disk cap or command sandbox. Head/tail context is not a substitute for rarity compression.
+
+Keep collection omissions and display limits visible. Distinguish a result rendered concisely from evidence that was unavailable to judgment.
+
+## Consequences
+
+A refusal is preferable to an answer about silently altered evidence. Budgeting cannot promise zero provider refusals without a provider token-counting contract. Command permissions remain those of the host, and JEV_TOOLS_ALLOW_COMMAND=0 disables the optional command path.

package/docs/adr/0008-static-test-discovery-conservative-plans.md

@@ -0,0 +1,19 @@
+# 0008 — Static test discovery and conservative execution plans
+
+Status: Accepted
+
+## Context
+
+Finding tests related to a changed unit is not the same as determining how a runner executes them. Evaluating third-party configuration during discovery would introduce unrequested execution.
+
+## Decision
+
+Discover existing tests from tracked sources, literal configuration, scripts and static imports without evaluating configuration or automatically collecting tests. Preserve runner, working directory, configuration, project and framework boundaries in separate command plans, including project options. Keep runtime and type-test evidence and commands separate.
+
+Select touched tests directly, follow statically resolved import closure through unchanged intermediates and applicable pytest fixtures, and judge remaining scenarios against changed-unit evidence. Retain tests when judgment is missing or unavailable. Use the selection threshold conservatively; when at least 80% of a file is selected, names are uncertain or counts are unknown, run the whole file.
+
+For unsupported, dynamic or unresolved runners, keep the plan unsure and identify the next manual action rather than inventing executable arguments. Residual exported-unit coverage checks apply only within the discovered inventory.
+
+## Consequences
+
+The tool returns plans and never runs them. The caller must execute the commands and inspect results. Static discovery cannot establish all repository tests or a requirement to add a new scenario; these scope limits follow [Explicit scope and conservative automation](0003-explicit-scope-conservative-automation.md).

package/docs/adr/0009-session-cache-requested-model-identity.md

@@ -0,0 +1,17 @@
+# 0009 — Session-local caching and requested-model identity
+
+Status: Accepted
+
+## Context
+
+Repeated identical judgments can reuse a result within a session, but optional commands can observe or mutate changing state. A model name in a response need not identify the implementation that actually served the request.
+
+## Decision
+
+Cache only successful non-command judgments in session memory. Include the requested model string in the cache identity along with the judgment inputs; do not persist the cache across sessions or cache command-bearing requests.
+
+Treat JEV_TOOLS_MODEL as the requested model identity. The default openjev is a moving alias. A version-shaped request string or an echoed model field does not prove that the served model is pinned. Do not claim runtime model-drift detection from that string.
+
+## Consequences
+
+Session caching avoids repeated identical work without presenting command output as immutable. Changing the requested model separates cached judgments, but cannot establish the identity or behavior of the model actually served. Cache accounting remains visible in result output.

package/docs/adr/0010-mcp-server-thin-host.md

@@ -0,0 +1,23 @@
+# 0010 - MCP server as a thin host over the same tools
+
+Status: Accepted
+
+## Context
+
+The tools were usable only inside pi and omp. Other agents (Claude Code, Claude Desktop, Kiro, Cursor, VS Code, Codex) integrate external tools through the Model Context Protocol. A separate implementation per client would duplicate evidence collection, judgment and budgets, and drift from the pi and omp behavior.
+
+## Decision
+
+Add `src/mcp/` as one more host, alongside the pi/omp entry point in `src/index.ts`:
+
+- `protocol.ts` implements JSON-RPC 2.0 dispatch for the tools capability only, with no I/O.
+- `tools.ts` calls the six existing tool factories unchanged and adapts their results, with the same `ToolDependencies`, session limits, HTTP client and configuration precedence ([ADR 0002](0002-one-http-protocol-across-hosts.md)).
+- `main.ts` is the stdio transport and the `jev-agent-tools-mcp` binary.
+
+Write the protocol by hand instead of depending on an MCP SDK, so the package keeps its single runtime dependency. Ship the binary as JavaScript compiled from `src/mcp/main.ts` into `dist/`, because Node refuses to strip TypeScript types under `node_modules`. pi and omp keep loading `src/` directly.
+
+Host-specific behavior stays out of the tools: MCP uses a generic host (`mcpHost()`), a host-neutral process runner and annotations that mark `jev_ask` as not read-only while commands are enabled. The run-end documentation check stays a pi/omp hook; MCP users call `jev_check_diff` with `check: "docs"`.
+
+## Consequences
+
+Every tool change reaches all hosts at once, and MCP tests exercise the real factories. The server must follow MCP protocol revisions itself; it supports the initialize-based versions and `server/discover`, and offers no resources or prompts. Clients decide approval and may ignore server `instructions`, so projects add [agent instructions](../agent-instructions.md) to their own instruction files. The build step is required before packing, enforced by `prepack`.

package/docs/agent-instructions.md

@@ -0,0 +1,120 @@
+# Agent instructions for MCP clients
+
+pi and OMP deliver the reading guide and discretionary Jev policy automatically. The MCP server sends the same semantic policy as its `instructions`, with MCP's explicit absence of an automatic docs hook, but clients may ignore that field. Add the generated block below to the project's instruction file so the agent can choose useful evidence tools and report their results accurately.
+
+Copy the block unchanged, or trim the optional tool table to the tools you enable. It contains no secrets and is safe to commit. Copies are not updated automatically: replace them from this page when upgrading a release.
+
+## The block
+
+<!-- BEGIN GENERATED JEV INSTRUCTIONS -->
+
+```markdown
+## Jev evidence tools (jev_* via MCP)
+
+<!-- Generated policy 2026-10-03.1 from src/texts/instructions.ts. Update this copied block from docs/agent-instructions.md on each release; pasted copies are not updated automatically. -->
+
+jev_* tools: choosing evidence and reading results.
+
+Use Jev for a bounded semantic judgment when its answer could change an open decision or focus the next inspection, and the relevant evidence is available. Use decisive reading, search or authorized execution directly when it settles the question. Exact lookup, counting and runtime causality belong to native tools. A Jev call is not a prerequisite for a conclusion, a review or task completion; no explanation is needed for choosing native tools.
+
+Before a chosen call, identify the open decision and supply only the evidence needed for a bounded question; a complete prior analysis is not required. Ask about one positive, self-contained observable fact per claim, with its sources, and show both sides of a comparison.
+- Failure: relevant output, the failing test and the implementation it exercises; output alone is a lead, not a bug-versus-wrong-test diagnosis. Include configuration or runtime evidence when the hypothesis depends on it. A static judgment does not establish runtime causality.
+- Change: current evidence and the earlier reference via base. Use the checkout/root corresponding to the work and admitted by the tool; another clone is not the same context.
+- Plan/documentation: precise observable commitments and the passages that constrain them. Local confirmation does not establish that omitted obligations were searched.
+- Selection/review: compatible inventory, references and configuration. Suggested commands are not executed commands; existing tests need not cover a new scenario. Read the diff natively for its contents, not as proof of safety or global coverage.
+
+The report begins with execution state: complete means the requested admitted work was processed; partial means some requested work remains unjudged or limited; not_judged means no admissible judgment; refused means a call-wide refusal. These states describe execution, not correctness, safety, documentation completeness or global test coverage. Static selection or conservative fallback can be useful without a Jev judgment; inspect the selection reason and remaining limits.
+
+Context identifies canonical host/server authority, requested and effective root, base and resolved reference, inventory restrictions and command execution/cwd when collected. Compare that context to your actual work before using a result. Unknown, not_collected and not_applicable are distinct, not guessed values or a substitute checkout.
+
+Each item distinguishes a judged result sourced from fresh or cache, static treatment without a Jev judgment, or unjudged work. A cached judgment is not a fresh verification. Only judged items carry a judgment measure; unjudged and static items have no invented probability or confidence. Source and treatment are independent of the probability band.
+
+Jev reads what you pass at a glance. A verdict is a lead to check before an irreversible action, not a proof. About 1 in 100 clear verdicts is wrong, and far more when the evidence is cut, from the wrong file, or depends on a file that was not passed; no mark can see that, so check the evidence yourself before you edit, delete or report done.
+
+Marks:
+- unsure: Jev does not see it clearly (yes/no between 0.20 and 0.80; a category or level under 0.85 confidence; findings between their thresholds), or a control of the call failed and the line says which. Inspect the passage or obtain the decisive file; unchanged rewording does not settle it.
+- abstain: a necessary piece is missing from what you passed; the line names it. Obtain that piece or leave the conclusion open. A further Jev call is optional when the changed evidence makes it useful.
+- "no (not shown)" or "not addressed": the file or state does not show it. That is not "false".
+- uncalibrated: no error rate has been measured for this kind of ask; read it as a hint.
+- Diagnostics: typed cause, origin, affected scope and materiality explain limits or blocking work, with referenced next actions. An uncertain judged item and work never judged are different. Inspect the named evidence or action without treating a diagnostic as a probability or a clean bill of health.
+
+Accounting separates tool invocation, HTTP attempts, questions actually sent, requested results (fresh/cache/not judged/static), cache probes (hits/requests), auxiliary controls and passage work, current reported cost and elapsed time. These counts are not interchangeable: an HTTP attempt is not a result, a cache probe is not a requested judgment, and a cached result does not imply a request. Unknown current cost means unreported, not zero or reconstructed historical cached cost. Use max_calls to bound a chosen wide ask.
+
+After an unavailable, refused or out-of-scope result, continue natively within the existing permissions; do not widen sharing or confinement to obtain a judgment. For uncertainty or missing evidence, inspect or obtain the decisive piece, or leave the conclusion open. Revisit Jev only when new evidence, a material context change or a new useful question makes the judgment useful; rewording unchanged evidence is not a reason to retry. There is no retry quota for genuinely changed evidence, and no certification is needed once decisive evidence settles the question. A reached cap or an unjudged result is not evidence of safety or zero affected tests.
+
+Report current conclusions first, then decisive evidence, origin and scope, then material reservations. Established means supported by relevant decisive evidence; a reported check remains explicitly reported, not observed execution. Distinguish native reading/execution, Jev's static judgment and testimony. A call count or global status is not proof.
+If native evidence settles the same scope and context after a Jev uncertainty, attribute the current conclusion to that evidence; old unsure or abstain results need not be recited as current reservations. A later Jev confirmation is attributed to Jev and retains its static limits. Independent reservations survive either resolution.
+Where an uncertainty actually returned by Jev remains material, explicitly say “Jev did not confirm X”, identify the missing evidence or guarantee, its known or indeterminate impact and the evidence to obtain. Preserve that reservation in the main text, summary and recommendation. Name native reservations and unjudged work as such, not as Jev uncertainty. Unresolved contradiction, stale evidence or a different checkout/base/scenario remains a reservation; the latest favorable answer does not win by default.
+Keep material limits in the main text, not only behind a link. Do not generalize a checked scenario into a universal guarantee. Separate relevant unestablished hypotheses from observations; omit irrelevant hypotheses. Explain unavailable historical causes only when material to action or requested, without inventing causality.
+Use existing history references when useful or requested; no exhaustive historical relay, persistent register or History block is required. A requested audit details available steps separately from the current state and does not reopen settled conclusions. Preserve existing traces; identify unavailable traces when they limit evidence or audit, without reconstructing evidence, executions or call counts. pi/OMP may reference an existing trace; MCP references must be client-accessible or explicitly unavailable.
+
+Ask about facts the files show, in positive sentences, with the evidence attached; do counting and searching with your text search tool or code.
+
+Evidence passed to jev_* tools leaves the machine for the configured endpoint. Review its data handling; share only authorized evidence, never secrets or credentials. Host/client approvals still apply. jev_ask commands run with normal shell permissions and no sandbox; prefer read-only commands. Tool choice does not relax quality, proof, approval or confidentiality obligations.
+
+jev_check_diff: Review a stable diff for semantic risks, stale documentation or specification drift when that review can inform an open decision. Read the diff natively when you need its contents. Choose risk, docs or spec for the question at hand; neither risk followed by docs nor a Jev review before done is required. Findings are leads within the inspected scope, not proof of global safety or completeness.
+
+MCP has no automatic run-end documentation hook. Its absence does not require manual replacement calls, including risk followed by docs. pi and OMP retain an opt-out host hook; that is an explicit automatic exception, not an agent call requirement.
+
+### Optional tool choices
+
+| Tool | Useful open decision |
+|---|---|
+| jev_ask | One bounded judgment combines a note, files, before/after evidence or command output. |
+| jev_ask_files | The same questions apply independently to many candidate files. |
+| jev_find_files | Find an entry point by behavior when the filename is unknown. |
+| jev_locate_in_file | Find a useful range in one file over 19 KB. |
+| jev_check_diff | Review a stable diff for the chosen risk, docs or spec question. |
+| jev_select_tests | Suggest commands for existing affected tests when selection can change the execution plan; it never runs them. |
+
+Use your text search tool for exact strings and known symbols, your file-name search tool for known filenames, and native reading or authorized execution for decisive evidence. Tool descriptions retain their full evidence recipes and limitations.
+```
+
+<!-- END GENERATED JEV INSTRUCTIONS -->
+
+## Where to put it
+
+| Client | File | Notes |
+|---|---|---|
+| Claude Code | `CLAUDE.md` at the project root | See [CLAUDE.md](#claudemd). `CLAUDE.local.md` for a personal, uncommitted copy. |
+| Codex CLI, and agents that read `AGENTS.md` | `AGENTS.md` at the project root | See [AGENTS.md](#agentsmd). |
+| Kiro | `.kiro/steering/jev.md` | See [Kiro steering](#kiro-steering). |
+| Cursor, VS Code, Windsurf, Claude Desktop | The client's project rules or custom instructions | Paste the block; Claude Desktop has no project file, so add it to the project's instructions in the app. |
+
+### CLAUDE.md
+
+Either paste the block into `CLAUDE.md`, or keep it in its own file and import it. Claude Code expands `@path` references in `CLAUDE.md` when it starts:
+
+```markdown
+# Project instructions
+
+@docs/jev-agent-instructions.md
+```
+
+Save the block as `docs/jev-agent-instructions.md` for that form.
+
+### AGENTS.md
+
+Paste the block under its own heading. Codex reads `AGENTS.md`; Claude Code reads it too.
+
+### Kiro steering
+
+Save as `.kiro/steering/jev.md` with front matter that includes it in every session:
+
+```markdown
+---
+inclusion: always
+---
+
+<the block>
+```
+
+## Keeping it current
+
+The versioned canonical fragments and host renderers live in [`src/texts/instructions.ts`](../src/texts/instructions.ts). Runtime guides, descriptions/guidelines, the OMP rule and this MCP block reuse them; the MCP block includes policy version, source and copy-update instructions. Thresholds continue to come from [policy constants](design.md#policy-thresholds).
+
+After changing the canonical policy, run `node scripts/generate-instructions.ts` to regenerate this block and `rules/jev-ask.md`. Run `node scripts/generate-instructions.ts --check` to reject stale generated outputs. During release verification, inspect delivery across pi/OMP/MCP for semantic parity, including the automatic pi/OMP hook versus no MCP hook; shared wording is not evidence of agent behavior. A release updates runtime/server instructions, not instruction blocks already pasted into external projects. Update those copies from this page; no synchronization with external copies is claimed.
+
+## Automatic hook and evaluation costs
+
+pi and OMP preserve the existing automatic run-end docs hook and its conditions/budget; `JEV_TOOLS_AUTO_DOCS=0` disables it. This is an explicit exception to agent-discretionary calls, not a requirement to invoke Jev, and does not certify complete documentation. MCP has no hook and no required manual replacement. In usage evaluation, record hook cost separately from discretionary calls and include both in full-task cost; no product price, budget setting or new runtime counter is introduced by this instruction policy.