# Alignment and effects

Check a material action against the active task before execution. Follow the returned `verdict` and `next_action`, then report the actual effects when effect reporting is enabled.

### Check an action

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

Requires `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
  }'
```

At minimum, provide `action`. The path supplies `task_id`. You can instead call the generic tool endpoint with `session_ref` or `task_id`.

### Verdicts and required behaviour

| Verdict | `next_action` | Host behaviour |
| ------- | ------------- | -------------- |
| `ALIGNED` | `PROCEED` | The action directly serves the active task. |
| `SUPPORTING` | `PROCEED_AND_RECORD_EXPANSION` | Proceed with the bounded dependency and retain the recorded expansion. |
| `NEEDS_EXPLANATION` | `REQUEST_AGENT_EXPLANATION` | Call the explanation endpoint with bounded evidence before proceeding. |
| `USER_CONFIRMATION_REQUIRED` | `ASK_SESSION_USER` | Ask the user inline and submit the trusted response. |
| `CONTEXT_REFRESH_REQUIRED` | `REFRESH_TASK_CONTEXT` | Fetch the current task context and re-check. |
| `REFOCUS` | `REPLAN_TO_CURRENT_TASK` | Do not perform the proposed action; replan toward the active objective. |
| `STOPPED` | `DO_NOT_EXECUTE` | Do not perform the action. |
| `OBSERVED_DRIFT` | `PROCEED` | Observe-mode only: the drift is recorded but execution is not blocked. |

An aligned or supporting result may include a short-lived `alignment_token`, `expires_at`, and `external_action_id`. A user-confirmation result includes a `proposal` with the question, proposal ID, expiry, and nonce required by the confirmation endpoint.

### Explain an ambiguous relationship

When the verdict is `NEEDS_EXPLANATION`, use:

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

Requires `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 re-evaluates the check and returns the same result shape as an alignment check. Follow the new verdict.

### Request an explicit scope change

Use `POST /v1/task-guard/tasks/{taskId}/changes` to evaluate a proposed objective or scope change.

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

This route evaluates the request as an `OBJECTIVE_CHANGE`. It normally returns `USER_CONFIRMATION_REQUIRED` with a proposal for the session user.

### Submit the user's confirmation

Use:

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

Requires `task_guard:confirmations:write` and an API key marked as a trusted Task Guard confirmation credential.

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

An accepted confirmation creates a new contract version and returns `REFRESH_TASK_CONTEXT`. A rejection returns `REPLAN_TO_CURRENT_TASK`.

> **Important**
> This confirms whether the work belongs to the Task Guard task. It does not replace a Govern checkpoint for a deployment, purchase, transfer, message, or other consequential action.


### Verify an enforced alignment token

An enforced host can bind execution to the exact action checked by Task Guard:

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

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

The token is accepted only while the task is active, the contract revision is still current, and the action signature matches. The response returns `allowed: true`, the task and check IDs, contract revision ID, workspace ID, and expiry.

### Report actual effects

After a checked action runs, use:

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

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

If the actual effect materially differs from the checked action, Task Guard returns `effect_aligned: false`, revokes matching alignment grants, and instructs the host to ask the session user before expanding further.