jev-agent-tools 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Before 1.0.0, incompatible changes will be called out explicitly. Internal source
+modules are not a stable library API.
+
+## [Unreleased]
+
+## [0.1.3] - 2026-10-02
+
+Initial npm release candidate, under the name `jev-agent-tools`. Versions 0.1.0,
+0.1.1 and 0.1.2 were tagged but never published; their outcomes are recorded below.
+
+### Added
+
+- Six evidence-oriented tools for pi and omp: `jev_ask`, `jev_ask_files`,
+  `jev_find_files`, `jev_locate_in_file`, `jev_check_diff` and `jev_select_tests`.
+- Typed judgment intents, fixed diff checks, static test discovery and conservative
+  execution plans, with visible uncertainty, missing evidence and collection limits.
+- A single non-blocking run-end check for stale existing documentation, with an
+  option to disable it.
+- Repository-confined file evidence collection, explicit command controls and
+  session call/cost budgets. Optional commands use host permissions, not a sandbox.
+- npm extension installation for both hosts, shared result-reading guidance,
+  tool reference documentation and architecture decisions.
+- In pi, the decision policy ships with the `jev_ask` tool guidelines and is present
+  whenever `jev_ask` is active; omp retains native rule discovery.
+
+### Compatibility
+
+Requires Node.js 24 or later. Supported host baseline: pi 0.87.1 or later, or
+omp 18.4.10 or later. Install with `pi install npm:jev-agent-tools@0.1.3` or
+`omp plugin install jev-agent-tools@0.1.3`. Omp uses its Bun runtime; Node.js is also
+required for Node-based project checks. These are support baselines, not the first
+host releases to implement package installation. Later host versions are expected
+to remain compatible but are not all individually validated. Optional native
+dependencies may be unavailable on some platforms; affected tools report their
+limitations. The HTTP client is compatible with the Jev API format; configure your
+own endpoint and credentials.
+
+### Fixed
+
+- The publish workflow passes the approved tarball to npm as a local path.
+- In pi, the `jev_ask` policy appears once in the system prompt instead of twice.
+
+## [0.1.2]
+
+Tagged but never published to npm: the scoped candidate was cancelled before
+publication after the package name changed to `jev-agent-tools`.
+
+## [0.1.1]
+
+Tagged but never published to npm: the unscoped package name was rejected.
+
+## [0.1.0]
+
+Tagged but never published to npm: the publish workflow failed before upload.
+
+[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/NomenAK/jev-tools/compare/v0.1.0...v0.1.3
+[0.1.2]: https://github.com/NomenAK/jev-tools/tree/v0.1.2
+[0.1.1]: https://github.com/NomenAK/jev-tools/tree/v0.1.1
+[0.1.0]: https://github.com/NomenAK/jev-tools/tree/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NomenAK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# jev-agent-tools
+
+Six evidence-oriented tools for pi and omp, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.
+
+## Install
+
+Install through your host's package manager. The npm package is `jev-agent-tools`. It ships TypeScript sources; no separate compilation is required.
+
+### pi
+
+```sh
+pi install npm:jev-agent-tools@0.1.3
+# Project-local installation:
+pi install -l npm:jev-agent-tools@0.1.3
+```
+
+### omp
+
+```sh
+omp plugin install jev-agent-tools@0.1.3
+```
+
+### Requirements and compatibility
+
+Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
+
+## Configure
+
+Set these before starting the host, using your own endpoint and credentials:
+
+```sh
+export JEV_TOOLS_URL="${YOUR_JEV_ENDPOINT}"
+export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"
+# Optional; already the default:
+export JEV_TOOLS_MODEL="openjev"
+```
+
+`YOUR_*` placeholders are inputs you supply, not additional product settings. Configuration is read when the extension loads; restart the host after changing it.
+
+| Variable | Meaning |
+|---|---|
+| `JEV_TOOLS_URL` | Required complete endpoint URL compatible with the Jev API format. |
+| `JEV_TOOLS_API_KEY` | Required Bearer credential; configuration values are not printed in tool output. |
+| `JEV_TOOLS_MODEL` | Requested model string, default `openjev`; a moving alias, not a guarantee of served-model identity. |
+| `JEV_TOOLS_MAX_CALLS` | Session-wide non-negative safe-integer call limit; absent or empty means unlimited. Invalid values refuse requests. |
+| `JEV_TOOLS_MAX_USD` | Session-wide finite non-negative cost limit, including fractions; absent or empty means unlimited. Invalid values refuse requests. |
+| `JEV_TOOLS_ALLOW_COMMAND` | `0` disables `command` in `jev_ask`; otherwise commands run with ordinary shell permissions, without an additional sandbox. |
+| `JEV_TOOLS_AUTO_DOCS` | `0` disables the automatic run-end documentation check. |
+
+Without the endpoint or key, tools remain registered and explain the missing configuration; the automatic documentation check is disabled. There is no fallback to a chat model. Per-tool `max_calls` is separate from session limits. A model name echoed by the response does not establish which model was actually served.
+
+## Choose a tool
+
+| Tool | Choose it when |
+|---|---|
+| [jev_ask](docs/tools/jev_ask.md) | One judgment combines a note, files, earlier versions or command output. |
+| [jev_ask_files](docs/tools/jev_ask_files.md) | The same questions apply independently to each candidate file. |
+| [jev_find_files](docs/tools/jev_find_files.md) | You need an entry point for a behavioral goal and do not know its filename. In omp, use native `find` when active. |
+| [jev_locate_in_file](docs/tools/jev_locate_in_file.md) | You need the relevant range in one file of at least 19 KB. |
+| [jev_check_diff](docs/tools/jev_check_diff.md) | Completed changes need risk, existing-documentation or specification review. |
+| [jev_select_tests](docs/tools/jev_select_tests.md) | You need commands for affected existing tests, without running or collecting them. |
+
+Use native read/search tools or code for exact source text, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output. Tool reference examples use fictional repository paths and are illustrative calls, not recorded executions.
+
+## Read the results
+
+A line without a mark is a **verdict**: a lead to check before editing, deleting or reporting completion, not a proof. Probabilities concern the evidence shown, not everything in your repository.
+
+| Mark | Meaning and next action |
+|---|---|
+| `unsure` | The answer is ambiguous or a control failed. Read the indicated passage or add the specific evidence that would settle it. Do not merely reword the question. |
+| `abstain` | A necessary piece is missing. Add the named file or command evidence and ask once. |
+| `no (not shown)` / `not addressed` | The supplied evidence does not show the statement; that does not make it false. |
+| `uncalibrated` | No established error-rate calibration applies to this ask; treat it as a hint even if its probability is high. |
+| Bracketed lines | Collection, parsing, budget or display limitations, with the next manual action. |
+
+Ordinary boolean verdict bands are at or below 0.20 and at or above 0.80; category/level verdicts require a leading-option probability of at least 0.85 after applicable controls. Fixed checks and navigation tools have their own thresholds, described in their references and [design](docs/design.md).
+
+The footer reports **calls · questions · cost · cache · time**: request count, questions judged, reported USD cost, cache hits/requests and elapsed time. A tool invocation may require several requests for batching or controls. Missing cost reporting is not evidence of a free request.
+
+In a final report, explicitly identify conclusions marked `unsure` or `abstain` as unconfirmed by Jev. If subsequent reading settles them, distinguish that verification from the tool's result and cite the decisive evidence. Otherwise retain the uncertainty in your summary and recommendation.
+
+## Usage guidance for pi and omp
+
+The extension supplies the shared reading guide in both hosts. omp discovers enabled npm plugin rules during normal startup; pi does not automatically discover the package's `rules/` directory. In pi, the same decision policy is part of the `jev_ask` tool guidelines, so it is present whenever `jev_ask` is active. A forced opaque prompt override may bypass this integration; disabled tools or disabled omp rules are not covered. This README block is recommended usage guidance, not itself an installed instruction:
+
+> Before concluding that a failure is a code bug, an incorrect test or an environment problem, or that a plan matches documentation, pass the relevant files to [jev_ask](docs/tools/jev_ask.md) and weigh its answer against your own reading. Include both the failing test and the code it exercises; identify any conclusion that remains unconfirmed.
+
+## Data and command safety
+
+Repository evidence, notes and optional command output are sent to your configured endpoint. Review its data-handling policy before using confidential repositories. See [security guidance](SECURITY.md).
+
+File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions. omp uses execution approval for commands; pi does not supply an additional per-tool command approval. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
+
+## Automatic documentation check
+
+On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including untracked files. A flagged existing sentence can request one additional turn to update it or explain why it remains correct. Merely unsure sections do not trigger another turn. Missing configuration, disabled automation, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This is not a check for every missing documentation obligation.
+
+## Known limits
+
+Static evidence and probability do not prove execution, safety or completeness. Import closure cannot discover every relationship; dynamic code, unsupported syntax and optional parser failures leave explicit gaps. No findings is not proof that unseen callers or documentation are correct. Test selection considers existing discovered scenarios, not whether a new scenario must be added. Session caching cannot establish the identity or stability of a moving model alias.
+
+## Development and contributions
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [CHANGELOG.md](CHANGELOG.md), [design](docs/design.md) and [architecture decisions](docs/adr/). Development checks run locally without contacting a judgment endpoint:
+
+```sh
+npm ci --include=optional
+npm run typecheck
+npm run check:imports
+npm run lint
+npm test
+```
+
+Internal source modules are implementation details, not a stable library interface.
+
+## License
+
+[MIT](LICENSE).

package/docs/design.md

@@ -0,0 +1,187 @@
+# Design
+
+The tools construct bounded evidence before asking for judgment. They preserve uncertainty and omissions instead of treating probability as proof.
+
+## Evidence before judgment
+
+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.
+
+## 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.
+
+## 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.
+
+## Probability is not proof
+
+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).
+
+## 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.
+
+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.
+
+## Policy thresholds
+
+Values below are implementation policy, not measurement results, universal accuracy guarantees or settings to edit during a session. Boolean bands preserve weak answers as unsure; choice bands require a clear leader. Fixed findings use a separate threshold. Test selection favors retaining potentially affected tests and whole-file commands when name filtering is fragile.
+
+### Judgment policy
+
+| Constant and value | Purpose |
+|---|---|
+| `BAND_BOOL_GRAY_A = 0.2` | Leave intermediate yes/no probabilities visibly unsure rather than reporting a weak verdict. |
+| `BAND_BOOL_YES_MIN = 0.8` | Leave intermediate yes/no probabilities visibly unsure rather than reporting a weak verdict. |
+| `BAND_CHOICE_VERDICT_MIN = 0.85` | Require a clear leading option for a choice or level verdict; this does not calibrate arbitrary caller asks. |
+| `ORDER_REVERSE_BELOW = 0.85` | Recheck ambiguous substantive option order and expose order sensitivity instead of promoting it. |
+| `ORDER_DISAGREE_MIN = 0.1` | Recheck ambiguous substantive option order and expose order sensitivity instead of promoting it. |
+| `CANNOT_TELL_MIN = 0.3` | Preserve an explicit missing-evidence outcome before applying ordinary verdict bands. |
+| `FLAG_MIN = 0.7` | Use one finding threshold across fixed review checks, distinct from caller-ask bands. |
+| `SELECT_MIN = 0.5` | Prefer running an extra test over dropping a potentially affected test. |
+| `SELECT_FILE_SHARE = 0.8` | Run the whole file when filtering would save little or introduce fragile name selection. |
+| `DOCS_CHECK_MIN = 0.2` | Surface potentially stale wording for manual checking without making it a finding. |
+| `WITNESS_LURE_MAX = 0.15` | Use size-aware decoy limits to detect a biased preset setup. |
+| `WITNESS_LARGE_LURE_MAX = 0.25` | Use size-aware decoy limits to detect a biased preset setup. |
+| `WITNESS_LARGE_CHARS = 13000` | Use size-aware decoy limits to detect a biased preset setup. |
+| `COVERAGE_WITNESS_LURE_MAX = 0.2` | Apply the coverage-specific small-decoy policy separately from risk decoys. |
+| `WITNESS_ETALON_MIN = 0.7` | Check a known positive reference and enable automatic witnesses on sufficiently large matrices. |
+| `WITNESS_AUTO_MIN_CELLS = 8` | Check a known positive reference and enable automatic witnesses on sufficiently large matrices. |
+
+## Engineering bounds
+
+Collection, transport and display limits have separate purposes. The state limit counts serialized characters; byte admission and token planning are different checks. Token estimates plan batching, not guaranteed tokenizer acceptance. Command stream limits are checked after execution and do not cap disk use or stop a running command.
+
+<details>
+<summary>Collection, transport and display constants</summary>
+
+### Evidence and request bounds
+
+| Constant and value | Purpose |
+|---|---|
+| `STATE_MAX_CHARS = 80000` | Bound admitted evidence and describe the file limit consistently; character admission is not guaranteed token acceptance. |
+| `FILE_MAX_KB = 80` | Bound admitted evidence and describe the file limit consistently; character admission is not guaranteed token acceptance. |
+| `TEST_SOURCE_MAX_BYTES = 1280000` | Bound test-source reads before discovery while keeping constructed states within their separate limit. |
+| `ASK_NOTE_MAX_CHARS = 8000` | Keep a combined situation's caller note and directly requested files bounded. |
+| `ASK_MAX_FILES = 20` | Keep a combined situation's caller note and directly requested files bounded. |
+| `MAX_FILES = 255` | Bound bulk file triage and choice cardinality; pointer choices must leave room for `none`. |
+| `CHOICE_MAX_OPTIONS = 255` | Bound bulk file triage and choice cardinality; pointer choices must leave room for `none`. |
+| `SCORE_MIN_LEVELS = 2` | Require a small, concrete set of ordered scoring situations. |
+| `SCORE_MAX_LEVELS = 10` | Require a small, concrete set of ordered scoring situations. |
+| `UNIT_MAX_CHARS = 6000` | Keep changed evidence focused through slices/hunks with local context. |
+| `UNIT_CONTEXT_LINES = 8` | Keep changed evidence focused through slices/hunks with local context. |
+| `CLOSURE_MAX_CHARS = 20000` | Bound automatically added static declarations; the retained budget is not a demonstrated optimum or a completeness guarantee. |
+| `REQUEST_MAX_TOKENS = 60000` | Leave planning headroom when forming question batches, without rejecting admissible states on a heuristic alone. |
+| `QUESTION_TOKENS = 1 / 3.3` | Estimate batches only; these coefficients are not exact costs or universal tokenizer bounds. |
+| `STATE_TOKENS = 0.283` | Estimate batches only; these coefficients are not exact costs or universal tokenizer bounds. |
+| `REQUEST_BASE_TOKENS = 456` | Estimate batches only; these coefficients are not exact costs or universal tokenizer bounds. |
+| `RATE_PER_SECOND = 8` | Share throughput and in-flight limits across requests rather than mistaking concurrency for rate control. |
+| `CONCURRENCY = 8` | Share throughput and in-flight limits across requests rather than mistaking concurrency for rate control. |
+| `TIMEOUT_MS = 10000` | Bound transport waiting and retry attempts. |
+| `REQUEST_ATTEMPTS = 3` | Bound transport waiting and retry attempts. |
+| `RETRY_BASE_MS = 500` | Back off transient failures with a bounded delay and handle longer server delays explicitly. |
+| `RETRY_MAX_MS = 5000` | Back off transient failures with a bounded delay and handle longer server delays explicitly. |
+| `HTTP_ERROR_MAX_CHARS = 300` | Keep error diagnostics concise and redact credentials. |
+| `GIT_BLOB_BATCH_SIZE = 400` | Bound historical blob batches so object IDs and options fit command-line limits. |
+| `RUNNER_PACKAGE_MAX_BYTES = 65536` | Bound local runner-version metadata reads without sending package contents as judgment evidence. |
+
+### Command evidence
+
+| Constant and value | Purpose |
+|---|---|
+| `ASK_TIMEOUT_S = 60` | Give optional commands a bounded default and caller-selectable maximum. |
+| `ASK_TIMEOUT_MAX_S = 300` | Give optional commands a bounded default and caller-selectable maximum. |
+| `OUTPUT_REPEAT_MIN = 5` | Group recurring line shapes while preserving rarer failure evidence. |
+| `OUTPUT_CHUNK_CHARS = 2500` | Bound the passage-finding stage when compressed output still cannot fit. |
+| `OUTPUT_FIND_MAX_CALLS = 40` | Bound the passage-finding stage when compressed output still cannot fit. |
+| `OUTPUT_HEAD_SHARE = 0.05` | Reserve beginning/end context within the final evidence stage, not as a substitute for rarity compression. |
+| `OUTPUT_TAIL_SHARE = 0.15` | Reserve beginning/end context within the final evidence stage, not as a substitute for rarity compression. |
+| `OUTPUT_FILE_MAX_BYTES = 67108864` | Refuse oversized captured streams after execution; this is not a disk or command-execution cap. |
+| `OUTPUT_LINE_MAX_CHARS = 8192` | Bound streaming line/shape bookkeeping and report the resulting limits explicitly. |
+| `OUTPUT_SHAPE_MAX_COUNT = 2048` | Bound streaming line/shape bookkeeping and report the resulting limits explicitly. |
+| `OUTPUT_FAILURE_WINDOW_LINES = 20` | Preserve local failure neighborhoods when identifying the failing test. |
+
+### Documentation collection and result display
+
+| Constant and value | Purpose |
+|---|---|
+| `DOCS_MAX_SECTIONS = 40` | Bound the set of existing Markdown sections judged by the documentation preset. |
+| `HOOK_BUDGET_MS = 15000` | Limit automatic run-end work without turning failures into a blocking host loop. |
+| `DOCS_COLLECT_BUDGET_MS = 750` | Stop progressive collection with omissions visible; this is not a strict wall-time or coverage guarantee. |
+| `DOCS_NAME_MAX_FILES = 32` | Bound name-owner bookkeeping and per-anchor traversal rather than claiming complete repository reachability. |
+| `DOCS_ANCHOR_MAX_FILES = 32` | Bound name-owner bookkeeping and per-anchor traversal rather than claiming complete repository reachability. |
+| `CALLER_DISPLAY_MAX_SPANS = 8` | Keep local-caller evidence lines readable while preserving full details. |
+| `LIMIT_DISPLAY_MAX_PATHS = 4` | Prioritize actionable limits and documentation locations while reporting remaining counts. |
+| `DOCS_DISPLAY_MAX_SECTIONS = 5` | Prioritize actionable limits and documentation locations while reporting remaining counts. |
+
+### File finding
+
+| Constant and value | Purpose |
+|---|---|
+| `FIND_NAME_CANDIDATES = 128` | Bound the default name-ranking and content-reading stages separately. |
+| `FIND_NAME_BATCH = 64` | Bound the default name-ranking and content-reading stages separately. |
+| `FIND_FILES_READ = 20` | Bound the default name-ranking and content-reading stages separately. |
+| `FIND_READ_PER_CALL = 5` | Judge small groups with keyword-selected evidence rather than bare paths. |
+| `FIND_EXCERPT_CHARS = 3000` | Judge small groups with keyword-selected evidence rather than bare paths. |
+| `FIND_POINTER_EXCERPT_CHARS = 1500` | Judge small groups with keyword-selected evidence rather than bare paths. |
+| `FIND_POINTER_MAX = 8` | Keep the entry-point choice focused on a bounded shortlist. |
+| `FIND_NAME_GUARD_MIN = 0.9` | Preserve a strongly named leading candidate when its excerpt is less conclusive. |
+| `FIND_NAME_GUARD_TOP = 3` | Preserve a strongly named leading candidate when its excerpt is less conclusive. |
+| `FIND_CONFIRM_MIN = 0.8` | Separate entry confirmation from admission to the content shortlist. |
+| `FIND_CONTENT_MIN = 0.5` | Separate entry confirmation from admission to the content shortlist. |
+| `FIND_GOAL_MIN_WORDS = 5` | Require a behavioral sentence before presenting an unqualified entry verdict. |
+| `FIND_QUICK_CANDIDATES = 32` | Offer a smaller bounded first-pass search. |
+| `FIND_QUICK_READ = 8` | Offer a smaller bounded first-pass search. |
+| `FIND_THOROUGH_CANDIDATES = 256` | Broaden related-file exploration without promising a better entry point. |
+| `FIND_THOROUGH_READ = 40` | Broaden related-file exploration without promising a better entry point. |
+| `FIND_EXCERPT_HEAD_CHARS = 1000` | Preserve leading file context when building excerpts. |
+| `FIND_PATH_WEIGHT = 3` | Prefer lexical goal matches in paths during deterministic pre-ranking. |
+| `FIND_GREP_PAGE_SIZE = 1024` | Bound lexical-result pages and streamed excerpt reads. |
+| `FIND_READ_CHUNK_BYTES = 16384` | Bound lexical-result pages and streamed excerpt reads. |
+
+### Locating within a file
+
+| Constant and value | Purpose |
+|---|---|
+| `LOCATE_MIN_KB = 19` | Route small files to direct reading; eligibility uses file bytes, not tokenization. |
+| `LOCATE_VERDICT_MIN = 0.7` | Distinguish one clear range, two plausible ranges and a weak choice requiring narrowing. |
+| `LOCATE_GRAY_MIN = 0.4` | Distinguish one clear range, two plausible ranges and a weak choice requiring narrowing. |
+| `LOCATE_SHRINK_TOP = 3` | Retry only within a narrowed shortlist plus `none`, rather than appending arbitrary context. |
+| `LOCATE_SECTION_MAX_LINES = 150` | Keep fallback sections bounded while avoiding tiny fragments. |
+| `LOCATE_SECTION_MIN_LINES = 8` | Keep fallback sections bounded while avoiding tiny fragments. |
+| `LOCATE_WINDOW_LINES = 80` | Bound streamed windows and their display labels. |
+| `LOCATE_LABEL_MAX_CHARS = 120` | Bound streamed windows and their display labels. |
+| `LOCATE_WHOLE_MAX_CHARS = 320000` | Bound whole-file admission before using the large-file path. |
+| `LOCATE_WHOLE_MAX_BYTES = 1280000` | Bound whole-file admission before using the large-file path. |
+| `LOCATE_READ_BUFFER_BYTES = 65536` | Bound the streaming read buffer. |
+| `LOCATE_WINDOW_MAX_SERIALIZED_CHARS = 20000` | Leave serialization headroom for multi-window refinement and metadata; this is an engineering bound, not calibrated accuracy. |
+
+### Architecture policy
+
+| Constant | Purpose |
+|---|---|
+| `IMPORT_LAYERS` | Enforce allowed downward local dependencies among core, presets, adapters, HTTP client and texts, including erased type imports, while rejecting cycles. |
+
+</details>
+
+## Compatibility and limitations
+
+Optional native syntax parsing and file-search acceleration can be absent. Tools report unsupported languages, incomplete parsing and heuristic sections rather than implying precise coverage. Static test discovery reads literal configuration without evaluating third-party code, keeps runtime and type tests separate, and preserves runner/project options. It cannot infer missing test obligations. File finding ranks names then reads bounded excerpts, not every file in the repository. Large-file location uses sections or streamed window outlines with visible limits.
+
+## Glossary
+
+| Term | Definition |
+|---|---|
+| Evidence state | The JSON evidence assembled for a judgment request. |
+| Intent | The typed judgment the caller declares and code compiles into questions. |
+| Claim | One self-contained factual statement supplied for verification. |
+| Evidence unit | A changed declaration, slice, file or hunk shown with its before/after evidence. |
+| Preset | A fixed, reviewed set of questions for a specific diff check. |
+| Leading-option probability | The probability of the most likely choice after applicable controls; not the response's separate confidence field. |
+| Witness | Known-reference evidence used to check a preset setup, not a runtime guarantee. |
+| Result mark | unsure or abstain identifying a conclusion the tool did not confirm. |
+
+## 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.

