Manual de Referència de Citació Legal

Propòsit

Aquest llibre d’execució és la guia operativa per al paquet de referència de citacions legals de CourtListener a Decision Gate.

Utilitzeu-ho per:

1. Validació offline determinista en CI/dev.
2. Validació manual d’opt-in en viu de fum contra CourtListener.
3. Postura de seguretat segura per a la producció i gestió de tokens.

Paquet Canònic

• Camí canònic: references/openapi/courtlistener-legal-citation-v1/
• Canonical OpenAPI: references/openapi/courtlistener-legal-citation-v1/openapi.json
• Entrada del catàleg de paquets: references/openapi/reference_library.json

Mode Determinista Offline (Per Defecte)

El mode fora de línia és el predeterminat i és necessari per al CI estàndard.

Executar suite de citació legal offline:

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

Valida l’import/perfil de quatre operacions estrictament:

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

Valida el contracte de cobertura del conjunt de dades:

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

S’esperen artefactes que inclouen:

• legal_citation_report.json
• tool_transcript.json
• exportar/verify sortides runpack per cas

Mode d’Opt-In en Directe (Manual)

El mode en viu és intencionadament manual i no forma part del CI de fusió-gating.

Required env:

• COURTLISTENER_LIVE=1

Opcional env:

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

Requisit de credencials:

• Store the raw API token in DG local encrypted secrets as secret://courtlistener/api_token (no cal exportar a la shell per a fum en viu).
• Typed runtime auth applies deterministic render metadata (prefix: "Token ") abans d’injectar l’encapçalament Authorization.
• DG secret store unlock is keyring-first. When keyring is unavailable/headless, set DECISION_GATE_SECRETS_PASSPHRASE before running secrets commands or fum en viu.
• DECISION_GATE_SECRETS_PASSPHRASE és material d desbloqueig d’emmagatzematge, no un token de proveïdor.

Inicialitza secrets xifrats locals i emmagatzema 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

Equivalent binari instal·lat: substituïu scripts/bootstrap/dg.sh per decision-gate en les ordres anteriors.

Flux d’importació alternatiu (només mapeigs explícits):

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

Executar fum en viu manualment:

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 comandament de prova directa continua disponible quan sigui necessari:

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

Aquest fum valida:

1. Vincle de capçalera d’autenticació per a Authorization a través de secret://courtlistener/api_token.
2. Comportament del cos codificat en formulari per a citationLookup.
3. Mescla de passar/fallar sobre un subconjunt viu limitat.

Artifact en viu:

• legal_citation_live_report.json

Postura de Seguretat en la Producció

Valors per defecte recomanats per a un ús semblant a la producció:

1. Mantingueu l’accés a la xarxa privada bloquejat (per defecte, tancat per fallada).
2. Utilitzeu vinculacions de credencials explícites (secret://...) i eviteu secrets en línia en les especificacions.
3. Restricció d’amfitrions mitjançant una política de seguretat en temps d’execució escrita on el desplegament ho permeti.
4. Mantingueu els reintents limitats i respecteu els senyals de retrocés/límits de taxa.

No relaxeu les configuracions de seguretat utilitzades per a les simulacions locals (allow_private_networks per a l’entorn de proves localhost) en les implementacions de producció.

Gestió de Tokens i Redacció

1. No comprometis fitxers d’entorn que continguin tokens o secrets.
2. Emmagatzemar tokens a la botiga secreta DG xifrada local (o gestor de secrets de l’empresa).
3. Mantingueu el valor del token de CourtListener en brut (sense el prefix Token en l’emmagatzematge).
4. Mai imprimeix els valors dels tokens en registres o artefactes.

Interpretació de Runpack

Per a cada cas, confirma:

1. El resultat de la decisió (pass o fail) coincideix amb la semàntica esperada de la porta.
2. runpack_verify informa que ha passat.
3. Els ancoratges d’evidència són presents i deterministes per a execucions offline repetides.

Procediment de refresc de fixtures

Utilitzeu el script de captura per a actualitzacions manuals de fixacions:

Nota: COURTLISTENER_API_TOKEN a continuació és només per al script de captura. No és el camí de credencials d’execució escrit utilitzat per les proves de fum en viu.

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ó de simulació:

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 actualitza els accessoris canònics del paquet i els reflecteix en:

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