# Symphony AI Master Spec Addendum
# Pre-Generation Standards Enforcement + Generation Preflight Spec Table

**Source:** Xian Baylin (PDF, 2026-02-24)
**Status:** Active — enforced on all marketing asset generation

---

## Core Rule

> Generate first and validate later is NOT the primary behavior.
> Resolve the correct output format first → generate → QA-verify.

Platform and placement standards are **hard generation constraints**, not post-hoc checks.

---

## Required Pre-Generation Workflow (7 Steps)

### Step 1 — Identify Generation Context
Lock BEFORE generation:
- Product ID + Product Name
- Target Platform (Facebook / X / Instagram / LinkedIn / TikTok)
- Placement (Feed / Story / Reels / Carousel / Link Post / etc.)
- Asset Type (Static image / Carousel card / Video cover / etc.)
- Channel Source (Symphony Chat / Discord / other)
- Request ID / Session ID

**If any required field is missing → do not proceed silently. Block and request correction.**

### Step 2 — Load Standards and Branding Sources
- Design Phase Brand Guidelines (primary identity source)
- Product Marketing Branding Profile (Symphony)
- Approved uploaded branding references (if any)
- Latest verified platform standards library (platform + placement + asset type)
- If refresh failed today → use last verified + mark `refresh_pending`

### Step 3 — Resolve Output Specifications (Generation Spec Resolver)
Produce BEFORE generation:
- Target aspect ratio
- Target pixel dimensions
- Allowed alternative ratios/dimensions (if applicable)
- Safe-zone requirements (if applicable)
- Quality requirements (minimum resolution/readability)
- Platform-fit validation rules (reused in QA)

**The resolved spec = source of truth for both generation AND QA.**

### Step 4 — Preflight Validation (must pass before generation)
Validate:
- [ ] Product selected and linked
- [ ] Platform selected
- [ ] Placement selected
- [ ] Asset type selected
- [ ] Branding profile available (or explicitly marked incomplete)
- [ ] Platform standards resolved successfully
- [ ] Output dimensions set
- [ ] Generation model supports resolved dimensions (or supported equivalent)

**Failure → block generation, return clear reason, provide required next step.**
**Never default to generic 16:9 when platform standards exist.**

### Step 5 — Pass Resolved Specs as Hard Constraints into Generation
Pass into the generator:
- Exact or allowed aspect ratio
- Target dimensions
- Platform-safe layout direction (e.g. vertical-first for TikTok)
- Text-safe margin guidance (if used)
- Branding constraints (logo usage, color palette, etc.)

**The generation prompt must not be generic when platform and placement are known.**

### Step 6 — Immediate Post-Generation Compliance Check (before success message)
Verify:
- Actual image dimensions match intended specs (or approved allowed variant)
- Output file exists and is linked to the correct product
- Asset record created with unique Asset ID
- Intended generation spec attached to asset metadata

**If dimensions don't match → mark as `off_spec`, trigger Fix/Regenerate flow. Do NOT mark as final success.**

### Step 7 — QA Runs After Generation (verification layer)
QA compares actual output versus:
- Resolved generation spec
- Branding standards
- Platform standards

Catches: dimension mismatch, layout/cropping risks, branding issues, readability issues, trend/platform fit.

---

## Non-Negotiable Guardrails

- ❌ Do NOT use generic/default 16:9 for platform-specific image posts (unless explicitly requested)
- ❌ Do NOT bypass preflight when platform and placement are known
- ❌ Do NOT mark off-spec assets as final without warning/status
- ❌ Do NOT overwrite original image during fix/regenerate
- ❌ Do NOT detach QA verdicts from exact Asset ID/version

---

## Required Fallback Behavior

- If platform standards refresh is temporarily inaccessible → use last verified, mark `standards_refresh_pending`, include last verified timestamp in metadata
- Do NOT disable platform QA enforcement because a source is temporarily inaccessible

---

## Generation Preflight Spec Table

