Contracte d’Autorització LLM

Propòsit i Audiència

Què: El contracte canònic de document únic per a l’autoria de Decision Gate impulsada per LLM. Per què: Aplicar controls deterministes i basats en evidències abans d’accions conseqüents. Qui: Equips que integren agents LLM amb Decision Gate en fluxos de treball fixos o bucles d’autoautoria. Prerequisits: evidence_flow_and_execution_model.md

Aquest és el document principal que s’ha de lliurar a un LLM. Altres guies són opcionalment més profundes. Per a un únic camí d’integració humana que cobreixi l’execució protegida, l’avaluació de DG-com a-habilitat i la composició recursiva, vegeu skill_pathways_onboarding.md.

Implementació de Referència

Per a una implementació de reclamació legal concreta d’aquest contracte (operació offline determinista més opt-in en viu), vegeu:

Invariants No Negociables

Decision Gate és un límit d’execució, no una anàlisi assessora.
Les afirmacions fáctiques que estan marcades com a requerides han de ser resoltes per evidència, no per la confiança del model.
Les accions conseqüents han de ser bloquejades quan les reclamacions requerides no estiguin resoltes.
precheck és només per iteracions; els camins conseqüents requereixen avaluació en viu.
Les discrepàncies de capacitat fallen tancades.

Seqüència d’Eines Canòniques

Utilitzeu aquesta seqüència per a cada flux de treball:

Capability discovery
- providers_list
- provider_contract_get
- proveidor_comprovar_esquema_obtenir
Authoring
- Extreure reclamacions
- Construir claim_inventory
- Compilar claim_condition_map
Fast loop
- schemas_register
- precheck
Consequential boundary
- scenario_define (si no està ja definit)
- escenari_inici
- escenari_seguent
Audit/debug
- runpack_export i/o evidence_query segons permeti la política

Habilitats Creuament

Aquest document roman el protocol normatiu. Les habilitats són embolcalls operatius per utilitzar el protocol de manera consistent.

Habilitats del repositori canònic:

skills/decision-gate-authoring
skills/decision-gate-verification
skills/decision-gate-capability-discovery

Pas de vianants:

Secció del playbook	Habilitat principal	Seqüència d’eines concreta
Seqüència d’eines canònica	`decision-gate-authoring`	`providers_list` -> `provider_contract_get` -> `provider_check_schema_get` -> `schemas_register` -> `precheck` -> `scenario_define` -> `scenario_start` -> `scenario_next`
Intercanvi de descoberta de capacitats	`decision-gate-capability-discovery`	`providers_list` -> `provider_contract_get` -> `provider_check_schema_get`
Contracte de descomposició de reclamacions	`decision-gate-authoring`	extracció de reclamacions + generació de `claim_inventory` (amb contracte)
Contracte de compilació de condicions	`decision-gate-authoring` + `decision-gate-capability-discovery`	comprovació d’esquemes + validació de comparadors/tipus abans de `claim_condition_map`
Contracte d’execució + Regles de parada dura	`decision-gate-authoring` + `decision-gate-verification`	bucle ràpid de `precheck`, després `scenario_start` en viu + `scenario_next`, després `runpack_export` + `runpack_verify`
Bloc de sol·licitud d’agent canònic	les tres habilitats	instruccions d’habilitat compactes que preserven aquest contracte (no una segona font de veritat)

decision_gate_docs_search consultes per donar suport a fluxos de treball de competències:

{
  "query": "llm authoring capability discovery handshake providers_list provider_check_schema_get",
  "max_sections": 4
}

{
  "query": "precheck versus live scenario_next hard stop rules enforcement_verdict",
  "max_sections": 4
}

{
  "query": "runpack_export runpack_verify trust lane verified asserted",
  "max_sections": 4
}

Descobriment de Capacitats Handshake

La descoberta de capacitats és obligatòria abans de la compilació de condicions en dominis arbitràries.

1) Llista de proveïdors

{}

Utilitzeu la càrrega útil anterior amb providers_list.

2) Obtenir contracte del proveïdor

{
  "provider_id": "json"
}

Utilitzeu la càrrega útil anterior amb provider_contract_get.

3) Obtenir detalls de l’esquema de comprovació

{
  "provider_id": "json",
  "check_id": "path"
}

Utilitzeu la càrrega útil anterior amb provider_check_schema_get.

Com a mínim, recolliu:

comparadors_permesos
params_schema
result_schema

Contracte de Descomposició de Reclamacions

Cada afirmació factual de candidat ha de ser representada en claim_inventory.

Regles de classificació:

gatable = true només quan la reclamació es pot comprovar de manera determinista contra una font d’evidència.
gating_required = true per a reclamacions que bloquegen accions conseqüents si no es resolen.
gatable = false requereix un reason no buit.

Es donen suport a dos modes d’operació:

