Jev Advisory

A non-authoritative, read-only semantic advisory sidecar for Gaia workflows, backed by TypeSafe AI System One (jev-1.13.0) and grounded by structured fallback to worker-luna.

Read the complete contract and safety documentation at docs/agents/jev.md.

One-Minute Quickstart (Offline / $0 Spend)

By default, all commands execute in offline / dry-run mode ($0 spend) without requiring an API key. Run an immediate evaluation using the repository's native discovery packet fixture:

python scripts/jev_advisory.py --mode mapping --input tests/fixtures/discovery-packet-v2-valid.json

This writes an evaluation report to generated-output/jev/report.json.

Consuming the Luna Handoff

The advisory runner does NOT launch an agent, invoke external processes, or spawn sub-agents. When running offline (default), or when live confidence falls below 0.75, or budget/Flash quota is exhausted, each evaluated item includes an actionable handoff under .fallback:

{
  "candidateId": "testcontrib/test-skill",
  "name": "Test Skill",
  "status": "fallback",
  "reason": "dry_run",
  "fallback": {
    "agent": "worker-luna",
    "instruction": "Evaluate state with questions using worker-luna reasoning (dry run mode active)."
  }
}

Curators or orchestrators can inspect generated-output/jev/report.json and feed this structured context directly to Luna reasoning agents when automated sidecar advisory is unavailable, low confidence, or depleted. Route based on task complexity:

• worker-luna (medium): Standard candidate mapping, duplicate triage, and routine PR/issue review.
• worker-luna-high: High-complexity candidate evaluations, ambiguous capability taxonomies, or conflicting evidence triage.
• worker-luna-xhigh: Deep architectural review, structural ontology changes, or contested policy decisions.

Note: The advisory tool emits this structured handoff packet for consumption by the curator or harness orchestrator; it never automatically spawns fallback agents.

Usage

All commands execute in offline / dry-run mode by default ($0 spend). To enable live TypeSafe API calls, add --live (requires TYPESAFE_API_KEY exported in environment and initialized budget).

# Explicitly source repo-local ignored credentials (.gaia/jev/local.env, mode 0600):
set +x; source .gaia/jev/local.env

# Initialize local monthly budget ledger (required before first live call)
python scripts/jev_advisory.py --mode mapping --init-budget

# 1. Candidate mapping advisory (inspect discovery packet against generic shortlist)
python scripts/jev_advisory.py --mode mapping --input registry-for-review/discovery-packets/<packet>.json

# 2. Issue backlog triage (recommend duplicate status and P0-P4 priorities)
python scripts/jev_advisory.py --mode issues --input <issues.json>

# 3. Upstream change review (evaluate release diffs and capability impact)
python scripts/jev_advisory.py --mode upstream --input <findings.json>

# 4. Evidence audit triage (flag semantic anomalies in evidence descriptions)
python scripts/jev_advisory.py --mode evidence --input <evidence.json>

# 5. Meta registry audit (identify generic descriptions needing generalization)
# Uses --collect-repo to inspect canonical generic nodes directly from registry/nodes/
# Supports bounded paging via --offset (default: 0) and --max-calls
python scripts/jev_advisory.py --mode meta --collect-repo --offset 0

# 6. Steward debt preflight (operator review outside automated runtime)
gaia steward scan --json > /tmp/debt.json
python scripts/jev_advisory.py --mode steward --input /tmp/debt.json

Operational Rules

1. Non-Authoritative Sidecar: Advisory outputs never mutate registry nodes, never alter deterministic decision precedence, and never skip L4 human checkpoints.
2. Real Luna Fallback: When confidence is below 0.75, questions are ambiguous, or budget limits are reached, the runner emits a structured handoff packet for worker-luna. A fallback is an actionable handoff for Luna, not an assertion that Luna ran.
3. Gaia Steward Zero-Model Rule: Steward automated dispatches run with a strict zero-model budget. Jev advisory is strictly forbidden inside the Class A/B dispatch loop; operator preflight is permitted only outside runtime.
4. Evidence & Trust Methodology: Jev advisory does not verify URLs, does not replace HTTP liveness checks, and never modifies Trust Magnitude scores or Star Bar requirements.