Recorder Asset Core Decision Gate
Docs
Decision Gate Docs

Deterministic, replayable gate evaluation with auditable decisions.

Asset Core docs

Legal Citation Reference Runbook

Purpose

This runbook is the operational guide for the CourtListener legal citation reference pack in Decision Gate.

Use it for:

  1. Deterministic offline validation in CI/dev.
  2. Manual opt-in live smoke validation against CourtListener.
  3. Production-safe security posture and token handling.

Canonical Pack

  • Canonical path: references/openapi/courtlistener-legal-citation-v1/
  • Canonical OpenAPI: references/openapi/courtlistener-legal-citation-v1/openapi.json
  • Pack catalog entry: references/openapi/reference_library.json

Offline Deterministic Mode (Default)

Offline mode is the default and is required for standard CI.

Run offline legal citation suite:

dg-reason="offline-legal-citation-suite" dg-owner="dg-maintainers" dg-expires=2026-05-15
cargo test -p system-tests --features system-tests --test providers -- --exact legal_citation::legal_citation_reference_projection_first_end_to_end

Validate strict four-operation import/profile:

dg-reason="offline-strict-import-check" dg-owner="dg-maintainers" dg-expires=2026-05-15
cargo test -p system-tests --features system-tests --test providers -- --exact legal_citation::legal_citation_reference_import_strict_four_operation_profile

Validate dataset coverage contract:

dg-reason="offline-dataset-coverage-check" dg-owner="dg-maintainers" dg-expires=2026-05-15
cargo test -p system-tests --features system-tests --test providers -- --exact legal_citation::legal_citation_reference_dataset_coverage_and_semantics

Expected artifacts include:

  • legal_citation_report.json
  • tool_transcript.json
  • runpack export/verify outputs per case

Live Opt-In Mode (Manual)

Live mode is intentionally manual and not part of merge-gating CI.

Required env:

  • COURTLISTENER_LIVE=1

Optional env:

  • COURTLISTENER_BASE_URL (default https://www.courtlistener.com/api/rest/v4)
  • COURTLISTENER_LIVE_CASE_LIMIT (default 3)

Credential requirement:

  • Store the raw API token in DG local encrypted secrets as secret://courtlistener/api_token (no shell export required for live smoke).
  • Typed runtime auth applies deterministic render metadata (prefix: "Token ") before injecting the Authorization header.
  • DG secret store unlock is keyring-first. When keyring is unavailable/headless, set DECISION_GATE_SECRETS_PASSPHRASE before running secrets commands or live smoke.
  • DECISION_GATE_SECRETS_PASSPHRASE is store unlock material, not a provider token.

Initialize local encrypted secrets and store the CourtListener token:

# If keyring is unavailable/headless:
export DECISION_GATE_SECRETS_PASSPHRASE="<strong-passphrase>"
scripts/bootstrap/dg.sh secrets init
export COURTLISTENER_API_TOKEN="<raw-api-token>"
scripts/bootstrap/dg.sh secrets put \
  --tenant-id 1 \
  --namespace-id 1 \
  --name courtlistener/api_token \
  --from-env COURTLISTENER_API_TOKEN
scripts/bootstrap/dg.sh secrets preflight \
  --tenant-id 1 \
  --namespace-id 1 \
  --name courtlistener/api_token

Installed binary equivalent: replace scripts/bootstrap/dg.sh with decision-gate in the commands above.

Alternative import workflow (explicit mappings only):

scripts/bootstrap/dg.sh secrets import \
  --tenant-id 1 \
  --namespace-id 1 \
  --env-file .env \
  --map COURTLISTENER_API_TOKEN=courtlistener/api_token

Run manual live smoke:

dg-reason="manual-live-citation-smoke" dg-owner="operator" dg-expires=2026-05-15
scripts/bootstrap/dg.sh live courtlistener smoke --case-limit 3

Direct test command remains available when needed:

COURTLISTENER_LIVE=1 \
COURTLISTENER_LIVE_CASE_LIMIT=3 \
cargo test -p system-tests --features system-tests --test providers -- --exact legal_citation::legal_citation_live_opt_in_smoke

This smoke validates:

  1. Auth header binding for Authorization via secret://courtlistener/api_token.
  2. Form-encoded body behavior for citationLookup.
  3. Pass/fail mix over a bounded live subset.

Live artifact:

  • legal_citation_live_report.json

Production Security Posture

Recommended defaults for production-like usage:

  1. Keep private-network access blocked (default fail-closed).
  2. Use explicit credential bindings (secret://...) and avoid inline secrets in specs.
  3. Restrict hosts via typed runtime security policy where deployment allows.
  4. Keep retries bounded and honor backoff/rate-limit signals.

Do not relax security settings used for local fixture stubs (allow_private_networks for localhost test harness) in production deployments.

Token Handling and Redaction

  1. Do not commit tokens or secret-bearing env files.
  2. Store tokens in the local encrypted DG secret store (or enterprise secret manager).
  3. Keep CourtListener token value raw (no Token prefix in storage).
  4. Never print token values in logs or artifacts.

Runpack Interpretation

For each case, confirm:

  1. Decision outcome (pass or fail) matches expected gate semantics.
  2. runpack_verify reports pass.
  3. Evidence anchors are present and deterministic for repeated offline runs.

Fixture Refresh Procedure

Use the capture script for manual fixture updates:

Note: COURTLISTENER_API_TOKEN below is for the capture script only. It is not the typed runtime credential path used by live smoke tests.

dg-reason="manual-fixture-refresh" dg-owner="operator" dg-expires=2026-05-15
COURTLISTENER_API_TOKEN="<raw-api-token>" \
python3 scripts/reference_packs/courtlistener_capture.py

Dry-run option:

dg-reason="manual-fixture-refresh-dryrun" dg-owner="operator" dg-expires=2026-05-15
COURTLISTENER_API_TOKEN="<raw-api-token>" \
python3 scripts/reference_packs/courtlistener_capture.py --dry-run

The script updates canonical pack fixtures and mirrors them into:

  • system-tests/tests/fixtures/legal_citation/
  • examples/agentic/legal-citation-verification/