@toolu/opencode 6.8.0

package/plugins/jev/skills/jev/references/problem-solving.md

@@ -0,0 +1,198 @@
+# Jev problem-solving patterns
+
+Load Setup + the matching example only. Evidence → focused judgment → next action.
+Reassess changed inputs; reuse unchanged evidence/questions/criteria across stages.
+Synthetic scenarios; replace observations with actual evidence in real work.
+
+Sources: TypeSafe [semantic search](https://docs.typesafe.ai/cookbooks/semantic_find.md)
+(separate ranking/existence), [citation checking](https://docs.typesafe.ai/cookbooks/citation_check.md)
+(exact quote check before context judgment), [batching](https://docs.typesafe.ai/patterns/fan-out.md)
+(independent questions, shared state). Evaluation only: [record](../evals/README.md).
+
+## Setup and failure handling
+
+Run setup + selected example in one Bash shell. Requires `curl`, `jq`, environment
+`TYPESAFE_API_KEY`; never read `.env`.
+
+```bash
+# Codex (for Claude Code use the second line instead):
+JEV="${TOOLU_CONFIG_DIR:-${CODEX_HOME:-$HOME/.codex}}/jev/jev.sh"
+# JEV="${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/jev/jev.sh"
+# Repository development, from the repository root, if not installed:
+if [ ! -x "$JEV" ]; then JEV="$PWD/plugins/jev/skills/jev/scripts/jev.sh"; fi
+JEV_EXAMPLES=$(mktemp -d)
+
+judge() {
+  local name="$1"
+  if "$JEV" ask "$JEV_EXAMPLES/$name.questions.json" \
+      -s "@$JEV_EXAMPLES/$name.state.json" --raw >"$JEV_EXAMPLES/$name.result.json"; then
+    jq '.answers' "$JEV_EXAMPLES/$name.result.json"
+  else
+    rm -f "$JEV_EXAMPLES/$name.result.json"
+    printf '%s\n' "Jev unavailable for $name; inspect the named evidence and apply the rubric manually." >&2
+    return 1
+  fi
+}
+```
+
+Failure → apply the example's rubric manually. Missing output is not a negative
+judgment. Uncertain/conflicting distributions → inspect source, gather evidence,
+or narrow question. No universal thresholds. Confidence is concentration, not
+correctness. Retain raw model/usage for evaluation; never credentials.
+
+## Search: rank excerpts and detect no answer
+
+Named retrieved excerpts: access/restoration and billing. Neither states retention.
+
+```bash
+cat > "$JEV_EXAMPLES/search.state.json" <<'JSON'
+{
+  "query": "How long are deleted project backups retained?",
+  "excerpts": {
+    "access": {"source": "docs/access.md", "text": "Administrators may restore a deleted project from a backup."},
+    "billing": {"source": "docs/billing.md", "text": "Invoices are emailed to the billing contact every month."}
+  }
+}
+JSON
+cat > "$JEV_EXAMPLES/search.questions.json" <<'JSON'
+{
+  "exists": {
+    "type": "noul",
+    "instructions": "Do the supplied `excerpts` contain an answer to `query`, including its requested retention duration?",
+    "criteria": {"true": "The duration is stated or unambiguously implied in the excerpts.", "false": "The excerpts omit the duration, even if they discuss backups or restoration."}
+  },
+  "access_relevance": {
+    "type": "score",
+    "instructions": "How well does `excerpts.access.text` answer `query`? Use only this excerpt.",
+    "criteria": ["Unrelated to deleted project backups.", "Discusses backups or restoration but omits the requested duration.", "Supplies the requested backup retention duration."]
+  },
+  "billing_relevance": {
+    "type": "score",
+    "instructions": "How well does `excerpts.billing.text` answer `query`? Use only this excerpt.",
+    "criteria": ["Unrelated to deleted project backups.", "Discusses backups or restoration but omits the requested duration.", "Supplies the requested backup retention duration."]
+  }
+}
+JSON
+judge search
+```
+
+Interpret: sort comparable Scores in code; inspect legend/distribution. A top
+rank can still be incomplete. Choice probabilities are relative, not graded
+relevance. Here, access ranks first but existence should be negative.
+Next: retrieve retention policy; never infer retention from billing frequency.
+Uncertain → inspect surrounding source/refine retrieval. API failure → manually
+confirm missing duration, then retrieve policy.
+
+## Debugging: prioritize an experiment, then reassess
+
+Supplied observations + hypotheses + experiments. Judgments prioritize tests;
+they do not prove causes.
+
+```bash
+cat > "$JEV_EXAMPLES/debug.state.json" <<'JSON'
+{
+  "observations": {"cold": "A fresh profile renders the current label.", "warm": "An existing profile still renders the old label after refresh."},
+  "hypotheses": {"cache": "A browser cache is serving stale assets.", "server": "The server serves an old build to every profile."},
+  "experiments": {"cache": "Disable the browser cache in the affected profile and reload.", "server": "Compare the deployed asset hash against the build artifact."}
+}
+JSON
+cat > "$JEV_EXAMPLES/debug.questions.json" <<'JSON'
+{
+  "next": {
+    "type": "choice",
+    "instructions": "Which supplied hypothesis best fits all `observations` and should have its `experiments` entry tried next? This is experiment prioritization, not proof of a cause.",
+    "criteria": {"cache": "The profile-dependent behavior favors stale browser assets.", "server": "The observations favor the same old deployment affecting all profiles.", "insufficient": "Neither hypothesis explains the observations, or evidence cannot distinguish them."}
+  }
+}
+JSON
+judge debug
+
+# Synthetic result of running the cache experiment; in real work supply actual output.
+jq '.observations += {"cache_disabled": "Old label persists with browser cache disabled.", "network": "Both profiles receive identical current assets.", "storage": "Only the affected profile has a saved label override in local storage."}' \
+  "$JEV_EXAMPLES/debug.state.json" > "$JEV_EXAMPLES/debug-next.state.json"
+cp "$JEV_EXAMPLES/debug.questions.json" "$JEV_EXAMPLES/debug-next.questions.json"
+judge debug-next
+```
+
+Interpret: first judgment prioritizes the cache experiment. New observations
+invalidate reuse; second should select `insufficient`. Next: test a local-storage
+hypothesis by removing/restoring only the saved override in a disposable profile.
+Confirm through reproduction before fixing. Cache still selected → inspect
+contradictory evidence, revise candidates. Uncertainty/API failure → choose the
+discriminating experiment from explicit evidence, without claiming certainty.
+
+## Planning: compare approaches against separate preferences
+
+Named alternatives + separate preferences → independent questions, one batch.
+
+```bash
+cat > "$JEV_EXAMPLES/plan.state.json" <<'JSON'
+{
+  "preferences": {"delivery": "Ship a working export this week.", "operations": "Avoid operating a new service."},
+  "approaches": {"worker": "Use the existing job worker and database; estimated two days of implementation.", "service": "Build and deploy a dedicated export service; estimated two weeks plus new monitoring."}
+}
+JSON
+cat > "$JEV_EXAMPLES/plan.questions.json" <<'JSON'
+{
+  "delivery": {
+    "type": "choice",
+    "instructions": "Which approach in `approaches` best fits `preferences.delivery`, taking the supplied estimates as assumptions rather than verified facts?",
+    "criteria": {"worker": "The existing worker approach better meets the delivery preference.", "service": "The dedicated service approach better meets the delivery preference.", "neither": "Neither approach meets it, or the supplied information cannot distinguish them."}
+  },
+  "operations": {
+    "type": "choice",
+    "instructions": "Which approach in `approaches` best fits `preferences.operations`?",
+    "criteria": {"worker": "The existing worker approach better meets the operations preference.", "service": "The dedicated service approach better meets the operations preference.", "neither": "Neither approach meets it, or the supplied information cannot distinguish them."}
+  }
+}
+JSON
+judge plan
+```
+
+Interpret: worker fits both supplied preferences. Next: verify worker capacity,
+retry semantics, and export requirements; Jev cannot validate estimates or
+feasibility. Conflicting preferences/`neither`/uncertainty → inspect tradeoffs or
+missing requirements. Reuse unchanged results at review; changed capacity →
+reassess affected questions. API failure → manually compare each preference and
+retain the technical checks.
+
+## Review: support, contradiction, or unsupported claim
+
+Named policy source + quote + claim. Check quote presence with code, then context.
+
+```bash
+cat > "$JEV_EXAMPLES/review.state.json" <<'JSON'
+{
+  "source": {"path": "docs/export-policy.md", "text": "Admins may request exports. Members cannot request exports; ask an admin to submit the request."},
+  "quote": "Members cannot request exports",
+  "claim": "Members may request exports directly."
+}
+JSON
+cat > "$JEV_EXAMPLES/review.questions.json" <<'JSON'
+{
+  "relation": {
+    "type": "choice",
+    "instructions": "How does `source.text`, read in full context, relate to `claim`? Use only the supplied source, not outside knowledge.",
+    "criteria": {"supports": "The source establishes the claim as stated, including its scope and qualifications.", "contradicts": "The source states something incompatible with the claim.", "unsupported": "The source neither establishes nor contradicts the claim, or lacks the context needed to decide."}
+  }
+}
+JSON
+if jq -e '.quote as $quote | .source.text | contains($quote)' \
+    "$JEV_EXAMPLES/review.state.json" >/dev/null; then
+  judge review
+else
+  printf '%s\n' 'Quote absent: fetch the source and repair the citation before semantic review.' >&2
+fi
+```
+
+Interpret: `contradicts` → correct claim and cite full passage. `unsupported` →
+retrieve evidence, qualify, or drop claim; unsupported does not mean false.
+`supports` concerns this excerpt, not source truth/currency. Next: verify provenance
+and product behavior with tools. Uncertain/API failure → read full passage and
+record explicit reasoning; never fabricate a Jev verdict.
+
+Clean up after retaining evaluation notes:
+
+```bash
+rm -rf "$JEV_EXAMPLES"
+```

package/plugins/jev/skills/jev/scripts/jev.sh

@@ -0,0 +1,405 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# jev — typed judgments from TypeSafe's System One API.
+# Usage: ./jev.sh <command> [options]
+#
+# Reads TYPESAFE_API_KEY from the environment (never from .env).
+
+command -v jq   >/dev/null 2>&1 || { echo "jev: jq required" >&2;   exit 1; }
+command -v curl >/dev/null 2>&1 || { echo "jev: curl required" >&2; exit 1; }
+
+JEV_URL="https://api.typesafe.ai/v1/systemone"
+DEFAULT_MODEL="jev-latest"
+
+# One check covers both unset and empty; the inline default keeps `set -u`
+# from aborting before the message can print.
+if [[ -z "${TYPESAFE_API_KEY:-}" ]]; then
+  echo "jev: TYPESAFE_API_KEY unset" >&2
+  exit 1
+fi
+if [[ "$TYPESAFE_API_KEY" == *$'\r'* || "$TYPESAFE_API_KEY" == *$'\n'* ]]; then
+  echo "jev: TYPESAFE_API_KEY must not contain line breaks" >&2
+  exit 1
+fi
+
+die() { echo "jev: $1" >&2; exit 1; }
+
+usage() {
+  cat >&2 <<'EOF'
+jev.sh <command> [options]
+
+Commands:
+  noul   <instructions>    Yes/no judgment -> probability of yes
+  choice <instructions>    Pick one option -> choice + probabilities + confidence
+  score  <instructions>    Rate on ordered levels -> score + legend + confidence
+  ask    <questions-json>  Many typed questions in ONE call (file path, or - for stdin)
+
+Shared options:
+  -s, --state VALUE   State to judge: literal text, @FILE, or - for stdin  [required]
+  -m, --model NAME    Model (default: jev-latest)
+      --id NAME       Question id in the answer map (default: q)
+      --raw           Print the whole response body instead of just .answers
+
+noul:    --true DESC / --false DESC   what a yes / a no means
+choice:  -o, --option KEY=DESC        repeatable, 2..255 (bare -o KEY sends no description)
+score:   -l, --level DESC             repeatable, 2..10, lowest level first
+EOF
+  exit 1
+}
+
+# Shared option state.
+STATE_RAW=""
+STATE_SET=false
+STATE_FROM_STDIN=false
+MODEL="$DEFAULT_MODEL"
+QID="q"
+RAW=false
+INSTRUCTIONS=""
+
+# state_json -> the JSON value for the request's `state` field.
+# A literal string stays a string. @FILE and - are sent as structured JSON only
+# when they parse as an object or an array; anything else (including a bare
+# JSON scalar such as 123) is sent as a string.
+state_json() {
+  local text file
+  case "$STATE_RAW" in
+    -)
+      text="$(cat)"
+      ;;
+    @*)
+      file="${STATE_RAW#@}"
+      [[ -r "$file" ]] || die "cannot read $file"
+      text="$(cat "$file")"
+      ;;
+    *)
+      printf '%s' "$STATE_RAW" | jq -Rs '.'
+      return
+      ;;
+  esac
+  if printf '%s' "$text" | jq -se 'length == 1 and (.[0] | type == "object" or type == "array")' >/dev/null 2>&1; then
+    printf '%s' "$text" | jq -c '.'
+  else
+    printf '%s' "$text" | jq -Rs '.'
+  fi
+}
+
+# claim_stdin — only one option may read stdin per invocation.
+claim_stdin() {
+  [[ "$STATE_FROM_STDIN" == true ]] && die "only one option can read stdin"
+  STATE_FROM_STDIN=true
+}
+
+# parse_shared OPTION ARG... -> RETURNS the consumed-arg count (0 = unrecognized).
+# Callers must invoke it as `consumed=0; parse_shared "$@" || consumed=$?` so the
+# non-zero count is read as data instead of tripping `set -e`.
+parse_shared() {
+  case "$1" in
+    -s|--state)
+      [[ $# -ge 2 ]] || die "--state needs a value"
+      STATE_RAW="$2"; STATE_SET=true
+      [[ "$2" == "-" ]] && claim_stdin
+      return 2;;
+    -m|--model)
+      [[ $# -ge 2 ]] || die "--model needs a value"
+      MODEL="$2"; return 2;;
+    --id)
+      [[ $# -ge 2 ]] || die "--id needs a value"
+      QID="$2"; return 2;;
+    --raw)
+      RAW=true; return 1;;
+  esac
+  return 0
+}
+
+require_state() { [[ "$STATE_SET" == true ]] || die "--state is required"; }
+require_instructions() { [[ -n "$INSTRUCTIONS" ]] || usage; }
+
+jev_post() (
+  local request="$1" tmp code status attempt delay retry_after
+  umask 077
+  tmp=$(mktemp -d "${TMPDIR:-/tmp}/jev.XXXXXXXX") || return 1
+  trap 'rm -rf "$tmp"' EXIT
+  # Keep the key out of process arguments; the private directory is removed on exit.
+  printf 'Authorization: Bearer %s\n' "$TYPESAFE_API_KEY" > "$tmp/auth-header"
+  for attempt in 1 2 3; do
+    status=0
+    code=$(printf '%s' "$request" | curl -sS \
+      --max-time "${JEV_TIMEOUT:-60}" \
+      --output "$tmp/body" --dump-header "$tmp/headers" --write-out '%{http_code}' \
+      -X POST "$JEV_URL" \
+      -H "@$tmp/auth-header" \
+      -H "Content-Type: application/json" -H "Accept: application/json" \
+      --data-binary @- 2>"$tmp/error") || status=$?
+    if [[ "$status" -eq 0 && "$code" == 2* ]]; then
+      cat "$tmp/body"
+      return 0
+    fi
+    # Same retry set as TypeSafe's SDK default policy: HTTP 408, 429, every
+    # 5xx (which covers the documented 529 overload), timeouts, and connection
+    # errors. curl's own --retry omits 529, so the loop lives here. Separate
+    # attempt bodies so transient errors never become answer JSON.
+    delay=$((1 << (attempt - 1)))
+    # Retry-After (seconds) wins over retry-after-ms (milliseconds, rounded up);
+    # both are documented SDK-honored headers. Waits over 60s surface the error.
+    retry_after=$(awk 'tolower($1) == "retry-after:" {gsub("\r", "", $2); print $2}' "$tmp/headers")
+    if [[ ! "$retry_after" =~ ^[0-9]+$ ]]; then
+      retry_after=$(awk 'tolower($1) == "retry-after-ms:" {gsub("\r", "", $2); print $2}' "$tmp/headers")
+      if [[ "$retry_after" =~ ^[0-9]+$ ]]; then
+        # More than 8 digits is already past the 60s ceiling; skip the arithmetic
+        # so an absurd header cannot overflow into a negative delay.
+        if [[ ${#retry_after} -gt 8 ]]; then
+          retry_after=61
+        else
+          retry_after=$(( (10#$retry_after + 999) / 1000 ))
+        fi
+      else
+        retry_after=""
+      fi
+    fi
+    if [[ "$retry_after" =~ ^[0-9]+$ ]]; then
+      if [[ ${#retry_after} -gt 2 ]] || ((10#$retry_after > 60)); then
+        break
+      fi
+      ((10#$retry_after <= delay)) || delay=$((10#$retry_after))
+    fi
+    [[ "$attempt" -lt 3 ]] || break
+    # $code is curl's %{http_code}: three digits, or 000 when no status line
+    # arrived (retried as a connection error whatever the exit status).
+    # Connection-level failures carry curl's own exit status instead:
+    # 7 (connect), 28 (timeout), 35 (TLS handshake), 52 (empty reply),
+    # 55 (send), 56 (receive) — the SDK retries these as connection errors.
+    case "$status:$code" in
+      0:408|0:429|0:5[0-9][0-9]|0:000|7:*|28:*|35:*|52:*|55:*|56:*) sleep "$delay";;
+      *) break;;
+    esac
+  done
+  [[ ! -s "$tmp/error" ]] || cat "$tmp/error" >&2
+  [[ ! -s "$tmp/body" ]] || cat "$tmp/body" >&2
+  [[ "$status" -ne 0 ]] || status=22
+  return "$status"
+)
+
+# evaluate QUESTIONS_JSON — send the request and print the answers.
+# An HTTP failure propagates: the API's error body goes to stderr and the exit
+# status is curl's own (22 for an error response, 28 for a timeout).
+evaluate() {
+  local questions="$1" state body out status
+  # Resolved in its own statement: a failure inside state_json exits the command
+  # substitution's subshell, and only an explicit check propagates that here.
+  state="$(state_json)" || exit $?
+  body=$(printf '%s\n%s\n' "$state" "$questions" | jq -sc --arg model "$MODEL" \
+    '{state: .[0], model: $model, questions: .[1]}')
+
+  set +e
+  out="$(jev_post "$body")"
+  status=$?
+  set -e
+  if [[ "$status" -ne 0 ]]; then
+    [[ -n "$out" ]] && printf '%s\n' "$out" >&2
+    exit "$status"
+  fi
+
+  # Never let a malformed success response be consumed as a false/no judgment.
+  printf '%s\n%s\n' "$questions" "$out" | jq -se '
+    def probability: type == "number" and . >= 0 and . <= 1;
+    def tokens: type == "number" and . >= 0 and . == floor;
+    def distribution($keys):
+      type == "object" and keys == ($keys | sort) and
+      all(.[]; probability) and (([.[]] | add) - 1 | fabs) < 0.000001;
+    length == 2 and
+    (.[0] as $questions | .[1] as $response | $response.answers as $answers |
+      ($response.model | type == "string" and length > 0) and
+      ($response.usage.input_tokens | tokens) and ($response.usage.output_tokens | tokens) and
+      ($answers | type == "object") and
+      (($questions | keys) == ($answers | keys)) and
+      all($questions | to_entries[];
+        . as $q | $answers[$q.key] as $a |
+        $a.type == $q.value.type and
+        if $a.type == "noul" then ($a.noul | probability)
+        elif $a.type == "choice" then
+          ($a.confidence | probability) and
+          ($a.probabilities | distribution($q.value.criteria | keys)) and
+          ($q.value.criteria | has($a.choice))
+        elif $a.type == "score" then
+          [range($q.value.criteria | length) | tostring] as $levels |
+          ($a.confidence | probability) and ($a.score | type == "number") and
+          $a.score >= 0 and $a.score <= ($q.value.criteria | length) - 1 and
+          ($a.legend | type == "object" and keys == ($levels | sort)) and
+          ($a.probabilities | distribution($levels))
+        else false end))
+  ' >/dev/null 2>&1 || die "invalid response: expected a typed answer for every question"
+
+  if [[ "$RAW" == true ]]; then
+    printf '%s\n' "$out" | jq '.'
+  else
+    printf '%s\n' "$out" | jq -c '.answers'
+  fi
+}
+
+# ── noul ────────────────────────────────────────────────────
+cmd_noul() {
+  local true_desc="" false_desc="" consumed
+
+  while [[ $# -gt 0 ]]; do
+    consumed=0
+    parse_shared "$@" || consumed=$?
+    if [[ "$consumed" -gt 0 ]]; then shift "$consumed"; continue; fi
+    case "$1" in
+      --true)  [[ $# -ge 2 ]] || die "--true needs a value"
+               true_desc="$2"; shift 2;;
+      --false) [[ $# -ge 2 ]] || die "--false needs a value"
+               false_desc="$2"; shift 2;;
+      -*)      die "unknown option: $1";;
+      *)       [[ -z "$INSTRUCTIONS" ]] || die "unexpected argument: $1"
+               INSTRUCTIONS="$1"; shift;;
+    esac
+  done
+
+  require_instructions
+  require_state
+
+  # criteria carries only the side(s) actually described, and is omitted
+  # entirely when neither was.
+  local question
+  question=$(jq -nc \
+    --arg id "$QID" \
+    --arg instructions "$INSTRUCTIONS" \
+    --arg t "$true_desc" \
+    --arg f "$false_desc" \
+    '((if $t == "" then {} else {"true": $t} end)
+      + (if $f == "" then {} else {"false": $f} end)) as $criteria
+     | {($id): ({type: "noul", instructions: $instructions}
+                + (if ($criteria | length) > 0 then {criteria: $criteria} else {} end))}')
+  evaluate "$question"
+}
+
+# ── choice ──────────────────────────────────────────────────
+cmd_choice() {
+  local criteria='{}' consumed key desc
+
+  while [[ $# -gt 0 ]]; do
+    consumed=0
+    parse_shared "$@" || consumed=$?
+    if [[ "$consumed" -gt 0 ]]; then shift "$consumed"; continue; fi
+    case "$1" in
+      -o|--option)
+        [[ $# -ge 2 ]] || die "--option needs a value"
+        key="${2%%=*}"
+        [[ -n "$key" ]] || die "--option needs a KEY (KEY=DESCRIPTION)"
+        # A bare KEY sends null — the API's documented "no extra detail" form.
+        # A repeated KEY keeps its original position and takes the last value.
+        if [[ "$2" == *=* ]]; then
+          desc="${2#*=}"
+          criteria=$(jq -c --arg k "$key" --arg d "$desc" '. + {($k): $d}' <<<"$criteria")
+        else
+          criteria=$(jq -c --arg k "$key" '. + {($k): null}' <<<"$criteria")
+        fi
+        shift 2;;
+      -*) die "unknown option: $1";;
+      *)  [[ -z "$INSTRUCTIONS" ]] || die "unexpected argument: $1"
+          INSTRUCTIONS="$1"; shift;;
+    esac
+  done
+
+  require_instructions
+  require_state
+  [[ "$(jq 'length' <<<"$criteria")" -ge 2 ]] || die "choice needs at least 2 options"
+  # The API accepts up to 255 options per Choice.
+  [[ "$(jq 'length' <<<"$criteria")" -le 255 ]] || die "choice accepts at most 255 options"
+
+  local question
+  question=$(jq -nc \
+    --arg id "$QID" \
+    --arg instructions "$INSTRUCTIONS" \
+    --argjson criteria "$criteria" \
+    '{($id): {type: "choice", instructions: $instructions, criteria: $criteria}}')
+  evaluate "$question"
+}
+
+# ── score ───────────────────────────────────────────────────
+cmd_score() {
+  local levels='[]' consumed
+
+  while [[ $# -gt 0 ]]; do
+    consumed=0
+    parse_shared "$@" || consumed=$?
+    if [[ "$consumed" -gt 0 ]]; then shift "$consumed"; continue; fi
+    case "$1" in
+      -l|--level)
+        [[ $# -ge 2 ]] || die "--level needs a value"
+        # Order is the rubric: levels stay in the order they were given.
+        levels=$(jq -c --arg l "$2" '. + [$l]' <<<"$levels")
+        shift 2;;
+      -*) die "unknown option: $1";;
+      *)  [[ -z "$INSTRUCTIONS" ]] || die "unexpected argument: $1"
+          INSTRUCTIONS="$1"; shift;;
+    esac
+  done
+
+  require_instructions
+  require_state
+  [[ "$(jq 'length' <<<"$levels")" -ge 2 ]] || die "score needs at least 2 levels"
+  # The API accepts up to 10 levels per Score.
+  [[ "$(jq 'length' <<<"$levels")" -le 10 ]] || die "score accepts at most 10 levels"
+
+  local question
+  question=$(jq -nc \
+    --arg id "$QID" \
+    --arg instructions "$INSTRUCTIONS" \
+    --argjson levels "$levels" \
+    '{($id): {type: "score", instructions: $instructions, criteria: $levels}}')
+  evaluate "$question"
+}
+
+# ── ask ─────────────────────────────────────────────────────
+# Many typed questions against one state, in a single request. Jev ingests the
+# state once and answers every question in parallel, so this is the cheap way
+# to ask several things — including speculative ones the caller may discard.
+cmd_ask() {
+  local src="" consumed text questions
+
+  while [[ $# -gt 0 ]]; do
+    # ask answers under the ids in the payload, so --id would name nothing.
+    [[ "$1" == "--id" ]] && die "ask takes its question ids from the payload; --id does not apply"
+    consumed=0
+    parse_shared "$@" || consumed=$?
+    if [[ "$consumed" -gt 0 ]]; then shift "$consumed"; continue; fi
+    case "$1" in
+      # A lone dash is the stdin source, not an option.
+      -)  [[ -z "$src" ]] || die "unexpected argument: -"
+          src="-"; claim_stdin; shift;;
+      -*) die "unknown option: $1";;
+      *)  [[ -z "$src" ]] || die "unexpected argument: $1"
+          src="$1"; shift;;
+    esac
+  done
+
+  [[ -n "$src" ]] || usage
+  require_state
+
+  if [[ "$src" == "-" ]]; then
+    text="$(cat)"
+  else
+    [[ -r "$src" ]] || die "cannot read $src"
+    text="$(cat "$src")"
+  fi
+
+  questions="$(printf '%s' "$text" | jq -sc 'if length == 1 then .[0] else error("expected one questions object") end' 2>/dev/null)" || die "invalid JSON in $src"
+  [[ "$(jq -r 'type' <<<"$questions")" == "object" ]] || die "questions must be a JSON object"
+  [[ "$(jq 'length' <<<"$questions")" -ge 1 ]] || die "questions must not be empty"
+
+  evaluate "$questions"
+}
+
+# ── dispatch ────────────────────────────────────────────────
+[[ $# -gt 0 ]] || usage
+command="$1"; shift
+case "$command" in
+  noul)   cmd_noul "$@";;
+  choice) cmd_choice "$@";;
+  score)  cmd_score "$@";;
+  ask)    cmd_ask "$@";;
+  -h|--help|help) usage;;
+  *)      echo "jev: unknown command: $command" >&2; usage;;
+esac

package/plugins/jira/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "jira",
+  "version": "6.8.0",
+  "description": "Jira issue search and workflow from the session via a REST wrapper (skill + bash). Cloud + Server/DC, read and safe writes. Standalone, no dependencies.",
+  "author": {
+    "name": "Falconiere Barbosa",
+    "email": "hello@falconiere.io"
+  },
+  "homepage": "https://github.com/falconiere/toolu",
+  "repository": "https://github.com/falconiere/toolu.git",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "jira",
+    "atlassian",
+    "skills"
+  ]
+}

package/plugins/jira/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "jira",
+  "version": "6.8.0",
+  "description": "Jira issue search and workflow from the session via a REST wrapper (skill + bash). Cloud + Server/DC, read and safe writes. Standalone, no dependencies.",
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/jira/README.md

@@ -0,0 +1,42 @@
+# jira
+
+Jira issue search and workflow from the session via a REST wrapper — a skill plus bash. Cloud + Server/DC, read and safe writes.
+
+## Install
+
+```
+/plugin install jira@toolu
+```
+
+Standalone, no dependencies.
+
+## What it provides
+
+- **`jira` skill** — work a ticket without leaving the session: JQL search, read/create/comment/transition/assign issues, plus boards, sprints, worklogs, projects, users, and attachments, with a `raw` verb for any endpoint. Triggers on Jira mentions, JQL, issue keys like `ABC-123`, a pasted `*.atlassian.net/browse/...` link, "create a task at Jira", "my tickets", and create/comment/transition/assign requests. **Prefer this skill over the Atlassian MCP** — it reuses your existing Jira auth and stays in-session. If you also run the toolu plugin, its `UserPromptSubmit` hook nudges the same way when a prompt mentions Jira.
+- **`plan` family** — decomposes non-trivial ticket work into small, individually verifiable steps and tracks them in a ledger.
+
+## Plans
+
+Read-only lookups run directly. Anything that **mutates** a ticket, or needs two or more calls, is planned first:
+
+```
+jira.sh plan init ABC-123                 # scaffold the host-native Jira plan path
+jira.sh plan run <DOC> [--step <id>]      # run each step's check, update the ledger
+jira.sh plan status ABC-123               # summary
+```
+
+Each step carries a `check` — a shell command that exits 0 **only when Jira itself reflects the change** (`"$JIRA" issue get ABC-123 --lean | jq -e '.status=="Done"'`). A step is green because Jira agrees, not because the agent said so. `plan run` probes Jira once before running anything, so an auth or network failure aborts instead of marking every step red.
+
+The ledger is written to `<repo>/.claude/tmp/plan-ledger/jira-<KEY>.json` on
+Claude or `<repo>/.codex/tmp/plan-ledger/jira-<KEY>.json` on Codex. It is
+deliberately **not** the branch ledger: toolu's push gate only reads
+`<branch-slug>.json`, so a pending Jira step can never block `git push`.
+
+## The Jira API
+
+The skill drives `scripts/jira.sh`, a bash wrapper over the Jira REST API (Cloud and Server/Data Center).
+
+- **Easiest** — if the [`jira` CLI](https://github.com/ankitpokhrel/jira-cli) is configured (`jira init`), the plugin reuses its login automatically (server + login from `~/.config/.jira/.config.yml`, token from the OS keyring). No extra setup.
+- **Or set environment variables** (these always take precedence; never a `.env` file): `JIRA_BASE_URL` (required), then either `JIRA_PAT` (Bearer) or `JIRA_EMAIL` + `JIRA_API_TOKEN` (basic). Set `JIRA_API_VERSION=2` for Server/Data Center.
+
+When nothing is configured the plugin prints a short, friendly setup prompt and exits.