Rutas de Habilidades Onboarding

Propósito

Esta guía es la única ruta de incorporación para ambos modos de uso de Decision Gate:

1. DG supervisa la ejecución de habilidades externas.
2. DG se llama como una habilidad de evaluación cuya semántica de comparador/RET es determinista sobre las entradas observadas completas.

También define cómo un arnés externo puede componer ambos modos sin permitir la deriva de políticas escritas por LLM. Esto no es ejecución de escenario recursiva o orquestación cruzada de escenarios propiedad de DG.

La plataforma de habilidades propiedad del repositorio se divide en dos anillos:

• Anillo interno: decision-gate-authoring, decision-gate-verification
• Anillo exterior: decision-gate-execution-boundary, decision-gate-incident-triage

Qué Ruta Usar

Intención	Ruta	Fuerza de Aplicación
Mutar estado externo (deploy, delete, pay, publish)	Ejecución de habilidades de guardias DG	Límite de envoltura de fallo cerrado; no es un buzón DG atómico
Producir análisis/informes/soporte a decisiones	DG como habilidad de evaluación	Cálculo solo a menos que esté envuelto por un límite
Bucles de agentes de múltiples pasos que autoran y luego ejecutan	Composición de arnés (guardia externa + evaluación interna)	Envoltura externa de fallo cerrado; no es elegibilidad de efecto atómico

Ruta A: Ejecución de Habilidades de Guardias DG

Utiliza esto cuando las acciones tengan efectos secundarios.

Superficie de habilidad primaria:

• decision-gate-execution-boundary para decisiones de permitir/negar en vivo
• decision-gate-verification para verificaciones post-ejecución limitadas e integridad de runpack
• decision-gate-incident-triage cuando el límite bloquea inesperadamente

Contrato Operativo

1. La propiedad de la puerta es de propiedad humana/política.
2. Las especificaciones de la puerta son artefactos versionados, no invenciones de LLM en tiempo de ejecución.
3. Cada llamada de habilidad mutante debe pasar la evaluación DG en vivo antes de la ejecución.
4. Una ejecución active bloquea la ejecución; solo el estado de ejecución exacto completed satisface la finalización inicial del escenario.
5. Las especificaciones de puerta consecuente deben tener un pase de falsificación independiente antes de la adopción; los predicados autoescritos son política candidata, no prueba de suficiencia.

Lista de Verificación de Configuración

1. Define un mapa de puerta por acción.
2. Autor y registrar especificaciones de escenario para cada clase de acción.
3. Implementar un envoltorio de tiempo de ejecución delgado: evaluate -> allow/deny -> execute.
4. Exportar y verificar la integridad de los runpacks como artefactos de auditoría/exportación derivados.

Ejemplo de mapa de acciones:

{
  "deploy_to_prod": {
    "scenario_id": "release-boundary-v1",
    "scenario_law_identity": "<64-lowercase-hex>",
    "required_min_lane": "verified",
    "required_run_status": "completed"
  },
  "publish_external_report": {
    "scenario_id": "publication-boundary-v1",
    "scenario_law_identity": "<64-lowercase-hex>",
    "required_min_lane": "verified",
    "required_run_status": "completed"
  }
}

Ejemplo de lógica de envoltura:

def guarded_skill_call(action_name, action_args):
    policy = action_gate_map[action_name]
    # scenario_start binds this new run to the exact immutable law identity.
    run_id = start_run(policy["scenario_id"], policy["scenario_law_identity"])
    operate_explicit_ready_stages(run_id)  # external operator/harness policy
    status = scenario_status(policy["scenario_id"], run_id)
    if status["status"] != policy["required_run_status"]:
        return {"allowed": False, "reason": "scenario_not_completed", "status": status}
    runpack = runpack_export(policy["scenario_id"], run_id)
    verify = runpack_verify(runpack["dir"], runpack["manifest_path"])
    if verify["status"] != "passed":
        return {"allowed": False, "reason": "runpack_verification_failed"}
    skill_result = call_external_skill(action_name, action_args)
    return {"allowed": True, "skill_result": skill_result, "accepted_head": status["accepted_head"]}

Referencias de implementación:

• scenario_define, scenario_start, scenario_evaluate_stage: integration_patterns.md
• runpack auditoría ruta: integration_patterns.md
• flujo de adaptador de extremo a extremo: scripts/adapters/adapter_tests.sh --frameworks=openai_agents --validate

Ruta B: Habilidad de Evaluación de DG

Utiliza esto para análisis estructurados cuando no se ejecuta ninguna acción de efecto secundario directa.

Superficie de habilidad primaria:

• decision-gate-authoring
• decision-gate-verification

Contrato Operativo

1. DG invoca la comparación determinista/semántica RET sobre las entradas observadas completas; la adquisición y la orquestación actual permanecen en un mundo abierto.
2. Las salidas impulsan la explicación/informe, no la mutación directa.
3. Si se solicita una mutación más tarde, cambie primero al límite de la Ruta A.
4. Una evaluación aprobada informa que los predicados declarados evaluaron como verdaderos bajo la evidencia exacta suministrada/adquirida y la semántica de política actual. No prueba por sí misma la verdad de la evidencia, la suficiencia del predicado, el compromiso aceptado, o la intención no declarada detrás de ellos.

