# Alignement et effets

Vérifiez une action matérielle contre la tâche active avant l'exécution. Suivre le retour `verdict` et `next_action`, puis signaler les effets réels lorsque la déclaration des effets est activée.

### Vérifiez une action

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

Nécessaire `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
  }'
```

Au minimum, fournir `action`C'est vrai. Le chemin fournit `task_id`C'est vrai. Vous pouvez plutôt appeler le paramètre d'outil générique avec `session_ref` ou `task_id`.

### Verdicts et comportement requis

| Verdict | `next_action` | Comportement de l'hôte |
| ------- | ------------- | -------------- |
| `ALIGNED` | `PROCEED` | L'action sert directement la tâche active. |
| `SUPPORTING` | `PROCEED_AND_RECORD_EXPANSION` | Procéder à la dépendance limitée et conserver l'expansion enregistrée. |
| `NEEDS_EXPLANATION` | `REQUEST_AGENT_EXPLANATION` | Appelez le point d'arrêt de l'explication avec une preuve limitée avant de procéder. |
| `USER_CONFIRMATION_REQUIRED` | `ASK_SESSION_USER` | Demandez à l'utilisateur en ligne et soumettez la réponse de confiance. |
| `CONTEXT_REFRESH_REQUIRED` | `REFRESH_TASK_CONTEXT` | Renseignez-vous sur le contexte de tâche actuel et revérifiez-le. |
| `REFOCUS` | `REPLAN_TO_CURRENT_TASK` | Ne pas exécuter l'action proposée; replanifier vers l'objectif actif. |
| `STOPPED` | `DO_NOT_EXECUTE` | Ne pas exécuter l'action. |
| `OBSERVED_DRIFT` | `PROCEED` | Observez le mode seulement : la dérive est enregistrée mais l'exécution n'est pas bloquée. |

Un résultat aligné ou de soutien peut inclure une courte durée de vie `alignment_token`, `expires_at`et `external_action_id`C'est vrai. Un résultat de confirmation de l'utilisateur comprend : `proposal` avec la question, l'ID de la proposition, l'expiration et le nonce requis par le paramètre de confirmation.

### Expliquez une relation ambiguë

Quand le verdict est `NEEDS_EXPLANATION`, utiliser:

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

Nécessaire `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 réévalue la vérification et retourne la même forme de résultat qu'une vérification d'alignement. Suivez le nouveau verdict.

### Demander un changement de portée explicite

Utilisation `POST /v1/task-guard/tasks/{taskId}/changes` évaluer un objectif proposé ou un changement de portée.

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

Cette route évalue la demande en tant que `OBJECTIVE_CHANGE`C'est vrai. Elle revient normalement. `USER_CONFIRMATION_REQUIRED` avec une proposition pour l'utilisateur de la session.

### Soumettre la confirmation de l'utilisateur

Utilisation:

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

Nécessaire `task_guard:confirmations:write` et une clé API marquée comme un titre de confirmation Task Guard de confiance.

```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."
}
```

Une confirmation acceptée crée une nouvelle version du contrat et renvoie `REFRESH_TASK_CONTEXT`C'est vrai. Un rejet revient `REPLAN_TO_CURRENT_TASK`.

> **Important**
> Cela confirme si le travail appartient à la tâche Task Guard. Il ne remplace pas un point de contrôle Govern pour un déploiement, un achat, un transfert, un message ou toute autre mesure consécutive.


### Vérifier un jeton d'alignement imposé

Un hôte forcé peut lier l'exécution à l'action exacte vérifiée par Task Guard :

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

Nécessaire `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"
  }
}
```

Le jeton n'est accepté que lorsque la tâche est active, la révision du contrat est toujours en cours et la signature de l'action correspond. La réponse retourne `allowed: true`, la tâche et vérifier les ID, l'ID de révision du contrat, l'ID de l'espace de travail et l'expiration.

### Signaler les effets effectifs

Après une action contrôlée, utilisez :

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

Nécessaire `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 l'effet réel diffère sensiblement de l'action cochée, Task Guard retourne `effect_aligned: false`, révoque les subventions d'alignement correspondantes, et demande à l'hôte de demander à l'utilisateur de la session avant d'élargir davantage.