/sw-jev

description: Use Jev or optional OpenAI Decisions for bounded routing, shell-command risk, text screening and failure triage. Use for "jev", "system one", or "classify this".
argument-hint: "[doctor|setup|ask|route|task|guard|screen|failure|browse|usage]"
metadata:
  version: "3.0.1"

sw-jev — bounded decisions

These **selection** models evaluate state against questions whose answers are enumerated in advance and return probabilities. Measure latency, cost and error rates on your own fixtures before enabling routing. It cannot answer outside your schema and never writes code, prose or explanations. Run `specweave --version`: exit 0 → **CLI path**; not found → **manual path** (the same POST by hand; curl and PowerShell forms below).

The one test

**Can every possible answer be written down before the call?** Yes → Jev. No → keep it in the frontier model. That is the whole rule. Three primitives: `choice` picks one of 2–255 named options and returns probabilities plus a confidence; `noul` returns the probability a statement is true (0–1), for yes/no gates; `score` places the state on 2–10 described, ordered levels, for graded severity or risk.

What leaves the machine

Every call sends its state — prompt text, task titles and acceptance criteria, the shell command, test-output tails, screened text, page text and element names — to the configured provider (OpenRouter, TypeSafe or OpenAI) under your own key. Secret-shaped values (tokens, `--password`/`--token` flags, `KEY=value` assignments, bearer headers, URL credentials) are masked heuristically first and the count is reported, but masking is best-effort, never a guarantee.

Setup

Key in the environment: `OPENROUTER_API_KEY` (endpoint `https://openrouter.ai/api/v1/systemone`, model `jev-1.13`) or `TYPESAFE_API_KEY` (`https://api.typesafe.ai/v1/systemone`, model `jev-latest`), or `OPENAI_API_KEY` (`https://api.openai.com/v1/decisions`, model `gpt-6-luna`). `JEV_API_KEY` is a fallback for all three providers. Never print, echo, log or commit the value — report the variable **name** only. CLI: `specweave jev setup` pings live, then writes `jev.enabled: true` into `.specweave/config.json`. Manual path: confirm the variable exists without printing it (`grep -q OPENROUTER_API_KEY .env`, PowerShell `Select-String -Quiet`), then set `"jev": { "enabled": true }` in `.specweave/config.json` yourself.

OpenAI Decisions (optional)

Run `specweave jev setup --provider openai` to ping with `OPENAI_API_KEY` and enable this provider in this project. Default remains off. The CLI maps `predicate` to `noul` and validates choices, score distributions and refusals. Do not send System One's `state`/question-map wire format to OpenAI: it requires `input` and a named `questions` array with `choices` or `levels`.

Calibrate OpenAI thresholds on labeled project examples before routing work; existing Jev thresholds are not verified for this model. Refusal, timeout, malformed answers or exhausted budgets keep the caller's normal fallback. No estimate grants command permission, proves an AC complete or overrides deterministic safeguards. Requests have 40-question/512-KiB caps, a 1-MiB response cap and one total deadline. Retain request IDs and evidence hashes, never raw source contents. See the official [Decisions guide](https://developers.openai.com/api/docs/guides/decisions).

Check it works

CLI form: `specweave jev doctor`. Manual path — the same call by hand:

curl -sS https://openrouter.ai/api/v1/systemone \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"jev-1.13","state":"ping","questions":{"ok":{"type":"noul","instructions":"Is this text non-empty?"}}}'

Invoke-RestMethod -Method Post -Uri 'https://openrouter.ai/api/v1/systemone' `
  -Headers @{ Authorization = "Bearer $env:OPENROUTER_API_KEY" } -ContentType 'application/json' `
  -Body '{"model":"jev-1.13","state":"ping","questions":{"ok":{"type":"noul","instructions":"Is this text non-empty?"}}}'

Exit 4 from any `specweave jev` command means Jev is disabled, unconfigured or unreachable. That is **not** a failure: continue with your own judgement.

Route a request

`specweave jev route "add rate limiting to the upload endpoint"` returns the matching skill, the request kind, the complexity → model tier, and whether the work needs an increment, each with a confidence. Below `jev.thresholds.route` (default 0.7) the tier falls back to `opus` and you pick the skill yourself. The tier is a suggestion you act on — nothing re-routes models behind you. `specweave jev task T-NN` answers the same question for one task already in the ledger. Manual path:

curl -sS https://openrouter.ai/api/v1/systemone -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{"model":"jev-1.13","state":{"prompt":"add rate limiting to the upload endpoint"},"questions":{"complexity":{"type":"choice","instructions":"How much reasoning does an experienced engineer need to complete this task correctly?","criteria":{"trivial":"Mechanical, fully specified edit. No design decision.","moderate":"Bounded implementation with a known approach; a few files.","complex":"Needs design or investigation; ambiguous requirements."}}}}'

Commands at a glance

`doctor` (provider, key variable name, latency) · `setup` · `route "<prompt>"` · `task T-NN` (model tier for one ledger task) · `guard "<command>"` · `screen <file>` · `failure <file>` · `ask --state @s.json --questions @q.json` · `browse --goal "<goal>" --url "<url>"` (headless, allow-listed domains only, never types text Jev chose, skips pay/delete/sign-out controls unless `--allow-sensitive`) · `usage`. Each is `specweave jev <action>`; `--json` for machines. `specweave jev setup --guard-bash` writes the config flag, the `.specweave/state/jev-guard.enabled` marker and a project `PreToolUse` hook (`--no-guard-bash` removes all thre