Grabadora Asset Core Puerta de Decisión
Docs
Documentos de Decision Gate

Evaluación de puertas determinista, reproducible con decisiones auditables.

Documentación de Asset Core

Manual de Referencia de Citación Legal

Propósito

Este runbook es la guía operativa para el paquete de referencia de citas legales de CourtListener en Decision Gate.

Úsalo para:

  1. Validación offline determinista en CI/dev.
  2. Validación manual de humo en vivo con opt-in contra CourtListener.
  3. Postura de seguridad segura para producción y manejo de tokens.

Paquete Canónico

  • Ruta canónica: references/openapi/courtlistener-legal-citation-v1/
  • Canonical OpenAPI: references/openapi/courtlistener-legal-citation-v1/openapi.json
  • Entrada del catálogo del paquete: references/openapi/reference_library.json

Modo Determinista Offline (Predeterminado)

El modo fuera de línea es el predeterminado y es necesario para la CI estándar.

Ejecutar suite de citación legal sin conexión:

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

Validar la importación/perfil de cuatro operaciones estrictas:

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

Validar el contrato de cobertura del conjunto de datos:

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

Se esperan artefactos que incluyen:

  • legal_citation_report.json
  • tool_transcript.json
  • runpack exportar/verificar salidas por caso

Modo de Opt-In en Vivo (Manual)

El modo en vivo es intencionalmente manual y no forma parte de la integración continua de merge-gating.

Required env:

  • COURTLISTENER_LIVE=1

Opcional env:

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

Requisito de credenciales:

  • Store the raw API token in DG local encrypted secrets as secret://courtlistener/api_token (no se requiere exportación de shell para pruebas en vivo).
  • Typed runtime auth applies deterministic render metadata (prefix: "Token ") antes de inyectar el encabezado Authorization.
  • DG secret store unlock is keyring-first. When keyring is unavailable/headless, set DECISION_GATE_SECRETS_PASSPHRASE before running secrets commands or humo en vivo.
  • DECISION_GATE_SECRETS_PASSPHRASE es material de desbloqueo de almacenamiento, no un token de proveedor.

Inicializa secretos locales encriptados y almacena el token de CourtListener:

# 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

Binario instalado equivalente: reemplazar scripts/bootstrap/dg.sh con decision-gate en los comandos anteriores.

Flujo de importación alternativo (solo mapeos explícitos):

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

Ejecutar humo en vivo manualmente:

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

El comando de prueba directa sigue disponible cuando se necesita:

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

Este humo valida:

  1. Vinculación del encabezado de autorización para Authorization a través de secret://courtlistener/api_token.
  2. Comportamiento del cuerpo codificado en formulario para citationLookup.
  3. Mezcla de aprobado/reprobado sobre un subconjunto vivo acotado.

Artifacto en vivo:

  • legal_citation_live_report.json

Postura de Seguridad en Producción

Valores predeterminados recomendados para un uso similar a la producción:

  1. Mantener el acceso a la red privada bloqueado (cerrado por defecto).
  2. Utilice enlaces de credenciales explícitos (secret://...) y evite secretos en línea en las especificaciones.
  3. Restringir hosts a través de una política de seguridad de tiempo de ejecución escrita donde el despliegue lo permita.
  4. Mantenga los reintentos limitados y respete las señales de retroceso/límite de tasa.

No relaje la configuración de seguridad utilizada para los stubs de fixture locales (allow_private_networks para el arnés de prueba localhost) en implementaciones de producción.

Manejo y Redacción de Tokens

  1. No comprometas tokens ni archivos de entorno que contengan secretos.
  2. Almacenar tokens en el almacén secreto DG local cifrado (o en el gestor de secretos empresarial).
  3. Mantener el valor del token de CourtListener en bruto (sin prefijo Token en el almacenamiento).
  4. Nunca imprimas los valores de los tokens en los registros o artefactos.

Interpretación de Runpack

Para cada caso, confirma:

  1. El resultado de la decisión (pass o fail) coincide con la semántica de puerta esperada.
  2. runpack_verify informa que ha pasado.
  3. Los anclajes de evidencia están presentes y son deterministas para ejecuciones offline repetidas.

Procedimiento de Actualización de Equipos

Utiliza el script de captura para actualizaciones manuales de accesorios:

Nota: COURTLISTENER_API_TOKEN a continuación es solo para el script de captura. No es la ruta de credenciales de tiempo de ejecución escrita utilizada por las pruebas de humo en vivo.

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

Opción de prueba en seco:

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

El script actualiza los accesorios de paquete canónicos y los refleja en:

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