jev-agent-tools 0.1.3 → 0.2.0

package/dist/tools/spec-check.js

@@ -0,0 +1,166 @@
+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 { prepareSpecCheck, readSpecJudgment, } from "../presets/spec.js";
+import { NOT_CONFIGURED } from "../texts/configuration.js";
+export async function runSpecCheck(deps, input) {
+    const started = performance.now();
+    const judgments = [];
+    const findings = [];
+    const limitations = [];
+    const unchecked = [];
+    let budget;
+    let sent = 0;
+    let incomplete = false;
+    let emptyBase;
+    const finish = (refusal) => {
+        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
+                ? {
+                    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.reduce((n, j) => n + (j.usage?.costUsd ?? 0), 0),
+                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 (!input.specPath)
+        return finish("spec_path required: no specification to check against.");
+    if (!deps.client)
+        return finish(NOT_CONFIGURED);
+    const comparison = await resolveBase(deps.exec, input.cwd, input.base, input.signal);
+    if (!comparison.ok)
+        return finish(comparison.error);
+    const base = comparison.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.");
+    const cwd = root.stdout.trim();
+    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);
+    if (!specification.ok)
+        return finish(specification.error);
+    const text = Object.values(specification.files)[0];
+    if (!text)
+        return finish("The specification is empty: nothing to check.");
+    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;
+        unchecked.push(`${unit.file} ${unit.name} (changed source unavailable)`);
+        return false;
+    });
+    const prepared = prepareSpecCheck(text, units);
+    if (!prepared.requirements.length)
+        return finish("No ### REQ-… requirements in the specification: nothing to check.");
+    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)
+        limitations.push({
+            fact: "The specification contains a Markdown table.",
+            next: "Read the table requirements: their interpretation is uncalibrated.",
+        });
+    incomplete = collected.limits.length > 0;
+    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}).`);
+    if (!units.length)
+        return finish();
+    const judgment = await deps.client.judge(prepared.state, prepared.questions, {
+        signal: input.signal,
+        ...deps.runtime.session.requestGate(),
+        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) {
+        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 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.
+- 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.
+
+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,91 @@
+# 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.
+
+Copy it unchanged, or trim the tool table to the tools you enable. It contains no secrets and is safe to commit.
+
+## The block
+
+```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.
+
+### When to use which
+
+| 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 ordinary search and reading for exact strings, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output.
+
+### Required habits
+
+- 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.
+
+### Reading results
+
+- 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.
+
+### Final answers
+
+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.
+
+### Data
+
+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.
+```
+
+## 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 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.

package/docs/design.md

@@ -8,7 +8,7 @@ Supply the discriminating evidence, not an argument about it. For comparisons, s
 
 ## 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. 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.
+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.
 
 ## Typed intents and fixed checks
 
@@ -20,7 +20,7 @@ Leading-option probability (p_max) is the probability of the most likely choice,
 
 ## 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. Unjudged tests stay selected. Automatic documentation review is the only run-end automation and can request at most one extra turn.
+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.
 
@@ -184,4 +184,4 @@ Optional native syntax parsing and file-search acceleration can be absent. Tools
 
 ## Architecture decisions
 
-See the [architecture decision records](adr/) for durable trade-offs. Start with the [README](../README.md) for installation and follow its six tool references for complete parameter contracts.
+See the [architecture decision records](adr/) for durable trade-offs. Start with the [README](../README.md) for installation and follow its six tool references for complete parameter contracts. MCP clients: [setup guide](mcp.md) and [agent instructions](agent-instructions.md).