# Canonical Operation Contract

## Source of truth

The canonical business-system input is the bundled [standard_system_operation.schema.json](standard_system_operation.schema.json). The Agent Prompt routes in-scope requests to this Skill, and this Skill returns a wrapper around exactly one operation. A host may replace the bundled schema only by an explicitly versioned compatible contract.

```json
{
  "status": "agent_parse_passed",
  "blockers": [],
  "operation": {
    "action": "team_order_create",
    "order_nature": "test",
    "submit_mode": "dry_run",
    "data": {}
  }
}
```

For blocked input:

```json
{
  "status": "agent_parse_blocked",
  "blockers": ["missing_field:data.product"],
  "operation": null
}
```

The Skill must return JSON only. The business system preserves raw text, task ID, external session ID, and parser/profile metadata outside `operation`.

## Allowed operation keys

At the operation level, use only:

- `action`
- `order_nature`
- `submit_mode`
- `source` (only schema-declared metadata)
- `data`

At the `data` level, use fields declared in the standard schema: customer/product/route/trip/order number, dates, recurrence, capacity, counts, prices, users, logistics, requests, passenger list, attachments, existing references, updates, confirmation, recovery, defaults, validation notes, and `resolution`. The current runtime also consumes the two documented compatibility fields `order_mode` and `test_marker`; do not add other ad-hoc fields.

## Two-stage resolution

For team create and batch tasks, the Agent may return a task-ready operation without `customer`, `route`, `trip`, or `order_number` when those values are ERP-derived. It must then include:

```json
"resolution": {
  "mode": "task_ready",
  "deferred_fields": ["customer", "route", "trip", "order_number"]
}
```

If all four fields are already present, still use `"mode": "task_ready"` unless the host has supplied verified ERP lookup evidence. The ERP preflight may call the product-template side effect and exact lookups to complete these fields. Only a fully resolved operation may be treated as `erp_ready`; neither state claims that an ERP write occurred.

Do not add `routeName`, `originalText`, `task_id`, `session_id`, `parser_prompt_version`, credentials, selectors, or arbitrary model commentary to `operation`. Transport metadata belongs in the business task wrapper.

## Status rules

- `agent_parse_passed` requires `operation` and an empty `blockers` array.
- `agent_parse_blocked` requires a non-empty `blockers` array and `operation: null`.
- Missing user-owned facts, ambiguous business references, conflicting explicit values, unsupported actions, or unsafe input must be blocked. ERP-owned deferred fields are valid only when represented by `resolution`.

## Compatibility boundary

The handoff package's `erp-task-v1` envelope is useful for internal Skill/executor interoperability. Its `operation=create_order`, `route=team_single`, and `task.fields` shape is not the Agent output contract. If the Skill receives that legacy shape, normalize it internally into the seven-action standard operation; do not ask the cloud Agent to emit both formats.