# Alineación y efectos

Revise una acción material contra la tarea activa antes de la ejecución. Sigue a los retornados `verdict` y `next_action`, luego reportar los efectos reales cuando se activa la presentación de los efectos.

### Revisar una acción

Uso `POST /v1/task-guard/tasks/{taskId}/checks`.

Requisitos `task_guard:checks:write`.

```bash
curl -X POST "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/checks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Edit the refund approval API route",
    "action_type": "edit",
    "target": "apps/api/src/routes/refunds.ts",
    "effect": "MODIFY",
    "effects": ["Add validation and approval checkpoint handling"],
    "rationale": "The route is explicitly included in the active task.",
    "current_step": "Implement API route",
    "contract_version": 1,
    "external_action_id": "action-01JY8V",
    "idempotency_key": "alignment-01JY8V",
    "provenance": "HOST_VERIFIED",
    "reversible": true
  }'
```

Al mínimo, prevean `action`. El camino abastece `task_id`. Puede llamar al punto final de la herramienta genérica con `session_ref` o `task_id`.

### Veredictos y comportamiento requerido

| Vered | `next_action` | Comportamiento de acogida |
| ------- | ------------- | -------------- |
| `ALIGNED` | `PROCEED` | La acción sirve directamente a la tarea activa. |
| `SUPPORTING` | `PROCEED_AND_RECORD_EXPANSION` | Proceder con la dependencia atada y mantener la expansión registrada. |
| `NEEDS_EXPLANATION` | `REQUEST_AGENT_EXPLANATION` | Llame al punto final de la explicación con pruebas limitadas antes de proceder. |
| `USER_CONFIRMATION_REQUIRED` | `ASK_SESSION_USER` | Pregúntele al usuario y envíe la respuesta de confianza. |
| `CONTEXT_REFRESH_REQUIRED` | `REFRESH_TASK_CONTEXT` | Obtenga el contexto de tarea actual y vuelva a comprobar. |
| `REFOCUS` | `REPLAN_TO_CURRENT_TASK` | No realice la acción propuesta; replanifique hacia el objetivo activo. |
| `STOPPED` | `DO_NOT_EXECUTE` | No realice la acción. |
| `OBSERVED_DRIFT` | `PROCEED` | Observe-mode only: la deriva se registra pero la ejecución no está bloqueada. |

Un resultado alineado o de apoyo puede incluir una vida corta `alignment_token`, `expires_at`, y `external_action_id`. Un resultado de confirmación de usuario incluye un `proposal` con la pregunta, la propuesta ID, la expiración, y ninguna vez requerido por el punto final de confirmación.

### Explique una relación ambigua

Cuando el veredicto `NEEDS_EXPLANATION`, uso:

```
POST /v1/task-guard/checks/{checkId}/explanation
```

Requisitos `task_guard:checks:write`.

```json
{
  "relationship": "This compatibility repair is required for the approval route tests to compile.",
  "evidence": [
    "The changed type is imported by the in-scope route.",
    "The failing test references the same request contract."
  ]
}
```

Task Guard reevalua el cheque y devuelve la misma forma de resultado como un control de alineación. Sigue el nuevo veredicto.

### Solicitar un cambio de alcance explícito

Uso `POST /v1/task-guard/tasks/{taskId}/changes` para evaluar un cambio de objetivo o de alcance propuesto.

```json
{
  "objective": "Also deploy the change to production.",
  "rationale": "Deployment was not included in the active task."
}
```

Esta ruta evalúa la solicitud como una `OBJECTIVE_CHANGE`. Normalmente regresa `USER_CONFIRMATION_REQUIRED` con una propuesta para el usuario de la sesión.

### Presentar la confirmación del usuario

Uso:

```
POST /v1/task-guard/changes/{proposalId}/confirmation
```

Requisitos `task_guard:confirmations:write` y una clave de API marcada como una confianza en la confirmación de Task Guard credencial.

```json
{
  "accepted": true,
  "direct_user_event_id": "user-event-01JY91",
  "host_signature_id": "host-signature-01JY91",
  "nonce": "nonce-returned-with-the-proposal",
  "host_user_ref": "user_42",
  "response": "Yes, include the production deployment."
}
```

Una confirmación aceptada crea una nueva versión de contrato y devoluciones `REFRESH_TASK_CONTEXT`. Retorno de rechazo `REPLAN_TO_CURRENT_TASK`.

> **Important**
> Esto confirma si el trabajo pertenece a la tarea de Task Guard. No reemplaza un puesto de control de Govern para un despliegue, compra, transferencia, mensaje u otra acción consiguiente.


### Verificar un token de alineación forzada

Un anfitrión forzado puede vincular la ejecución a la acción exacta verificada por Task Guard:

```
POST /v1/task-guard/alignment/verify
```

Requisitos `task_guard:checks:write`.

```json
{
  "task_id": "tgt_01JY8S",
  "external_action_id": "action-01JY8V",
  "alignment_token": "eyJ…",
  "action": "Edit the refund approval API route",
  "effect": "MODIFY",
  "tool_name": "apply_patch",
  "resource": {
    "type": "file",
    "id": "apps/api/src/routes/refunds.ts"
  }
}
```

El token solo se acepta mientras la tarea está activa, la revisión del contrato sigue siendo actual, y la firma de acción coincide. La respuesta devuelve `allowed: true`, la tarea y chequear identificaciones, identificación de revisión de contratos, identificación del espacio de trabajo y expiración.

### Informe de los efectos reales

Después de una acción verificada, utilice:

```
POST /v1/task-guard/checks/{checkId}/effects
```

Requisitos `task_guard:effects:write`.

```json
{
  "actual_effect": "MODIFY",
  "actual_effects": [
    "Updated the refund route validation",
    "Added approval checkpoint handling"
  ],
  "affected_resources": [
    { "type": "file", "id": "apps/api/src/routes/refunds.ts" }
  ],
  "summary": "The action changed only the checked route.",
  "validation_outcome": "Integration tests passed."
}
```

Si el efecto real difiere materialmente de la acción verificada, Task Guard regresa `effect_aligned: false`, revoca los subsidios de alineación coincidentes, e instruye al anfitrión a preguntar al usuario de la sesión antes de ampliarse más.