### Table Rules
- Structure rows by **platform + placement + asset type** — not one generic standard per platform
- Required columns: Platform, Placement, Asset Type, Use Case, Recommended Ratio, Allowed Ratios, Target Dimensions, Allowed Dimensions/Range, Safe-Zone Notes, Min Quality, Branding Notes, QA Checks, Fallback Behavior, Source Type, Last Verified Date, Refresh Status, Confidence Level
- **Resolver rule:** match request to row → resolve output settings → apply to generation → attach row metadata to asset for QA traceability
- **Fallback matching:** exact match → platform+asset type fallback → platform default fallback → mark `fallback_applied`, lower confidence, add QA warning
- **Never silently choose arbitrary dimensions**

---

## Preflight Spec Table (Full)

| Platform | Placement | Asset Type | Use Case | Rec. Ratio | Allowed Ratios | Target Dimensions | Allowed Dimensions | Safe-Zone Notes | Min Quality | QA Checks | Fallback | Source | Last Verified | Refresh Status | Confidence |
|----------|-----------|------------|----------|-----------|----------------|-------------------|-------------------|-----------------|-------------|-----------|----------|--------|--------------|----------------|------------|
| Facebook | Feed | Static Image | Organic/Ads | 1:1 or 4:5 | 1:1, 4:5 | 1440×1440 or 1440×1800 | 1080×1080 min | No critical text within 14% of edges | ≥1080px, readable at mobile | Ratio, dimensions, text safety, brand fit | 1:1 at 1440×1440, mark fallback | Last Verified | 2026-02-24 | Verified | Medium |
| Facebook | Story | Static Image | Organic/Ads | 9:16 | 9:16 | 1080×1920 | — | Top 14% + bottom 20% clear (UI overlays) | ≥1080px | Ratio, safe zone, brand fit | 9:16 at 1080×1920 | Last Verified | 2026-02-24 | Verified | Medium |
| Facebook | Reels | Video Cover | Organic | 9:16 | 9:16 | 1080×1920 | — | Top 130px, bottom 250px clear | ≥720p | Ratio, safe zone, no critical text in zone | 9:16 cover | Last Verified | 2026-02-24 | Verified | Medium |
| Instagram | Feed | Static Image | Organic | 4:5 (portrait) | 1:1, 4:5 | 1080×1350 (portrait) or 1080×1080 (square) | ≥1080px wide | No critical text within 10% of edges | ≥1080px | Ratio, dimensions, readability, brand fit | 1:1 at 1080×1080, mark fallback | Last Verified | 2026-02-24 | Verified | Medium |
| Instagram | Story | Static Image | Organic/Ads | 9:16 | 9:16 | 1080×1920 | — | Top 250px, bottom 340px clear (UI overlays) | ≥1080px | Ratio, safe zone, brand fit | 9:16 at 1080×1920 | Last Verified | 2026-02-24 | Verified | Medium |
| Instagram | Reels | Video Cover | Organic | 9:16 | 9:16 | 1080×1920 | — | Top 250px, bottom 340px clear | ≥720p | Ratio, safe zone, no critical text in zone | 9:16 cover | Last Verified | 2026-02-24 | Verified | Medium |
| Instagram | Feed | Carousel Card | Organic | 1:1 | 1:1 | 1080×1080 | — | Keep text centred; avoid crop edges | ≥1080px | Ratio, readability, card-to-card consistency | 1:1 at 1080×1080 | Last Verified | 2026-02-24 | Verified | Medium |
| X | Feed | Static Image | Organic/Ads | 16:9 (landscape) or 1:1 | 16:9, 1:1 | 1200×675 (16:9) or 1080×1080 (1:1) | — | No critical text in bottom 5% (CTA strip) | ≥600px | Ratio, crop risk, readability, brand fit | 16:9 at 1200×675, mark fallback | Last Verified | 2026-02-24 | Verified | Medium |
| X | Feed | Video Cover | Organic | 16:9 | 16:9, 1:1 | 1280×720 | — | Avoid bottom 10% | ≥720p | Ratio, safe zone, brand fit | 16:9 cover | Last Verified | 2026-02-24 | Verified | Medium |
| LinkedIn | Feed | Static Image | Organic | 1.91:1 | 1.91:1, 1:1 | 1200×628 | 1200×627 | Avoid bottom 20% on mobile (text overlay) | ≥1200px | Ratio, dimensions, readability, brand fit | 1.91:1 at 1200×628, mark fallback | Last Verified | 2026-02-24 | Verified | Medium |
| LinkedIn | Feed | Link Post / Link Preview | Organic | 1.91:1 | 1.91:1 | 1200×627 | — | Keep headline readable at thumbnail | ≥1200px | Ratio, dimensions, brand fit | 1.91:1 at 1200×627 | Last Verified | 2026-02-24 | Verified | Medium |
| LinkedIn | Feed | Carousel Card | Organic | 1:1 or 4:5 | 1:1, 4:5 | 1080×1080 or 1080×1350 | — | Centred content; consistent across cards | ≥1080px | Ratio, readability, card consistency | 1:1 at 1080×1080 | Last Verified | 2026-02-24 | Verified | Medium |
| TikTok | In-Feed | Static Image | Organic/Ads | 9:16 | 9:16 | 1080×1920 | ≥540×960 | Top 130px, bottom 250–480px, right 60–100px, left 44px (UI overlays) | ≥720p | Ratio, safe zone, dimensions, brand fit | 9:16 at 1080×1920 | Last Verified | 2026-02-24 | Verified | Medium |
| TikTok | In-Feed | Video Cover | Organic/Ads | 9:16 | 9:16 | 1080×1920 | — | Top 130px + bottom 480px clear | ≥720p | Ratio, safe zone, no critical text in zone | 9:16 cover | Last Verified | 2026-02-24 | Verified | Medium |

