# Asset Workflow Integrity and Delivery Guarantee

**Created:** 2026-02-24 (Xian)
**Status:** Active spec — gap analysis in progress
**Priority:** Critical

---

## Objective

Ensure users always receive the correct, QA-verified image. Every generated asset must be fully tracked from creation through delivery, with no verdict mix-ups, no unreviewed assets delivered as final, and full audit traceability.

---

## Requirements

### 1. Unique Asset ID + Preserved Context
- Every generated asset must have a **unique Asset ID**
- Asset ID must carry: `product_id`, `source_channel`, `request_id`, `target_platform`
- Asset ID is immutable — regenerated versions get a new ID (see Req #10)

### 2. QA Results Bound to Exact Asset ID/Version
- QA verdicts must be attached to the exact Asset ID/version that was scanned
- No floating verdicts, no cross-version contamination

### 3. Visible Lifecycle State Model
```
Generated → Saved → Queued for QA → Scanning → Verdict Ready → Delivered
```
- Each state transition must be recorded with timestamp
- UI must show current state clearly

### 4. Preview-Only Until QA Complete
- Assets in `Queued for QA` or `Scanning` state may only be shown as **Preview (QA Pending)**
- Final delivery not allowed until verdict is complete OR authorized user manually approves

### 5. No "Final/Ready" Until QA Complete
- System must not mark any asset as final or ready until:
  - QA verdict is `pass`, OR
  - Manual approval by authorized user (with audit log entry)

### 6. QA Delay / Failure Recovery
- If QA is delayed or errors out, UI and chat must show:
  - Clear status (e.g. "QA timed out", "QA failed to run")
  - Recovery action options: **Retry QA** / **Review in Content Review**

### 7. Non-Pass Verdict Format
- `Needs Review` or `Warning` verdicts must include:
  - **Specific reason** (not generic labels)
  - **Recommended fix** (actionable)

### 8. Audit Log — All Manual Actions
Every manual override or review action must be logged with:
- User (who took the action)
- Timestamp
- Action type (approve, override, retry, flag, etc.)
- Previous state → new state

### 9. Cross-Surface Consistency
- Content Review tab and chat/Discord verdict messages must reference:
  - Same Asset ID / version
  - Same product
- No discrepancy between what's shown in UI and what was messaged

### 10. Versioning for Regenerated Assets
- Regenerated assets get a new version ID (e.g. `asset-123-v2`)
- Old version's verdict must not transfer to new version
- UI must show version history and prevent verdict confusion between versions

---

## Lifecycle State Model (Detail)

| State | Meaning | UI Treatment |
|-------|---------|--------------|
| `generated` | File created, not yet saved to system | Internal only |
| `saved` | Ingested into qa-reports, assigned Asset ID | Visible as "Added" |
| `queued` | Queued for QA, waiting for scanner | 🕐 "QA Pending" badge |
| `scanning` | QA actively running | ⚡ "Scanning..." badge |
| `verdict_ready` | QA complete, verdict attached | ✅ / ⚠️ / ❌ badge |
| `delivered` | Shown as final to user | Full display unlocked |
| `override_approved` | Manually approved before QA or after warning | 👤 "Approved" badge + audit entry |

---

## Gap Analysis

*(Filled in after reviewing current system — see below)*

---

## Implementation Plan

*(To be determined after gap analysis)*
