# Support-to-engineering handoff workflow blueprint

Version: 1.0
Canonical job: `/solutions/customer-support/support-to-engineering-handoff`

## State model

`qualified -> validating -> needs_evidence|duplicate_review|privacy_exception|ready -> submitted -> awaiting_ack -> accepted|rejected|more_evidence -> investigating -> fix_ready -> verification -> verified|verification_failed -> customer_update -> closed`

## Data contract

```yaml
handoff_id: string
support_ticket_id: string
escalation_version: integer
observed: string
expected: string
environment: object
timeline: [{at: datetime, event: string, source_id: string}]
reproduction: {attempted: boolean, steps: [string], result: string}
impact: {scope: string, severity_inputs: object, workaround: string|null}
evidence: [{id: string, type: string, sanitized: boolean, access_class: string}]
engineering_ref: string|null
support_owner: string
engineering_owner: string|null
```

## Steps and permissions

1. **Human:** qualify destination and escalation type.
2. **Code:** validate schema, scan evidence and search duplicate candidates.
3. **Human:** decide uncertain duplicate and approve sensitive-data boundary.
4. **AI:** draft only from referenced fields/events; no diagnosis or invented reproduction.
5. **Human:** approve severity and submission.
6. **Code:** create/link once with key `{support_ticket_id}:v{escalation_version}`.
7. **Trigger:** enforce acknowledgement and update timers.
8. **Code:** synchronize allowed state events through an explicit field allowlist.
9. **Human:** verify outcome and approve customer-facing communication.

## Failure handling

- An unknown create result enters reconciliation; it never immediately retries.
- Mapping failures retain payload hash, destination response and owner.
- Timer expiry escalates to a named queue based on severity.
- Link changes are append-only and preserve superseded references.

## Acceptance tests

1. Missing observed/expected fields cannot submit.
2. Unsafe attachment cannot cross the boundary.
3. Model output contains references for each factual statement.
4. Two create attempts produce one engineering item.
5. Both records contain reciprocal links after recovery from a partial write.
6. Engineering rejection returns a reason and owned support state.
7. Fix-ready cannot transition directly to closed.
8. Internal-only comments never synchronize to the customer record.