---

## Paste-Ready AI Instructions

**Using the table during generation:**
Before generating any marketing asset, resolve the output format using the Generation Preflight Spec Table based on platform, placement, and asset type. Apply the resolved aspect ratio and dimensions as hard generation constraints. Do not use generic/default dimensions when a matching platform spec exists. Attach the resolved spec metadata to the generated asset and use the same spec in QA validation. If no exact match exists, use the defined fallback behavior, mark `fallback_applied`, and lower confidence.

**QA comparison rule:**
During QA, validate the generated asset against the exact resolved preflight generation spec (not only generic platform rules). Compare actual dimensions/aspect ratio, platform placement fit, safe-zone risk, and branding alignment. If the asset fails due to format mismatch, return a specific reason and recommend or trigger Fix/Regenerate using the resolved preflight spec.

**Optional auto-fix rule for format-only failures:**
If QA fails only due to platform format/dimension mismatch, the system may auto-trigger a Fix/Regenerate flow using the resolved preflight generation spec, while preserving the original image and linking the new version to the original Asset ID.

---

## User Explicit Format Override (Xian — 2026-02-24 Addendum)

**Rule:** If the user explicitly requests a format (e.g. "square" / "1:1"), treat it as a high-priority generation constraint. Do NOT silently switch to another format.

**Logic:**
- If `requestedRatio` is provided AND is a valid allowed ratio for the platform+placement → use it, resolve matching dimensions, log `matched_user_intent`
- If `requestedRatio` is provided AND is NOT valid for the platform+placement → block preflight, return `adjusted_with_warning` with clear reason + allowed ratios listed
- If no `requestedRatio` provided → use platform default, log `platform_default`

**Resolver Logging (required on every generation):**

| `intentMatchStatus` | Meaning |
|---------------------|---------|
| `matched_user_intent` | Resolved spec matches user's explicit format request |
| `platform_default` | No user request — platform default applied |
| `adjusted_with_warning` | User requested invalid ratio; preflight blocked |
| `fallback_applied` | No exact spec found; fallback used |

**Preflight validation rule:** If user requests a valid format but resolver would choose differently → preflight must enforce the user's format. No silent substitution.

**Implementation:** `requestedRatio` parameter on `/api/marketing/generate-asset` and `resolvePreflightSpec()`.
