PixelLift

Role Matrix

A visual, brand-scoped permission builder that lets admins define who can view, apply, edit, approve, or publish presets per brand or collection. Simulate a user’s access before saving to prevent misconfigurations, speed onboarding, and protect brand integrity.

Requirements

Brand & Collection-Scoped Permission Model

"As a brand admin, I want to assign permissions by brand and collection so that each team member only sees and acts on relevant presets."

Description

Establish a granular, brand- and collection-scoped permission model that defines allowed actions—view, apply, edit, approve, publish—on resources like Style Presets, Collections, and Batch Jobs. Support role-based assignment with scoped overrides, brand isolation (multi-tenant), and inheritance rules (brand → collection). Provide an efficient evaluation engine with caching and indexing to resolve effective permissions at request time across the app and API. Include default system roles and migration of existing users into the new model.

Acceptance Criteria

Assign brand-level role with collection override

Given User U has role "Preset Editor" at Brand B And Collection C belongs to Brand B And a collection-level override on C grants "approve" and denies "publish" for U When U requests effective permissions for Preset P in Collection C via API Then the response includes allows: ["view","apply","edit","approve"] and denies: ["publish"] And POST /presets/{id}/publish returns 403 for Preset P in Collection C And POST /presets/{id}/approve returns 200 for Preset P in Collection C And for Preset Q in Collection D (same brand, no override), allows: ["view","apply","edit"] and denies: ["approve","publish"] And app UI buttons reflect the same permissions (approve enabled, publish disabled in C; approve/publish disabled in D)

Default system roles and permissions matrix

Rule: The following default roles exist and are assignable at brand scope with optional collection overrides - Brand Admin: allow {view, apply, edit, approve, publish} on {Style Presets, Collections, Batch Jobs} within brand; allow manage role assignments within brand - Preset Editor: allow {view, apply, edit} on {Style Presets, Batch Jobs}; view-only on Collections; deny {approve, publish} - Approver: allow {view, apply, approve} on {Style Presets, Batch Jobs}; view-only on Collections; deny {edit, publish} - Publisher: allow {view, apply, publish} on {Style Presets, Batch Jobs}; view-only on Collections; deny {edit, approve} - Operator: allow {view, apply} on {Batch Jobs using only approved presets}; view-only on {Style Presets, Collections}; deny {edit, approve, publish} - Viewer: allow {view} only on all resources in scope; deny {apply, edit, approve, publish} Validation: - An Operator creating a Batch Job with any unapproved preset returns 403 - A Publisher cannot approve a preset (returns 403) but can publish an approved preset (200) - A Viewer cannot access POST/PUT/PATCH/DELETE endpoints for any resource (403), and UI shows no action controls

Brand isolation across tenants

Given User U has assignments only within Brand A and none in Brand B When U calls GET /brands/B/style-presets or GET /style-presets?brand=B Then the API returns 403 Forbidden When U calls GET /style-presets without brand filter Then only Brand A presets are returned and total/count reflect Brand A data only And direct access to any resource by ID that belongs to Brand B returns 403 And cross-brand aggregation endpoints exclude Brand B data for U

Permission evaluation engine performance and cache invalidation

Given a steady-state load of ≥500 permission checks/second across ≥1,000 users and ≥5 brands When the system warms up Then p95 evaluation latency ≤25 ms and p99 ≤50 ms for cached checks And on cold cache (first check after deploy) p95 ≤150 ms And steady-state cache hit ratio ≥85% When an admin changes a user’s role or override Then all affected effective-permission cache entries are invalidated within 2 seconds across nodes And the very next check reflects the change (no stale allows beyond 2 seconds) And error rate from permission evaluation <0.1% over a 30-minute soak test

Resource-level enforcement across app and API

Given a user lacking a required action on a specific resource When they attempt that action via UI or API Then UI control is disabled/hidden and API responds 403 with error_code "ERR_FORBIDDEN" and reason "missing_permission:<action>" Validation matrix: - Style Presets: view | apply | edit | approve | publish enforced per effective permissions - Collections: view enforced for all roles with scope; edit restricted to Brand Admin; approve/publish not exposed for Collections unless explicitly permitted by role (default deny) - Batch Jobs: view | apply | publish enforced per effective permissions; edit limited to job owner with edit permission or Brand Admin And list endpoints exclude resources the user cannot view; counts reflect only viewable resources

Permission precedence and inheritance resolution

Rules: - Default: no assignment implies no access - Same-scope multiple roles: effective allows = union(allows); effective denies = union(denies); any deny overrides corresponding allow - Cross-scope precedence: collection overrides take precedence over brand assignments; effective permissions at collection = (brand allows ∪ collection allows) − (brand denies ∪ collection denies); any explicit deny wins - Cross-brand isolation: roles from one brand never apply to another - Mixed outcomes are consistent across UI and API for the same user/resource/action

Migration of existing users into new model

Given a pre-migration snapshot of each user’s effective permissions by brand and collection And default system roles are available When the migration script executes on staging against production-like data Then 100% of users retain identical effective permissions post-migration (no loss, no escalation) And 0 users gain access to new brands/collections they did not previously access And 0 users are left unmapped; otherwise migration fails with a report And the migration is idempotent: re-running produces no changes And a production run completes within the maintenance window and logs success for 100% of assignments

Visual Role Matrix Builder UI

"As an admin, I want a clear matrix UI to manage role permissions so that I can configure access quickly and confidently."

Description

Deliver a visual matrix builder that lets admins assign actions to roles across brands and collections through a grid UI. Include bulk select, drag-to-fill, search/filter by user, role, brand, collection, and resource type, plus keyboard accessibility and WCAG AA compliance. Show immediate visual cues for inherited vs. explicit permissions and pending changes. Support draft mode with reversible changes and clear save/cancel, and integrate with the simulator for instant previews.

Acceptance Criteria

Grid-based assignment of actions to roles per brand/collection

Given an admin opens the Role Matrix for a selected scope (All Brands/Specific Brand/Specific Collection) When the matrix loads Then the grid displays roles as rows and actions (View, Apply, Edit, Approve, Publish) across the selected resources with current effective states visible And empty/error states are not shown when data is available Given roles, brands, and collections exist When the admin toggles a permission cell Then the cell reflects the new state immediately in the UI as a pending explicit change without persisting to the server And a pending-changes counter increments Given at least one pending change exists When the admin clicks Save Then all pending changes are persisted and the UI updates to show them as explicit (not pending) And a success toast appears within 2 seconds Given a save attempt is made When the server responds with an error Then an error message is displayed with retry And no changes are persisted and pending indicators remain Given up to 50 roles and 200 resources When the matrix first renders Then time to interactive is under 2 seconds on a standard laptop (i5+, 8GB RAM, latest Chrome)

Bulk select and drag-to-fill permissions

Given the matrix is visible When the admin clicks a row header (role) or column header (action) Then all visible cells in that row/column are selected for bulk edit Given multiple cells are selected via mouse drag or Shift+Arrow keys When the admin presses Space/Enter or uses the bulk toggle control Then the selected cells all change to the chosen state and are marked as pending And a confirmation chip shows the number of cells affected Given some selected cells are already explicitly set When a bulk operation is applied Then existing explicit states are overwritten to the new explicit state And inherited states become explicit with the new value Given a bulk operation was just applied When the admin presses Ctrl+Z or clicks Undo Then the last bulk change is reverted without persisting Given very large selections (≥1000 cells) When a bulk operation is applied Then the UI remains responsive and completes the update within 1 second

Search and filter by user, role, brand, collection, and resource type

Given the admin enters text in the search box When the query matches roles, users, brands, collections, or actions Then the matrix filters to matching entities and highlights the match Given filters are applied for Role, Brand, Collection, and Resource Type When multiple filters are combined Then the result set reflects the intersection of all filters And a visible chip list shows active filters with one-click clear Given a specific user is selected in the User filter When the matrix updates Then only roles/resources relevant to that user are shown And effective permissions for that user are highlighted distinct from global role defaults Given a dataset of up to 5,000 visible cells post-filter When typing or changing filters Then results update within 300 ms on a standard laptop Given no results match When filters are applied Then an empty state appears with a clear-filters action

Keyboard navigation and WCAG AA compliance

Given the matrix is focused When the admin uses Tab/Shift+Tab Then focus moves through interactive controls in a logical order with a visible focus indicator Given a cell has focus When the admin presses Arrow keys Then focus moves to the adjacent cell; Space/Enter toggles the cell state; Shift+Arrow extends selection for range edit Given a screen reader is active When a cell receives focus Then it announces role, action, resource, current state (checked/unchecked), and source (explicit/inherited/pending) Given the UI is rendered When evaluated for contrast Then all text and interactive elements meet WCAG 2.2 AA contrast (≥4.5:1; large text ≥3:1) Given all interactive elements When tested with keyboard only Then there are no keyboard traps; skip links are available to jump to the matrix and filters; all controls have accessible names and roles Given ARIA attributes are required When cells and controls are rendered Then proper semantics (aria-checked, aria-pressed, aria-describedby) are present and valid

Visual indicators for inherited, explicit, and pending states

Given the matrix is visible When permissions are displayed Then inherited, explicit, and pending states are visually distinct using both color and iconography And a legend explains the indicators Given a cell is inherited When the admin hovers or focuses the cell Then a tooltip reveals the inheritance source (e.g., Brand default, Role policy) without obscuring the cell Given a cell is toggled during the session When the state changes Then a pending badge appears on the cell and a global pending count updates in the header Given multiple pending changes exist When the admin clicks the Pending filter Then only cells with pending status are shown And clearing the filter restores the full view

Draft mode with reversible changes and clear save/cancel

Given no changes have been made When the admin interacts with the matrix Then Save and Cancel are disabled until the first change occurs Given at least one change is made When the draft banner appears Then Save and Cancel become enabled and show the number of pending changes Given pending changes exist When the admin clicks Cancel Then a confirmation dialog appears to discard or keep changes And choosing Discard reverts all cells to their prior effective state and clears the draft Given pending changes exist When the admin navigates away or attempts to close the page Then an unsaved-changes prompt appears preventing accidental loss Given a single cell was changed When the admin uses Revert on that cell Then the cell returns to its prior effective (inherited/explicit) state without affecting others

Simulator integration for instant previews before save

Given the simulator panel is open When the admin selects a user and scope (Brand or Collection) Then the simulator shows the user’s effective permissions for presets and related actions before any new changes are saved Given the admin toggles permissions in the matrix When the simulator is visible Then the simulator updates within 300 ms to reflect the predicted effective access under the draft changes and is clearly labeled as Preview Given incompatible or conflicting changes are made When the simulator evaluates the draft Then conflicts are highlighted with guidance on which role/resource causes the conflict Given Save is clicked When persistence succeeds Then the simulator switches from Preview to Live and matches the post-save matrix state

Access Simulator (What‑If) Preview

"As an admin, I want to simulate a user’s access before saving so that I can catch and prevent misconfigurations."

Description

Provide a what-if access simulator that previews a specific user’s effective permissions before saving changes. Allow testing by selecting a user and/or a set of roles, brands, and collections, and display allowed/denied actions with explanations (source role, inheritance, conflicting rules). Generate warnings for risky configurations and show the impact delta compared to current production settings.

Acceptance Criteria

Simulate Existing User’s Effective Permissions

Given I am an Admin on the Role Matrix And I open the Access Simulator When I select an existing user Then the simulator preloads the user’s current roles and scoped brands/collections And the current production effective permissions are captured as the baseline for delta And the Simulate action becomes available

Simulate Ad Hoc Roles/Brands/Collections (No User)

Given I am on the Access Simulator When I do not select a user but select one or more roles and at least one brand or collection Then the simulator calculates effective permissions for the hypothetical identity And if no role is selected, the Simulate action remains disabled with a validation message

Show Allowed/Denied With Explanations Per Scope

Given a simulation has been run Then for each brand/collection scope the actions View, Apply, Edit, Approve, Publish are displayed with Allowed or Denied And each action provides a Why explanation including source role(s), rule type (allow/deny), scope, and inheritance details And if multiple roles contribute, all contributors are listed with the applied precedence noted

Highlight Conflicts and Resolution Rationale

Given at least one conflicting rule exists across roles or scopes for the simulated identity When the simulation is run Then the UI flags the conflict on the affected action and scope And the simulator explicitly states which rule prevails and the resolution rationale (e.g., precedence, specificity) And the explanation references the originating role and scope for the prevailing and losing rules

Risky Configuration Warnings

Given simulation results differ from production When the simulated identity would gain any new Approve or Publish permission in any brand or collection Then a High-risk change warning is displayed listing affected brands/collections and actions And when any existing Approve or Publish permission would be removed Then a Potentially disruptive change warning is displayed listing affected brands/collections and actions And when the scope of any action expands from one brand/collection to more than one Then a Scope expansion warning is displayed with before/after counts

Delta vs Production Summary and Details

Given a baseline of current production permissions exists When the simulation results differ from production Then a Delta panel shows counts of Added, Removed, and Changed permissions by action and by brand/collection And a detailed list of deltas is displayed with before → after state per action and scope And each delta item links to its corresponding Why explanation

Simulation Is Non-Destructive and Resettable

Given I have staged selections and run a simulation Then no role, scope, or permission changes are persisted to production And when I click Reset, the simulator clears staged selections and results back to the baseline And when I navigate away or refresh, no permission changes are applied to production

Approval & Publish Gate Enforcement

"As a brand owner, I want publishing gated by approval so that only vetted presets go live and protect brand integrity."

Description

Enforce approval and publishing rules across PixelLift. Only users with Approve can transition presets to Approved; Publish requires Approved status and the Publish permission within the same scope. Apply these gates to batch operations, API endpoints, and integrations, with clear error messages and UI indicators. Support configurable review requirements (e.g., dual-approval) per brand, and block cross-brand publishes.

Acceptance Criteria

Approval Gate: Only Approvers Can Set Preset to Approved

Given a user without Approve permission in Brand A and a preset within Brand A in Review When the user attempts to approve via the UI Then the Approve control is disabled and a tooltip states "Requires Approve permission in Brand A" Given the same user and preset When the user calls the approve API endpoint Then the request is rejected with HTTP 403 and error code PERMISSION_DENIED including fields action=approve, requiredPermission=Approve, scopeType=brand, scopeId=Brand A, entityType=preset, entityId=<presetId>; and the preset status remains unchanged Given a user with Approve permission in Brand A and the preset in Review When the user approves Then the preset status transitions to Approved and an audit log records approver userId, timestamp, scopeId, previousStatus, newStatus=Approved

Publish Gate: Requires Approved Status and Publish Permission in Same Scope

Given a preset in Approved within Brand A and a user with Publish permission in Brand A When the user publishes via UI or API Then the operation succeeds (HTTP 200), the preset status becomes Published, and an audit log records publisher userId, timestamp, scopeId, previousStatus=Approved, newStatus=Published Given a preset not in Approved within Brand A and any user When the user attempts to publish Then the request is rejected with HTTP 409 PRECONDITION_FAILED and message "Preset must be Approved before publish"; no status change occurs Given a preset in Approved within Brand A and a user without Publish in Brand A When the user attempts to publish Then the request is rejected with HTTP 403 PERMISSION_DENIED including requiredPermission=Publish and scopeId=Brand A; no status change occurs

Dual-Approval: Configurable Review Requirements Per Brand

Given Brand B has dual-approval requirement set to 2 and a preset in Review within Brand B When the first eligible approver approves Then the preset is not yet Approved, approvalCount=1, and the approver is recorded; the same user cannot approve again (HTTP 409 DUPLICATE_APPROVAL) Given the same preset and a second distinct user with Approve in Brand B When the second user approves Then the preset status becomes Approved and both approvals are recorded with userId and timestamps Given Brand C has dual-approval disabled (or set to 1) When a user with Approve in Brand C approves a preset in Review Then the preset immediately becomes Approved with a single approval recorded

Batch Operations: Per-Item Gate Enforcement and Result Summary

Given a batch request to approve or publish multiple presets with mixed states and permissions When the batch operation is executed via UI or API Then each item is evaluated independently against approval/publish gates; successful items are processed, and failed items return itemized errors with HTTP status per item (e.g., 403 PERMISSION_DENIED, 409 PRECONDITION_FAILED) including action, requiredPermission (if applicable), and scope And the batch response includes a per-item results array and aggregate counts (total, succeeded, failed); processing continues despite failures in other items; each item update is atomic

API and Integrations: Consistent Gate Enforcement and Error Schema

Given any API or integration endpoint that changes preset status (approvePreset, publishPreset, partner integrations) When a caller without required permission in the preset’s scope attempts the action Then the endpoint responds with HTTP 403 PERMISSION_DENIED and a standardized error body containing fields: code, message, action, requiredPermission, scopeType, scopeId, entityType, entityId, correlationId Given the preset state does not meet preconditions (e.g., publish on non-Approved) When the action is requested Then the endpoint responds with HTTP 409 PRECONDITION_FAILED and the standardized error body; no side effects occur Given the same action is attempted via different channels (UI, REST API, integration) When gates are violated Then the error codes and messages are consistent across channels

Cross-Brand Publish Block

Given a preset scoped to Brand A and a user with Publish permission only in Brand B (or in both A and B) When the user attempts to publish the Brand A preset into Brand B (e.g., targetBrandId=Brand B) Then the request is rejected with HTTP 403 SCOPE_MISMATCH and message "Cross-brand publish is blocked"; no change occurs to the preset or Brand B assets; an audit log records the denied attempt with sourceBrandId and targetBrandId Given a publish attempt without an explicit target brand where the preset scope is Brand A When processed Then the publish only targets Brand A; any attempt to route output to another brand is blocked with the same error

UI Indicators and Messaging for Gate States

Given a user views a preset details page When the user lacks Approve or Publish permissions or the preset is not in the required state Then the Approve/Publish controls are disabled with tooltips that explicitly state the unmet requirement (e.g., "Requires Publish permission in Brand A" or "Preset must be Approved to publish") Given dual-approval is required and exactly one approval has been recorded When the page loads Then the UI displays an approval progress indicator (e.g., 1/2 approvals) and the Approve button is disabled for the user who already approved Given an action fails due to gate enforcement When the UI shows an error banner/toast Then the message text matches the API error (code and reason) and includes the scope; the user is provided a link or CTA to request access or contact an admin

Conflict Detection & Safe‑Guard Validation

"As an admin, I want automated validation of role changes so that I avoid breaking access or exposing sensitive presets."

Description

Add pre-save validation and conflict detection that scans role matrices for contradictory, over-broad, or unsafe policies. Detect cases like publish without approve, approve without view, dangling roles without members, no remaining admin for a brand, or cross-brand exposures. Provide inline warnings, remediation suggestions, and hard blocks for critical violations.

Acceptance Criteria

Hard Block: Publish Without Approve

Given an admin edits the Brand X role matrix And a role grants Publish on any preset scope within Brand X And the same role’s effective permissions (including inherited roles) do not grant Approve on the same scopes When the admin attempts to save Then the save is blocked and no changes persist And an inline error is shown at each offending permission with severity=Critical and code=PUB_NO_APPROVE And the error lists the affected role(s) and scope(s) count And a remediation suggestion is available to add Approve to the matching scopes or remove Publish And the Save action is disabled until all PUB_NO_APPROVE conflicts are resolved And an audit log entry is recorded with action=validation_blocked, code=PUB_NO_APPROVE, brand=Brand X, count >= 1

Warning: Approve Without View

Given an admin edits the Brand X role matrix And a role grants Approve on any preset scope within Brand X And the same role’s effective permissions do not grant View on the same scopes When validation runs (on change, simulate, or pre-save) Then an inline warning appears with severity=Warning and code=APP_NO_VIEW for each affected scope And a “Add View for affected scopes” quick-fix is available And saving is allowed without blocking And an audit log entry is recorded with action=validation_warning, code=APP_NO_VIEW, count >= 1

Warning: Dangling Roles Without Members

Given the role matrix contains one or more roles with zero assigned members or groups When validation runs Then a warning appears with severity=Warning and code=DANGLING_ROLE for each such role And a remediation suggestion is available to assign members or archive the role And saving is allowed And the warning summary displays total dangling roles count

Hard Block: No Remaining Brand Admin

Given changes would remove or demote the last user/group with Admin capability for Brand X When the admin attempts to save Then the save is blocked and no changes persist And an inline error appears with severity=Critical and code=NO_BRAND_ADMIN And the error lists current candidates who meet Admin criteria before the change (=0 after change) And a remediation suggestion is available to assign Admin to at least one user/group for Brand X And Save is disabled until NO_BRAND_ADMIN is resolved And an audit log entry is recorded with action=validation_blocked, code=NO_BRAND_ADMIN, brand=Brand X

Hard Block: Cross-Brand Exposure

Given a permission grants View/Apply/Edit/Approve/Publish on Brand B to a principal whose brand membership excludes Brand B When validation runs or on save Then the change is blocked with severity=Critical and code=CROSS_BRAND_EXPOSURE And the error lists the principal(s), source brand membership, and target brand(s) exposed And a remediation suggestion is available to restrict scope to allowed brands or update membership And Save is disabled until all CROSS_BRAND_EXPOSURE conflicts are resolved And an audit log entry is recorded with action=validation_blocked, code=CROSS_BRAND_EXPOSURE, count >= 1

Consistency: Simulation Mirrors Save Validation

Given the admin runs “Simulate access as User U” for Brand X before saving And conflicts exist per PUB_NO_APPROVE, APP_NO_VIEW, DANGLING_ROLE, NO_BRAND_ADMIN, or CROSS_BRAND_EXPOSURE When simulation is executed Then the simulation pane displays the same validation items with identical codes, severities, counts, and affected entities as pre-save validation And resolving a conflict in the matrix updates the simulation validation list in real time (<300 ms p95) And running pre-save validation after simulation yields identical results

Performance: Validation at Scale

Given a role matrix up to 200 roles, 10 brands, 500 presets/collections, and up to 10,000 permission edges When the user edits any single permission Then inline validation feedback appears within 200 ms p95 and 400 ms p99 And running “Simulate access” completes within 500 ms p95 and 1000 ms p99 And “Save” pre-commit validation completes within 1000 ms p95 and 2000 ms p99 And validation does not freeze the UI thread (>55 FPS) during feedback rendering

Audit Trail & Versioned Policy History

"As a compliance officer, I want versioned audit history of permission changes so that I can trace decisions and restore previous states."

Description

Implement end-to-end audit logging and versioned history for all permission-related changes, including who changed what, when, and the before/after diff. Support per-brand filtering, CSV/JSON export, immutable logs for compliance, and one-click rollback to a prior version with dependency checks. Surface recent changes within the Role Matrix UI and via API.

Acceptance Criteria

Audit Event on Role Matrix Permission Change

Given an admin with manage-permissions privileges edits a preset permission within the Role Matrix for brand X When they change a user's ability and click Save Then the system records an audit event with fields: event_id, tenant_id, brand_id, actor_id, actor_email, action='permission.update', resource_type='preset_permission', resource_id, timestamp (UTC ISO 8601), request_id, ip, user_agent, before_state, after_state, diff (JSON Patch) And the event persists successfully before the save response is returned And the policy version for brand X increments by 1

Versioned Policy History Retrieval and Diff

Given there are at least two saved versions of the brand X permission policy When a reviewer opens the policy history and selects versions N and N-1 Then the UI shows a human-readable before/after summary and a machine-readable diff (JSON Patch) And selecting View raw returns the exact stored before_state and after_state JSON for both versions And the API returns versions with version number, created_at, actor_id, actor_email, and optional changelog message

Per-Brand Audit Filtering and Isolation (UI and API)

Given audit events exist for brands X and Y When a compliance user applies filters brand_id=X and a date range Then only events for brand X within the date range are returned And no events from brand Y are included And results are paginated (default page size 50) and sortable by timestamp desc And the API endpoint for audit retrieval with the same filters enforces RBAC so users without audit:view for brand X receive 403

CSV and JSON Export of Filtered Audit Logs

Given a user has applied filters to the audit log for brand X When they export to CSV Then the downloaded file contains only the filtered result set up to the export limit of 50,000 records and includes headers: event_id, tenant_id, brand_id, timestamp, actor_email, action, resource_type, resource_id And initiating a JSON export yields newline-delimited JSON (NDJSON) with the same records and field names And the API supports equivalent exports and returns 202 with job_id for async exports exceeding 5,000 records, followed by a downloadable URL when complete

Immutable Audit Log Enforcement and Tamper Evidence

Given an audit event exists When any user attempts to modify or delete the event via UI or API Then the operation is rejected with 405 or 403 and the message 'Audit logs are immutable' And there is no supported API to update or delete audit events And a proof endpoint returns a valid tamper-evident hash (e.g., chain or Merkle proof) for the event upon request

One-Click Policy Rollback with Dependency Checks

Given a policy history for brand X with current version N and a prior version N-1 When an admin selects Rollback to version N-1 and confirms Then the system runs dependency checks for referenced presets, roles, and collections and lists any blockers by ID and reason And if no blockers exist, the system creates version N+1 identical to N-1, marks it current, and records an audit event action='policy.rollback' linking versions And if blockers exist, the rollback is aborted with no state changes and a clear error summary

Surface Recent Changes in Role Matrix UI and via API

Given a user opens the Role Matrix for brand X When the page loads Then a Recent Changes panel displays the 20 most recent permission-related events for brand X with actor, relative time, and a short summary And clicking an item opens a detailed diff view for that event And GET /audit/recent?brand_id=X&limit=20 returns the same events in the same order

Permissions API & Webhook Notifications

"As a platform integrator, I want APIs and webhooks for permission management so that I can sync PixelLift with our identity provider."

Description

Expose secured REST/GraphQL endpoints and SDK helpers for managing roles, assignments, scopes, and permission checks. Include a lightweight authorize endpoint to verify an action on a resource, and webhooks for permission changes to allow external cache invalidation and downstream sync. Enforce OAuth scopes and rate limits, and document endpoints with examples and error codes.

Acceptance Criteria

OAuth Scope Enforcement Across REST and GraphQL

- Given a valid OAuth 2.0 access token containing the required scopes for an endpoint/field, when the client calls that REST endpoint or GraphQL field, then the server authorizes the call and returns a 2xx response with only data allowed by the scopes. - Given a token missing a required scope, when calling a REST endpoint, then the server returns 403 with body { error: { code: "insufficient_scope", requiredScopes: [..], providedScopes: [..], requestId } }. - Given a token missing a required scope, when calling a GraphQL field, then HTTP status is 200 and the response contains errors[0].extensions.code = "INSUFFICIENT_SCOPE" and extensions.requiredScopes listing missing scopes; no unauthorized data is returned. - Given an invalid or expired token, when calling any endpoint, then the server returns 401, includes WWW-Authenticate header, and body error.code = "invalid_token" (REST) or a top-level 401 (GraphQL HTTP) with the same error shape in extensions. - Given a token scoped to a specific brand/collection, when the request targets a different brand/collection, then the server returns 403 with error.code = "scope_mismatch". - For every REST route and GraphQL field, the required scopes and applicable brand/collection constraints are machine-readable (e.g., OpenAPI x-required-scopes / GraphQL directive) and validated in contract tests.

Lightweight Authorize Endpoint Decision Semantics and Performance

- Given POST /v1/authorize with subjectId, action, resourceType, resourceId, and optional context { brandId, collectionId }, when the subject is permitted, then the server returns 200 with { allow: true, reasons: ["ALLOWED"], decisionId, evaluatedAt } (ISO-8601). - Given the same inputs when not permitted, then the server returns 200 with { allow: false, reasons: ["insufficient_scope" | "no_matching_role" | "assignment_expired" | "resource_not_found"], decisionId, evaluatedAt }. - Given an unknown action/resourceType or malformed payload, then the server returns 400 with error.code = "validation_error" and field-level details. - Given repeated identical authorize requests under consistent state, then allow is deterministic and decisionId is traceable in audit logs. - Performance: p95 latency for /v1/authorize <= 100ms and p99 <= 250ms under documented reference load; SLIs and test harness validate targets.

Roles, Assignments, and Scopes Management CRUD with Audit

- POST /v1/roles creates a role within a brand scope; unique name per brand is enforced; success returns 201 with role.id; duplicates return 409 with error.code = "duplicate_role". - PATCH/PUT /v1/roles/{id} requires If-Match ETag; stale ETag returns 412; success returns 200 and a new ETag. - DELETE /v1/roles/{id} on a role with active assignments returns 409 with error.code = "role_in_use"; deleting an unassigned role returns 204. - POST /v1/assignments creates a user→role assignment with optional collection scope and optional expiration; duplicates return 409 with error.code = "duplicate_assignment"; expired assignments are not considered in authorize decisions. - Scope validation: unknown brandId/collectionId returns 404 with error.code = "scope_not_found". - All write operations (create/update/delete) generate audit records with actorId (from token), action, targetType, targetId, scope, requestId, and timestamp; GET /v1/audit supports filtering by actorId, targetId, and time range.

Webhook Notifications for Permission Changes

- Events emitted: role.created, role.updated, role.deleted, assignment.created, assignment.updated, assignment.deleted, scope.updated; each event payload includes id, type, occurredAt (ISO-8601), brandId, collectionId (if any), actorId, requestId, and data.{...}. - Delivery timeliness: 99% of events are delivered to subscribed endpoints within 30 seconds of the committing API write. - Each webhook request includes X-PixelLift-Signature with HMAC-SHA256 over timestamp + body and X-Event-ID; receivers can validate using a shared secret; replays older than 5 minutes (by signature timestamp) are rejected by the platform. - Retry policy: non-2xx responses trigger exponential backoff retries for up to 24 hours; delivery stops after a 2xx; 410 disables the endpoint; 3xx is treated as failure and retried. - Idempotency: the same X-Event-ID is never reused; receiving the same event twice must be safe; platform deduplicates per endpoint. - Endpoint management: a webhook endpoint must be verified before activation via a verification event; a test event can be sent on demand from the dashboard/API.

SDK Helpers Parity and Local Decision Caching

- Official SDK provides helpers: authorize(subjectId, action, resourceType, resourceId, context?), createRole, updateRole, deleteRole, createAssignment, deleteAssignment, listRoles, listAssignments; all helpers map 1:1 to API endpoints and shapes. - The SDK exposes a verifyWebhookSignature(payload, headers, secret) utility that validates X-PixelLift-Signature and timestamp window. - The SDK’s authorize helper supports in-memory caching keyed by { subjectId, action, resourceType, resourceId, brandId, collectionId }; default TTL = 60s, negative TTL = 15s; cache can be disabled; tests verify correctness and TTL behavior. - Error handling parity: API error codes are surfaced as typed exceptions with code, message, details, requestId; TypeScript types are provided for all inputs/outputs. - Retries and backoff for transient 5xx/429 are implemented with jitter; maximum retry duration and attempts are configurable and documented.

Rate Limiting and Quotas Visibility

- All REST and GraphQL requests are subject to per-client rate limits; the /v1/authorize endpoint uses a separate higher-capacity bucket; limits are configurable per plan and environment. - When a limit is exceeded, REST responses return 429 with headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After; GraphQL returns HTTP 429 with the same headers. - Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to inform consumption. - Contract tests validate correct header presence and decrement behavior, and that exceeding limits produces 429 within the same window.

API Documentation, Examples, and Error Codes

- OpenAPI 3.1 spec for REST is published at /docs/openapi.json and includes endpoint descriptions, parameters, request/response schemas, required OAuth scopes, and error models; GraphQL SDL is published at /graphql/schema and includes field-level authorization directives. - Developer docs include runnable examples (cURL, JavaScript/TypeScript, Python) for: creating a role, assigning a role, checking authorization, and handling webhooks; examples execute successfully against a sandbox. - Error format is standardized across REST ({ error: { code, message, details?, requestId } }) and GraphQL (errors[].extensions.code, errors[].extensions.requestId); error code catalog is documented with remediation guidance. - Versioning and deprecation: new versions are announced with changelog entries; deprecated endpoints emit Sunset and Deprecation headers and are documented with end-of-life dates.

Draft Sandbox

A safe workspace to iterate on preset changes without touching live outputs. Batch-test drafts on sample images, compare side-by-side with current presets, and promote with one click when results meet standards—enabling confident experimentation with zero production risk.

Requirements

Draft Preset Versioning

"As a brand manager, I want to create draft versions of style presets without affecting live outputs so that I can experiment safely and refine styles before rollout."

Description

Enable creation of draft versions of existing style presets that are fully isolated from production. Each draft carries a unique version ID, metadata (author, timestamp, change notes), and a non-production flag. Drafts support granular edits (retouch intensity, background settings, crop rules) and a change-diff view against the current live preset. Draft artifacts are stored separately and never applied to live jobs until promotion. Provide APIs and UI to create, edit, clone, archive, and delete drafts, with audit logging for compliance. This ensures safe experimentation and repeatability while integrating with the existing preset library and project structure.

Acceptance Criteria

Create Draft from Live Preset (UI)

Given an Editor is viewing a live preset When the user clicks "Create Draft" and provides optional change notes (0–500 chars) Then a draft version is created with a unique versionId (UUIDv4), linked to the parent presetId, and nonProduction=true And metadata is recorded: authorId=current user, createdAt=server UTC ISO-8601 timestamp, changeNotes as provided And the draft appears in the Preset Library under the parent preset with label "Draft" And no live jobs reference the draft and it is excluded from production preset selectors

Draft CRUD via API with Auth and Validation

Given a client with scope presets.drafts.write When the client calls POST /presets/{presetId}/drafts with a valid payload Then the API returns 201 with the new draft resource including versionId and nonProduction=true And invalid inputs (unknown presetId, missing required fields, invalid values) return 404/400 with error codes Given a client with scope presets.drafts.read When the client calls GET /presets/{presetId}/drafts?status=active&limit=50 Then the API returns 200 with paginated results, totalCount, and filters applied When the client calls PATCH /presets/{presetId}/drafts/{versionId} with If-Match=ETag and valid changes Then the API returns 200 and updates only the draft fields; concurrent edits without matching ETag return 412 When the client calls POST /presets/{presetId}/drafts/{versionId}:clone Then the API returns 201 with a new draft version carrying over fields and a new versionId and authorId=current user When the client calls POST /presets/{presetId}/drafts/{versionId}:archive Then the draft status becomes archived, editable=false, and archivedAt is set; repeated archive requests are idempotent (200) When the client calls DELETE /presets/{presetId}/drafts/{versionId} Then the draft is soft-deleted (recoverable for 30 days) and deletes are blocked if the draft has active sandbox runs (409)

Granular Draft Editing (Retouch, Background, Crop)

Given a draft is open in the editor When the user sets retouchIntensity to a value between 0 and 100 inclusive Then validation passes and the value is saved; values outside this range are rejected with inline error When the user sets background.mode to one of [remove, solid, transparent, scene] and background.color to a valid hex when required Then the draft saves successfully and previews update using draft values When the user edits cropRules (aspectRatios, focalPoint, padding) Then changes are persisted to the draft only, not the live preset, and appear in the draft JSON And saving the draft returns success within 500 ms under normal load

Draft vs Live Change-Diff View

Given a draft exists for a live preset When the user opens Compare with Live Then the UI displays only fields that differ, with before (live) and after (draft) values side-by-side And nested changes (arrays/objects) are diffed by path and highlighted And unchanged fields are hidden by default with an option to Show All And the diff can be exported as JSON containing only changed paths And the view loads within 1 second for presets up to 50 KB

Draft Isolation and Storage of Artifacts

Given the user runs a sandbox render using a draft When processing completes Then all generated artifacts are stored under /drafts/{presetId}/{versionId}/ and are not listed in any production bucket or CDN path And artifacts are tagged with nonProduction=true metadata And draft outputs are watermarked "DRAFT" in the UI preview And live job pickers and automations do not offer draft versions

Audit Logging for Draft Lifecycle Actions

Given a user performs create, edit, clone, archive, or delete on a draft When the action completes Then an audit log entry is created with actorId, presetId, draftVersionId, action, timestamp (UTC ISO-8601), requestId, and before/after snapshot hashes And audit entries are immutable and retrievable via GET /audit?entity=draft&draftVersionId={id} And delete and archive require a non-empty change note; otherwise the action is rejected with 400

UI Safeguards and Permissions

Given a Viewer role opens a live preset Then the Create Draft and Edit actions are hidden Given an Editor role opens a live preset When attempting to delete a draft Then the UI requires type-to-confirm of the draft versionId and shows impact summary (active sandbox runs, last edited) before enabling Delete And permission checks are enforced server-side; unauthorized actions return 403 And within the Preset Library, Drafts are visually labeled and sortable by createdAt and author

Sample Set Selector

"As a content lead, I want to build a representative sample set for draft testing so that results reflect real catalog diversity and edge cases."

Description

Provide tools to define and persist representative sample image sets used for testing drafts. Users can pick images manually or by rules (recent uploads, product tags, collections, SKU coverage, image aspect ratios, lighting conditions). Support randomization with a fixed seed for repeatability, caps on sample size, and dataset pinning per workspace or preset. Integrate with the media library for fast filtering and ensure privacy controls (exclude customer images, respect folder permissions). The outcome is a consistent, realistic test bed that surfaces edge cases and reduces bias in evaluations.

Acceptance Criteria

Manual Sample Set Selection and Persistence

Given I have access to the Media Library in Workspace W within the Draft Sandbox And I can view only images I have permission to access When I manually select N images and save the sample set named "Summer Shoes Draft Set" Then the system persists the set with exactly N unique image IDs And the saved set is listed under Workspace W > Sample Sets with the correct name and count And reopening the selector shows the same N images marked as selected And an audit record is created capturing user, timestamp, selection method = manual, and image count

Rule-Based Selection for Tags, Collections, SKU Coverage, Aspect Ratio, and Lighting

Given I open the Rule Builder for Sample Set Selector When I configure rules including: - Uploaded within last 30 days - Product tags include any of ["summer","sandals"] - Collections include any of ["Shoes","Sale"] - SKU coverage requires at least one image per SKU in [S1,S2,S3] - Aspect ratio in {1:1, 4:5} - Lighting condition in {studio, low_light} And I set a sample size cap K Then the preview shows an eligible pool that matches all rules and is deduplicated And generating the sample returns exactly min(K, pool size) images And each SKU in [S1,S2,S3] is represented by at least one image unless no eligible images exist for that SKU, in which case a warning lists the missing SKUs And saving the rules persists them and regenerates the same results upon reopen if the underlying library has not changed and randomization is disabled

Seeded Randomization for Repeatable Samples

Given I enable Randomize with seed ABC123 and set cap K And the eligible pool size M is at least K When I generate a sample set Then the selected image ID list is deterministic for seed ABC123 And regenerating with the same seed and unchanged pool returns an identical ID list And changing the seed to DEF456 returns a non-identical ID list And the saved sample set metadata includes the seed and pool criteria

Sample Size Cap Enforcement and Validation

Given the eligible pool size is M When I set the sample size cap to K and generate a sample Then the resulting sample contains exactly min(M, K, SystemMax) images And if K exceeds SystemMax, the UI informs me the cap was reduced to SystemMax and displays the final count And if K is not a positive integer, form validation blocks saving and shows an inline error message

Dataset Pinning per Workspace and Preset

Given a saved sample set S exists When I pin S to Workspace W and to Preset P Then opening Draft Sandbox in Workspace W with Preset P preselects S as the default dataset And switching to a different preset P2 preselects the dataset pinned to P2 or none if unpinned And users without access to Workspace W cannot view or use S And unpinning S removes it as the default while keeping it available in the sample set list if permissions allow

Privacy Controls and Folder Permission Enforcement

Given some images are flagged CustomerContent = true or are located in folders I do not have permission to access When I search, filter, or build a sample set manually or by rules Then images flagged CustomerContent = true or in unauthorized folders do not appear in results And attempts to add such images by direct ID return a permission error and do not modify the sample set And previews, comparisons, and exports exclude such images And an audit entry records each blocked attempt with user, timestamp, and reason

Media Library Integration and Performance

Given a media library with up to 50,000 images When I apply filters (recent uploads, tags, collections) and paginate through results Then initial filter results render within 2 seconds at the 95th percentile And subsequent page loads render within 1 second at the 95th percentile And selected images remain selected across pagination and when filters change but still include those images And the UI displays the eligible pool count and current selected count in real time

Batch Draft Processing

"As a studio operator, I want to batch-run drafts on sample images so that I can evaluate results at scale quickly and reliably."

Description

Execute draft presets on selected sample sets via a scalable batch engine with queuing, concurrency controls, and progress tracking. Support resumable jobs, per-workspace quotas, GPU utilization, and cost guardrails. Outputs are stored as ephemeral draft results with TTL and content-addressed caching to avoid reprocessing identical inputs. Provide job telemetry (ETA, throughput, failures), structured logs, and deterministic settings for fair comparisons. This enables rapid, controlled experimentation across hundreds of images without impacting production resources.

Acceptance Criteria

Queueing and Concurrency for Batch Drafts

Given a sample set of 500 images and a draft preset and concurrency_limit=8 When the job is submitted Then no more than 8 images are processed concurrently at any time And remaining images are queued And queue_depth and active_worker_count are observable via the job status API Given concurrency_limit is updated from 8 to 4 while a job is running When the update is applied Then active_worker_count converges to 4 within 10 seconds without aborting in-flight tasks Given two jobs from the same workspace with FIFO scheduling enabled When both are submitted Then tasks are scheduled in FIFO order per workspace And cross-workspace fairness is maintained per global scheduler policy

Progress, ETA, Throughput, and Failure Telemetry

Given a running job When requesting status via API Then the response includes total, processed, succeeded, failed, queued counts; throughput_images_per_min; estimated_time_remaining_seconds; started_at; updated_at Given progress changes during execution When 10 seconds pass Then updated_at and estimated_time_remaining_seconds are refreshed at least every 10 seconds Given at least one task fails When status is requested Then failures[] contains image_id, error_code, error_message, retry_count, last_attempt_at Given logging is enabled When inspecting job logs Then each log entry includes job_id, image_id, event_type, timestamp_iso8601, duration_ms (when applicable), severity, and error_code (when applicable) Given a job completes When status is requested Then completion_state is one of {succeeded, completed_with_failures, failed} And final throughput_images_per_min is reported

Resumable Jobs and Deterministic Re-runs

Given a running job is interrupted (e.g., worker crash or network loss) When it is restarted within 24 hours Then already-succeeded images are not reprocessed And pending images resume processing from the last completed checkpoint Given identical inputs (image content hash), draft preset version, and deterministic settings (random_seed and operator_versions) When the job is re-run Then produced outputs are bitwise-identical and share the same content hash Given an image fails with a transient error When automatic retry policy max_retries=3 with exponential backoff is configured Then the system retries up to 3 times and records each attempt in logs and job status And the image is marked failed only after all retries are exhausted

Per-Workspace Quotas and Throttling

Given daily_draft_image_quota=10000 and 9800 images already processed today for a workspace When a job for 500 images is submitted Then only 200 images are scheduled And 300 images are rejected with error_code=quota_exceeded and a remediation message including remaining_quota Given active_concurrent_jobs_quota=2 for a workspace When a third job is submitted Then the job is accepted in queued state if queueing_allowed=true Otherwise it is rejected with error_code=quota_exceeded Given quotas are increased for a workspace When the new limits are applied Then queued jobs transition to running automatically if capacity permits And status changes are emitted to the event stream

GPU Utilization and Scheduling

Given 2 provisioned GPUs and per-task gpu_requirement=1 and concurrency_limit=8 When the job runs Then at most 2 GPU tasks run concurrently and remaining tasks wait in queue Given a GPU becomes unhealthy mid-run When health checks fail for that GPU Then tasks on that GPU are rescheduled to healthy GPUs And job status reflects a rescheduling event with affected image_ids Given GPU metrics collection is enabled When job status is requested Then the API reports gpu_utilization_percent per GPU and avg_gpu_memory_used_mb during the last sampling window

Cost Guardrails and Budget Enforcement

Given monthly_draft_budget_usd=200 for a workspace and estimated_cost_usd for a new job=250 When submission is attempted Then the job is blocked with error_code=budget_exceeded And the response includes estimated_cost_usd and remaining_budget_usd Given a job starts with remaining_budget_usd=50 and estimated_cost_usd=40 When actual_cost_usd reaches 50 Then the job is auto-paused And remaining tasks are not started And status=paused_budget_reached Given a paused_budget_reached job receives an additional budget of 100 When resumed by an authorized user Then processing continues without reprocessing previously completed images

Ephemeral Draft Storage, TTL, and Content-Addressed Caching

Given draft outputs have ttl_hours=168 When 168 hours elapse after an output's created_at timestamp Then the output is auto-deleted and no longer retrievable via the draft asset API And a deletion event is recorded in logs Given an image+preset combination previously produced an output with content_hash=H within TTL When the same combination is re-run Then processing is skipped And cached output with content_hash=H is returned And job status marks the item as cache_hit=true Given the same image with a modified preset version When re-run Then processing occurs And cache_hit=false And a new content_hash is produced

Side-by-Side Compare Viewer

"As a visual merchandiser, I want to compare draft outputs side-by-side with current results so that I can quickly spot quality differences and approve changes with confidence."

Description

Deliver an interactive viewer to compare draft outputs against current live preset results and original images. Include split-view and two-up layouts, synchronized zoom/pan, before/after toggles, and keyboard navigation. Display key metadata (preset version, parameters) and visual aids (histogram, clipping warnings, edge masks for background removal). Allow per-image annotations and reviewer comments, and support shareable review links with expiry. Color-manage the display (sRGB) and respect watermark/download restrictions for drafts. This accelerates review cycles and raises confidence in visual quality.

Acceptance Criteria

Split-View and Two-Up with Synchronized Zoom/Pan

Given Draft, Live, and Original variants are available and the viewer is open in split-view or two-up When the user zooms via UI controls, mouse wheel/trackpad, or +/- keys Then both panes update to the same magnification within 1% and remain position-aligned within ≤2px at 100% zoom And switching between split-view and two-up preserves the current zoom level and focal point And initial load renders a fit-to-screen view in ≤500 ms for a 24MP image on target browsers And pan operations respond in ≤100 ms and do not exceed ≤2px desync between panes over a 4K canvas And the split divider is draggable and snaps with no more than 16 ms input latency

Before/After Toggle and Side Swap

Given Draft and a chosen baseline (Live or Original) are loaded When the user presses B or clicks the Before/After toggle Then the viewer toggles between Draft and baseline in both split-view and two-up within ≤100 ms and shows clear side labels (Draft, Live, Original) And holding B shows the alternate state only while pressed (press-and-hold) And pressing S swaps left/right assignment within ≤100 ms without changing zoom or focal point And the selected baseline persists across image changes within the current review session

Metadata and Visual Aids Display Accuracy

Given an image pair is selected When the metadata panel is opened Then it displays preset name, version (e.g., vX.Y.Z), and the parameter set applied to each variant, matching processing job records exactly (0 mismatches) And the histogram matches an offline reference histogram within ±1% per 256-bin channel bucket And enabling clipping warnings overlays red for pixels clipped at 255 in any channel and blue for pixels at 0, with pixel-accurate alignment And enabling edge mask shows the background removal mask aligned within ≤1px of the processed edges and supports opacity control from 0–100% in 10% increments

Keyboard Navigation and Accessibility

Given the viewer has keyboard focus When Arrow keys are pressed Then the image pans by 10% viewport per keypress (Shift+Arrow = 25%) And +/- zooms in/out by 20% increments; 0 sets Fit, 1 sets 100% And Tab/Shift+Tab cycles through actionable controls without focus traps, with visible focus indicators And pressing ? opens a keyboard shortcut overlay that lists all shortcuts and is dismissible with Esc And all functions are operable without a mouse and meet WCAG 2.1 AA keyboard requirements

Per-Image Annotations and Reviewer Comments

Given a user with Editor or Reviewer role opens an image in the viewer When the user adds a pin or box annotation at a location Then the annotation anchors to image coordinates and remains correctly positioned under any zoom/pan And each annotation supports a threaded comment stream with timestamps; authors can edit/delete their own comments within 15 minutes And annotations/comments are saved per image and variant (Draft/Live) and display user, time, and status (open/resolved) And View-only users (including via share links) can see but cannot create, edit, or resolve annotations/comments

Shareable Review Links with Expiry and Revocation

Given a project member generates a review link When an expiry is set between 1 hour and 30 days (default 7 days) Then the link grants view-only access to the specified images and viewer features, with watermarking and download restrictions enforced for drafts And accessing an expired or revoked link returns 410 Gone and blocks further viewing within 60 seconds of revocation And the link token is unguessable (≥128-bit entropy) and audit logs record creation, access times, and revocations And owners can revoke links at any time from the share panel

Color Management (sRGB) and Draft Watermark/Download Restrictions

Given images with embedded color profiles (e.g., Adobe RGB, ProPhoto) are loaded When rendered in the viewer Then they are converted and displayed in sRGB with ΔE00 ≤ 2 versus a reference conversion for a standard test chart on color-managed devices And draft outputs display a semi-transparent watermark and have downloads disabled: no download button, right-click save blocked, and unauthenticated direct asset requests return 403 And users with only view permissions cannot obtain an unwatermarked draft via any viewer control or URL And admins with explicit override can download, and the action is logged

One-Click Promote & Rollback

"As a product owner, I want to promote an approved draft to live with one click and a rollback option so that I can deploy improvements safely and quickly."

Description

Provide a guarded promotion flow that atomically sets a draft preset as the live version with optional scheduling and canary validation on a small set. Enforce pre-promotion checks (required approvals, passing quality gates, no active edits) and generate an audit trail with version notes. Support immediate rollback to the previous live version and notify stakeholders via in-app alerts and webhooks. Promotion is safe, reversible, and observable, ensuring zero production risk while streamlining deployment of approved styles.

Acceptance Criteria

Immediate Promotion - Pre-checks and Atomic Swap

Given a draft preset D exists with all required approvals completed, all configured quality gates passing, and no active edits on D And the user has Promote permissions for the workspace And there is an existing live preset version L When the user clicks Promote Now for D and confirms Then the system atomically sets D as the new live version L+1 with no partial/visible intermediate state And the previous live version is recorded as Previous Live And the promotion request returns success with the new live version identifier And no other presets are modified And the Draft Sandbox marks D as Promoted and locks further edits until a new draft is created

Scheduled Promotion - Execution and Failure Handling

Given a draft preset D is scheduled for promotion at a future UTC timestamp T with optional freeze window checks enabled And at scheduling time, D satisfies all pre-promotion checks When the system clock reaches T Then the system re-evaluates all pre-promotion checks at execution time And if all checks pass, D is promoted atomically to live (L+1) and the schedule is cleared And if any check fails (e.g., new edit detected, approval revoked, quality gate fail), the promotion is not executed, the schedule is canceled, and stakeholders are notified with the failure reason And if the user cancels the schedule before T, no promotion occurs and no state changes are applied

Canary Validation - Sample Guard and Gates

Given a draft preset D has a defined canary sample set S (by percentage or explicit list) within allowed bounds (e.g., 1–5% of catalog or 50–500 images) And quality gate thresholds are configured for the canary (e.g., background accuracy, defect rate, color variance) When the user starts a canary run for D Then the system applies D only to S and leaves the current live version for all non-S items And the system generates a canary report with metrics, pass/fail per gate, and side-by-side thumbnails for S And if Auto-abort on fail is enabled and any gate fails, the promotion action is blocked and live remains unchanged And if all gates pass, the user can finalize promotion in one click without reprocessing S

One-Click Rollback - Atomic Restore

Given a promotion from L to L+1 has occurred and the prior live version L is retained When the user clicks Rollback and confirms Then the system atomically restores L as the live version and marks L+1 as Rolled Back And any pending schedules tied to L+1 are canceled And an audit entry is recorded with actor, reason, and correlated promotion id And stakeholders are notified via in-app alert and webhook of the rollback outcome

Audit Trail & Version Notes - Complete and Immutable

Given a promotion or rollback action is initiated When the action completes (success or failure) Then an immutable audit record is created containing: actor, action type (promote/rollback), draft id, from_version, to_version, timestamps (started/completed), pre-check results, canary metrics snapshot (if any), outcome, and webhook delivery summary And promotion requires non-empty version notes (minimum 5 characters) which are stored in the audit record And audit records are queryable by time range, actor, preset id, and outcome And audit records cannot be edited or deleted by end users

Stakeholder Notifications - In-App and Webhooks

Given notification subscriptions exist for promotion and rollback events When a promotion or rollback succeeds or fails Then targeted stakeholders receive in-app alerts containing version ids, action, outcome, and links to audit and diffs And configured webhooks are sent with a signed payload schema including event type, preset id, from_version, to_version, actor, outcome, and timestamps And webhook delivery uses retry with exponential backoff for transient failures and records final delivery status And no notifications are sent for scheduled attempts that are canceled before execution

Concurrency & Idempotency - Safe, Single-Action Semantics

Given two users attempt to promote the same draft D concurrently When both requests are submitted within a short window Then only one promotion succeeds and the other receives a conflict response with no state change And if a client retries the same promotion using the same idempotency key, the server processes it at most once and returns the original result And if any active edit session exists on D at the moment of execution, the promotion is blocked with a clear error referencing the active editor/session And promote/rollback endpoints are linearizable: read-after-write returns the new live version immediately after success

Access Control & Approvals

"As an admin, I want role-based permissions and approvals for drafts so that only authorized changes move to production."

Description

Implement role-based access control for draft creation, editing, viewing, and promotion. Configure approval workflows with required reviewers, minimum approvals, and optional policy checks by workspace. Provide audit logs of all actions, reviewer comments, and decisions, plus secure share links for external reviewers with expiration and watermarking. Integrate with SSO/SCIM roles and existing organization permissions. This ensures proper governance without slowing small teams, balancing control and velocity.

Acceptance Criteria

RBAC: Draft Create/Edit/View/Promote Enforcement

Given a user authenticates via SSO and is assigned one of: Admin, Draft Editor, Reviewer, Viewer And the workspace has default permissions applied When the user attempts each action on drafts via UI and API: create, edit, view, submit for review, approve/decline, promote Then access is allowed only per role policy: - Admin: all actions - Draft Editor: create, edit, view, submit for review; cannot approve or promote - Reviewer: view, comment, approve/decline; cannot create, edit, or promote - Viewer: view only; cannot create, edit, approve/decline, or promote And disallowed actions return HTTP 403 on API and disabled controls with tooltip "Insufficient permissions" in UI And each denied attempt is recorded in the audit log with actor, action, timestamp, and reason "permission_denied"

Approval Workflow: Required Reviewers and Minimum Approvals

Given a workspace admin configures an approval workflow with required reviewers [A, B] and minimum approvals = 2 And "allow substitutes" is disabled When a draft is submitted for review Then only listed required reviewers may approve And promotion eligibility requires approvals >= 2 and approvals include both A and B And if a required reviewer declines, the draft enters "Changes Requested" until resubmitted And the system prevents marking the review complete if any required reviewer has not approved

Gatekeeping: Promotion Blocked Until Approvals and Policy Checks Satisfied

Given a draft has at least the configured minimum approvals and all required reviewers have approved And all configured policy checks (e.g., background removal verification, resolution >= 2000px) have passed When a user with Promote permission clicks Promote or calls POST /drafts/{id}/promote Then the draft is promoted and a new preset version is created and timestamped And if any precondition is unmet, the promotion is blocked with a consolidated error message listing unmet items And a promotion event (success or blocked) is written to the audit log including approver list and policy check results

Audit Log: Complete, Immutable, and Exportable Records

Given any action on drafts or workflows occurs (create, edit, submit, approve, decline, comment, share link create/revoke, promote, permission denied) When viewing the audit log for a draft or workspace Then each event includes: actor id and display name, actor role, action type, object id and version, ISO-8601 UTC timestamp (UTC), IP address, result (success/denied), and optional comment text or reason And log entries are append-only (no update/delete APIs) and have a monotonically increasing sequence id And logs can be exported by Admin as CSV and JSON for a specified date range And logs are retained for at least 365 days

External Review: Expiring Watermarked Share Links

Given a Draft Owner generates an external review link scoped to a specific draft with expiry = 7 days and comment-only permission When an external reviewer opens the link Then the reviewer can view watermarked images and leave comments but cannot download originals or promote And every image is overlaid with the workspace watermark text and draft id And the link becomes unusable after expiry or immediate revocation, returning HTTP 410 via API and an "Link expired" page in UI And all views and comments via the link are attributed to "External Reviewer" with per-link token id in the audit log

SSO/SCIM: Role Mapping and Permission Inheritance

Given organization SSO is configured and SCIM is enabled with group-to-role mappings (e.g., okta_group_editors -> Draft Editor) When a user is added to or removed from a mapped IdP group Then their PixelLift role updates within 5 minutes and access reflects the new role on next request And deprovisioned users lose all access within 60 seconds of SCIM delete and active sessions are revoked And local role changes in PixelLift are overridden by SCIM-sourced mappings on next sync and recorded in the audit log

Small Team Fast-Path: Streamlined Workflow Without Governance Loss

Given a workspace sets Minimum Approvals = 0 and has no Required Reviewers configured When a Draft Editor submits and then promotes their own draft Then promotion is allowed without reviewer approvals, provided all policy checks pass And the promotion is fully audited (including actor, policy results, and before/after preset version) And if Required Reviewers or Minimum Approvals > 0 are later configured, subsequent promotions require the new approvals

Quality & Impact Summary

"As a QA reviewer, I want a quality summary and pass/fail gates for draft runs so that promotion decisions are data-driven and consistent with brand standards."

Description

After each batch run, generate a summary report with visual and quantitative indicators: background removal confidence, color delta, exposure and white balance shifts, sharpness and noise metrics, crop/size conformance, processing time, error rates, and estimated cost. Highlight outliers and failures, show per-image thumbnails, and compute pass/fail against configurable thresholds. Provide export (CSV/JSON) and link the report to promotion gates. This gives data-backed evidence to judge whether a draft meets brand standards and operational constraints.

Acceptance Criteria

Auto-Generated Batch Quality Summary

Given a Draft Sandbox batch run with up to 500 images completes processing When the run finishes Then a Quality & Impact Summary is generated within 60 seconds and attached to the run And the summary includes per-image fields: image_id, background_removal_confidence (0.00–1.00, 2 decimals), color_delta_E00, exposure_shift_EV, white_balance_shift_K, sharpness_variance, noise_SNR_dB, crop_size_conformance (true/false), processing_time_ms, error_code, estimated_cost_cents And the summary includes batch aggregates: total_images, failed_images, error_rate_percent (2 decimals), total_processing_time_ms, total_estimated_cost_cents, mean/median/min/max for each numeric metric And missing per-image metrics are recorded as null without failing summary generation

Outlier Detection and Highlighting

Given a threshold profile is configured for the draft's preset When the summary is generated Then any metric outside its threshold is flagged per image with outlier=true and reason_codes And the batch shows outlier_count equal to the number of images with ≥1 violation And toggling "Show Outliers" lists only outlier images sorted by severity within 1 second And updating thresholds recalculates outlier flags within 5 seconds without reprocessing images

Per-Image Thumbnails in Report

Given the summary is viewed in the Draft Sandbox When per-image rows render Then each row displays a processed-image thumbnail with max dimension 200 px, WebP format, and file size ≤ 50 KB And thumbnails lazy-load and render above-the-fold rows within 500 ms on a 3G fast network And clicking a thumbnail opens the full-size processed image in a new tab with the image_id in the URL

Threshold-Based Pass/Fail Computation

Given a threshold profile T is active When the summary is generated or thresholds change Then image_status is Pass if all thresholded metrics are within bounds and error_code is null; otherwise Fail with reason_codes populated And batch_status is Pass if at least 95% of images pass and error_rate_percent ≤ the configured limit (default 2%); otherwise Fail And the header displays pass_count, fail_count, and pass_percent with two decimals And status recalculates within 5 seconds of a threshold change without reprocessing images

CSV and JSON Export of Summary

Given a user clicks Export CSV or Export JSON on a completed summary with up to 1,000 images When the export is requested Then the file downloads within 10 seconds and contains one row/object per image plus batch-level metadata And CSV is UTF-8, comma-delimited, includes a header row, and row count equals total_images + 1 And JSON validates against schema id "pixellift.qualitySummary.v1" with top-level fields batch and images[] And exported numeric fields preserve at least the precision shown in the UI

Cost and Processing Time Accuracy

Given pricing rules and operation counts used in the batch are known When estimated_cost_cents and processing_time_ms are computed Then per-image estimated_cost_cents matches the pricing table within ±2% and rounds to the nearest cent And batch total_estimated_cost_cents equals the sum of per-image estimates And per-image processing_time_ms equals the sum of stage times within ±5% and batch total equals the sum of per-image times

Promotion Gate Enforcement via Summary

Given a user attempts to Promote a draft to Live When the Quality & Impact Summary batch_status is Pass Then the Promote action is enabled and requires the summary_id to be linked to the promotion record And when batch_status is Fail, the Promote action is disabled unless the user has OverridePromotion permission and enters an override_reason (≥10 characters) And all promotion attempts are audit-logged with user_id, timestamp, batch_status, outlier_count, and total_estimated_cost_cents

Smart Approvals

Configurable approval chains with SLAs, change diffs, and auto-escalation. Approvers get concise visual summaries and can approve from email or Slack, keeping launches on schedule while ensuring significant edits receive proper oversight.

Requirements

Dynamic Approval Chains & Rules Engine

"As a brand operations manager, I want to configure conditional approval chains for batches so that significant edits get proper oversight without slowing routine work."

Description

Provide configurable, multi-step approval workflows for PixelLift projects and batches, supporting sequential and parallel stages, conditional routing based on asset metadata (product category, brand, risk score, change magnitude), and policy templates. Includes per-step SLAs, required approver roles, minimum quorum, and thresholds that define significant edits (e.g., background replaced, retouch intensity above a set level). Integrates with PixelLift job orchestration so batch processing pauses at approval gates and resumes automatically upon approval. Offers UI for creating, cloning, and simulating workflows, with versioning and safe rollout by workspace.

Acceptance Criteria

Sequential and Parallel Approval with Role Quorum

Given a workflow "PL-Workflow-1" with Stage 1 (sequential) requiring role=Brand Manager and quorum=2 of 3 And Stage 2 (parallel) contains "Legal Review" (role=Legal Counsel, quorum=1) and "QA Review" (role=QA Lead, quorum=1) And a batch job "B-1001" enters Stage 1 When two distinct users with role=Brand Manager approve within Stage 1 Then the job advances to Stage 2 and both "Legal Review" and "QA Review" open concurrently And additional approvals for Stage 1 after quorum are ignored and logged When one Legal Counsel and one QA Lead approve their respective parallel steps Then the job exits Stage 2 and continues processing And the audit log records approver IDs, timestamps, and stage outcomes

Conditional Routing by Metadata and Significant Edit Thresholds

Given a policy with rule: if product_category in ["Beauty","Skincare"] OR risk_score >= 70 OR significant_edit=true then route to "Compliance Review" else route to "Standard Review" And significant_edit is defined as (background_replaced=true OR retouch_intensity >= 60) And batch "B-2002" has asset metadata: product_category="Beauty", retouch_intensity=72, background_replaced=true, risk_score=65 When the workflow evaluates routing for the batch Then the batch is routed to "Compliance Review" And the evaluation report lists matched conditions ["product_category","significant_edit"] and non-matched ["risk_score"] When asset metadata is product_category="Shoes", retouch_intensity=40, background_replaced=false, risk_score=20 Then the batch is routed to "Standard Review"

Per-Step SLA, Reminders, and Auto-Escalation

Given Stage "Brand Approval" has SLA=24h, reminder cadence=6h, and escalation target="Brand Director" group after SLA breach And batch "B-3003" enters the stage at T0 When no quorum is achieved by T0+24h Then the system marks the stage "Overdue" and sends an escalation notification to the "Brand Director" group And reminders were sent at T0+6h, T0+12h, and T0+18h to pending approvers And an escalation approver's approval satisfies quorum When quorum is met before SLA breach Then no escalation is sent and stage status is "Completed on time"

Email and Slack One-Click Approvals with Secure Tokens

Given approver Alice is assigned to Stage "Legal Review" And the system sends an email and Slack message with Approve/Reject buttons embedding a single-use token that expires in 24h When Alice clicks Approve in Slack within 24h Then the approval is recorded, the token is invalidated, and the stage updates in under 3 seconds And the Slack message updates to show the decision and an audit link When the same token is used again or after expiry Then the action is rejected with "Token invalid or expired" and no state change occurs And the audit log captures channel, user ID, IP, timestamp, and comment (if provided)

Pause and Auto-Resume at Approval Gates in Job Orchestration

Given batch "B-4004" has an approval gate after the "Background Removal" step When the gate opens Then the pipeline pauses downstream tasks for that batch and releases compute resources for the paused job When approval quorum is reached Then the pipeline resumes automatically within 10 seconds and continues at the next step When the stage is rejected Then remaining downstream steps are canceled and the batch status is set to "Changes Requested" with notifications sent to the submitter

Workflow Builder: Create, Clone, Simulate, and Versioned Rollout

Given a user with role "Workflow Admin" opens Workflow Builder When they create workflow v1.0 with three stages and save Then the workflow is versioned as 1.0 and set to Draft until rolled out to Workspace A When they clone v1.0 to v1.1, edit rules, and run simulation against sample assets A1 and A2 Then the simulator shows per-asset routes, matched rules, and SLAs without executing jobs When v1.1 is rolled out to Workspace A with rollout mode="Gradual 25%" Then new jobs are assigned v1.1 in 25% of cases and in-flight jobs remain on their original version When rollout is promoted to 100% and then v1.1 is reverted Then new jobs return to the previous stable version and a change log entry is created

Concise Visual Summaries and Change Diffs for Approvers

Given an approval stage is opened for batch "B-5005" When approvers open the summary in email or Slack Then they see per-asset before/after thumbnails, detected edits (e.g., "Background replaced", "Retouch intensity: 72"), risk score, and SLA remaining time And the summary loads in under 2 seconds for up to 100 assets with total payload under 5 MB And all images include alt-text and the content is keyboard and screen-reader accessible When approvers click "View full diff" Then a web view shows side-by-side large previews with annotations and a downloadable change report (PDF) linked in the audit trail

Visual Diff Summaries for Batches

"As an approver, I want concise visual diffs and batch rollups so that I can review hundreds of images quickly and catch high-impact changes."

Description

Generate concise, visual summaries per asset and per batch that include before/after sliders, annotated lists of transformations, change heatmaps, and a significance score for quick triage. Provide batch-level rollups showing counts of high-significance edits, outliers, and flagged items. Enable quick filters and sampling tools for fast review (e.g., review a 10% sample or all items over a threshold). Embed bandwidth-friendly thumbnails in notifications and deep link to full-resolution proofing in PixelLift.

Acceptance Criteria

Per-Asset Before/After Slider

- Given an approver opens an asset summary from a processed batch, When the page loads, Then a before/after slider is displayed above the fold showing Original vs Enhanced. - Given the user drags the slider, When sliding from 0% to 100%, Then the two images remain pixel-aligned (≤1px deviation) and no layout reflow occurs. - Given standard network conditions (5 Mbps, 100 ms RTT), When the asset summary loads cold, Then both images are visible and draggable within 1.5 seconds. - Given the user drags the slider, Then interaction latency stays under 200 ms and frame rate ≥ 50 FPS on a mid-tier laptop and a modern mobile device. - Given the user clicks "Zoom 100%", When zoom is active, Then the slider continues to function on the zoomed image without loss of alignment.

Annotated Transformation List Accuracy

- Given a processed asset, When viewing the Transformations panel, Then a chronological, human-readable list of applied operations is shown with parameters (e.g., Background removed; Exposure +0.7 EV; Crop 4:5). - Given the pipeline metadata, When compared to the UI list, Then 100% of applied operations are present, ordered correctly, and parameter values match within ±1% for numeric values. - Given a transformation in the list, When the user hovers or clicks it, Then the affected region(s) highlight on the visual and the panel focuses the selected item. - Given an asset with no edits, When viewing the panel, Then the UI displays "No changes applied" and hides irrelevant controls.

Pixel Change Heatmap Visualization

- Given a processed asset, When the user toggles Change Heatmap, Then a heatmap overlay appears with a legend and adjustable sensitivity from 0–100%. - Given a known test pair with synthetic differences, When generating the heatmap, Then ≥95% of modified pixels are detected and ≥95% precision is achieved for unchanged pixels. - Given the user downloads the heatmap, When clicking Export, Then a PNG of the overlay at asset resolution downloads within 3 seconds for assets up to 24 MP. - Given the user toggles off the heatmap, Then the base image returns to normal with no residual overlay.

Significance Score and Threshold Filtering

- Given an asset summary, When displayed, Then a significance score between 0 and 100 is shown with a badge (Low/Medium/High) mapped to configurable thresholds (default: Low 0–39, Medium 40–69, High 70–100). - Given a batch, When applying a filter Score ≥ T, Then 100% of assets with score ≥ T are included and 0% with score < T are included. - Given thresholds are updated by an admin, When filters and badges refresh, Then counts and badges update within 1 second without a full page reload. - Given identical inputs and model version, When the same asset is scored twice, Then the score difference is ≤ ±2 points.

Batch-Level Rollups and Outlier Detection

- Given a batch of N assets, When viewing the batch summary, Then rollups display: total assets, counts of High/Medium/Low significance, Outliers, and Flagged. - Given rollup counts, When cross-checked via corresponding filters, Then counts exactly match the items returned. - Given default outlier detection (z-score > 2.5 on batch significance distribution), When enabled, Then qualifying assets are labeled Outlier; if method is switched to IQR, rollups recompute within 2 seconds for up to 5,000 assets. - Given a batch up to 5,000 assets, When opening the batch summary, Then rollups compute and render within 3 seconds on first load and within 1 second on subsequent loads (cached).

Sampling Tools: Percentage and Seeded Randomization

- Given a batch, When the user selects Sample 10%, Then the system returns a random subset of ceil(0.10 × N) unique assets. - Given a seed value S, When the user sets Seed = S and applies the same sampling percentage again, Then the returned subset is identical across sessions and devices. - Given combined filters, When the user applies Score ≥ T and then Sample 10%, Then sampling operates only on the filtered set. - Given sampling is active, When viewing the grid, Then the UI displays the sample size and provides a control to Review All to exit sampling.

Notifications: Thumbnails and Deep Links to Proofing

- Given email and Slack notifications are enabled, When a batch completes, Then notifications include per-asset thumbnails and a batch-level summary; each thumbnail is ≤150 KB and ≤800 px on the longest edge. - Given a user clicks a thumbnail or Open in PixelLift, When the link opens, Then the full-resolution proofing view loads with the corresponding batch/asset and any filter context applied. - Given standard network conditions (5 Mbps, 100 ms RTT), When opening a deep link, Then the first full-resolution image is visible within 2 seconds and remaining assets stream progressively. - Given clients that block external images, When viewing the notification, Then alt text is present and links remain functional with readable layout.

SLA Timers with Auto-Reminders & Escalation

"As a project lead, I want SLA timers with auto-escalation so that approvals stay on schedule and delays are handled proactively."

Description

Track SLA per approval step with business-hours calendars and time-zone awareness. Send proactive reminders before due times and follow-ups after breaches, escalating to backup approvers or managers as configured. Support escalation trees, snooze options, OOO auto-reassignment, and pause/resume for holidays. Surface SLA status in dashboards and provide metrics (average approval time, breach rate) for operational reporting. Log all reminders and escalations in the audit trail.

Acceptance Criteria

Business-Hours & Time-Zone SLA Computation

- Given an approval step with an 8-business-hour SLA and an approver in America/Los_Angeles with business hours 09:00–17:00 Mon–Fri, when the request is submitted Friday at 16:30 local time, then the due time is Monday 12:30 local time and only business hours are counted. - Given the requester is in Europe/Berlin, when viewing the same step, then the due timestamp is displayed localized to the viewer without changing the underlying due moment. - Given a DST transition (spring forward) occurs during the SLA window, when computing remaining time, then the lost hour is not counted as business time and the due time reflects correct business-hour math. - Given business hours exclude weekends, when a step is submitted Saturday, then the SLA countdown begins at 09:00 Monday in the approver’s time zone.

Pre-Due Reminders with Snooze

- Given a step with reminders configured for T-24h and T-2h, when those thresholds are reached within the approver’s business hours, then reminders are sent via the configured channels (email and/or Slack) with remaining time shown in the message. - Given a reminder threshold occurs outside business hours, when the next business hour window opens, then exactly one queued reminder is sent and no duplicates are produced. - Given the approver clicks Snooze for 2 hours in a reminder, when the snooze window is active, then no additional reminders are sent for that step and reminders resume after snooze expires. - Given a per-step max reminder count of 3, when more than 3 reminders would be triggered, then additional reminders are suppressed and the suppression is recorded.

Breach Follow-Up and First-Level Auto-Escalation

- Given a step breaches its SLA, when breach is detected, then a follow-up notification is sent immediately to the current approver and the step status is marked Breached in UI and API. - Given an escalation rule with a 1-business-hour grace period to Backup Approver A, when the breach remains unresolved for 1 business hour, then the step is escalated to A per configuration (reassign or parallel) and A is notified via configured channels. - Given the original approver approves during the grace period, when the step becomes approved, then the scheduled escalation is canceled and the status updates to Approved without an escalation event.

Multi-Level Escalation Trees with Skip/Stop Conditions

- Given an escalation tree [Primary -> Backup -> Manager Group -> Director], when each escalation interval elapses without approval, then the step escalates to the next node and notifications are sent at each level. - Given a node in the tree is ineligible (OOO or already approved), when escalation reaches that node, then the node is skipped and escalation proceeds to the next eligible node. - Given any user in the current node approves, when approval is recorded, then all pending downstream escalations are canceled and the escalation chain stops at that level. - Given the final node is reached and no approval occurs within its SLA, when the final interval elapses, then no further escalation occurs and the step is flagged for manual intervention in UI and API.

OOO Auto-Reassignment to Delegates

- Given the primary approver has an active OOO window with delegate D, when a step is assigned to the primary, then it is auto-reassigned to D, notifications are sent to D, and the due time is recalculated using D’s business-hours calendar and time zone. - Given the primary becomes OOO after assignment, when OOO activates, then any currently assigned, unapproved steps are reassigned to the delegate per policy and both users are notified. - Given no delegate is configured, when the primary is OOO at assignment time, then the step escalates to the configured backup path per the escalation rules and this action is recorded.

Holiday Pause and Resume

- Given the approver’s holiday calendar marks a day as a holiday, when an SLA window spans that day, then the SLA countdown pauses at the start of the holiday and resumes at the next business day start, extending the due time accordingly. - Given a step is submitted during a holiday, when computing the SLA start, then the countdown begins at the next business day start in the approver’s time zone. - Given multiple consecutive holidays or weekends, when computing due time, then all non-business days are excluded from the SLA calculation and the remaining time is accurate to the hour. - Given an SLA is paused for a holiday, when viewing the step, then the UI displays Paused with reason Holiday and shows paused duration not counted toward SLA.

SLA Visibility, Reporting & Audit Trail

- Given an approval request, when viewed in the dashboard, then each step displays status (On Track, At Risk ≤20% SLA remaining, or Breached), remaining/elapsed business hours, due timestamp, and current escalation level. - Given filters for date range, team, and status are applied, when metrics load, then average approval time (business hours), breach rate, and p50/p90 are computed from the filtered set and match values derived from raw events. - Given an export is requested, when the CSV is generated, then it includes per-step fields (IDs, assignees, due times, statuses, SLA durations, escalation levels) with timestamps in UTC and the viewer’s local offset. - Given any reminder, snooze, reassignment, or escalation event occurs, when inspecting the audit trail, then an entry exists with timestamp, actor=system, recipients, channel(s), template ID or subject, outcome (queued/sent/delivered if available), and related step IDs.

Actionable Email & Slack Approvals

"As a busy approver, I want to approve from email or Slack with clear context so that I can keep launches moving without logging into the app."

Description

Deliver actionable approval requests via email and Slack with secure, one-click Approve, Request Changes, and Reject actions. Include batched thumbnails, key metrics, and top diffs in the message for context. Use signed, expiring tokens and SSO handoff to allow secure actions without full login. Support bulk decisions, inline comments, and quick filters within Slack modals, with reliable fallback deep links to the web app if interactivity is blocked.

Acceptance Criteria

One-Click Email Approval with Secure Token

Given an approver receives an approval email with Approve, Request Changes, and Reject CTAs When the approver clicks a CTA within the token TTL Then the action is executed without full login via SSO handoff and a confirmation screen shows decision, item count, and reference ID And the token is single-use; subsequent clicks return an "Expired or Used" page and do not change state And clicks after TTL return an "Expired" page with a deep link to the web app approval view And the decision, channel=email, user, timestamp, and IP are audit logged

Slack Modal Quick Filters and Actions

Given an approver opens a Slack approval modal from a PixelLift notification or shortcut When they apply quick filters (e.g., submitter, brand preset, priority, due soon) and select a subset of items Then the list updates in-modal and selection persists across filters And Approve/Reject/Request Changes actions are available for single or multiple selected items And an ephemeral Slack confirmation summarizes outcomes with links to details

Bulk Decisions with Per-Item Outcomes

Rule: Up to 200 items can be actioned in a single bulk operation from Slack or email deep link Rule: Bulk operations return per-item outcomes; successes are committed, failures remain pending with reasons Rule: For 100 items, 95th percentile server processing time is ≤ 8 seconds; UI shows progress/spinner until completion Rule: If any item requires a comment for Request Changes, the modal enforces a comment before submission

Context-Rich Visual Summaries in Messages

Rule: Email and Slack messages include batched thumbnails (up to 6) with alt text, key metrics (item count, presets applied, background type), and top diffs (e.g., background removed, retouch strength, style preset) Rule: A "View all" link opens the approval page with the same selection pre-applied Rule: Diffs link to a side-by-side before/after view in the web app

Inline Comment Capture on Request Changes

Given an approver chooses Request Changes for one or more items When they submit the action Then a comment is required (minimum 3 characters) and supports @mentions And the comment is stored on each affected item’s thread, visible in the web app within 5 seconds And submitters receive a notification with the comment and item links

Secure Tokens, SSO Handoff, and Authorization

Rule: Action links/buttons use signed, single-use, expiring tokens bound to approval ID and recipient user; configurable TTL (5–60 min), default 15 min Rule: Only assigned approvers with permission can complete the action; unauthorized attempts return 403 and do not change item state Rule: SSO handoff allows the action to complete without full login; no persistent session is created unless the user explicitly continues to the app Rule: All token validations and decisions are audit logged with channel, user, decision, item IDs, and timestamp

Fallback Deep Links When Interactivity Is Blocked

Given Slack interactivity is disabled or times out, or an email client blocks action buttons When the approver uses the fallback deep link Then the web app opens to the approval view with the same context (pre-filtered selection) and offers Approve/Request Changes/Reject and bulk actions And SSO redirect signs the user in if needed without losing context And the fallback path is tracked as channel=web_fallback in audit logs

Audit Trail & Compliance Exports

"As a compliance officer, I want an immutable audit trail and exports so that we can prove proper oversight during audits."

Description

Maintain immutable, tamper-evident logs of every approval decision, timestamp, approver identity, content viewed (diffs, summaries), and justification notes. Link decisions to exact asset versions and the workflow version used at the time. Provide exports to CSV/JSON and webhook delivery to external DAM, QA, or governance systems. Include e-discovery search, configurable retention policies, and data residency controls aligned to workspace regions.

Acceptance Criteria

Immutable Tamper-Evident Approval Log

Given an approval event is recorded When any user attempts to modify or delete a prior log entry through UI or API Then the system rejects the operation with HTTP 403 and records an audit-violation event Given the audit log integrity check is executed When hashes are recomputed Then each record contains a hash and previous_hash that form an unbroken chain without gaps Given an export with integrity manifest is generated When the manifest checksum is validated Then recomputed checksums match the published manifest and the export is marked valid Given a simulated storage crash and recovery When the service restarts Then all committed log records persist and sequence numbers remain strictly increasing without duplicates

Complete Event Data Capture

Given an approval decision is submitted via any channel (Web, Email, Slack, API) When the event is persisted Then the record includes event_id, event_type, decision, timestamp (ISO 8601 UTC), approver_id, approver_email, auth_method, ip_address, user_agent, requester_id, request_id, asset_id, asset_version_id, workflow_id, workflow_version, viewed_artifacts (diff_id, summary_id), justification_text (nullable), sla_at_decision, source_channel And required fields are non-null and validated against allowed enumerations; optional fields are null when not applicable And timestamps are monotonic per request_id and include millisecond precision

Decision Linkage to Exact Versions

Given an approval is made on asset version Vn under workflow version Wm When the audit record is created Then it stores asset_id, asset_version_id=Vn, asset_content_hash, workflow_id, workflow_version=Wm, and diff_version_id used at decision time And when the asset or workflow is later updated, the historical record continues to resolve to Vn and Wm without ambiguity And when replaying the event, the system retrieves the exact versions referenced by the record

CSV/JSON Export with Filtering and Scale

Given a workspace admin requests an export with date range, event types, approvers, and field selection When the export is generated Then the system produces a ZIP containing NDJSON (.jsonl) and CSV files matching the selected schema and a data dictionary And CSV conforms to RFC 4180 with UTF-8 encoding and header row; JSON is one event per line; timestamps are ISO 8601 UTC And exports up to 1,000,000 events complete within 30 minutes and are chunked into files of <= 100 MB with deterministic filenames And the export includes an integrity manifest with SHA-256 checksums for each file

Webhook Delivery with Idempotency and Security

Given a subscriber registers a webhook with endpoint URL and HMAC secret When new audit events occur Then the system sends POST requests within 30 seconds containing the event payload, a unique delivery_id, and an Idempotency-Key header And each request includes an X-Signature header with SHA-256 HMAC of the body and a timestamp so receivers can verify authenticity and freshness And on non-2xx responses or timeouts, deliveries are retried with exponential backoff for up to 24 hours, then marked failed and an alert is emitted And deliveries for the same request_id preserve order, and duplicate processing is prevented via Idempotency-Key reuse

E-Discovery Search Query and Export

Given a compliance user with e-discovery permission accesses audit search When they query by keyword phrase, approver, decision type, date range, asset_id, workflow_version, and justification_text Then results return within 2 seconds for datasets up to 50,000 records and within 10 seconds for up to 1,000,000 records And queries support exact phrase (quoted), boolean AND/OR, and field filters; results include total count and are paginated And selected results can be exported to CSV/JSON with the same schema as standard audit exports

Retention Policies and Data Residency Enforcement

Given a workspace in region EU sets a 7-year retention policy and a legal hold on request_id=XYZ When the nightly purge job runs Then records older than 7 years without legal holds are irreversibly deleted and a signed purge report is added to the audit log And records under legal hold are retained until the hold is removed And all audit data, exports, and backups are stored and processed exclusively in the configured region and never leave it And when retention settings are shortened, the system requires explicit confirmation and enforces a 7-day grace period before deletions execute

Role-Based Access, Delegation, and Overrides

"As a workspace admin, I want role-based permissions and delegation so that only authorized people can approve and we have coverage when someone is out."

Description

Enforce role- and scope-based permissions for creating workflows, approving steps, and overriding decisions. Support temporary delegation for out-of-office coverage, approver alternates, and emergency overrides requiring a reason, multi-factor confirmation, and automatic notifications. Highlight overrides in dashboards and the audit log, and restrict high-risk approvals to designated roles or multi-approver quorum as configured.

Acceptance Criteria

Role- & Scope-Based Permissions Enforcement

Given a user with role "Workflow Creator" scoped to Brand=A, when they create a workflow under Brand=A, then the API returns 201 and the workflow scope is set to Brand=A. Given the same user attempts to create a workflow under Brand=B, when they submit, then the API returns 403 and no workflow is created. Given a user without the "Approver" role views a pending approval, when the approval screen loads, then Approve and Override actions are hidden/disabled and any direct API calls are blocked with 403. Given a user with role "Approver" scoped to Catalog=Shoes, when they approve an item in Catalog=Shoes, then the approval succeeds (200) and is recorded; when they attempt outside their scope, then the action is blocked (403) and logged. Given any permission-denied attempt occurs, when the system blocks the action, then an audit entry is created with user ID, action, resource ID, scope, and timestamp.

Time-Bound Delegation for Out-of-Office Coverage

Given a delegator configures delegation to a delegatee with start/end timestamps and scope, when the delegatee accepts, then the delegation activates at the start time and deactivates at the end time automatically. Given the delegation is active, when an approval assigned to the delegator arrives within the delegated scope, then the delegatee receives notifications and can approve or decline it. Given the delegatee takes action under delegation, when the audit log records the event, then it attributes "delegatee on behalf of delegator" and stores the delegation ID. Given the delegation has ended or is outside scope, when the delegatee attempts action, then the system returns 403 and no state change occurs. Given a delegation is created, then it cannot grant access beyond the delegator's own role and scopes; attempts to exceed are rejected (400) at save-time. Given delegation activation or deactivation occurs, then email/Slack notifications are sent to both delegator and delegatee within 1 minute.

Auto-Routing to Alternates on OOO or SLA Breach

Given a step has a primary approver and alternates [A,B] with SLA=24h, when the primary is marked Out-of-Office or the SLA expires without action, then the approval is reassigned to the first eligible alternate and both primary and alternate are notified. Given alternates are evaluated, when an alternate lacks required role/scope, then they are skipped and the next is evaluated until an eligible alternate is found or none exist. Given an alternate approves, then the step completes and further responses from other alternates are ignored; duplicate approvals are prevented at the API (409). Given any reassignment occurs, then the audit log records original assignee, reason (OOO/SLA), new assignee, and timestamp.

Emergency Override with Reason and MFA

Given a user with the "Override" permission initiates an override, when prompted, then they must supply a reason of at least 10 characters and complete MFA within 60 seconds or the attempt fails (401/422) with no state change. Given MFA succeeds and the user is within scope, when they confirm the override, then the system advances the workflow, records the action as an override, and tags the record with reason, MFA method, and actor. Given an override completes, then notifications are sent immediately to workflow owner, security/admin group, and the bypassed approver(s) via email/Slack. Given an override is attempted by a delegate without explicit "Override" permission, then it is blocked (403) and logged.

Override Visibility in Dashboards and Audit Log

Given an approval was completed via override, when dashboards load, then the item displays a visible "Override" badge/icon and can be filtered using a "Show Overrides Only" control. Given the audit log is queried for that item, then the entry includes override flag, actor, original approver(s), reason text, MFA status/method, step ID, and timestamps. Given exports are generated (CSV/JSON), then override-specific fields are included. Given a normal (non-override) approval occurs, then no override badge appears and no override fields are populated.

High-Risk Approval Quorum and Role Restrictions

Given a High-Risk step is configured with allowed roles {Owner, Senior Approver} and quorum=2, when approvals are collected, then the step completes only after approvals from two distinct eligible users are recorded. Given an ineligible user attempts to approve a High-Risk step, then the attempt is blocked (403) and logged with reason "role/scope not permitted". Given fewer than quorum approvals are recorded, when the SLA expires, then escalation rules trigger and the step remains incomplete. Given overrides are allowed for High-Risk steps with configured override quorum=2, when only one override actor confirms, then the override does not complete; when two distinct override actors confirm within the allowed window, then the override completes and is logged as High-Risk Override.

Release Scheduler

Time-lock when new preset versions go live. Pin versions to specific batches, freeze changes during drops, and roll back instantly if needed—keeping imagery consistent mid-campaign and avoiding surprises during high-velocity launches.

Requirements

Versioned Preset Store

"As a brand manager, I want to create immutable versions of style presets so that I can release changes without affecting in-flight campaigns."

Description

Introduce immutable, versioned style presets with semantic versioning and metadata (creator, createdAt, changelog). Past versions are read-only; new versions are created via clone-and-edit to preserve auditability and reproducibility. Ensure all processing services can resolve a preset by stable version identifier and that rendering behavior is deterministic across versions. Include validation for backward compatibility, diff view between versions, and referential integrity so batches and jobs always resolve to a valid version. Integrate with PixelLift’s preset editor, batch processor, and permissions model.

Acceptance Criteria

Publish Immutable Preset Version (SemVer + Metadata)

Given a user with "Preset Editor" permission has created a new preset draft When they set the version to "1.0.0", provide a non-empty changelog, and click Publish Then the system validates semantic versioning (MAJOR.MINOR.PATCH), stamps createdAt (UTC), and records creator metadata And the version state becomes read-only; any update attempt to preset fields returns 409 "Preset version is immutable" And using "Clone" from 1.0.0 creates a new draft prepopulated with identical settings and cleared version field And the system suggests the next version (1.0.1 by default) and requires a new changelog on publish

Stable Version Resolution and Deterministic Rendering

Given a preset reference in the form presetId@1.2.0 is provided to the editor, batch processor, and renderer services When each service resolves the reference Then all services retrieve an identical configuration payload (byte hash equality) And processing the same source image twice with presetId@1.2.0 yields byte-identical outputs (checksum match) across runs and environments And resolving a preset without a version (presetId) returns the current default version id And requesting a non-existent version returns 404 with a machine-readable error code PRESET_VERSION_NOT_FOUND

Backward Compatibility Validation on Publish

Given a draft cloned from presetId@1.2.0 is prepared for release as 1.2.1 (patch) When only non-breaking fields are modified (e.g., numeric parameter adjustments within allowed ranges) Then Publish succeeds and the changelog is stored Given a draft includes breaking changes (e.g., removal of a field or algorithm type change) When the target version is a patch or minor bump Then Publish is blocked with error code INCOMPATIBLE_VERSION_BUMP and a list of detected breaking changes And setting the target version to 2.0.0 (major) for the same changes allows Publish to proceed

Version Diff View with Previews and Changelog

Given a user selects two versions of the same preset (e.g., 1.0.0 vs 1.1.0) When the diff view is opened Then the UI displays field-by-field differences categorized as added/removed/changed with counts And a side-by-side preview renders on three sample images using each version within 5 seconds total And the changelog for the newer version is displayed alongside the diff And the user can export the diff as JSON via a Download action, producing a file that includes before/after values

Referential Integrity for Batches and Jobs

Given existing batches and jobs reference presetId@1.0.0 When version 1.0.0 is deprecated or a newer default is published Then all existing references continue to resolve successfully without mutation And attempts to delete version 1.0.0 are blocked with 409 "Version in use" while references exist And integrity checks report zero dangling references after migrations or cleanup operations And if a referenced version is forcibly removed in a test environment, dependent jobs fail fast with 404 and include remediation guidance in the error payload

Permissions and Audit Logging for Versioned Presets

Given roles Admin, Preset Editor, and Viewer exist Then Admin and Preset Editor can create, clone, and publish versions; only Admin can deprecate or delete versions; Viewer has read-only access And unauthorized actions return 403 with error code INSUFFICIENT_PERMISSIONS and are recorded And every create/clone/publish/deprecate/delete action writes an immutable audit record including actor id, action, version id, timestamp (UTC), and a diff hash And audit records are queryable by version id and actor

Release Scheduling, Pinning, Freeze, and Rollback

Given version 1.1.0 is scheduled to go live at 2025-10-01T10:00:00Z When the current time is before the go-live Then the default version remains on the previous version When the go-live time is reached Then the default version for new batches flips to 1.1.0 automatically and a VERSION_WENT_LIVE event is emitted And batches pinned to 1.0.0 continue to use 1.0.0 regardless of default changes And a freeze window on an active drop blocks changes to pinned versions and schedules; attempts return 423 Locked And a one-click rollback sets the default back to the prior version within 60 seconds and emits a VERSION_ROLLED_BACK event without altering existing pinned batches

Batch Version Pinning

"As a seller uploading a new catalog batch, I want to pin the exact preset version used so that reprocessing later yields the same look."

Description

Enable explicit pinning of a specific preset version to each batch at creation and during reprocessing. Persist the mapping batchId → presetVersion so all renders, retries, and regenerations use the pinned version for consistent visual output. Provide UI and API options to select a version, prevent accidental drift, and display pinned status in batch details. Handle edge cases such as archived versions, deleted presets, and cross-workspace moves by enforcing safe fallbacks and warnings.

Acceptance Criteria

Pin Preset Version During Batch Creation (UI)

Given I am on Create Batch UI with a selected preset that has multiple versions And I select a specific preset version from the version picker When I create the batch Then the batch is saved with pinned=true and presetVersionId set to the selected version And all initial renders use that presetVersionId And changing the preset’s default version after creation does not alter the batch’s pinned version And Batch Details displays the pinned version label, ID, and a "Pinned" badge

Pin Preset Version via API on Batch Create/Update

Given a POST /batches request includes presetId and a valid presetVersionId belonging to that preset When the request is submitted with valid authentication Then the response is 201 and the body includes pinned=true and the same presetVersionId And a subsequent GET /batches/{id} returns the same pinned fields Given a POST /batches includes presetId but omits presetVersionId Then the system pins to the latest active version at creation time and returns its presetVersionId Given the provided presetVersionId does not belong to the preset Then the response is 422 with error code PinnedVersionInvalid Given a PATCH /batches/{id} with presetVersionId to re-pin and the user has Editor role and the batch is not currently processing Then the response is 200 and future renders use the new presetVersionId Given a PATCH occurs while the batch is processing Then the response is 409 Conflict with error code BatchBusy

Use Pinned Version for All Renders, Retries, and Regenerations

Given a batch is pinned to preset version V1 And the preset’s default version is later updated to V2 When I retry failed items, regenerate outputs, or reprocess the batch Then all processing jobs use V1 And each render job’s metadata includes presetVersionId=V1 And API GET /renders for the batch returns presetVersionId=V1 for the associated renders

Behavior with Archived or Deleted Preset Versions

Given a batch is pinned to a preset version that becomes Archived When I view Batch Details Then the pinned version shows an "Archived" badge with a non-blocking warning And reprocessing is allowed using the archived version Given a batch is pinned to a preset version that is Deleted When I attempt to reprocess or render Then processing is blocked and the UI shows a blocking banner requiring re-pin And API operations return 410 Gone with error code PinnedVersionDeleted And the UI offers a one-click re-pin to the latest active version with explicit confirmation And upon confirmation, the batch is re-pinned to the selected version and an audit entry is created

Display and Communicate Pinned Status in Batch Details and Lists

Given a batch with a pinned version When I open Batch Details Then I see pinned=true, preset name, version label, version ID, release date, and a link to release notes And the batch list shows a "Pinned" indicator and supports filtering by pinned status And API GET /batches includes pinned, presetVersionId, pinnedAt, and pinnedBy fields

Cross-Workspace Batch Move with Pinned Versions

Given I initiate moving a batch to another workspace And the target workspace contains the same preset and preset version Then the move completes and the batch retains the same presetVersionId Given the target workspace lacks the preset or the pinned version Then the move is blocked and a mapping dialog requires selecting an available preset version in the target workspace And the move cannot complete until a valid version is selected or the move is canceled And upon completion with a selection, the batch is re-pinned to the chosen version and an audit entry is recorded

Controlled Re-Pinning and Audit Trail

Given I have Editor or higher permissions When I change the batch’s pinned version in the UI Then a confirmation modal summarizes oldVersionId -> newVersionId and requires explicit confirmation And upon confirmation, the pinned version updates, future renders use the new version, and an audit log entry is recorded with actor, timestamp, oldVersionId, and newVersionId Given I lack sufficient permissions Then the re-pin control is disabled in the UI and API PATCH /batches/{id} returns 403 Forbidden with error code InsufficientPermissions

Timed Release & Timezone Control

"As a marketing lead, I want to schedule when a new preset version becomes active in my timezone so that launches switch over consistently at the planned moment."

Description

Allow scheduling of a new preset version to become active at a specific date/time with explicit timezone selection and DST awareness. The scheduler performs an atomic pointer switch for the preset’s active version and guarantees idempotency and retry on transient failures. Provide conflict detection (e.g., overlapping schedules, frozen windows), preflight validation, and a countdown/status view. Ensure safe handling of in-progress jobs (finish with old version) and new jobs (start with new version) with clear cutover semantics. Integrate with the job orchestrator and system clock service for accuracy and reliability.

Acceptance Criteria

DST-Aware Timezone Scheduling

Given I select timezone "America/Los_Angeles" and choose 2025-03-09 02:30 local time When I attempt to save the schedule Then the system rejects the save with error code TIME_INVALID_DST and suggests the nearest valid local times (e.g., 03:00), and the UTC preview for 03:00 local displays 2025-03-09T10:00:00Z Given I select timezone "America/Los_Angeles" and choose 2025-11-02 01:30 local time When I attempt to save the schedule without disambiguating offset Then the system requires me to choose either "UTC-07 (before fallback)" or "UTC-08 (after fallback)", and the saved schedule stores the resolved absolute UTC instant accordingly Given a schedule is saved with a selected timezone When I view the schedule details Then I see both the local wall time with offset and the canonical UTC time, and the cutover executes at the stored UTC instant per the system clock service

Atomic Cutover and Job Routing

Given preset P has active version v1 and a scheduled switch to v2 at time T (UTC) And job J1 began processing at time t1 < T And job J2 is submitted at time t2 >= T When time reaches T Then the active pointer switches from v1 to v2 atomically within 1 second And J1 completes using v1 exclusively And J2 starts using v2 exclusively And no job processes a mix of v1 and v2 within a single job And an audit event preset_version_activated for v2 is recorded exactly once with event_time >= T

Idempotent Switch with Retry on Transient Failure

Given a transient network error occurs after issuing the cutover command for preset P to version v2 at time T When the scheduler retries the cutover using the same idempotency key Then the final active version is v2, only one audit/event record exists for the cutover, and duplicate notifications are not sent Given duplicate cutover events are received within 60 seconds for the same preset and target version When the second event is processed Then it results in a no-op with a 200 response indicating idempotency, and no additional side effects occur Given the scheduler process crashes mid-cutover When a standby instance resumes and retries within 60 seconds Then the cutover completes successfully without manual intervention and without leaving stale locks

Conflict Detection: Overlaps and Freeze Windows

Given a preset has a freeze window from Fstart to Fend When a user schedules an activation at time T where Fstart <= T <= Fend Then the system blocks the action with error code SCHEDULE_BLOCKED_FROZEN and displays the freeze window details Given a preset already has a pending scheduled activation at T1 When a user attempts to create a second scheduled activation for the same preset Then the system blocks the action with error code SCHEDULE_CONFLICT and shows the existing schedule details; no new schedule is created Given preset P has version vX pinned to Batch B When a new activation of version vY is scheduled Then the preflight informs "Batch B will continue using its pinned version" and the scheduler excludes Batch B from cutover without blocking the schedule

Preflight Validation and Confirmation Gate

Given I click Schedule for preset P to activate version v2 at T with timezone Z When preflight runs Then it validates: v2 exists and is published (not archived), user has Schedule permission for P, job orchestrator is reachable, and system clock service health indicates skew < 100 ms; any failed check is shown with specific error codes and the schedule is not created Given all preflight checks pass When I proceed to confirmation Then I am shown a summary including preset, current version, new version, activation time in local (with offset) and UTC, cutover semantics, and affected scope; I must confirm explicitly before the schedule is created Given the schedule is created When I inspect the record via API Then it includes fields: preset_id, target_version_id, activation_utc, timezone, local_time_display, created_by, idempotency_key, and status=Scheduled

Countdown and Status Visibility

Given a future activation is scheduled for preset P at time T (UTC) When I view the schedule detail page Then I see a live countdown to T updating at least once per second, showing both local time (with offset) and UTC; if detected client clock skew > 5 seconds relative to server time, a warning is displayed Given the activation is approaching When time reaches T Then status transitions are reflected as: Scheduled -> Cutting Over (for up to 60 seconds) -> Live upon success, or Failed if not completed by T+60s; the same states are returned by the status API Given I cancel the schedule before T When I confirm cancellation Then the countdown stops, status becomes Canceled, and no cutover occurs at T

Change Freeze Windows

"As a campaign owner, I want to freeze preset changes during a drop window so that no accidental edits alter live imagery."

Description

Introduce configurable freeze windows to block preset edits and releases during critical campaign periods. Support per-workspace and per-preset scopes, recurring and one-off windows, and admin override with justification. Provide UI indicators, API enforcement, and pre-schedule validation that prevents creating releases inside frozen periods. Log all override attempts and enforce granular permissions to reduce risk of accidental changes mid-drop.

Acceptance Criteria

Block Edits and Releases During Active Freeze

Given an active freeze window applies to the target preset or workspace When a user with Editor role attempts to save preset parameter changes via UI Then the Save action is prevented, controls remain disabled, and the UI displays a reason indicating the freeze end timestamp in the workspace timezone And no changes are persisted to the preset version Given an active freeze window applies to the target preset or workspace When a client calls the API to publish a new preset version or attach a preset version to a batch Then the request fails with HTTP 403 and error code FREEZE_WINDOW_BLOCKED including windowId and endsAt fields And zero publish jobs are enqueued and no side effects occur Given no active freeze window applies When the same edit or release actions are performed Then the actions succeed with standard response codes and persisted changes

Pre-Schedule Validation Blocks Releases in Frozen Periods

Given a freeze window covers 2025-11-25 09:00–12:00 in the workspace timezone When a user selects 2025-11-25 10:00 for a preset release in the Release Scheduler and clicks Save Then the client shows an inline validation error stating the selection is within a freeze window and prevents saving And the UI suggests the nearest available datetime after the freeze ends Given the same request is attempted via API When POST /v1/releases is called with a scheduledAt inside a freeze window Then the API responds HTTP 422 with error code FREEZE_WINDOW_VIOLATION and includes fields nearestAvailableAt and conflictingWindowId And the release is not created

Scope: Workspace vs Preset Freeze Precedence

Given a workspace-level freeze window is active and a preset-level freeze window is not configured for Preset A When a user attempts to edit or release Preset A Then the action is blocked due to the workspace freeze Given a preset-level freeze window is active for Preset B while the workspace has no active freeze When a user attempts to edit or release Preset B Then the action is blocked due to the preset-level freeze only Given both workspace and preset-level freeze windows overlap for Preset C When a user views allowed times in the scheduler for Preset C Then the blocked intervals reflect the union of both freezes And read-only operations (e.g., viewing preset details) remain available

Recurring and One-Off Freeze Windows with Timezone & DST Handling

Given a recurring weekly freeze is configured for Fridays 08:00–20:00 in America/Los_Angeles When the calendar transitions across DST changes Then enforcement occurs at 08:00–20:00 local wall-clock time each Friday regardless of DST shift Given a one-off freeze is configured on 2025-12-01 06:00–14:00 local time When both the recurring Friday freeze and the one-off window overlap a date Then the system enforces the union of blocked intervals for that date And UI calendars shade the full union as unavailable Given overlapping freeze windows are configured via API When GET /v1/freeze-windows is called Then the API returns all configured windows with timezone, recurrence, and effective intervals, and clearly identifies overlaps via overlappingWindowIds

Admin Override Requires Justification and Scoped Duration

Given an active freeze window applies When a Workspace Admin initiates an override Then they must provide a justification of at least 20 characters and select a scope of either Single Operation or Time-bound (max 30 minutes) And the override cannot be activated without meeting both requirements Given a valid override is active and scoped to Single Operation When the admin performs one blocked action (e.g., publishing a preset version) Then the action succeeds and the override automatically expires immediately after Given a non-admin attempts to activate an override When they submit the override form or call the API endpoint Then the request is rejected with HTTP 403 and error code INSUFFICIENT_ROLE Given any override is activated When the action completes Then an audit record is created including actorId, role, targetId, action, windowId, justification, scope, startedAt, endedAt, and outcome

UI Indicators and Disabled Controls During Freeze

Given an active freeze window applies to a preset or workspace When the user opens the Preset List, Preset Editor, or Release Scheduler Then a visible Frozen badge appears for affected presets and a banner displays next available edit time And edit/publish controls are disabled with a tooltip explaining the freeze and end time And the indicators are accessible (ARIA labels provided, tooltip content reachable by keyboard) Given no active freeze window applies When the same pages are opened Then no Frozen indicators are shown and all controls are enabled

Granular Permissions and Change Logging for Freeze Windows

Given role-based access control is configured When a Workspace Owner or Admin attempts to create, update, or delete a freeze window via UI or API Then the action succeeds with HTTP 200/201 and the window is persisted Given an Editor or Viewer attempts the same When they submit the request Then the action is rejected with HTTP 403 and error code INSUFFICIENT_ROLE Given any freeze window is created, updated, or deleted When the operation completes Then an immutable audit log entry is recorded with actorId, role, operation, windowId, scope (workspace/preset), recurrence, timezone, previousValues, newValues, timestamp, and ipAddress And GET /v1/audit-logs?eventType=freeze-window returns the entry within 5 seconds of the operation

One-click Rollback & Restore

"As an operations manager, I want to roll back to a prior preset version with one click so that I can quickly recover from unexpected visual issues."

Description

Provide an atomic rollback action that instantly reassigns the active version pointer to the prior stable version, with optional selection of a specific historical version. Ensure rollbacks are idempotent, logged, permission-gated, and include safety checks (e.g., cannot roll back to deleted or incompatible versions). Offer UI confirmation with impact summary and an API endpoint for automated recovery. Handle job routing so new jobs use the restored version while in-flight jobs complete with the previously active version.

Acceptance Criteria

Atomic One-Click Rollback Switch

Given a preset P with active version V3 and prior stable version V2, and at least one in-flight job using V3 When an authorized user triggers the one-click rollback to the prior stable version Then the active version pointer for P updates atomically to V2 within 2 seconds and is immediately reflected in both UI and API reads And no intermediate state is observable (reads return either V3 before commit or V2 after commit) And in-flight jobs continue and complete on V3 without restart or version reassignment And all new jobs submitted after the commit route to V2 100% of the time And repeating the same rollback within 5 minutes results in a no-op with 200 OK and no additional side effects (idempotent)

Historical Version Selection and Safety Checks

Given a preset P with versions V1, V2, V3 where V1 and V2 are compatible, V0 is deleted, and V4 is incompatible When a user selects "Rollback to…" and chooses V1 Then the system validates the target exists, is not deleted/archived, is enabled, and is schema-compatible with P And on pass, the active pointer updates to V1; on fail, the rollback is blocked without side effects And attempting rollback to a deleted version returns 400 with code VERSION_NOT_FOUND and a human-readable message And attempting rollback to an incompatible version returns 409 with code VERSION_INCOMPATIBLE and includes the incompatibility reason And if organizational policy blocks rollback, the call returns 423 with code ROLLBACK_BLOCKED and a remediation hint

Permission-Gated Rollback with Audit Logging

Given a user without the "Preset:Rollback" permission attempts a rollback via UI or API When the action is executed Then the system denies with 403 FORBIDDEN and code FORBIDDEN_OPERATION, without changing the active version And for an authorized user, a rollback (attempted or successful) writes an immutable audit log entry containing: presetId, previousVersionId, newVersionId (if any), actorId, actorRole, source (UI/API), timestamp, requestId, idempotencyKey (if provided), rationale (if provided), outcome (SUCCESS/FAILURE), and affectedScopes (e.g., pinned batches count) And audit entries are queryable by admins by presetId/date range and exportable as CSV/JSON

UI Confirmation Modal with Impact Summary

Given an authorized user initiates rollback from the preset detail page When the confirmation modal opens Then it displays: current active version, proposed target version, count of in-flight jobs on current version, count of queued jobs impacted, note that in-flight jobs will not be switched, note that pinned batches remain on their pinned versions, and any active freeze windows affecting scope And the Confirm button remains disabled until pre-checks load (<= 2 seconds) and the user explicitly confirms (e.g., checkbox or typing "ROLLBACK") And if pre-checks fail (e.g., target incompatible or policy freeze without override), the modal shows an actionable error and prevents submission And on confirm, the modal closes only after the rollback commits and shows a success toast summarizing the change

API Rollback Endpoint with Idempotency and Concurrency Control

Given a client calls POST /presets/{presetId}/rollback with an optional targetVersionId and Idempotency-Key header When the request is valid and authorized Then the server performs the rollback and returns 200 with body { presetId, previousVersionId, newVersionId, committedAt, routerEpoch } And duplicate requests with the same Idempotency-Key within 24 hours return the original result without re-executing side effects And concurrent rollback attempts on the same preset result in exactly one success; losers receive 409 with code CONFLICT_ACTIVE_CHANGE And p95 latency is <= 800 ms under nominal load; the version pointer is globally consistent within 2 seconds of commit

Job Routing Consistency with Pins and Freeze Windows

Given some batches are pinned to version V3 and a global drop freeze window may be active When a rollback to V2 is executed Then the job router sends all new unpinned jobs to V2 within 2 seconds of commit And pinned batches continue on their pinned versions unaffected by the rollback And scheduled future releases retain their configured go-live times and target versions and are not altered by the rollback And if a freeze window blocks version changes, rollback is prevented unless the actor has "Preset:OverrideFreeze"; on override, a rationale is required and recorded in audit logs And no in-flight jobs are re-routed; queue health metrics (enqueue/dequeue rates, failure rate) remain within baseline ±5% over 10 minutes post-rollback

Audit Log & Alerts

"As a team admin, I want a clear audit trail and alerts for releases and rollbacks so that I can monitor changes and respond to failures."

Description

Record all release-related events—version creation, scheduling, activation, freeze/override, pin changes, and rollback—with actor, timestamp, and affected entities. Provide searchable UI, export, and retention policies. Emit real-time notifications to email and Slack on successes, failures, and upcoming cutovers, with configurable recipients per workspace. Surface failure reasons and remediation tips inline to speed incident response.

Acceptance Criteria

Event Logging Coverage & Fidelity

Given a workspace with Release Scheduler enabled When any of the following events occur: preset version created; schedule created or updated; activation started or completed; freeze window applied or removed; override applied or removed; batch pin added, changed, or removed; rollback initiated or completed Then an audit log entry is persisted for each event with fields: event_type, actor_id, actor_name, actor_type (user|service), occurred_at (UTC ISO-8601), workspace_id, preset_id, from_version_id (nullable), to_version_id (nullable), batch_ids (array), schedule_id (nullable), reason (nullable), outcome (success|failure), correlation_id, entry_id And the log entry is immutable; any correction results in a new entry that references the prior entry via prior_entry_id And the entry becomes queryable within 5 seconds of the event time

Audit Log Search & Filter

Given an audit log with at least 5,000 events in the last 30 days When a user opens the Audit Log UI and applies any combination of filters: date range, event_type, actor (name or ID), preset_id, version_id, batch_id, outcome, text search (reason) Then results include all and only records matching the filters within the current workspace And the first page of 50 results returns in ≤ 2 seconds for up to 10,000 matching records And results are sortable by occurred_at (asc|desc), actor_name, event_type And the UI displays total count and supports pagination (configurable page size: 25/50/100) And clearing filters resets the view to the default last 7 days

Audit Log Export & Retention Enforcement

Given the workspace retention policy is set to 180 days When a user requests an export (CSV or JSON) for a selected date range Then the system validates the range is within retention and the estimated size ≤ 500,000 rows; otherwise prompts to narrow the range And upon confirmation an export job is created and recorded in the audit log with correlation_id And for exports ≤ 500,000 rows a downloadable file is produced within 10 minutes, with a 24-hour expiring link And the exported file includes header fields and all logged fields in UTC And records older than 180 days are neither searchable nor exportable And when an admin updates retention to a new value (e.g., 365 days), subsequent searches and exports honor the new policy and the change is logged (old→new)

Real-time Email & Slack Notifications

Given notification recipients are configured for the workspace When a scheduled activation is 15 minutes away Then an upcoming cutover notification is delivered to subscribed recipients with: preset name, from_version_id, to_version_id, schedule_time (UTC), affected batches count/list (≤ 20 listed, rest summarized), and a deep link to details When an activation or rollback completes with success or failure Then a notification is delivered within 60 seconds including: event_type, outcome, error_code and message if failure, correlation_id, and deep link And duplicate notifications with the same correlation_id are not sent more than once And if Slack delivery fails (non-2xx), the failure is logged and email is attempted as a fallback And per-event-type subscriptions (upcoming_cutover, activation_success, activation_failure, rollback_success, rollback_failure) are respected

Recipient Configuration & Permissions

Given a user with Workspace Admin role opens Notifications settings When they add or remove email recipients and Slack webhooks Then emails must pass format validation and Slack webhooks must pass a connectivity test (HTTP 2xx) before saving And recipients can be subscribed per event type (upcoming_cutover, activation_success, activation_failure, rollback_success, rollback_failure) And saving changes records a configuration-changed audit entry with before/after (secrets redacted) And users without Admin role can view but cannot modify recipients (controls disabled and server rejects writes)

Inline Failure Reasons & Remediation

Given a scheduled activation or rollback fails When a user opens the incident details via the audit log or notification deep link Then the UI displays error_code, error_message, failed_step, correlation_id, affected entities (workspace, preset_id, version_id, batch_ids), and timestamp And at least one remediation tip is displayed with a link to relevant docs or settings (e.g., re-auth Slack, adjust permissions, resolve conflicting freeze) And a context-appropriate action is available (Retry, Rollback, or Dismiss) based on event type and state And details and tips render within 10 seconds of page load And acknowledging the incident records an audit entry with actor and timestamp

Release Webhooks & API Events

"As a developer integrating PixelLift, I want webhook events and APIs for releases so that our storefront and workflows can react to changes in real time."

Description

Expose secure APIs to manage schedules, pins, and freeze windows, and publish signed webhooks for key lifecycle events (scheduled, activated, skipped, failed, rolled_back). Include HMAC signature verification, retries with backoff, idempotency keys, and per-workspace rate limits. Provide event payloads that include preset identifiers, version, timestamps, and affected batches so external systems (CMS, storefront, CI) can react in real time to visual changes.

Acceptance Criteria

Webhook HMAC Signature & Replay Protection

Given a workspace has a webhook endpoint and secret S When PixelLift sends any release lifecycle event webhook (scheduled, activated, skipped, failed, rolled_back) Then the request includes headers: X-PixelLift-Timestamp (epoch ms), X-PixelLift-Signature (HMAC-SHA256 over "{timestamp}.{raw_body}" using S), X-PixelLift-Event-ID (UUID), X-PixelLift-Delivery-ID (UUID), X-PixelLift-Delivery-Attempt (integer >= 1) Given the consumer recomputes the signature with S over the exact raw body and X-PixelLift-Timestamp within a 5-minute tolerance When compared to X-PixelLift-Signature Then the signatures match Given the same delivery is retried When sent again Then X-PixelLift-Delivery-ID remains the same and X-PixelLift-Delivery-Attempt increments by 1 Given the webhook body or timestamp is altered in transit When the consumer recomputes the HMAC Then the signature does not validate

Event Delivery, Exponential Backoff, and At-Least-Once

Given a subscriber responds with 2xx When a release lifecycle event is generated Then 99% of deliveries complete within 10 seconds of event creation and 100% complete within 60 seconds Given a subscriber responds with 5xx or times out When delivery fails Then PixelLift retries with exponential backoff and full jitter for up to 6 total attempts (initial + 5 retries), each delay capped at 60 seconds, with a total retry window <= 5 minutes Given the final attempt also fails When retries are exhausted Then the delivery is marked failed; no further retries occur; a delivery record is accessible via API including attempt history and last response/status Given multiple events exist for the same preset_id When delivered Then deliveries maintain per-preset causal order (earlier events are attempted before later ones) Given a transient failure When a retry receives a 2xx Then the delivery is marked delivered and no additional retries occur

Idempotency for Management APIs

Given a client sends POST to create or mutate schedules, pins, or freeze windows with an Idempotency-Key header and identical request body When the same request is retried within 24 hours Then the API returns 200/201 with the original response body, echoes Idempotency-Key, and no duplicate side effects or duplicate events are created Given two concurrent POST requests with the same Idempotency-Key When processed Then exactly one operation is committed; the other returns the same result Given a non-matching body is sent with a reused Idempotency-Key When processed Then the API responds 409 Conflict indicating key reuse mismatch and performs no side effects Given GET and DELETE endpoints When supplied an Idempotency-Key Then GET ignores the header; DELETE is safe to retry (idempotent) and does not create duplicate events

Per-Workspace Rate Limiting for Management APIs

Given a workspace W has a configured limit of 600 requests per 10 minutes for management APIs When W sends requests under the limit Then each response includes X-RateLimit-Limit: 600, X-RateLimit-Remaining with the correct remaining count, and X-RateLimit-Reset with the reset epoch seconds Given W exceeds the limit within the window When an additional request is received Then the API responds 429 Too Many Requests with Retry-After set to remaining seconds until reset and performs no side effects Given another workspace W2 with a different limit When W2 sends requests Then W2’s quota is enforced independently of W’s Given outbound webhook deliveries occur When measuring API usage Then webhook delivery traffic does not consume management API rate limit quota

Event Payload Schema Completeness

Given any release lifecycle event (scheduled, activated, skipped, failed, rolled_back) When the webhook is delivered Then the JSON payload validates against the published schema (via field schema_version) and includes: event_id (UUID), event_type, occurred_at (RFC3339), workspace_id, preset_id, preset_version, affected_batch_ids (array), actor (user_id or "system"), reason (for "skipped"/"failed"), previous_version (for "rolled_back"), and metadata.trace_id Given a new optional field is added in a newer schema_version When delivered to an older client Then required fields and semantics remain backward-compatible Given an event of type "rolled_back" When delivered Then payload contains from_version and to_version with correct values and a non-empty reason Given an "activated" event resulting from a scheduled release When delivered Then payload contains schedule_id and activation_time matching server-side records

Secure APIs for Schedules, Pins, and Freeze Windows

Given a workspace-scoped API key with permission "releases:write" When calling endpoints to create/update/delete schedules, pin versions to batches, and create freeze windows Then unauthorized requests return 401, insufficient scope returns 403, and authorized requests return 2xx with stable resource IDs Given a valid schedule creation specifying preset_id, preset_version, and a future activation_time When created Then the API returns 201 with schedule_id and a "scheduled" event is emitted with matching fields Given a valid pin request specifying preset_version and batch_ids When processed Then the API returns 200/201, the batches are locked to the pinned version, and an "activated" event includes affected_batch_ids and preset_version Given an active freeze window overlapping an activation_time or pin attempt When a change is attempted Then the API rejects with 409 Conflict and emits a "skipped" event with reason "freeze_window" Given a rollback request for a preset to a prior version When executed Then the API returns 200 and a "rolled_back" event is emitted with from_version, to_version, and affected_batch_ids

Brand Binding

Automatic enforcement of preset-to-brand and channel pairing. Block off-brand usage, auto-assign the correct preset based on supplier or folder tags, and warn on mismatches—reducing rework and safeguarding visual identity across catalogs.

Requirements

Brand–Preset Mapping Engine

"As a brand manager, I want to define which style presets are approved per brand and channel so that all processed images remain consistent with our visual identity."

Description

A centralized mapping service that binds each brand to its approved style presets and channel variants. Supports one-to-many relationships, channel-level overrides, versioning, and effective date ranges to accommodate seasonal campaigns. Provides default fallbacks when metadata is incomplete and exposes an API for other PixelLift services to resolve the correct preset during batch processing. Ensures every image is processed with the right, brand-compliant preset without manual selection.

Acceptance Criteria

Preset Resolution by Brand and Channel Overrides

Given brand B1 has base preset P1 and channel override Instagram->P1_IG When resolvePreset(brand=B1, channel=Instagram) Then response.presetId = P1_IG and response.mappingVersionId is not null Given brand B1 has base preset P1 and no channel override for Web When resolvePreset(brand=B1, channel=Web) Then response.presetId = P1 Given unknown brand When resolvePreset(brand=Unknown, channel=Web) Then response.presetId = GlobalDefaultPreset and response.warnings includes WARN_FALLBACK_BRAND Given normal load When performing 10,000 single-key lookups over 10 minutes Then p95 latency <= 100 ms and error rate < 0.1%

Auto-Assignment via Supplier and Folder Tags

Given mappings: supplierTag=Acme -> P2; folderTag=Summer24 -> P3 When resolvePreset(brand=B1, channel=Web, metadata={supplierTag:Acme, folderTag:Summer24}) Then response.presetId = P3 Given mapping precedence When conflicting tag mappings exist Then precedence is channelOverride > folderTag > supplierTag > brandDefault > globalDefault and response.decisionPath reflects applied steps Given no metadata tags When resolvePreset(brand=B1, channel=Web) Then response.presetId = brandDefaultPreset Given unit tests covering precedence When running the mapping precedence test suite Then all 12 test cases pass

Effective Date Ranges and Versioning for Seasonal Campaigns

Given brand B1 default P1 (v1) and seasonal override P2 (v2) effective [2025-10-01T00:00Z, 2025-12-31T23:59:59Z] When resolvePreset is called with processingTimestamp=2025-11-15T12:00Z Then response.presetId = P2 and response.mappingVersionId = v2 Given the same configuration When processingTimestamp=2026-01-01T00:00Z Then response.presetId = P1 and response.mappingVersionId = v1 Given overlapping effective ranges for the same brand+channel When both match the timestamp Then the rule with the latest effectiveStartDate wins; if equal, the highest version number wins; if equal, the latest updatedAt wins Given any timestamp ambiguity When resolving Then all timestamps are interpreted in UTC and returned as UTC

Block Off-Brand Preset Usage and Channel Mismatch Warning

Given preset P9 is not approved for brand B1 When processBatch is called with explicitPresetId=P9 for images of brand B1 Then the request is rejected with HTTP 403 and errorCode=ERR_OFF_BRAND and allowedPresetIds are returned Given preset P1 base is approved for brand B1 and channel variant P1_IG exists When processBatch is called with explicitPresetId=P1 and channel=Instagram Then the service auto-corrects to P1_IG, proceeds, and returns warnings=[WARN_CHANNEL_MISMATCH] and appliedPresetId=P1_IG Given any block or auto-correction event When it occurs Then an audit log entry is written with fields {brandId, channel, requestedPresetId, appliedPresetId, userId/requestId, timestamp} within 2 seconds

Batch Resolution API Contract and Performance

Given endpoint POST /v1/preset-resolution When called with a payload of up to 1,000 items Then it returns per-item decisions with HTTP 200 and content-type application/json in under 300 ms p95 and 600 ms p99 Given a requestId header X-Idempotency-Key When the same key is retried Then identical responses are returned and no duplicate side effects are recorded Given sustained traffic of 10,000 resolutions per minute When load-tested for 30 minutes Then success rate >= 99.9% and mean CPU utilization <= 70% Given invalid items in the batch When N out of M items are invalid Then the API returns HTTP 207 Multi-Status, processes valid items, and reports per-item errors with codes

Fallback Hierarchy When Metadata Is Incomplete

Given brand B1 has default preset P1 and global default P0 exists When resolvePreset(brand=B1, channel=Unknown) Then response.presetId = P1 and response.decisionPath includes ["brandDefault"] Given unknown brand and global default P0 exists When resolvePreset(brand=Unknown, channel=Web) Then response.presetId = P0 and response.warnings includes WARN_FALLBACK_BRAND Given no global default configured When resolvePreset cannot determine a preset Then the API returns HTTP 412 with errorCode=ERR_NO_DEFAULT_CONFIG and does not process the image Given any fallback decision When resolved Then response includes decisionPath enumerating each applied rule in order

Auditability and Change History for Mappings

Given mapping changes are made When a mapping is created, updated, or deleted Then a new immutable version is recorded with {versionId, brandId, channel, tags, presetId, effectiveRange, changedBy, changedAt, changeReason} Given the history endpoint GET /v1/mappings/{brandId}/history When called Then it returns the last 100 changes in reverse chronological order within 200 ms p95 Given role RBAC 'BrandAdmin' When a user without this role attempts to modify mappings Then the API returns HTTP 403 ERR_FORBIDDEN Given any resolution response When returned Then it includes mappingVersionId and effectiveRangeStart/End fields referencing the applied version

Rule-Based Auto Assignment

"As an operations lead, I want presets to auto-assign based on supplier and folder tags so that batch uploads require zero manual selection."

Description

A rules engine that auto-assigns presets based on supplier, folder tags, filename patterns, SKU prefixes, EXIF/camera data, or custom metadata. Rules are prioritized with deterministic conflict resolution and fallbacks. Integrates at import and pre-process stages to apply bindings at scale for batch uploads. Includes dry-run mode, decision logging, and idempotent reprocessing to avoid duplicate work.

Acceptance Criteria

Auto-Assign by Supplier on Import (Batch Upload)

Given a rule exists: supplier = "Acme" -> preset = "StudioClean v3" And a batch of 500 images is imported with supplier = "Acme" When the import begins Then 100% of images are auto-assigned preset "StudioClean v3" before entering the processing queue And no manual action is required to apply the preset And each item displays assignment status = "Auto-assigned by rule: supplier=Acme"

Auto-Assign via Filename Pattern and SKU Prefix

Given a rule exists: filename matches "*_hero.*" OR SKU prefix = "HR-" -> preset = "HeroPop v2" And files 12345_hero.jpg and HR-7788.png are imported without supplier or folder tags When the files are evaluated by the rules engine at import Then both files are assigned preset "HeroPop v2" And files not matching the filename or SKU patterns are not assigned by this rule

Auto-Assign via EXIF and Custom Metadata

Given a rule exists: EXIF.CameraModel = "Canon EOS R5" AND custom.collection = "Lookbook" -> preset = "Lookbook SoftLight v1" And an image has EXIF.CameraModel = "Canon EOS R5" and custom.collection = "Lookbook" When the image is imported or reaches the pre-process evaluation stage Then the preset "Lookbook SoftLight v1" is assigned And if the EXIF field is missing or mismatched, this rule is skipped without error and other rules continue to evaluate

Deterministic Rule Priority and Conflict Resolution

Given rules exist: - R1: supplier = "Acme" -> preset = "A" priority = 90 - R2: filename contains "_hero" -> preset = "B" priority = 80 - R3: SKU prefix = "AC-" -> preset = "C" priority = 90 And an image from supplier "Acme" has filename "AC-123_hero.jpg" and SKU "AC-123" When the rules engine evaluates matches Then the applied preset is "A" because higher priority wins and ties are resolved by specificity order: supplier > folder tag > SKU prefix > filename > EXIF > custom metadata; if still tied, lowest rule ID wins And the decision records the evaluated rules, priorities, and the applied tie-breaker

Fallback to Brand/Global Defaults When No Rule Matches

Given no rule matches an image And a brand default preset "BrandDefault v4" exists for the image's brand/channel When the image is evaluated at import or pre-process Then the preset "BrandDefault v4" is assigned And if no brand default exists, the global default preset "Neutral v1" is assigned And the decision record notes "Fallback: Brand Default" or "Fallback: Global Default"

Dry-Run Mode with Decision Logging and Export

Given dry-run mode is enabled for an import job with 200 images And rules R1..Rn are configured When the job is executed in dry-run Then no presets are applied or persisted to any image And a decision report is generated listing for each image: selected preset (if any), matched rule IDs, tie-breaker used, and whether fallback was applied And the report is viewable in the UI and downloadable as CSV And the dry-run summary shows counts for: matched by rule, used brand fallback, used global fallback, no decision

Idempotent Reprocessing and Update Behavior

Given an image was previously auto-assigned preset "P1" and processed When the rules engine is re-run with the same rules and inputs Then no duplicate assignment or reprocessing occurs And when rules change so the image now matches preset "P2" and re-evaluation is invoked with allowUpdates = true Then the assignment updates to "P2" and the image is reprocessed exactly once And when allowUpdates = false, the existing assignment "P1" remains unchanged

Off-Brand Usage Blocker & Override

"As a brand manager, I want the system to block off-brand preset usage and allow controlled overrides so that we reduce rework while retaining governance."

Description

Real-time enforcement that prevents applying non-approved presets to a brand or channel. Provides clear error messaging, suggested compliant alternatives, and a governed override path for authorized roles (with reason codes, approver identity, and time-limited exceptions). Configurable strictness per workspace or brand, with batch-safe handling to stop only offending items while continuing valid ones.

Acceptance Criteria

Real-Time Block on Non-Approved Preset (UI Single Apply)

Given a workspace with brand "Acme" and channel "Amazon" configured to Block non-approved presets And preset "Moody Vibe" is not approved for the Acme-Amazon pairing When a user attempts to apply "Moody Vibe" to an image in the Acme-Amazon context via the UI Then the apply action is prevented (no mutation to the asset) And an error is displayed containing: presetName, brandName, channelName, policyMode=Block And 1–3 compliant preset suggestions are shown, ranked by relevance And the decision is logged with fields: userId, assetId, presetId, brandId, channelId, timestamp, policyMode, overrideAvailable=true And the UI response occurs within 300 ms P95 from click to message

Batch Processing: Partial Continue with Offending Items Isolated

Given a batch of N images where some have a non-approved preset for the active brand-channel When the batch is processed Then compliant items are processed successfully And offending items are blocked without halting the entire batch And the batch result indicates Partial Success with counts: total=N, succeeded=S, blocked=B, failed=F (non-policy failures) And each blocked item has reasonCode=OFF_BRAND_PRESET and 1–3 suggested compliant presets And a downloadable per-item report (CSV and JSON) is available within 60 seconds of batch completion And batch duration overhead is <= 10% compared to an all-compliant baseline of the same size

Governed Override Request and Approval (Four-Eyes)

Given a user with role Editor encounters a Block on applying a non-approved preset When the user submits an override request with required fields: reasonCode (from configured list) and optional comments (<= 500 chars) Then the request is routed to a Brand Admin or Compliance Approver (not the requester) And approval by an eligible approver issues an override token scoped to {brandId, channelId, presetId} with TTL default 24h (configurable 1–168h) And the apply action succeeds only after approval and only within token scope and validity And the audit log records requesterId, approverId, timestamps (requested, approved), tokenId, expiry, reasonCode And if requester==approver, the approval is rejected with code FOUR_EYES_REQUIRED And upon expiry, subsequent applies are blocked again until a new approval is granted

Configurable Strictness per Workspace/Brand

Given policyMode can be set at workspace-level and overridden at brand-level to one of [Block, Warn, Off] When a brand-level mode is set, it takes precedence over the workspace-level mode Then for Warn mode, non-approved preset applies are allowed but display a warning with suggestions and are logged with outcome=WARNED And for Off mode, no policy check runs and no warnings are shown And policy changes propagate to enforcement (UI and API) within 60 seconds and are visible in the policy settings UI And a GET policy endpoint returns the effective mode for a brand-channel And unit/integration tests cover all mode combinations and precedence

API Enforcement and Error Contract

Given the API endpoints POST /apply-preset and POST /batches/{id}/apply-preset When a non-approved preset is requested under policyMode=Block Then the server returns HTTP 422 with code=OFF_BRAND_PRESET and a payload including: presetName, brandName, channelName, policyMode, suggestedPresetIds (0–3) And no changes are persisted to the target asset(s) And under Warn mode, the server returns 200 with warnings[] containing code=OFF_BRAND_PRESET and suggestions, while applying the preset And including a valid, unexpired override token (X-Override-Token) that matches {brandId, channelId, presetId} yields 200 and applies the preset And invalid/expired/mismatched tokens yield 403 with code=INVALID_OVERRIDE And P95 API latency for enforcement checks is <= 400 ms for single apply and <= 800 ms for batch per 100 items

UI Messaging and Discoverability of Compliant Presets

Given a user is blocked or warned for off-brand preset usage in the UI When the message is shown Then the modal/banner headline reads "Preset not approved for Brand-Channel" And the body includes reason, current preset, effective policyMode, and a link "View brand-approved presets" that opens a filtered list And suggested compliant presets (1–3) show name, thumbnail, and Apply buttons; selecting one applies immediately if allowed And the component meets accessibility: focus is trapped, Esc closes, screen-reader labels for controls, and all visible text is localizable And analytics events track impressions, suggestion clicks, and conversion to compliant apply

Audit Log and Reporting for Compliance Events

Given enforcement is enabled When any of the following occurs: Block, Warn, OverrideRequested, OverrideApproved, OverrideDenied, AppliedWithOverride Then an audit event is recorded with fields: eventType, userId, assetId|batchId, presetId, brandId, channelId, policyMode, reasonCode (if any), overrideTokenId (if any), timestamp (UTC), outcome And Admins can filter and export these events via UI and API over a selectable date range And data retention is 365 days with role-based access controls (only Admins view PII) And exported CSV reflects filters and includes a checksum/hash of rows for integrity verification

Real-Time Mismatch Detection

"As a catalog editor, I want real-time warnings when a photo’s preset doesn’t match its destination channel so that I can fix issues before publishing."

Description

Validation layer that detects preset-to-brand or channel mismatches during upload, editing, and export. Checks parameters like aspect ratio, background color, margins, watermarking, and color profile against the bound preset. Surfaces inline warnings and one-click fixes (reapply correct preset or adjust parameters), plus a batch summary view to resolve issues before publishing.

Acceptance Criteria

Inline Warning on Upload for Preset Mismatch

Given a project with a bound preset-to-brand and/or channel mapping When a user uploads images and analysis completes Then any image whose aspect ratio, background color, margin, watermarking, or color profile deviates from the bound preset is flagged with an inline warning badge on the thumbnail and a summary tooltip listing the offending parameters And the warning appears within 1 second per image at the 95th percentile for batches up to 500 images And each flagged image shows two CTAs: "Reapply Correct Preset" and "Adjust Parameters" And unflagged images display no warning and proceed normally

Auto-Assign Correct Preset by Supplier or Folder Tag

Given a folder or upload batch tagged with a supplier or brand identifier that has a configured preset binding When images are added to the batch Then the correct bound preset is auto-applied without user action and the action is indicated via a non-blocking toast and per-image icon And accuracy is 100% for all images with a valid mapping; images without a mapping are left unchanged and listed in a "No Mapping" filter And attempting to manually select an off-brand preset is blocked with an explanatory message

Real-Time Parameter Drift Detection During Editing

Given the editor is open on an image with a bound preset When the user modifies any controlled parameter (aspect ratio, background color, margin, watermarking, or color profile) so that it no longer matches the preset Then a real-time warning banner and inline control highlights appear within 200ms, identifying the specific parameters out of compliance And the "Revert to Preset" CTA becomes enabled; selecting it restores only the drifted parameters while preserving other edits And the warning clears immediately when parameters return to compliance

One-Click Fix Applies Bound Preset

Given an image is flagged for mismatch When the user clicks "Reapply Correct Preset" Then all out-of-compliance parameters are reset to the bound preset values in a single operation within 500ms, the image revalidates, and the warning state is cleared And non-conflicting user edits (e.g., exposure or retouch adjustments) remain intact And an undo step is added to history allowing full reversal in one action

Pre-Export Batch Mismatch Summary and Resolution

Given a user initiates export for a batch When any images in the batch are out of compliance with their bound preset/channel rules Then a pre-export modal shows counts by mismatch type, affected image thumbnails, and per-image checklists of failing parameters And the modal provides "Fix All" and "Fix Selected" actions that apply corrections and revalidate before allowing export And if organizational policy blocks off-brand exports, export is prevented for failing items with a clear reason and link to fix; otherwise user can proceed after acknowledging warnings

Channel-Specific Rules Enforcement on Export

Given a bound channel with explicit constraints (e.g., marketplace requires 1:1 aspect, pure white background #FFFFFF, sRGB, no watermark) When the user selects an export target that conflicts with the bound channel or when the image parameters violate channel constraints Then the system flags the conflict, auto-selects the correct channel preset if available, or blocks export until parameters comply And the validation explicitly checks and reports: aspect ratio tolerance ±0.01, background color deltaE < 2 to #FFFFFF, margins within preset %, watermarking disabled/enabled per rule, and ICC profile equals sRGB

Channel-Specific Preset Variants

"As an e-commerce marketer, I want channel-specific preset variants to be applied automatically so that each marketplace receives optimized, compliant images."

Description

Support for per-channel variations of a base brand preset (e.g., Amazon white background, Instagram square crop, Shopify padding). Automatically selects and renders the correct variant at export or publish time, with reprocessing when channel policies or presets change. Maintains asset versioning to track which variant was used and ensures consistent outputs across marketplaces.

Acceptance Criteria

Auto-Select Preset Variant per Export Channel

- Given a base brand preset has channel-specific variants configured, When an export or publish job targets a specific channel (e.g., Amazon, Instagram, Shopify), Then the system auto-selects the matching channel variant without user input. - And the job record for each asset stores brand_id, preset_id, variant_id, and channel. - And the output asset filename includes the channel and variant version in the pattern: <sku>_<channel>_v<presetVersion>.<ext>. - And 100% of assets in the job receive the correct channel variant; any asset without a mapping is halted with status "BLOCKED" and reason "MISSING_VARIANT".

Brand Binding Blocks Off-Brand Variant Usage

- Given workspace brand B is active, When a user attempts to apply a preset variant from brand C, Then the action is blocked with error code BRAND_BINDING_VIOLATION and cannot proceed to export/publish. - Given a variant is selected that does not match the target channel, When the user queues export, Then a warning is shown and a one-click "Switch to <channel> variant" option is provided; proceeding without switch is blocked if policy=Block, otherwise allowed with recorded warning if policy=Warn. - And all blocks/warnings are logged with user_id, asset_id, rule_id, timestamp, and decision (Blocked|Warned|Auto-switched).

Auto-Assign Variant via Supplier and Folder Tags

- Given supplier and/or folder tags are mapped to a brand preset and channel, When images are batch-uploaded into a tagged folder, Then the system auto-assigns the corresponding channel-specific variant and queues processing. - And the assigned variant is displayed in batch review; users with Brand Manager role may override before processing; overrides are captured in audit with old_variant_id and new_variant_id. - And if multiple rules match, the highest-priority rule is chosen and the decision path is shown; if no rules match, default to the base preset and set job warning NO_RULE_MATCH.

Auto-Reprocess on Policy or Preset Change with Versioning

- Given a channel policy or any channel-specific preset variant is edited and saved, When the change is published, Then previously exported assets tied to that variant are marked Outdated and added to a Reprocess queue. - And reprocessing creates new asset versions with incremented presetVersion (and variant settings hash), leaving prior versions intact and retrievable. - And enabled channel connectors receive updated assets after reprocessing; publish actions reference the new version id. - And a summary report lists counts of impacted, reprocessed, skipped, and failed assets with reasons.

Asset Version Metadata and Traceability

- Given any export or publish generates an output, When the asset is produced, Then the system persists an immutable version record with fields: assetVersionId, brand_id, preset_id, variant_id, presetVersion, channel, settings_hash, source_hash, and timestamp. - And the version history view can filter by channel and presetVersion, and displays the exact variant used. - And a Reproduce Output action re-runs processing pinned to the recorded presetVersion and settings_hash; the resulting file matches the stored version by byte-level checksum.

Fallback Behavior When Channel Variant Missing

- Given a base preset has no defined variant for the target channel, When a user exports or publishes to that channel, Then the system applies the base preset with channel-safe defaults and emits warning MISSING_CHANNEL_VARIANT. - And an org-level policy controls fallback behavior (Block | Allow with Warning); the configured policy is enforced consistently across batch jobs. - And when a new channel variant is later defined, users can bulk reprocess previously warned assets to replace fallback outputs; the new versions are linked to the original via priorVersionId.

Binding Audit & Compliance Reporting

"As a compliance analyst, I want audit logs and reports of bindings and overrides so that I can track adherence and identify training gaps."

Description

Comprehensive, immutable logs of preset bindings, assignments, blocks, and overrides, including user, timestamp, source metadata, and reason codes. Provides dashboards and exportable reports for compliance rate, off-brand attempts prevented, and rework avoided. Offers filters by brand, supplier, channel, and time window, plus webhooks/CSV exports for BI integration and retention controls.

Acceptance Criteria

Immutable Audit Log for Binding Events

Given a binding action (auto-assign, block, or override) occurs, When the event is processed, Then an audit entry is created within 5 seconds containing: event_id (UUID), event_type, outcome, preset_id/name, brand_id/name, channel_id/name, supplier_id/name, source_folder, tag_ids, image_id(s), rule_id, user_id/email or "system", timestamp (ISO 8601 UTC), reason_code (if block/override), request_id, and hash_chain value. Given an audit entry exists, When any actor attempts to modify it via API or UI, Then the system prevents mutation and logs a tamper_attempt event with actor and timestamp. Given audit entries are appended, When a daily integrity check runs, Then each entry’s hash_chain equals SHA-256(prev_hash + canonical_entry_json) and the check reports 0 mismatches. Given an event_id, When retrieved via API, Then the response returns the exact stored entry and a 200 status within 300 ms for the 95th percentile.

Dashboard Metrics: Compliance, Blocks, Rework Avoided

Given a selected time window and scope, When the dashboard loads, Then compliance_rate = compliant_events ÷ eligible_events rounded to 1 decimal and displayed with numerator/denominator. Given block events occurred in scope, When the dashboard loads, Then off_brand_attempts_prevented equals the count of block events in scope. Given minutes_per_rework is set to 5, When calculating rework_avoided, Then rework_avoided_minutes = off_brand_attempts_prevented × 5 and is displayed as HH:MM and (if cost_per_min configured) as currency. Given new events stream in, When 60 seconds elapse, Then dashboard aggregates reflect the new totals. Given filters return no data, When the dashboard loads, Then the UI shows zeros and an empty-state message without errors.

Filterable Reporting by Brand, Supplier, Channel, and Time

Given filters for brand, supplier, channel, and time window, When multiple values are selected per facet, Then results include events matching any selected value within each facet and all facets are combined with AND. Given a time zone is chosen, When the time window is applied, Then boundaries are computed in that time zone and displayed; default is UTC if none provided. Given a query returning ≤ 100,000 events, When results are requested, Then the first page loads within 3 seconds and the query supports deterministic sorting: timestamp desc, event_id as tiebreaker. Given paginated results, When navigating pages, Then the total count is accurate and page changes do not alter ordering for a fixed dataset.

Exports: CSV Download and Webhook Delivery for BI

Given a user requests CSV export for the current filters, When the export completes, Then the CSV is UTF-8 with a header row and columns: event_id, event_type, outcome, preset_id, preset_name, brand_id, brand_name, channel_id, channel_name, supplier_id, supplier_name, source_folder, tag_ids, image_ids, rule_id, user_id, user_email, timestamp_utc, reason_code, request_id, hash_chain. Given an export exceeds 100,000 rows, When requested, Then an asynchronous job is created and a downloadable, signed URL is provided that expires in 24 hours. Given fields contain commas, quotes, or newlines, When generating CSV, Then values are escaped according to RFC 4180. Given a webhook destination with shared secret is configured, When new audit events occur, Then a JSON batch is POSTed within 30 seconds signed with HMAC-SHA256 (header X-PixelLift-Signature) and includes an Idempotency-Key. Given a webhook delivery receives a non-2xx response, When retrying, Then the system retries up to 6 times with exponential backoff capped at 10 minutes and guarantees at-least-once delivery.

Override Logging with Reason Codes and Approvals

Given a user initiates a preset override, When submitting, Then a reason_code from the configured list is required and an optional note up to 500 characters is allowed. Given override requires approval, When the request is made, Then the approver must differ from the requester and the approver’s user_id is recorded in the audit log. Given an override is executed, When logging the event, Then the entry includes previous_preset_id/name, new_preset_id/name, override=true, and links to the originating rule_id. Given a user lacks override permission, When they attempt an override, Then the action is blocked and a block event is logged with reason_code=permission_denied and no state change occurs.

Retention Controls and Redaction Policy

Given an admin sets a workspace retention policy (e.g., 365 days), When a log entry exceeds the retention window and is not under legal hold, Then it is deleted or archived per policy and a retention_deletion summary event is recorded. Given PII fields (e.g., user_email) are configured for redaction after 90 days, When an entry passes the redaction threshold, Then those fields are irreversibly redacted while preserving non-PII fields and metric integrity. Given a legal hold is applied to a brand, When retention jobs run, Then entries under hold are excluded from deletion until the hold is lifted and the hold is auditable. Given a retention policy change, When saved, Then the change is logged with admin user_id, timestamp, and old/new values and applies prospectively to new deletions.

Mapping Admin Console

"As a workspace admin, I want an admin console to manage mappings and import rules in bulk so that onboarding new brands and suppliers is fast and error-free."

Description

An admin UI for managing brand-to-preset mappings and auto-assignment rules. Includes bulk import/export, in-line validation, role-based access control, preview of presets on sample images, and test-run capability before applying changes to full catalogs. Tracks change history with rollback, supports multi-brand workspaces, and provides guardrails to avoid breaking existing bindings.

Acceptance Criteria

Bulk Import with Inline Validation

- Given an Admin or Editor uploads a CSV/JSON using the provided template, the system validates required fields (brand_id, channel_id, preset_id, rule_scope, priority, status) before commit. - Row-level errors and warnings are displayed inline with line numbers; first 200 surfaced in UI and a full downloadable error report is generated. - Critical errors (missing required fields, invalid IDs, duplicate key brand+channel+scope, non-integer priority) block import; warnings (unused columns, deprecated fields) allow proceed with explicit confirmation. - Import is atomic: either all valid rows are applied or none if any critical error exists. - Idempotency: re-importing an identical file produces zero changes and records a no-op audit entry. - Performance: validation for 10,000 rows completes ≤ 15s; applying 10,000 valid rows completes ≤ 60s. - Audit: a single change-set is created with counts of created/updated/deleted mappings and a checksum of the source file. - Guardrail: attempts to overwrite active mappings used by in-flight jobs require Admin confirmation and are deferred if a safe window is scheduled.

Auto-Assignment Rule Engine Evaluation

- When an asset enters the pipeline with brand_id, channel, supplier_tag, and folder_tag, rules evaluate in descending priority; match order: supplier_tag > folder_tag > brand default; first match wins. - Deterministic outcome: given identical inputs and ruleset version, the same preset_id is assigned; tiebreaker is most recent update timestamp if priorities are equal. - Fallback: if no rule matches, processing is blocked with error "No preset mapped"; a notification is sent to brand owners and Admins. - Per-channel enforcement: a preset not bound to the asset's brand+channel is rejected with a mismatch error; asset is not processed. - Rule application logs rule_id, ruleset_version, and assigned preset_id with the asset's job record. - Rule changes affect only jobs queued after the save timestamp; in-flight jobs retain previous assignments. - Throughput: the engine evaluates ≥ 300 assets/second per workspace under nominal load with p95 decision latency ≤ 50 ms.

Role-Based Access Control for Mapping Admin Console

- Roles supported: Owner, Admin, Editor, Viewer; default new users are Viewer. - Owner/Admin: full CRUD on mappings, rules, imports, rollbacks, and can apply test-run results. - Editor: can create/edit mappings and run dry runs; cannot apply to production or perform rollbacks. - Viewer: read-only; may export reports; no create/update/delete actions. - All mutating endpoints enforce authorization and return 403 on insufficient permission; corresponding UI controls are disabled and tooltipped. - Every attempted and successful action is logged with actor_id, role, IP, timestamp, and outcome. - SSO group-to-role mapping is supported; manual overrides persist and are auditable. - Permission changes take effect immediately across sessions and are reflected in UI within 5 seconds.

Preset Preview on Sample Images

- Selecting a brand and preset allows previewing up to 5 sample images; previews render ≤ 2s per 1080p image (batch of 5 ≤ 10s, p95). - Preview shows before/after toggle and 1:1 zoom; no catalog changes are persisted. - The rendering pipeline version used is identical to production; the version is displayed in the UI. - Visual fidelity: color difference between preview and production output for the same input is ΔE ≤ 2. - Input color spaces supported: sRGB and Adobe RGB; others are rejected with an explanatory message. - Optional preview download as JPEG/WebP is available with max file size 10 MB per image; watermark "Preview" is applied. - Caching: repeating the same preset+image preview returns cached result with p95 ≤ 500 ms.

Dry Run of Rule Changes Before Catalog Apply

- Users select a ruleset and target scope (workspace/brand/channel/folder) and initiate a dry run; no changes are persisted. - The system evaluates ≥ 50,000 assets and produces an impact report: counts per rule, conflicts, blocked assets, and proposed preset assignments. - Report generation completes ≤ 3 minutes for 50,000 assets with progress feedback and cancel option. - Admins can promote the dry run to apply; a content hash of the evaluated set ensures the applied set matches the report; if the catalog has changed, promotion is blocked and a re-run is required. - No emails or processing jobs are triggered by dry runs; results are stored for 30 days and are auditable. - Applying from a dry run executes transactionally; success/failure and counts are recorded in a change-set.

Change History and Point-in-Time Rollback

- Every create/update/delete of mappings or rules generates a versioned change-set with before/after values, actor, timestamp, and rationale (optional text). - History view supports filtering by brand, channel, actor, and date range; export available as CSV/JSON. - Admins can rollback an individual change-set or restore to a specific timestamp; the system presents an impact summary before execution. - Rollback is atomic and requires a confirmation with a reason ≥ 15 characters. - Guardrails block rollbacks that would introduce duplicate/conflicting mappings; suggested resolutions are presented. - All rollback operations are logged and reversible (forward-apply the prior change-set). - Performance: rollback of change-sets ≤ 10,000 rows completes ≤ 60s.

Guardrails in Multi-Brand Workspaces

- Isolation: a preset from Brand A cannot be mapped to Brand B; cross-workspace access is blocked. - Uniqueness enforced: at most one active default preset per brand+channel; scoped rules (supplier/folder) cannot overlap at equal or higher priority without explicit override and justification. - Impact check on save shows affected catalogs/assets; if affected_count > 0, Admin confirmation is required; option to schedule apply window is provided. - Deletion is blocked if a mapping is referenced by active or scheduled jobs; UI lists blockers and links to cancel or reschedule. - Real-time validation returns field-level errors within 500 ms of input change. - Concurrency: optimistic locking prevents stale updates; saves with outdated versions are rejected with guidance to refresh. - Notifications are sent to brand owners and Admins on blocked saves, high-impact changes, and scheduled applies.

Audit Insights

Tamper-proof activity trails with usage analytics by brand, user, and preset version. Receive anomaly alerts (e.g., off-brand attempts), export compliance reports, and map usage to cost centers for clear accountability and simpler audits.

Requirements

Immutable Audit Log Ledger

"As a security and compliance officer, I want an immutable, tamper-evident audit log of all processing activities so that I can prove compliance and investigate incidents with confidence."

Description

Provide an append‑only, tamper‑evident audit ledger that records every significant action in PixelLift, including uploads, AI retouch operations, background removals, style‑preset applications (with preset/version IDs), exports, approvals, and administrative changes. Each entry must capture timestamp (NTP-synchronized), actor (user/service/API key), brand/workspace, cost center tag, asset IDs, operation parameters, model versions, originating IP/agent, and outcome status. Entries are hash‑chained and signed to detect alteration, stored on WORM-capable storage with configurable retention and legal holds. Include a verifiable proof endpoint to validate integrity of individual entries or ranges. Integrate via an event bus so all services emit standardized audit events with correlation IDs, ensuring end‑to‑end traceability across the processing pipeline.

Acceptance Criteria

Append‑Only Hash‑Chained Ledger Writes

Given a valid audit event, When it is appended, Then the entry includes previous_hash, entry_hash, and digital_signature with key_id, and the chain continuity is verifiable end-to-end. Given any attempt to update or delete an existing ledger entry via API or storage, When executed, Then the operation is rejected with 403 and a tamper_attempt audit event is recorded. Given the ledger data at rest, When any bit in a past entry is modified, Then the next verification detects chain break and reports the earliest affected entry_id. Given signing key rotation occurs, When new entries are appended, Then signatures verify with the new key_id and previously signed entries continue to verify with their original key_id.

Complete Field Capture for Significant Actions

Given actions upload, AI_retouch, background_removal, style_preset_apply, export, approval, and admin_change, When performed, Then an audit entry is recorded for each with fields: timestamp_utc, actor (user/service/api_key), brand_workspace, cost_center_tag, asset_ids, operation_type, operation_parameters, model_version, originating_ip, user_agent, outcome_status, correlation_id. Given a style_preset_apply action, When recorded, Then preset_id and preset_version are present and non-empty. Given an action fails, When recorded, Then outcome_status includes failure_code and error_message. Given timestamps are captured, When validated against NTP, Then ntp_offset_ms is present and within ±500 ms.

WORM Storage, Retention, and Legal Hold

Given WORM-capable storage is configured, When ledger objects are written, Then they are immutable for the active retention period. Given a brand/workspace retention policy between 1 and 10 years is configured by an authorized admin, When saved, Then new entries inherit the policy and the change is itself audited. Given a legal hold is placed on a brand/workspace or entry range, When retention expiry is reached, Then deletion is prevented until the hold is lifted and all actions are audited. Given an attempt to delete or rewrite a WORM-protected object, When executed, Then the operation fails with 403 and a tamper_attempt audit event is recorded.

Integrity Proof Endpoint (Entry and Range)

Given an entry_id, When GET /audit/proof?entry_id={id} is called with valid auth, Then 200 is returned with entry_hash, previous_hash, signature, key_id, and verification_result=true. Given start and end identifiers, When GET /audit/proof?start={s}&end={e} is called, Then a contiguous-chain proof for the range is returned within 2 seconds for ranges ≤ 10,000 entries and verifies client-side. Given a nonexistent entry_id or range, When proof is requested, Then 404 is returned with error_code=ENTRY_NOT_FOUND. Given a chain break within the requested range, When proof is requested, Then verification_result=false and first_corrupted_entry_id is included.

Event Bus Standardization and Correlation

Given any service emits audit events, When publishing to the event bus, Then messages conform to schema_version=X with required fields and pass schema registry validation. Given a user action triggers downstream processing, When events are emitted across services, Then a single correlation_id is propagated and present in all related ledger entries. Given the event bus is unavailable, When an event is to be emitted, Then the service retries with exponential backoff up to 5 minutes, persists to an outbox, and duplicates are handled idempotently. Given a publish fails schema validation, When attempted, Then it is rejected, captured in a DLQ with reason, and the failure is audited.

Administrative Key and Role Controls

Given RBAC policies are enforced, When a user without Audit.Admin role attempts to change retention, legal holds, signing keys, or proof settings, Then the request is denied with 403 and is audited. Given a key rotation is initiated by Audit.Admin, When completed, Then a new key pair with incremented key_id is active for signing, prior keys remain for verification-only, and rotation metadata is recorded. Given a brand-scoped user requests audit entries, When authorized, Then results are limited to the user's brand/workspace scope and access is audited.

Time Synchronization and Clock Drift Monitoring

Given system nodes synchronize time via NTP, When drift exceeds ±500 ms on any node, Then new audit writes from that node are blocked, an alert is raised, and the event is audited. Given entries are timestamped, When saved, Then each includes server_time_utc and a monotonic_sequence to guarantee ordering for same-millisecond events. Given NTP services are restored, When drift returns within threshold, Then audit writes resume and recovery is audited.

Granular Audit Filters & Search

"As a compliance analyst, I want to filter and search audit records by brand, user, preset version, and time range so that I can quickly find relevant evidence during reviews."

Description

Deliver a queryable audit interface (UI + API) that supports filtering by brand, user, role, time range, action type, asset ID, preset name/version, outcome status, IP/geolocation, and correlation ID. Provide full‑text search on metadata, sortable columns, pagination, saved searches, and export of result sets. Enforce role‑based access controls so users only see records within their permitted scopes. Optimize for large datasets with indexed queries and consider time‑partitioned storage. Include quick pivots from aggregated views to raw audit entries for fast investigations.

Acceptance Criteria

Multi-Dimensional Filtering (UI & API)

Given an organization with ≥10M audit records spanning multiple brands, users, roles, action types, asset IDs, preset names/versions, outcome statuses, IPs/geolocations, correlation IDs, and a time range ≥90 days When a user applies any single supported filter (brand, user, role, time range, action type, asset ID, preset name/version, outcome status, IP/geolocation, correlation ID) in the UI or via API Then only matching records are returned and the applied filter is shown as active And p95 response time for single-indexed filter queries is ≤2s for result sets ≤10k rows When multiple different filter types are applied concurrently Then filters combine with AND semantics across types and OR semantics within multi-select values of the same type And the total count equals the filtered set size (±0.1%) And time range filters are inclusive of start and exclusive of end in UTC And IP filter accepts exact IP and CIDR; geolocation filter accepts country/region/city codes And correlation ID filter is exact and case-insensitive And UI and API return identical results for equivalent queries

Full-Text Search Across Metadata

Given audit records containing metadata fields (e.g., file name, preset name, notes, error messages) When the user submits a full-text query string in the UI or API parameter q Then results include records where any metadata field contains the query terms (case-insensitive, tokenized on alphanumerics) And combining full-text search with filters returns the intersection of both And p95 response time for full-text queries over ≤10k returned rows is ≤3s And results are ranked by relevance then by timestamp desc when sort is not explicitly set And an empty query or only stop-words returns no full-text matches and does not alter applied filters

Sortable Columns & Pagination (UI & API)

Given the audit list view with columns: timestamp, brand, user, role, action type, asset ID, preset name, preset version, outcome status, IP, geolocation, correlation ID When the user clicks a column header (UI) or sets sort parameters (API) Then the list sorts ascending/descending correctly and stably, defaulting to timestamp desc on initial load And changing sort resets pagination to the first page And pagination supports page sizes 25/50/100 (default 50) in UI, and API supports cursor-based pagination with next/prev tokens and a limit up to 500 And the same query + sort + cursor deterministically returns the same page And p95 latency to fetch any page ≤2s for pages up to 500 rows And the total count reflects the filtered set across all pages

Saved Searches: Create, Run, Manage

Given a user with permission to save searches When the user saves the current combination of filters, full-text query, sort, and columns as a named Saved Search Then the Saved Search is persisted with a unique name per user (1–120 chars) and is listed under the user’s Saved Searches When the user runs a Saved Search Then the UI applies the exact saved parameters and returns identical results to the original at the same data snapshot And p95 load time to apply a Saved Search is ≤2s for queries returning ≤10k rows When the user renames, updates, or deletes a Saved Search Then the changes are persisted and reflected in the list; deleted searches no longer appear And Saved Searches are private to the owner user and not visible to other users

Export Filtered Results (CSV/JSON, Sync/Async)

Given a filtered/sorted result set in the audit interface When the user exports results to CSV or JSON via UI or API Then only records within the current query scope are exported and RBAC is enforced And for result sets ≤50k rows, the export downloads synchronously within 60s; for larger sets up to 5M rows, an asynchronous job is created and a downloadable link is provided upon completion And exported data preserves applied sort order and includes the selected columns; timestamps are ISO 8601 UTC And the export file name includes org/brand (where applicable), query date range, and a timestamp And the API exposes endpoints to create export jobs and poll job status And the number of exported rows equals the query’s total count at export time

Role-Based Access Scope Enforcement

Given users with different scopes (e.g., Org Admin with all brands in org; Brand User restricted to Brand A; Standard User restricted to own actions) When a user queries the audit UI or API Then only records within that user’s permitted brands/resources are returned And out-of-scope filter values are disabled in UI and rejected by API with 403 and an explanatory error And tenant isolation is enforced so users cannot access records from other organizations under any circumstances And API tokens inherit the issuing user’s scopes and produce identical visibility And all access denials are themselves auditable with user, reason, and attempted scope

Pivot from Aggregated Views to Raw Audit Entries

Given an aggregated view (e.g., counts by brand, action type, or outcome over a selected time window) When the user clicks an aggregate bucket (bar, slice, or table cell) Then the app opens the raw audit list view with corresponding filters and the same time window pre-applied And the raw list total count matches the aggregate bucket count at query time (±0.1%) And the pivoted state is shareable via a deep link URL capturing filters, time range, and sort And navigating back returns to the aggregate view with prior state preserved And p95 latency to open the pivoted raw list is ≤2s for ≤10k-row result sets

Usage Analytics by Brand/User/Preset Version

"As a brand operations manager, I want usage analytics by brand, user, and preset version so that I can measure adoption, efficiency gains, and enforce brand standards."

Description

Aggregate audit events into analytics dashboards that show volumes processed, success/failure rates, average processing time, estimated time saved, preset adoption and effectiveness, and anomaly counts. Provide drill‑down from charts to underlying audit entries, with breakdowns by brand, cost center, user, preset version, and time window. Ensure multi‑tenant data isolation, near‑real‑time updates via streaming aggregations, and exportable widgets. Surface KPIs relevant to e‑commerce outcomes (e.g., conversion lift correlation where available) to demonstrate value and drive preset governance.

Acceptance Criteria

Real-Time Brand-Level Aggregates

Given audit events for tenant T and brand B are ingested via the streaming pipeline When new events arrive Then dashboard metrics for brand B (processed volume, success rate, failure rate, average processing time, estimated time saved) update within 60 seconds at p95 and 120 seconds at p99 And estimated time saved is computed as sum(max(0, baseline_edit_time_per_asset - processing_time_per_asset)) with a brand-configurable baseline (default 180 seconds), and the baseline value is displayed in the widget info And for any 1-hour window, each metric matches a point-in-time recomputation from the audit store within the greater of 0.5% absolute difference or ±5 events

Drill-Down From Charts to Audit Trail

Given a user views an analytics chart with filters for brand(s), cost center(s), user(s), preset version(s), and a time window When the user clicks a chart element (bar, slice, point, or legend bucket) Then a drill-down table opens showing underlying audit entries constrained by the same filters and time window And the table includes columns: timestamp, brand, cost center, user, preset version, status, processing time, assetId, error code (if any) And the drill-down supports server-side pagination to at least 50,000 rows with sortable columns; p95 response time <= 2 seconds for page sizes up to 100 rows And a deep link "View in Audit Trail" preserves the drill-down filters and time window; a back action returns to the original dashboard and scroll position

Multi-Tenant Isolation and Role-Based Access

Given a user authenticated for tenant A requests analytics for tenant B Then the request is denied with HTTP 403 and no cross-tenant identifiers or counts are leaked in error bodies or timing side channels beyond a constant-time response window (±100 ms) And all analytics and drill-down queries require and verify tenantId from the access token and enforce brand/cost-center scopes from the user role (e.g., AnalyticsViewer) so that only authorized brands/cost centers are visible And a support break-glass role requires a justification string and produces an immutable audit event; access is time-bound (default 1 hour) and is visible in the tenant's audit trail And automated integration tests with two synthetic tenants confirm zero cross-join leakage and zero data visibility across tenants

Advanced Breakdown and Filtering

Given filters for brand(s), cost center(s), user(s), preset version(s), and time window (Last 15m, 1h, 24h, 7d, 30d, Custom) When any combination of these filters is applied Then all widgets and tables reflect the filters consistently within 2 seconds at p95 for up to 1,000,000 events in range And breakdown mode renders grouped/stacked charts for the selected dimension and totals equal the sum of buckets within the greater of 0.1% or ±5 events And empty-result states render a clear "No data for selected filters" message without errors; clearing filters restores prior state And the current filter state is encoded in a shareable URL and is restored when the URL is revisited

Anomaly Detection and Counts

Given anomaly rules are enabled (off-brand attempts, failure-rate spikes, processing-time outliers, abnormal preset adoption changes) When an anomaly is detected in the last 1-hour window Then the anomaly count widgets update within 2 minutes at p95 and 5 minutes at p99 of detection And each anomaly entry includes rule id, severity, brand, user, preset version, count, first_seen, last_seen, and a link to filtered drill-down And on a labeled validation dataset, the false-positive rate is <= 5% and true-positive rate is >= 80% And disabling a rule removes it from counts and suppresses new detections within 60 seconds

Exportable Analytics Widgets and Reports

Given a user selects Export on any analytics widget When export is requested Then the system provides PNG (visual), CSV (aggregated rows), and JSON (widget config and query) that respect current filters, breakdowns, and user scopes And downloads begin within 5 seconds at p95; CSV exports up to 1,000,000 rows complete within 2 minutes or stream progressively without errors; column headers are consistent and UTF-8 encoded And an embeddable signed URL (iframe) is generated with tenant/brand scoping and a configurable TTL (default 7 days); access after TTL expiration is denied And exported artifacts include metadata (generated_at UTC, tenantId, brand(s), time range, filters) and a SHA-256 checksum for integrity verification

KPI Correlation: Preset Adoption vs Conversion Lift

Given a brand has connected conversion/order data with at least 30 days and 1,000 sessions of coverage When computing correlation between preset adoption rate and conversion lift over a selectable time granularity (day/week) Then the dashboard displays Pearson r, 95% confidence interval, and p-value; results marked "significant" when p < 0.05 And where data coverage is insufficient, the widget shows an "Insufficient data" state with required minimums and does not show a misleading value And the correlation methodology and data sources are linked; last computed timestamp is shown; computations refresh daily at 02:00 UTC and backfill within 24 hours

Anomaly Detection & Off‑Brand Alerts

"As a brand security admin, I want real-time alerts on off-brand or anomalous activity so that I can intervene before noncompliant images reach customers."

Description

Implement policy‑driven anomaly detection that flags off‑brand or risky activity, such as use of unapproved presets, manual overrides beyond thresholds, unusual processing spikes, access from atypical locations/IPs, or after‑hours usage. Allow per‑brand rules and baselines with severity levels, suppression windows, and alert routing to email, Slack, and webhooks. Each alert must link to supporting audit entries and include enough context for triage. Provide acknowledge/snooze/resolve workflows and capture analyst feedback to refine detection over time. Ensure low latency from event to notification to block noncompliant outputs before publication where configured.

Acceptance Criteria

Off‑Brand Preset Usage Blocks Publication

Given Brand A has an approved preset list and blocking enabled for off-brand usage When a user processes an image with a preset not on Brand A’s approved list Then the output is blocked from publication, a High severity alert is generated, and alerts are routed to Brand A’s configured email, Slack, and webhook channels And the first alert delivery occurs within 10 seconds at p95 (30 seconds p99) from the event time And the alert and block are recorded with a correlation ID and linked audit trail entries

Manual Override Threshold Breach Alert

Given Brand B has policy thresholds configured for manual adjustments (e.g., exposure, saturation, crop) When a user’s manual override exceeds any configured threshold for Brand B during processing Then a Medium or High severity alert (per rule config) is generated and routed to Brand B’s channels And the processed output is blocked if the rule’s action is set to Block, otherwise allowed with alert-only And the alert includes the parameter, attempted value, allowed threshold, user ID, asset ID, timestamp, and rule ID

Processing Spike Anomaly per Brand Baseline

Given Brand C has a baseline defined as the 7-day moving median per weekday-hour for jobs/hour with a spike threshold of 3x When processing volume for Brand C in a given hour exceeds 3x the baseline Then a Medium severity anomaly alert is generated and delivered to Brand C’s routing And duplicate alerts for the same spike are suppressed for the configured suppression window (e.g., 60 minutes) And the alert includes baseline value, observed value, multiplier, timeframe, and initiating users (if identifiable)

Atypical Location/IP and After‑Hours Access Alerts

Given Brand D has allowed geographies/IP ranges and business hours configured When a login or processing action occurs from a new country or ASN not on the allowlist, or outside business hours by more than 30 minutes Then a High (geo/IP) or Medium (after-hours) severity alert is generated and routed to email, Slack, and webhook And the first alert delivery occurs within 10 seconds at p95 (30 seconds p99) from the event time And the alert includes user ID, IP, geo lookup, ASN, device fingerprint (if available), local time, rule ID, and recommended actions

Alert Payload Completeness and Audit Linkage

Given an alert is generated for any rule When the alert is viewed in the console or received via any channel Then it contains: brandId, userId, assetId(s), ruleId, rule name, severity, event timestamp (UTC), processing node, presetId/version (if applicable), action taken (Block/Allow), correlationId, and links to supporting audit entries And following any audit link displays the corresponding immutable audit records with matching correlationId and hashes

Acknowledge/Snooze/Resolve Workflow with Suppression

Given an active alert is visible in the console When an analyst acknowledges the alert Then the alert status changes to Acknowledged with user, timestamp, and note captured When the analyst snoozes the alert for 60 minutes Then no duplicate alerts for the same rule-entity (brand+rule+asset or brand+rule+user, as applicable) are emitted during the snooze window unless severity escalates When the analyst resolves the alert with a disposition (True Positive, False Positive, Benign) and optional tags/notes Then the resolution, disposition, tags, and notes are persisted and visible in audit and via API

Per‑Brand Rule Configuration and Routing Isolation

Given Brands E and F have separate rule sets, severities, suppression windows, and channel routings configured When an off-brand event occurs in Brand E Then only Brand E’s rules evaluate and only Brand E’s channels receive the alert per its severity and suppression settings And no alerts are emitted to Brand F’s channels, and Brand F’s rules/baselines remain unaffected And updating Brand E’s rule (e.g., severity change) does not modify Brand F’s rules or baselines

Compliance Report Export (CSV/PDF/API)

"As an auditor, I want to export signed compliance reports with detailed activity and summaries so that I can satisfy audit requests efficiently."

Description

Offer one‑click and scheduled export of compliance reports over a selected scope and period, delivering digitally signed PDFs and CSV/JSON datasets via download, email, or S3. Reports include executive summaries, KPI snapshots, detailed activity line items, preset versions used, approval records, anomalies with dispositions, and cryptographic proofs (hash‑chain anchors and signatures) for evidentiary integrity. Provide time zone normalization, localization, and versioned report templates mapped to common frameworks (e.g., SOC 2, ISO 27001 evidence categories). Expose an API for programmatic retrieval and integration with GRC systems.

Acceptance Criteria

One-Click On-Demand Compliance Report Export

Given a user with "Reports.Export" permission selects a scope (brands/users/presets) and a date range and clicks "Export", When processing completes, Then a digitally signed PDF and CSV and JSON dataset are produced and available via in-app download within 2 minutes for workloads ≤ 10,000 activity records. And Then, if an email recipient is specified, the same artifacts are delivered by email with expiring signed download links valid for 7 days. And Then, if an S3 destination is configured, the artifacts are uploaded to the configured bucket/path with server-side encryption enabled (SSE-S3 or SSE-KMS) and private ACL. And Then each artifact name follows compliance_<scope>_<periodStart>-<periodEnd>_<templateVersion>_<timestampZ>.<ext> and includes a stable reportId in metadata. And Then the PDF includes sections: Executive Summary, KPI Snapshot, Detailed Activity Line Items, Preset Versions Used, Approval Records, Anomalies with Dispositions, and Cryptographic Proofs; CSV/JSON contain machine-readable equivalents with a data dictionary and templateVersion.

Scheduled Recurring Report Delivery

Given a schedule (daily/weekly/monthly) is created with a specific time zone and delivery channels (email and/or S3), When the schedule triggers, Then the report for the prior period aligned to that time zone is generated and delivered within 15 minutes of the scheduled time. And Then runs are idempotent: reruns for the same schedule+period overwrite S3 objects atomically and suppress duplicate emails (max one per period per recipient). And Then failures notify owners and retry up to 3 times with exponential backoff; after final failure, the run is marked failed with an error code and correlationId. And Then a backfill option allows generating historical reports from a chosen start date with no missing periods. And Then schedule creation, updates, and executions are audit logged with who/when and parameters.

Cryptographic Integrity and Tamper-Proofing

Given a report is generated, Then the PDF is digitally signed (PAdES-B) with an organization X.509 certificate and validates as trusted in Adobe Acrobat and via command-line verification. And Then CSV and JSON artifacts are accompanied by a manifest.json containing SHA-256 hashes of each file, a Merkle root, chainHeight, previousRoot, anchorTimestamp, and a detached signature. And Then recomputing file hashes matches manifest values, and the manifest signature validates against the published public certificate. And Then altering any artifact or manifest causes verification to fail, producing a distinct integrity error code.

API Retrieval for GRC Integration

Given a service authenticates via OAuth 2.0 client credentials with scope reports:read, When it POSTs to /api/v1/reports with parameters (scope, periodStart, periodEnd, templateVersion, formats, delivery), Then it receives HTTP 202 with jobId and correlationId. And Then GET /api/v1/reports/{jobId} returns status (queued|running|failed|complete), progress percent, and on completion, signed URLs for PDF/CSV/JSON, metadata (reportId, templateVersion, itemCount, timeZone), and expiresAt. And Then GET /api/v1/reports supports listing with filters (scope, createdAt range, templateVersion) and pagination (limit, cursor) sorted by createdAt desc. And Then API enforces rate limits (429 with Retry-After) and returns structured errors with machine-readable codes and correlationId; all timestamps are ISO 8601 with offset.

Framework-Mapped Template Versions

Given a user selects a report template version mapped to SOC 2 and ISO 27001 evidence categories, When the report is generated, Then it includes a control mapping section referencing the chosen frameworks and a templateVersion identifier. And Then changing the default template does not alter previously generated reports; prior reports render with their original template version. And Then deprecated templates are flagged at selection with a warning and suggested replacement, and selection is still allowed for backward compatibility. And Then all template selections and changes are audit logged with actor, timestamp, and reason.

Localization and Time Zone Normalization

Given a user sets locale and time zone (e.g., fr-FR and Europe/Paris), When a report is generated, Then the PDF renders headings and date/number formats per locale and normalizes all timestamps to the selected time zone with explicit offset (e.g., 2025-09-21 14:30:00 GMT+02:00). And Then CSV/JSON timestamps are ISO 8601 with offset and include top-level fields timeZone and locale; numeric fields use dot decimal in machine-readable datasets regardless of locale. And Then KPI rollups and period boundaries are computed using the selected time zone and match PDF narratives and dataset aggregates.

Cost Center and Usage Analytics Breakdown

Given cost centers are configured and entities (brands/users/preset versions) are mapped, When a report is generated, Then it includes breakdowns by brand, user, preset version, and cost center with totals for photos processed, processing minutes, storage egress, anomalies, approvals, and attributable cost. And Then overall totals reconcile with the sum of group totals within 0.1% tolerance and differences are explained (e.g., rounding) in the report notes. And Then the report includes an appendix listing entity-to-cost-center assignments; unmapped entities are flagged and grouped under "Unmapped" with counts and costs. And Then all grouping keys include stable IDs in CSV/JSON and human-readable names in PDF.

Cost Center Mapping & Chargeback

"As a finance ops manager, I want to map usage to cost centers and generate chargeback reports so that I can allocate costs accurately across teams."

Description

Enable administrators to define cost center codes and map them to brands, teams, users, or API keys, with rule‑based overrides by preset type or project tag. Attribute usage from the audit stream to cost centers and generate periodical chargeback reports with unit counts, rates, taxes, and totals. Provide simulations to preview the financial impact of mapping changes and support retroactive reclassification with a controlled workflow. Integrate exports to billing/ERP systems and enforce permissions so only finance roles can modify mappings and rates.

Acceptance Criteria

Cost Center Mapping by Entity with Rule-Based Overrides

Given a FinanceAdmin defines cost center codes with names, status, currency, and effective-dated unit and tax rates And creates mappings for brand, team, user, and API key entities And defines override rules that match on preset type and/or project tags (exact and glob patterns) And sets a global default cost center for unmatched usage When a usage event arrives with attributes {brand, team, user, apiKey, presetType, projectTags} Then the system resolves the event to exactly one cost center using this precedence: override rules (higher priority > higher specificity > most recent) > user > apiKey > team > brand > global default And the resolved mapping includes costCenterCode, mappingVersion, matchedRuleId (if any), and evaluation timestamp And conflicting or overlapping mappings are prevented at save time with validation errors And p95 rule resolution latency is <= 100 ms per event at a throughput of 5,000 events/minute

Mapping Change Simulation & Financial Impact Preview

Given a FinanceAdmin edits mappings, rates, or taxes in draft mode When they run a simulation for a selected date range and scope (brand/team/user/preset type/tag) Then the system computes projected deltas per cost center: unit counts, subtotals, taxes, and totals, comparing draft vs current production And presents a side-by-side comparison with net impact and top-affected entities And the simulation excludes events already reclassified in an approved retroactive workflow unless explicitly included And for up to 1,000,000 events the simulation completes within 10 minutes, with progress updates and cancel support And no production data or reports are modified until the draft is approved and published

Audit Stream Usage Attribution

Given audit events contain tenant, brand, team, user, apiKey, presetType, projectTags, unitType, unitQuantity, and timestamp When events are ingested Then attribution to a cost center is applied idempotently based on the active mapping at event timestamp (effective-dated) And the attribution record stores {eventId, costCenterCode, unitType, unitQuantity, rate, taxRate, mappingVersion, matchedRuleId} And p95 end-to-end attribution delay from ingestion to availability for reporting is <= 60 seconds And malformed events are quarantined with alerting, retriable after fix, and excluded from reports until attributed And tenant boundaries are enforced so mappings and attributions are isolated per tenant

Scheduled Chargeback Report Generation & Contents

Given FinanceAdmin schedules reports (weekly or monthly) with time zone and currency When a report is generated for a period Then it includes per cost center and per unit type: unit counts, rate, subtotal, tax rate, tax amount, and total, plus period start/end, tenant, mappingVersionHash, and number of unattributed events And provides breakdowns by brand and preset type, and an optional detail file with line items limited by configured retention And totals reconcile: sum(subtotals) + sum(taxes) = grand total, with rounding to 2 decimals using bankers rounding And rates and taxes used reflect the effective configuration at event time (not report time) And the report is available as CSV and JSON, downloadable in-app and deliverable via configured exports

Finance-Only Permissions and Change Auditability

Given role-based access control is configured When a non-Finance user attempts to create/update/delete cost centers, mappings, rates, or taxes Then the action is blocked with 403 and no changes persist And when a FinanceAdmin performs such changes, MFA (if enabled) is required and changes are versioned with before/after, user, timestamp, and reason And every change produces a tamper-evident audit log entry linked to related reports and exports And read-only viewers can access reports but cannot view rates if rate visibility is disabled by policy

ERP/Billing Export Delivery and Reliability

Given FinanceAdmin configures export destinations: SFTP (SSH key), HTTPS webhook (OAuth2), or email When a report is finalized Then the system exports summary and detail files with deterministic filenames {tenant}_{period}_{version}.{csv|json} And includes an idempotency key and SHA-256 checksum; deliveries use at-least-once retries with exponential backoff for up to 24 hours And success is recorded only upon 2xx webhook response, verified SFTP write, or accepted email status; failures trigger alerts with retry status And exported payloads conform to the published schema with required columns and field types

Retroactive Reclassification Approval Workflow

Given a FinanceAdmin proposes a reclassification for a date range and filters (brand/team/user/apiKey/preset type/tag) from cost center A to B with a justification When the request is submitted Then the system runs a pre-apply simulation showing deltas and impacted reports And requires a second approver with Finance role to approve before changes apply And upon approval, affected attributions and reports are recalculated, prior report versions are retained and marked superseded, and corrected exports are sent with a correction flag And the workflow supports rollback to the prior state, producing a new version and corresponding exports And all steps are audit-logged and immutable

Preset Version Lineage & Change Diff

"As a brand owner, I want visibility into preset version history and differences so that I can control changes and trace outcomes for accountability."

Description

Track full lineage of style presets, including who changed what and when, approval status, and version notes. Provide visual and textual diffs of preset parameters (e.g., background style, crop rules, retouch intensities) and link each processed image in the audit ledger to the exact preset version applied. Support allow/deny lists of preset versions per brand, rollback to prior versions, and optional reprocessing of affected assets. Expose this lineage in analytics and exports to strengthen brand governance and explain outcome differences over time.

Acceptance Criteria

Immutable Preset Version Lineage Visible per Brand

Given a brand preset exists and a user saves changes, When the changes are committed, Then a new preset versionId is created with parentVersionId, editorUserId, ISO-8601 UTC timestamp, changeSummary, approvalStatus, and versionNotes recorded in the audit ledger Given any existing preset version, When a user attempts to edit it directly, Then the system prevents modification and returns an error indicating versions are immutable and a new version must be created Given a preset with 200+ versions, When viewing the lineage timeline, Then versions render in chronological order with parent-child links, and the view loads in under 2 seconds for up to 500 versions Given the audit ledger, When a ledger entry is programmatically altered outside the application, Then tamper detection marks the entry as invalid and the UI surfaces a tamper-evident warning

Visual and Textual Diff Between Any Two Preset Versions

Given two versions of the same preset are selected, When requesting a diff, Then changed parameters (e.g., background.style, crop.rules, retouch.intensity) are listed with exact old and new values Given two versions are selected, When displaying the diff, Then a side-by-side visual preview renders using the product sample image, and a textual JSON-style diff shows parameter paths with old→new values Given parameters that have not changed, When rendering the diff, Then they are excluded from the changed list and can be optionally toggled on via a "show unchanged" control Given numeric parameters changed within tolerance (e.g., float rounding), When computing the diff, Then the result suppresses false positives via stable rounding and order-insensitive comparisons Given the diff view, When the user clicks Export, Then a downloadable artifact (PDF for visuals and JSON for text) is generated containing versionIds, timestamps, editors, and the full change list

Audit Ledger Links Each Processed Image to Exact Preset Version

Given a batch is processed with preset version V, When inspecting any resulting image’s audit entry, Then the entry includes presetId and presetVersionId=V with a link to the version details Given a preset is updated to a new version during an ongoing batch, When later inspecting images, Then images completed before the update reference the previous version and images completed after reference the new version Given an export of processed assets is requested, When the CSV is downloaded, Then each row includes presetId, presetVersionId, jobId, brandId, and processedAt timestamp Given an image was reprocessed, When viewing its history, Then all prior presetVersionIds are shown in chronological order with who initiated each processing run

Enforce Brand Allow/Deny Lists for Preset Versions

Given a brand has an allow list of preset versionIds, When a user attempts to process with a version not on the allow list, Then the job is blocked and the API responds 403 BRAND_VERSION_NOT_ALLOWED with the offending versionId Given a brand has a deny list entry for a preset versionId, When a user attempts to process with that version, Then the job is blocked and an anomaly event is logged and alert is sent to brand admins Given an admin updates allow/deny lists, When the change is saved, Then the change is recorded in the audit ledger with editorUserId, timestamp, and rationale and takes effect within 10 seconds Given the UI lists available versions for a brand, When rendering the selector, Then only allowed and non-denied versions are selectable, and denied versions appear disabled with a tooltip reason

One-Click Rollback to Prior Preset Version with Optional Reprocessing

Given a preset has multiple versions, When an admin selects a prior version Vprev and confirms rollback, Then Vprev becomes the active version for the brand and the action is recorded with actor, timestamp, and notes Given rollback is performed with "Reprocess affected assets" checked, When the job runs, Then assets processed since a specified date or since version Vbad are reprocessed using Vprev and linked to the new processing run Given the reprocessing job completes, When viewing the job summary, Then success/failure counts, duration, and sample error messages are shown and each affected image’s audit entry is updated with the new presetVersionId Given a rollback is executed, When inspecting the lineage, Then no historical versions are deleted and the lineage shows a rollback event node linking from the current to Vprev

Lineage and Version Usage Exposed in Analytics and Exports

Given the analytics dashboard, When filtering by presetId and presetVersionId, Then usage metrics (images processed, success rate, average processing time, conversion lift if available) update accordingly Given a multi-brand account with cost centers, When exporting usage analytics, Then the CSV includes brandId, costCenter, presetId, presetVersionId, userId, jobId, processedAt, and counts per day Given a large export request of up to 100k rows, When the export is initiated, Then the file is delivered within 60 seconds or the system returns an asynchronous download link within 10 seconds and emails when ready Given a time range is selected, When viewing the trend chart, Then version changes are annotated on the timeline with tooltips linking to diffs and approver notes

Approval Workflow and Gating for Preset Versions

Given a new preset version is created, When saved, Then its approvalStatus defaults to Draft and cannot be used for production processing by non-admins Given a user with approver role, When they set approvalStatus to Approved and add notes, Then the change is recorded with approverUserId, timestamp, and notes and the version becomes eligible for production Given a non-approver attempts to approve or use a Draft/Pending version for production, When they submit, Then the system blocks the action with 403 VERSION_NOT_APPROVED and logs an anomaly event Given a version is Rejected or Deprecated, When a user attempts to select it, Then the UI disables selection and the API denies processing with a clear error referencing the approvalStatus

Smart Sampler

Automatically selects five representative images from your recent uploads—covering lighting, backgrounds, product types, and edge cases—so your brand preset is trained on the real variety you ship. Skip guesswork and get a sturdier, more reliable style in minutes.

Requirements

Diversity Sampler Engine

"As a boutique owner, I want PixelLift to automatically pick a diverse set of five photos from my latest uploads so that my brand preset learns from the real variety in my catalog without me handpicking examples."

Description

Implements the core selection algorithm that automatically chooses five representative images from a user’s recent uploads. Uses computer vision embeddings and clustering to capture variation across lighting conditions, background types, product categories, materials, and compositions. Applies quality heuristics (sharpness, exposure, noise) and tie-breakers to avoid near-duplicates and ensure coverage of distinct visual modes. Integrates with PixelLift’s asset store and indexing pipeline, outputs a ranked set with reason codes (e.g., “low-key lighting,” “busy background,” “reflective surface”) for transparency. Provides confidence scores and fallbacks when insufficient diversity is detected, and exposes a service API consumed by preset training.

Acceptance Criteria

Five-Image Selection from Configured Recent Uploads Window

Given a user has at least 5 eligible recent uploads within the configured recent-uploads window and assets are indexed and visible When the Diversity Sampler Engine is invoked for that user Then it returns exactly 5 unique image_ids ordered by representativeness_score descending And all returned images originate from the configured recent-uploads window And the selection is deterministic for identical input set and configuration (same 5 ids and order)

Diversity Coverage Across Visual Modes

Given an eligible pool of >= 5 images with computed embeddings and attribute tags When the engine samples the representative set Then the 5 selections belong to at least 4 distinct embedding clusters at k>=5 using cosine distance And pairwise cosine similarity between any two selections is < 0.90 And attribute coverage across the 5 selections spans at least 3 dimensions among: lighting variants, background types, product categories, material types, composition types And cluster_ids, diversity_score [0,1], and covered_dimensions are included in the response

Near-Duplicate and Redundancy Avoidance

Given near-duplicate candidates exist in the eligible pool When building the selection set Then items with perceptual-hash Hamming distance <= 8 or embedding cosine similarity >= 0.97 to a higher-ranked candidate are excluded from the 5 And no two returned items share the same source_capture_id and capture_timestamp within 2 seconds And if de-duplication reduces eligible choices below 5, fallback behavior is triggered

Quality Heuristics Filtering

Given quality metrics are computed for each candidate image When scoring candidates Then every selected image meets all thresholds: sharpness (Laplacian variance) >= 120, exposure EV in [-1.5, 1.5], SNR >= 20 dB, short_side >= 800 px, no major motion blur detected And quality_scores per metric are included per selected image And if fewer than 5 candidates meet thresholds, fallback behavior is triggered

Transparency via Reason Codes and Ranking

Given a ranked selection is produced When the response is returned Then each selected item includes 1–3 reason_codes from the controlled vocabulary and a primary_reason And each item includes: image_id, rank (1–5), cluster_id, representativeness_score [0,1], quality_scores, attribute_flags And ties in representativeness_score are broken by higher quality_score, then more recent upload_time And ranks are contiguous and strictly increasing from 1 to 5

Confidence Scores and Low-Diversity Fallback

Given diversity and quality metrics are computed When diversity_score < 0.60 or unique_clusters < 4 or eligible_count < 5 Then the engine returns the best-available set (minimum 3 items) with fallback=true, fallback_reason, guidance_message, and missing_dimensions And sampler_confidence [0,1] is included and reflects diversity and quality (monotonic with diversity_score) And can_train=false when returned_count < 3, else true

Service API and Indexing Integration

Given a client presents valid credentials and organization_id When POST /sampler/jobs is called with org_id and optional window/config Then the service responds 202 with a job_id and enqueues the task And the engine queries the asset store for assets where index_status=ready and visibility=seller within the specified window And GET /sampler/jobs/{job_id} returns 200 with status in {queued, running, succeeded, failed}, duration_ms, and the selection payload on success And the operation is idempotent for identical inputs within 24h (same job_id and result) And P95 end-to-end time for pools up to 2,000 assets is <= 45,000 ms; P99 <= 90,000 ms

Edge Case Inclusion

"As a seller of varied products, I want tricky product scenarios automatically represented in the sample so that my preset performs reliably on hard cases I actually ship."

Description

Detects and prioritizes inclusion of edge-case photos (e.g., transparent or reflective products, black-on-black, white-on-white, intricate patterns, extreme aspect ratios, low-resolution, motion blur) when present in the candidate set. Maintains a taxonomy of edge-case types and thresholds to ensure at least one edge case is represented without over-weighting anomalies. Includes safeguards to exclude irrecoverable defects (e.g., corrupted files) from selection. Produces labeled tags that can be surfaced in the UI rationale and stored with the training snapshot.

Acceptance Criteria

Edge Case Inclusion When Present

Given a candidate set of 5–1000 images and the edge-case taxonomy thresholds are loaded, When the set contains ≥1 image classified as any edge-case type with classifier confidence ≥ its configured threshold, Then the 5 selected images include ≥1 edge-case image; And when no image meets any edge-case threshold, Then 0 edge-case images are selected; classifications below threshold must not trigger inclusion.

Edge Case Non-Overweighting Rule

Given the proportion P of edge-case images (meeting thresholds) in the candidate set, When selecting 5 images, Then the number of edge-case selections E satisfies: - If P < 20%, E ≤ 1 - If 20% ≤ P < 50%, E ≤ 2 - If P ≥ 50%, E ≤ 3

Edge Case Diversity Preference

Given the candidate set contains ≥2 distinct edge-case types meeting thresholds, When selecting edge-case images for inclusion, Then selected edge-case images must prefer distinct types (no duplicate type) until each present type has at least one representation or the edge-case cap is reached; And ties are broken by classifier confidence in descending order.

Irrecoverable Defects Safeguard

Given the candidate set contains corrupted or unreadable files (e.g., zero-byte, unsupported format, decode error), When running selection, Then such files are excluded from consideration and not counted toward edge-case proportion P or selections E; And a reason code per file is logged and included in the selection rationale output; And the sampler returns up to 5 valid selections; if <5 valid candidates exist, it returns all valid ones with a shortfall reason.

Edge Case Tagging and Snapshot Persistence

Given selection completes, When returning the 5 selected images, Then each selected image includes tags[] with zero or more edge-case types, classifier confidence per tag, and taxonomyVersion; And these tags and the taxonomyVersion are persisted with the training snapshot and available to the UI rationale endpoint within 1 second of selection completion.

Taxonomy Versioning and Thresholds

Given the system is initialized, When retrieving the edge-case taxonomy, Then it is versioned and includes at least: transparent, reflective, black-on-black, white-on-white, intricate pattern, extreme aspect ratio, low-resolution, motion blur; And each type has a configurable confidence threshold in [0.0, 1.0]; And the taxonomyVersion used is recorded with every selection output for auditability.

Recency & Eligibility Rules

"As a brand manager, I want Smart Sampler to pull from my most recent, valid uploads so that the sample reflects what I’m currently listing, not outdated or low-quality images."

Description

Defines the candidate pool for sampling based on configurable recency windows (e.g., last 14 days or last 500 uploads), workspace/brand scoping, and eligibility filters. Excludes failed imports, near-duplicates, and images below minimum quality thresholds. Supports manual refresh and rerun to capture newly uploaded images. All rules are configurable per workspace and auditable to ensure the sample reflects true, current catalog conditions.

Acceptance Criteria

Recency Window — Last N Days

Given a workspace with time zone set and recency rule type "Days" = 14 When Smart Sampler builds the candidate pool Then only images with uploaded_at in [now-14 days, now] in the workspace time zone are included And images older than now-14 days are excluded And images with uploaded_at exactly at now-14 days are included

Recency Window — Last N Uploads

Given recency rule type "Uploads" = 500 in Workspace A When Smart Sampler builds the candidate pool Then the 500 most recent successfully imported unique uploads in Workspace A are included And if fewer than 500 eligible uploads exist, all eligible uploads are included And ties on uploaded_at are resolved by descending upload_id

Workspace and Brand Scoping

Given Workspace A with brands B1 and B2 and the brand filter set to B1 When Smart Sampler builds the candidate pool Then only images where workspace_id = A and brand_id in {B1} are eligible And images from other workspaces or brands are excluded And if the brand filter is unset, all brands within Workspace A are eligible

Eligibility Exclusions — Import Failures, Near-Duplicates, Low Quality

Given workspace thresholds min_quality_score = 0.7, min_dimension_px = 1000, and duplicate_similarity_threshold = 0.95 When Smart Sampler evaluates eligibility Then images with import_status != "completed" or is_soft_deleted = true are excluded And images with similarity >= 0.95 to any other image within the recency window are near-duplicates; only the highest quality_score instance is retained and the rest excluded And images with quality_score < 0.7 or min(width, height) < 1000 are excluded And an exclusion_reason code is recorded for every excluded image

Manual Refresh & Rerun Captures New Uploads

Given a previous sampler run completed and new eligible images have been uploaded since that run When the user clicks "Refresh & Rerun" for the workspace Then the candidate pool is rebuilt using the currently saved rules and includes the new eligible images And triggering "Refresh & Rerun" twice without additional uploads yields identical candidate pools And the rebuild completes within 10 seconds for up to 10,000 eligible images

Audit Trail for Candidate Pool Generation

Given Smart Sampler generates a candidate pool When the run completes Then an audit record is stored with: run_id, timestamp, initiated_by (user_id/service), workspace_id, brand filter, rule_version, recency rule type/value, quality thresholds, duplicate threshold, include_count, exclude_count by reason, and lists of included and excluded image IDs with reason codes And a user with audit permissions can view and export the audit record in JSON and CSV And rerunning with the same data snapshot and rule_version reproduces the same candidate pool and audit counts

Per-Workspace Rule Configuration & Versioning

Given a workspace admin updates recency and eligibility rules When the admin clicks Save Then the configuration is validated and saved as a new version with version_id, editor_id, and timestamp And subsequent Smart Sampler runs use the latest saved version; in-flight runs use the version snapshot they started with And non-admin users cannot modify the rules; they can view the active version and its effective values

Sample Review & Override

"As a boutique owner, I want to quickly review and swap any of the five picks before training so that I stay confident the sampler reflects my brand reality."

Description

Provides a lightweight review UI showing the five selected images, their diversity rationale, and suggested alternates per slot. Enables one-click swap, approve, or regenerate actions before preset training. Persists an immutable selection snapshot (image IDs, model/version, parameters, reason codes) tied to the preset training job for traceability. Includes keyboard shortcuts and accessible controls to minimize friction and support quick confirmation.

Acceptance Criteria

Display Sampler Selection with Diversity Rationale & Alternates

Given a completed Smart Sampler run for recent uploads When the user opens the Sample Review UI Then exactly 5 slots are displayed with the selected representative images And each slot shows a human-readable diversity rationale mapped to reason codes And each slot lists 1–3 suggested alternates with their reason codes And thumbnails use skeletons while loading and show a fallback with retry on error And the selection shows the model name, version, and key parameters used

One-Click Approve, Swap, and Regenerate

Given the Sample Review UI is open When the user clicks Approve All Then all 5 slots are marked approved and the Continue/Train action becomes enabled Given a slot with alternates When the user clicks Swap on an alternate Then the alternate becomes primary within 300 ms and the previous primary moves to alternates Given a slot When the user clicks Regenerate Then up to 3 new alternates return within 5 seconds with updated reason codes and previously rejected images are excluded Given any in-progress changes When the user navigates away and returns Then the current selection state is preserved until approval and snapshot

Immutable Selection Snapshot & Traceability

Given the user confirms the selection When the system persists the snapshot Then it records: preset ID, training job ID, 5 primary image IDs, per-slot alternates at decision time, reason codes, model name, model version, sampler parameters, timestamps, and user ID And the snapshot is immutable; subsequent changes create a new snapshot with a new version and existing records are read-only And each training job references exactly one snapshot ID; re-running training on the same selection reuses the same snapshot And an audit API allows retrieval by preset ID and training job ID and returns a checksum to verify integrity

Keyboard Shortcuts & Efficient Navigation

Given the Sample Review UI When keyboard shortcuts are used Then the user can approve all (A), approve current slot (Enter), swap to highlighted alternate (S), regenerate current slot (R), navigate slots (Left/Right), and cycle alternates (Up/Down) And a visible shortcut hint panel is toggled with ? and is accessible to screen readers And all actions are fully operable without a pointing device; a full review can be completed via keyboard alone And shortcuts avoid conflicts with native browser defaults via scoped handling or remapping

Accessibility Compliance (WCAG 2.1 AA)

Given assistive technology users navigate the Sample Review UI When interacting with controls and status changes Then all actionable elements have programmatic names, roles, and states with logical focus order And focus indicators meet 3:1 contrast; text and interactive elements meet 4.5:1 contrast; images and rationales have text alternatives And dynamic updates (swap, regenerate, approve) are announced via ARIA live regions without stealing focus And the UI is operable at 200% zoom and in high-contrast mode with no keyboard traps and 44x44px minimum hit targets

Performance & Responsiveness

Given a median network and typical session When the user opens the Sample Review UI Then above-the-fold content renders within 2 seconds and all thumbnails within 3 seconds And approve/swap actions update the UI within 300 ms; regenerate returns alternates within 5 seconds at p95 And snapshot persistence completes within 1 second at p95 and does not block the UI And UI animations and transitions maintain responsiveness above 55 FPS during loading and interactions

Error Handling & Recovery

Given an image fails to load When a retry is triggered Then the system retries up to 3 times with exponential backoff and provides a visible Retry control; if still failing, a meaningful error is shown and the slot remains actionable Given regenerate fails for a slot When the user retries Then previous alternates are retained, a non-blocking toast explains the failure, and no partial state corruption occurs Given snapshot persistence fails When the user confirms again Then a blocking error with safe retry is shown and no training job starts without a persisted snapshot And all errors are logged with a correlation ID and exposed in the audit trail with failure reason codes

Processing SLA & Scalability

"As a time-pressed seller, I want the sample to be ready in seconds even for large batches so that I can train and publish presets without waiting."

Description

Ensures the sampler processes large catalogs quickly and reliably. Targets selection completion within 30 seconds for up to 2,000 eligible images and scales via background jobs and batching to 10,000+ images. Implements queueing, backoff, and partial results fallback when resources are constrained. Exposes progress indicators and clear error states in the UI. Observability includes latency metrics, timeouts, and autoscaling signals to maintain the SLA under peak loads.

Acceptance Criteria

SLA: Complete selection within 30s for 2,000 eligible images

Given a tenant with 2,000 eligible images and no other sampler job running for that tenant When the user starts Smart Sampler Then five representative images are selected and persisted within 30 seconds end-to-end in at least 95% of runs And the 99th percentile completes within 45 seconds And no job-level timeout or unhandled error occurs And a completion event is emitted within 1 second of persistence

Scalability: Background jobs and batching for 10,000+ images

Given a tenant with 10,000 eligible images When Smart Sampler is started Then the sampler job enqueues within 1 second and begins processing within 5 seconds when a worker is available And images are processed in batches of no more than 500 per worker with parallel workers And a per-tenant concurrency cap is enforced (default 2) to prevent noisy-neighbor impact And the job completes without worker crashes or data corruption

Reliability: Queueing, retries, and backoff under resource constraints

Given transient failures (e.g., HTTP 5xx, timeouts) while processing a batch When a batch fails Then the system retries with exponential backoff (initial 2s, max 30s, full jitter) up to 5 attempts And duplicate concurrent sampler jobs for the same tenant are prevented And after final failure the batch is moved to a dead-letter queue with error code and trace metadata And a DLQ metric increments for alerting

Resilience: Partial results fallback with deadline

Given the job exceeds the 30-second SLA or encounters resource constraints When fewer than five selections are ready by the SLA deadline Then at least three high-confidence representatives are returned if available and the job is marked Partial And remaining selections continue in the background until completion or a 2-minute ceiling, whichever comes first And the UI shows 'Partial (X/5)' with Resume and Retry actions And a completion notification is emitted when the remaining selections finalize

UX: Real-time progress indicator and states

Given an active sampler job When the user views job status Then the UI displays state (Queued, Processing, Partial, Completed, Failed), percent complete, items processed/total, and ETA And progress updates within 1 second of backend state changes without requiring a manual refresh And progress is announced via ARIA live regions for screen readers And Cancel and Retry actions are available when applicable

UX: Clear error states with actionable recovery

Given a sampler job fails When the user views the error Then the UI presents a specific error category (Upload Corruption, Rate Limited, Resource Exhausted, Internal Error) And shows recommended next steps and a Retry button for retryable errors And displays a correlation ID matching backend logs And non-retryable failures do not requeue automatically

Observability & Autoscaling: Maintain SLA under peak load

Given a peak load of 100 concurrent sampler jobs each with 2,000 eligible images When the load persists for 5 minutes Then P95 end-to-end selection latency remains ≤ 30 seconds And metrics are emitted for queue wait, processing time, retries, timeouts, and batch sizes at 1-minute resolution And an alert fires if P95 latency > 30s for 5 consecutive minutes And autoscaling increases worker capacity within 60 seconds of sustained queue depth > 50 and scales back within 10 minutes after queue depth < 10

Selection Telemetry & Feedback Loop

"As a product manager, I want insights into how users accept or modify the sampler’s picks so that we can continuously improve selection quality and training outcomes."

Description

Captures user interactions (approvals, swaps, regenerations) and post-training outcomes (preset acceptance rate, downstream edit rate) to measure sampler effectiveness. Computes coverage metrics for lighting, backgrounds, and product categories in chosen samples versus catalog distribution. Feeds anonymized statistics into model improvement while respecting workspace boundaries and privacy settings. Surfaces basic quality analytics to the product team for iterative tuning.

Acceptance Criteria

User Interaction Telemetry Capture

Given telemetry is enabled for workspace W and a user is interacting with Smart Sampler selections When the user approves a sample, swaps a sample, requests a regeneration, or dismisses a sample Then an event is recorded with fields: event_id (UUIDv4), workspace_id, anonymized_user_id (workspace-scoped hash), session_id, sampler_session_id, selection_id, action_type ∈ {approve, swap, regenerate, dismiss}, action_metadata (optional), timestamp (ISO-8601 UTC), client_version, latency_ms And no raw image pixels, filenames, or free-text notes are included in the payload And server-side idempotency ensures duplicate event_ids do not create multiple records And the end-to-end capture rate for eligible actions over a 24h window is ≥ 99.5%

Telemetry Reliability & Latency

Given the client is offline or experiencing intermittent connectivity When interaction events are generated Then events are queued locally up to 5,000 events or 10 MB (whichever comes first) for up to 24 hours And queued events are retried with exponential backoff and jitter until acknowledged by the server And P95 end-to-end latency from event creation to server availability is ≤ 120 seconds; P99 ≤ 5 minutes And daily event loss (client-sent minus server-acknowledged) is ≤ 0.2% And server guarantees at-least-once delivery with idempotent upserts (dedupe by event_id), resulting in ≤ 0.5% duplicate insert attempts and 0% duplicate stored records

Coverage Metrics Computation

Given a Smart Sampler run is finalized for workspace W When coverage is computed Then the baseline distribution is derived from W’s last 30 days of uploads or the most recent 10,000 images, whichever is smaller And the selected 5 samples are classified for lighting ∈ {studio, natural, low-light, mixed}, background ∈ {white, colored, textured, in-situ}, and product_category (workspace taxonomy) And classifier macro-F1 on a validation set is ≥ 0.90 for lighting and background, and ≥ 0.85 for product_category And the system computes per-dimension representation deltas (selected vs baseline) and an overall Coverage Score ∈ [0,1] And metrics are persisted within 60 seconds of selection and are queryable by sampler_session_id

Post-Training Outcome Tracking

Given a brand preset is trained from a Smart Sampler session S When the preset is used in production Then the system attributes downstream outcomes to S for the next 14 days or first 500 processed images, whichever comes first And preset acceptance rate is computed as accepted_presets / eligible_presets and is updated daily And downstream edit rate is computed as images with manual edits beyond crop / generated images and is updated daily And outcome metrics exclude workspaces that opt out of telemetry and sessions with fewer than 50 generated images And metrics are available via internal analytics API with filters by workspace_id and date range

Privacy & Workspace Boundary Controls

Given workspace W has telemetry disabled When a user performs sampler-related actions Then no telemetry payloads are transmitted or stored for W and local buffers are purged within 60 seconds Given telemetry is enabled When events are processed and aggregated Then user identifiers are hashed with a workspace-scoped salt; no email, names, or image content are stored And cross-workspace joins are blocked; queries are constrained to workspace_id unless using approved aggregated datasets with k-anonymity k ≥ 20 And data retention for raw events is ≤ 180 days; deletion requests are honored within 7 days And all access to telemetry and analytics requires authorized roles and SSO; access is logged

Product Team Quality Analytics

Given a product analyst with the appropriate role accesses the Quality Analytics dashboard When viewing Smart Sampler analytics Then the dashboard displays, by selectable time range, event volumes, action rates (approve/swap/regenerate/dismiss), coverage scores, preset acceptance rate, and downstream edit rate And no raw images, product names, or free-text are displayed; workspace identifiers are hashed And API/dashboards return within P95 ≤ 800 ms for cached queries and ≤ 3 s for uncached, with 99.9% monthly availability And metric definitions are documented and accessible via in-UI tooltips And data freshness is ≤ 60 minutes

Anonymized Model Feedback Ingestion

Given the nightly aggregation window closes When the model improvement pipeline requests input Then the system exports only cohort-level aggregates (cohort size ≥ 20) with workspace identifiers removed and differential privacy noise calibrated to ε ≤ 2, δ ≤ 1e-5 per 30 days And the exported schema includes coverage_score, per-dimension representation deltas, preset_acceptance_rate, downstream_edit_rate, and sample_size And exports are versioned and lineage-tracked; the consumer job references the dataset version and fails closed if privacy checks or schema validation fail And no data from telemetry-disabled workspaces is included

Audit & Reproducibility

"As a support engineer, I want to reproduce a customer’s sample exactly so that I can debug issues and explain selection rationale with confidence."

Description

Provides deterministic sampling via seeded randomness and records all inputs required to reproduce a given selection (candidate set identifiers, embeddings version, classifier versions, thresholds, seed). Enables support and power users to re-run the sampler and verify identical outputs or explain divergences after model upgrades. Stores audit logs with retention aligned to workspace policy and exposes a support-only replay tool.

Acceptance Criteria

Deterministic Sampling With Seed

Given a fixed candidate_set_ids list, embeddings_version, classifier_versions, threshold set, sampler_version, and seed S When Smart Sampler is executed three consecutive times without changing any inputs Then each run returns exactly five unique image_ids identical to one another and in the same order And the run records indicate the same seed S was used for all executions

Complete Audit Record Per Sampler Run

Given a sampler run completes successfully When the audit record is written Then the record contains: run_id, timestamp (UTC), workspace_id, actor (user_id or service_account), candidate_set_ids, embeddings_version, classifier_versions (by component), thresholds, sampler_version, seed, sampling_strategy, and output image_ids with ranks And the record is immutable and retrievable by run_id via support tooling And no successful run is observable to end users unless its audit record exists

Retention Enforcement Aligned to Workspace Policy

Given a workspace retention policy of N days is configured When an audit record becomes older than N days Then it is purged within 24 hours of crossing the threshold and is no longer retrievable by any role And audit records newer than N days remain retrievable And purge events are themselves logged with run_id and purge_timestamp

Support-Only Replay Reproduces Output

Given a user with support role and permission sampler.replay and a target run_id When they invoke Replay with option use_recorded_versions=true Then the tool re-runs Smart Sampler using the recorded candidate_set_ids, embeddings_version, classifier_versions, thresholds, sampler_version, and seed And it returns the same five image_ids in the same order and marks the replay status as Reproduced And if required inputs are missing (e.g., candidate not present or version unavailable), the tool returns an error code (MISSING_INPUTS or VERSION_UNAVAILABLE) without partial results And users without support role receive 403 Forbidden with no leakage of audit fields

Divergence Report After Model Upgrades

Given a historical run_id and newer component versions are available When Replay is invoked with use_recorded_versions=false (use_latest=true) Then the tool executes the sampler with the latest available embeddings/classifiers while keeping the same candidate_set_ids and seed And it produces a divergence report including: original vs new component versions, Jaccard similarity of selection sets, list of added/dropped image_ids with rank positions, and summary reasons where available And the replay is marked DIVERGED if the five image_ids or their order differ

Power-User Deterministic Re-run via API

Given a workspace admin or designated power_user and a historical run_id When they call the re-run API with explicit pins matching the audit record (seed, embeddings_version, classifier_versions, thresholds, sampler_version) and scope limited to their workspace Then the API returns the same five image_ids in the same order And the API creates a new run_id whose audit record references the original run_id as replay_of And access is denied (403) for users outside the workspace

Style Coach

Inline guidance with best‑practice tips and guardrails as you set background, crop, lighting, and retouch levels. Clear, plain‑language hints explain trade‑offs and suggest starting points, helping non‑designers dial in an on‑brand look with confidence.

Requirements

Contextual Inline Tips & Explanations

"As a non‑designer seller, I want clear, in‑context explanations for each adjustment so that I can choose settings confidently without learning photo jargon."

Description

Provide inline, plain‑language guidance for background, crop, lighting, and retouch controls that explains what each adjustment does, the trade‑offs (e.g., “stronger retouching may reduce texture realism”), and suggests starting values based on product category and selected brand preset. Hints appear contextually as users hover or adjust sliders, with concise do/don’t examples and quick links to apply recommended settings. Content is non-technical, localized, and accessible, with glossary rollovers for unfamiliar terms. Integrates with the existing editor UI as a collapsible “Coach” panel and lightweight tooltips, instrumented with analytics to measure usage and tip efficacy, and supports A/B testing of copy variants.

Acceptance Criteria

Tooltip guidance for background control during hover and adjustment

Given the user hovers over or focuses the Background control or begins adjusting its slider When the trigger occurs Then a tooltip appears within 300 ms, anchored to the control, never obscuring the main image canvas, and remains visible while the control is focused or active And the tooltip copy is plain-language (Flesch-Kincaid Grade ≤ 8), includes a one-sentence what-it-does explanation, a trade-off statement (e.g., realism vs. cleanliness), and a starting value recommendation derived from the current product category and brand preset And the tooltip contains one Do and one Don’t micro-example with 96×96 px thumbnails and alt text And an Apply Recommendation link is present and focusable And pressing Esc or moving focus away dismisses the tooltip And the tooltip is not rendered when the control is disabled

Coach panel integration, collapse/expand, and state persistence

Given the editor is loaded When the user clicks the Coach panel toggle or presses the assigned keyboard shortcut Then the panel expands/collapses without shifting the image canvas and without overlapping critical editor controls And panel open/closed state persists across projects and sessions for the signed-in user And on viewports < 1024 px width the panel renders as a bottom sheet with the same content and controls And the Coach code is lazy-loaded; initial editor bundle size increase is ≤ 30 KB gzipped And first open completes within 500 ms on a 5 Mbps connection (p95) And the panel is fully operable via keyboard (Tab/Shift+Tab) with a visible focus indicator

Personalized starting values by product category and brand preset

Given a product has a detected or selected category and a brand preset is active When a user opens tips for Background, Crop, Lighting, or Retouch Then each tip displays a Recommended starting value sourced from the category×preset mapping table with a visible version tag And clicking Apply sets the corresponding control(s) to the recommended values and updates the preview within 200 ms (p95) And an "Applied" toast appears for 2–4 seconds with an Undo action that reverts the settings And if category is unknown, preset-level defaults are used; if both unknown, global defaults are used; these fallbacks are explicitly labeled And recommendations never exceed the allowed min/max for each control

Do/Don’t examples and quick actions

Given a tip is displayed for any of the four controls When the content renders Then it includes at least one Do and one Don’t example relevant to the current control and product category And each example includes a 96×96 px thumbnail, concise caption (≤ 80 characters), and alt text describing the example And clicking the Do example’s Apply button applies its linked settings immediately without page navigation And the Don’t example has no Apply action And examples are hidden if bandwidth is low and thumbnails fail to load after 2 seconds, with text-only fallbacks shown

Localization and glossary rollovers for non-technical language

Given the user’s locale is en-US, es-ES, fr-FR, or de-DE When tips and Coach content are displayed Then copy is served in the user’s locale with no truncated or clipped strings, and numbers/date formats follow the locale And if the locale is unsupported, content falls back to en-US with a non-blocking notice in settings And all tip bodies meet Flesch-Kincaid Grade ≤ 8 in each locale And glossary-marked terms display an inline dotted underline; on hover or focus, a glossary tooltip opens within 250 ms with a 20–120 character definition and is dismissible with Esc or blur And glossary tooltips are navigable via keyboard and announced by screen readers

Accessibility of tooltips and Coach panel (WCAG 2.2 AA)

Given a keyboard-only or screen reader user interacts with tips or the Coach panel When navigating through controls and content Then all interactive elements are reachable via Tab order, have visible focus, and support activation via Enter/Space And tooltips use role="tooltip" with proper aria-describedby associations; panel uses appropriate landmark/role And content meets contrast ratio ≥ 4.5:1; interactive targets are ≥ 44×44 px And no tooltip auto-dismisses in under 5 seconds while focused/hovered; Esc always dismisses And screen readers announce tooltip open/close and the Apply action result And there is no keyboard trap; focus returns to the invoking control after tooltip dismissal

Analytics instrumentation and A/B testing of tip copy

Given analytics is enabled When a user views a tip, expands/collapses the Coach, clicks Apply, views a glossary term, or dismisses a tip Then events tip_viewed, coach_opened/closed, tip_applied, glossary_viewed, and tip_dismissed are emitted with properties: user_id_hash, session_id, control_id, product_category, brand_preset_id, locale, ab_variant_id, timestamp And events are queued and delivered with p95 latency ≤ 2 s and daily drop rate ≤ 2% And no PII (names, emails, images) is included in payloads And A/B copy variants are supported with a 50/50 random split (configurable), sticky per user for the experiment duration, and the assigned ab_variant_id is included on all related events And experiments can be enabled/disabled remotely with a safe fallback to control copy within 200 ms

Real‑time Before/After Preview

"As a boutique owner, I want to preview changes instantly and compare before/after so that I can see the impact and avoid over‑editing."

Description

Render immediate visual feedback for all Style Coach adjustments with a smooth, low‑latency preview that supports a before/after toggle (split slider and quick tap), per‑adjustment previews, and instant revert to defaults. The preview pipeline incrementally applies changes on-device with GPU acceleration and smart throttling to maintain target frame rates, falling back to progressive updates for large images or low‑power devices. Ensures pixel parity between preview and final export, with safeguards to re-render at full fidelity after adjustments. Includes keyboard shortcuts and accessible controls for comparison modes.

Acceptance Criteria

Split Slider Before/After Comparison

Given a product photo is loaded in Style Coach with at least one adjustment applied And the before/after split slider is visible When the user drags the slider horizontally via mouse, touch, or keyboard arrows Then the preview updates continuously so that pixels left of the divider show the unprocessed "before" image and pixels right show the processed "after" image with no cross-bleed And the divider tracks input within 1 rendered frame of movement And median frame rate during drag on a reference device is >= 45 FPS, with 95th percentile input-to-frame latency <= 120 ms And the divider cannot be dragged outside image bounds and supports RTL locales And there is no flicker, tearing, or mismatch between displayed halves during drag

Quick Tap and Hold Before/After Toggle

Given at least one adjustment is applied When the user presses and holds the comparison key (e.g., Space) or presses and holds the on-screen Compare button Then the preview switches to "before" within 60 ms and remains so while held And on release, the preview returns to "after" within 60 ms preserving current adjustments And a single tap (keyboard or button) toggles persistent compare mode on/off And the toggle state is reflected in the UI and is limited to the current session And frame rate during toggling does not drop below 30 FPS on reference devices

Per-Adjustment Live Preview Responsiveness

Given background, crop, lighting, or retouch controls are being adjusted via drag or input When the control value changes Then the on-device GPU-accelerated preview updates within 80 ms of the latest input and at least every 100 ms during continuous drag And intermediate renders are cancelable; outdated frames are dropped in favor of the newest value And upon interaction end (>= 200 ms idle), a full-fidelity re-render completes within 500 ms And visual output of the full-fidelity re-render matches the next exported image per Pixel Parity criteria

Instant Revert to Defaults

Given adjustments have been made When the user invokes Revert to Defaults (button or Cmd/Ctrl+Backspace) Then all Style Coach controls reset to system defaults and the preview updates within 150 ms And the action is atomic (single undo step) and undo/redo restores prior state including compare mode And no residual crop, mask, or hidden parameters remain after revert And any in-progress renders are canceled and replaced by a default-state full-fidelity render

Preview-to-Export Pixel Parity Safeguard

Given the preview has stabilized after user interaction (>= 200 ms idle) When the user triggers Export or background save Then the system verifies parity by producing a full-fidelity render with the same pipeline and color management as preview And the exported image and the stabilized preview buffer are bitwise identical in linear RGB 16-bit (or 8-bit where applicable) for supported devices Or, if hardware/driver variance prevents bitwise equality, the per-pixel absolute delta must be <= 1/255 with SSIM >= 0.999; otherwise an automatic re-render is performed before export until criteria are met And color profile, ICC tags, and output dimensions match exactly between preview and export

Smart Throttling and Progressive Updates on Constrained Devices

Given a large image (> 24 MP) or a device flagged as low-power or thermally throttled When the user adjusts any Style Coach control Then the system maintains interactive frame rate >= 30 FPS by throttling expensive passes and rendering lower-resolution tiles first And a progressive preview appears within 150 ms and refines to full resolution within 700 ms after interaction ends And no UI thread stall exceeds 16 ms at 60 Hz; input remains responsive throughout

Keyboard Shortcuts and Accessible Comparison Controls

Given a keyboard-only or screen reader user is operating Style Coach When interacting with compare modes (split slider, quick toggle) and revert Then all functions are reachable via documented shortcuts: Focus split slider, Move divider (Left/Right), Quick compare (Space), Toggle compare (C), Revert (Cmd/Ctrl+Backspace) And every control exposes accessible name, role, and state; focus order is logical; no focus trap occurs And features are operable without a pointer; shortcuts are surfaced in tooltips and Help And meets WCAG 2.2 AA for 2.1.1 Keyboard, 2.4.3 Focus Order, 4.1.2 Name, Role, Value And screen readers announce compare mode state and divider position (percentage) within 500 ms

Style Guardrails & Safe Ranges

"As a marketplace seller, I want guardrails that keep edits within platform guidelines so that my listings aren’t penalized and my brand looks consistent."

Description

Enforce recommended and hard‑limit ranges for background, crop, lighting, and retouch parameters based on brand presets and marketplace policies (e.g., pure white background, minimum subject coverage). Provide proactive warnings before settings violate guidelines, explain why, and offer one‑click corrections ("snap to safe"). A rules engine maps product category and target marketplace to parameter bounds and validation checks, with configurable templates per marketplace and brand. Guardrails never block experimentation in sandbox mode but require confirmation to publish non‑compliant results. Includes audit logging for applied guardrails and a visual indicator when settings are outside recommended ranges.

Acceptance Criteria

Non-Compliant Publish Requires Explicit Confirmation

Given a live publish target is selected for marketplace M and brand preset B is active And at least one parameter (background, crop, lighting, retouch) violates a configured rule When the user clicks Publish Then a confirmation modal appears within 500 ms listing each violated rule with plain-language explanation and source (Marketplace/Brand) And for any hard-limit violation, the Publish Anyway action is not available; primary actions are Snap to Safe & Publish and Cancel And if only recommended-range violations exist, actions include Publish Anyway, Snap to Safe & Publish, and Cancel And choosing Snap to Safe & Publish adjusts all violating parameters to the nearest compliant values per the active ruleset and completes publish successfully And if there are no violations, publish proceeds with no modal

Sandbox Mode Allows Unrestricted Experimentation

Given sandbox mode is enabled for the current project When the user sets parameters outside recommended or hard-limit ranges Then no editing interactions are blocked and changes are applied in the editor And inline warnings and indicators still appear to inform about potential non-compliance And exporting previews or downloading test renders proceeds without confirmation And attempting to publish to a live marketplace from sandbox triggers the non-compliant publish confirmation modal if violations exist

Proactive Warning Explains Violation and Suggests Fix

Given the user is adjusting a parameter slider governed by a ruleset When the value enters within 10% of a hard limit Then an inline caution tooltip appears within 300 ms indicating proximity to the limit and the reason source (e.g., Marketplace policy) When the value crosses a recommended bound Then a yellow warning pill appears within 300 ms with message explaining the recommendation, the why, and a CTA Snap to Safe When the value exceeds a hard limit Then the control is marked red, a persistent banner appears with a plain-language explanation and link to Learn more, and publish will require correction And all warnings clear within 300 ms after the value returns to within recommended range

One-Click Snap to Safe Corrects Settings

Given one or more parameters are outside compliant ranges for the active ruleset When the user clicks Snap to Safe from a warning, banner, or modal Then the system computes nearest compliant values and applies them to the current selection (single image or batch) in under 700 ms per 100 images And a toast confirms "Fixed N issues across K images" with a View details link listing adjustments by parameter And after correction, no hard-limit violations remain and any recommended-range violations are resolved unless explicitly excluded by the user

Rules Engine Loads Bounds by Category and Marketplace

Given product category C and marketplace M are selected and brand preset B is active When the editor session initializes or the user changes C, M, or B Then the rules engine loads the configured templates for M and B, including any category-specific overrides And hard-limit bounds are computed as the most restrictive intersection of M and B hard limits And recommended ranges are taken from B and clipped to the computed hard-limit bounds; if B lacks a recommendation, fall back to M, else to global defaults And the active ruleset exposes ruleId(s), ruleVersion(s), and sources for each parameter And ruleset evaluation completes within 200 ms when cached and within 800 ms on a cold fetch

Audit Log Captures Guardrail Events

Given a guardrail-related event occurs (warning shown, snap-to-safe applied, publish override, ruleset change) When the event is processed Then an audit log entry is written within 1 s containing: timestamp, userId, projectId, imageId(s), environment (sandbox/live), actionType, parameter(s), previousValue(s), newValue(s), ruleId(s), ruleVersion(s), marketplace, brandPresetId, and outcome And audit entries are retained for at least 180 days and are exportable as CSV and JSON And viewing Compliance History for an image shows the last 20 guardrail events in chronological order

Visual Indicator for Out-of-Range Settings

Given a parameter value is within recommended range Then the control shows a neutral state with no badge and no thumbnail indicator When the value exits the recommended range but remains within hard limits Then a yellow Out of recommended badge appears on the control and a yellow indicator appears on affected image thumbnails within 300 ms When the value exceeds a hard limit Then a red Non-compliant badge appears on the control, affected thumbnails show a red indicator, and the Publish button displays a red dot with the count of violating images And returning values to within recommended range clears indicators within 300 ms

AI Smart Defaults

"As a time‑pressed seller, I want smart starting values based on my product type so that I can get an on‑brand look faster with fewer adjustments."

Description

Auto‑suggest starting values for background, crop, lighting, and retouch based on detected product type, material, and initial image conditions (exposure, shadows, background uniformity). The model leverages existing product metadata, visual features, and the user’s selected brand preset to compute a balanced baseline, displaying confidence and reasoning in plain language (e.g., “jewelry identified—reduce shadows to reveal sparkle”). Users can accept all suggestions, apply per‑control, or dismiss. The system learns from user overrides to refine future defaults per brand. Includes privacy‑safe processing and deterministic fallbacks when detection is uncertain.

Acceptance Criteria

Auto-Suggest Smart Defaults Based on Product and Brand

Given a product image with metadata and a selected brand preset When the Style Coach panel is opened Then the system proposes values for background, crop, lighting, and retouch for that image without applying them. Given a batch of up to 200 images When suggestions are generated Then 95th-percentile latency per image is <= 2 seconds and average latency is <= 1 second. Given different product types (e.g., jewelry, apparel, footwear) When suggestions are generated Then proposed values vary appropriately by type and respect brand preset constraints.

Apply All, Per-Control, or Dismiss Suggestions

Given suggestions are available for an image or batch When the user selects "Apply all" Then all four controls adopt the suggested values and a confirmation toast appears. Given suggestions are available When the user toggles apply per control Then only the selected controls update to suggested values and others remain unchanged. Given suggestions are available When the user selects "Dismiss" Then no control values change and the suggestion banner is hidden for the current session. Given any application of suggestions When the user clicks Undo within 30 seconds Then all affected controls revert to their exact prior values.

Confidence and Plain-Language Reasoning Display

Given suggestions are available When the UI renders them Then each control shows a numeric confidence score (0–100%) and a one-sentence rationale referencing detected product, material, or image conditions. Given a rationale sentence When measured for readability Then it has a Flesch–Kincaid grade level <= 8 and length <= 140 characters. Given any control has confidence < 50% When displayed Then a "Low confidence" badge appears with a link to view fallback criteria. Given the user opens the rationale tooltip When expanded Then detection signals (product type, material, exposure level, background uniformity) and their confidences are listed.

Learning From User Overrides Per Brand

Given brand learning is enabled When a user adjusts any control by >= 15% from the suggested value on >= 5 images of the same detected product type within 30 days Then subsequent suggestions for that brand and product type shift at least 50% toward the median of those overrides. Given multiple brands operate in the system When overrides differ between brands Then learned adjustments remain brand-scoped and never influence other brands. Given the admin selects "Reset learning" for a brand When confirmed Then all learned adjustments for that brand are cleared and new suggestions revert to the model baseline. Given a brand has opted out of learning When users make overrides Then no new override data is stored and suggestions remain at baseline.

Deterministic Fallback on Low Detection Confidence

Given overall detection confidence < 0.5 or product type is unknown When suggestions are requested Then the system uses deterministic brand-neutral baseline values for all controls. Given the same input image and brand preset under fallback conditions When suggestions are requested multiple times Then identical fallback values are returned each time. Given fallback is active When suggestions are displayed Then the UI shows a banner stating "Using fallback defaults due to low confidence" and suppresses per-control confidence scores. Given the user selects "Retry detection" once per session When re-run completes Then the system either replaces fallback with new suggestions (if confidence >= 0.5) or remains in fallback with an updated timestamp.

Privacy-Safe Processing and Data Retention

Given images are processed to generate suggestions When processing completes Then raw images and derived features are automatically deleted within 30 minutes and are not used to train global models. Given system event logs are stored When reviewed Then they contain no full-resolution images or PII, only anonymized event IDs, timestamps, and aggregated metrics. Given override-learning data is stored When scoped Then it is limited to brand ID, contains only control deltas and detection labels, and can be purged upon brand request within 72 hours. Given a brand admin requests a data export When initiated Then the system provides an export of learned adjustments and anonymized event history for that brand within 24 hours.

Batch Consistency Advisor

"As a catalog manager, I want the system to flag inconsistent edits across a batch so that all images align with my brand preset."

Description

Analyze parameter variance across a batch and flag inconsistencies that may harm brand coherence (e.g., mixed crops or background hues). Provide a summary view with suggested harmonization actions such as “apply average crop to all,” “normalize background tone,” and “match lighting to reference image,” with previews and per‑image exceptions. Supports cluster‑based grouping for different subcategories within a batch and runs as a background job with progress updates for large uploads. Integrates with existing batch apply/undo, and records changes for easy rollback.

Acceptance Criteria

Background Hue Inconsistency Flagging

Given a batch of images is uploaded and Consistency Advisor analysis is initiated When the system computes each image’s background hue and detects ΔE00 > 3.0 relative to the batch median on ≥10% of images or ≥5 images (whichever is greater) Then the Summary view displays a "Background hue inconsistent" flag with the exact count of affected images and a preview grid of at least 6 thumbnails And the flag shows measured variance (median hue and ΔE00 standard deviation) and includes a "Normalize background tone" action

Normalize Background Tone Action with Preview and Exceptions

Given a "Background hue inconsistent" flag is present When the user clicks "Normalize background tone", selects target = batch median hue, and optionally deselects exception images Then a side-by-side preview renders within 2 seconds for the selected subset, showing before/after for at least 3 representative images And on Apply, the normalized tone is applied only to selected images, thumbnails and metadata update within 5 seconds, and a confirmation reads "<updated> images updated, <excluded> excluded" And the operation is recorded as a single batch action with parameters (target hue, method, affected image IDs) for rollback

Average Crop Apply and Undo

Given the advisor detects more than one output aspect ratio across the batch When the user selects "Apply average crop to all" Then the system computes the modal aspect ratio and center alignment, shows preview overlays for at least 3 images, and on Apply updates crops for all selected images within 5 seconds And a single Undo reverts all applied crops and restores previous crop metadata and thumbnails for all affected images

Cluster-Based Grouping of Subcategories

Given a batch contains visually distinct subcategories When the advisor performs clustering Then images are partitioned into k ≥ 2 groups, each with a group identifier and ≥5 images when available, and the Summary view shows per-group inconsistency flags and suggested actions And applying a harmonization action at the group level affects only images in that group and leaves other groups unchanged

Match Lighting to Reference Image

Given the user selects a reference image from the batch When the user chooses "Match lighting to reference" Then the advisor estimates exposure, contrast, and color temperature from the reference and generates previews for at least 3 sample images And on Apply, adjusted images’ mean luminance and white balance deviate by no more than ±2% from the reference metrics (unless excluded), and a confirmation shows the affected count

Background Job and Progress Updates for Large Batches

Given an upload of ≥200 images or total size ≥500 MB When analysis starts Then the Consistency Advisor runs as a background job with visible status stages (Queued, Analyzing, Suggestions ready) and a progress bar updating at least every 2 seconds And users can continue other in-app tasks while the job runs, and the Summary view becomes available with incremental results within 60 seconds

Change Log and One-Click Rollback

Given one or more harmonization actions have been applied When the user opens the change log Then each entry lists action type, parameters, actor, timestamp, and exact image IDs affected And clicking "Rollback" on an entry reverses the changes across all affected images within 10 seconds, restoring previous thumbnails and metadata, and creates a log entry noting the rollback

Guidance Content Management & Localization

"As a content admin, I want to manage and localize the guidance copy so that tips remain accurate, testable, and relevant across markets."

Description

Provide a lightweight CMS for Style Coach copy and examples, allowing product/UX teams to author, version, localize, and target tips by control, product category, marketplace, and user proficiency. Supports feature flags, rollout scheduling, and A/B testing hooks. Content is delivered via a cached, schema‑validated config to avoid app rebuilds, with rollback on failure and analytics to track tip engagement and impact on edit outcomes. Enables consistent tone of voice and rapid iteration of guidance without code changes.

Acceptance Criteria

CMS Authoring, Versioning, and Style Compliance

Given I am a CMS editor with permission "Guidance:Write" When I create or edit tip copy or examples Then I can save as Draft with a semantic version increment and required change log notes Given a Draft exists When I Publish it Then the config version is incremented, the previous version is retained as Last Good, and the audit trail records timestamp, editor, diff, and reason Given two editors modify the same tip concurrently When the second editor attempts to Publish Then a merge conflict is surfaced and must be resolved before publish succeeds Given content fails tone-of-voice/style lint rules When I attempt to Publish Then the publish is blocked with actionable lint errors and required approver(s) can override only via recorded approval Given I view the Version History of a tip When I select any prior version Then I can preview and restore it in one action without code changes

Localization Coverage and Fallback

Given locales en-US and es-ES are required for a tip When I submit a Draft for review Then the schema validator enforces either localized strings for each key or an explicit fallback marker Given a user with locale de-DE When de-DE and de are not provided Then the system serves en-US per the configured fallback chain and records the fallback level in telemetry Given a locale ar-SA (RTL) When the tip is rendered Then layout direction, punctuation, and numerals follow locale rules and screenshots/examples swap direction where applicable Given a new translation is Published When client cache TTL expires or a purge is issued Then clients fetch the updated locale strings without an app rebuild and without visual flash of untranslated text

Contextual Targeting by Control, Category, Marketplace, and Proficiency

Given targeting rules {control:"Crop", category:"Apparel", marketplace:"Amazon", proficiency:"Novice"} When a Novice user opens the Crop control on an Apparel item configured for Amazon Then the targeted tip renders in the Style Coach within 200 ms of panel open Given multiple tips match the same context When priorities are defined Then the highest priority tip displays; when priorities tie Then the most specific rule (greatest attribute match count) wins deterministically Given no tip matches the context When the panel opens Then the control-level default tip displays if enabled, otherwise no tip renders and no empty container is shown

Feature Flags and Scheduled Rollouts

Given a tip group is gated by feature flag "stylecoach.tips.v2" When the flag is Off for a cohort Then members of that cohort do not receive v2 content Given a rollout schedule 10% at T0, 50% at T0+12h, 100% at T0+24h When time passes each threshold Then exposure adjusts automatically without deploy and the change is visible in audit logs Given an internal QA override is enabled When a user is in the QA cohort Then they receive 100% exposure regardless of global rollout settings Given a pause is invoked due to incident When the rollout is paused Then further exposure increases halt within 60 seconds and newly ineligible users revert to the previous config

A/B Testing Hooks and Stable Assignment

Given an experiment with variants A and B and experiment_id is defined When an eligible user first views the Style Coach in the targeted context Then the user is assigned a stable variant by (user_id, experiment_id) hashing for 30 days Given a tip impression, click, or dismiss occurs When the analytics event is emitted Then payload includes experiment_id, variant_id, tip_id, control, category, marketplace, proficiency, locale, and config_version Given hourly sample-ratio monitoring is active When absolute allocation imbalance exceeds 2 percentage points for >2 consecutive checks Then an alert is sent to the analytics channel with experiment metadata

Schema-Validated Cached Config with Health-Based Rollback

Given a config build completes When it is promoted to CDN Then it must pass JSON Schema vX validation and signature verification; otherwise the promotion fails and Last Good remains active Given a client launches offline When a Last Good config is cached Then guidance content loads from cache without errors and is marked as offline-source in telemetry Given a newly activated config correlates with >3% 5xx or client error rate increase over 5 minutes When the health check triggers Then an automatic rollback to Last Good is executed and a purge forces clients to revert within the cache TTL window Given a manual purge is requested When executed Then 95% of active clients fetch the new config within 10 minutes, confirmed by config_version in heartbeat events

Engagement Analytics and Outcome Attribution

Given a tip is displayed When the user views, clicks Learn More, hovers, or dismisses Then impression, click, hover_time_ms, and dismiss events are captured with session_id and tip_id Given the user adjusts the targeted control within 2 minutes of a tip impression When events are processed Then the adjustment is attributed to the tip with control_name and delta value recorded Given daily aggregation runs at 02:00 UTC When metrics are computed Then the dashboard surfaces tip-level CTR, average engagement time, and post-tip adoption rate by locale, marketplace, and proficiency with data freshness < 24h

Preview Grid

See instant before/after results across all five samples at once. Toggle elements (shadow, crop ratio, background tone, retouch strength) to compare variants side‑by‑side and lock choices faster—no tab hopping or reprocessing delays.

Requirements

Instant Multi-Sample Preview Grid Rendering

"As an online seller previewing my catalog, I want to see all five samples appear instantly in a grid so that I can evaluate options quickly without waiting or switching tabs."

Description

Render five sample images in a responsive grid with instant before/after visibility, using progressive preview generation and client-side GPU acceleration (WebGL/canvas) to achieve sub-200ms interaction latency. Provide skeleton loaders, lazy-loading for high-resolution frames, and caching to avoid reprocessing delays. Support synchronized zoom/pan, responsive breakpoints, and device memory safeguards to prevent crashes on large batches. Implement error and retry states per tile, plus observability (metrics and logs) for time-to-first-preview, FPS, and failure rates. Ensure parity with final server-rendered output via color profiles and consistent tone mapping, with graceful fallback to static previews when hardware acceleration is unavailable.

Acceptance Criteria

Five-Sample Responsive Grid with Before/After Toggle and Breakpoints

- Given the Preview Grid is opened with at least five uploaded samples, When the viewport width is >= 1200px, Then five tiles render in a single row with equal gutters and consistent aspect-fit, showing all five simultaneously. - Given the viewport width is 992–1199px, When the grid renders, Then five tiles are visible within two rows (columns 3+2) without horizontal scroll; gutters are 8–16px; tiles maintain aspect-fit. - Given the viewport width is 768–991px, When the grid renders, Then three columns are used and all five tiles are accessible via vertical scroll with no content overflow. - Given the viewport width is < 768px, When the grid renders, Then two columns are used and all per-tile controls remain accessible without overlapping content. - Given a user activates the global Before/After toggle, When toggled, Then all five tiles switch state in unison and each tile indicates the active state. - Given a user modifies shadow, crop ratio, background tone, or retouch strength, When applied, Then the same parameters are applied uniformly across all five visible tiles for side-by-side comparison. - Given keyboard navigation, When using Tab/Shift+Tab and Enter/Space, Then each tile’s controls (including Before/After) are focusable and operable with a visible focus indicator.

Progressive Previews with Skeletons, Lazy-Loading, and Caching

- Given a visible tile requests a preview, When loading starts, Then a skeleton loader appears within 100ms and persists until an image frame is displayed. - Given Good 4G network conditions (≈10 Mbps, RTT ≈150ms), When loading visible tiles, Then time-to-first-preview (low-res) per tile is <= 600ms at the 95th percentile. - Given high-resolution frames are available, When swapping from low-res to high-res, Then each visible tile completes the swap within 2.5s at P95 without layout shift (CLS <= 0.01 per tile). - Given tiles are outside the viewport, When the grid loads, Then high-res requests for those tiles are deferred until they are within 300px of the viewport edge. - Given network concurrency limits, When loading multiple tiles, Then no more than 6 image requests are in-flight concurrently. - Given a previously rendered style combination is requested again, When the tile renders, Then the preview is served from cache and displayed within 150ms at P95 without issuing a server request. - Given the device is offline and a cached preview exists, When the tile becomes visible, Then the cached preview is displayed; otherwise an offline placeholder is shown with no spinner.

Performance and Observability Under Load

- Given five tiles are visible, When the user performs a before/after toggle, a single style change, zoom, or pan, Then end-to-end visual response latency is <= 200ms at the 95th percentile on Desktop Baseline (8-core CPU, 8GB RAM, integrated GPU) and Mobile Baseline (A14-class or equivalent). - Given the user pans continuously for 3 seconds, When measuring frame cadence, Then average FPS is >= 45 and FPS does not drop below 30 for more than 200ms. - Given telemetry is enabled, When a session uses the Preview Grid, Then the client emits metrics: time_to_first_preview_ms, interaction_latency_ms, pan_fps_avg, preview_failure_rate, gpu_backend (WebGL/Canvas), each tagged with session_id, tile_id, and timestamps. - Given a preview failure occurs, When logging, Then a failure event is recorded with error_code and retry_count and is included in preview_failure_rate; sampling rate is 100% for this feature. - Given distributed tracing, When any tile loads, Then a trace_id is propagated across client logs and image requests to correlate timing.

GPU Acceleration with Graceful Fallback to Static Previews

- Given the browser supports WebGL2 or WebGL, When the grid initializes, Then GPU acceleration is used for compositing and tone operations and gpu_backend=WebGL is reported in diagnostics. - Given WebGL context creation fails or is lost, When rendering, Then the system automatically falls back to Canvas2D/WASM without a crash and displays a non-blocking notice that hardware acceleration is disabled. - Given a QA flag to force software mode, When enabled, Then rendered results match the GPU path within defined color parity thresholds and the UI remains fully operable. - Given hardware acceleration is unavailable and software cannot meet performance targets, When necessary, Then static server-generated previews are displayed while controls remain functional and the user is informed of the fallback.

Synchronized Zoom/Pan Across Grid

- Given any tile is focused or hovered, When the user zooms via Ctrl/scroll, pinch, or zoom controls, Then all five tiles synchronize to the same zoom level within one frame and maintain the same focal point within 1px. - Given the user pans by dragging within one tile, When the drag ends, Then all other tiles reflect the same relative pan offset simultaneously. - Given the user activates Reset View, When triggered, Then all tiles return to fit-to-frame within 100ms. - Given zoom constraints, When zooming, Then the supported zoom range is 100%–400% with smooth interpolation and no visible aliasing at 200% on 2x DPR displays.

Color and Tone Parity with Server Output

- Given a calibration set of images with server-rendered outputs, When the client renders previews, Then CIEDE2000 color difference per tile vs server output is median <= 1.0 and P95 <= 2.0 in sRGB. - Given tone mapping and gamma, When comparing luminance histograms, Then mean luminance delta is <= 2% and clipped pixel proportion differs by <= 0.5% vs server output. - Given input images contain sRGB or Display P3 profiles, When rendered, Then colors are correctly converted/managed such that the above parity thresholds are maintained. - Given the browser lacks color management, When detected, Then the system warns via a non-blocking toast and falls back to sRGB assumptions while maintaining P95 <= 3.0 DeltaE.

Resilience: Device Memory Safeguards and Per-Tile Error/Retry

- Given the device reports Device Memory <= 4 or a memory pressure signal is received, When rendering five tiles, Then concurrent decoded image buffers are limited to <= 3 tiles and peak JS heap <= 200MB and GPU textures <= 256MB as verified in performance profiling. - Given a memory pressure or WebGL out-of-memory event, When detected, Then the grid reduces preview resolution by one step and disables optional effects (e.g., soft shadows) and continues without a crash. - Given a tile fails due to network timeout or processing error, When the failure occurs, Then the tile shows an error state with message, error_code, and Retry action while other tiles remain interactive. - Given retry policy, When auto-retry triggers or the user taps Retry, Then exponential backoff is applied (e.g., 1s, 3s) with a maximum of 2 automatic retries and 1 manual retry; on success the tile returns to normal. - Given requests are superseded by new style changes, When cancellation occurs, Then the previous request is aborted and no stale frames replace newer ones (no flashback).

Real-time Variant Toggles (Shadow, Crop Ratio, Background Tone, Retouch Strength)

"As a boutique owner refining my product photos, I want to toggle styling controls and see instant updates so that I can compare variants side-by-side and decide faster."

Description

Provide interactive controls that update previews in real time without a server round-trip: shadow on/off and intensity, selectable crop ratios (e.g., 1:1, 4:5, 3:2) with safe-zone guides, background tone palette/slider including brand presets, and retouch strength levels with live approximations. Support per-sample overrides and a global apply mode with clear UI state. Use worker threads for image operations to keep the UI responsive and reconcile client approximations with server-quality renders in the background to guarantee visual consistency. Persist chosen values in session state and prefill from the last-used brand preset.

Acceptance Criteria

Instant Shadow Toggle and Before/After in Preview Grid

Given the Preview Grid shows five sample images with shadow controls and Before/After mode available When the user toggles Shadow On or Off Then all five previews reflect the new shadow state within 150 ms without a loading indicator And no synchronous network request is made and the UI remains interactive (pointer latency ≤ 50 ms) And the Shadow Intensity slider is enabled only when Shadow is On Given Shadow is On and the user drags the Shadow Intensity slider When the slider value changes Then previews update continuously at least every 100 ms and land on the exact final value on release And the chosen intensity value is persisted in session state Given the user activates Before/After mode When any toggle is changed Then each of the five tiles displays synchronized Before and After states for the current image without reprocessing delay

Crop Ratios with Safe-Zone Guides Across Samples

Given crop ratio options 1:1, 4:5, and 3:2 are visible When the user selects a ratio Then safe-zone guides render on all five previews within 100 ms and the crop overlays reflect the selected ratio exactly And panning/zooming within the crop remains ≥ 55 fps And the selected ratio is saved per-sample and (if Global Apply is active) as a global value Given Global Apply mode is active When the user changes crop ratio Then all samples without overrides adopt the new ratio, and overridden samples remain unchanged and are visibly marked as locked

Background Tone Palette and Brand Preset Application

Given the background control shows a tone palette, a numeric slider, and brand presets When the user selects a brand preset Then all five previews update within 150 ms to the preset tone and the preset is highlighted as selected And the applied tone matches the preset target within ΔE00 ≤ 2 And the choice is persisted in session state Given the user adjusts the tone slider When the slider is moved Then the preview updates continuously without visible banding And the numeric value is displayed and copyable Given Global Apply is Off When a tone change is made Then only the active sample updates

Retouch Strength Live Approximation and Background Reconciliation

Given retouch strength control with levels 0–100 is visible When the user sets a new value Then the local preview updates within 200 ms using a client-side approximation And when the background server-quality render completes, SSIM ≥ 0.98 and ΔE00 ≤ 2 between local preview and final within the product region And the swap to server-quality occurs without flicker and with layout shift ≤ 1 px And the retouch value persists in session and restores on reload

Per-Sample Overrides vs Global Apply with Clear UI State

Given a Global Apply toggle is visible and Off by default When Global Apply is turned On Then subsequent control changes apply to all samples except those with per-sample overrides And overridden samples display a lock icon and tooltip "Override active" And a "Reset to Global" action is available on overridden samples Given a sample has an override When the user clicks "Reset to Global" Then the sample adopts the current global values and the override indicator is removed Given global values change Then overridden samples remain unchanged

Worker Threads Keep UI Responsive During Image Operations

Given the app is processing 5× 2048 px previews on a device with ≥ 4 logical cores When the user rapidly toggles controls and drags sliders for 10 seconds Then the main thread frame rate remains ≥ 55 fps and input latency ≤ 50 ms And image processing executes in worker threads with no single main-thread long task ≥ 50 ms aside from painting And no "Unresponsive" browser prompt appears Given network latency is 200–400 ms and background reconciliation is active Then preview updates are never blocked by network and no spinner is shown for local updates

Session Persistence and Last-Used Brand Preset Prefill

Given the user sets values for shadow, crop ratio, background tone, and retouch strength When the user navigates away and returns within the same session Then the same values are restored for each sample and the global state Given a new batch is started without selecting a preset When the editor loads Then controls prefill from the last-used brand preset for the account And the preset name is displayed as selected And users can override any control per-sample or globally

Synchronized Before/After Comparison & Grid Controls

"As a power user comparing edits, I want synchronized before/after controls across the grid so that I can spot differences quickly without repeating the same actions on each image."

Description

Enable per-tile and global comparison modes, including a before/after flip, a draggable split slider, and synchronized zoom/pan across selected tiles. Provide reset-to-default and quick-compare (press-and-hold) interactions. Maintain consistent overlays (crop guides, safe zones) in both before and after states. Ensure keyboard and pointer parity for all compare actions and maintain performance targets under 60 FPS on supported hardware.

Acceptance Criteria

Per‑Tile and Global Compare Scoping

Given five preview tiles are visible and at least one tile is selected When the user switches scope to Global compare Then any compare action (flip, split slider, zoom, pan) applies simultaneously to all selected tiles, and non-selected tiles are unaffected And a scope indicator displays "Global" and the count of affected tiles equals the number of selected tiles When the user switches to Per‑Tile scope and focuses a tile Then compare actions affect only that focused tile and other tiles remain unchanged And switching scopes does not modify underlying image adjustments or style presets

Synchronized Zoom/Pan Across Selected Tiles

Given two or more tiles are selected and Global scope is active When the user zooms via mouse wheel, trackpad pinch, or keyboard +/− Then all selected tiles adjust zoom by the same factor within ±1% tolerance and maintain the same focal point When the user pans by dragging or using arrow keys Then all selected tiles pan by the same pixel offset within ±1 px, clamped to image bounds; non-selected tiles do not move And continuous zoom/pan interactions render at an average ≥60 FPS (p95 ≥50 FPS) on supported hardware

Before/After Comparison Modes (Flip and Split)

Given compare mode is Flip When the user toggles Before/After via the toolbar control or its keyboard shortcut Then the image state switches instantly between Before and After with toggle latency <50 ms and no reprocessing delay Given compare mode is Split When the user drags the split handle within a tile Then the handle moves smoothly and reveals Before on one side and After on the other, with the handle position persisted per tile in Per‑Tile scope and shared in Global scope And the handle snaps at 0%, 50%, and 100% when within 8 px proximity And split interactions render at ≥60 FPS average on supported hardware

Quick‑Compare Press‑and‑Hold

Given the After state is visible When the user press‑and‑holds the Quick Compare control (pointer down on the compare button or holding the assigned keyboard key) Then the affected tile(s) temporarily switch to the Before state for the duration of the hold and revert to the previous state within 50 ms of release And in Global scope only selected tiles are affected; in Per‑Tile scope only the focused tile is affected And Quick Compare uses no transitional animations; overlays remain visible and unchanged

Reset Compare Controls to Defaults

Given any non‑default compare settings are active (e.g., zoom not fit‑to‑tile, non‑zero pan, split mode on, flip active) When the user activates Reset Compare Then all tiles return to defaults: After state, Fit‑to‑Tile zoom, centered pan, Split mode off, Flip mode off, split handle hidden, overlays on, scope unchanged And the reset completes within 100 ms and produces no change to image edits or style presets

Keyboard and Pointer Parity for Compare Actions

Given the application window has focus When a user performs any compare action with a pointer (zoom, pan, flip, split slider, quick‑compare, reset) Then an equivalent keyboard interaction exists and is accessible via documented shortcuts And all compare controls are reachable by Tab order, show a visible focus indicator, and can be activated via Enter/Space as applicable And no compare functionality is pointer‑only; automated tests verify keyboard parity for each action

Overlay Consistency Across States and Compare Modes

Given crop guides and safe‑zone overlays are enabled When the user flips Before/After, uses the split slider, or performs zoom/pan in any scope Then overlay position, size, and opacity remain constant relative to the image content (alignment error ≤1 px at 100% zoom or ≤0.5% of tile dimension at other zoom levels) And overlays render above imagery in both states without flicker or duplication and never lag behind image transforms by more than one frame

Variant Pinning and Choice Locking

"As a seller narrowing options, I want to pin the best-looking variant so that I don’t lose it while testing other adjustments."

Description

Allow users to pin a preferred variant in any tile, freezing its settings and visual state while continuing to experiment with others. Indicate pinned status visually and prevent accidental overrides until explicitly unlocked. Support naming or tagging the locked choice and persisting it when navigating between pages or sessions. Expose a concise summary of locked parameters for auditability.

Acceptance Criteria

Pin Variant in Tile and Freeze State

Given the Preview Grid is loaded with at least five sample tiles and each tile has multiple generated variants When the user pins any variant within a tile via the pin control or context menu action Then the selected tile’s current image and parameter values (shadow, crop ratio, background tone, retouch strength, preset) are snapshotted and frozen And subsequent adjustments to any global toggle or preset do not alter the pinned tile’s visual output or stored parameters And the pin action completes within 300 ms from user input And any number of tiles can be pinned simultaneously without error

Pinned Status Indicator and Accessibility

Given a variant is pinned in a tile Then the tile displays a lock icon overlay and a distinct border style indicating pinned status And a tooltip labeled "Pinned" appears on hover or focus of the tile And the pinned indicator has a minimum 4.5:1 contrast ratio against the image/background And assistive technologies announce the state change via an ARIA label/state (e.g., aria-pressed or aria-selected equivalent) as "Pinned" And the indicator remains visible and accurate after grid refreshes, scrolling, or viewport resize

Prevent Overrides and Respect Pins in Batch Operations

Given one or more tiles are pinned When the user attempts to modify a pinned tile’s parameters (e.g., change retouch strength, crop ratio) via per-tile controls Then the controls are disabled or the change is blocked for the pinned tile, and no parameter value is altered And a non-blocking toast appears within 500 ms stating the action was skipped due to a pin, with a direct "Unlock" action When the user applies a batch preset/reset to all tiles Then pinned tiles are excluded from the operation and a summary toast reports "Skipped N pinned tiles" with accurate count And no reprocessing is triggered for pinned tiles during batch actions

Name/Tag Locked Choice and Edit Constraints

Given a tile is pinned When the user adds or edits a tag for the pinned choice Then the input accepts 1–32 characters consisting of letters, numbers, spaces, hyphens, and underscores only And invalid characters are rejected with inline validation messaging within 200 ms And the tag is saved automatically within 300 ms of input blur or Enter And the tag is rendered on the tile and in details view without truncation up to 32 chars (ellipsis beyond) And removing a tag leaves the pin intact

Persistence Across Navigation and Sessions

Given one or more tiles are pinned (with optional tags) When the user navigates to another page within the app and returns to the Preview Grid, or refreshes the browser Then all pinned states, frozen images, and tags are restored exactly as saved When the user signs out and signs back in on the same account within 30 days Then all pinned states, frozen images, parameter snapshots, and tags persist for the associated catalog/batch And pinned state restoration for grids up to 100 tiles completes within 1 second on a typical broadband connection

Locked Parameters Summary for Auditability

Given a tile is pinned When the user opens the details/summary for the pinned tile Then the UI displays the exact frozen parameter values: shadow (on/off), crop ratio (numeric), background tone (code/name), retouch strength (0–100), and applied preset (name/version) And the summary includes timestamp of pin and user identifier And the values match the underlying stored snapshot with no rounding beyond one decimal place for numeric sliders And the user can copy the summary to clipboard in a single action

Explicit Unlock Flow, Confirmation, and Undo/Redo

Given a tile is pinned When the user selects Unlock via the lock control or context menu Then a confirmation appears once per session (until "Don’t ask again" is checked) and, upon confirm, the tile is unlocked within 300 ms And after unlocking, subsequent global or per-tile changes apply normally to that tile When the user performs Undo after an unlock action Then the tile returns to the pinned state with the original frozen image and parameters restored And Redo reapplies the unlock state

Batch Apply Selected Settings to Full Upload

"As a store owner, I want to apply my chosen look to all product photos at once so that I can finish edits quickly and keep my brand consistent."

Description

Provide a one-click action to apply the currently selected settings (or pinned variant parameters) to the entire batch or a selected subset. Validate conflicts (e.g., incompatible crop ratio for certain SKUs) and show an impact summary before committing. On confirm, update the processing job configuration, enqueue reprocessing, and display progress with the ability to cancel or revert. Ensure idempotency and record the chosen settings as a reusable style preset.

Acceptance Criteria

Apply Selected Settings to Entire Batch with Impact Summary

Given the user has selected settings or pinned variant parameters in the Preview Grid And a batch of N images is available When the user clicks "Apply to All" Then an impact summary modal is displayed containing: total_selected=N, compatible_count, conflict_count grouped by reason, parameter_deltas, estimated_duration_range, and estimated_storage_delta And the Confirm button remains disabled until the summary renders with all counts When the user confirms Then the processing job configuration is updated atomically with a new version number And one reprocessing job with a unique job_id is enqueued And a progress panel appears showing states (Queued, Processing, Finalizing) with item-level counts updating at least every 5 seconds

Apply Settings to Filtered Subset or Manual Selection

Given the user has filtered the grid or manually multi-selected K items (K ≥ 1) When the user clicks "Apply to Selection" Then the impact summary reflects total_selected=K and excludes unselected items And only the selected items are included in the updated job configuration And non-selected items remain unchanged after processing completes

Conflict Detection and Resolution for Incompatible Crop Ratios

Given one or more items are incompatible with the selected crop ratio or min-dimension requirements When conflicts are detected during pre-commit validation Then the impact summary lists conflict_count with reason codes (e.g., AR_LOCKED, MIN_DIM) and example SKUs And the user can choose a resolution policy: (a) Skip conflicted items [default], (b) Auto Adjust per SKU rule, or (c) Use Original crop And changing the policy updates the counts in the summary before confirmation When the user confirms Then the chosen policy is applied consistently, and each conflicted item receives a logged resolution outcome

Idempotency and Concurrency Control

Given the user triggers "Apply" and the client retries or the user clicks again within 60 seconds When duplicate requests with the same settings hash are received Then the backend returns the same job_id and does not enqueue duplicate jobs And the UI deduplicates and shows a single progress panel for that job When two different clients attempt to apply changes to the same batch concurrently Then optimistic concurrency prevents a stale write, and the second request receives a 409 with the latest config version to review

Cancel and Revert Reprocessing

Given a reprocessing job is in progress When the user clicks Cancel Then the job is aborted and no additional items are updated And if any items were already updated, a Revert option is presented When the user clicks Revert within 24 hours of the job start Then all affected items and configuration are restored to the previous version within 5 minutes for batches up to 1,000 images And an audit log records cancel/revert actions with timestamps and actor

Save Chosen Settings as Reusable Style Preset

Given the user confirms applying selected settings Then those parameters (background tone, shadow, crop ratio, retouch strength, pinned variant parameters) are saved as a new preset with a generated default name and optional user override And the preset appears in the user's preset library within 5 seconds And presets are immutable and versioned; editing creates a new version When the user applies this preset to a future batch Then the settings populate instantly and can be batch-applied using the same flow

Non-Destructive Versioning & Undo History

"As a user experimenting with styles, I want non-destructive history so that I can safely explore options and roll back if needed."

Description

Track all preview-grid changes as non-destructive versions per asset, enabling undo/redo and revert-to-original without data loss. Store lightweight diffs and parameter sets rather than duplicating full images. Persist session state to recover work after refresh or reconnect, and allow exporting/importing the parameter set for reuse across projects.

Acceptance Criteria

Undo/Redo of Preview Grid Parameter Changes

- Given an asset open in Preview Grid with five samples visible, when the user changes any parameter (shadow, crop ratio, background tone, retouch strength) on any sample, then a new undo entry is recorded with parameter name, old value, new value, sampleId, assetId, timestamp, and userId. - Given there are N undo entries, when the user invokes Undo stepwise, then the preview updates to each prior state in order, with visual update latency ≤ 300 ms per step if cached or ≤ 1000 ms per step if recomposition is required, and no image data is duplicated. - Given the user has undone M steps, when Redo is invoked M times, then the resulting render is visually equivalent to the pre-undo state (SSIM ≥ 0.99, ΔE2000 ≤ 2.0) and the parameter sets are identical to their recorded values.

Revert to Original Without Data Loss

- Given an asset with one or more saved versions, when the user selects Revert to Original, then the original image and default parameters are restored while preserving the ability to Undo back to the previous state. - Given a revert operation, when the change is persisted, then no full-resolution image blob is duplicated and the storage delta for the new version record is ≤ 5 KB (parameters + metadata only). - Given the asset is reverted, when the user exports the current parameter set, then the export clearly indicates it is the "original" baseline (versionId, schemaVersion, createdAt) and contains no derived adjustments.

Session Persistence After Refresh/Reconnect

- Given an active editing session on an asset in the Preview Grid, when the browser is refreshed or the network disconnects and reconnects within 24 hours, then the last active version, full undo/redo stack, selected sample, and parameter values are restored automatically upon project reload. - Given any parameter change, when 2 seconds of user inactivity elapse, then the session state is autosaved to durable storage and survives process restarts. - Given the client was offline when changes were made, when connectivity is restored, then the queued diffs are synced exactly once in causal order with no lost or duplicated version entries.

Lightweight Diff Storage and Reconstruction Fidelity

- Given versioning uses parameter sets and lightweight diffs, when reconstructing any prior version from the original image, then the rendered output matches a fresh application of the same parameters with SSIM ≥ 0.99 and ΔE2000 ≤ 2.0 across the full image. - Given a sequence of K parameter changes, when K versions are saved, then total additional storage consumed is ≤ 5 KB × K and at most one original image blob exists for the asset. - Given a version record, when inspected, then it includes parentVersionId, schemaVersion, parameterSetHash, createdAt, and userId fields for auditability.

Export/Import Parameter Set Across Projects

- Given an asset version is active, when the user selects Export Parameters, then a portable JSON (≤ 10 KB) is downloaded containing schemaVersion, parameterSet, seed/randomness controls, and a checksum. - Given a valid exported file, when Import Parameters is used in a different project and asset, then the parameters apply successfully and the resulting render is visually equivalent to the source (SSIM ≥ 0.99, ΔE2000 ≤ 2.0). - Given an export with an unsupported schemaVersion, when import is attempted, then the user receives a clear, actionable message and the import is blocked without mutating the current asset.

Version Timeline Visibility and Selection in Preview Grid

- Given an asset is open, when the user opens the Versions panel, then a chronological list of versions is shown with versionId, createdAt, author, and a compact diff summary (changed parameters) for each entry. - Given a version is selected in the panel, when applied, then all five samples update consistently to reflect that version’s parameter set within 500 ms and the selection is reflected in the undo/redo stack. - Given multiple versions exist, when hovering a version, then a quick preview renders without committing, and dismissing hover leaves the current state unchanged.

Accessibility & Keyboard-First Navigation

"As a keyboard and screen-reader user, I want complete access to preview and compare controls so that I can efficiently make decisions without a mouse."

Description

Implement full keyboard navigation of the grid and controls with logical tab order, focus indicators, and shortcuts for common actions (toggle before/after, adjust retouch strength, cycle crop ratios, pin/unpin). Provide ARIA roles, labels, and live region announcements for state changes (e.g., variant pinned, batch apply started). Ensure color-contrast and screen-reader compatibility for overlays and sliders, with motion-reduction options for users sensitive to animations.

Acceptance Criteria

Keyboard-Only Grid Navigation and Logical Tab Order

- Given the Preview Grid is loaded, When the user presses Tab from the page start, Then focus moves in this order: top action bar → grid view controls → grid tiles (left-to-right, top-to-bottom) → details panel controls (if present) → footer actions, with no dead-ends or skipped interactive elements. - Given focus is on a grid tile, When the user presses Arrow Up/Down/Left/Right, Then focus moves to the adjacent tile and a screen reader announces "Tile X of Y" for the newly focused tile. - Given any modal or overlay opens, When it appears, Then focus moves to the modal's first focusable element, is trapped within until closed, and returns to the triggering control on close. - Given a control becomes disabled or hidden, When tabbing, Then it is removed from the tab sequence and skipped. - Given the grid re-renders (e.g., after applying a crop), When the previously focused element no longer exists, Then focus is set to the nearest relevant element (same tile index or parent group) without dropping to the document body.

Visible Focus Indicators on All Interactive Elements

- Given any interactive element is focused via keyboard, Then a 2px focus indicator with at least 3:1 contrast against adjacent colors is clearly visible and not clipped by container overflow. - Given focus is on an image tile, Then a focus ring or overlay ensures 3:1 contrast regardless of the image content beneath. - Given the app is in light or dark theme, Then the focus indicator maintains the 3:1 contrast requirement in both themes. - Given the browser zoom is set to 200%, Then the focus indicator remains at an effective thickness of ≥2px and fully visible around the element.

Shortcut Keys for Toggle, Pin, Retouch, and Crop Ratio

- Given a grid tile is focused and no text input is active, When the user presses B, Then the tile toggles Before/After preview and an aria-live polite message announces "Before view" or "After view". - Given a grid tile is focused, When the user presses P, Then the variant is pinned/unpinned within 100 ms, the pin icon reflects the state, and aria-live announces "Pinned" or "Unpinned". - Given retouch strength is adjustable for the focused tile, When the user presses ] or [, Then the value increases/decreases by 5 within bounds 0–100, the numeric value updates, aria-valuenow matches the value, and holding the key repeats at ~5 steps/second. - Given multiple crop ratios exist (e.g., 1:1, 4:5, 16:9), When the user presses C, Then the next ratio is applied; When Shift+C is pressed, Then the previous ratio is applied; aria-live announces the new ratio label. - Given focus is inside a text input or while dragging a slider, When shortcut keys are pressed, Then no shortcut action is triggered to avoid conflicts.

ARIA Roles, Labels, and Live Announcements for State Changes

- Given interactive components are rendered, Then tiles expose role="group" or role="button" as appropriate with accessible names (e.g., "Sample 3"), buttons have aria-labels or visible labels, and toggleable controls use aria-pressed to reflect state. - Given sliders are present, Then each uses role="slider" with aria-label or aria-labelledby and correct aria-valuemin, aria-valuemax, and aria-valuenow reflecting the current value. - Given state changes occur (pin/unpin, before/after toggled, crop ratio changed, batch apply started/completed/failed), Then a single aria-live="polite" (or role="status") region announces a concise, non-duplicated message within 500 ms (e.g., "Pinned sample 2", "Batch apply started for 5 items", "Batch apply complete: 5 succeeded, 0 failed"). - Given page structure is defined, Then landmark roles (header, main, complementary, contentinfo) are present for efficient screen reader navigation.

Screen Reader Operability of Sliders and Modals

- Given the retouch strength slider has focus, When Arrow Left/Right (or Up/Down) are pressed, Then the value changes by 1; When PageUp/PageDown are pressed, Then the value changes by 10; When Home/End are pressed, Then the value jumps to min/max; each change is announced as a percentage. - Given any slider change occurs via keyboard or mouse, Then aria-valuenow updates immediately and the visible numeric value stays in sync. - Given a modal or side panel opens, Then it has aria-modal="true", is labelled by an element referenced via aria-labelledby, provides an accessible description if needed via aria-describedby, and pressing Escape closes it. - Given a modal closes, Then focus returns to the element that opened it.

Motion Reduction Preference and In-App Toggle

- Given the user has OS/browser prefers-reduced-motion enabled, Then non-essential animations (transitions, parallax, wipes) are disabled (0 ms) and essential feedback animations are reduced to ≤100 ms fade with no motion. - Given the user toggles "Reduce animations" in app settings, Then the preference takes effect immediately across the grid and controls, persists across sessions, and overrides default motion settings. - Given before/after comparisons are shown, Then with motion reduction enabled they switch instantly with no sliding wipe effects.

Overlay and Control Color Contrast on Image Tiles

- Given text and icons appear over images, Then all text meets WCAG AA contrast ≥4.5:1 and UI components (icons, controls, focus rings) meet ≥3:1 against their immediate background, achieved via dynamic scrims or alternative styling as needed. - Given hover, active, and focus states of controls, Then the contrast ratios remain at or above their respective thresholds. - Given the interface is zoomed to 200% and in both light and dark themes, Then the stated contrast ratios are maintained.

Consistency Meter

Real‑time score that measures uniformity across your sample set and predicts how well the preset will generalize to the rest of your catalog. Flags outliers and offers quick fixes (e.g., adjust crop margin by 2%) to secure a cohesive, brand‑true finish.

Requirements

Real-time Uniformity Scoring Engine

"As an online seller, I want a real-time consistency score while configuring my preset so that I can quickly see whether my catalog will look cohesive before I process the full batch."

Description

Implements a streaming analyzer that computes a 0–100 Consistency Score and per-metric sub-scores (e.g., crop margin, subject centering, aspect ratio, background uniformity, exposure, white balance, shadow hardness, color cast, edge cleanliness, resolution consistency, compression artifacts, and style similarity to the selected preset). Scores update instantly as users upload samples, tweak preset parameters, or change the sample set. Reuses shared image features from PixelLift’s preprocessing to minimize recomputation, exposes an event bus for UI updates, and supports idempotent rescoring on partial batches. Allows brand-specific thresholds and weighting profiles, and handles missing or corrupted images gracefully.

Acceptance Criteria

Real-time Score Update and Event Publication

Given a project with Consistency Meter visible and an active sample set When (a) an image upload completes and preprocessing finishes, (b) a preset parameter is changed, or (c) an image is added or removed from the sample set Then the overall Consistency Score (0–100, integer) and all per‑metric sub‑scores are recalculated and published on the scoring event bus within 300 ms of the triggering change And Then the published message includes: projectId, sampleSetVersion (monotonic), changeType ∈ {uploadComplete, presetChanged, sampleSetChanged}, overallScore, subScores[{metricId, value 0–100, unit}], timestamp (ISO‑8601), dedupKey And Then events for a given project are delivered in ascending sampleSetVersion order to subscribed clients

Comprehensive Per‑Metric Sub‑Scores and Overall Calculation

Given any scoring run Then sub‑scores are produced for each metric: crop margin, subject centering, aspect ratio, background uniformity, exposure, white balance, shadow hardness, color cast, edge cleanliness, resolution consistency, compression artifacts, style similarity to the selected preset And Then each sub‑score is an integer in [0,100], where 100 = perfect adherence to the preset/brand target And Then the overall Consistency Score equals the weighted arithmetic mean of the sub‑scores using the active weighting profile; difference between published and recomputed overall score ≤ 0.5 points And Then with identical inputs, repeated runs produce identical sub‑scores and overall score

Feature Reuse and Incremental Scoring Efficiency

Given N images with cached preprocessing features When only preset weights or thresholds change Then zero image features are recomputed and only aggregation runs; end‑to‑end score update latency ≤ 150 ms for N ≤ 200 on reference hardware When exactly k images in the sample set change content or features (k ≤ N) Then only those k images are rescored; total recomputed images = k; cache hit rate for unaffected images ≥ 90% And Then average CPU time for rescoring after weight‑only changes is ≤ 20% of a cold scoring run baseline for the same N

Idempotent Rescoring on Partial Batches

Given a partial batch upload where some images are pending, retried, or duplicated by the client When a rescoring request with the same inputs (projectId, sampleSetVersion, changeSet hash) is processed multiple times Then the engine produces identical overall and sub‑scores, emits the same dedupKey, and increments sampleSetVersion at most once And Then a rescoring trigger that results in no score changes produces no new event and no version increment

Brand Thresholds and Weighting Profiles

Given Brand A and Brand B with distinct thresholds and weighting profiles applied to the same sample set When scoring is executed under each brand profile Then sub‑scores and the overall score reflect the respective weights and thresholds, and the published overall score difference matches the recomputed difference within 0.5 points And Then when no brand profile is specified, the system applies the default profile and records profileId in the event payload And Then updating a brand profile’s weights takes effect on the next scoring and is published within 300 ms of the change

Outlier Flagging with Actionable Quick Fixes

Given active brand thresholds for each metric When an image’s metric deviates beyond its threshold by Δ Then the image is flagged as an outlier for that metric and the deviation amount and direction are included in the result payload And Then the engine provides at least one quick‑fix suggestion containing: parameterName, suggestedDelta within allowed range (e.g., cropMargin:+2%), and expected score improvement (Δscore) And Then applying the suggestion via API triggers rescoring and increases the targeted metric sub‑score by ≥ 80% of the predicted Δscore on a controlled test set

Graceful Handling of Missing or Corrupted Images

Given an input sample set containing missing or corrupted images When scoring runs Then affected images are skipped, marked with errorCode ∈ {MissingImage, CorruptImage, UnsupportedFormat, Timeout}, and the remaining images continue processing And Then the overall score is computed using only successfully processed images and includes completenessRatio = processedCount/totalCount in the event payload And Then the API returns a multi‑status result (e.g., 207) or equivalent, and no unhandled exceptions or crashes occur

Preset Generalization Predictor

"As a boutique owner, I want the meter to predict how well my chosen preset will generalize to the rest of my catalog so that I can avoid rework and ensure brand consistency across new uploads."

Description

Forecasts how a chosen style preset will perform on the remainder of the catalog by modeling variance in the sample set, product category metadata, and historical outcomes. Produces confidence bands (e.g., high/medium/low) and expected failure modes (e.g., dark fabrics underexposed, reflective items with harsh shadows). Requires a minimum diverse sample size, highlights underrepresented categories, and suggests additional samples to improve prediction quality. Integrates with the scoring engine to run quick what‑if simulations as the user adjusts preset parameters.

Acceptance Criteria

Real‑time Confidence Band Display

- Given a sample set that meets the minimum diversity threshold, when a user selects a style preset, then the predictor outputs a numeric confidence score (0–100) and a band mapped as: High ≥ 80; Medium 50–79; Low < 50. - When the user changes any preset parameter, the confidence score and band refresh within 700 ms for sample sets ≤ 500 images and within 1.5 s for ≤ 2,000 images. - The displayed score and band remain consistent after page refresh and when re-opening the project (persisted in project state). - The confidence band tooltip lists contributing factors including sample variance, category coverage, and historical performance weights.

Expected Failure Modes Enumeration

- When predicting, the system returns at least the top 3 expected failure modes with human-readable labels and example thumbnails sourced from the sample. - Each failure mode includes an estimated prevalence percentage (0–100%) and severity levels mapped as: High ≥ 70th percentile severity, Medium 40–69th, Low < 40th. - For each failure mode, at least one auto-fix suggestion is provided (e.g., exposure +0.2 EV, crop margin +2%) and is previewable on click. - On a labeled holdout set (n ≥ 200), ≥ 70% of predicted failure modes correspond to observed issues after applying the preset. - Failure modes and metadata are available via API at GET /v1/predictions/{id}.

Minimum Diverse Sample Size Enforcement

- The predictor requires a minimum of 24 images spanning ≥ 3 product categories with no single category > 60% of the sample; thresholds are configurable per workspace. - If the minimum is not met, the Predict action is disabled and an inline message lists unmet conditions and the exact additional images required per category. - The system suggests up to 3 categories to add with required counts and provides a CTA to upload or select from catalog. - Once requirements are satisfied, the Predict action enables without manual refresh, and the first prediction completes within 1 s for ≤ 500 images.

Underrepresented Category Highlighting and Sample Suggestions

- Category coverage is computed as sample share divided by catalog share; categories with coverage index < 0.5 are flagged as underrepresented. - Underrepresented categories are shown in the UI with a badge and a recommendation "Add N images" where N is computed to reach coverage index ≥ 0.8. - Clicking the recommendation opens the uploader pre-filtered to the category; after adding images, coverage recalculates and flags clear within 1 s. - A downloadable CSV report lists categories, coverage index, required N, and current counts.

What‑If Simulation Integration

- When a user adjusts a preset parameter (e.g., crop margin +2%, exposure +0.2 EV), a what‑if simulation runs and returns updated confidence score, band, and Consistency Meter delta (± points) within 800 ms for ≤ 500 images. - A side‑by‑side comparison view shows baseline vs simulated metrics and the top 5 images with greatest predicted change. - Toggling off the simulation or clicking Reset restores baseline metrics instantly (<150 ms) with no state persisted. - No database writes occur until the user clicks Apply; event logs include parameter changes and deltas.

Outlier Detection and Quick Fixes

- Outliers are defined as images with predicted post‑process quality > 2.0 standard deviations below the sample mean or in the lowest 10th percentile; the system lists count and thumbnails. - Each outlier includes at least one quick fix with estimated impact (predicted score change) and a one‑click preview. - Batch apply is available for outliers sharing feature similarity cosine ≥ 0.8; processing completes within 2 s for up to 100 images. - After applying a quick fix (preview or batch), the predictor recalculates metrics for affected images and updates the overall confidence score within 700 ms.

Outlier Detection & Smart Suggestions

"As a product photographer, I want outliers flagged with specific, actionable suggestions so that I can fix the few problem images without manually hunting for them."

Description

Identifies per-metric outliers within the sample set using robust statistics and learned thresholds, visually flags them, and generates targeted, parameter-level suggestions (e.g., increase crop margin by 2%, shift white balance +250K, reduce shadow intensity by 10%). Quantifies expected score lift for each suggestion and allows users to apply fixes per-image or across the preset. Ensures suggestions remain within brand guardrails and clearly label any trade-offs.

Acceptance Criteria

Detect Per‑Metric Outliers in Sample Set

- Given a labeled sample set (>=30 images) with known per-metric outliers (crop margin, white balance, shadow intensity), when the Consistency Meter runs, then the system flags outliers per metric on image tiles and lists them in the Outliers panel. - Then per-metric detection achieves >=90% precision and >=85% recall versus ground truth on the set. - Then thresholds are computed via robust statistics (median + k*MAD) combined with learned per-metric offsets, and the effective threshold value is shown in a tooltip. - Then each flag stores metric name, measured value, deviation in MAD units, and timestamp for auditability.

Visual Flagging and Drill‑Down

- Given flagged images, when a user hovers a flag, then a tooltip shows: metric, image value, sample median, deviation (MAD units). - When the user clicks a flag, then a side panel opens with a histogram of the sample distribution and the image’s position highlighted. - Then flag icons render within 500 ms after analysis completion for a 100-image sample set. - Then each flag control has an accessible aria-label: "Outlier: {metric}" and is keyboard focusable.

Generate Parameter‑Level Smart Suggestions

- For each flagged metric, the system generates 1–3 parameter-level suggestions with explicit numeric adjustments (e.g., crop margin +2%, white balance +250K, shadow intensity −10%). - Each suggestion displays an expected Consistency score lift (+X points) with an 80% confidence interval and a model confidence score (0–1). - Suggestions that would violate brand guardrails are not shown; instead, a note states "Blocked by guardrail" with the specific rule. - Each suggestion lists any trade-offs (e.g., "May reduce naturalness by 1–2 pts") next to the lift value. - Numeric adjustments respect per-metric step sizes (crop: 0.5%, WB: 50K, shadows: 1%) and rounding rules.

Apply Fixes Per‑Image and Across Preset

- Given a flagged image, when the user clicks "Apply fix" on a suggestion, then only that image is re-rendered with the adjustment and its Consistency score is recalculated. - When the user selects "Apply to preset", then the preset parameter updates and all images in the sample set re-evaluate; for 100 images, updated flags and scores appear within 3 seconds. - Batch apply provides an Include/Exclude filter defaulted to images matching the outlier condition; changes affect only the filtered set. - All apply actions are undoable in one step; selecting Undo restores the prior preset and image states with matching scores. - Partial failures surface an error list with retry for failed images; successful applies remain intact.

Expected Score Lift Calculation Validity

- Given a held-out validation subset (>=50 images), when applying the top suggestion in dry-run evaluation, then predicted lift is within ±2 Consistency points of realized lift for >=80% of images. - When two suggestions are stacked, then cumulative lift prediction error is <=30% relative for >=70% of cases. - If model confidence <0.5, then expected lift displays "N/A" and the suggestion is tagged Low Confidence. - The lift detail panel shows model version and validation dataset timestamp.

Brand Guardrails Enforcement

- Suggestions never propose values outside brand guardrails defined in the active brand profile; attempts are blocked with the message: "Blocked by guardrail: {rule}". - Guardrails are enforced for both per-image and preset-level applies, including batch operations. - Overrides require a user with the "Brand Admin" role; otherwise the override control is disabled. - All blocked or overridden actions are logged with user, rule, old/new values, and timestamp in the audit trail.

One-click Auto-tune Preset

"As a time-pressed seller, I want one-click fixes that auto-tune the preset based on the meter’s guidance so that I can lock in a cohesive look with minimal effort."

Description

Applies selected meter suggestions to the active preset in a single action, creates a versioned draft, updates previews, and triggers automatic rescoring. Supports scoped application (entire batch, subset, or single image), instant undo, and side-by-side before/after comparison. Enforces safe bounds, respects locked brand settings, and writes an audit trail of parameter changes to support review and rollback.

Acceptance Criteria

One‑Click Apply Selected Meter Suggestions

Given an active preset with one or more Consistency Meter suggestions visible and at least one suggestion selected, When the user clicks "Auto‑tune Preset", Then the system creates a new draft preset version with an incremented version tag (e.g., vN+1) without altering the published preset, And applies only the selected suggestions to the draft parameters exactly as specified (including units), And validates all changes against schema and constraints prior to save; any invalid change is rejected with a field‑level error and no partial save occurs, And updates on‑canvas previews for the current scope within 2 seconds of save, And enqueues an automatic Consistency Meter rescore for the same scope within 1 second of save, And displays a success confirmation including the new draft version identifier.

Scoped Application (Batch, Subset, Single Image)

Given the user has chosen a scope (Entire batch | Selected subset | Current image), When "Auto‑tune Preset" is executed, Then only images within the chosen scope have previews and sidecar edits updated, And images outside the scope remain unchanged, And the Consistency Meter rescore job is created for the chosen scope only, And the UI reflects the active scope via a visible scope badge, And a progress indicator reports counts for total, completed, and failed items within the scope until processing completes.

Respect Locked Brand Settings and Safe Bounds

Given one or more brand settings are locked and safe bounds exist for all tunable parameters, When Auto‑tune attempts to modify any locked parameter, Then the locked parameters remain unchanged, And those suggestions are skipped with a non‑blocking notice listing each skipped field and reason "locked", And all applied parameter values are clamped within defined min/max bounds; any clamping is recorded and surfaced as an informational note, And the operation completes without errors and with remaining applicable suggestions applied.

Instant Undo of Auto‑tune

Given Auto‑tune has been applied to a draft in the current session, When the user clicks Undo, Then all parameter changes from the last Auto‑tune action are reverted atomically to the prior values, And previews revert to the prior state within 2 seconds, And a Consistency Meter rescore is triggered for the reverted state within 1 second, And the activity log records an undo entry referencing the reversed change set and resulting draft version.

Side‑by‑Side Before/After Comparison

Given the user has enabled side‑by‑side comparison, When Auto‑tune is applied, Then the "Before" pane displays the exact pre‑apply render frozen at the moment before changes, And the "After" pane displays the updated draft render, And zoom and pan remain synchronized between panes, And each pane is labeled with timestamp and version (Before: vN, After: vN+1).

Audit Trail of Parameter Changes with Versioning

Given Auto‑tune modifies the draft preset, When the draft is saved, Then an audit entry is created containing: ISO‑8601 timestamp, actor (user ID), action "auto_tune_apply", preset ID, new draft version tag, scope (type and counts), list of parameter deltas (field, previous value, new value, units), suggestion IDs applied, suggestions skipped with reason (locked/safe_bound_violation), and rescore job ID, And the audit entry is immutable and retrievable via Activity Log UI and API endpoint, And rollback can target this audit entry to restore the prior version in one action.

Outlier Reduction Feedback and Quick Fix Application

Given the Consistency Meter flags outliers and provides quick‑fix suggestions, When the user selects those suggestions and runs Auto‑tune, Then the subsequent rescore presents an updated score and delta versus prior for the scoped items, And previously flagged outliers are re‑evaluated and marked resolved or unresolved with counts displayed, And any unresolved outliers present follow‑up actionable suggestions, And the success notification summarizes score delta and count of outliers resolved.

Meter UI & Drilldown Dashboard

"As a user, I want a clear meter UI with drilldowns and previews so that I can understand why the score is low and confidently apply targeted adjustments."

Description

Provides a responsive UI component showing the primary Consistency Score, sub-score bars, and status badges with hover tooltips and plain-language explanations. Includes a drilldown modal with sortable thumbnails, per-metric filters, and a diff view to compare suggested adjustments. Offers keyboard navigation, accessible labels, and clear empty/error/loading states. Integrates into the batch upload flow and preset editor without blocking other actions and supports localization.

Acceptance Criteria

Primary Score and Sub-score Display (Responsive)

Given a processed sample set and an active preset When the Meter UI is rendered on a desktop viewport (width ≥ 1280px) Then the primary Consistency Score (0–100) and five labeled sub-score bars are visible without horizontal scrolling Given the same context When the viewport is mobile (width ≤ 480px) Then the primary score and sub-scores reflow into a single-column layout with no visual overlap and essential labels remain readable Given an adjustment to the active preset settings When the change is applied Then the primary and sub-scores visually update within 1000 ms

Status Badges and Tooltips with Plain-Language Explanations

Given sub-score thresholds configured for Good, Needs Review, and Outlier When a sub-score meets a threshold Then the correct status badge is shown with the mapped label and color and the mapping is consistent across views Given a status badge is hovered or keyboard-focused When the tooltip is triggered Then a tooltip appears within 200 ms containing a one-sentence explanation, the relevant threshold, and a suggested quick fix Given a tooltip is open When focus moves away or Escape is pressed Then the tooltip dismisses and focus returns to the triggering element

Drilldown Modal with Sortable Thumbnails and Per-Metric Filters

Given the user clicks View details from the Meter UI When the drilldown opens Then a modal overlays the page without navigation and initial focus is set to the modal header Given thumbnails with per-image scores are displayed When the user clicks a column header (Score, File name, Time) Then the grid sorts by that column and toggles between ascending and descending on subsequent clicks Given metric and status filters are available When the user selects a metric and a status Then only matching thumbnails remain visible and the filter chips reflect the active filters Given the user closes the modal When the modal is dismissed Then the underlying page scroll position and state are preserved

Diff View to Compare Suggested Adjustments

Given a thumbnail is selected in the drilldown When the user opens Diff view Then a side-by-side before and after is shown with a comparison slider and metric deltas Given quick fix suggestions are available for the selected image When the user applies a suggested adjustment Then the after preview updates and metric deltas recalculate within 1000 ms and an undo option becomes available Given the user cancels or undoes the change When the action is triggered Then the view reverts to the original state without residual visual artifacts

Keyboard Navigation and Accessibility Compliance

Given the Meter UI and drilldown are present When navigating by keyboard Then all interactive elements are reachable via Tab and Shift+Tab with a visible focus indicator and Enter or Space activates the focused control Given the drilldown modal is open When navigating Then focus is trapped within the modal and Escape closes the modal and focus returns to the previously focused trigger Given assistive technology users interact When screen readers announce elements Then the primary score, sub-scores, badges, and tooltips have accessible names and roles, and color contrast for text and essential indicators is at least 4.5:1

Empty, Error, and Loading States

Given no sample images are available When the Meter UI loads Then an empty state appears with a concise message and a primary action to add images and no errors are shown Given metrics are being computed When the user opens the Meter UI Then skeleton placeholders are shown until data arrives and no layout shift exceeds 100 px during loading Given an error occurs while fetching or computing metrics When the UI receives an error Then a non-technical message with an error reference code and a Retry action is displayed and the app remains responsive

Non-blocking Integration and Localization Support

Given the user is in the batch upload flow or preset editor When the Meter UI mounts Then Upload, Save Preset, and Apply Preset actions remain available and responsive and meter computation runs asynchronously Given the user navigates away mid-computation When the view changes Then computation is canceled or safely paused and no blocking dialogs prevent navigation and returning restores the last known state Given the user switches locale between en-US, fr-FR, and es-ES (and RTL ar) When the locale change is applied Then all visible strings come from localization files, numbers and dates format per locale conventions, RTL layouts mirror correctly, and no hard-coded text remains

Low-latency Incremental Scoring at Scale

"As a team lead, I want the meter to update quickly as images stream in so that my team doesn’t stall during large batch uploads."

Description

Meets real-time performance targets with initial scoring in ≤2 seconds for up to 50 images and ≤200 ms incremental updates per additional image at the 95th percentile. Uses batched inference, background workers, and cached features to minimize latency and compute cost. Degrades gracefully for very large sets, providing progressive results and queue status indicators. Includes telemetry, rate limiting, and backpressure controls to ensure stability under load.

Acceptance Criteria

P95 Initial Scoring ≤2s for First 50 Images

Given a user uploads up to 50 images and selects a style preset When the Consistency Meter starts scoring Then the first overall score and all per-image scores are displayed within 2,000 ms at the 95th percentile over at least 500 runs in a warm-service environment And fewer than 1% of runs exceed 5,000 ms And a visible progress indicator is shown until scores appear

P95 Incremental Update ≤200ms Per Additional Image

Given an already-scored set of 50 images When 1 to 10 additional images are added Then the overall score updates and the new image(s) receive scores with server-side latency ≤200 ms per image at P95, measured from enqueue to publish, across ≥500 runs And client UI renders the updated score(s) within 300 ms P95 from server publish And updates are streamed without requiring a page refresh

Progressive Results and Queue Status for Large Uploads

Given an upload of 5,000 images When scoring begins Then the UI displays progressive results with at least the first 50 scores within 3,000 ms and subsequent updates at intervals ≤2,000 ms And a queue status indicator shows items processed/total, current throughput (images/sec), and ETA, updated at least every 2,000 ms And no update gap exceeds 5,000 ms until processing completes

Telemetry and Alerts for Latency and Stability SLOs

Given production load When telemetry is collected Then metrics are emitted for initial and incremental latency (P50/P95/P99), queue depth, batch size distribution, cache hit rate, worker utilization, and error rates at 10-second resolution And dashboards visualize these metrics with 1-minute and 5-minute windows And alerts trigger when P95 initial latency >2,000 ms or P95 incremental latency >200 ms for 5 consecutive minutes, or 5xx error rate >0.5% for 5 minutes

Rate Limiting and Backpressure Under Multi-tenant Load

Given 100 tenants concurrently uploading totaling ≥20,000 images at ~200 requests/sec When a tenant exceeds its configured limit Then the API returns HTTP 429 with a Retry-After header and the excess work is queued or rejected without data loss And tenants under their limits continue to meet latency SLOs (P95 initial ≤2,000 ms; P95 incremental ≤200 ms) And system 5xx error rate remains ≤0.5% and worker CPU utilization ≤85%

Cached Features Accelerate Re-scoring

Given a previously scored batch is re-scored with the same preset within 15 minutes When scoring is re-triggered Then time to first 50 scores decreases by ≥60% compared to a cache-cold baseline measured the same day And cache hit rate for feature retrieval is ≥80% during the run And compute time (GPU/CPU seconds) per image is reduced by ≥50% as reported by telemetry

Channel Targets

Declare where images will go (Amazon, Etsy, Shopify, social) and Sprint auto‑sets compliant bounds for margins, backgrounds, DPI, and aspect ratios. You design once while PixelLift enforces the right constraints to pass marketplace checks later.

Requirements

Channel Rules Engine

"As a boutique seller, I want PixelLift to automatically apply channel-specific rules so that my images pass marketplace checks the first time."

Description

A centralized, versioned repository of marketplace and social channel compliance rules (e.g., aspect ratios, min/max dimensions, DPI, file types, file-size limits, background color/opacity, margin/safe-area, watermark/border allowances, color space). Rules support variants by channel, locale, and image role (e.g., Amazon Main vs Additional). Rules are expressed in a machine-readable schema consumed by the rendering pipeline and UI. PixelLift maintains default templates and updates them; admins can extend/override within workspaces. When a user declares targets, the engine resolves applicable constraints and exposes them as enforceable policies to processing, validation, and export services, ensuring consistent, auditably correct outputs.

Acceptance Criteria

Resolve Constraints for Declared Targets (Single Channel, Role, Locale)

- Given channel=Amazon, locale=US, role=Main Image, when targets are saved, then the rules engine returns a resolved policy scoped to those three dimensions. - The policy includes: aspect_ratio, min_width, max_width, min_height, max_height, min_dpi, allowed_file_types, max_file_size_bytes, background_color, background_opacity, safe_area_pct, watermark_allowed, border_allowed, color_space, and rule_version_id. - The policy payload includes source identifiers: channel_id, locale_id, role_id, template_version_id. - Resolution occurs within 200 ms at p95 under nominal load. - If any dimension is unknown, the engine returns HTTP 400 with error_code="UNKNOWN_TARGET_DIMENSION" and no policy is produced.

Workspace Rule Override Precedence and Audit Logging

- Given a workspace-level admin override on a rule (e.g., background_color) for channel=Amazon US Main Image, when resolving a policy, then the override value is returned and the default template value is not. - Overrides apply only within the originating workspace; other workspaces continue to resolve defaults. - All override create/update/delete actions are captured with actor_id, timestamp, change_diff, and version_id; the audit log is retrievable via an API and includes pagination. - Submitting an override with invalid schema is rejected with HTTP 422 and a list of schema violations; no changes are persisted. - Non-admin users attempting to create overrides receive HTTP 403.

Machine-Readable Rule Schema Validation and Coverage

- Rules are stored and retrieved as JSON conforming to schema version v1.x; JSON Schema validation passes for all default templates. - Required properties cannot be null or missing; invalid values trigger descriptive errors with JSON Pointer paths to the offending fields. - The engine exposes a validation operation that returns valid=true/false and violations[]; test suite includes at least 20 positive and 20 negative samples. - The schema supports variants by channel, locale, and image role; resolving selects the most specific matching rule per dimension. - Backward-compatible schema changes increment the minor version; incompatible changes increment the major version and are rejected unless a feature flag explicitly enables them.

Versioning, Pinning, and Update Propagation

- Each resolved policy includes rule_version_id and template_version_id; IDs are immutable and monotonically increasing. - When a batch job starts, it pins the rule_version_id; subsequent rule updates do not affect that job's processing, validation, or export. - New jobs created after a rule update automatically use the latest version by default; users may opt to pin to a prior version via API/UI. - Publishing a rule update propagates to resolution within 60 seconds; p95 publish-to-availability latency <= 60s. - A diff operation returns a structured comparison between two versions, including breaking_change=true/false and a list of impacted fields.

Enforcement During Processing, Validation, and Export

- Processing enforces resolved policies; any image violating a constraint is marked non-compliant with reason codes (e.g., ASPECT_RATIO_OUT_OF_RANGE) and remediation hints. - The validation service returns per-image, per-target pass/fail with a complete list of violations and the rule_version_id used. - Export blocks non-compliant images by default; an authorized override flag is required to export non-compliant images, and the export includes a compliance report JSON alongside assets. - For a batch of 500 images, validation p95 latency per image <= 50 ms; validation completes successfully for >99% of images without timeouts. - Exported assets include a manifest embedding channel, locale, role, and rule_version_id; the manifest validates against a published JSON Schema.

Multi-Channel Targets and Per-Target Policy Output

- When multiple targets are declared (e.g., Amazon US Main, Etsy Listing, Instagram Feed), the engine returns a distinct policy object for each target with unique policy_id and rule_version_id. - The rendering pipeline receives a per-target policy map; it produces separate outputs when constraints differ and reuses a single output when constraints are identical; the number of outputs equals the count of unique policies. - Conflicting constraints across targets are not merged; the engine flags conflicts with a warning list and recommends multi-render; no single-output over-constraining occurs. - The UI and API display compliance status per target; a target can pass while another fails within the same batch. - For 10 combined targets across 100 images, policy resolution p95 latency per target <= 50 ms, and total memory overhead remains within 200 MB during resolution.

Target Selection & Preset Overrides

"As a store owner, I want to select my sales channels once per batch so that PixelLift enforces the right constraints without manual tweaks."

Description

An intuitive project/batch-level UI and API to declare one or more channel targets (Amazon, Etsy, Shopify, Instagram, etc.) with brand-default presets per workspace. Supports per-channel overrides (e.g., different background policy), per-image exceptions, and preset saving/sharing. Displays real-time rule summaries (badges for required dimensions, background, margins) and conflict warnings. Selections persist in project metadata, are version-aware with respect to rules, and drive downstream enforcement, validation, and export. Streamlines setup to a single step while enabling granular control when necessary.

Acceptance Criteria

Select Multiple Channel Targets at Project Level

Given a new project with no channels selected When the user selects Amazon and Etsy and clicks Save Then the project metadata stores ["amazon","etsy"] and the UI shows 2 selected Given a saved project with channels selected When the project is reloaded Then the previously selected channels remain selected with no duplicates Given a project with three channels selected When the user deselects Etsy and saves Then "etsy" is removed from project metadata and the badges update within 500 ms Given an attempt to add an unsupported channel ID When the selection is saved Then the save is rejected and a validation error message is shown

Apply Workspace Brand-Default Presets on New Project

Given workspace brand-default presets exist for Amazon and Etsy When a new project is created and those channels are selected Then the defaults auto-apply and are visible in the rule summary (background, margins, DPI, aspect ratio) Given no brand-default preset exists for a selected channel When the channel is added to the project Then PixelLift applies global defaults and marks them with a "Default" badge Given brand-default presets are changed at the workspace level When creating a new project after the change Then the new defaults apply to the new project, and existing projects remain unchanged Given an override was made and saved When the user clicks "Reset to default" for that channel Then the preset values revert to the brand-default values

Per-Channel Preset Override at Project Level

Given Amazon and Instagram are selected for a project When the user changes Instagram background to #F7F7F7 and leaves Amazon at #FFFFFF Then only Instagram's preset reflects #F7F7F7 and Amazon remains #FFFFFF Given a channel has at least one overridden field When viewing the channel list Then an "Overridden" indicator is shown for that channel Given a channel has overrides When the user clicks "Reset to default" for that channel Then all overridden fields revert to the channel's default preset and the indicator disappears Given channel overrides are saved When the project is re-opened Then the overrides persist exactly as saved

Per-Image Exception Overrides Within Batch

Given a batch of 100 images with Amazon and Etsy selected When the user sets a 10% margin exception for image IMG_001 on Amazon only Then only IMG_001 on Amazon uses 10% margin, while all other images and channels retain their channel-level settings Given 10 images are multi-selected When a 3000x3000 export size exception is applied for Etsy Then the exception applies to those 10 images on Etsy only Given an image has one or more exceptions When opening its details panel Then a badge lists each overridden property per channel Given exceptions exist on an image When the user clicks "Clear exceptions" Then the image reverts to the project/channel preset and exception badges are removed Given exceptions are set When exporting the batch Then the rendered outputs honor the exceptions for the affected images and channels

Real-Time Rule Summaries and Conflict Warnings

Given one or more channels are selected When viewing the rule summary panel Then badges show per-channel requirements for dimensions, background policy, margin bounds, DPI, and aspect ratio Given a setting violates a selected channel's rule When the user changes a value into a non-compliant state Then a conflict warning appears within 200 ms with guidance to restore compliance Given a conflict warning is visible When the user adjusts the value into the allowed range/policy Then the warning clears within 200 ms and the badge becomes compliant Given mutually incompatible settings across selected channels are detected When the summary is displayed Then the UI surfaces a non-blocking notice suggesting per-channel overrides and allows the project to be saved

Version-Aware Rule Persistence in Project Metadata

Given marketplace rule definitions are versioned with IDs When a project is saved with selected channels Then the project metadata stores ruleVersionIds per channel at time of save Given ruleVersionIds have been updated upstream When opening an existing project saved on older versions Then the stored versions remain active and a banner offers to upgrade with a changelog preview Given the user accepts an upgrade When confirmation is given Then the project switches to the new ruleVersionIds, revalidates, and displays any new conflicts introduced Given an export is performed When the export manifest is generated Then it records the ruleVersionIds used for validation and enforcement

Preset Saving and Sharing Across Workspace

Given a user with permission edits channel presets When the user saves the configuration as a named preset Then a preset with a unique ID is created and visible to all workspace members Given a shared preset exists When another member applies it to a project/channel Then all preset fields apply exactly and the action is audit logged with user, time, and preset version Given a preset is updated When changes are saved Then a new preset version is created; existing projects retain their previous version until explicitly upgraded Given a preset is deleted When it is referenced by existing projects Then those projects retain a frozen copy; the preset is no longer available for new applications

Auto-Adjust Constraint Enforcement

"As a catalog manager, I want PixelLift to auto-adjust images to meet channel requirements so that I don’t have to re-edit or reshoot."

Description

Non-destructive processing that automatically enforces selected channel constraints: canvas resize, smart crop/pad using subject-aware bounding boxes, background replacement/flattening, DPI resampling, color profile conversion, margin normalization, and format/quality optimization to meet file-size caps. Detects and removes/flags prohibited elements (e.g., watermarks, borders, text overlays) when rules require. Provides configurable strictness (auto-fix vs flag-only) and protects against quality loss via thresholds and skip-with-warning behavior. Ensures outputs meet compliance while preserving visual integrity and brand style.

Acceptance Criteria

Amazon Main Image Constraints Auto-Enforcement

Given a channel profile "Amazon Main Image" with constraints: background=#FFFFFF flattened; subject coverage 85–95% of canvas; aspect ratio 1:1; min longest side=1600 px; DPI=300; color profile=sRGB IEC61966-2.1; max file size=10 MB; prohibited elements: text, logos, watermarks, borders. When a batch of 50+ varied product photos is processed with Auto-Adjust Constraint Enforcement. Then each output: - has a pure white background (CIE ΔE2000 to #FFFFFF ≤ 1.0) and no transparency - maintains the detected subject fully inside frame; subject coverage is between 85% and 95%; edge padding ≥ 2% on all sides - is 1:1 aspect ratio; longest side ≥ 1600 px; metadata DPI set to 300 - embeds sRGB IEC61966-2.1; flattened single layer - is exported as JPEG with file size ≤ 10 MB while SSIM ≥ 0.98 vs the pre-optimization image - contains no prohibited elements; any removed elements are logged with reason codes - passes channel compliance validation with zero errors - leaves the original source files unmodified

Shopify Color Profile Conversion & File Size Optimization

Given a channel profile "Shopify Product" with constraints: target longest side=2048 px (upscale limit 2×), color profile=sRGB IEC61966-2.1, preferred export=WebP then JPEG, max file size cap=20 MB, quality threshold SSIM ≥ 0.98. When images are processed with Auto-Adjust Constraint Enforcement. Then each output: - has longest side set to 2048 px unless that requires >2× upscaling; in that case upscaling is limited to 2× and a "ResolutionLimit" warning is recorded - is converted to and embeds sRGB IEC61966-2.1 - is exported as WebP if it meets the cap with SSIM ≥ 0.98; otherwise exported as JPEG - has file size ≤ 20 MB; if meeting the cap would break SSIM ≥ 0.98, the system retains SSIM ≥ 0.98, attaches "SkipWithWarning:FileSize", and marks compliance=false

Social Square Crop with Subject-Aware Padding

Given a channel profile "Instagram Square" with constraints: aspect ratio 1:1; min size 1080×1080; safe margin ≥ 3% around detected subject; background preset="Gradient A"; color profile=sRGB; max file size=8 MB. When an image with an off-center subject is processed. Then the output: - is 1:1 with dimensions ≥ 1080×1080 via subject-aware crop/pad; no subject pixels are clipped (subject IoU ≥ 0.99 with pre-crop mask) - has ≥ 3% padding between the subject bounding box and each edge - replaces background with preset "Gradient A" and flattens layers - is in sRGB and ≤ 8 MB with SSIM ≥ 0.98 vs pre-optimization

Prohibited Elements Detection & Handling

Given a channel where prohibited elements include watermarks, borders, and text overlays, and strictness=Auto-Fix, and a test set containing examples for each violation plus clean images. When the batch is processed. Then: - watermarks are removed or masked without altering subject pixels (no change inside subject mask; Dice coefficient ≥ 0.99) - borders are trimmed and the canvas is re-padded/cropped to restore required margins and aspect ratio - text overlays not integral to the subject are removed; if removal would alter the subject, the image is flagged "RemovalRisk" and left unchanged - clean images are not modified - each action logs type, bounding box coordinates, and reason code; compliance=true where all violations are fixed; compliance=false for flagged images

Strictness Modes: Auto-Fix vs Flag-Only Behavior

Given the same violating input and channel constraints, with strictness toggled at the channel level. When strictness=Auto-Fix. Then all fixable violations are corrected automatically; unfixable violations are flagged; final compliance=true only if no violations remain; originals are unmodified; an audit trail lists each fix. When strictness=Flag-Only. Then no pixel-level changes are applied; all violations are detected and reported with reason codes; final compliance=false; suggested fixes are included in the report.

Quality Preservation Thresholds & Skip-with-Warning

Given a channel profile with a file size cap and quality thresholds SSIM ≥ 0.98 and PSNR ≥ 40 dB. When resampling or compression would require breaching thresholds to meet the file size cap. Then the system: - attempts alternate formats and qualities and selects the smallest file that maintains thresholds - if no setting meets the cap while maintaining thresholds, outputs the version that maintains thresholds, attaches "SkipWithWarning:QualityGuard", and marks compliance=false unless the channel allows "allow-near-cap ≤ 10%", in which case exceeding the cap by ≤ 10% is permitted and compliance=true

Non-Destructive Processing, History & Reversion

Given any channel constraints and an input image. When Auto-Adjust Constraint Enforcement is applied and the user later changes a rule and reprocesses. Then: - the original asset remains unchanged on disk - all operations are stored as an ordered, parameterized history - reprocessing starts from the original asset, not from a prior export; results are deterministic for identical inputs/configuration - the user can revert to any prior step and export again; exports are versioned and traceable to the source and configuration hash

Preflight Compliance Report

"As a marketer, I want a preflight report per channel so that I know what will fail and how to fix it before publishing."

Description

A pass/fail validator that checks each image against each selected channel’s rule set prior to export or publishing. Presents actionable diagnostics (what failed and why) with one-click fix suggestions, bulk apply, and preview. Summarizes blocking errors vs non-blocking warnings at batch and image levels. Exposes results via UI and downloadable CSV/JSON for audit/QA. Integrates with the rules engine for versioned, reproducible validation, reducing rejections and back-and-forth edits.

Acceptance Criteria

Batch Preflight Validation Across Multiple Channels

Given a batch of at least 100 images and channels Amazon and Etsy selected with rules engine version v1.12 pinned When the user runs Preflight Validation Then each image is evaluated independently against each selected channel’s rule set And the report lists for every image–channel pair a status of Pass, Fail, or Warn And the batch summary displays counts of Pass, Fail, and Warn across all images and channels And validation completes without error within 120 seconds for a batch of up to 500 images on the standard plan

Blocking Errors vs Warnings Summary

Given the rules define severities Blocking and Warning When validation completes Then the batch header shows total Blocking Errors and total Warnings separately And each image row shows per-channel chips for Blocking and Warning counts And a filter “Show blocking only” lists only images with one or more blocking errors And non-blocking warnings do not prevent export, but remain visible in summaries

Actionable Diagnostics and One-Click Fix with Preview

Given a failed rule (e.g., background color non-compliant for Amazon) When the user opens the image detail panel Then the panel lists each failed rule with channel, ruleId, severity, human-readable message, and suggested fix And a “Preview Fix” shows a non-destructive preview of the adjustment When the user clicks “Apply Fix” Then the image variant is updated and validation re-runs for affected channels And “Bulk Apply All Suggested Fixes” applies the corresponding fixes across all applicable images and re-runs validation And all applied fixes are logged with timestamp, user, and affected imageIds

Exportable Compliance Report (CSV and JSON)

Given preflight validation has been executed When the user downloads the CSV report Then the file contains one row per image–channel–rule with columns: batchId, imageId, filename, channel, ruleId, ruleVersion, severity, status, message, fixSuggested, fixApplied, timestamp And when the user downloads the JSON report Then it contains the same fields grouped by image and channel and validates against schema version 2.0 And exported filenames include batchId and ISO-8601 timestamp And exports complete within 30 seconds for up to 10,000 rows

Reproducible Validation via Versioned Rules

Given channels are selected and the rules engine exposes versioned rule sets When validation runs Then the report header records the exact rules version ID per channel And re-running validation on the same images with the same pinned versions yields identical results And when a newer rules version is available, the UI displays an “Update available” indicator and offers “Revalidate with latest” Then results from the latest run are labeled with the new version and do not overwrite prior results unless confirmed by the user

Preflight Gate Prior to Export or Publish

Given a batch contains images with mixed Pass, Fail, and Warn results When the user opens the Export/Publish dialog Then channels with any blocking errors have export toggles disabled and show the count of blocking issues And channels with zero blocking errors are enabled for export And a “View issues” link opens the report filtered to the selected channel and blocking errors And attempting to export a channel with blocking errors is prevented and shows an error listing up to three blocking issues with a link to view all; warnings do not block export

Multi-Channel Derivative Export

"As an operations lead, I want per-channel exports with correct naming and metadata so that my upload automations and listings just work."

Description

Generation of per-channel, per-variant outputs from a single design, applying naming conventions, folder structures, and embedded metadata mappings appropriate to each destination. Handles color profile normalization (e.g., sRGB), background flattening/alpha handling, DPI setting, and compression strategies tuned to hit file-size limits without visible artifacts. Supports parallelized, resumable batch export with deterministic outputs for caching and duplicate detection. Ensures ready-to-upload assets for every target with minimal manual handling.

Acceptance Criteria

Per-Channel Variant Export From Single Design

Given a project with one base design, 3 channel targets (Amazon, Etsy, Shopify), and 4 product variants When Multi-Channel Derivative Export is triggered Then exactly 12 output images are produced (3 channels × 4 variants) And each file name matches the channel’s naming template (including SKU, VariantID, and Channel suffix) And each file is placed under the correct channel/variant folder structure as configured And the export summary reports counts per channel and variant that match files on disk

Metadata Mapping & Embed Per Destination

Given a channel-specific metadata mapping defining required keys and prohibited fields When the export completes Then each output embeds exactly the mapped metadata for its destination (e.g., SKU, VariantID, Channel, AltText) And prohibited metadata (e.g., GPS, camera serial) is removed And validating metadata with the built-in checker returns 0 errors and 0 warnings for all files

Color Profile Normalization & Background Handling

Given inputs may contain varied color profiles and transparency When exporting to channels that require sRGB and opaque backgrounds Then outputs are converted to sRGB IEC61966-2.1 and transparency is flattened to the configured background color And for channels that allow transparency, alpha is preserved and no background flattening occurs And measured color difference after conversion is ΔE00 ≤ 2 against the reference transform And exported files include exactly one embedded sRGB profile tag

DPI, Aspect Ratio, and Margin Compliance

Given each channel profile defines target pixel bounds, aspect ratio, DPI tag, and content margins When the export runs Then each output’s pixel dimensions and aspect ratio fall within the specified constraints for its channel And DPI metadata matches the channel profile value And auto-crop/pad operations do not clip the detected product bounding box (0 clipped pixels) And channel compliance validation passes 100% for all outputs

Compression & File Size Compliance With Quality Guardrails

Given each channel defines a maximum file size and recommended codec/quality settings When encoder settings are applied during export Then every output is ≤ the channel’s max file size And structural similarity SSIM ≥ 0.98 and PSNR ≥ 40 dB versus the pre-compression rendered image And no visible blocking/ringing is detected by the artifact detector (0 flagged tiles) And the export log records the chosen quality level and number of encode passes per file (≤ 3 attempts)

Parallelized Resumable Batch Export

Given a batch of 500 images with concurrency set to 8 workers When the export is paused at 37% and later resumed Then previously completed files are not reprocessed and the job resumes from the last confirmed checkpoint And no partial/corrupted files are present (all outputs are written atomically) And final produced file count equals the expected total and matches the manifest And average CPU utilization of workers remains within configured limits without worker crashes (0 worker failures)

Deterministic Outputs, Caching, and Duplicate Detection

Given identical inputs and channel configurations across two runs When Multi-Channel Derivative Export is executed twice Then all outputs are byte-identical with matching checksums and metadata across runs And unchanged items are served from cache on the second run (cache hit rate ≥ 90% when no inputs changed) And duplicate detection prevents emitting multiple identical files to the same destination (0 duplicate files), with dedup events logged

Direct Publish Connectors

"As a seller, I want to publish directly to my stores and marketplaces so that I can go live faster without downloading and reuploading files."

Description

Optional connectors to publish validated assets directly to Shopify, Etsy, Amazon (SP-API), and social platforms. Provides OAuth account linking, per-store/channel mapping, SKU/handle association, destination collection/album selection, and dry-run mode. Implements queued, rate-limited uploads with retries, webhook/callback handling, and clear error surfacing. Adheres to each platform’s API constraints and quotas, enabling end-to-end flow from design to live listing without manual downloads/uploads.

Acceptance Criteria

OAuth Account Linking and Token Management

- Given I am an org admin and select "Connect Shopify" from Direct Publish Connectors, when I complete the OAuth flow successfully, then the connector status changes to "Linked" and displays the store domain and shop ID. - Given an access token has expired, when a publish job is initiated, then the system refreshes the token using the stored refresh token and retries the request once without user action. - Given I click "Unlink" for a linked connector, when I confirm, then all tokens are revoked at the provider (if supported), deleted from storage, audit-logged, and the connector status becomes "Not linked". - Given multiple stores/accounts are linked for a provider, when I view publish settings, then each account is selectable independently with its own saved configuration. - Rule: Access and refresh tokens are stored encrypted at rest and redacted in logs and UI.

Per-Store/Channel Mapping and Destination Selection

- Given multiple channels are linked (Shopify, Etsy, Amazon, social), when I configure per-store/channel mappings for a project, then the mapping is saved and preselected on subsequent publish flows. - Given Shopify is selected, when I choose one or more destination collections and/or a product handle, then published images are attached to the specified product and the product is assigned to the selected collections. - Given Etsy is selected, when I specify a listing ID (draft or active), then images are uploaded to that listing's gallery in the configured order. - Given Amazon (SP-API) is selected, when I specify Seller SKU(s) and marketplace, then images are attached to the correct catalog item(s) under the selected marketplace. - Given a selected channel is missing required destination details, when I attempt to start a publish job, then validation fails with a blocking message identifying the channel and missing fields.

SKU/Handle Association and Image Attachment

- Given assets carry SKU/handle metadata or a mapping table is provided, when publishing to Shopify, then each image attaches to the product matching the handle or SKU per the mapping. - Given publishing to Amazon, when an image is marked as "MAIN" vs "ADDITIONAL", then it is submitted to the corresponding image slot (MAIN or PT01–PT08) for the specified SKU. - Given duplicate images are mapped to multiple variants of the same product, when publishing, then the image is uploaded once and associated to each variant as allowed by the platform without duplicate uploads. - Given no matching SKU/handle is found for an asset, when validating, then the asset is flagged as "Unmapped" and is excluded from publishing with an actionable error.

Dry-Run Mode Publish Simulation

- Given Dry Run is enabled, when I start a publish job, then no external write calls are executed and no assets are created/modified on any platform. - Then a per-asset simulation report is generated including target channel, destination identifier (e.g., shop ID, listing ID, SKU), intended slot/position, and predicted payload size. - Given Dry Run, when constraints or mappings are invalid, then the same validation errors are surfaced as in a real publish and the job result shows 0 successful publishes. - Rule: Audit logs for Dry Run include only simulated requests and explicitly mark the job as "Dry Run".

Queued, Rate-Limited Uploads with Retries and Idempotency

- Given a publish job with 500+ assets across channels, when the job runs, then uploads are queued and processed with a maximum concurrency of 5 per channel by default (configurable). - Given a 429 or rate-limit response is received, when retrying, then the system honors Retry-After headers (if present) and uses exponential backoff with jitter up to 5 attempts before marking the asset as failed. - Rule: Each asset publish attempt uses a stable idempotency key per channel (jobId+assetId) so that retries do not create duplicate images within a 24-hour window. - Given the worker service restarts mid-job, when it resumes, then already-succeeded assets are not re-sent and remaining queued items continue processing.

Webhook/Callback Handling and Status Synchronization

- Given a provider emits success/failure callbacks for image uploads, when a webhook is received, then the corresponding asset/job status updates within 30 seconds and stores external identifiers (e.g., Shopify image ID). - Given no webhook is received within 10 minutes of a request, when the job is still pending, then the system polls the provider every 60 seconds up to 30 minutes or until completion, after which remaining items time out as failed. - Rule: Duplicate or out-of-order callbacks are handled idempotently and do not regress a terminal status. - Then the user-facing job summary shows counts by channel: Succeeded, Failed, Skipped, and Pending, with downloadable error details.

Marketplace Constraint Validation and Blocking Pre-Publish

- Given Channel Targets are applied, when an asset violates a selected channel's requirements (e.g., Amazon MAIN not on pure white background, aspect ratio outside bounds, DPI below minimum, margins outside limits, max file size exceeded), then the asset is blocked from publish with a specific, per-violation message and proposed fix. - Given all selected assets meet their channel constraints, when I start a publish job, then pre-flight validation passes in under 10 seconds per 1,000 assets and the job proceeds to queue. - Rule: Blocked assets are excluded from API calls; the publish job proceeds for compliant assets and reports the count and reasons for exclusions per channel.

Rule Change Monitoring & Alerts

"As a brand admin, I want to be alerted when marketplace rules change so that my presets stay compliant and exports continue to pass."

Description

Continuous monitoring of marketplace documentation and PixelLift-maintained rule templates to detect changes. On updates, creates a new rules version, shows human-readable diffs, notifies workspace admins (in-app, email, Slack), and proposes migration of presets/targets with effective-date scheduling. Triggers automatic re-validation of affected projects and flags at-risk exports. Maintains an audit log of rule versions applied to each asset for traceability and compliance evidence.

Acceptance Criteria

Rule Change Detection and Version Creation

Given a monitored rules source (marketplace documentation or PixelLift template) publishes a material change When the monitoring job next runs (<= configured polling interval) Then the system detects the delta and creates a new immutable rules version with unique versionId, channelTarget, source, createdAt, and parentVersionId And Then no new version is created if the normalized rules JSON is unchanged versus the latest version (idempotent) And Then the new version is persisted and visible in the Rules Library list

Human-Readable Diffs for Updated Rules

Given a new rules version exists When an admin opens the diff view Then the UI shows added, removed, and modified constraints with plain-language labels and old vs new values for margins, background, DPI, and aspect ratio And Then the diff view displays the total number of changes and the count of impacted presets/targets And Then a link to the diff is available for sharing with other admins

Admin Notifications (In-App, Email, Slack) on Rule Update

Given a new rules version is created When notifications are dispatched Then all workspace admins receive an in-app alert, an email, and a Slack message (if a webhook is configured) within one polling interval containing channel name, versionId, change summary, link to diff, and impacted preset/target counts And Then if Slack delivery fails, the failure is logged and email/in-app delivery still succeeds

Preset/Target Migration Proposal with Effective-Date Scheduling

Given a new rules version exists When an admin opens the migration wizard Then the system lists all impacted presets and channel targets with per-item change summaries and a selectable checkbox And Then the admin can schedule an effective date/time (with timezone) for migration and preview the resulting constraints And Then upon confirmation, scheduled migration jobs are created and tracked with statuses (pending, running, completed, failed) And Then at the effective time, selected presets/targets are atomically updated to reference the new rules version

Automatic Re-Validation and At-Risk Export Flagging

Given a new rules version is created When automatic re-validation runs Then assets in affected projects and channel targets are re-validated against the new rules and results are recorded And Then any existing exports that would fail under the new rules are flagged At Risk with the failing constraints listed And Then At-Risk flags are visible in the dashboard and on project pages with links to the failing assets

Asset-Level Audit Log and Compliance Evidence

Given any asset has been validated or exported When viewing its audit log Then entries show ruleVersionId, channelTargetId, validation outcome, timestamp, and actor (system/user) for each event And Then audit entries are immutable and can be filtered by asset, project, channel, and ruleVersionId And Then the audit log can be exported to CSV for a selected time range

Source Attribution and Impact Scoping

Given a rules update is detected When viewing the version details Then the source is labeled as Marketplace Documentation or PixelLift Template with a source URL or internal reference And Then the scope of impact is enumerated (channels and constraint categories changed) And Then only impacted presets/targets are included in migration proposals and re-validation

Batch Validator

Run your new preset on a small test batch and get instant feedback: pass/fail reasons, visual diffs, and estimated processing time and cost. Accept or tweak with one click, ensuring you only roll out settings that meet standards and timelines.

Requirements

Sample Set Builder

"As a boutique owner, I want to run my preset on a representative subset of my catalog so that I can validate quality and timing without processing the entire batch."

Description

Enable users to select and generate a small, representative test batch (e.g., 10–50 images) from an uploaded catalog to validate a style-preset before full rollout. Provide selection modes (random, stratified by product/category/SKU, and outlier-focused sampling such as low-resolution or atypical aspect ratios) with configurable caps to control spend. Display sample composition and representativeness indicators (e.g., coverage by category, lighting, background types). Integrates with PixelLift’s catalog metadata and image analysis services to tag images for stratification and to precompute attributes used in sampling.

Acceptance Criteria

Random Sample Generation (10–50 images)

Given an uploaded catalog with at least 50 images and Random mode selected When the user requests a sample size between 10 and 50 (inclusive) and confirms Then the system returns exactly the requested number of unique images within 3 seconds for catalogs up to 10,000 items And each image has an equal selection probability (±2% over 100 repeated draws with fixed parameters) And if the catalog contains fewer images than requested, the system blocks generation and displays a validation error explaining the minimum and current counts And if a random seed S is provided, repeated generation with the same catalog snapshot and S returns the identical image set

Stratified Sampling by Category/SKU

Given an uploaded catalog with category and SKU metadata available and Stratified mode selected When the user requests N images and chooses proportional by category (default) or custom targets per category/SKU Then the sample contains items per stratum that match the target distribution within ±1 item per stratum or ±5% (whichever is larger), and totals equal N And strata with no available items are omitted and reported; shortfalls are reallocated proportionally to remaining strata And at least one item per present stratum is included when N >= number of strata, unless explicitly excluded by the user And the composition summary displays counts and percentages per stratum matching the actual sample

Outlier-Focused Sampling (low-res, atypical aspect ratios)

Given image analysis tags (resolution, aspect ratio, background type) are available and Outlier-focused mode is selected When the user defines outlier rules (e.g., lowest 10% resolution and aspect ratio outside 0.75–1.5) and requests N images Then at least 60% of the sample satisfies at least one outlier rule or the maximum possible if fewer outliers exist, with any shortfall backfilled by random non-outliers And the sample metadata lists which rules each selected image matched And if fewer than 5 outliers exist, the system warns the user before generation And generation completes within 5 seconds for catalogs up to 10,000 items

Spend Cap Enforcement and Cost/Time Estimation

Given pricing per image is available and a spend cap is set by image count or currency When the user requests a sample size N that would exceed the cap Then the system suggests the maximum allowable sample size K that fits the cap, with estimated cost and processing time, and blocks sizes > K unless the cap is changed And the estimated cost equals unit price × selected image count within ±$0.01 rounding tolerance and updates within 1 second of parameter changes And if pricing is unavailable, the system disables cap-by-currency and informs the user

Representativeness Indicators Display

Given a generated sample and catalog attribute distributions (category, lighting, background) are available When the composition is displayed Then indicators show counts and percentages for each attribute value for both sample and catalog And any attribute value whose sample percentage deviates by more than 20% relative from the catalog is flagged with a warning icon and tooltip And coverage includes at least 90% of attribute values present in the catalog when N >= number of values, otherwise a warning explains limitations And the indicators render within 2 seconds and can be exported as CSV

Integration with Metadata and Image Analysis Services

Given access to catalog metadata and image analysis services When sampling requires tags not present locally Then the builder requests and caches required tags before selection, with each external call retried up to 3 times with exponential backoff And if either service is unavailable after retries, only Random mode remains enabled with a non-blocking alert explaining reduced functionality And all selected images in the sample are saved with their tags and sampling mode in the sample record for audit

Persist and Reuse Sample Definitions

Given a configured sampling setup (mode, parameters, seed, filters) When the user saves the sample definition Then the definition is stored with a unique ID and can be rerun later to produce the same image set when executed against the same catalog snapshot and seed And if the catalog has changed, rerun displays differences and requires confirmation before regenerating And users can rename, duplicate, and delete saved definitions; deletes are soft-deleted and recoverable for 30 days

Validation Rule Engine

"As a brand manager, I want explicit pass/fail criteria with clear reasons so that I can ensure images meet our standards and marketplace requirements."

Description

Provide a configurable rules framework that evaluates processed test images against brand and marketplace standards to yield clear pass/fail outcomes and human-readable reasons. Support rules such as background uniformity and color tolerance, subject centering and margin bounds, minimum resolution and aspect ratio, shadow/halo tolerances, color palette adherence, compression/file size limits, and watermark detection. Include default rulesets (e.g., Amazon white background, Shopify guidelines) and allow custom thresholds per workspace. Compute per-image metrics and aggregate pass rate, highlight failing rules with guidance, and expose an extensible metrics registry for future criteria.

Acceptance Criteria

Core Rule Suite Evaluation on Test Batch

Given a configured ruleset "Amazon Default" with thresholds: background L*a*b* std dev <= 2.0; background mean deltaE to pure white <= 3.0; subject margins between 5% and 15% of image edges; subject centroid offset <= 2% of image width/height; minimum resolution >= 1600x1600 px; aspect ratio = 1:1 ± 1%; shadow/halo opacity <= 5%; color palette adherence >= 95% to brand palette; file size <= 2 MB; JPEG quality >= 85; watermark detection confidence <= 0.10 When a test batch of N images is processed with a selected preset Then each image is marked Pass only if all enabled rules are satisfied within thresholds, otherwise Fail with failing rules listed per image

Default Marketplace Rulesets Availability and Selection

Given a workspace with no custom rules defined When the user selects "Amazon Default" or "Shopify Default" Then the engine loads the corresponding predefined rule bundle with documented thresholds and enabled rule list And running validation applies those rules without additional configuration And switching between defaults updates the active bundle and subsequent validation outcomes accordingly

Workspace Threshold Overrides and Precedence

Given a workspace that duplicates "Amazon Default" into "Brand A - Amazon" And overrides: background deltaE <= 2.5, min margin >= 8%, max file size <= 1.5 MB When validation runs under "Brand A - Amazon" Then the engine uses the overridden thresholds for evaluation And unspecified thresholds inherit from the base ruleset And changes to the base ruleset after duplication do not alter overridden values in the workspace version And any rule disabled at workspace level is not evaluated

Aggregate Pass Rate and Metrics Export

Given a processed test batch of N images with per-image rule evaluations and metrics recorded When validation completes Then the engine returns aggregate pass rate = (count of images with Pass)/N to two decimal places And returns batch-level summaries (mean, p95) for background deltaE, centroid offset, margin min/max, resolution, aspect ratio, file size, watermark confidence And exports per-image metrics in a documented schema including ruleId, metric name, value, threshold, and pass boolean

Failing Rule Reasons and Actionable Guidance

Given any image that fails one or more rules When the validation report is generated Then each failing rule includes: rule name, measured value, threshold, delta from threshold, and a concise remediation tip And remediation tips reference relevant preset controls (e.g., "Increase background cleanup to 70–80%") And reasons are human-readable and do not expose internal model IDs

Extensible Metrics Registry and New Rule Onboarding

Given a new metric plugin "specularHighlightRatio" registered with id "metric.specularHighlightRatio" and documentation And a new rule "MaxSpecularHighlightRatio" configured to use that metric with threshold <= 0.12 When the engine loads the registry Then the new metric is discoverable via API and usable in rule expressions without core engine changes And validation using a ruleset that includes the new rule evaluates it and affects Pass/Fail as expected And removing the plugin cleanly invalidates the dependent rule with a descriptive configuration error

Deterministic Evaluation and Repeatability

Given the same input image bytes, preset, and ruleset version When validation is executed multiple times on the same hardware and configuration Then per-image metrics and Pass/Fail outcomes are identical across runs And outputs include the ruleset version hash and preset version to enable reproducibility

Visual Diff Viewer

"As a photo editor, I want to visually compare before-and-after results with rule overlays so that I can quickly spot issues and decide whether the preset is acceptable."

Description

Provide an interactive viewer to compare original vs. processed images with side-by-side and overlay modes, adjustable opacity slider, zoom/pan, grid and safe-margin overlays, clipping and color gamut warnings, and rule annotations directly on the image (e.g., centering boxes, background masks). Allow quick navigation across the sample set, keyboard shortcuts for review speed, and download/export of processed samples. Ensure responsive performance for large images and accessibility compliance for controls and annotations.

Acceptance Criteria

Compare Modes and Opacity Control

Given a test batch image pair is open in the Visual Diff Viewer When the user toggles view mode via UI or hotkey "M" Then the viewer switches between Side-by-Side and Overlay within 150 ms and preserves zoom/pan state Given Overlay mode is active When the user adjusts opacity via slider, arrow keys (1% step), or Shift+Arrow (10% step) Then overlay opacity updates continuously at ≥30 fps and the current percentage is displayed and announced to assistive tech Given the reviewer advances to the next image When no changes are made to display settings Then the last-used mode and opacity persist across images in the session

Synchronized Zoom and Pan Performance

Given Side-by-Side mode with 24–50 MP images When the user zooms via wheel/pinch (5%–800%) or double-click to 100% and pans via drag/space-drag Then both panes stay synchronized within 1 px, interactions render at ≥60 fps (24 MP) or ≥30 fps (50 MP), and reset ("R") completes within 100 ms Given the user holds "Alt" When panning or zooming Then panes temporarily desynchronize and revert to sync on release Given the viewer is resized from 1280x800 to 4K When maintaining current zoom Then content scales without pixelation beyond source resolution and maintains centering

Overlays and Rule Annotations

Given overlays are toggled via "G" (grid) and "S" (safe margin) When enabled Then a rule-of-thirds grid and a safe-margin overlay (default 5%, adjustable 0–20% in 1% steps) render on both panes with opacity 10–60% and persist across images Given rule annotations are toggled via "T" When enabled Then centering crosshair, subject bounding box, and background mask appear with labels; center deviation and fill percentage are shown with numeric readouts accurate to ±1 px/±0.5% Given any overlay or annotation is visible When tabbing through controls Then each has an accessible name, ARIA state, and visible focus indicator meeting WCAG 2.2 AA contrast

Clipping and Color Gamut Warnings

Given the warnings toggle "W" is activated When evaluating the processed image against its embedded or assigned color profile Then clipped pixels (<=0.5% or >=99.5% per channel) and out-of-gamut pixels (relative to sRGB or the selected profile) are highlighted with distinct legends and counts Given synthetic test charts with known clipped and out-of-gamut regions When analyzed Then the viewer reports pixel counts within ±1% tolerance of ground truth and updates the legend in under 150 ms Given warnings overlay is active with other overlays When overlay opacity is adjusted Then all overlays remain distinguishable with a minimum 3:1 contrast against the image content

Sample Navigation and Keyboard Shortcuts

Given a sample set of 200 images When navigating with Right/Left arrows, Home/End, or clicking thumbnails in the filmstrip Then the next image renders within 300 ms on cache hit and 800 ms on first load, with prefetch of the next two images Given keyboard shortcuts are used When pressing "M", "R", "G", "S", "T", or "W", or holding Space for pan Then the mapped action occurs and a non-intrusive toast shows the action name and shortcut for 2 seconds Given the first or last image is in view When pressing Left at first or Right at last Then navigation wraps around only if "Wrap" is enabled; otherwise an edge hint is shown and focus remains

Download/Export Processed Samples and Reports

Given one or more samples are selected When the user clicks "Download Processed" Then a ZIP containing processed images with original filenames and a JSON summary (image_id, pass/fail reasons, diff metrics, processing time and cost estimates) is generated and downloaded Given a selection of up to 50 images totaling ≤500 MB When exporting Then the ZIP is prepared server-side and the download starts within 10 seconds; progress is displayed and the operation is cancellable Given color profiles are embedded in processed files When files are exported Then processed images retain the intended ICC profile and metadata is preserved or stripped according to export settings

Accessibility and Compliance

Given keyboard-only navigation When reviewing all controls and overlays Then all functions are operable via keyboard with a logical focus order and visible focus states Given a screen reader such as NVDA, JAWS, or VoiceOver When announcing UI controls and overlay states Then controls expose accessible names, roles, states, and live updates; opacity, zoom, and mode changes are announced within 500 ms Given WCAG 2.2 AA criteria When auditing color contrast, target sizes, and motion Then controls meet contrast ≥4.5:1, interactive targets are ≥24x24 px, reduced-motion preference disables animated transitions, and no content flashes more than 3 times per second

Time & Cost Estimator

"As an independent seller, I want to know how long processing will take and what it will cost so that I can plan my listing schedule and stay within budget."

Description

Estimate total processing time and monetary cost for running the selected preset across the entire batch by extrapolating from the test run, factoring in current queue load, hardware tier, image resolution distribution, and pricing rules. Present min/avg/max time ranges, confidence indicators, and currency breakdown. Update estimates dynamically when the preset, rules, or sample composition changes. Persist the estimate alongside the validation report and surface alerts if estimates exceed workspace budgets or SLA targets.

Acceptance Criteria

Extrapolate from Test Batch to Full Batch

Given a completed test batch of at least 10 images processed with preset P and recorded per-image timings and costs by resolution bucket When the estimator is opened for a full batch of M images Then the total estimated cost equals the sum over resolution buckets of (avg per-image cost from the test batch × image count in the full batch) using the current pricing rules, with rounding tolerance ≤ ±0.01 in the workspace currency And the total estimated processing time equals the sum over resolution buckets of (avg per-image processing time from the test batch × image count in the full batch), expressed in minutes And images flagged as unsupported are excluded from both totals and displayed as an excluded count

Factor Real-Time Queue Load and Hardware Tier

Given a current queue load Q (jobs ahead) and a selected hardware tier T with a configured performance multiplier When the estimator computes time ranges Then the ranges include queue wait time based on Q and the rolling average per-job time, and are scaled by the multiplier for T And the UI displays the current Q and selected T alongside the estimate And changing T updates the time estimates within 2 seconds of selection

Present Time Ranges with Confidence Indicator

Given test batch size N and coefficient of variation cv derived from per-image processing times When computing and displaying the estimate Then the UI shows numeric min, avg, and max durations with units (minutes/hours) and ensures min ≤ avg ≤ max And a confidence badge is displayed as High if N ≥ 50 and cv ≤ 0.20, Medium if N ≥ 20 and cv ≤ 0.35, else Low And the badge tooltip communicates expected error bounds: High ±15%, Medium ±25%, Low ±40%

Show Currency and Cost Breakdown

Given workspace currency settings and active pricing rules (base, hardware surcharges, preset surcharges, discounts) When the estimator displays cost Then the UI shows currency code and symbol and a breakdown with per-image average, batch total, and line items (base, surcharges, discounts) And totals equal the sum of line items, rounded to two decimals, with no hidden adjustments And the pricing rules version/timestamp used is visible in a tooltip or details panel

Dynamic Refresh on Preset/Rules/Sample Changes

Given the estimator panel is open When the user changes preset settings, pricing rules, or the test batch composition (add/remove images) Then the estimate recalculates and the UI refreshes within 2 seconds And an "Updated" timestamp and change highlight are shown And if recalculation fails, an inline error is shown and the prior estimate is labeled "Stale" and visually dimmed

Persist Estimate with Validation Report

Given a completed test run with an active estimate When the user saves or exports the validation report Then the estimate (time ranges, confidence, cost breakdown, and inputs snapshot: preset version, pricing rules version, queue timestamp, hardware tier, resolution distribution) is persisted with the report And reopening the report later shows the same values regardless of subsequent changes to presets or pricing rules And the report appears in the Batch Validator history with the estimate accessible from the list and detail views

Budget and SLA Exceedance Alerts

Given a workspace remaining budget B and SLA target T_sla When the estimated total cost exceeds B Then a blocking red alert states the overage amount and the "Accept" action is disabled unless the user has override permission and confirms When the estimated average or P95 processing time exceeds T_sla Then a non-blocking amber warning states the delta and provides actions to adjust preset, choose a faster hardware tier, or reduce batch size

One-click Accept/Tweak/Retry

"As a shop owner, I want to accept or adjust my preset and revalidate with minimal friction so that I can confidently roll out settings without wasting time."

Description

Provide primary actions to either accept the current preset and launch full-batch processing, open the preset editor with current settings for tweaks, or re-run the validator with a new sample in one click. Gate acceptance on meeting a configurable pass-rate threshold or require explicit override with confirmation and reason. Ensure idempotent job creation, atomic transition from validation to production run, and real-time status updates/notifications. Preserve context so edits in the preset editor can be revalidated and compared to prior runs.

Acceptance Criteria

Accept gated by pass-rate threshold with explicit override

Given an organization-level or preset-level pass-rate threshold is configured (default 95%) and the latest validator run is completed When the validator results screen loads Then the Accept button is enabled only if pass-rate >= threshold and disabled otherwise Given the Accept button is disabled due to threshold not met When the user selects Override Then a confirmation modal requires a reason of at least 10 characters, displays the current pass-rate and threshold, and shows an explicit warning about risks Given the user confirms the override with a valid reason When the override is submitted Then the production run is initiated and an audit log entry is recorded with userId, timestamp, presetVersion, validatorRunId, pass-rate, threshold, and override reason Given the pass-rate >= threshold When the user clicks Accept Then the production run is initiated without requiring an override modal

Atomic promotion and idempotent production job creation

Given a validator run meets gating (or override confirmed) When the user clicks Accept Then exactly one production job is created with an idempotency key composed of orgId + batchId + presetVersion + validatorRunId and duplicate attempts within 5 minutes do not create additional jobs Given the job creation succeeds When transitioning from validation to production Then the validator run is marked Promoted atomically only after the job is persisted and a jobId is returned; otherwise the run remains Unpromoted and an actionable error is shown Given the job is created When viewing the job details Then metadata includes presetVersion, validatorRunId, source batchId, item counts, and a snapshot of estimated time and cost as of acceptance

One-click Tweak opens editor with preserved context and compare

Given a completed validator run is in view When the user clicks Tweak Then the preset editor opens preloaded with the exact settings used by the latest run and the sampled images, metrics, and diffs context are preserved Given the editor is open with preserved context When the user clicks Revalidate Then a new validator run executes against the same sample by default, with an option to pick a different sample, and the results view shows side-by-side comparison to the prior run (scores, pass/fail reasons, and visual diffs) Given the user saves changes and exits the editor When returning to the validator results view Then the latest run is selected, prior runs remain available in history, and filters/selections persist across page refresh

One-click Retry runs validator with a new sample

Given a completed validator run is in view When the user clicks Retry Then a one-step sample picker offers Last Sample, Random (10, 50, 100), and Custom selection options with Random 50 preselected, and starting the run requires a single confirm click Given a new validator run is started via Retry When the run begins Then the UI reflects Validating state within 3 seconds and shows an updated time and cost estimate Given the Retry run completes When results are displayed Then pass/fail reasons, visual diffs, and summary metrics are shown and Accept gating is recalculated from this latest run Given rate limits are in place When more than 5 validator runs are triggered for the same preset within 60 seconds Then the Retry control is disabled and a cooldown countdown is displayed until limits reset

Real-time status updates and notifications

Given a validator run or production job is active When backend status changes occur Then in-app progress updates are displayed within 2 seconds via WebSocket; if WebSocket is unavailable, polling occurs every 10 seconds Given key state transitions occur (Run Completed, Job Started, Job Completed, Job Failed) When notifications are enabled Then users receive an in-app toast with the state, primary metrics, and a deep link to details Given email/webhook notifications are configured at the workspace level When a production job starts or finishes Then an email/webhook is sent containing jobId, presetVersion, validatorRunId, total items, succeeded/failed counts, startedAt, finishedAt, and duration

Concurrency safety for Accept across multi-clicks and clients

Given multiple Accept attempts occur (double-clicks, rapid retries, or from different clients) for the same presetVersion and validatorRunId within 30 seconds When requests reach the backend Then only the first succeeds in creating a production job and subsequent attempts return 409 Already Promoted with the existing jobId surfaced to the UI Given the first Accept succeeds When the page is refreshed or opened on another device Then the UI shows the Promoted state with a link to the existing job and Accept is disabled Given suppressed duplicate attempts occur When viewing the activity log Then one Promotion entry exists with additional Suppressed duplicate records capturing userId, timestamp, and source client

Validation Audit Trail & Versioned Reports

"As an operations lead, I want a complete history of validation runs and decisions so that I can audit quality, reproduce results, and roll back when necessary."

Description

Record every validation session with immutable metadata: preset version and diff, ruleset and thresholds, sample selection method and composition, per-image results and annotations, aggregate metrics, time/cost estimates, user decisions, and any overrides. Provide searchable history, sharable links, and export (PDF/CSV) for compliance and collaboration. Support retention policies by workspace and enforce role-based access to reports and sample outputs. Enable one-click rollback to a previously validated preset version.

Acceptance Criteria

Immutable Session Recording

Given a completed batch validation run in workspace W When the system persists the session Then the session record includes non-null fields: session_id, created_at (UTC ISO-8601), created_by_user_id, workspace_id, preset_id, preset_version, preset_diff (JSON Patch), ruleset_id, ruleset_thresholds, sample_selection_method, sample_composition, per_image_results (image_id, pass/fail reasons, annotations, visual_diff_uri), aggregate_metrics (pass_rate, avg_score, stdev), estimated_time_ms, estimated_cost_cents, user_decision, overrides (approver_id, rationale) And subsequent attempts to modify any of these fields return HTTP 409 and are audit-logged with actor_id and timestamp And repeated reads of the session return the same SHA-256 checksum for the persisted payload

Searchable Validation History & Filters

Given a workspace with >= 1,000 validation sessions over the last 90 days When a user applies filters (date range, preset_version, ruleset_id, user_decision, pass_rate >= threshold) and a full-text query on History Then only matching sessions are returned And the first page (<= 50 rows) renders within 2000 ms at p95 And results are sortable by created_at and pass_rate And the full-text query matches across metadata and per-image annotations And an empty state is shown when no records match

Role-Based Access Enforcement

Given RBAC roles Owner, Admin, Editor, Viewer, External Reviewer with defined permissions When a user attempts to view, export, share a report, or download sample outputs Then access is granted only if the role has the corresponding permission in that workspace And unauthorized attempts return HTTP 403 and are audit-logged with actor_id, action, resource_id And sample output URIs are time-limited and require the same authorization context

Shareable Link Lifecycle

Given a user with Share permission creates a shareable link to a specific session When they set scope (report-only | report+samples) and expiry (1 hour to 30 days) Then the system issues a signed URL that grants exactly the requested scope until expiry And revoking the link invalidates access within 60 seconds And each access is logged (viewer_id or IP, timestamp, user_agent) And the shared view is read-only and hides destructive actions

Export Reports (PDF/CSV) with Data Fidelity

Given a session record with up to 500 images When a user exports PDF and CSV Then the PDF includes metadata, aggregate metrics, per-image summaries (image_id, pass/fail reasons), visual diff thumbnails or URIs, and a document hash And the CSV contains one row per image with stable column headers and UTC timestamps And generation completes within 10 seconds at p95 And the contents of both exports match the persisted session data exactly

Workspace Retention Policies & Purge

Given workspace retention policy R days and optional legal holds on sessions When a session reaches age > R and has no active legal hold Then its report, exports, share links, and sample outputs are permanently deleted And search indexes are updated and access attempts return HTTP 410 Gone And purge runs at least daily and emits an audit log entry per session And sessions on legal hold are excluded from purge until the hold is removed

One-Click Rollback to Validated Preset Version

Given an authorized user views a previously validated preset version in History When they click Rollback and confirm Then that version becomes the active preset for the workspace within 60 seconds And an audit entry links the rollback action to the source session and prior active version And new validations started after propagation use the rolled-back version And rollback is blocked if there are uncommitted preset edits, showing a clear error message

RuleStream

Always-current rule engine that auto-syncs marketplace specs by region and category. Get change alerts with plain‑language summaries, auto-revalidate impacted images, and see exactly what needs updating—eliminating surprise rejections and last‑minute rework.

Requirements

Marketplace Spec Auto-Sync

"As an e-commerce seller, I want PixelLift to automatically keep marketplace rules up to date for my regions and product categories so that my images always meet current requirements without me having to track changes manually."

Description

Continuously ingest and normalize marketplace compliance specifications (e.g., Amazon, Etsy, eBay, Shopify) by region and category via scheduled pulls and webhook triggers. Map external rule fields (dimensions, background, watermark, file size/format, text overlays, margins) into PixelLift’s internal rule schema and category taxonomy. Provide resilient caching, rate limiting, and fallback to last-known-good rules on source outages. Detect deltas between versions to mark impacted categories/regions and set effective dates. Expose a health panel showing last sync time, source URLs, and any parser errors. Enables always-current compliance without manual updates, reducing listing rejections and rework.

Acceptance Criteria

Scheduled Pull Normalizes Multi-Market Rules by Region & Category

Given scheduled sync interval is configured to 60 minutes and sources for Amazon, Etsy, eBay, and Shopify are enabled When the scheduler runs at the configured interval Then the system fetches specs for each enabled marketplace-region-category combination from the configured source URLs And parses and normalizes fields into the internal rule schema: dimensions (unit-normalized), background, watermark, file size (bytes), file format (enum), text overlays, margins (percent or pixels) And maps each rule to the internal category taxonomy ID for the corresponding marketplace-region-category And persists a normalized RuleSet with keys {marketplace, region, categoryId, versionId} including sourceUrl and fetchedAt timestamps And records metrics per marketplace for requests made, RuleSets stored, and failures And completes without error with success rate 100% for reachable sources

Webhook Change Event Triggers Idempotent Delta Sync

Given a valid marketplace webhook notification for a specific marketplace-region-category with a unique changeId is received When the webhook is processed Then the system fetches the latest source spec and computes a field-level delta against the last stored version And creates a new version only if a non-empty delta exists And sets version metadata: versionId, changeId, effectiveDate (from source or now), and delta summary And ensures idempotency by ignoring duplicate webhooks with the same changeId for 24 hours And enforces a single in-flight sync per marketplace-region-category via locking

Version Delta Detection Marks Impacted Categories/Regions and Effective Dates

Given two consecutive RuleSet versions exist for a marketplace-region-category When any of the mapped fields (dimensions, background, watermark, file size/format, text overlays, margins) differ between versions Then the system generates an ImpactRecord listing impacted marketplace, region, and categoryId with change types per field And marks the affected marketplace-region-category as "Impacted" until the effectiveDate passes And assigns effectiveDate from the source if provided; otherwise sets effectiveDate to the ingestion timestamp And emits a RuleSetChanged event containing marketplace, region, categoryId, previousVersionId, newVersionId, effectiveDate

Rate Limiting, Caching, and Retry Backoff Protect Source APIs

Given provider rate limits and a cache TTL are configured When the sync client calls provider APIs Then requests are paced so that the configured rate limits are never exceeded And responses are cached per source URL for the configured TTL and served from cache when within TTL And on HTTP 429/5xx/timeouts, the client retries up to 3 times with exponential backoff starting at 1s and jitter And after retries are exhausted, the sync marks the source as DEGRADED and continues with other sources

Fallback to Last-Known-Good Rules on Source Outage

Given a source API experiences sustained failures (>=3 consecutive attempts within 15 minutes) When a sync is attempted Then the system serves and exposes the last-known-good RuleSet for all affected marketplace-region-category combinations And flags the affected scope with usingFallback=true and records outage details And prevents deletion or overwriting of the last-known-good data until a successful sync occurs And clears the fallback flag automatically on the next successful sync

Health Panel Exposes Sync Status, Source URLs, and Parser Errors

Given the health API endpoint /rulestream/health is queried When the request is made with or without filters (marketplace, region, categoryId, status) Then the response includes for each marketplace-region-category: lastSyncStartedAt, lastSyncSucceededAt, sourceUrl(s), status (OK/DEGRADED/ERROR), currentVersionId, parserErrors[] And the endpoint responds within 800 ms for up to 10,000 records And parser errors include categoryId, field, message, and sample payload snippet And the data reflects the latest completed sync run

Schema Mapping Completeness for Core Fields

Given a source spec payload contains fields for dimensions, background, watermark, file size, file format, text overlays, and margins When the payload is parsed Then 100% of required fields are mapped to the internal schema or a parser error is recorded with details And units are normalized (e.g., inches/cm to mm) and enumerations are validated against allowed values And invalid or unsupported fields do not block processing of supported fields; partial mappings are flagged with severity=WARNING And the stored RuleSet passes schema validation with no critical errors

Plain-Language Change Summaries

"As a catalog manager, I want plain-language alerts explaining what changed and which listings are affected so that I can quickly assess impact and prioritize fixes."

Description

Generate human-readable summaries for rule changes with clear highlights of what changed, why it matters, affected categories/regions, effective dates, and severity (blocking vs advisory). Provide concise diffs (before/after) and link to full rule details. Deliver alerts across channels (in‑app notifications, email, Slack/webhook) with actionable CTAs to review impact or start revalidation. Summaries use non-technical language and examples (e.g., “Main image must have pure white background (#FFFFFF)”); localize terms and units per user locale. Improves awareness and reduces time to understand and act on changes.

Acceptance Criteria

In-App Alert: Plain-Language Summary with CTAs

Given a marketplace rule update affects at least one category or region in the user’s workspace When RuleStream syncs changes Then an in-app notification is created within 15 minutes containing: a human-readable title, what changed, why it matters, affected categories/regions, severity (Blocking or Advisory), effective date/time, and a concise before/after diff snippet, plus a link to full rule details And Then the notification shows a Review Impact CTA that opens the impact view filtered to the specific change And Then the notification shows a Start Revalidation CTA only if impacted images > 0; otherwise the CTA is hidden or disabled with an explanation And Then clicking Start Revalidation enqueues revalidation for all impacted images and displays progress status in-app

Email Notification: Localized Summary with Before/After Diff

Given a user has email alerts enabled and a locale/time zone set When a rule change is synced that impacts the user’s selected marketplaces/regions/categories Then an email is sent within 15 minutes with a subject that includes severity, marketplace, region, and a short change summary And Then the email body includes: what changed, why it matters, affected categories/regions, effective date/time in the user’s time zone, a concise before/after diff, at least one simple example, and links to Review Impact and full rule details And Then terms, dates, color codes, and units are localized to the user’s locale (e.g., cm vs inches, date format, decimal separators) without altering numeric accuracy And Then the email is sent once per unique rule change per workspace (no duplicates) and includes a Manage Notifications link respecting user preferences

Slack/Webhook Delivery: Actionable Alert and Structured Payload

Given a workspace has Slack integration configured When a relevant rule change is synced Then a Slack message posts within 15 minutes using clear, plain language and includes severity color/label, what changed, why it matters, affected categories/regions, effective date/time, a concise before/after diff snippet, and links to Review Impact and full rule details And Then all links in the Slack message deep-link to the corresponding in-app views Given a workspace has a generic webhook configured When a relevant rule change is synced Then a POST is delivered with a JSON payload that includes: change_id, severity, marketplace, regions, categories, effective_at (ISO 8601), summary_text, diff.before, diff.after, examples[], urls.review_impact, urls.rule_details, locale, impacted_counts, created_at And Then the webhook is HMAC-SHA256 signed via shared secret with X-Signature header, uses an Idempotency-Key, and retries up to 3 times with exponential backoff on 5xx responses

Diff Generation: Concise, Accurate Before/After Highlights

Given the previous and current versions of a marketplace rule When generating the change summary Then the before/after diff highlights only modified elements (added/removed/changed) and preserves exact tokens (e.g., “#FFFFFF”) And Then each side of the diff is truncated to a maximum of 240 characters with ellipses if longer, and provides a View full rule link And Then the diff includes one positive and one negative example illustrating compliance vs non-compliance And Then visual diff indicators meet accessibility contrast (WCAG AA) and include text labels for screen readers

Severity and Effective Date Display Logic

Given rule metadata indicates enforcement level When summarizing Then severity is mapped to Blocking or Advisory and displayed consistently across all channels with corresponding label and color Given the rule has an effective date/time When summarizing Then the effective date/time is shown in the user’s time zone and formatted per locale; if effective immediately, display Effective now And Then summaries for Blocking changes include an Action required badge; Advisory changes include a Recommended badge

Plain-Language Quality and Examples

Given technical rule text is available When creating the human-readable summary Then the text is non-technical, avoids undefined jargon, and achieves a readability score at or below 8th-grade level (Flesch-Kincaid Grade <= 8.0) And Then the summary includes at least one concrete example with localized units/terms (e.g., “Main image must have a pure white background (#FFFFFF)”) and is <= 120 words And Then prohibited/ambiguous terms list (e.g., “utilize”, “henceforth”, “hereunder”) does not appear in the summary

Impact Review and Revalidation Flow

Given a rule change is detected When the user opens Review Impact from any channel Then the impact view is scoped to the change_id and lists impacted assets grouped by severity (Blocking vs Advisory), with exact counts And Then if auto-revalidation is enabled for the workspace, impacted assets are queued within 15 minutes and results update the counts in real time; otherwise the user can trigger Start Revalidation from the view And Then revalidation job status (queued, running, completed) and outcome (Pass/Fail) are visible, and completing revalidation updates the alert to Resolved if all assets pass

Impact Analysis & Auto-Revalidation

"As a merchandising lead, I want PixelLift to automatically revalidate affected images when rules change so that I can see exactly what will fail and fix it before listings are rejected."

Description

Identify all assets, listings, and style-presets impacted by rule deltas using category/region mapping and historical validation results. Automatically queue revalidation jobs to test images against new rules (e.g., background color, aspect ratio, edge whitespace, watermarks, text overlays, file type/size). Produce pass/fail results with reasons, confidence scores, and remediation tags. Update dashboards with affected counts, risk levels, and deadlines based on effective dates; support filtering by marketplace, region, category, and account. Minimizes surprise rejections by proactively catching upcoming noncompliance.

Acceptance Criteria

Impact Analysis on Background Color Rule Delta

Given a published rule delta changing background color for marketplace=MKT-A, region=EU, category=Shoes with effective_date set When impact analysis runs Then 100% of assets, listings, and style-presets historically validated under (MKT-A, EU, Shoes) are evaluated within 10 minutes And the impacted set includes all and only items that would fail under the new rule And each impacted item record includes id (asset/listing/preset), marketplace, region, category, impacted_rule_ids, effective_date, and last_validated_at

Auto-Queue Revalidation for Aspect Ratio Change

Given impacted items exist for a rule delta on aspect_ratio When the delta is published Then revalidation jobs for all impacted items are enqueued within 5 minutes And job priority is ordered by ascending effective_date and higher risk_level first And the queue prevents duplicate jobs per (asset_id, rule_version) pair And a retry policy (max 3 attempts, exponential backoff up to 15 minutes) is applied for transient failures

Pass/Fail Results with Reasons, Confidence, and Remediation Tags

Given a revalidation job completes for an asset When rules are evaluated Then a result is produced with status PASS or FAIL for the asset And for each failed rule the result includes rule_id, reason_code, human_readable_reason, confidence_score between 0 and 1 with two-decimal precision, and at least one remediation_tag And the result is persisted and available via dashboard and API within 1 minute

Dashboard Affected Counts, Risk Levels, and Deadlines

Given at least one rule delta with impacted items exists When the dashboard loads Then it displays total impacted counts and breakdowns by marketplace, region, category, and account And shows risk_level as High when effective_date <= 7 days and impacted_count > 0, Medium when 8–30 days, Low when > 30 days And displays deadline equal to the rule's effective_date for each group And all aggregates refresh within 1 minute after new results are persisted

Filtering by Marketplace, Region, Category, and Account

Given the dashboard contains impacted data across multiple marketplaces, regions, categories, and accounts When the user applies filters marketplace=MKT-A, region=US, category=Apparel, account=ACC-123 Then lists, charts, and counts display only items matching all selected filters And the URL/query state reflects the filters for shareable deep links And clearing filters restores unfiltered totals within 2 seconds

Idempotent Revalidation on Rule Version Updates

Given a rule delta is superseded by a new version before its effective_date When the new version is received Then queued jobs for the old version are cancelled within 2 minutes And assets already revalidated against the old version are requeued only if their expected outcome differs under the new version And the system guarantees no more than one active job per (asset_id, rule_version) at any time

One-Click Remediation Suggestions

"As a seller, I want one-click, compliant fixes for failing images so that I can remediate issues at scale without manual editing."

Description

Provide prescriptive, auto-generated fixes for failed validations and enable one-click batch remediation. Supported actions include adjusting canvas to required aspect ratio, adding padding for edge whitespace, enforcing pure white or compliant background, converting file format/quality to meet size caps, and removing disallowed text/watermarks. Integrate with PixelLift style-presets to suggest safe preset updates and version bumps; allow preview and selective apply with rollback. Track changes back to the specific rule version that prompted the fix. Accelerates recovery from rule changes while preserving brand consistency.

Acceptance Criteria

Auto-Generated Fix Suggestions for Failed Validations

Given a batch upload contains images failing marketplace rules by region and category When the user opens the RuleStream Remediation panel for that batch Then the system displays for each failed rule on each image: a prescriptive fix action, a plain‑language explanation referencing rule name and version, a preview thumbnail, and estimated impact (aspect ratio, background, file size) And suggestions are generated for up to 500 images within 60 seconds And every suggestion is traceable to the specific rule ID and version that triggered it

One-Click Batch Remediation Execution and Auto-Revalidation

Given the user selects any subset of suggested fixes across the batch When the user clicks Remediate All Then the system applies the selected fixes atomically per image, creating a new image version and preserving the original And completes processing of 500 images within 10 minutes under normal load And displays a completion summary with counts: succeeded, failed, retried, skipped And automatically revalidates all remediated images against the active rule set And shows pass/fail per image with links to any remaining issues And partial failures do not block other images; failed items have actionable error messages and a retry option

Aspect Ratio and Edge-Whitespace Compliance via Canvas Adjust/Padding

Given images fail aspect ratio or edge‑whitespace rules When the user accepts the "Adjust canvas/add padding" suggestion Then each output image matches the required aspect ratio within ±0.01 tolerance And minimum edge whitespace meets or exceeds the rule requirement And no subject clipping is introduced; the subject remains fully visible And revalidation for aspect ratio and edge‑whitespace rules passes And output dimensions and file size remain within marketplace caps

Background Compliance and Text/Watermark Removal

Given images fail background or disallowed text/watermark rules When the user accepts the "Enforce background and remove text/watermarks" suggestion Then background is set to the rule‑compliant color/template (e.g., pure white #FFFFFF) per rule And OCR/watermark detection confidence for disallowed elements is below the rule's rejection threshold And no text overlays remain except those explicitly allowed by the rule And revalidation for background and text/watermark rules passes

Format/Quality Conversion to Meet File Size Caps

Given images exceed file size caps or have non‑compliant format/color profile When the user accepts the "Convert format/quality" suggestion Then output format, color profile, and metadata match the rule requirements And file size is ≤ the marketplace cap while maintaining SSIM ≥ 0.98 versus the input And pixel dimensions meet min/max constraints And revalidation for file type, color profile, and size passes

Style-Preset Safe Update, Preview, Selective Apply, and Rollback with Traceability

Given a rule change conflicts with the current PixelLift style‑preset When the user opens preset suggestions Then the system proposes a new preset version with only rule‑safe parameter changes, listing the changed parameters And the user can preview side‑by‑side before/after on sample images within 3 seconds per preview And the user can selectively apply the new preset version to chosen catalogs or images And a one‑click rollback restores prior image versions and reverts the preset to the previous version And all actions are logged with timestamp, user, impacted assets, and the originating rule ID/version And remediated images are revalidated and results recorded

Rule Versioning & Audit Trail

"As a compliance officer, I want a complete versioned history of rules, validations, and fixes so that I can demonstrate due diligence and trace issues when marketplaces question a listing."

Description

Maintain immutable, versioned snapshots of marketplace rules per source/region/category with timestamps, source references, and content hashes. Store validation outcomes and remediation actions per asset, linked to the rule version in effect at the time. Provide exportable audit logs (CSV/JSON/PDF) and APIs for compliance evidence, including who approved changes and when. Support rollback to prior rule mappings if a feed is erroneous. Ensures traceability for enterprise customers and simplifies dispute resolution with marketplaces.

Acceptance Criteria

Create Immutable Rule Snapshot on Sync

Given a new or changed marketplace rule feed is detected for a specific source/region/category When the sync job runs Then the system creates a new rule version snapshot with fields: versionId (UUID), sourceReference, region, category, fetchedAt (ISO 8601 UTC), contentHash (SHA-256), and rawRulePayload And the snapshot content is immutable; any update attempt returns 409 and does not alter contentHash or payload And retrieving by versionId returns the exact stored snapshot bytes And if the computed contentHash matches the latest active snapshot for the same source/region/category, no new version is created and the sync is recorded as idempotent

Link Validation Outcomes to Rule Version

Given an asset is validated against marketplace rules When validation completes Then the system stores a validation record with assetId, ruleVersionId used, validatorEngineVersion, validatedAt (UTC), outcome (Pass/Fail), and violations[] And the record persists unchanged even if newer rule versions are activated later And remediation actions (manual or automated) are appended with actionType, actorId, actionAt (UTC), and reference the originating validation recordId And API/UI retrieval returns a complete chronological history per asset including all validation records and remediation actions

Export Audit Logs for Compliance

Given a user with audit:read scope requests an export via API or UI with filters (date range ≤ 90 days, region, category, assetIds[], outcome) When the export is generated Then CSV and JSON files are produced for up to 100,000 records within 2 minutes and a PDF summary for up to 5,000 records within 2 minutes And each record includes assetId, ruleVersionId, ruleFetchedAt, sourceReference, region, category, contentHash, outcome, violations, remediation actions, actorIds, decision/approval info, and timestamps (UTC) And download URLs are returned with SHA-256 checksums and 24-hour expiry And exports larger than 100,000 records are paginated via a cursor-based API without data loss or duplication across pages And all export requests are themselves logged in the audit trail with requesterId, requestedAt, filters, and file checksums

Record Rule Change Approvals

Given a proposed rule mapping change requires approval before activation When an approver with role Compliance Admin approves or rejects the change Then an approval record is stored with approverId, decision (Approve/Reject), decisionAt (UTC), changeSummary, priorVersionId, newVersionId, and optional rationale And the approval record is tamper-evident via an HMAC signature over its fields using the organization key And activation of a rule version without an approval record returns 403 and the version remains inactive And audit queries by versionId return who approved and when

Rollback to Prior Rule Mapping

Given an active rule version is determined erroneous for a source/region/category When a user with rollback permission selects a prior version to activate Then the selected prior version becomes the active mapping within 60 seconds and a rollback event is recorded with requesterId, reason, priorActiveVersionId, newActiveVersionId, and timestamp (UTC) And no snapshots are deleted or modified; only the active pointer changes And all impacted assets are queued for revalidation against the restored version within 15 minutes And notifications are sent to subscribed users indicating rollback details and revalidation status

Auto-Revalidate on Rule Update

Given a new rule version becomes active for a source/region/category When activation occurs Then impacted assets in that scope are identified and queued for revalidation within 5 minutes And 95% of queued assets up to 50,000 complete revalidation within 60 minutes And new validation records reference the new ruleVersionId while preserving prior records intact And assets that transition from Pass to Fail are flagged and included in a change-impact report accessible via API

Rule Testing Sandbox

"As a brand ops manager, I want to test upcoming rules against my catalog and presets so that I can anticipate failures and adjust workflows before changes go live."

Description

Offer a sandbox to simulate current, upcoming, or custom rule sets against selected assets and style-presets without affecting production. Allow users to import proposed marketplace changes or upload custom rule JSON for private channels, run validations, and preview remediation outcomes. Provide what-if comparisons (current vs upcoming) and estimated effort to fix. Enable promotion of a tested rule set to production with safeguards and approvals. Helps teams prepare for changes and de-risk rollouts.

Acceptance Criteria

Upload and Validate Custom Rule JSON

- Given a user with Rules:Manage permission uploads a custom rule JSON file (<=10 MB) conforming to PixelLift RuleStream schema v1.2, When validation runs, Then the system accepts the upload, displays parsed rule count, channel=Private, and assigns a rule-set version ID. - Given a JSON that violates schema or has syntax errors, When validation runs, Then the system rejects the upload and returns a clear error list with file name, line, column, and up to 100 issues; no rule set is created. - Given duplicate rule IDs or key collisions, When validation runs, Then the system blocks save and prompts to auto-namespace or fix conflicts before proceed. - Given references to unknown marketplace categories or regions, When validation runs, Then the system requires mapping to known categories/regions before enabling Run; unresolved references keep status=Draft.

Import Proposed Marketplace Rule Changes

- Given a supported marketplace, region, and category are selected, When the user clicks Import Upcoming Changes, Then the system fetches the latest proposed rules, tags them with Effective Date, and shows a plain-language summary with counts of Added/Modified/Removed rules and links to sources. - Given the marketplace feed is unavailable, When import is attempted, Then the system shows a retry/backoff status and offers manual file import; successful manual import is tagged Source=Manual. - Given an upcoming rule set is imported, When saved, Then it is read-only (annotatable), versioned, and available for sandbox runs without altering production rules.

Non-Destructive Sandbox Validation Run

- Given a user selects up to 10,000 assets and one or more style-presets, and selects a rule set (current, upcoming, or custom), When Run Validation in Sandbox is started, Then the system validates all selected combinations without writing to production assets, metadata, caches, or publish statuses. - Given the run completes, When results are stored, Then they are saved under a Sandbox Project ID with full audit log and auto-expire in 30 days; production automations are not triggered. - Given asset selection exceeds 10,000, When run is initiated, Then the system blocks start and prompts to split the batch or request a quota increase.

What-If Comparison: Current vs Upcoming Rules

- Given the same asset set is evaluated against Current and Upcoming rule sets, When the comparison completes, Then the system displays side-by-side pass/fail totals, newly failing/passing asset lists, and the specific rules causing status changes. - Given comparison results are shown, When the user exports, Then a CSV export containing asset IDs, rule IDs, current status, upcoming status, and delta is downloadable. - Given per-rule estimated fix time defaults (minutes) are configured, When the comparison identifies failures, Then the system displays total estimated effort (hours), average per asset, and breakdown by rule.

Remediation Preview for Failed Assets

- Given failed assets have auto-remediable rules, When the user requests Preview Fix, Then the system generates non-destructive preview thumbnails (min 1024px) showing proposed changes with visual diffs within 60 seconds per asset, without altering originals. - Given an issue is not auto-remediable, When viewing details, Then the system provides plain-language remediation guidance referencing the violated rule and required change. - Given previews are generated, When the user downloads the remediation plan, Then a JSON/CSV containing asset IDs, proposed actions, and estimated effort is provided.

Governance and Safeguards for Promotion to Production

- Given a sandbox rule set has passed review, When Promote to Production is initiated, Then at least two distinct approvers with Rules:Approve must approve; the requester cannot self-approve. - Given promotion pre-checks are configured (0 critical fails, <=5% non-critical fails), When the system runs a gating validation on a defined sample or full set, Then promotion is blocked unless thresholds are met or documented waivers exist. - Given promotion succeeds, When finalization occurs, Then the system records an immutable audit entry (timestamp, approvers, rule-set hash) and provides one-click rollback to the previous production version.

Performance and Progress for Batch Sandbox Runs

- Given a sandbox run includes up to 5,000 assets, When validation starts, Then 95% of runs complete within 5 minutes and display a live progress indicator with remaining time estimate. - Given a sandbox run is executing, When the user pauses or cancels, Then the system safely pauses/cancels within 30 seconds and preserves partial results for later resume. - Given runs up to 10,000 assets, When completed, Then per-asset and per-rule timing metrics are available for download to support capacity planning.

Category IQ

Automatically identifies the correct product category from image cues and listing metadata, then applies the right, category‑specific checks. Cuts false flags and ensures precise validation (e.g., apparel vs. jewelry nuances) without manual mapping or guesswork.

Requirements

Multimodal Category Classification Engine

"As a boutique seller, I want the system to automatically detect the correct category from my photos and listing details so that I don’t have to map categories manually and can trust downstream checks."

Description

Build a production-grade classifier that fuses image features with listing metadata (titles, tags, attributes) to predict the correct product category from PixelLift’s unified taxonomy. Must output category ID, full path, and confidence score; support top-k predictions and out-of-distribution detection; be resilient to background removal artifacts and partial occlusions. Expose as a horizontally scalable microservice (REST/gRPC) with p95 latency ≤300 ms per item at batch size 32, autoscaling, health checks, and detailed metrics/tracing. Enable safe, zero-downtime model updates via canary and version pinning.

Acceptance Criteria

Batch Classification Output Schema and Top‑K Results

Given a request to classify a batch of items (batch_size ≤ 128) via REST /v1/classify or gRPC Classify with images and listing metadata When the request is processed Then each item response includes: category_id (string in unified taxonomy), full_path (string "Department>Category>Subcategory"), confidence (0.0–1.0), and top_k results each with category_id and confidence sorted by descending confidence And the number of top_k results equals the requested k (default 5, max 20) And responses preserve input order and include the client-supplied item_id And all returned category_id values exist in the taxonomy snapshot for the returned model_version

Multimodal Accuracy on Unified Taxonomy Benchmark

Given the PixelLift validation set v1.0 (stratified by category; n ≥ 50,000) When evaluating the production model with default settings Then top-1 accuracy ≥ 92% and top-3 accuracy ≥ 98% overall And weighted F1 ≥ 0.93 overall And per-major-department top-1 accuracy ≥ 88% And expected calibration error (ECE, 15 bins) ≤ 0.05

Out‑of‑Distribution Detection and Unknown Handling

Given an OOD benchmark consisting of non-taxonomy product types and non-product images, and an operational OOD threshold τ When evaluating the service Then AUROC for OOD vs in-distribution ≥ 0.95 and FPR at 95% TPR ≤ 10% And OOD items are returned with ood=true, category_id="unknown", and confidence ≤ 0.20 And in-distribution items are returned with ood=false and in-distribution recall ≥ 95% at τ And τ is configurable per model_version and applied without restart within 60 seconds of change

Robustness to Background Removal and Partial Occlusions

Given a paired dataset of original images and variants with AI background removal artifacts (alpha edges), JPEG compression at Q=60, and 20% area rectangular occlusions When running classification with default settings Then top-1 accuracy on the perturbed set decreases by ≤ 2 percentage points vs the original set And for pairs where original confidence ≥ 0.60, predicted top-1 category matches the original in ≥ 95% of cases And OOD flag rate on transparent PNGs differs by ≤ 2 percentage points from originals

Latency, Throughput, and Horizontal Scalability

Given steady load generated with batch size = 32 and typical payloads When the service runs on the target production instance type per pod Then p95 per-item latency ≤ 300 ms and p99 ≤ 450 ms over a 30-minute window And throughput ≥ 200 items/second per pod at ≤ 85% GPU/CPU utilization And autoscaling increases replicas from min=2 to max=20 within 60 seconds of sustained CPU > 70% or queue backlog > 1000 items, maintaining p95 ≤ 300 ms And request error rate (HTTP 429/503/gRPC UNAVAILABLE) ≤ 0.10% during 10× baseline load for 30 minutes

Service Interfaces, Validation, and Observability

Given clients integrate via REST and gRPC When invoking REST POST /v1/classify or gRPC Classify with a batch payload Then the service validates inputs and returns 400/INVALID_ARGUMENT for schema violations with machine-readable error codes And supports parameters: top_k (1–20), model_version, ood_threshold, and returns model_version in responses And exposes /healthz (liveness), /readyz (readiness), and /metrics (Prometheus) including latency histograms, error rates, model_version labels, and top-k distribution And propagates W3C tracecontext (traceparent) and emits spans per request and per item with attributes: model_version, batch_size, device, latency_ms

Zero‑Downtime Model Updates with Canary and Version Pinning

Given a new model version is deployed behind the service When initiating a canary rollout Then traffic starts at 10% for ≥ 15 minutes and auto-promotes only if canary p95 latency within +5% of baseline, error rate ≤ 0.5%, and shadow top-1 agreement with baseline ≥ 99% And automatic rollback triggers within 2 minutes if any threshold is breached And clients can pin model_version; pinned requests are not routed to canary and remain available during rollout And no downtime occurs (availability ≥ 99.99% and 5xx spike ≤ 0.5% over rollout window)

Adaptive Taxonomy Mapping & Versioning

"As an operations manager, I want Category IQ to stay aligned with marketplace category changes so that validations remain accurate without rework."

Description

Maintain a normalized, versioned category graph aligned to major marketplaces (Shopify, Etsy, Amazon) and custom merchant taxonomies. Provide tools to import external taxonomies, map them to the internal schema, manage synonyms/aliases, and deprecate or merge categories with effective dates. Expose read APIs to resolve current and historical mappings and ensure backward compatibility for existing jobs and presets.

Acceptance Criteria

Shopify/Etsy/Amazon Taxonomy Import and Mapping to Internal Graph

- Given a valid Shopify/Etsy/Amazon taxonomy export (≤50k nodes), When an admin imports it via tooling, Then a new immutable internal taxonomy version is created with a unique version_id and full audit log (actor, checksum, timestamp). - Given repeated import of the same file, When executed, Then the operation is idempotent (0 changes detected). - Given source nodes lacking mappings, When import completes, Then 100% are either mapped to internal categories or reported with actionable errors; import fails and fully rolls back if unmapped nodes > 0. - Given a successful import, When validation runs, Then parent/child integrity is preserved (no cycles, no orphans) and P95 import time ≤ 5 minutes.

Custom Merchant Taxonomy Mapping with Synonyms and Aliases

- Given a merchant uploads a custom taxonomy with synonym/alias columns, When mapping to internal categories, Then each alias resolves to a single canonical internal_category_id and is case- and locale-insensitive. - Given an alias collides across two internal categories, When saving, Then the operation is rejected with a conflict error listing collisions. - Given synonyms are added or removed, When a new taxonomy version is published, Then the change is versioned and historical resolutions continue to honor the prior version. - Given an alias is resolved via the read API, When requested, Then the response returns the canonical internal_category_id and indicates it was resolved via alias.

Scheduled Category Deprecation with Effective Dates and Redirects

- Given a category is scheduled for deprecation with effective_at and optional replaced_by, When current time < effective_at, Then the category remains active and writable. - Given current time ≥ effective_at, When creating new mappings or jobs targeting the deprecated category, Then the operation is blocked and a redirect to replaced_by is suggested if present. - Given existing jobs/presets referencing the deprecated category created before effective_at, When resolving without an explicit timestamp, Then they resolve via their pinned version; When resolving with at ≥ effective_at, Then they return the replacement category (or status=deprecated if none). - Given a deprecation is published, When auditing, Then an immutable audit log entry exists with actor, reason, and effective_at.

Category Merge with Historical Resolution Preservation

- Given categories A and B are merged into category C with effective_at, When resolving with at < effective_at, Then A and B resolve to themselves; When resolving with at ≥ effective_at or without at, Then A and B resolve to C. - Given the merge is committed, When validating graph integrity, Then no cycles or orphaned nodes exist and all synonyms of A and B transfer as aliases of C. - Given presets or jobs referencing A or B, When run after the merge, Then they execute via redirect to C with no configuration changes required and the redirect is logged.

Read API: Resolve Current and Historical Mappings

- Given marketplace_id, marketplace_category_id, and optional at timestamp, When calling the category resolution API, Then it returns 200 with internal_category_id, version_id, and status for known mappings. - Given a deprecated category without at, When calling the API, Then it returns 410 with replaced_by metadata if available. - Given an unknown mapping, When calling the API, Then it returns 404 with error_code=MAPPING_NOT_FOUND. - Given normal system load, When calling the API, Then P95 latency ≤ 200 ms and availability ≥ 99.9% monthly.

Backward Compatibility for Existing Jobs and Presets

- Given a job was created under taxonomy version V, When a new taxonomy version V+1 is published, Then the job completes using V without change and outputs identical internal category IDs to prior runs. - Given a preset references an internal_category_id that becomes deprecated or merged, When the preset is used after the change, Then it auto-resolves to the replacement and logs the redirect in the run metadata. - Given system-wide taxonomy updates, When examining job failure rates, Then the post-update 24-hour failure rate does not increase by more than 0.5 percentage points relative to the 7-day prior baseline. - Given a merchant opts to migrate presets to the latest taxonomy, When using the migration tool, Then a preview shows affected items and the change applies atomically with rollback support.

Category-Specific Validation Rules Engine

"As a seller, I want the correct checks to run for each product type so that issues are caught and fixed according to category nuances."

Description

Implement a declarative rules engine that triggers category-specific validations after classification (e.g., apparel: mannequin/pose compliance and wrinkle detection; jewelry: specular highlight/reflection and macro focus; footwear: pair presence and sole visibility; cosmetics: label legibility and shade swatch; home decor: scale reference). Rules are configurable per merchant and brand, support thresholds and dependencies, and emit pass/fail with structured reason codes and suggested fixes. Integrate with PixelLift’s retouch pipeline to auto-apply corrective actions where possible and re-validate post-fix.

Acceptance Criteria

Post-Classification Apparel Rule Execution

Given an image is classified as category=apparel When the rules engine runs category-specific validations Then it executes only apparel rules: pose_compliance, mannequin_presence_policy, wrinkle_intensity And it applies thresholds from brand override if present, otherwise merchant default And each rule returns status in {Pass, Fail} with a reasonCode and suggestion on Fail And no non-apparel category rule is executed for this image

Jewelry Reflection and Macro Focus Validation

Given an image is classified as category=jewelry When the rules engine validates category rules Then specular_highlight_percentage <= configured threshold results in Pass, otherwise Fail with reasonCode=JEWELRY_GLARE_EXCESS and a suggestion And macro_focus_score >= configured threshold results in Pass, otherwise Fail with reasonCode=JEWELRY_MACRO_FOCUS_LOW and a suggestion And the response includes per-rule metric values and thresholds used

Footwear Pair Presence and Sole Visibility

Given an image is classified as category=footwear When category-specific validations run Then pair_presence is detected for two shoes in frame; otherwise Fail with reasonCode=FOOTWEAR_PAIR_MISSING and a suggestion And sole_visibility_percent for at least one shoe >= configured threshold; otherwise Fail with reasonCode=FOOTWEAR_SOLE_NOT_VISIBLE and a suggestion And only footwear rules are evaluated for this image

Cosmetics Label Legibility and Shade Swatch

Given an image is classified as category=cosmetics and listing metadata contains a shade attribute When category validations run Then for primary images, label_ocr_confidence >= configured threshold; otherwise Fail with reasonCode=COS_LABEL_ILLEGIBLE and a suggestion And a shade_swatch is detected with swatch_area_percent >= configured threshold; otherwise Fail with reasonCode=COS_SWATCH_MISSING and a suggestion And thresholds reflect brand overrides when configured

Auto-Correction Integration and Re-Validation

Given a rule evaluation fails and has a mapped auto-corrective action with autoFixEnabled=true When the engine triggers the retouch pipeline for that action Then the engine re-validates the previously failed rule(s) exactly once on the corrected image And if the rule passes after correction, the result records autoFixApplied=true, fixAction code, and before/after metric values And if the rule still fails, the result records autoFixApplied=false and updated metrics with the same reasonCode and a suggestion And the job completes with consolidated results for the original and re-validated evaluations

Merchant/Brand Config Overrides and Rule Dependencies

Given a merchant default config and a brand-level override that raises the wrinkle_intensity threshold and disables mannequin_presence_policy When an apparel image tagged with that brand is evaluated Then wrinkle_intensity uses the brand override threshold And mannequin_presence_policy is not executed and does not appear in evaluated rules And for images where human_presence=false, pose_compliance is not executed and does not appear in evaluated rules And images without the brand tag use merchant default thresholds

Structured Result Envelope with Reason Codes and Fix Suggestions

Given any category validation run completes When the engine emits results Then the top-level payload includes assetId, merchantId, brandId, category, configVersion, engineVersion, evaluatedAt, and overallStatus derived from per-rule statuses And each evaluated rule entry includes ruleCode, category, status in {Pass, Fail}, metric name(s) with numeric values, threshold(s), severity, reasonCode (on Fail), suggestion (on Fail), autoFixAttempted, autoFixApplied, and fixAction (if applied) And the payload validates against the published JSON schema without errors

Confidence Thresholds & Human-in-the-Loop Review

"As a catalog manager, I want low-confidence items routed to a quick review flow so that I can resolve edge cases fast without slowing the batch."

Description

Provide configurable per-merchant thresholds for auto-assign vs. review. For low-confidence or conflicting metadata cases, surface top-3 category suggestions with rationales and allow one-click selection or keyboard-driven bulk actions. Support review queues, SLAs, and notifications. After resolution, the system re-runs validations and records the decision for learning and audit.

Acceptance Criteria

Per‑Merchant Confidence Threshold Configuration

Given I am a merchant admin in PixelLift settings When I configure AutoAssignThreshold and ReviewThreshold values between 0.00 and 1.00 with two‑decimal precision Then the form validates the range, prevents invalid input, and shows default values of 0.85 (auto‑assign) and 0.50 (review) And saving the settings versions the change with timestamp, actor, previous value, and merchant ID And the new thresholds take effect for new ingestions within 1 minute and apply only to my merchant’s items

Auto‑Assign on High Confidence Without Metadata Conflict

Given an item is ingested and Category IQ returns a top‑1 category with probability p And the merchant’s AutoAssignThreshold = Ta And no metadata conflict is detected When p ≥ Ta Then the system auto‑assigns the top‑1 category within 30 seconds And immediately runs the category‑specific validations And logs an audit entry with p, Ta, selected category, and rationale And the item bypasses the review queue

Top‑3 Suggestions for Low Confidence or Conflicting Metadata

Given Category IQ returns probabilities for categories and the merchant thresholds Ta (auto) and Tr (review) When p < Ta or a metadata conflict is detected (metadata‑derived category ≠ top‑1 image category) Then the UI displays the top‑3 category suggestions sorted by probability with confidence scores and one‑sentence rationales And the reviewer can apply any suggestion with a single click And applying a suggestion updates the category in under 1 second and removes the item from the queue And the decision is logged with all top‑3 suggestions and confidences

Keyboard and Bulk Actions in Review Queue

Given a reviewer is focused on the review queue When they navigate with Arrow/J/K keys and open the suggestion picker with Enter Then pressing 1/2/3 selects the corresponding suggestion and applies it in under 1 second And Shift+Arrow or Space allows multi‑select of items And choosing a bulk action to apply suggestion index (1/2/3) applies to up to 200 selected items within 5 seconds And a results summary shows success and per‑item failures without losing selection context

SLA Tracking and Reviewer Notifications

Given the merchant configures a review SLA duration and notification channels (email/Slack/webhook) When an item enters the review queue Then an SLA deadline is computed in the merchant’s time zone and displayed with a countdown And a reminder is sent at 15 minutes before deadline to assigned reviewers And an escalation notification is sent upon breach to the configured channel(s) And all notifications are logged with timestamp, recipients, and delivery status

Post‑Resolution Re‑Validation

Given a reviewer selects a category (via single or bulk action) When the decision is saved Then category‑specific validations automatically re‑run and results are available within 10 seconds And if all validations pass, the item status updates to Validated and downstream workflows resume And if any validation fails, failures with reasons are shown and the item remains in Needs Fix until re‑run passes

Decision Recording for Learning and Audit Export

Given a classification decision occurs (auto‑assign or human selection) When the decision is finalized Then an immutable audit record stores merchant ID, item ID, actor, timestamps, thresholds in effect, conflict flags, top‑3 suggestions with confidences, chosen category, rationale, and validation outcomes And human corrections are queued for the learning pipeline within 5 minutes And an authorized merchant admin can export audit records via API for a date range (≤100k rows) as CSV or JSON within 2 minutes

Batch Processing & Throughput Guarantees

"As a user uploading a large catalog, I want Category IQ to process quickly at scale so that my editing workflow isn’t blocked."

Description

Enable high-throughput processing for batches of 100–10,000 items with parallel inference, autoscaling across GPU/CPU nodes, and backpressure-aware job orchestration. Targets: sustain 1,500 items/min per node and complete 1,000-item batches with end-to-end p95 under 5 minutes. Provide resumable jobs, idempotent tasking, retries with exponential backoff, and real-time progress via WebSockets and webhooks.

Acceptance Criteria

Sustain 1,500 Items/Minute Per Node

Given a single production node under normal operating conditions and representative item mix When a steady-state load is applied for at least 10 consecutive minutes Then the node sustains >= 1,500 processed items per minute measured over rolling 1-minute windows And the item-level error rate is <= 0.5% And the input queue depth does not increase over the interval (net drain >= 0)

1,000-Item Batch p95 End-to-End Under 5 Minutes

Given a 1,000-item batch submitted via API with autoscaling enabled When processing begins under normal production conditions Then the end-to-end latency (submission to final completion webhook delivery) for >= 95% of items is <= 5 minutes And the batch completes with 100% of items either succeeded or placed in a dead-letter list with error details And WebSocket progress indicates >= 95% completion by 5 minutes

Autoscaling Across GPU/CPU Nodes to Clear Backlog

Given the global queue backlog exceeds 2x the sustainable per-node rate for 60 seconds When autoscaling evaluates capacity Then additional GPU/CPU worker nodes are provisioned within 60 seconds to achieve a processing rate greater than the arrival rate And backlog begins to decrease within 2 minutes of scale-out And no in-flight tasks are dropped during scale-out or scale-in And scale-in occurs only after backlog remains < 0.5x sustainable rate for 10 minutes

Backpressure-Aware Orchestration and Ingestion Throttling

Given worker queues exceed the target wait threshold of 30 seconds When additional batch submissions arrive Then the ingestion API responds with HTTP 429 and a Retry-After header reflecting current drain capacity And the orchestrator rate-limits dispatch to saturated nodes so queue wait time p95 stays <= 60 seconds And no tasks fail with resource exhaustion due to overload And no message loss occurs in the job queue

Resumable Batches After Network/Worker Interruptions

Given an active batch with some items completed and others pending When the client disconnects or a worker restarts and later recovers Then the batch resumes without reprocessing completed items And the client can query an accurate list of completed, in-progress, and pending item IDs And duplicate outputs produced per batch is 0

Idempotency and Retry with Exponential Backoff

Given a batch submission includes an Idempotency-Key header When the same submission is repeated within 24 hours Then the API returns the original batch ID and status without creating duplicate work or side effects And transient item failures are retried up to 5 attempts with exponential backoff starting at 2 seconds, factor 2, with full jitter capped at 60 seconds And after max attempts the item moves to a dead-letter queue with machine-readable error code and trace ID

Real-Time Progress via WebSockets and Webhooks

Given a client subscribes to WebSocket updates and registers a webhook endpoint When a batch is running Then progress updates are emitted at least every 2 seconds or on >= 1% progress change, whichever is sooner And webhook events (started, progress, completed, failed) are HMAC-SHA256 signed and delivered with at-least-once semantics with retries for 24 hours And event delivery latency p95 from state change to client receipt is <= 3 seconds And WebSocket streams can resume using the last sequence number without loss or duplication

Explainability & Audit Trail

"As a QA lead, I want to see why a category was chosen and what checks ran so that I can verify correctness and train my team."

Description

Expose interpretable signals behind each categorization, including saliency heatmaps for visual cues and highlighted metadata tokens. Display reason codes and rule results in UI and API. Persist detailed audit logs (predictions, confidences, overrides, rules invoked, outcomes) for at least 180 days with export to CSV/NDJSON and searchable trace IDs for support and compliance.

Acceptance Criteria

UI Explainability: Heatmaps, Token Highlights, Reason Codes

Given a completed Category IQ categorization in the UI for a single product image with listing metadata When the user opens the Explainability panel Then a saliency heatmap overlay toggle is visible and defaults to off And enabling the overlay displays the top 3 visual regions ranked by saliency with numeric scores (0–1) and tooltips on hover And the listing metadata shows the top highlighted tokens (minimum 3, maximum 10) contributing to the prediction with contribution scores And a Reason Codes list shows at least 1 and up to 5 codes with human‑readable labels and machine codes And a Rules Evaluated section lists each invoked rule with result (Pass/Fail), threshold(s), input(s), and rule version And all scores in the panel match the API values for the same trace_id within a tolerance of 0.001

API Explainability Payload with Reason Codes and Rules

Given a GET request to /v1/category/explanations/{trace_id} with a valid trace_id When the response returns 200 Then the payload includes: category, confidence (0–1), reason_codes[], rules_invoked[], saliency_map.url, saliency_regions[], metadata_tokens[] with offsets and contribution, and trace_id And each rules_invoked[] item contains: name, version, inputs, thresholds, result (pass|fail), and outcome_notes And reason_codes[] contains code, label, and weight And the response validates against the published OpenAPI schema and is backward compatible with the last minor version And response time p95 ≤ 500 ms without raster saliency_map; ≤ 1500 ms when including raster And if trace_id is not found, Then 404 is returned with error.code="TRACE_NOT_FOUND" and support_contact

180-Day Audit Log Persistence and Retrieval

Given predictions and any overrides are generated When the audit record is written Then it is persisted within 5 seconds and includes: timestamp (UTC ISO‑8601), user/account_id, job_id, trace_id, input_refs, predicted_category, confidence, reason_codes[], rules_invoked[], outcome, override_flag, override_details (if any), and actor And records are retained for at least 180 days and purged on day 181 And retrieval by exact trace_id returns the record with p95 latency ≤ 300 ms And a tamper‑evident hash is stored per record and can be verified via API

Export Audit Logs to CSV and NDJSON with Filters

Given an admin selects a time window and optional filters (account, category, outcome, has_override) When they request an export Then a downloadable file is generated in CSV and NDJSON with identical content And exports include headers/keys matching the audit log schema and include trace_id in every row/object And exports up to 1,000,000 records complete within 10 minutes and are chunked if larger And exports can be requested via API POST /v1/audit/exports and polled at GET /v1/audit/exports/{export_id} And files are UTF‑8 encoded; NDJSON is newline‑delimited; ZIP compression is applied when size > 100 MB

Search and Trace ID-based Case Reconstruction

Given a user has a trace_id from a support ticket When they search in the UI or call GET /v1/audit/records?trace_id={id} Then exactly one matching record is returned (or zero if purged) with full details And trace_id values are unique within the 180‑day retention window And the UI opens a timeline view showing events: prediction, rules evaluation, override (if any), export references And partial search by prefix (first 8 chars) returns the exact match if unique, else prompts to disambiguate

Manual Override Logging and Explainability Update

Given a human reviewer overrides a category in the UI or via API When the override is saved Then the system records override_reason (free‑text up to 280 chars), actor_id, timestamp (UTC), previous_category, new_category, and linkage to original trace_id And the audit record is versioned (v1, v2, …) preserving the original prediction as v1 And explainability views and API reflect override_applied=true and display the override reason and actor And exports include both original and latest outcomes with version metadata

Rule Invocation Trace with Inputs and Outcomes

Given a categorization run uses category‑specific rules When evaluation completes Then the system logs for each rule: rule_id, name, category_scope, version, inputs (with values), thresholds, result, latency_ms, and any error And the UI Rules Evaluated section can be expanded to show inputs and thresholds for each rule And the API returns the same details under rules_invoked[] with consistent ordering And if a rule errors, Then result="error" and the overall prediction includes a reason_code indicating degraded rules evaluation

Continuous Learning from Corrections

"As a product owner, I want the system to improve from user feedback so that accuracy increases over time without manual rule maintenance."

Description

Capture user overrides and validation outcomes into a feedback store and use them to fine-tune ranking or adapters on a scheduled cadence. Run guarded A/B evaluations and monitor precision/recall by category and merchant; alert on degradations >5% and enable one-click rollback to previous model versions. Support per-merchant personalization with caps to prevent overfitting and maintain global performance.

Acceptance Criteria

Feedback Capture from User Overrides

Given a merchant changes the predicted category in Category IQ, When the override is saved, Then a feedback event is written to the feedback store within 5 seconds with fields: event_id (UUID), timestamp (UTC), merchant_id, product_id, original_category, new_category, confidence_score, user_id (hashed), session_id, source=ui, model_version, category_tree_version. Given the same override is retried with the same event_id, When the write is processed, Then the store performs idempotent upsert and retains a single record. Given a batch CSV correction import, When the import completes, Then one feedback event per item is stored with source=batch and a batch_id linking the set. Given transient storage or network errors, When an event write fails, Then the client retries with exponential backoff up to 3 attempts and emits an error metric; overall 24h write success rate >= 99.5% and P95 write latency <= 2s. Given privacy requirements, When the feedback is stored, Then no raw PII is stored (user_id hashed, no emails) and records are encrypted at rest.

Nightly Fine-Tuning with Data Thresholds

Given the nightly scheduler at 02:00 UTC, When the training job triggers, Then it assembles the last 30 days of labeled feedback and validation outcomes partitioned by category and merchant. Given a category-partition has insufficient data, When counts are calculated, Then training for that partition is skipped if total labeled examples < 500 or positives per class < 50, and an 'insufficient_data' event is logged. Given sufficient data for a partition, When training runs, Then it completes within 60 minutes and produces versioned artifacts (semver vX.Y.Z+build), with registry entry including checksum and data snapshot_id for reproducibility. Given training completes, When validation is evaluated, Then precision and recall are computed per category and per merchant and stored in the experiment tracker; if any partition deviates >5% from the last successful validation, the candidate is flagged for guarded A/B only (no auto-promotion).

Guarded A/B Evaluation and Promotion Gate

Given a candidate model version exists, When an A/B experiment is started, Then 10% of traffic is routed to the candidate and 90% to the control with stratified sampling across merchants and top 50 categories. Given the experiment is running, When stop criteria are evaluated, Then it runs until each of the top 20 categories has ≥ 5,000 predictions or 7 days elapse, whichever comes first. Given sufficient sample sizes, When metrics are computed, Then precision, recall, and false-positive rate are calculated per category and per merchant cohort (cohorts with ≥ 500 predictions) with 95% confidence intervals. Given metrics are available, When eligibility for promotion is checked, Then the candidate is promotable only if: (a) overall weighted precision and recall are ≥ control, (b) no category shows > 5% relative degradation in precision or recall with 95% confidence, and (c) no merchant cohort shows > 5% relative degradation. Given eligibility fails, When the gate evaluates, Then the experiment auto-stops, the candidate is rejected, and a notification is sent to the ML channel with links to the report. Given eligibility passes, When promotion occurs, Then the serving registry updates atomically to the new model version and the experiment is archived with final metrics.

Real-time Degradation Monitoring and Alerting

Given any serving model version, When rolling 24h precision and recall per category or merchant drop by > 5% relative to baseline with ≥ 1,000 predictions, Then an alert is sent to Slack #ml-alerts and PagerDuty within 2 minutes. Given an alert is sent, When the payload is constructed, Then it includes model_version, baseline_version, impacted categories/merchants, metric deltas, volume, start time, and dashboard and rollback links. Given the degradation condition clears, When metrics recover within thresholds for 24h, Then the alert auto-resolves and the incident is closed with resolution notes captured. Given persistent degradation > 48h, When auto-remediation is evaluated, Then a recommendation to rollback is posted to the incident with a one-click action link.

One-Click Rollback to Previous Model

Given a current serving model and a previous passing model exist, When a user triggers rollback via UI or API, Then 100% of traffic is switched back to the previous model within 5 minutes with zero failed prediction requests attributable to the switch. Given rollback executes, When system state is recorded, Then the serving registry logs actor, timestamp, from_version, to_version, reason, and request_id, and all new predictions include the rolled_back model_version. Given rollback is initiated, When safety checks run, Then a 1% canary is executed for up to 2 minutes; if canary fails health checks, rollback aborts and an alert is raised; otherwise rollout proceeds to 100%. Given rollback completes, When monitoring runs, Then precision/recall and error rates return to baseline levels within 30 minutes or an incident is opened automatically.

Per-Merchant Personalization with Global Caps

Given merchant-specific feedback exists, When eligibility is evaluated, Then a per-merchant adapter is enabled only if the merchant has ≥ 100 labeled corrections and outcomes in the last 60 days across ≥ 3 categories and each included category has ≥ 30 examples. Given a merchant adapter is trained, When its impact is assessed, Then on a 10% merchant holdout it shows ≥ 3% relative improvement in both precision and recall, and simultaneously the global (all-merchants) holdout shows < 2% relative degradation in either metric. Given personalization weights are applied, When serving constraints are enforced, Then adapter weight norms are clamped to configured caps, and at least 10% of the merchant's traffic is routed to the global model for exploration and drift detection. Given a personalized merchant shows drift, When 7-day rolling metrics degrade by > 3% with ≥ 1,000 predictions, Then the merchant is automatically reverted to the global model and a notification is sent to the account owner and ML channel.

FixFlow

Configurable auto‑fix pipeline that resolves common failures (background, margins, DPI, shadow) with safe thresholds and rollback. Choose when to auto‑apply vs. request review, preview diffs in one click, and ship compliant images faster without compromising brand fidelity.

Requirements

Rule-Based Auto-Fix Engine

"As a boutique owner, I want my product photos auto-corrected for background, margins, DPI, and shadow in one pass so that I can publish a consistent catalog faster without hand-editing."

Description

Implements a configurable pipeline that automatically detects and corrects common image issues (background cleanup, margin normalization, DPI standardization, and shadow reconstruction) using ordered, modular rules. Each rule is toggleable, parameterized, and can be scoped per workspace, brand, style-preset, or marketplace profile. The engine supports batch execution for hundreds of photos, honors preset styles from PixelLift, and records per-step outcomes for observability. It ensures consistent, studio-quality outputs while reducing manual editing time by up to 80% and aligning with brand guidelines across large catalog uploads.

Acceptance Criteria

Scoped, Toggleable Rule Configuration

1) Given a workspace W with defaults and overrides at brand B, style-preset S, and marketplace profile M, When an image tagged (B, S, M) is processed, Then rule parameters resolve using scope precedence S > M > B > W and unspecified params inherit from the next-wider scope. 2) Given a rule R is toggled OFF at scope S, When processing images under S, Then R is not executed and is recorded as "skipped (disabled)" in the run log. 3) Given an invalid parameter value is saved for rule R at any scope, When saving, Then the system rejects it with a validation error and no changes are applied.

Ordered, Modular Batch Execution

1) Given a pipeline order [background_cleanup, margin_normalization, dpi_standardization, shadow_reconstruction], When processing a batch of 500 images, Then each image's run log lists the rules executed in exactly that order with per-rule status applied/skipped/failed. 2) Given a batch job is started, When 500 images are submitted, Then the system processes all images without exceeding the configured concurrency limit and exposes real-time progress (total, processed, succeeded, failed, pending). 3) Given a batch contains corrupt images, When the pipeline runs, Then corrupt images are marked failed with error codes while the rest complete successfully.

Auto-Apply vs Review Gate with Safe Thresholds and Rollback

1) Given rule-level confidence scores in [0,1] and a per-scope threshold T, When R's confidence < T, Then the system routes the image to "Request Review", does not commit R's changes, and notifies the review queue. 2) Given safe delta limits for metrics (e.g., margin variance <= 2%, background residual <= 0.5%, DPI = target), When any post-rule metric violates its limit, Then the engine rolls the image back to the pre-rule state, records a rollback event, and marks the step "failed (rolled back)". 3) Given a pipeline configured for Auto-Apply, When all rules meet thresholds and deltas, Then the image is committed automatically with status "auto-applied" and no review requested.

Preset Harmony and Marketplace Compliance

1) Given a PixelLift style-preset S sets target margins and background, When the pipeline runs, Then margin_normalization and background_cleanup use S's targets and do not override S-defined aesthetics. 2) Given a marketplace profile M defines background = #FFFFFF and min DPI = 300, When processing images for M, Then outputs meet those constraints exactly or are flagged for review with reasons listed. 3) Given conflicting settings between S and M, When processing for M, Then M's compliance rules take precedence for compliance-critical fields while S governs non-compliance-critical styling, and the precedence is logged.

Per-Step Observability and Diff Preview

1) Given a processed image, When inspecting the run log, Then for each rule the system shows: start/end timestamps, parameters used, metrics before/after, outcome, and any artifacts (e.g., masks) with IDs. 2) Given an image with changes, When "Preview Diff" is clicked, Then the system displays side-by-side original vs final and per-step diffs within 1 second P95 for images <= 25 MB. 3) Given export is requested, When downloading the audit bundle, Then a JSON report and per-step artifacts are included with consistent IDs matching the run log.

Idempotency and Deterministic Ordering

1) Given identical inputs and configuration (including rule order and parameters), When the pipeline is re-run on the same image, Then the final output and run log are byte-for-byte identical. 2) Given the rule order is changed, When the pipeline is re-run, Then the run log reflects the new order and any differences in output are recorded with a change summary. 3) Given non-deterministic operations (if any) exist, When the pipeline runs, Then a fixed seed is used per job so repeated runs reproduce identical results.

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Automation Architect Avery

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Recommerce Refiner Riley

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Test-and-Tune Taylor

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Studio-Streamliner Sam

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Line-Sheet Lila

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Private-Label Polisher Priya

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

Role Matrix

Requirements

Brand & Collection-Scoped Permission Model

Description

Acceptance Criteria

Visual Role Matrix Builder UI

Description

Acceptance Criteria

Access Simulator (What‑If) Preview

Description

Acceptance Criteria

Approval & Publish Gate Enforcement

Description

Acceptance Criteria

Conflict Detection & Safe‑Guard Validation

Description

Acceptance Criteria

Audit Trail & Versioned Policy History

Description

Acceptance Criteria

Permissions API & Webhook Notifications

Description

Acceptance Criteria

Draft Sandbox

Requirements

Draft Preset Versioning

Description

Acceptance Criteria

Sample Set Selector

Description

Acceptance Criteria