Flux de treball fix: els humans predefinixen les classes de reclam necessàries (per exemple, cites legals).
Autoautoria: l’agent extreu reclamacions en temps d’execució i compila condicions a partir de les capacitats descobertes.

S’espera que hi hagi especificitat de domini: les reclamacions depenen de les fonts de dades i l’accés de cada equip.

Contracte de Compilació de Condicions

Per a cada gatable = true reclamació, compila una o més condicions utilitzant:

provider_id
check_id
params
comparador
esperat
trust_min_lane

Requisits de compilació:

El comparador ha d’estar en allowed_comparators de provider_check_schema_get.
params ha de complir amb params_schema.
expected ha de ser compatible amb result_schema i la semàntica del comparador.
condition_id els valors han de ser únics dins l’escenari.

Contracte d’Execució

Bucle d’iteració ràpida (assertat)

Registre l’esquema mitjançant schemas_register.
Executa precheck contra la càrrega afirmada.
Corregeix el mapeig de reclamacions, l’esquema o les condicions fins que les reclamacions requerides s’avaluïn per passar a estats.

Límite conseqüent (verificat)

Abans de qualsevol acció conseqüent:

Assegureu-vos que l’escenari estigui definit (scenario_define).
Crear execució (scenario_start).
Executar avaluació en viu (scenario_next).
Procediu només si el resultat de la decisió és aprovat/avançat/complet per a la vostra política de límits.

Regles de Parada Dura (NO S’HAN DE PROCEGUIR)

No permeteu accions conseqüents quan qualsevol de les condicions següents sigui certa:

Una reclamació gatable requerida no té mapeig en claim_condition_map.
Una condició mapejada requerida resol false o unknown.
scenario_next no retorna un resultat de pas permès per al límit de lliberació.
La política requereix verificat però només s’utilitza evidència afirmada.
La validació del contracte del proveïdor/comprovador/comparador/tipus falla.

Bloc de Prompt de l’Agent Canonical

Enganxa això al teu missatge del sistema d’agents, després vincula la capa d’eines als instruments DG MCP.

You are the Decision Gate Authoring Agent. Follow this protocol exactly.

Inputs:
- draft_output: candidate output text or structured payload
- consequence_boundary: the action that must be blocked unless gates pass
- policy_defaults:
  - required_risk_levels: ["high", "critical"]
  - required_min_lane: "verified"

Required outputs (all four):
1) claim_inventory
2) capability_matrix
3) claim_condition_map
4) enforcement_verdict

Protocol:
1. Discover provider capabilities using providers_list, provider_contract_get, provider_check_schema_get.
2. Extract factual claims from draft_output.
3. Build claim_inventory:
   - Set gatable=true only for deterministically checkable claims.
   - Set gating_required=true for claims whose failure must block consequence_boundary.
   - Include non-empty reason for every gatable=false claim.
4. Build claim_condition_map for all gatable=true claims.
5. Validate mappings against provider check contracts (comparators, params, value types).
6. Run precheck for fast iteration.
7. Before consequence_boundary, run live scenario_start + scenario_next.
8. Set enforcement_verdict.can_proceed=true only if all required gatable claims are resolved by passing live-evaluated conditions at required trust lane.

Hard-stop behavior:
- If any required gatable claim is unmapped, unknown, false, or lane-invalid, set can_proceed=false and emit explicit blocking_reasons.
- Never treat model confidence or self-verification text as evidence.

Plantilles JSON incrustades

claim_inventory (requerit)

{
  "claim_inventory": [
    {
      "claim_id": "claim_001",
      "claim_text": "Case X exists in court records",
      "gatable": true,
      "gating_required": true,
      "reason": "Deterministic external lookup available",
      "evidence_source_hint": "court_records_api",
      "risk_level": "high"
    }
  ]
}

capability_matrix (requerit)

{
  "capability_matrix": [
    {
      "provider_id": "json",
      "check_id": "path",
      "allowed_comparators": ["equals", "exists", "not_exists", "in_set"],
      "params_schema_ref": "provider_check_schema_get:json:path:params_schema",
      "result_schema_ref": "provider_check_schema_get:json:path:result_schema"
    }
  ]
}

claimconditionmap (requerit)

{
  "claim_condition_map": [
    {
      "claim_id": "claim_001",
      "condition_id": "case_exists",
      "provider_id": "rest",
      "check_id": "json_path",
      "params": {
        "url": "https://api.example.com/cases/lookup?id=925-F3d-1339",
        "jsonpath": "$.exists"
      },
      "comparator": "equals",
      "expected": true,
      "trust_min_lane": "verified"
    }
  ]
}

enforcement_verdict (requerit)

{
  "enforcement_verdict": {
    "can_proceed": false,
    "blocking_reasons": [
      "required claim claim_001 unresolved",
      "live evaluation not complete"
    ],
    "required_claims_unresolved": ["claim_001"]
  }
}

Camí Daurat Mínim (Un Flux de Fi a Fi)