package/docs/tools/jev_ask.md

@@ -0,0 +1,92 @@
+# jev_ask
+
+Ask typed questions about one situation assembled from a note, files, earlier versions and optional command output.
+
+## Use for
+
+Compare a failing test with the code it calls, check a plan against documentation, or judge behavior that depends on several pieces of evidence. Provide both sides of a comparison and the evidence that distinguishes rival explanations.
+
+## Use another tool when
+
+Use [jev_ask_files](jev_ask_files.md) for independent answers per file. Use native read or shell execution when you need source text or full output, and native search for exact matches. Use [jev_check_diff](jev_check_diff.md) for fixed review checks over a finished diff.
+
+## Evidence model
+
+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.
+
+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.
+
+## Parameters
+
+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. |
+| `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. |
+| `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. |
+
+All intents may add `about: string` naming the relevant evidence, such as `state`, `output`, `files` or `files["src/billing.ts"]`.
+
+| Intent | Fields | Meaning |
+|---|---|---|
+| `verify` | `claims: {id: statement}` | Verify one positive self-contained factual statement per claim, preserving its exact text. |
+| `classify` | `categories: {name: description}`, optional `pick: "one"` (default) or `"many"`, optional `by: string` | Pick a category or independently judge each; `by` describes the dimension. |
+| `decide` | `hypotheses: {name: statement}` | Choose among mutually exclusive rivals, including fallback outcomes. |
+| `rate` | `dimension: string`, `levels: string[]` | Choose among 2–10 concrete ordered situations on one dimension. |
+| `locate` | `target: string`, nonempty `among: string[]`, optional `count: "one"` (default) or `"many"`, optional `attribution: boolean` | Identify candidates serving the target. Attribution is supported only for `count: "one"`. |
+| `free` | `question: {type, instructions, criteria?}` | Custom uncalibrated bool, choice or score. |
+
+Nonempty maps are limited to 255 entries, including room for generated choice fallbacks. `free.instructions` must be nonempty; bool criteria optionally describe `true`/`false`, choice criteria map options to descriptions, and score criteria contain 2–10 levels. Unknown fields and invalid intent shapes are rejected. Claims should not be questions, counts, dates or compound assertions; warnings preserve your original wording. Put every ask you need in one request. Attribution makes an additional judgment without the pointed file: `attributed` means the pick moved away; `does not rest on it` means it did not. This is an evidence-dependence check, not runtime causality.
+
+## Example
+
+Illustrative call with fictional repository paths, not a recorded execution:
+
+```json
+{
+  "paths": ["src/billing.ts", "test/billing.test.ts"],
+  "base": "HEAD",
+  "asks": [
+    {
+      "intent": "verify",
+      "about": "files[\"src/billing.ts\"]",
+      "claims": {"rounding": "prorate rounds down to the whole cent"}
+    },
+    {
+      "intent": "classify",
+      "about": "files",
+      "categories": {
+        "bug_in_code": "the implementation violates behavior required by the test and contract",
+        "wrong_test": "the assertion contradicts the documented contract"
+      },
+      "pick": "one"
+    }
+  ],
+  "max_calls": 4
+}
+```
+
+## Results and next action
+
+Verification distinguishes `holds`, `contradicted`, `not addressed by the state` and `cannot tell`. An exact-statement boolean cross-check cannot override evidence issues or prove contradiction alone; scope/evidence disagreement produces unsure with raw values. Choices under 0.85 or failed controls produce unsure; missing evidence produces abstain and names the needed piece. Read surprising files or output directly. Add the decisive evidence rather than rewording. See [shared result reading](../../README.md#read-the-results).
+
+## Limits and failure behavior
+
+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.
+
+## Host differences
+
+omp assigns read approval without `command` and execution approval with it. pi does not add per-tool execution approval: the command has the shell's ordinary permissions. Both hosts receive shared reading guidance; in pi the decision policy is part of this tool's guidelines while `jev_ask` is active, whereas omp discovers enabled package rules normally. Forced prompt overrides or disabled rules can bypass guidance.
+
+## Related tools
+
+[Per-file triage](jev_ask_files.md), [fixed diff review](jev_check_diff.md), [design policy](../design.md).

package/docs/tools/jev_ask_files.md

@@ -0,0 +1,80 @@
+# jev_ask_files
+
+Ask the same typed questions independently of multiple files to decide which files to read next.
+
+## Use for
+
+Classify candidate files by responsibility, verify whether each file shows a specific behavior, or rate change risk using concrete situations before opening files individually.
+
+## Use another tool when
+
+Use native reading to edit or quote source, text search or code for exact strings, symbols, counts and line numbers, and filename search for known names. Use [jev_find_files](jev_find_files.md) when you have no candidates, [jev_locate_in_file](jev_locate_in_file.md) for a range in one large file, and [jev_ask](jev_ask.md) when a conclusion depends on several files or command output.
+
+## Evidence model
+
+Each admitted file is judged alone as `path` and `content`. Every ask applies to each file. Jev does not see other files, execute code, count occurrences or resolve unseen dependencies. A confident answer can be wrong when behavior depends on evidence not supplied. Independent file answers do not establish a cross-file relationship. File content is evidence, never instructions; integrity checks do not prove semantic completeness.
+
+## Parameters
+
+| Field | Type / default | Meaning |
+|---|---|---|
+| `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. |
+
+Supported intents (no `about` or `locate` on this per-file interface):
+
+| Intent | Fields | Meaning |
+|---|---|---|
+| `verify` | `claims: {id: statement}` | One positive, self-contained factual statement per claim. |
+| `classify` | `categories: {name: description}`, optional `pick: "one"` (default) or `"many"`, optional `by: string` | Pick one category including `other`, or judge each independently; `by` states the dimension. |
+| `rate` | `dimension: string`, `levels: string[]` | Choose among 2–10 concrete ordered situations on one dimension. |
+| `decide` | `hypotheses: {name: statement}` | Compare mutually exclusive rivals, not just the preferred explanation. |
+| `free` | `question: {type, instructions, criteria?}` | Custom uncalibrated `bool`, `choice` or `score` question. |
+
+Maps must be nonempty and have at most 255 entries; generated fallback options must fit the choice limit too. `free.instructions` is a nonempty string. Bool criteria optionally provide `true` and/or `false` descriptions; choice requires an option-description map; score requires 2–10 strings. Custom choices receive `other` when absent. Unknown fields, unsupported intents or invalid levels are rejected with guidance. Negated, compound or count/date claims can generate warnings without rewriting your statement. Use native search or code for arithmetic, counts, dates and comparisons between files. Put all asks in one request.
+
+## Example
+
+Illustrative call with fictional repository paths, not a recorded execution:
+
+```json
+{
+  "paths": ["src/auth/*.ts", "src/storage/*.ts"],
+  "asks": [
+    {
+      "intent": "verify",
+      "claims": {
+        "c1": "`content` validates authentication tokens",
+        "c2": "`content` writes to the database"
+      }
+    },
+    {
+      "intent": "classify",
+      "categories": {
+        "http": "routing and request parsing",
+        "domain": "business rules without I/O",
+        "storage": "queries and persistence"
+      },
+      "pick": "one"
+    }
+  ],
+  "max_calls": 4
+}
+```
+
+## 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).
+
+## Limits and failure behavior
+
+Build output, binaries, lockfiles, ignored untracked files, empty files and oversized files are excluded or reported. The advertised 80 KB bound derives from 80,000-character evidence admission; readers also check bytes and valid UTF-8. Kept file evidence is not silently truncated. Paths cannot escape through absolute paths, parent segments, symlinks or Git metadata; internal URLs are not files. Missing configuration refuses judgment, never falls back to a chat model. Batching and controls mean one file judgment is not a promise of exactly one HTTP request.
+
+## Host differences
+
+Judgment behavior is shared. Native search names adapt to the host. omp marks this tool read-only; pi does not automatically discover npm package rules, but the extension delivers its shared reading guide.
+
+## Related tools
+
+[Combined evidence](jev_ask.md), [file finding](jev_find_files.md), [large-file location](jev_locate_in_file.md), [design policy](../design.md).