Flujo Típico de Herramientas

1. Leer los recursos de herramienta/esquema generados y el perfil de capacidad local exacto.
2. Artefactos de construcción: claim_inventory, capability_matrix, claim_condition_map.
3. Evaluar: scenario_precheck_stage contra una ley registrada exacta para la iteración, luego scenario_start -> scenario_open_stage -> scenario_evaluate_stage con evidencia de llamador hostil o directivas explícitas de adquisición local acotada.
4. Exportar y verificar la integridad del runpack cuando se requiere un artefacto de auditoría/exportación derivado: runpack_export, runpack_verify.

Contrato objetivo permanente: llm_native_playbook.md. La secuencia de herramientas en esta guía sigue siendo un ejercicio de incorporación de contrato actual hasta que PF-09 regenere las proyecciones ejecutables.

Ruta C: Composición de Arnés (Bucle de Autoría + Límite de Ejecución)

Esta es la preocupación común de “DG dentro de un flujo de trabajo de agente que también usa DG como su guardia externa”. El arnés secuencia llamadas DG independientes; un evaluador nunca invoca otro escenario.

Usa un modelo de anillo:

1. Anillo interno: autoría y verificación.
2. Anillo exterior: límite de ejecución y triaje de incidentes para el control consecuente.

Reglas estrictas:

1. El anillo interno puede proponer asignaciones; no puede relajar la política del anillo externo.
2. Las definiciones de la puerta del anillo exterior permanecen creadas por el sistema y versionadas.
3. Bloques del anillo exterior sobre cualquier reclamación requerida no resuelta independientemente del texto de confianza del anillo interior.
4. La identidad exacta de la ley de escenario inmutable y la cabeza de ejecución aceptada son las fuentes de decisión semántica del DG. La verificación base del runpack establece sus controles de integridad de artefacto nombrado; la verificación asistida por autoridad revalida adicionalmente la ley hostil y reproduce la historia semántica aceptada cuando se utiliza ese camino explícito. Ninguno de los modos prueba la entrega de efectos externos, la causalidad entre escenarios, la recuperación, la calificación de despliegue, o la no repudio calificada por política.
5. Los cambios en la puerta del anillo exterior consecuente requieren falsificación independiente de predicados durante la autoría, antes de su uso en vivo.

Patrón a evitar:

"The agent self-evaluated with DG and therefore can deploy."

"The agent authored new predicates, passed them, and therefore the intended claim is proven."

Patrón correcto:

"The agent used DG for analysis, then the system-enforced deployment gate passed live, then deploy executed."

"The authoring agent proposed predicates, a separate review attempted to falsify them, unresolved false-green risks were blocked, and only then was the gate used for closure."

Ruta de Incorporación Rápida (Repositorio)

Utiliza esta secuencia al integrar humanos o agentes LLM en ambos caminos.

1. Ejecuta el inicio rápido de un solo comando probado (ambos caminos + caso de denegación forzada):

scripts/bootstrap/skill_pathways_quickstart.sh configs/presets/quickstart-dev.toml

2. Lee llm_native_playbook.md y esta guía.
3. Instalar habilidades:

scripts/skills/install_local.sh

4. Ejecutar el bucle de incorporación de extremo a extremo:

bash scripts/adapters/adapter_tests.sh --frameworks=openai_agents --validate

5. Ejecutar matriz de corrección determinista:

uv run --project . --locked --extra quality python scripts/skills/eval_runner.py \
  --mode deterministic \
  --cases all \
  --out-dir .tmp/skills/eval-deterministic-local

6. Ejecutar matriz requerida en vivo para las habilidades que enfrentan el límite:

uv run --project . --locked --extra quality python scripts/skills/eval_runner.py \
  --mode live \
  --cases live-required \
  --out-dir .tmp/skills/eval-live-local

Definición de Hecho (Mínimo Sin Errores)

Antes de declarar la adopción completa:

1. Las habilidades mutantes están envueltas por la lógica de límite de la Ruta A.
2. Las especificaciones de la puerta están versionadas y son propiedad de la política (no texto de aviso ad hoc).
3. Las cuatro habilidades soportadas se instalan como paquetes autónomos sin referencias externas al repositorio.
4. Las instrucciones orientadas a LLM incluyen reglas explícitas de parada definitiva.
5. Los informes de evaluación de habilidades deterministas son válidos para los casos requeridos.
6. Los informes de evaluación de habilidades requeridas en vivo pasan para casos que enfrentan el límite.
7. Las verificaciones de Runpack se realizan en flujos de trabajo de límite en vivo.

Referencias cruzadas

• llm_native_playbook.md
• integration_patterns.md
• guía_de_onboarding_de_agentes_openai.md