Aquest flux és intencionadament mínim i alineat amb el comportament actual de les eines OSS.

Consell de Windows: PowerShell/CMD no suporten curl en múltiples línies al estil bash. Utilitzeu un comandament d’una sola línia o cadenes de PowerShell aquí. Consell de preset: Comenceu amb configs/presets/quickstart-dev.toml per a ús local.

Pas 1: Definir escenari

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "scenario_define",
      "arguments": {
        "spec": {
          "scenario_id": "llm-precheck",
          "namespace_id": 1,
          "spec_version": "v1",
          "stages": [
            {
              "stage_id": "main",
              "entry_packets": [],
              "gates": [
                {
                  "gate_id": "quality",
                  "requirement": { "Condition": "report_ok" }
                }
              ],
              "advance_to": { "kind": "terminal" },
              "timeout": null,
              "on_timeout": "fail"
            }
          ],
          "conditions": [
            {
              "condition_id": "report_ok",
              "query": {
                "provider_id": "json",
                "check_id": "path",
                "params": { "file": "report.json", "jsonpath": "$.summary.failed" }
              },
              "comparator": "equals",
              "expected": 0,
              "policy_tags": []
            }
          ],
          "policies": [],
          "schemas": [],
          "default_tenant_id": 1
        }
      }
    }
  }'

Pas 2: Registrar l’esquema de precomprovació

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "schemas_register",
      "arguments": {
        "record": {
          "tenant_id": 1,
          "namespace_id": 1,
          "schema_id": "llm-precheck",
          "version": "v1",
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "report_ok": { "type": "number" }
            },
            "required": ["report_ok"]
          },
          "description": "LLM precheck payload schema",
          "created_at": { "kind": "logical", "value": 1 },
          "signing": null
        }
      }
    }
  }'

Pas 3: Precomprovació (cicle ràpid)

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "precheck",
      "arguments": {
        "tenant_id": 1,
        "namespace_id": 1,
        "scenario_id": "llm-precheck",
        "spec": null,
        "stage_id": "main",
        "data_shape": { "schema_id": "llm-precheck", "version": "v1" },
        "payload": { "report_ok": 0 }
      }
    }
  }'

Forma de resposta esperada:

{
  "decision": {
    "kind": "complete",
    "stage_id": "main"
  },
  "gate_evaluations": [
    {
      "gate_id": "quality",
      "status": "true",
      "trace": [
        { "condition_id": "report_ok", "status": "true" }
      ]
    }
  ]
}

Pas 4: Límite en viu (requerit abans d’una acció conseqüent)

# scenario_start
curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "scenario_start",
      "arguments": {
        "scenario_id": "llm-precheck",
        "run_config": {
          "tenant_id": 1,
          "namespace_id": 1,
          "run_id": "run-1",
          "scenario_id": "llm-precheck",
          "dispatch_targets": [],
          "policy_tags": []
        },
        "started_at": { "kind": "unix_millis", "value": 1710000000000 },
        "issue_entry_packets": false
      }
    }
  }'

# scenario_next
curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "scenario_next",
      "arguments": {
        "scenario_id": "llm-precheck",
        "request": {
          "run_id": "run-1",
          "tenant_id": 1,
          "namespace_id": 1,
          "trigger_id": "trigger-1",
          "agent_id": "agent-1",
          "time": { "kind": "unix_millis", "value": 1710000000000 },
          "correlation_id": null
        },
        "feedback": "trace"
      }
    }
  }'

Procediu només si la decisió en viu compleix la vostra política de pas.

Recuperació d’errors i escalada

Si la validació o l’avaluació falla:

Capability mismatch
- Tornar a consultar provider_check_schema_get i corregir la discrepància entre comparador/paràmetres/tipus de resultat.
precheck hold or tool error
- Valida la càrrega útil contra la forma de dades; assegura’t que els IDs de condició s’alineïn amb les claus de la càrrega útil.
Live run hold/fail
- Inspeccioneu runpack (runpack_export) o truqueu a evidence_query (si la política de divulgació ho permet).
Trust lane mismatch
- Si la política requereix verified, no aprovi proves només afirmades.
Unclear claim classification
- Escalar a l’owner de política humana; per defecte gating_required = true per a reclamacions d’alt risc.

Anàlisis profundes específiques del proveïdor:

Glossari

Inventari de reclamacions: Llista llegible per màquina de reclamacions candidates i classificació de portes. Matriu de capacitats: Capacitats de proveïdor/comprovació descobertes a partir d’eines DG. Mapa de condicions de reclamació: Mapeig determinista de reclamacions que es poden portar a condicions DG. Precomprovació: Simulació d’evidència afirmada, sense mutació de l’estat d’execució. Execució en viu: Avaluació obtinguda del proveïdor que muta l’estat d’execució i suporta l’auditoria de paquet d’execució. Acció conseqüent: Qualsevol acció que canvia l’estat extern, allibera sortida o compromet una decisió.