jev-agent-tools 0.2.0 → 0.3.0

package/dist/tools/spec-check.js

@@ -1,12 +1,27 @@
+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 = [];
@@ -15,7 +30,7 @@ export async function runSpecCheck(deps, input) {
     let sent = 0;
     let incomplete = false;
     let emptyBase;
-    const finish = (refusal) => {
+    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`
@@ -47,7 +62,9 @@ export async function runSpecCheck(deps, input) {
                 !budget &&
                 !unchecked.length &&
                 !findings.length &&
-                emptyBase === undefined
+                emptyBase === undefined &&
+                report.items.size > 0 &&
+                [...report.items.values()].every((item) => item.treatment === "judged")
                 ? {
                     lines: [
                         {
@@ -61,55 +78,97 @@ export async function runSpecCheck(deps, input) {
             yield: {
                 calls: judgments.reduce((n, j) => n + (j.calls ?? 0), 0),
                 questions: judgments.reduce((n, j) => n + (j.questions ?? 0), 0),
-                costUsd: judgments.reduce((n, j) => n + (j.usage?.costUsd ?? 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,
             },
         });
-        return { ok: !refusal, envelope, judgments, findings };
+        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.");
+        return finish("spec_path required: no specification to check against.", "missing_required");
     if (!deps.client)
-        return finish(NOT_CONFIGURED);
+        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);
+        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.");
+        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);
+        return finish(collected.error, collected.cause ?? "git_failure");
     if (!specification.ok)
-        return finish(specification.error);
+        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.");
+        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 units = collected.units.filter((unit) => {
-        if (unit.before !== null || unit.after !== null)
-            return true;
+    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)`);
-        return false;
-    });
     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.");
