# Ausrichtung und Auswirkungen

Überprüfen Sie eine materielle Aktion gegen die aktive Aufgabe vor der Ausführung. Folgen Sie der Rückkehr `verdict` und `next_action`, dann die tatsächlichen Auswirkungen melden, wenn die Effektberichterstattung aktiviert ist.

### Überprüfung einer Aktion

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

Benötigt `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
  }'
```

Mindestens bieten `action`. Die Trassenversorgung `task_id`. Sie können stattdessen den generischen Tool-Endpunkt mit `session_ref` oder `task_id`.

### Urteile und erforderliches Verhalten

| Urteil | `next_action` | Wirtsverhalten |
| ------- | ------------- | -------------- |
| `ALIGNED` | `PROCEED` | Die Aktion dient direkt der aktiven Aufgabe. |
| `SUPPORTING` | `PROCEED_AND_RECORD_EXPANSION` | Fahren Sie mit der begrenzten Abhängigkeit fort und behalten Sie die aufgezeichnete Expansion bei. |
| `NEEDS_EXPLANATION` | `REQUEST_AGENT_EXPLANATION` | Rufen Sie den Erklärungsendpunkt mit begrenzten Beweisen an, bevor Sie fortfahren. |
| `USER_CONFIRMATION_REQUIRED` | `ASK_SESSION_USER` | Fragen Sie den Benutzer inline und senden Sie die vertrauenswürdige Antwort. |
| `CONTEXT_REFRESH_REQUIRED` | `REFRESH_TASK_CONTEXT` | Holen Sie sich den aktuellen Aufgabenkontext und überprüfen Sie erneut. |
| `REFOCUS` | `REPLAN_TO_CURRENT_TASK` | Führen Sie die vorgeschlagene Aktion nicht aus; Planen Sie auf das aktive Ziel hin neu. |
| `STOPPED` | `DO_NOT_EXECUTE` | Führen Sie die Aktion nicht aus. |
| `OBSERVED_DRIFT` | `PROCEED` | Nur im Observe-Modus: Die Drift wird aufgezeichnet, aber die Ausführung wird nicht blockiert. |

Ein abgestimmtes oder unterstützendes Ergebnis kann eine kurzlebige `alignment_token`, `expires_at`, und `external_action_id`. Ein User-Confirmation-Ergebnis beinhaltet eine `proposal` mit der Frage, der Vorschlags-ID, dem Ablauf und der Nonce, die vom Bestätigungs-Endpunkt verlangt werden.

### Erklären Sie eine mehrdeutige Beziehung

Wenn das Urteil `NEEDS_EXPLANATION`, Verwendung:

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

Benötigt `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 bewertet die Überprüfung neu und gibt die gleiche Ergebnisform wie eine Ausrichtungsprüfung zurück. Folgen Sie dem neuen Urteil.

### Beantragen Sie eine explizite Änderung des Umfangs

Verwendung `POST /v1/task-guard/tasks/{taskId}/changes` Bewertung eines vorgeschlagenen Ziels oder einer vorgeschlagenen Änderung des Anwendungsbereichs.

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

Diese Route wertet die Anfrage als `OBJECTIVE_CHANGE`. Normalerweise kehrt es zurück `USER_CONFIRMATION_REQUIRED` mit einem Vorschlag für den Sitzungsbenutzer.

### Senden Sie die Bestätigung des Benutzers

Verwendung:

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

Benötigt `task_guard:confirmations:write` und einen API-Schlüssel, der als vertrauenswürdiger Task Guard-Bestätigungsnachweis gekennzeichnet ist.

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

Eine akzeptierte Bestätigung erstellt eine neue Vertragsversion und gibt zurück `REFRESH_TASK_CONTEXT`. Eine Ablehnung kehrt zurück `REPLAN_TO_CURRENT_TASK`.

> **Important**
> Dies bestätigt, ob die Arbeit zur Task Guard-Aufgabe gehört. Es ersetzt keinen Govern-Checkpoint für eine Bereitstellung, einen Kauf, eine Übertragung, eine Nachricht oder eine andere Folgemaßnahme.


### Überprüfen Sie ein erzwungenes Alignment-Token

Ein erzwungener Host kann die Ausführung an die genaue Aktion binden, die von Task Guard überprüft wurde:

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

Benötigt `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"
  }
}
```

Das Token wird nur akzeptiert, während die Aufgabe aktiv ist, die Vertragsrevision noch aktuell ist und die Aktionssignatur übereinstimmt. Die Response Returns `allowed: true`, die Task- und Prüf-IDs, die Vertragsrevisions-ID, die Workspace-ID und den Ablauf.

### Tatsächliche Auswirkungen melden

Nachdem eine überprüfte Aktion ausgeführt wurde, verwenden:

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

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

Wenn sich der tatsächliche Effekt wesentlich von der überprüften Aktion unterscheidet, kehrt Task Guard zurück `effect_aligned: false`, widerruft Matching Alignment Grants und weist den Host an, den Sitzungsbenutzer zu fragen, bevor er weiter expandiert.