+        return finish("No ### REQ-… requirements in the specification: nothing to check.", "missing_required");
     if (!collected.units.length) {
         emptyBase = base;
         return finish();
@@ -117,20 +176,24 @@ export async function runSpecCheck(deps, input) {
     if (unchecked.length) {
         unchecked.push(...prepared.requirements.map((requirement) => `${requirement.label} (changed source unavailable)`), "drift (changed source unavailable)");
     }
-    if (prepared.tableWarning)
+    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 = collected.limits.length > 0;
+    }
+    incomplete = report.missingWork;
+    const state = withEvidenceContext(prepared.state, evidenceContext);
     if (units.length + 1 > CHOICE_MAX_OPTIONS ||
-        JSON.stringify(prepared.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}).`);
+        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(prepared.state, prepared.questions, {
+    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 = {
@@ -149,6 +212,40 @@ export async function runSpecCheck(deps, input) {
         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();

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

@@ -14,11 +14,11 @@ Keep limits and thresholds in src/constants.ts. Batch questions for the same evi
 
 Enforce downward import layers, including erased type dependencies:
 
-- core/ imports core/, constants.ts, result.ts and type-only contracts from jev/types.ts.
+- 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 and result.ts.
+- 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.ts import nothing. Root integration modules and tools/ compose the layers.
+- 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.
 

package/docs/agent-instructions.md

@@ -1,54 +1,77 @@
 # Agent instructions for MCP clients
 
-pi and omp inject the jev reading guide and the `jev_ask` policy automatically. The MCP server sends the same text as its `instructions`, but clients may ignore that field. Add the block below to the project's instruction file so the agent knows when to use the tools and how to read their results.
+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 it unchanged, or trim the tool table to the tools you enable. It contains no secrets and is safe to commit.
+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)
 
-The jev_* tools send repository evidence to a judgment endpoint and return typed answers with probabilities. They complement reading, searching and running code; they do not replace them.
+<!-- 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. -->
 
-### When to use which
+jev_* tools: choosing evidence and reading results.
 
-| Tool | Use it when |
-|---|---|
-| jev_ask | One judgment combines a note, files, an earlier version (base) or a command's output. |
-| jev_ask_files | The same questions apply independently to each of many candidate files. |
-| jev_find_files | You need the entry point for a behaviour and do not know the filename. |
-| jev_locate_in_file | You need the relevant line range in one file of at least 19 KB. |
-| jev_check_diff | Changes are complete and need risk, documentation or specification review. |
-| jev_select_tests | You need the commands for existing tests affected by the changes (it does not run them). |
+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.
 
-Use ordinary search and reading for exact strings, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output.
+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.
 
-### Required habits
+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.
 
-- Before concluding that a failure is a bug in the code, a wrong test or an environment problem, or that a plan matches the documentation, pass the relevant files to jev_ask and weigh its answer against your own reading. Include both the failing test and the code it exercises.
-- Ask about facts the files show, in positive sentences, with the evidence attached.
-- Before reporting a change as done, call jev_check_diff with check "risk", then with check "docs" (MCP has no automatic documentation check). Update or justify every flagged sentence.
-- Bound wide asks with max_calls.
+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.
 
-### Reading results
+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.
 
-- A line with no mark is a verdict: a lead to check before editing, deleting or reporting done, not a proof.
-- unsure: the answer is ambiguous or a control failed. Read the passage or file the line points to, or add the file that settles it. Rewording the question does not help.
-- abstain: a necessary piece is missing; the line names it. Add that file or command and ask once.
-- "no (not shown)" or "not addressed": the evidence does not show it. That is not "false".
-- uncalibrated: no measured error rate; treat it as a hint.
-- Lines in brackets: what limited the call and the next action or parameter to use.
+Ask about facts the files show, in positive sentences, with the evidence attached; do counting and searching with your text search tool or code.
 
-### Final answers
+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.
 
-Identify every conclusion a jev_* tool marked unsure or abstain, say Jev did not confirm it, and name the evidence still needed. If you settled it by reading the decisive evidence yourself, say so and cite that evidence, separately from Jev's result.
+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.
 
-### Data
+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.
 
-Evidence passed to jev_* tools leaves the machine. Do not pass secrets, credentials or files the user has not agreed to share. jev_ask commands run with normal shell permissions and no sandbox; prefer read-only commands.
+### 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 |
@@ -88,4 +111,10 @@ inclusion: always
 
 ## Keeping it current
 
-The block restates the guide in [`src/texts/guide.ts`](../src/texts/guide.ts) and the policy in [`rules/jev-ask.md`](../rules/jev-ask.md). Thresholds are in [design](design.md#policy-thresholds). If a release changes them, the server's `instructions` change automatically; update the copied block from this page.
+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.

package/docs/design.md

@@ -6,10 +6,18 @@ The tools construct bounded evidence before asking for judgment. They preserve u
 
 Supply the discriminating evidence, not an argument about it. For comparisons, show both sides: a failing test and its implementation, or a file before and after. A bounded static import closure adds declarations before judgment where supported; it cannot establish completeness or discover relationships without imports. Commands are evidence sources, not a sandbox or a substitute for reading the output directly.
 
+Every call captures its host/server authority independently. Optional `root` admits only an exact repository top-level or live registered worktree with the same Git common directory, before content, commands, cache or HTTP. No override preserves existing cwd behavior; an invalid override never falls back. The effective context, requested/resolved base and inventory limits travel with evidence and results. See [root admission](../README.md#evidence-root).
+
+Explicit selectors define required evidence; lexical hints do not become vetoes merely because they resemble filenames. Exact directory paths cannot fall back to suffix matches. Canonical paths serialize each current/base version once, with aliases as metadata, and file admission counts identities rather than versions. Missing requirements gate their full question/control group; global-note requirements remain global. Captured output and repository files keep separate provenance.
+
+Historical-only files pass the same protected-path, ignore, regular-file and text admission checks before their base content is disclosed. Current and base versions share the distinct-file ceiling; unresolved or over-budget selectors are not retried through raw historical reads.
+
 ## Pure core, thin adapters
 
 Pure core transformations construct states, units, questions and display envelopes. Adapters own filesystem, Git, parsing and host effects; the HTTP client owns transport. Presets define fixed review questions and texts define host-facing guidance. Hosts sit on top: `src/index.ts` registers the tools with pi and omp, and `src/mcp/` serves the same tool factories to any MCP client over stdio ([ADR 0010](adr/0010-mcp-server-thin-host.md), [setup](mcp.md)). Dependency checks keep shared contracts below consumers, reject cycles and account for erased type imports. Pure path operations and erased parser types are explicit architectural exceptions. Both hosts use the same HTTP judgment protocol.
 
+The dependency-free `src/result-types.ts` defines `ResultReportV1`; `core/result-report.ts` builds reports and validates semantic invariants, while `report-schema.ts` supplies the closed transport schema and structural validator. Producers record actual observations rather than reconstructing them from rendered prose. `renderResultReport` projects the same report to self-contained text, retaining native read/runner details. pi/omp publish `details.result`; supported MCP versions publish `structuredContent.result` without introducing a second judgment policy.
+
 ## Typed intents and fixed checks
 
 Caller intents compile to typed questions with canonical options and exact statement text. Verification of one combined situation preserves the distinction between holds, contradicted, not addressed and cannot tell, with an exact-statement cross-check that cannot override missing evidence. Custom questions remain uncalibrated. Diff checks use reviewed questions over before/after evidence units; tests are evidence, not changed units to judge. A matrix asks boolean cells across units; a pointer chooses one candidate or none. Neither executes the code.
@@ -18,11 +26,15 @@ Caller intents compile to typed questions with canonical options and exact state
 
 Leading-option probability (p_max) is the probability of the most likely choice, not the response's separate confidence field. Gray bands and applicable option-order checks expose ambiguity. Missing evidence remains abstention. Preset witnesses use a decoy and a known positive reference to detect a biased setup; failed controls do not promote findings. No mark establishes that unseen evidence is complete. See [result reading](../README.md#read-the-results).
 
+Execution state and judgment band are independent: complete/partial/refused/not judged describe processing, while verdict/unsure/abstain describe admitted judgments. Every requested item is fresh, cache, static or unjudged; static/fallback decisions have no invented probability. Auxiliary controls and passage decisions do not inflate requested-result counts. Missing required controls leave the requested group unjudged. Accounting distinguishes HTTP attempts, questions sent, cache probes, current cost and elapsed time; unknown cost is never reconstructed as zero or historical cached cost. Scoped diagnostics preserve material omissions and useful conditional actions.
+
 ## Bounded work, visible limits
 
 Admission limits, request planning, rate limiting and retry bounds are distinct. Oversized evidence is refused or visibly omitted, never silently converted into an ordinary verdict. Per-invocation max_calls and session call/cost limits are separate; control and severity requests count too. Under a session USD limit, requests are admitted one at a time so each admission sees all cost reported so far. Unjudged tests stay selected. Automatic documentation review is the only run-end automation and can request at most one extra turn.
 
-Successful non-command judgments are cached only in session memory by canonical evidence, question and requested model string. Errors are not cached; command judgments bypass caching. The default openjev alias can move, and an echoed model name does not prove served-model identity. Fractional budgets bound admission, not an exact prediction of the final request's cost.
+Successful non-command judgments are cached only in session memory by canonical evidence, question and requested model string. Every judgment input, including control and passage decisions, carries admitted authority/root provenance and the resolved base when applicable; that metadata participates in both cache identity and serialized evidence admission. Identical content from different roots or base revisions cannot reuse a judgment. Errors are not cached; command judgments bypass caching. The default openjev alias can move, and an echoed model name does not prove served-model identity. Fractional budgets bound admission, not an exact prediction of the final request's cost.
+
+`src/texts/instructions.ts` is the versioned source for host policy, evidence guidance and current-state presentation. `node scripts/generate-instructions.ts` updates checked-in omp/MCP fragments; `--check` detects drift. Jev is discretionary when it can inform an open decision; native decisive evidence requires no certification call. Unchanged retries and mandatory risk/docs sequences are not recovery policy. pi/omp retain the opt-out documentation hook; MCP has no replacement obligation. Final presentation distinguishes native execution, Jev's static judgment and reported evidence, preserving independent material reservations without requiring an exhaustive history registry.
 
 ## Policy thresholds
 

package/docs/mcp.md

@@ -18,8 +18,8 @@ The server reads, per field, the environment first and then the configuration sa
 
 | Variable | Required | Meaning |
 |---|---|---|
-| `JEV_TOOLS_URL` | yes | Complete endpoint URL compatible with the Jev API format. |
-| `JEV_TOOLS_API_KEY` | yes | Bearer credential. Never printed in tool output. |
+| `JEV_TOOLS_URL` | yes | Complete endpoint URL compatible with the Jev API format. Must be `https:`; plain `http:` is accepted only for `127.0.0.1`, `::1` or `localhost`. |
+| `JEV_TOOLS_API_KEY` | yes | Bearer credential. Never printed in tool output, never passed to `jev_ask` commands, and replaced with `[redacted]` in their output. |
 | `JEV_TOOLS_MODEL` | no | Requested model, default `openjev`. |
 | `JEV_TOOLS_ROOT` | no | Repository directory when `--root` is not given. |
 | `JEV_TOOLS_MAX_CALLS`, `JEV_TOOLS_MAX_USD` | no | Session call and cost limits for this server process. |
@@ -194,7 +194,7 @@ npx -y -p jev-agent-tools jev-agent-tools-mcp --root . < /dev/null
 
 In PowerShell, run the second as `$null | npx -y -p jev-agent-tools jev-agent-tools-mcp --root .`.
 
-The second command prints `jev-agent-tools MCP server ready (root ...; endpoint configured)` on stderr and exits when stdin closes. In the client, the six tools should be listed: `jev_ask`, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff`, `jev_select_tests`. Ask the agent to run `jev_ask` with a one-line note and a yes/no question; the result ends with the calls, cost and time footer.
+The second command prints `jev-agent-tools MCP server ready (root ...; endpoint configured)` on stderr and exits when stdin closes. In the client, the six tools should be listed: `jev_ask`, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff`, `jev_select_tests`. A smoke call with a one-line note and a yes/no question reports execution, evidence context, fresh/cache/static/unjudged items, diagnostics and separate request/result accounting. This verifies integration, not model accuracy.
 
 ## From a clone
 
@@ -207,12 +207,14 @@ Then use `"command": "node"` with `"args": ["/absolute/path/to/jev-tools/dist/mc
 
 ## Differences from pi and omp
 
-- **No run-end documentation check.** It is a host hook. Before finishing, ask the agent to call `jev_check_diff` with `check: "docs"`; the [instructions](agent-instructions.md) say so.
+- **No run-end documentation check.** pi/OMP retain an automatic opt-out host hook (`JEV_TOOLS_AUTO_DOCS=0`). MCP has no hook and its absence does not require manual replacement calls, including risk followed by docs; choose a review only when it can inform an open decision.
 - **Approval is the client's.** `jev_ask` is annotated as not read-only and potentially destructive while it accepts `command`; the other five are read-only. All six are open-world because evidence goes to your endpoint. `JEV_TOOLS_ALLOW_COMMAND=0` removes `command` from the schema and makes `jev_ask` read-only.
-- **Instructions.** The reading guide and the `jev_ask` policy are sent as the server's `instructions`. Clients may ignore them, so also add the [agent instructions](agent-instructions.md) to the project.
+- **Instructions.** The full reading guide and discretionary policy are sent as the server's `instructions`, using the same canonical fragments as pi/OMP with MCP's explicit hook difference. Clients may ignore them, so also copy the versioned [agent instructions](agent-instructions.md) into the project and update the copy on release upgrades.
 - **Tool names in descriptions** refer to "your text search tool" and "your file-name search tool" instead of pi or omp tool names.
-- **Protocol.** Versions 2024-11-05 through 2025-11-25 via `initialize`, 2026-07-28 via `server/discover` and per-request `_meta`. Modern discovery supplies server identity in `_meta["io.modelcontextprotocol/serverInfo"]`; discovery and tool lists advertise `ttlMs: 0` and `cacheScope: "private"`, so clients must not share them across authorization contexts. Tools only; no resources, prompts or sampling. Cancelling a call aborts its Jev requests and command.
+- **Protocol.** Versions 2024-11-05 through 2025-11-25 use `initialize`; 2026-07-28 uses `server/discover` and per-request `_meta`. Versions 2025-06-18 and later advertise `outputSchema` and return `structuredContent.result`; 2024-11-05 and 2025-03-26 receive self-contained text only. Each request retains its negotiated version even if another request changes the session version. Only 2026-07-28 adds `resultType: "complete"` and `ttlMs: 0` / `cacheScope: "private"`; this transport completion is independent of the report's execution state. Modern discovery supplies identity in `_meta["io.modelcontextprotocol/serverInfo"]`. Expected refusals use typed reports and appropriate `isError`; unexpected server exceptions remain JSON-RPC internal errors without invented report accounting. Tools only; no resources, prompts or sampling. Cancelling a call aborts its Jev requests and command.
+- **Malformed arguments.** Input-schema violations return JSON-RPC `INVALID_PARAMS` without a result report or judgment; well-formed calls rejected by root/evidence admission retain their typed refusal report.
 - **One process, one session.** Limits, cache and counters last as long as the connection; restart the server to reset them.
+- **Per-call evidence root.** All six tools accept `root` for a registered worktree of the same repository, with the [shared admission restrictions](../README.md#evidence-root). The startup directory remains the authority; `root` is not permission to access unrelated repositories.
 - **Command shutdown.** Cancellation, command timeout, stdin closure, SIGTERM and SIGINT wait for bounded command-tree termination. On POSIX the managed group receives SIGTERM, then SIGKILL after two seconds if it remains. On Windows, the server maps ordinary MSYS descendants through the same Bash installation's process table before running the system `taskkill /T /F`; each subprocess is bounded to five seconds. Cancelled calls receive no response. This is not a sandbox: descendants that deliberately detach from the managed group or escape the tracked tree are not contained.
 
 ## Troubleshooting

package/docs/tools/jev_ask.md

@@ -14,7 +14,9 @@ Use [jev_ask_files](jev_ask_files.md) for independent answers per file. Use nati
 
 The tool assembles one JSON situation. A note appears as `state`; repository files as `files["path"]`; historical versions as `files_before["path"]`; and command evidence as `output` with `command`, `exit_code`, `timed_out`, `stdout` and `stderr`. You receive answers, not the assembled file contents or captured output. Jev reads the evidence at a glance; it does not count, calculate or infer missing dependencies. Evidence outweighs an explanation of its role.
 
-Before judgment, bounded depth-one static import closure adds supported used declarations and data files, including before/after versions when applicable. A `closure:` line records additions and gaps. This is not completeness: configuration, documentation and other flow relationships without imports must be passed explicitly. Named missing file references can be added if uniquely resolvable; unresolved or empty referenced evidence prevents the affected ask from being posed.
+Before judgment, bounded depth-one static import closure adds supported used declarations and data files, including before/after versions when applicable. A closure diagnostic records additions and gaps; it cannot establish completeness or discover relationships without imports. Explicit `files[...]` and `files_before[...]` selectors name required evidence. Ordinary lexical mentions such as `.only` or `process.env` do not create missing-file vetoes, and names printed in command output are not disk evidence. An exact path with directory segments never falls back to another file with the same basename. For abbreviated references, a uniquely matching supplied file takes precedence over inventory discovery; ambiguity is reported, not guessed.
+
+One canonical path stores each file version; lightweight aliases do not duplicate content. Current and base versions remain distinct, and the 20-file limit counts distinct file identities, not their versions. A before-only selector can load historical content without a current file. `null` denotes a proven absent base version, not unavailable evidence. Missing/empty requirements exclude their question group and its controls; a requirement in the global note applies to all groups. Numeric zero and boolean false are not empty evidence.
 
 For recognizable assertion failures, the tool attempts to attach the failing test named by the log. An unidentifiable target produces a warning; any bug-versus-wrong-test conclusion under that warning remains unproven. Pass the failing test and implementation yourself whenever possible.
 
@@ -24,10 +26,11 @@ At least one of `state`, `paths` or `command` must provide evidence.
 
 | Field | Type / default | Meaning |
 |---|---|---|
-| `state` | Optional string, at most 8,000 characters | Short request, plan or observation not shown by the files; not a place to paste files or logs. JSON object text is accepted as structured state; `files` is reserved and rejected in such a note. |
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
+| `state` | Optional string, at most 8,000 characters | Short request, plan or observation not shown by the files; not a place to paste files or logs. JSON object text is accepted, but reserved evidence keys such as `files`, `files_before`, `evidence` and `output` cannot be supplied by the note. |
 | `paths` | Optional array of nonempty strings, at most 20 | Repository-relative files to read; not recursive directory or glob triage. |
-| `base` | Optional nonempty Git ref | Add each requested file's earlier version; absent earlier files are `null`. Use `HEAD` for uncommitted before/after questions. Historical evidence counts toward admission. |
-| `command` | Optional nonempty string | Execute `bash -c` at the repository root with `CI=1`, normal shell permissions and no additional sandbox. |
+| `base` | Optional nonempty Git ref | Add historical versions for the resolved revision; only established absence is `null`. Use `HEAD` for uncommitted before/after questions. Both versions count toward serialized evidence admission. |
+| `command` | Optional nonempty string | Execute `bash -c` at the repository root with `CI=1` and without `JEV_TOOLS_API_KEY`, normal shell permissions and no additional sandbox. The configured key is replaced with `[redacted]` in captured output, with the count reported. |
 | `timeout_s` | Optional number, default 60, range 1–300 | Command timeout in seconds. |
 | `asks` | Required intent, nonempty intent array, or JSON string encoding them | Typed questions; one intent per judgment. |
 | `max_calls` | Optional non-negative integer | Limit requests including controls and output passage finding; unjudged work is reported. |
@@ -81,7 +84,7 @@ Verification distinguishes `holds`, `contradicted`, `not addressed by the state`
 
 Serialized evidence, including keys and escapes, is bounded to 80,000 characters. Oversized files/state are refused with a split suggestion, not silently shortened. Repository file confinement rejects escaping paths and internal URLs.
 
-Commands are captured in private temporary files and cleaned up. Captured streams over 64 MiB are refused after execution; this neither caps disk usage nor interrupts execution. Repeated line shapes are compressed; lines over 8,192 characters and more than 2,048 distinct shapes produce visible notices. If compression still cannot fit, bounded passage judgments retain failure details and beginning/end context with omission markers. Excessive passage work is refused with guidance to narrow the command. A timeout gives `exit_code: null` and `timed_out: true`, not success; cancellation stops without judgment. Command calls bypass caching. `JEV_TOOLS_ALLOW_COMMAND=0` disables command evidence. Missing endpoint/key refuses judgment without a chat-model fallback.
+Commands are captured in private temporary files and cleaned up. Captured streams over 64 MiB are refused after execution; this neither caps disk usage nor interrupts execution. Repeated line shapes are compressed; lines over 8,192 characters and more than 2,048 distinct shapes produce visible notices. If compression still cannot fit, bounded passage judgments retain failure details and beginning/end context with omission markers. Command output reaches this stage before immutable file/note budget refusal, including calls with base snapshots and import closure. Excessive passage work is refused with guidance to narrow the command. Reports distinguish not started, finished and unknown execution, preserve observed cwd/exit/timeout even if later processing fails, and do not equate a judgment refusal with an unexecuted command. A timeout gives `exit_code: null` and `timed_out: true`, not success; cancellation stops without judgment. Command calls bypass caching. `JEV_TOOLS_ALLOW_COMMAND=0` disables command evidence. Missing endpoint/key refuses judgment without a chat-model fallback.
 
 ## Host differences
 

package/docs/tools/jev_ask_files.md

@@ -18,6 +18,7 @@ Each admitted file is judged alone as `path` and `content`. Every ask applies to
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `paths` | Required nonempty array of nonempty strings | Repository-relative files, recursive directories or globs; at most 255 admitted files. |
 | `asks` | Required typed intent, nonempty array of intents, or JSON string encoding them | All asks apply to every admitted file. An array is the clearest form. |
 | `max_calls` | Optional non-negative integer | Request limit for this invocation; remaining files are listed unchecked. Separate from session budgets. |
@@ -65,7 +66,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 ## Results and next action
 
-Results preserve the exact statement next to each file's answer. Boolean `yes` or `no (not shown)` includes the probability of yes; intermediate probabilities between 0.20 and 0.80 are unsure. Categories and levels need a leading-option probability of at least 0.85 after applicable controls. `classify`, `rate`, `decide` and `free` are uncalibrated; sharing a display band does not establish an error rate. Failed integrity or option-order controls make clear-looking results unsure. Read the candidate file before acting. Skipped and unchecked files and bracketed limits explain missing work. See [shared result reading](../../README.md#read-the-results).
+Results preserve the exact statement next to each file's answer and distinguish fresh/cache judgments from unjudged files. Boolean `yes` or `no (not shown)` includes the probability of yes; intermediate probabilities between 0.20 and 0.80 are unsure. Categories and levels need a leading-option probability of at least 0.85 after applicable controls. `classify`, `rate`, `decide` and `free` are uncalibrated; sharing a display band does not establish an error rate. Failed integrity or option-order controls make clear-looking results unsure; missing required judgments never become fabricated probabilities. Read the candidate file before acting. Typed diagnostics and actions explain skipped/unchecked files, causes and scope. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior
 

package/docs/tools/jev_check_diff.md

@@ -18,6 +18,7 @@ Changed declarations, slices, files or hunks become before/after evidence units.
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `check` | Required `"risk"`, `"docs"` or `"spec"` | Select the preset below. |
 | `base` | Optional nonempty Git ref, default `HEAD` | Compare the current tree, including untracked files, with this revision. |
 | `spec_path` | Optional nonempty repository-relative string | Required for `spec`: Markdown specification with `### REQ-…` headings. |
@@ -36,7 +37,7 @@ For replaced member accesses, separate local-caller checks inspect statically re
 
 ### docs
 
-Judge up to 40 existing tracked Markdown sections mentioning changed code or importing source, and identify the existing sentence made false. Collection and traversal limits are visible. This is not an exhaustive detector of missing documentation, arbitrary companion edits or every stale sentence.
+Judge up to 40 existing tracked Markdown sections mentioning changed code or importing source, and identify an existing sentence that may no longer match the change. Collection and traversal limits remain material reservations in the report. This is not an exhaustive detector of missing documentation, arbitrary companion edits or every stale sentence; inspect the sentence against the code before changing it.
 
 ### spec
 
@@ -64,6 +65,8 @@ For another preset, use `{"check":"docs","base":"HEAD"}` or `{"check":"spec","ba
 
 Findings name the evidence unit, stale sentence or requirement and its probability. Fixed findings require at least 0.7. Docs probabilities from 0.2 up to 0.7 are unsure without an additional judgment; read the indicated wording. Local-caller probabilities between 0.2 and 0.7 are unsure; `cannot_tell` at least 0.3 is abstain naming the missing provider or binding. Failed witness batches remain unsure. Read flagged source, callers or documentation before editing and preserve unresolved uncertainty in reports. See [shared result reading](../../README.md#read-the-results).
 
+Structured items retain negative as well as positive review results, actual control values and fresh/cache provenance. Budget-exhausted or incomplete groups are unjudged, not negative findings. Documentation completeness limits, collection omissions and witness failures remain scoped diagnostics even when another part of the review yields usable results.
+
 ## Limits and failure behavior
 
 No findings is not proof of safety, unseen-caller coverage or complete documentation. Unjudged units, callers, sections, requirements and severity are named when request or session budgets stop work. Parser gaps and unresolved dynamic providers remain limits, not invented answers. Missing configuration refuses judgment without a chat-model fallback. Static collection is bounded and does not evaluate third-party code.

package/docs/tools/jev_find_files.md

@@ -18,6 +18,7 @@ Deterministic lexical pre-ranking and name judgments produce candidates; the too
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `goal` | Required nonempty string | Behavioral sentence with at least five content words for an unqualified entry verdict. Shorter goals are accepted but capped at unsure. |
 | `keywords` | Optional array of nonempty strings, default empty | Known identifiers or terms steering lexical ranking and excerpt selection. |
 | `scope` | Optional directory string or array of directory strings, default repository | Restrict search; an incorrect scope may yield none. |
@@ -44,7 +45,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 ## Results and next action
 
-`entry:` names the file to open first with its probability, followed by ranked related paths and a suggested read. `entry: unsure` can mean two plausible entries, order sensitivity, inconclusive excerpts or a short goal: read the leading two candidates. `entry: none` means no candidate fit the supplied evidence: rephrase the behavioral goal or widen scope. Paths and probabilities are not source text; read the files before editing. See [shared result reading](../../README.md#read-the-results).
+The report distinguishes the primary entry decision from auxiliary ranking and controls, retains actual fresh/cache provenance and supplies useful read actions. Unsure can mean two plausible entries, order sensitivity, inconclusive excerpts or a short goal: inspect the leading candidates. A judged `none` means no candidate fit the supplied evidence: clarify the behavioral goal or widen the relevant scope. An empty collection, exhausted budget or missing response is not a `none` judgment and carries no invented probability. Paths and probabilities are not source text; read the files before editing. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior