TimeMeld

LinkLock

Recipient‑bound magic links that verify the invited email at join time with a lightweight OTP. If a link is forwarded, the recipient can request access in one click for organizer approval—preventing gate‑crashers without forcing account creation. Hosts get cleaner attendance, guests get instant, secure entry.

Requirements

Recipient-Bound Magic Link Issuance

"As an invited guest, I want a secure, personal link that just works without creating an account so that I can join quickly and confidently."

Description

Generate a signed, recipient-specific magic link for each invitee that encodes meeting ID, recipient email hash, expiration, and one-time claim token. Embed the link into the TimeMeld calendar invite and reminder emails. Links must be usable without account creation and scoped to the intended email address only. Implement HMAC signing, short TTLs, and revocation support. On issuance, update the meeting’s attendee roster and surface link state in the organizer view for transparency and troubleshooting.

Acceptance Criteria

Issuance and Email Embedding

Given a scheduled meeting with multiple invitees and the organizer sends invitations When recipient-bound magic links are generated Then the system creates a unique, signed magic link per invitee encoding meetingId, recipientEmailHash, expiration, and oneTimeClaimToken And the URL contains no raw email address or other PII And the link is embedded in the invite email body and the attached calendar (ICS) description for that invitee And reminder emails for that meeting include the same recipient-specific link And the attendee roster is updated with an entry per invitee marked "Link Issued" including linkId and expiration timestamp

HMAC Signature and Payload Integrity

Given a generated magic link token Then its signature verifies using the server-managed HMAC secret and the payload exactly matches the signed claims When any claim (meetingId, recipientEmailHash, expiration, oneTimeClaimToken) is modified Then signature verification fails and access is denied When the signature is missing or malformed Then access is denied and no OTP is sent

Email Binding and OTP Verification Without Account Creation

Given a recipient opens their magic link Then the system prompts for a one-time passcode sent to the invited email address and does not require account creation or password setup When the recipient enters the correct OTP within its validity window Then the recipient is authenticated as the invited email and may join the meeting When the visitor cannot receive the OTP at the invited email or attempts to supply a different email Then claiming is denied and the link remains unclaimed

One-Time Claim and Reuse Prevention

Given a magic link has not been claimed When the invited recipient completes OTP verification Then the oneTimeClaimToken is marked claimed and meeting access is granted When the same link is used again after being claimed Then access is denied and no new OTP is sent

Expiration TTL Enforcement and Revocation

Given a magic link with an expiration timestamp in the future Then it can be claimed and used until that timestamp is reached When the current time exceeds the expiration timestamp Then access is denied and no OTP is sent When the organizer revokes an invitee’s link before expiration Then subsequent access attempts are denied, and the attendee roster state changes to "Revoked" with a revocation timestamp

Organizer View Link State Visibility

Given the organizer opens the meeting’s attendee panel Then each invitee shows link state as one of "Issued", "Claimed", "Revoked", or "Expired" along with the expiration timestamp When a link is issued, claimed, revoked, or expires Then the state displayed to the organizer reflects the change and is visible upon page refresh And the link URL shown to the organizer does not expose the recipient’s raw email address

Lightweight OTP Email Verification

"As an invitee, I want to confirm my identity with a quick code sent to my email so that I can enter securely without a full signup."

Description

Upon link click, require a brief OTP challenge sent to the invited email to confirm identity. Support 6-digit codes, 5-minute TTL, limited attempts, resend with rate limiting, and auto-fill via magic deep-link where supported. Provide an accessible UI with clear error states and localization hooks. Integrate with the existing email provider, log verification outcomes, and gracefully route mismatches to the forwarded-link request flow. Store only minimal necessary data and comply with privacy policies.

Acceptance Criteria

OTP Generation, Delivery, and 5‑Minute Validity

Given an invitee clicks a valid LinkLock meeting link When the OTP challenge screen loads Then the system issues a single-use 6-digit numeric OTP bound to the invitee email and session And sends the OTP via the existing email provider within 60 seconds And the OTP expires 5 minutes after issuance And only the most recently issued OTP for the active session is accepted And expired or superseded OTPs return the error message "Code expired — request a new code"

Limited Verification Attempts and Lockout

Given an active OTP is issued When the user submits an incorrect code Then the attempt count increments And after 5 incorrect attempts within the OTP validity window, the challenge is locked for 10 minutes or until a new OTP is issued And further submissions during lockout are blocked with the error "Too many attempts — try again later" And a lockout event is logged with invite ID and timestamp (no PII)

Resend OTP with Rate Limiting and Anti‑Abuse Controls

Given the OTP challenge is displayed When the user taps "Resend code" Then the system enforces a 30-second cooldown before the button re-enables And no more than 3 resends are allowed within 15 minutes per invite And each resend generates a new OTP and invalidates the previous OTP And email send failures surface the message "We couldn't send the code — please try again" without revealing account status And a resend event is logged with outcome

Deep‑Link Auto‑Fill and Submission

Given the user opens the verification deep-link from the OTP email on a supported device When the app or browser receives the deep-link Then the 6-digit code auto-fills and submits the verification form And on failure to auto-submit, the code remains populated for manual submit And if the deep-link references a different invite than the current session, the code is rejected and the user is prompted to refresh the session

Accessible, Localized OTP UI and Clear Error States

Rule: The OTP screen meets WCAG 2.1 AA (keyboard-only navigation, visible focus, 4.5:1 contrast, screen reader labels) Rule: Inline error messages (invalid code, expired code, too many attempts, send failure) are text, mapped to localization keys, and announced via ARIA live regions Rule: The 6-digit inputs accept paste, restrict to numeric, and expose a polite countdown timer with accessible announcements Rule: On successful verification, focus moves to a confirmation region with a success message that is screen-reader readable

Forwarded Link Mismatch and Request‑Access Routing

Given a verification attempt fails due to invite mismatch or the user indicates they cannot access the invited inbox When the user selects "Request access" Then a one-click request is sent to the organizer with meeting ID, invite ID, and requester email (entered in form or taken from session) And the user sees confirmation "Access request sent" And no account creation is required to submit the request And the original invite remains unverified until organizer approval

Event Logging, Data Minimization, and Privacy Compliance

Rule: The system logs otp_issued, email_send_success/failure, otp_verified_success, otp_invalid, otp_expired, attempts_limit_reached, resend_requested, resend_rate_limited, deep_link_used, forwarded_request_initiated Rule: Logs include only non-PII identifiers (invite_id, meeting_id, session_id), timestamps, and outcome; full emails and OTP values are never logged Rule: OTPs are stored as salted hashes with TTL = 5 minutes and are purged on verification or expiry Rule: Audit logs are retained for 30 days in accordance with privacy policy Rule: CI checks include PII scanning for log statements in this module

Forwarded Link Access Request Flow

"As someone who received a forwarded invite, I want to request access in one click so that the host can approve me without friction."

Description

Detect forwarded link scenarios (email mismatch or undeliverable OTP) and present a one-click Request Access form capturing name and email. Submit requests to the meeting organizer with context (meeting, original recipient, device, timestamp). Provide a clear waiting state for the requester and automatic updates on approval/denial. On approval, issue a new recipient-bound link and update the attendee roster; on denial, present organizer-provided guidance. Ensure minimal friction while preventing unauthorized entry.

Acceptance Criteria

Email Mismatch Triggers Access Request

Given a visitor opens a recipient-bound magic link for invited_email And enters a different email (requester_email ≠ invited_email) to request OTP When the mismatch is detected before sending OTP Then the OTP is not sent And the Request Access form is displayed with fields: Name (required) and Email prefilled with requester_email (required) And there is a single primary CTA labeled "Request access" And no account creation or password setup is required And the UI does not display invited_email anywhere

Undeliverable OTP Triggers Access Request

Given a visitor opens a recipient-bound magic link and enters an email When the OTP email hard-bounces or is undeliverable within 30 seconds Then the Request Access form is displayed with fields: Name (required) and Email prefilled (required) And a non-blocking explanation is shown: "We couldn't reach that email" And no further OTP attempts are sent to that email for this link session

Access Request Submission and Organizer Notification

Given the Request Access form is displayed When the visitor submits valid Name and Email Then a request record is created including meeting_id, original_invited_email, requester_name, requester_email, device_info (OS, browser), timezone, IP_hash, and UTC timestamp And duplicate submissions from the same requester_email for the same meeting within 60 seconds are de-duplicated (single request stored) And the meeting organizer receives an actionable notification (in-app and email) within 60 seconds containing meeting details, original_invited_email (masked), requester_name/email, device_info, and approve/deny controls

Requester Waiting State and Live Decision Updates

Given a request has been submitted When the requester remains on the waiting screen Then the screen clearly indicates "Awaiting organizer approval" with the submitted email And the client polls or receives push updates at least every 10 seconds And upon organizer approval or denial, the screen updates within 5 seconds to the corresponding state without manual refresh

Approval Flow Issues New Link and Updates Roster

Given the organizer approves a request Then a new magic link is generated bound to requester_email with a 30-minute validity window for first use and standard expiry thereafter And the link is emailed to requester_email immediately and surfaced on the waiting screen as a Continue button And the meeting attendee roster is updated to include requester_email with status "Approved via access request" And an audit log entry records approver_id, requester_email, timestamp, device_info, and link_id And the original magic link remains valid only for invited_email and cannot be used by requester_email

Denial Flow Presents Organizer Guidance

Given the organizer denies a request with optional guidance text Then the requester sees a denial state with the organizer-provided guidance (if any) and a privacy-safe explanation And an email notification is sent to requester_email within 60 seconds with the same guidance And no meeting access or new link is issued And an audit log entry records denier_id, requester_email, timestamp, and reason code/text

Privacy and Abuse Safeguards

Given any forwarded-link access request scenario Then the UI never exposes the original invited_email or full name to the requester And rate-limits prevent more than 5 access requests per requester_email per meeting per hour, returning a friendly error on excess And all organizer notifications mask original_invited_email (e.g., a****@example.com) And stored device and network identifiers are hashed or truncated per policy

Host Approval Console and Notifications

"As a meeting organizer, I want an approval queue with instant notifications so that I can control who joins and keep attendance clean."

Description

Provide organizers with a dedicated console to review, approve, or deny access requests. Include request details, quick actions, SLA indicators, and bulk operations. Send real-time notifications via email and Slack on new requests and decisions. On approval, automatically generate and deliver a fresh recipient-bound link, update calendar invite participants when applicable, and sync attendance state with TimeMeld’s dashboard. Preserve an audit record of all actions for compliance and support.

Acceptance Criteria

Triage Pending Access Requests with SLA Indicators

Given I am a host with events receiving access requests When I open the Host Approval Console Then I see a paginated list of requests with columns: Requester Email, Event Title, Event Time, Timezone, Reason (if provided), Source (Forwarded/Direct), Request Age, Current Status, SLA Remaining And each row provides quick actions: Approve, Deny, View Details And SLA Remaining displays color codes: green (>30m), amber (10–30m), red (<10m) and updates at least every 60s without full page refresh And I can filter by Status (Pending/Approved/Denied/Expired), Event, and SLA band (green/amber/red), and sort by Request Age and SLA Remaining And the list view loads within 2s for up to 100 pending requests And selecting View Details reveals the full request data including invitee email, forwarder email (if applicable), and request note (if provided)

Approve Request Generates Recipient-Bound Link and Updates Calendar & Dashboard

Given a pending access request is selected When I click Approve Then the system generates a new recipient-bound magic link tied to the requester’s email and sends it via email within 60s And the request status changes to Approved and is reflected on the console within 5s And if the event has calendar sync enabled, the requester is added as an attendee on the calendar event within 60s; otherwise, no calendar change is attempted And the attendee’s state is updated in TimeMeld’s dashboard to Approved within 15s And the approval action is idempotent; repeated Approve actions do not create additional links or duplicate calendar attendees

Deny Request with Reason and No-Link Guarantee

Given a pending access request is selected When I click Deny and optionally enter a reason Then the request status changes to Denied and is reflected within 5s And no magic link is generated or sent And the requester receives a denial email containing the reason (if provided) within 60s And subsequent attempts by the requester to use previously forwarded links are blocked with a message to request access And the denial action is idempotent

Bulk Approve/Deny with Per-Item Outcomes

Given I multiselect between 2 and 100 pending requests When I choose Approve or Deny and confirm Then the system executes the action per request and displays per-item success/failure and overall progress And the bulk operation completes within 10s for 100 requests under normal load And notifications, link generation, calendar updates, and dashboard sync occur per item as in single-item flows And partial failures do not block successful items; failed items are retriable individually

Real-Time Email and Slack Notifications for New Requests and Decisions

Given I am an organizer subscribed to notifications for an event When a new access request is submitted Then I receive a Slack message to the configured channel and an email including: requester email, event title/time, request reason (if any), request age, and a deep link to the console within 60s And when a request is approved or denied, the requester receives an email with the decision (and reason if denied) within 60s, and organizers receive a Slack update summarizing the decision And duplicate notifications for the same request are suppressed within a 5-minute window And notifications respect per-user preferences for Slack and email

Comprehensive Audit Trail for Requests and Actions

Given any lifecycle event occurs on an access request (create, approve, deny, bulk action, notification attempt, calendar sync, dashboard sync) When I view the audit log for that request Then I see an append-only timeline with entries containing: timestamp (UTC), actor (user id or system), action type, request id, event id, previous state, new state, reason (if any), notification channels attempted and outcomes, calendar sync result, dashboard sync result, and correlation id And audit entries are immutable and cannot be edited or deleted by end users And I can export the audit log for a selected time range to CSV, and it downloads within 30s for up to 10,000 entries

Resilience and Fallbacks for Notification and Calendar Failures

Given a transient failure occurs when sending Slack or email notifications When a request is created or a decision is made Then the system retries up to 3 times over 5 minutes with exponential backoff and logs each attempt in the audit trail And if Slack delivery fails after retries, an email notification is sent as a fallback (if enabled), and vice versa And if calendar attendee update fails, the approval remains recorded, the dashboard is updated, the host is alerted in-console with a retriable error banner, and a background retry is scheduled; no duplicate attendees are created upon eventual success And guests do not see internal errors; if their link delivery is delayed, they receive a clear message to check email again

Session Binding and Re-entry Window

"As an invitee, I want to rejoin from the same device without repeating verification so that I can recover from connection issues during the meeting."

Description

After successful OTP, bind the authenticated attendee to a device/session for the meeting window to allow seamless re-entry without repeated verification. Support configurable policies (single-device vs. multi-device), organizer-initiated revocation, and automatic expiry at meeting end plus grace period. Securely store session tokens, respect timezone-aware meeting windows, and handle edge cases like overlapping meetings or rescheduled times. Reflect active sessions in the organizer view for visibility.

Acceptance Criteria

Seamless Re-entry Within Meeting Window

Given an attendee completes OTP for a meeting, When the attendee reconnects from the same device/session during the meeting window, Then access is granted without re-verification. Given an attendee has an active bound session, When the attendee refreshes the page or reopens the join link during the window, Then the attendee bypasses OTP and is admitted. Given the meeting window has ended and the grace period has elapsed, When the attendee attempts re-entry, Then the session is invalid and OTP is required or access is denied according to policy. Given the grace period is configured (e.g., 15 minutes), When the attendee reconnects within the grace window after scheduled end, Then access is granted without re-verification.

Policy Enforcement: Single-device vs Multi-device

Given policy = single-device, When the same attendee attempts to start a second session on a different device/browser, Then the second session is blocked and the attendee is shown a one-click access request to the organizer. Given policy = single-device and the organizer approves a device switch, When the second device is admitted, Then the first device session is immediately revoked and cannot rejoin without re-approval. Given policy = multi-device with limit N, When the attendee starts sessions on up to N distinct devices, Then all N sessions are admitted; When a (N+1)th device attempts to join, Then it is blocked and may request access. Given policy changes from multi-device to single-device during the meeting, When more than one active session exists, Then only the most recent or organizer-selected session remains active and others are revoked with an inline notice.

Organizer-Initiated Session Revocation

Given an organizer opens the meeting’s attendee/session panel, When the organizer clicks Revoke on a specific attendee or device, Then the corresponding session token(s) become invalid within 5 seconds and the attendee is removed from the meeting. Given a revoked attendee attempts to rejoin during the meeting window, When they click the link again, Then they are shown a Request Access option and cannot re-enter without organizer approval or re-verification as configured. Given an organizer performs a bulk revoke (All sessions for attendee), When executed, Then all devices for that attendee are invalidated and reflected in the organizer view with status = Revoked. Given a revocation occurs, When viewing audit logs, Then an entry exists with timestamp, actor (organizer), target (attendee/device), and outcome (success/failure).

Expiry at Meeting End with Timezone Awareness and Grace Period

Given a meeting is scheduled from 10:00 to 11:00 in the organizer’s timezone, When an attendee in a different timezone joins and obtains a bound session, Then the session validity ends at 11:00 organizer timezone plus configured grace period regardless of attendee local time. Given the scheduled end time passes, When the grace period elapses, Then all active session tokens are server-invalidated and attendees must re-verify for any subsequent meetings. Given the grace period is set to 0, When the meeting end time occurs, Then sessions expire immediately at the scheduled end. Given a meeting is extended by the organizer to a later end time, When the extension is saved, Then existing active sessions inherit the new end time plus grace without requiring re-verification.

Overlapping and Rescheduled Meetings Handling

Given an attendee is invited to two overlapping meetings A and B, When the attendee has an active bound session for A, Then the session cannot be used to join B; a separate session must be created via OTP for B. Given a meeting is rescheduled (same meeting ID) to a new start/end time, When the change is saved, Then existing session validity windows update to the new times and continue to allow seamless re-entry. Given a meeting is duplicated or recreated with a new meeting ID, When the attendee uses the old session token, Then access is denied and the attendee is prompted to verify for the new meeting. Given overlapping meetings share the same attendee and device, When switching between A and B, Then session cookies/tokens remain scoped by meeting ID and do not leak across meetings.

Secure Session Token Storage and Rotation

Given a session is created after successful OTP, When the token is issued to the client, Then it is stored in an HttpOnly, Secure, SameSite=Lax cookie and is not accessible via JavaScript. Given the server persists session state, When storing token references, Then only a hashed (e.g., SHA-256/HMAC) token identifier is stored at rest; the raw token is never persisted. Given tokens are generated, When evaluating entropy, Then each token contains at least 128 bits of cryptographic randomness and includes an embedded or associated expiry no later than meeting end plus grace. Given key rotation occurs, When a signing/encryption key is rotated, Then newly minted tokens use the new key and existing tokens continue to validate until their natural expiry or are invalidated on rotation according to policy. Given a token is revoked or expired, When the client presents it, Then the server responds 401/440 and requires re-verification; the token cannot be refreshed beyond the meeting window.

Organizer View of Active Sessions

Given the organizer opens the meeting’s session dashboard, When viewing attendees, Then each attendee row shows count of active sessions, device type/browser, approximate location (country/region), last activity timestamp, and status (Active/Revoked/Expired). Given a session state changes (join, revoke, expire), When the organizer view is open, Then the list updates within 10 seconds to reflect the new state. Given the organizer selects an attendee/device in the dashboard, When clicking Revoke, Then the target session is terminated and the UI confirms success; the attendee is removed from the meeting. Given multiple active sessions for an attendee under multi-device policy, When the organizer selects Revoke All, Then all sessions for that attendee terminate and the counts update accordingly.

Audit Trails and Attendance Integrity

"As an organizer, I want clear audit logs and attendance reporting so that I can verify who joined and maintain compliance."

Description

Capture immutable event logs for link issuance, opens, OTP sends/verifications, access requests, approvals/denials, and session lifecycle. Surface anomalies (multiple attempts, mismatched domains, repeated denials) and provide export (CSV/API) for compliance. Integrate with TimeMeld’s attendance view to show verified participants, prevented gate-crashers, and reasons for denials. Apply data retention policies, redaction on request, and ensure PII minimization while enabling effective operational support.

Acceptance Criteria

End-to-End Immutable Audit Logging

- The system records an append-only event entry for each of: link_issued, link_opened, otp_sent, otp_verified, access_requested, access_approved, access_denied, session_started, session_ended. - Each entry includes: event_id (UUIDv4), event_type, occurred_at (UTC ISO-8601 ms), meeting_id, invite_id, actor_id (nullable), actor_email_hash (SHA-256 + salt), ip_anonymized, user_agent_hash, outcome (success|failure), attempt_number (where applicable). - OTP plaintext is never persisted in any log; only a salted, non-reversible hash may be stored for verification traceability. - Event writes are durable and queryable within 5 seconds of occurrence for 99% of events; 100% within 60 seconds. - Tamper-evidence: each entry contains prev_hash to form a hash chain; the verification endpoint returns chain_status=valid for unmodified logs. - Idempotency: submitting the same idempotency_key yields a single log entry; duplicates are rejected with 409 and not persisted.

Anomaly Detection and Surfacing

- Default thresholds: OTP attempts >5 within 10 minutes per invite -> OTP_RATE_LIMIT; opens from >3 countries within 24 hours -> GEO_SUSPICION; requester domain != invited domain -> DOMAIN_MISMATCH; >2 denials for the same requester within 24 hours -> REPEATED_DENIAL; >4 distinct device fingerprints within 24 hours -> DEVICE_ROTATION. - Anomalies are computed within 60 seconds of the triggering event and displayed on the meeting’s LinkLock panel with a badge and reason_code. - Each anomaly includes contributing event references and aggregate counts used for detection. - Hosts can acknowledge anomalies; acknowledged=true is persisted and included in API/CSV exports. - All anomalies are written to the audit log with anomaly=true and the appropriate reason_code.

Export via CSV and API

- CSV export supports filters: date_range (UTC), meeting_id, invite_id, event_type, anomaly_flag, reason_code; output includes a header row with deterministic column order and schema_version. - CSV export of up to 100,000 rows completes within 30 seconds; larger datasets stream with pagination and do not exceed memory limits. - API endpoint /v1/audit-events supports OAuth2, cursor-based pagination, rate limiting at 600 requests/min, and returns next_cursor when more data is available. - Timestamps are UTC ISO-8601 with milliseconds; CSV formatting follows RFC 4180 (proper escaping, quoting, and line breaks). - Exported record counts match the audit store for the same filter (0 record discrepancy in verification).

Attendance View Integration

- Attendance view displays for each attendee: verification_status (Verified|Unverified|Denied), join_method (LinkLock|Manual), verified_at (if applicable), and reason_code for Denied. - A “Prevented gate-crashers” section lists denied attempts with masked requester email, timestamp, and reason_code; the badge count equals the number of denials in the audit log for the meeting. - Clicking an attendee opens a side panel showing their audit trail filtered by invite_id. - Counts and statuses in the attendance view exactly match the audit log for the meeting (no tolerance). - If no audit records exist, the view renders a non-error empty state message: "No verification activity."

Data Retention and Legal Hold

- Workspace-level retention period is configurable between 30–730 days (default 180); events older than the period are purged daily at 02:00 UTC. - Applying a legal_hold to a meeting or invite prevents purge of associated records until the hold is removed. - Purge removes PII fields from aged records and sets redacted=true, preserving event_type, occurred_at, meeting_id, invite_id, and reason_code. - Purge and legal hold changes are themselves audit-logged with actor and timestamp. - A metrics endpoint exposes last_purge_time, records_purged, and errors; failures trigger an alert to on-call.

PII Minimization and Sensitive Data Handling

- Audit events store only: actor_email_hash (SHA-256 with workspace-specific salt), ip_anonymized (/24 IPv4, /48 IPv6), coarse_geo (country, region), user_agent_hash, device_fingerprint_hash; raw emails and full IPs are not stored in event rows. - OTP secrets are never logged; only a salted hash and a boolean outcome are recorded. - Access to any mapping service that can resolve email -> email_hash is limited to Support_Admin with break-glass approval; all lookups are audit-logged. - All audit data is encrypted at rest (AES-256) and in transit (TLS 1.2+); encryption keys are rotated at least every 90 days. - CI enforcement: automated tests fail the build if disallowed fields (e.g., raw_email, full_ip, otp_plaintext) are detected in event schemas or fixtures.

User-Initiated Redaction and Support Tooling

- Organizer or data subject can submit a redaction request via UI or /v1/redactions API specifying meeting_id and/or invite_id; the request is authenticated and audit-logged. - Upon workspace-admin approval, the system redacts PII fields for matching events within 24 hours, sets redacted=true, and records redacted_at and redaction_reason. - Redaction preserves non-PII fields necessary for compliance and analytics (event_type, occurred_at, reason_code) and breaks linkage to personal identifiers. - Support console enables authorized users to search by meeting_id, invite_id, or email_hash; view anomalies; and export scoped logs; every action is permission-checked and audit-logged. - A nightly verification job confirms all approved redactions are applied; any failures create an alert and are visible in the metrics endpoint.

Auto‑Localize

Detects a guest’s timezone and language to present the meeting date, time, and details in their locale—handling DST shifts, 12/24‑hour formats, and travel changes automatically. Eliminates confusion and missed calls caused by manual time conversions.

Requirements

Automatic Timezone Detection & Verification

"As a meeting guest, I want my timezone detected automatically so that invites and reminders show the correct local time without me converting it manually."

Description

Detect each guest’s timezone automatically using multiple signals (calendar metadata, email headers, browser Intl API, and privacy‑respecting IP geolocation as a last resort). Cross‑validate signals to compute a confidence score, cache per contact, and auto‑refresh until meeting start to capture changes. Persist detection results with timestamps and source for auditability. Expose a lightweight detection service used by scheduling flows, invite generation, and reminder systems across TimeMeld. Trigger re‑localization of invites and reminders on timezone change with minimal disruption, and surface a non‑blocking confirmation UI when confidence is low.

Acceptance Criteria

Multi‑Signal Timezone Detection with Confidence Scoring

Given calendar metadata and browser Intl API report the same IANA timezone When detection runs Then the resolved timezone equals that IANA ID and confidence >= 90 and sources include calendar and browser Given email headers and browser Intl API conflict and no calendar metadata exists When detection runs Then the resolved timezone matches the highest‑weighted signal, confidence is between 60 and 79, and conflicts are recorded per source Given only IP geolocation is available When detection runs Then the resolved timezone is derived from IP, confidence <= 50, and source is marked last_resort=true

Low‑Confidence Confirmation Prompt

Given a detected timezone with confidence < 60 When the guest opens the RSVP or scheduling page Then a non‑blocking confirmation prompt displays the suggested timezone with up to two alternatives and accepting sets confidence to 95, dismissing logs status=unconfirmed and allows the flow to continue Given the confirmation prompt is shown When the guest proceeds without acting Then the flow is not blocked and a silent recheck is scheduled within 10 minutes Given the guest explicitly confirms a timezone When subsequent detections find a conflict within 12 hours Then the confirmed value is not overridden without explicit user change

Auto‑Refresh Timezone Tracking Pre‑Meeting

Given a meeting is scheduled more than 24 hours away When initial detection completes Then auto‑refresh is scheduled at T‑24h, T‑6h, T‑1h, and T‑10m and on calendar/device change webhooks Given a refresh detects a different IANA timezone or UTC offset with confidence >= 80 When the change is recorded Then the cached timezone is updated immediately and change_detected=true is set Given no new signals are available at a refresh time When the cached value was last seen within 7 days Then reuse the cached timezone and decay confidence by 0 if <=7 days else by 10 points per additional week

Minimal‑Disruption Re‑localization on Timezone Change

Given a confirmed timezone change for a guest and meeting UTC time is unchanged When local wall time differs for that guest Then regenerate localized invite and reminders for that guest only, send at most one updated invite per guest per 12 hours, and within 30 minutes of start update reminders only without resending the invite Given multiple timezone changes occur within 3 hours When re‑localization would trigger multiple updates Then coalesce updates into a single message reflecting the latest timezone Given a timezone change with confidence between 60 and 79 When preparing reminders Then include a one‑click "Confirm your timezone" link in the reminder content

Persisted Detection Records with Audit Trail

Given any detection run completes When persisting results Then store contact_id, meeting_id (nullable), resolved_tz (IANA), confidence (0‑100), sources_used with per‑source tz and timestamps, decided_at, evaluator_version, last_resort_ip_used (bool) Given a persisted detection record exists When queried via the audit API Then it is returned within 1 second p95 and is immutable; corrections create a new version linked by previous_version_id Given an org admin exports meeting detection results When the export completes Then the CSV contains one row per guest with first_detected_at, last_detected_at, changes_count, and last_change_reason

Detection Service Integration in Scheduling, Invites, and Reminders

Given the scheduling UI and a participant email is entered When the UI calls the detection service Then a response is returned within 300 ms p95 containing timezone, confidence, sources[], cache_age_ms; on failure a cached value is returned with stale=true Given invite generation runs for recipients When localization is performed Then the detection service is called for each unique contact and the ICS uses the returned timezone; transient failures retry up to 3 times with exponential backoff Given the reminder system builds messages When a cached detection is <= 6 hours old Then it is reused; otherwise a refresh is triggered and the last known value is used if the refresh exceeds 500 ms

Privacy‑Respecting IP Fallback and Opt‑Out

Given no non‑IP signals are available or signals conflict with confidence < 60 When IP fallback is enabled Then IP is mapped to timezone at city level or coarser, raw IP is not stored beyond 24 hours, only derived timezone and country are persisted, and last_resort_ip_used=true is recorded Given a contact or organization has opted out of IP lookup When detection runs Then IP geolocation is not invoked and confidence reflects available signals only Given guests are located in GDPR/CCPA regions When IP data is processed Then lawful basis is recorded and a link to the privacy notice is included in the confirmation prompt

Locale‑Aware Date/Time & Language Formatting

"As an attendee, I want meeting details presented in my language and familiar date/time format so that I can instantly understand when the meeting occurs."

Description

Render meeting dates, times, and contextual text using the guest’s locale, including 12/24‑hour preference, local date order, week start day, numerals, and timezone display names/abbreviations. Use CLDR/ICU for formatting and pluralization, and provide translated templates for system messages (subject lines, RSVP buttons, reminder copy). Support right‑to‑left languages and regional nuances. Provide a single formatting utility consumed by email, in‑app views, Slack notifications, and ICS generation to ensure consistency.

Acceptance Criteria

Consistent Locale Formatting Across Email, In‑App, Slack, and ICS

Given a meeting start instant 2025-03-21T19:30:00Z and guest A with locale=en-US, tz=America/New_York When rendering the time string via the shared formatting utility for email subject, in‑app card, Slack notification, and ICS SUMMARY Then each surface displays exactly: "Fri, Mar 21, 2025, 3:30 PM EDT" and no surface deviates in punctuation, order, or hour-cycle And the ICS contains DTSTART;TZID=America/New_York:20250321T153000 and includes a VTIMEZONE for America/New_York Given the same instant and guest B with locale=en-GB, tz=Europe/London When rendering across all surfaces Then each surface displays exactly: "Fri, 21 Mar 2025, 19:30 GMT" And the ICS contains DTSTART;TZID=Europe/London:20250321T193000 and a VTIMEZONE for Europe/London Given the same instant and guest C with locale=de-DE, tz=Europe/Berlin When rendering across all surfaces Then each surface displays exactly: "Fr., 21.03.2025, 20:30 MEZ" And the ICS contains DTSTART;TZID=Europe/Berlin:20250321T203000 and a VTIMEZONE for Europe/Berlin Given the same instant and guest D with locale=ja-JP, tz=Asia/Tokyo When rendering across all surfaces Then each surface displays exactly: "2025/03/22 04:30 JST" And the ICS contains DTSTART;TZID=Asia/Tokyo:20250322T043000 and a VTIMEZONE for Asia/Tokyo

Auto‑Relocalize on Guest Timezone Change (Travel)

Given a meeting start instant 2025-06-10T15:00:00Z and guest with initial locale=en-IN, tz=Asia/Kolkata And an email invite and ICS have already been sent When the guest’s device timezone is detected as Europe/London ≥24 hours before the event Then all subsequent renders (reminders, in‑app, Slack) show: "Tue, 10 Jun 2025, 16:00 BST" for locale=en-GB hour-cycle and date order And a regenerated ICS for that guest contains DTSTART;TZID=Europe/London:20250610T160000 and VTIMEZONE for Europe/London And no stale communications are sent showing Asia/Kolkata after the timezone change Given the guest reverts to America/New_York before T‑1h When the T‑1h reminder is sent Then it displays: "Tue, Jun 10, 2025, 11:00 AM EDT" and the ICS DTSTART uses America/New_York And the event instant remains 2025-06-10T15:00:00Z across all conversions

DST Transition Handling and Ambiguity Resolution

Given instant 2025-03-09T09:30:00Z and guest tz=America/Los_Angeles (spring forward day) When formatting the local time Then it displays "Sun, Mar 9, 2025, 1:30 AM PST" and offset is UTC−8 Given instant 2025-03-09T10:30:00Z and the same tz When formatting the local time Then it displays "Sun, Mar 9, 2025, 3:30 AM PDT" (note hour 2:00 AM is skipped) and offset is UTC−7 Given instant 2025-11-02T08:30:00Z and guest tz=America/New_York (fall back day) When formatting the local time Then it displays "Sun, Nov 2, 2025, 4:30 AM EDT" and offset is UTC−4 Given instant 2025-11-02T09:30:00Z and the same tz When formatting the local time Then it displays "Sun, Nov 2, 2025, 4:30 AM EST" and offset is UTC−5 Given an invalid local wall time such as 2025-03-09 02:15 at tz=America/Los_Angeles When the utility is asked to format this wall time Then it either throws error code NONEXISTENT_LOCAL_TIME or, if configured with resolve=nextValid, returns "Sun, Mar 9, 2025, 3:15 AM PDT"; the behavior is controlled by an explicit configuration flag and covered by automated tests And ICS VTIMEZONE blocks for America/Los_Angeles and America/New_York include both standard and daylight rules covering 2025 transitions

Right‑to‑Left (RTL) Rendering and Numerals

Given locale=ar-SA and tz=Asia/Riyadh with instant 2025-03-21T19:30:00Z When rendering email subject and in‑app title Then the string begins with an RTL mark (U+200F) and all digits are Arabic‑Indic (e.g., time shows "٢٢:٣٠") And punctuation and spacing are placed according to UAX#9 (no mirrored commas around Latin segments) And RSVP buttons are labeled in Arabic and ordered and aligned right‑to‑left (e.g., [نعم] then [لا]) And Slack messages include bidi isolation around interpolated LTR segments (e.g., email addresses) using U+2068/U+2069 or equivalent Given locale=he-IL and tz=Asia/Jerusalem When rendering the same event Then the primary paragraph direction is RTL, numbers remain locale‑appropriate, and no mixed‑direction garbling occurs in subject, buttons, or Slack text

ICU Templates, Variables, and Pluralization

Given ICU message key reminder.minutes with pattern for en: "Reminder in {minutes, plural, one {# minute} other {# minutes}}" When minutes=1 Then the rendered string is "Reminder in 1 minute" When minutes=2 Then the rendered string is "Reminder in 2 minutes" Given ICU message key for ru: "Напоминание через {minutes, plural, one {# минуту} few {# минуты} many {# минут} other {# минуты}}" When minutes=1 Then the rendered string is "Напоминание через 1 минуту" When minutes=2 Then the rendered string is "Напоминание через 2 минуты" When minutes=5 Then the rendered string is "Напоминание через 5 минут" Given a template with placeholders: "{organizer} scheduled {title}" When organizer="Ana" and title="Sprint Review" Then the rendered string is "Ana scheduled Sprint Review" in the guest’s language, with placeholders safely escaped Given a missing translation for locale=pt-BR When rendering any key Then the system falls back to locale=pt, otherwise to en, while preserving number/date formatting for pt-BR And telemetry records the missing key once per release/channel

Single Formatting Utility Enforcement and Consistency

Given the codebase is scanned with a lint rule forbidding direct Date/Number formatting outside the shared utility When running CI Then there are 0 violations of disallowed APIs (e.g., Date.toLocaleString, Intl.DateTimeFormat) outside the utility package Given the shared utility version is updated When rendering the same instant for a test guest across email, in‑app, Slack, and ICS in an end‑to‑end test Then all four surfaces produce identical normalized tokens for date/time, timezone label, numerals, and language And a golden snapshot diff shows no divergence between surfaces Given a locale override feature flag When toggled from en-US to en-GB in a test session Then all surfaces switch to 24‑hour format and day‑month order consistently with no surface lagging by more than one render cycle

Week Start Day and Calendar Grid Localization

Given the in‑app calendar grid and locale=en-US When rendering a week view Then the first column is Sunday and weekday headers are "Sun, Mon, Tue, Wed, Thu, Fri, Sat" Given locale=en-GB When rendering the same view Then the first column is Monday and headers are localized ("Mon, Tue, Wed, Thu, Fri, Sat, Sun") Given locale=ar-SA When rendering the same view Then the first column is Saturday, headers are RTL‑localized, and digits use Arabic‑Indic Given a live locale switch in the UI from en-US to en-GB When the user switches locales Then the grid re‑renders with the correct first day of week within one frame without requiring a page reload

DST‑Safe Scheduling Engine

"As a scheduler, I want meeting times to account for DST shifts at the event date so that no one misses a call due to clock changes."

Description

Compute attendee‑specific meeting times using IANA tzdb rules at the event’s future date, correctly handling daylight saving time transitions, historical changes, and ambiguous/non‑existent local times. Auto‑update tzdb data regularly. Detect when a proposed slot falls within a DST change window and provide alternative suggestions or add clear annotations. Ensure ICS invites include correct TZID and DTSTART/DTEND with VTIMEZONE to render properly across Google, Outlook, and Apple Calendar.

Acceptance Criteria

Non‑Existent Local Time Handling (Spring Forward)

Given an attendee’s timezone has a DST spring‑forward on the event date where local times between 02:00 and 02:59 do not exist When the scheduling engine evaluates a candidate slot that maps to a non‑existent local time (e.g., 02:30) Then the engine must reject that slot for that attendee And it must propose at least 2 alternative valid local times within ±90 minutes that respect the attendee’s working hours and ergonomic constraints And the UI must display an annotation containing the words “DST” and “time skipped” for the affected attendee And the confirmed ICS must include DTSTART/DTEND with a TZID and VTIMEZONE such that the time resolves to a valid single UTC instant in that locale And no “floating” times (no DTSTART/DTEND without TZID and no trailing Z) are present

Ambiguous Local Time Handling (Fall Back)

Given an attendee’s timezone has a DST fall‑back on the event date where a local wall time (e.g., 01:30) occurs twice When the scheduling engine offers or confirms a slot at the ambiguous local time Then the UI must disambiguate the occurrence by indicating the UTC offset (e.g., UTC−04 vs UTC−05) or labels “before fallback”/“after fallback,” and display an annotation containing the word “DST” And the ICS must include TZID with a VTIMEZONE whose STANDARD/DAYLIGHT definitions make DTSTART unambiguously map to the intended UTC instant across Google, Outlook, and Apple Calendar imports And the engine must additionally suggest at least 1 alternative slot outside the ambiguous window

ICS Invite TZ Fidelity Across Major Calendars

Given a meeting is confirmed with attendees across at least three distinct IANA timezones When the system generates the ICS invite Then the VCALENDAR must include a VTIMEZONE component for each unique TZID referenced And DTSTART and DTEND must include TZID parameters using valid IANA tzdb names (e.g., America/Los_Angeles) and must not be floating times And importing the ICS into Google Calendar, Microsoft Outlook (desktop/web), and Apple Calendar must display identical local wall times per attendee and resolve to the same UTC instants And automated validation must confirm no warnings for unknown TZID and that the DTSTART/DTEND are not suffixed with Z when TZID is present

TZDB Auto‑Update, Versioning, and Rollback

Given IANA tzdb publishes a new release When the update service runs Then the system must detect, download, verify checksum/signature, and activate the new tzdb within 24 hours And if verification fails, the system must keep the previous tzdb active and log an alert with severity ERROR And each scheduled event must persist the tzdbVersion used for its time computations And updating tzdb must not mutate the UTC instants of already‑scheduled events; only newly scheduled or re‑computed proposals may change And an admin/status endpoint must expose current tzdbVersion and lastUpdatedAt And an integration test simulating a jurisdictional rule change must show different proposal outputs before vs. after update while existing event UTC instants remain unchanged

Attendee Timezone Change Prior to Event

Given an attendee accepts an invite while in Timezone A and later their detected/declared timezone changes to Timezone B before the event When the attendee views the event details or receives reminders Then the displayed local time must reflect Timezone B while the event’s UTC instant remains unchanged And no duplicate invites are generated; the original ICS remains valid and renders correctly in the attendee’s calendar And ergonomic weighting for new proposal computations must use Timezone B for that attendee from the time of change forward And a single non‑blocking notification informs the attendee that times were localized to the new timezone

Cross‑Region Proposal Generation Over DST Boundary

Given a team with attendees in regions that transition DST on different dates (e.g., US and EU) and a target week that spans differing DST states When the engine generates candidate meeting windows Then it must produce at least 3 viable proposals that respect each attendee’s working hours and ergonomic constraints And none of the proposals may fall into non‑existent or ambiguous local times for any attendee And proposals within ±24 hours of any attendee’s DST switch must include a visible “DST” annotation explaining the shift And the scoring must avoid repeating the same attendee’s least‑ergonomic slot across consecutive weeks when a DST boundary is involved

Travel‑Aware Participant Updates

"As a traveling engineer, I want my meeting details to automatically re‑localize when my timezone changes so that I don’t have to reschedule or manually convert times."

Description

Monitor participant timezone changes near the event by listening for OS/browser timezone shifts, optional calendar signals, or explicit self‑reported travel windows from a secure link. When a change is detected, re‑localize all participant‑visible times, regenerate ICS as needed, and send minimal, localized update notifications without altering the canonical UTC event time. Provide guardrails to avoid notification spam and a summary banner indicating that times were adjusted due to travel.

Acceptance Criteria

OS Timezone Shift Re-localization Without UTC Change

Given a confirmed participant with browser timezone sharing enabled and an event starting in ≤72 hours And the participant’s OS/browser timezone offset changes and remains stable for ≥10 minutes When the system detects the change Then the participant-visible event time is recalculated in the new timezone using correct DST rules and locale-specific 12/24-hour format And the event’s canonical UTC start and end times remain unchanged And a single localized, minimal update notification is sent to the participant And the event view shows a localized banner indicating times were adjusted due to travel/DST for that participant

Self-Reported Travel Window Overrides Locale

Given a participant opens a time-bound, tokenized secure link for the specific event When they submit a travel window with start/end timestamps and a destination timezone Then the system stores the window and applies the specified timezone to all participant-visible times during that window And the system automatically reverts to the prior detected/home timezone after the window ends And at most one localized notification is sent at window start (and at window end) only if the local clock time representation changes And no notification is sent if the local clock time remains unchanged And the secure link requires a valid token, expires after 7 days or upon save, and is scoped only to that event’s travel settings

Calendar Signal Heuristic With Conflict Resolution

Given the participant has granted optional calendar access and an event occurs within the next 7 days And a calendar item indicates travel whose location/timezone overlaps the event time with a different offset And the inferred timezone remains consistent for ≥10 minutes When the system ingests the signal Then participant-visible times use the inferred timezone for the overlap period And precedence for conflicts is: self-reported > OS/browser > calendar And no more than one notification per event per participant is sent in any 24-hour period And no notification is sent if the local clock time representation does not change

ICS Regeneration Preserves UTC With Incremented Sequence

Given a participant’s effective timezone changes and affects their localized representation When an updated ICS is generated for that participant Then the ICS retains the same UID as the original invite And the SEQUENCE value is incremented by at least 1 from the previous ICS And DTSTART and DTEND remain in UTC and equal to the canonical event times And SUMMARY and DESCRIPTION fields are localized to the participant’s language where available And the ICS validates against RFC 5545 And the updated ICS is attached to the notification And no ICS is regenerated if there is no change to participant-visible representation

Localized Minimal Notification With Rate Limits

Given the participant’s language and locale are known or inferred from Accept-Language When a timezone change requires notifying the participant Then the notification content is localized to the participant’s language And it displays the unchanged UTC time and the new local time formatted per locale And it excludes nonessential details beyond the change summary and relevant action links And at most one notification per event per participant is sent within any 24-hour window And duplicate notifications within 60 minutes are suppressed And notifications respect user opt-out preferences

Travel Adjustment Summary Banners

Given a participant views the event page or invite When their displayed time has been adjusted due to travel or DST within the last 72 hours Then a localized banner is shown indicating times were adjusted and showing the last updated timestamp And the banner does not reveal other participants’ personal travel details And the host’s event dashboard shows a non-identifying banner that one or more participants had time adjustments

Multi‑Channel Localized Invitations & Updates

"As a guest, I want localized invites and updates across email, calendar, and Slack so that I see the same correct time everywhere I check."

Description

Generate consistent, localized content across channels: email (HTML/text), calendar invites (ICS with correct timezone blocks), Slack DMs, and in‑app views. Ensure that all channels display the same localized time and copy, and that updates or reschedules propagate atomically. Provide deep links like “View in my time zone” and “Change language” that respect per‑guest preferences and device locale.

Acceptance Criteria

Localized New Invite Consistency Across Channels

Given a meeting is created by a host in America/Los_Angeles with title "Sprint Sync" and two guests: Guest A (de-DE, Europe/Berlin) and Guest B (ja-JP, Asia/Tokyo) When TimeMeld generates and sends invitations via email (HTML and plain text), Slack DM, in-app view, and attached .ics files Then each channel displays the meeting date and time in the guest’s local timezone with correct DST application for that date And each channel formats time according to locale conventions (e.g., de-DE and ja-JP use 24-hour format; no AM/PM) And the email Content-Language header matches the guest locale, and HTML and plain text bodies contain identical date/time strings And the Slack DM and in-app view display the same localized date/time and copy as the email for that guest And the .ics includes a single VEVENT with a consistent UID across channels and DTSTART/DTEND specified (with TZID or UTC) such that the event renders at the same instant as other channels in the guest’s calendar, including across DST And when all channel times are normalized to UTC, they are equal for a given guest

Atomic Reschedule Propagation Across Channels

Given an existing meeting invite has been delivered across email, Slack DM, in-app, and .ics with SEQUENCE N When the host reschedules the meeting to a new time Then updated email (HTML/plain), Slack DM, in-app view, and .ics are delivered and visible within 60 seconds And no channel shows the old time after 60 seconds; all channels display the new time and updated copy And the .ics update uses the same UID with SEQUENCE N+1 and an appropriate METHOD (REQUEST/PUBLISH) so calendar clients replace the prior instance And the Slack DM updates the original message (or posts a threaded update) reflecting the new time without creating a duplicate invite message And the in-app view reflects the new time without requiring a hard refresh And a single event version identifier is recorded so all channel payloads reference the same version

Deep Link — View in My Time Zone

Given a guest has a stored preference timezone of Europe/London and their current device timezone is Asia/Kolkata When they click the "View in my time zone" link in any channel Then the landing view renders the meeting time in Asia/Kolkata with the correct GMT offset and DST for the event date And the view clearly indicates the timezone used for rendering And the guest’s stored preference timezone remains unchanged on the server And the deep link is signed; invalid or expired tokens return 401 without revealing event details

Deep Link — Change Language Preference

Given a guest’s language is set to English (en-US) When they click "Change language" and select Spanish (es-ES) Then the confirmation UI displays in Spanish and future email, Slack DM, in-app views, and .ics text fields (SUMMARY/DESCRIPTION) use Spanish And outgoing emails include Content-Language: es-ES and web views respect Accept-Language for es-ES And previously sent messages are not edited retroactively unless a resend is explicitly triggered And if the selected language is unsupported, the system falls back to English per string and records the fallback with the requested language code

Guest Travel — Automatic Timezone Update

Given a guest originally viewed the invite in America/New_York and travels to Europe/Paris before the event When they open the in-app view or receive a Slack reminder within 24 hours of the event Then the displayed meeting time reflects Europe/Paris local time with correct DST for the event date And the calendar entry from the original .ics (same UID) renders at the correct instant after the device timezone change And no duplicate calendar events are created due to the timezone change And the guest’s effective rendering timezone is updated for display without changing the stored preference unless explicitly saved by the guest

Cross-Channel Consistency and Formatting Validation

Given an invite is generated for a guest with locale fr-FR and timezone Europe/Paris When content is produced for email (HTML/text), Slack DM, in-app, and .ics Then date formatting follows fr-FR conventions (e.g., mardi 14 octobre 2025, 14:30) and 24-hour time And all channels include the same canonical event title and description text in French And when normalized to ISO-8601 UTC, the start and end instants are identical across all channels And the plain-text email contains no HTML tags and matches the human-readable date/time string used in HTML, Slack, and in-app And there are no placeholders or untranslated strings; any missing translation falls back to English with a logged warning

User Overrides, Preferences & Privacy Compliance

"As an attendee, I want to control my timezone and language settings and what detection methods are used so that I’m comfortable with privacy and always see accurate details."

Description

Allow guests to override detected timezone and language, set persistence scope (this event vs. all future TimeMeld invites), and manage consent for geolocation signals. Store only minimal necessary data with retention limits, and provide export/delete options to meet GDPR/CCPA. Offer admin policies to restrict detection methods by region and to set default fallbacks. Log detection sources and consent decisions for compliance audits.

Acceptance Criteria

Guest Overrides Timezone

Given a guest sees meeting times in a detected timezone When the guest clicks "Change Timezone" and selects a different timezone Then all displayed times update to the selected timezone within 500 ms And a visible label "Timezone: {Selected}" appears and remains on the page And the override persists according to the selected persistence scope And the change is recorded in the audit log with timestamp and source="user"

Guest Overrides Language

Given a detected language is applied When the guest selects a different language from the language switcher Then UI strings and date/time formats update to the selected language within 500 ms without a full page reload And the confirmation email for this invite is generated in the selected language And RTL languages render with correct direction and layout where applicable And the change is recorded in the audit log

Preference Persistence Scope

- The scope control offers "This Event Only" and "All TimeMeld Invites" whenever a guest overrides timezone or language - Selecting "This Event Only" stores the preference client-side scoped to the invite token and expires at event end or 30 days, whichever is sooner; no server-side profile is created - Selecting "All TimeMeld Invites" stores only timezone and language server-side keyed to a verified email and applies to future TimeMeld invites; it expires after 12 months of inactivity or upon guest revocation - The selected scope is displayed and can be changed before leaving the page; changes take effect immediately - If the guest email is unverified, the "All TimeMeld Invites" option is disabled with an explanatory message

Consent for Geolocation Signals

- A consent prompt lists each detection method (IP geolocation, browser language, device timezone, travel detection) with individual toggles - Detection methods do not execute until consent is captured, except those marked as strictly necessary by current admin policy; non-consented methods remain disabled - Declining consent triggers use of admin-configured fallback timezone and language; no IP or precise location is stored - Consent records include method toggles, timestamp, region code, policy ID, and (if provided) guest email; retention is 13 months or until revoked - Guests can revisit and modify consent at any time; updates take effect immediately and are logged

Data Export and Deletion (GDPR/CCPA)

- A self-serve portal allows guests to request data export or deletion after email verification - Exports include timezone/lang preferences, consent history, detection-source logs, applied policy IDs, and timestamps; delivered within 5 minutes as downloadable JSON and CSV - Deletion requests remove stored preferences and consent records within 7 days; audit logs are pseudonymized by removing direct identifiers - A confirmation of export or deletion is emailed to the requester; subsequent invites use defaults with no auto-filled overrides - Rate limiting is enforced: maximum 3 privacy requests per 24 hours per email

Admin Regional Policies and Fallbacks

- Admins can define region-based policies specifying allowed detection methods and default fallback timezone/language; precedence is region > org > system - Disallowed methods are not executed and are hidden or disabled in the guest consent UI for affected regions - Policy changes propagate and are enforced within 5 minutes across invite pages and APIs - When region cannot be reliably determined pre-consent, the org default policy is applied; no geolocation lookup results are stored - All policy changes are captured in an audit log with actor, timestamp, and change summary

Audit Logging of Detection Sources and Decisions

- For each invite session, an immutable log entry is created for detection sources used, consent state, overrides applied, persistence scope, effective policy ID, region code, and timestamps - Logs do not store raw IP addresses or precise coordinates; region/country code is stored; guest email is hashed with an org-scoped salt - Log retention is 24 months; access is restricted to Compliance Admins; export is available in CSV and JSON - Log writes succeed within 200 ms of the triggering event and are resilient to client refreshes via server-side logging with idempotency keys

Fallback & Error Resilience

"As a guest, I want clear fallbacks and conversion options when my locale can’t be determined so that I can still confirm the correct meeting time."

Description

When detection confidence is low or signals conflict, default to a safe presentation that includes UTC, host’s timezone, and a prominent “Convert to my time” link that opens a localized viewer. Provide clear error states in invites, resilient parsing of malformed locales, and automatic retries for external dependencies. Capture telemetry on failures, confidence levels, and overrides to guide continuous improvement.

Acceptance Criteria

Low-Confidence Detection Fallback Display

Given detection_confidence < 0.7 OR locale_timezone is null When rendering meeting details for a guest Then display meeting time in UTC (ISO 8601 with Z) and host timezone (IANA name and localized time) And display a prominent "Convert to my time" link above the fold with role="button" And do not display an auto-localized date/time string And emit telemetry event fallback_used with fields: reason="low_confidence", confidence, guest_id_hash, meeting_id

Conflicting Signals Resolution Policy

Given signals from Accept-Language, IP geolocation, and calendar timezone differ by two or more distinct timezones When determining the guest timezone Then set detection_confidence <= 0.6 and use fallback presentation And display UTC and host timezone times and the "Convert to my time" link And emit telemetry event conflict_detected with sources[], chosen_policy="fallback", and confidence

"Convert to my time" Localized Viewer

Given a guest clicks the "Convert to my time" link When the localized viewer opens Then detect the device timezone via Intl/ECMAScript APIs and format date/time in the device locale (12/24h per locale) And account for DST at the scheduled datetime using the IANA timezone database And render the viewer within 1000 ms TTFB on a 3G connection And display the timezone name and offset (e.g., "Europe/Berlin (UTC+02:00)") And if the device timezone changes while open, update the display within 5 seconds

Clear Error States in Invites

Given a failure occurs during localization (e.g., formatter throws, template missing, service unreachable) When generating the invite content in HTML and plain-text Then render a clear error banner "We couldn't localize your time" without technical details And include UTC and host timezone times and the "Convert to my time" link And ensure accessibility: banner role="alert" and contrast ratio >= 4.5:1 And emit telemetry error_state_rendered with error_code, stack_hash, meeting_id

Resilient Parsing of Malformed Locales

Given malformed locale inputs such as "en_US", "pt-PT-utf8", empty strings, or deprecated/alias timezone IDs like "US/Eastern" When parsing headers or profile fields Then normalize to a best-effort standard (e.g., "en-US", "pt-PT", "America/New_York") or set to null without throwing And maintain a normalization map for at least 50 common malformed cases And unit tests cover at least 20 malformed inputs with 100% pass rate And emit telemetry locale_parse_normalized with original and normalized values (hashed as applicable)

Automatic Retries and Circuit Breaking

Given an external dependency (timezone/geo lookup or localization service) returns 5xx or times out When making the request Then retry up to 3 times with exponential backoff starting at 200 ms with +/-50% jitter And total added wait time does not exceed 2 seconds And open a circuit breaker after 5 consecutive failures for 60 seconds And on final failure, present fallback (UTC + host time + "Convert to my time" link) and emit telemetry external_retry_exhausted with attempt_count and durations

Telemetry Coverage and Privacy Safeguards

Given any fallback, conflict, override, parsing normalization, or external failure occurs When recording telemetry Then capture at minimum: event_name, meeting_id, tenant_id, timestamp, reason_code, detection_confidence (0..1), tz_sources[], selected_tz, user_agent_hash And exclude raw IP, email, or full user agent; hash or tokenize identifiers with salt rotation every 30 days And batch and send within 10 seconds or on app close, with at-least-once delivery And validate against schema "autolocalize_v1"; events failing validation are dropped with local debug log only

Easy Rebook

Lets external guests propose or pick from organizer‑approved alternate slots directly from the invite page. One tap updates everyone’s calendars, preserves conferencing details, and respects fairness rules—cutting email back‑and‑forth while staying humane across timezones.

Requirements

Guest Rebook Widget

"As an external guest, I want to rebook directly from the invite page by choosing an organizer-approved slot so that I can avoid email back-and-forth and pick a time that fits my timezone."

Description

Embeddable, mobile-responsive widget on the invite page that lets external guests pick from organizer-approved alternate slots or propose within allowed windows. Automatically localizes times to the guest’s timezone, displays meeting context (title, participants, duration), and enforces basic constraints (buffers, working hours, slot caps). Includes accessibility compliance, inline validation, and instant feedback on slot availability. Instrumented for analytics and supports deep links with preselected options.

Acceptance Criteria

One‑Tap Rebook from Organizer‑Approved Slot (Desktop & Mobile)

Given an external guest opens the invite page containing the Guest Rebook Widget on a supported desktop or mobile browser And at least one organizer‑approved alternate slot is displayed When the guest selects an available slot and taps Confirm Then the widget verifies availability in real time and locks the slot within 500 ms And the meeting is rescheduled for all participants, preserving conferencing details and description And updated calendar invites are delivered to all attendees within 10 seconds And the original slot is released and the new slot is shown as booked on refresh And the guest sees a success state with localized date/time and an Add to Calendar action And no duplicate events or overlapping holds are created

Guest Proposes Times Within Organizer‑Allowed Windows

Given proposals are enabled with configured allowed windows, lead time, and number of proposals (1–3) When the guest enters a proposal outside the allowed windows or lead time Then the Confirm action remains disabled and an inline error explains the violation When the guest submits proposals within the allowed windows Then the proposals are accepted, participants are notified, and any temporary holds respect configured buffers And the guest can modify or withdraw proposals until an organizer accepts, with status visibly updated within 2 seconds of change And proposals that would exceed daily slot caps are blocked with an inline reason

Automatic Timezone Detection and Localization with Guest Override

Given the widget loads and can read the browser Intl API timezone or a tz parameter in the URL When rendering available slots and meeting details Then all times display in the detected/param timezone with correct DST handling When the guest changes the timezone via the control Then all displayed times update within 300 ms and the selection persists for the session And any Add to Calendar output encodes the correct timezone/offset so the event lands at the intended local time

Inline Validation and Constraint Enforcement (Buffers, Working Hours, Slot Caps, Fairness)

Given organizational constraints are configured (minimum buffers before/after, participant working hours, per‑day slot caps, and fairness limits) When a slot violates any constraint Then the slot is disabled and a reason is shown via tooltip or inline helper text When the guest attempts to confirm a slot that became non‑compliant due to a recent change Then submission is blocked with a clear message and refreshed, compliant alternatives are presented within 1 second When fairness limits would be exceeded (e.g., too many early/late meetings for a participant in the current week) Then the slot is either hidden or marked unavailable with a fairness reason code

Accessibility Compliance for the Guest Rebook Widget (WCAG 2.2 AA)

Given a keyboard‑only user navigates the widget Then all interactive elements are reachable in logical order with a visible focus indicator and no focus traps And screen readers announce labels, state, and dynamic updates (via aria‑live) for slot changes, errors, and confirmations And color contrast for text and interactive elements meets ≥ 4.5:1; controls have touch targets ≥ 44×44 dp; content reflows at 320 px width without loss of function And the widget yields 0 critical/serious issues in automated audits (axe‑core, Lighthouse) across Chrome/Firefox/Safari desktop and iOS/Android mobile

Deep Link with Preselected Options and Secure Token Handling

Given a guest opens a deep link containing a signed token with meeting identifier and optional preselected slot and timezone When the token is valid and unexpired (≤ 72 hours) Then the widget loads with the slot preselected and timezone applied; the guest can confirm in one tap When the token is invalid, expired, or the slot is no longer available Then the widget loads safely without PII, shows an explanatory message, and surfaces the next best compliant options And no querystring or token reveals PII; signature validation prevents tampering

Analytics and Telemetry Instrumentation for Rebook Interactions

Given the widget is rendered Then analytics events are fired for widget_viewed, slots_shown, slot_selected, propose_started, propose_submitted, rebook_confirmed, validation_error, and a11y_navigation And each event includes meeting_id, anonymous_guest_id (hashed), slot_id (if applicable), timezone, device_type, duration, outcome, and reason_code (for errors) And events are queued and delivered within the session with ≤ 1% loss; offline retries back off and cap at 24 hours And events exclude PII by design and honor Do Not Track and org privacy settings

Organizer-Approved Slots Management

"As an organizer, I want to pre-approve alternate slots with my constraints so that guests can safely rebook without needing my manual review each time."

Description

Controls for organizers to pre-approve or curate alternate windows generated by TimeMeld, including duration, working-hour bounds, buffer rules, blackout dates, per-day caps, and series-level preferences. Supports quick add/remove of slots from within the calendar event, auto-refreshes suggestions as calendars change, and allows default templates per team. Integrates with fairness and ergonomics settings so only compliant slots are exposed to guests.

Acceptance Criteria

Constraint-Governed Slot Generation

Given an organizer opens Manage Alternate Slots for an event with at least two attendees When they set Duration=30m, Working Hours per attendee=09:00–17:00 local, Min Buffer=15m before and after, add two Blackout Dates, and set Per-day Cap=2 per attendee, then click Generate Then the suggestions list contains only slots that satisfy all configured constraints And no slot overlaps any attendee's blackout dates And no slot violates the per-attendee working hours And no slot leaves less than 15 minutes buffer from existing events on the organizer's calendar And no attendee has more than 2 suggested slots on any single day And the UI displays the count of suggested slots

Inline Add/Remove of Approved Slots

Given the organizer views Suggested and Approved slot lists within the calendar event When they click Approve on a suggested slot and Save Then the slot appears in the Approved list and on the guest invite page within 10 seconds or upon page refresh And when they click Remove on an approved slot and Save Then the slot is removed from the guest invite page within 10 seconds or upon page refresh And if a guest attempts to book a removed slot from a stale page, the system blocks the booking and displays "Slot no longer available"

Auto-Refresh on Calendar Changes

Given a suggested slot exists for an event When any attendee creates a conflicting calendar event overlapping that time Then the slot is automatically marked unavailable and removed from suggestions within 2 minutes And if the conflicting event is deleted, the slot reappears within 2 minutes provided it still meets all constraints And the organizer receives a non-blocking in-app notification of the change

Series-Level Preferences and Overrides

Given a recurring meeting series with Easy Rebook enabled When the organizer sets series-level duration, working-hour bounds, buffer rules, blackout dates, and per-day caps and saves Then these preferences apply to all future occurrences by default And modifying constraints on a single occurrence creates an occurrence-level override And clearing an occurrence-level override reverts that occurrence to the series defaults And changing series defaults does not overwrite existing occurrence-level overrides

Team Template Application and Governance

Given a team with a default slots template is selected for the event When the organizer opens Manage Alternate Slots Then the panel pre-populates with the template's duration, working-hour bounds, buffer rules, blackout dates, and per-day caps And only team admins can create or edit team templates And updating a team template affects newly created events under that team but does not change existing saved settings on already-configured events

Fairness and Ergonomics Compliance Filter

Given team-level fairness rotation and ergonomics (quiet hours, earliest/latest boundaries, load balance) settings are enabled When slots are generated or an organizer attempts to approve a slot Then any slot that violates fairness or ergonomics rules is excluded from suggestions and cannot be approved And excluded slots display a reason code or tooltip explaining the violated rule And all approved slots are labeled as Compliant with reference to the active rule set

Zero-Compliant-Slots Fallback

Given the configured constraints and fairness rules yield zero compliant slots for an event When the organizer opens the Approved Slots view Then the system displays No compliant slots and highlights the most restrictive constraints to relax And the guest invite page hides reschedule options and presents a Request another time action instead

One-Tap Calendar Update

"As an organizer, I want rebooking to update everyone’s calendars and keep the same conferencing details so that the meeting continues seamlessly without new links or confusion."

Description

Atomic reschedule operation that updates all participants’ calendars when a guest selects a new slot, preserving conferencing details (meeting ID/link), agenda, attachments, and participant list. Supports Google and Microsoft 365 with ICS fallback, updates resource bookings (rooms), and sends updated invites and confirmations. Ensures idempotency, prevents duplicates, and maintains original meeting series linkage for recurring events.

Acceptance Criteria

Atomic Reschedule Across All Calendars

Given a scheduled meeting with multiple participants across Google Calendar and Microsoft 365 And at least one external attendee using a non-integrated calendar And the organizer has pre-approved alternate time slots When an external guest selects one approved slot and confirms rebook Then the system updates the meeting time for all participants atomically And the event UID remains the same and the SEQUENCE is incremented exactly once And the original time is released for all participants And if any participant update fails, all updates are rolled back to the original time And the initiator and organizer receive a failure notification detailing the failed provider(s) And no partial updates persist

Preserve Conferencing and Meeting Artifacts

Given an existing meeting with a conferencing link/meeting ID, agenda text, file attachments, and a defined participant list When the meeting is rescheduled via one-tap rebook Then the conferencing link/meeting ID remains unchanged And the agenda and all attachments remain attached once and only once (no duplicates) And the participant list remains unchanged (no unintended adds/removals) And any join instructions, passcodes, and dial-ins are preserved

Cross-Platform Updates with ICS Fallback

Given attendees include Google Calendar users, Microsoft 365 users, and non-integrated email attendees When the reschedule is committed Then Google attendees receive a native Calendar API update and see the new local time on the same event UID And Microsoft 365 attendees receive a Graph API update and see the new local time on the same event UID And non-integrated attendees receive an email with an ICS update (METHOD: REQUEST) containing the same UID and an incremented SEQUENCE And all attendees’ calendars reflect the same absolute UTC time window And conferencing details remain clickable and unchanged across all delivery paths

Resource Booking Reassignment on Reschedule

Given the meeting has an associated room/resource booking When the meeting is moved to a new time Then the original resource booking is released And the same room is booked for the new time if available And if the room is unavailable at the new time, the meeting is updated without a room and the organizer is notified immediately with a Room Unavailable alert And no double-booking is created for any resource And attendees’ calendar entries remain consistent with the resource state

Idempotent Reschedule Request Handling

Given the rebook confirmation may be clicked multiple times or retried by the network/webhook When identical reschedule requests (same event UID and target slot) are received within the idempotency window Then only one calendar update is applied And the system returns the same success response for subsequent duplicates And no duplicate calendar events are created And no duplicate notification emails are sent And the event SEQUENCE is incremented exactly once

Recurring Series Linkage Preservation

Given the meeting belongs to a recurring series When a single occurrence is rescheduled via one-tap Then that occurrence becomes an exception retaining the series UID and RECURRENCE-ID And the rest of the series remains unchanged When the entire series is rescheduled Then the series master is updated while preserving RRULE and attendees And Google and Microsoft 365 displays continue to show correct series linkage for all participants

Updated Invites and Confirmations Distribution

Given the reschedule succeeds When the update is committed Then all attendees receive exactly one updated invitation/notification reflecting the new time And the organizer and initiating guest receive a confirmation message And notifications include old and new times rendered in each recipient’s local timezone And ICS attachments are included for non-integrated recipients And delivery status is logged per recipient without exposing duplicate sends

Fairness Enforcement

"As a distributed team member, I want rebooking to respect fairness rules so that inconvenient times are shared equitably across participants."

Description

Application of timezone-weighted, ergonomic rules during rebooking to avoid repeated early/late times for the same participants. Evaluates guest and organizer local times, rotates inconvenience across a series, and blocks slots that violate configured thresholds. Surfaces "most fair" recommendations and writes outcomes to the equity scoreboard for transparency and reporting.

Acceptance Criteria

Block Unfair Rebook Slots by Threshold

Given organizer-approved alternate slots and configured fairness policy values: WorkdayStart, WorkdayEnd, WindowSizeOccurrences, MaxEarlyLatePerWindow When the guest views candidate rebook times Then any slot where any participant’s local start time is before WorkdayStart or after WorkdayEnd is labeled Unfair and disabled for selection And any slot that would increase any participant’s count of early/late occurrences in the last WindowSizeOccurrences beyond MaxEarlyLatePerWindow is labeled Unfair and disabled And the UI displays the affected participants and the violated rule for each disabled slot

Rotate Inconvenience Across Series

Given a recurring meeting series with recorded inconvenience counts per participant over the last WindowSizeOccurrences And configured policy values: WeightEarly, WeightLate, MaxShareDelta When fairness scores are computed for each candidate slot Then each candidate receives a total fairness score derived from per-participant inconvenience contributions weighted by WeightEarly and WeightLate And any candidate whose projected share delta for any participant exceeds MaxShareDelta is excluded from selection And among remaining candidates, the allowed set favors those that reduce the variance of inconvenience counts across participants

Surface Most-Fair Recommendations

Given at least one fair candidate slot exists after applying fairness exclusions When presenting options on the rebook page Then the top 3 candidates with the lowest fairness scores are labeled Most fair and sorted ascending by score And if feasible, at least one Most fair candidate does not assign inconvenience to the same participant as the last occurrence And selecting any Most fair candidate succeeds without triggering a fairness violation

Write Outcomes to Equity Scoreboard

Given a rebook action is confirmed to a fair slot When persisting the result Then the system records to the Equity Scoreboard: meetingId, seriesId, occurrenceTimestampUTC, selectedSlotTimestampUTC, perParticipant {participantId, timezone, localStart, inconvenienceType, severityWeight}, totalFairnessScore, rotationBalancesBeforeAfter, selectedBy, and reasonCodes And the scoreboard entry is visible in the UI and API within 5 seconds of confirmation And the entry is included in export/report endpoints for the meeting series

Handle DST and Timezone Changes

Given a participant’s timezone setting changes or a DST transition affects the occurrence date When evaluating and displaying candidate slots Then local start times are computed using the effective IANA timezone rules for the occurrence date for each participant And fairness decisions (block/allow, scoring, recommendations) use these computed local times And any cached fairness evaluations for the affected meeting occurrence are invalidated and recomputed within 2 seconds of the detected change

Fallback and Organizer Override When No Fair Slots

Given all organizer-approved alternates are blocked by fairness rules When the guest opens the rebook options Then the UI indicates No fair times available and offers Request new times And the system generates the next three fair windows within FallbackHorizonDays and includes them in the request to the organizer And if the organizer overrides fairness to select a blocked slot, an override note is required, the action is logged with override=true and reasonCode=OrganizerOverride, and the scoreboard reflects the override

Secure Tokenized Access

"As an organizer, I want only intended invitees to rebook securely without needing an account so that my meetings aren’t hijacked or exposed."

Description

Signed, expiring, single-use rebooking links scoped to the specific event and invitee, with optional email verification/OTP. Detects forwarded links, rate-limits attempts, and enforces CSRF protection. No account required for guests while still attributing the actor for audit logs. Compliant with data privacy requirements and configurable link lifetimes.

Acceptance Criteria

Single-Use, Event-and-Invitee-Scoped Token

Given a valid signed token bound to event E and invitee I, when the link is opened before expiry, then the rebook page renders only for event E and invitee I and no other events are accessible. Given the same token is used to successfully submit a rebooking for event E, when the token is used again (GET or POST), then the system returns HTTP 410 Gone, shows a "Link already used" message, and performs no state changes. Given a token with a modified or invalid signature, when the link is opened, then the system returns HTTP 401/403, shows an "Invalid link" message, and does not reveal any event or invitee metadata. Rule: The token present in the URL contains no plaintext PII (e.g., no email or names), and all request-scoped identifiers are enforced from the token rather than client-provided parameters.

Configurable Token Expiration and Enforcement

Given the organization sets token_lifetime_hours = X within the allowed range (1–168 hours), when a new token is issued, then its server-side expiry is now + X hours and is embedded/saved accordingly. Given a token is accessed after its expiry time, when the page is requested, then the system returns HTTP 410 Gone, shows a "Link expired" message with a CTA to request a new link, and does not reveal event details. Given token_lifetime_hours is changed by an admin, when new tokens are created, then they use the new lifetime, and previously issued tokens retain their original expiry.

Forwarded Link Detection and Safe Response

Given a token for invitee email i@example.com, when the guest enters an email that does not equal i@example.com to proceed, then access is denied or escalated to verification, and an audit event "forwarded_link_detected" is recorded. Given the same token is opened from more than 3 unique IPs or device fingerprints within 1 hour, when attempting to proceed, then the user is forced into verification (OTP) before continuing and subsequent attempts are rate-limited. Rule: Until verification passes for a suspected forwarded link, the page redacts meeting title, organizer names, and other sensitive details.

Optional Email Verification/OTP

Given require_guest_otp = true, when the invitee opens the link, then they are prompted to confirm i@example.com and a 6-digit OTP is sent to that address. Given an OTP has been sent, when the correct code is entered within 10 minutes and no more than 5 attempts, then verification succeeds and the user proceeds to rebook. Given incorrect OTP attempts exceed 5 or the OTP expires, when further attempts are made, then verification is locked for 15 minutes and an audit entry is recorded. Given require_guest_otp = false, when the link is opened, then no OTP step is shown and rebooking proceeds using token validation alone. Rule: OTP resend generates a new code, invalidates the previous code, and is limited to 3 resends per 15 minutes per token.

Rate Limiting and Lockouts

Rule: A maximum of 10 sensitive actions (OTP submit, OTP resend, rebook POST) per IP and per token are allowed within 5 minutes; further requests receive HTTP 429 with a Retry-After header and no state change. Rule: OTP resend is capped at 3 per 15 minutes per IP and per token; additional requests are blocked with HTTP 429 and explanatory UI text. Given multiple identical rebook submissions carry the same Idempotency-Key within 2 minutes, when they are received, then only the first is processed and subsequent ones return HTTP 409 Conflict with no duplicate changes.

CSRF Protection on Rebook Actions

Given a rebook POST request is submitted without a valid CSRF token bound to the current session cookie, then the server returns HTTP 403 and no state changes occur. Given the POST request Origin/Referer does not match the rebook page origin, then the server returns HTTP 403 and no state changes occur. Rule: Session cookies used in the flow are set with Secure and SameSite=Lax (or stricter) flags enabled.

Audit Logging and Actor Attribution (No Account)

Rule: For each action (token issued, link opened, OTP sent, OTP verified success/fail, forwarded_link_detected, rate_limited, rebook submitted success/fail, token expired/invalid), an immutable audit log entry is created capturing event_id, invitee_id, token_id, actor_email (from token or verified input), timestamp (UTC), IP, user_agent, action, and result. Given a rebooking is completed by a guest without an account, when the action is logged, then the actor is attributed as "guest:<invitee_email>" and includes token_id for traceability. Rule: Audit log entries are accessible only to authorized organizer/admin roles for the related event and are retained according to configured data retention policies.

Notifications & Activity Trail

"As an organizer, I want clear notifications and an audit trail of rebooking actions so that I stay informed and can track changes over time."

Description

Real-time notifications to organizers and attendees on rebook proposals, approvals, and confirmations via email and Slack, plus webhook callbacks for integrations. Provides an in-app activity timeline with before/after times, actor identity, timestamps, and reason codes. Supports notification preferences and digesting to reduce noise.

Acceptance Criteria

Real-Time Proposal Notification to Organizer and Internal Attendees

Given an external guest submits a rebook proposal from the invite page and the proposal is persisted When the event is recorded Then the organizer and all internal attendees receive notifications via Email and Slack within 10 seconds And each notification includes: meeting title, proposed slot in recipient local timezone and UTC, actor name and email, reason code (if provided), actionable links to Approve/Decline/View Proposal, and a unique notification_id And no duplicate notifications are sent to the same recipient within a 5-minute window for the same proposal_id And the proposing external guest receives a single email acknowledgment with a proposal tracking link And delivery outcomes are logged per recipient and channel with timestamp and message_id

Approval or Decline Notification and State Synchronization

Given an organizer approves or declines a rebook proposal When the decision is saved Then the proposing guest and all attendees receive notifications within 10 seconds (Email to all; Slack to internal attendees) And the notification states the decision, decision maker identity, optional reason code, and provides a link to the updated proposal status And pending proposal notifications are marked resolved in the activity timeline with a reference to the decision event_id And duplicate notifications for the same decision and recipient are prevented within a 5-minute window And delivery outcomes are logged per recipient and channel with timestamp and message_id

Rebook Confirmation Notification After Calendar Update

Given a proposal has been approved When calendar updates succeed for all required attendees Then send a confirmation notification via Email and Slack within 10 seconds to organizer and internal attendees, and Email to external guests And the confirmation includes before_start_at and after_start_at (recipient local timezone and UTC), preserved conferencing link, and an updated ICS attachment or calendar update link And if any attendee's calendar update fails after 3 retry attempts within 15 minutes, send a failure notification to the organizer including attendee identifier and error code, with a Retry action link And all confirmation and failure notifications are logged with outcome status, timestamp, and message_id

Webhook Callbacks: Delivery, Security, and Idempotency

Given webhook subscriptions are configured and enabled for the workspace When any of the following events occur: proposal.created, proposal.approved, proposal.declined, rebook.confirmed Then POST a JSON payload to the subscriber endpoint within 5 seconds containing: event_id, event_type, occurred_at (ISO 8601 UTC), meeting_id, actor {id, name, email}, before_start_at, after_start_at, reason_code (optional) And include headers X-TimeMeld-Signature (HMAC-SHA256 of raw body using shared secret) and X-TimeMeld-Timestamp And treat any non-2xx response or request timeout > 10 seconds as a failure; retry up to 12 attempts with exponential backoff and jitter (approx schedule: 30s, 1m, 2m, 4m, 8m, 16m, 32m, 1h, 2h, 4h, 8h, 16h), ceasing on HTTP 410 or when subscription is disabled And ensure idempotency by setting Idempotency-Key equal to event_id and not delivering duplicates to the same endpoint And record per-attempt delivery status and final Pass/Fail visible in the activity timeline with last response code

In-App Activity Timeline Fidelity and Auditability

Given a user views the meeting's activity timeline When rebook-related events have occurred Then entries for proposal, approval/decline, confirmation, and webhook delivery appear newest-first, paginated 50 per page, loading in under 1 second on a standard broadband connection And each entry displays: actor display name and email, event type, timestamp (relative plus ISO 8601 UTC on hover), before_start_at and after_start_at (with timezone abbreviation), reason code (if any), and a link to the related record And entries are immutable; corrections or system adjustments create a new entry that references the prior event_id And access control ensures only invitees and org admins see the full timeline; external guests see only events in which they are participants And times render in the viewer's local timezone while preserving UTC in metadata for copy/export

Notification Preferences, Quiet Hours, and Digesting

Given a user sets notification preferences When preferences specify per-channel (Email, Slack) and per-event-type (proposal, approval, confirmation) settings Then notifications respect these settings: disabled channels do not receive messages; enabled channels do, with no automatic fallback unless explicitly configured And users can define daily quiet hours in their local timezone; notifications generated during quiet hours are deferred into a digest unless marked critical by policy And a daily digest is sent at the user's chosen local time summarizing deferred notifications in the past 24 hours with counts and links; individual messages for those events are not sent And changes to preferences take effect within 1 minute and are logged as entries in the activity timeline indicating actor, fields changed, and timestamp And external guests may opt into Email and daily digest via invite-page preferences; Slack is unavailable to external guests

Conflict Handling & Concurrency

"As a guest, I want the system to handle conflicts and simultaneous changes gracefully so that my rebooking either succeeds cleanly or provides safe alternatives without confusion."

Description

Concurrency-safe booking flow with short-term slot holds, conflict detection against all participants and resources, and graceful fallbacks that suggest the next best fair slot. Implements locking, retries, and rollback to maintain consistency across calendars. Communicates clear errors to guests and preserves proposals when finalization fails.

Acceptance Criteria

Short-Term Slot Hold Prevents Double Booking

Given two guests attempt to book the same organizer-approved slot within the hold TTL When the first request places a hold on the slot Then the second request sees the slot as unavailable and cannot proceed to confirmation And the default hold TTL is 3 minutes (configurable 1–10 minutes) And the hold state is reflected to all viewers within 2 seconds And on successful confirmation the hold converts to a booking; on expiry or cancel the slot immediately becomes available to others

Conflict Detection Across All Participants and Resources

Given a proposed slot overlaps any busy event for required participants or required resources When a guest attempts to finalize the booking Then the system blocks confirmation and lists each conflict (participant/resource, event title if visible, start/end time) And conflicts consider all linked calendars marked as busy, working-hour constraints, and resource calendars And the system does not create partial bookings or tentative holds on conflict

Graceful Fallback Suggests Next Best Fair Slot

Given finalization fails due to a detected conflict or race condition When the guest requests alternatives Then the system returns at least 3 alternative slots within the next 7 days, ranked by TimeMeld fairness score and timezone ergonomics And each alternative respects organizer-approved windows and fairness rules (no repeated inconvenient windows for the same attendee within the last 3 occurrences) And selecting an alternative is one tap and preserves conferencing details and invitee list

Atomic Booking with Locking, Retry, and Rollback

Given multiple calendars must be updated to complete a booking When any calendar write fails or times out Then all previously written events are rolled back within 5 seconds and any holds are released And a per-slot, per-meeting lock prevents concurrent writes; the lock is released on success or failure And the system retries up to 2 times with exponential backoff (e.g., 200ms then 400ms) And operations are idempotent via a booking token so duplicates are not created

Idempotent Confirmation Handles Double-Submit

Given a guest double-clicks confirm or resubmits the request within 30 seconds When duplicate finalize requests with the same booking token reach the server Then exactly one booking is created And all responses return the same booking ID and start/end time And no duplicate emails or notifications are sent

Clear Errors and Proposal Preservation on Failure

Given finalization fails after a guest submits a slot When the error is surfaced to the UI Then the guest sees an actionable message within 2 seconds including reason category (conflict, permission, network) and next steps And the original proposal is saved in a pending state visible to both guest and organizer And the organizer receives a notification with the failure reason and proposed slot And an audit log entry with a correlation ID is recorded And all holds and partial changes are cleaned up

Hold Expiry and Abandonment Recovery

Given a guest has placed a hold by selecting a slot but does not confirm When the hold TTL elapses or the rebook page is closed Then the hold auto-expires and the slot is released And the slot’s availability updates for all viewers within 2 seconds And no calendar events or invites are created

Calendar Deeplink

One‑tap Add to Calendar for Google, Outlook, and Apple with ICS fallback. Injects the correct timezone, conferencing link, and updates that auto‑sync if the meeting moves—so guests never juggle stale links or wrong times.

Requirements

Provider-Specific Deeplink Generation

"As an invited attendee, I want a one-tap button that adds the meeting to my calendar provider so that I don’t have to manually copy details or worry about compatibility."

Description

Generate provider-specific one-tap Add to Calendar links for Google Calendar, Outlook (web/desktop), and Apple Calendar with a robust ICS fallback. Links must prefill title, description, organizer, attendees (optional), location with conferencing URL, reminders, and a stable event UID. Ensure proper URL encoding and support for mobile intents/deeplinks. Integrate with TimeMeld’s meeting object to pull canonical details and emit signed links usable across email, web, and Slack surfaces. Outcome: attendees add events in one tap without manual copy/paste, regardless of provider or device.

Acceptance Criteria

One-Tap Add to Google Calendar (Email/Mobile)

Given a signed Google Calendar deeplink generated from the TimeMeld meeting object When a recipient taps it in Gmail or a mobile browser with Google Calendar installed Then the Google Calendar app opens directly and shows an add-event sheet prefilled with: And Title equals meeting.title And Description contains meeting.description plus the conferencing URL And Organizer equals meeting.organizer.email And Attendees list equals meeting.attendees[*].email when provided; omitted when empty And Location equals conferencing URL host or meeting.location if provided And Start/End reflect meeting.start and meeting.end in meeting.timezone (no device timezone override) And A default reminder 10 minutes before is set And Event UID equals meeting.uid and matches the ICS UID And All characters are percent-encoded; non-ASCII renders correctly And If the composed URL exceeds 2000 chars, a shortlink is used that resolves to the same intent within 300 ms p95 And Tapping Save adds the event without additional edits

Outlook Web and Desktop Deeplink Resolution

Given a signed Outlook deeplink for the TimeMeld meeting When opened in Outlook Desktop (Windows/macOS) Then an ms-outlook:// deep link opens a prefilled event compose window with title, description (including conferencing URL), organizer, optional attendees, location, start/end in meeting.timezone, a 10-minute reminder, and a stable UID stored in iCalUId or custom ExtendedProperty When opened in Outlook Web (OWA) Then an https://outlook.office.com template opens with the same fields prefilled And If the deep link scheme is blocked, an HTTPS fallback path is used automatically And Open-to-compose latency is ≤ 1.5 seconds on a 4G connection p95 And All parameters are URL-encoded; special characters and emojis render correctly

Apple Calendar Add via webcal/ICS on iOS and macOS

Given a signed webcal:// or .ics link generated from the TimeMeld meeting When tapped in Mail/Safari on iOS or clicked in Safari/Mail on macOS Then the native Calendar prompts to add a single event prefilled with: And UID equals meeting.uid And DTSTART/DTEND include TZID=meeting.timezone And VTIMEZONE component is included for meeting.timezone And ORGANIZER and ATTENDEE lines are present per RFC 5545 when attendees provided And DESCRIPTION includes the conferencing URL and plain-text details And LOCATION equals conferencing URL host or meeting.location if provided And VALARM is set 10 minutes before And URL property points to the conferencing link And The ICS validates against RFC 5545 with zero errors and size ≤ 50 KB And Add requires ≤ 2 taps

ICS Fallback for Unknown/Blocked Providers and Slack

Given a recipient clicks the Add to Calendar link from Slack (desktop/mobile) or an unknown/unsupported client When provider detection fails or is blocked Then TimeMeld serves a signed webcal:// subscription by default, with an HTTPS .ics download fallback if webcal is unsupported And The ICS contains UID=meeting.uid, SEQUENCE=current sequence, METHOD:PUBLISH, and PRODID identifying TimeMeld And HTTP headers include Content-Type: text/calendar; charset=utf-8 and Cache-Control: no-store And The link functions on iOS, Android, Windows, and macOS default calendar apps And End-to-end add flow completes in ≤ 2 seconds on broadband p95

Reschedule Auto-Sync via Stable UID and SEQUENCE

Given attendees added the event via a webcal subscription or Apple Calendar using the provided ICS And the meeting is rescheduled in TimeMeld When the client next refreshes the subscription Then the ICS for UID=meeting.uid has SEQUENCE incremented and updated DTSTART/DTEND/TZID And Apple Calendar and Google Calendar (subscribed by URL) reflect the new time within 5 minutes p95 And Conferencing URL remains unchanged and valid And Attendees are not duplicated and reminders persist

Link Signing, Tamper Resistance, and Cross-Surface Usability

Given any provider-specific or ICS fallback link When the token is expired or modified Then the endpoint returns HTTP 410 (gone) for web or an in-app error page with a one-tap request-new-link action And Valid links use an HMAC-SHA256 signature over meetingId, provider, nonce, and expiration; expiration ≤ 30 days And No PII (attendee emails/names) is embedded in the URL; details are resolved server-side post-validation And The same signed URL functions from email, web pages, and Slack without exposing the token in link previews (via no-unfurl meta or redirect) And All redirects complete within 300 ms p95

Timezone Injection, URL Encoding, and DST Edge Cases

Given a meeting in a DST transition window or a half/quarter-hour timezone (e.g., Asia/Kathmandu, Australia/Adelaide) When generating Google, Outlook, Apple, and ICS links Then all links encode start/end using IANA TZID=meeting.timezone (not fixed UTC offsets) And ICS includes a correct VTIMEZONE with transitions covering at least the next 2 years And Device display after add matches the intended local time And No silent UTC conversion occurs without TZID/VTIMEZONE And Titles/descriptions with newlines, commas, ampersands, and emojis are correctly percent-encoded in URLs and UTF-8 in ICS And Automated tests cover ≥ 10 DST transitions and ≥ 5 rare-offset zones

Timezone-Accurate ICS with VTIMEZONE

"As an attendee in a different timezone, I want the event to appear at the correct local time so that I don’t join an hour early or late."

Description

Produce ICS files that include VTIMEZONE components and TZID on DTSTART/DTEND to preserve the organizer’s intended timezone across providers and daylight-saving transitions. Include UTC equivalents for cross-provider consistency and map IANA to Windows timezones for Outlook. Persist the canonical timezone from TimeMeld and convert appropriately for attendees’ local displays without altering the scheduled instant. Outcome: meetings consistently appear at the correct local time, eliminating early/late joins due to DST or parsing differences.

Acceptance Criteria

ICS Exports With VTIMEZONE And TZID

Given an event with organizer timezone set to an IANA zone (e.g., America/Los_Angeles) When an ICS file is generated for the event Then the ICS contains exactly one VTIMEZONE component whose TZID equals the organizer’s timezone And DTSTART and DTEND are expressed with TZID referencing that VTIMEZONE (no floating times) And DTSTAMP and LAST-MODIFIED are UTC values with a trailing Z And the ICS passes RFC 5545 validation with zero errors and zero warnings in the linter

Cross-Provider Time Consistency (Google, Outlook, Apple)

Given two test events scheduled at 2025-03-09 09:00 America/Los_Angeles and 2025-11-02 09:00 America/Los_Angeles When the ICS is imported into Google Calendar (web), Outlook for Windows, Outlook on the web, and Apple Calendar Then each provider displays the local start and end times that correspond to the same UTC instants (0-minute variance) And no provider shows an off-by-one-hour shift or duplicate entries

Windows Timezone Mapping for Outlook

Given an event whose organizer timezone is an IANA zone with a known Windows mapping (e.g., America/New_York → Eastern Standard Time) When generating an ICS intended for Outlook on Windows Then the ICS applies the correct Windows timezone mapping so Outlook displays the correct local time across DST And verification on Outlook for Windows shows the expected local time with 0-minute variance relative to the intended UTC instant

DST Transition Integrity (Spring Forward and Fall Back)

Given an event during the spring-forward gap (e.g., 2025-03-09 02:30 America/Los_Angeles) and an event during the fall-back overlap (e.g., 2025-11-02 01:30 America/Los_Angeles) When ICS files are generated and imported into Google, Outlook (Windows and web), and Apple Calendar Then the spring-forward event is encoded using a roll-forward policy to the next valid local time and displays consistently across providers And the fall-back event resolves to the first occurrence hour using TZID rules and displays consistently across providers And neither event is shifted by ±60 minutes relative to the intended instant

Update Sync via UID and SEQUENCE

Given an event initially distributed via ICS with METHOD:REQUEST and a stable UID When the meeting is rescheduled in TimeMeld Then a new ICS is produced with the same UID and SEQUENCE incremented by 1 And Google Calendar, Outlook (Windows and web), and Apple Calendar update the existing event in place within 2 minutes (no duplicates) And the conferencing link remains unchanged unless explicitly modified in the update And cancellations use METHOD:CANCEL and remove the existing event

Preserve Scheduled Instant With Local Display Conversion

Given attendees in multiple timezones different from the organizer’s timezone When they import the ICS Then each attendee sees the event at their local time that corresponds to the same UTC instant encoded in DTSTART/DTEND (0-minute variance) And the ICS retains the organizer’s canonical timezone via TZID/V.TIMEZONE And changing a device’s timezone after import re-renders the local time while preserving the same UTC instant

Auto-Sync Updates and Cancellations

"As an organizer, I want attendees’ calendars to update automatically when I reschedule or cancel so that no one follows a stale time or link."

Description

Ensure calendar entries stay in sync when meetings move or are canceled. Reuse a stable event UID and increment SEQUENCE in ICS updates; emit METHOD:REQUEST for updates and METHOD:CANCEL for cancellations. Provide a per-event webcal subscription URL to enable background refresh across providers; when connectors are authorized, push updates via Google and Microsoft APIs for faster propagation. Guarantee that conferencing links, times, and titles remain current without attendee action. Outcome: no stale entries or orphaned links on attendee calendars.

Acceptance Criteria

ICS Update: Stable UID and SEQUENCE Increment

Given an attendee added the event via the TimeMeld deeplink When the organizer changes the start time, title, or conferencing link Then TimeMeld issues an ICS update with the same UID And SEQUENCE is increased by exactly 1 relative to the last sent value And METHOD:REQUEST is set and DTSTAMP reflects the update time in UTC And attendees' calendars (Google, Outlook, Apple) show the updated time in their local timezone, updated title, and new conferencing link And no duplicate events are created

ICS Cancellation: METHOD:CANCEL Removes Event

Given attendees previously added the event via the TimeMeld deeplink or webcal subscription When the organizer cancels the meeting in TimeMeld Then TimeMeld emits an ICS with the same UID, incremented SEQUENCE, and METHOD:CANCEL And the VEVENT includes STATUS:CANCELLED And attendee calendars remove the event or mark it as canceled And any conferencing link is no longer accessible from the calendar entry

Webcal Subscription: Background Refresh Publishes Latest State

Given an attendee subscribes to the per-event webcal URL from the deeplink When the organizer changes the meeting details Then a GET on the webcal URL returns an ICS with the same UID and an increased SEQUENCE And the ICS reflects the latest start/end/timezone, title, and conferencing link And HTTP responses include ETag and Last-Modified headers And changes are present on the feed within 60 seconds of the organizer update

Push Connectors: Fast Propagation to Google and Microsoft

Given the host has authorized Google and Microsoft connectors in TimeMeld And attendees include at least one Google Calendar user and one Microsoft 365/Outlook user When the organizer updates or cancels the event Then TimeMeld calls the respective Calendar APIs to update or cancel the event by stable provider event ID And attendee calendars reflect the change within 2 minutes And no duplicate events are created in provider calendars

RSVP State Preserved Across Updates

Given attendees have responded (Accepted, Tentative, or Declined) When TimeMeld sends an update via ICS, webcal, or provider API Then attendee RSVP status remains unchanged on their calendar And only fields changed by the organizer are updated (time, title, conferencing link, description)

Timezone and DST Correctness After Move

Given the original event occurs before a DST transition for at least one attendee timezone When the organizer moves the meeting to after the DST transition Then the ICS includes appropriate VTIMEZONE components for referenced timezones And attendees view the meeting at the correct local wall time after the move And no duplicate all-day or off-by-one-hour artifacts appear

Idempotent Update Delivery

Given an update or cancellation is delivered multiple times due to retries When the same SEQUENCE is processed more than once Then TimeMeld does not create duplicates or regress event fields And only updates with a higher SEQUENCE mutate stored or published event state

Conferencing Link Fidelity

"As a participant, I want the calendar entry to contain a working join link so that I can enter the meeting without hunting for it."

Description

Embed the most current conferencing join details in provider-native fields and the event body. For Google API events, populate conferenceData/hangoutLink; for ICS, set LOCATION to the meeting name and include full join URL, passcodes, and dial-ins in DESCRIPTION. Maintain link integrity during reschedules through the auto-sync pipeline and sanitize content to avoid client stripping. Optimize for mobile deep links and ensure links remain clickable across email clients. Outcome: attendees can join directly from the calendar entry every time.

Acceptance Criteria

Google Calendar Event Uses Native Conferencing Fields

Given a meeting scheduled via TimeMeld into Google Calendar with conferencing details When the event is created through the Google Calendar API Then the event includes conferenceData.hangoutLink for Google Meet OR a primary conferenceData.entryPoints[].uri for the selected provider And events.get returns a non-null native join link And the event description also includes the same join URL, passcode (if any), and at least one E.164 dial-in number And the join link is clickable from Google Calendar on Web and Android/iOS And no duplicate or conflicting join links appear in the event

ICS File Carries Complete Join Details

Given a meeting exported as an ICS from TimeMeld When the ICS is opened in Apple Calendar, Outlook, and Google Calendar Then LOCATION equals the TimeMeld meeting name (<= 255 characters) And DESCRIPTION includes: a labeled primary join URL, passcode, and at least one E.164 dial-in number And DESCRIPTION is plaintext with RFC 5545-compliant line folding (no HTML) And the ICS validates with zero errors/warnings in an RFC 5545 validator And all links are clickable in the resulting calendar entry across those clients

Auto-Sync Maintains Link Fidelity on Reschedule

Given an existing meeting with conferencing details created by TimeMeld When the organizer reschedules the meeting via TimeMeld Then the Google event is updated in place (same event.id) and the ICS keeps the same UID And the primary join URL and passcode remain unchanged And invitees receive an updated invitation reflecting the new time And no additional/duplicate conferencing blocks are appended to DESCRIPTION And the update is published by TimeMeld within 30 seconds of the reschedule action

Mobile Deep Links Resolve to Native Apps

Given a device with the provider’s native app installed (e.g., Zoom, Google Meet, Teams) When the user taps the join link from the calendar entry in Apple Calendar, Google Calendar, or Outlook mobile on iOS 16+ or Android 11+ Then the OS opens the corresponding app and navigates directly to the meeting within 2 seconds And if the app is not installed, the link opens the provider’s HTTPS join page in the default browser And the same link works from the event description and any native join button the client renders

Links Remain Clickable Across Email and Calendar Clients

Given a calendar invitation or update with conferencing details generated by TimeMeld When the invite is viewed in Gmail Web, Outlook Desktop (Windows/macOS), Outlook Web, Apple Mail, and iOS Mail Then the primary join URL renders as a single clickable link (no broken wrapping) And dial-in numbers render as tap-to-dial tel: links on mobile clients And links remain clickable after SafeLinks/URL rewriting where applicable

Content Sanitization Prevents Client Stripping

Given conferencing details provided by an organizer or provider When TimeMeld injects these details into native fields and the event body Then HTML/scripts/unsupported markup are stripped; only plaintext and valid URLs remain And only whitelisted schemes are allowed (https, zoommtg, tel); others are removed And non-essential tracking parameters are removed while preserving join functionality And DESCRIPTION length <= 8,000 characters and LOCATION length <= 255 characters And Google, Outlook, and Apple clients display the join link without stripping or rewriting it

Secure Signed Deeplinks

"As a security-conscious admin, I want add-to-calendar links to be safe and non-shareable beyond the intended recipients so that sensitive meeting details are protected."

Description

Issue tamper-proof, expiring deeplinks that resolve to provider-specific links or ICS. Sign links with HMAC over event ID, attendee hash, and expiry; enforce HTTPS, short TTLs, and scope-limited tokens. Implement rate limiting, revoke on cancel, and avoid PII in query parameters. Log access for auditability and integrate with TimeMeld’s auth and event store. Outcome: only intended recipients can use the link, mitigating leakage and enumeration risks.

Acceptance Criteria

Recipient-Limited Access and Correct Resolution

Given a signed deeplink scoped to event_id E and attendee_hash H, When the intended recipient opens it over HTTPS before expiry, Then the system resolves to the correct provider-specific URL or serves an ICS file that contains the current event start/end time in the recipient’s timezone and the active conferencing link. Given the same deeplink, When opened by a user whose context does not match attendee_hash H (e.g., different authenticated identity or no proof token), Then the system responds 403 Forbidden with a generic error and no event metadata leakage (no title, time, organizer, or location in body or headers).

HMAC Signature Composition and Key Rotation

Given a deeplink, Then its signature is computed as HMAC-SHA256 over the canonical base64url string "event_id.attendee_hash.expiry_epoch" using the active signing key; the link includes parameters: sig (base64url) and kid (key id). When a request is received, Then signature verification is performed in constant time; if kid is unknown or sig invalid, respond 403 and do not redirect or serve ICS. And key rotation is supported by accepting previous keys for a grace period ≤ 48 hours from rotation time; after the grace period, links signed with old kid are rejected with 403.

Tamper Detection and Rejection

Given any modification to event_id, attendee_hash, expiry_epoch, kid, or sig, When the link is requested, Then the system responds 403 Forbidden with a generic message, and no redirect or ICS content is returned. And an audit_log entry is created with fields: event_id_hash, attendee_hash, token_id_hash (if present), outcome="tamper_detected", request_id, ip_hash, user_agent_hash, and timestamp.

Expiry Enforcement with Short TTL

Given a signed deeplink with TTL ≤ 24h (system default 6h), When it is requested after expiry_epoch, Then the system returns 410 Gone with a non-identifying message and no redirect or ICS content; audit outcome="expired" is recorded. When requested before expiry, Then the response includes Cache-Control: no-store and Pragma: no-cache, and the API does not reveal remaining TTL in body or headers beyond standard HTTP caching controls.

Revocation on Cancel and Correct Reschedule Behavior

Given an event E is cancelled in TimeMeld, When any previously issued deeplink for E is requested, Then respond 410 Gone; audit outcome="revoked", reason="cancelled" is recorded. Given an event E is rescheduled, When a previously issued valid deeplink for E is requested before its expiry, Then it resolves to the updated provider-specific URL or ICS reflecting the new time and conferencing details; the signature remains valid because it excludes mutable fields such as start time.

Rate Limiting and Enumeration Mitigation

Given repeated requests to the same deeplink token or enumeration attempts (varying sig/kid/event_id) from a single IP or /24, When thresholds exceed 10 requests per minute per token and 100 requests per hour per IP range, Then subsequent requests receive 429 Too Many Requests with a Retry-After header; no redirect or ICS content is served. And after 3 threshold breaches within 15 minutes, Then a temporary block of 15 minutes is applied to the token and IP range; audit outcome="rate_limited" with counters recorded; legitimate requests after cooldown succeed if otherwise valid.

Privacy-Preserving URLs, HTTPS-Only, and Allowlisted Redirects

Given any generated deeplink, Then the URL path and query parameters MUST NOT contain raw PII (e.g., email, name); only opaque identifiers and hashes using base64url without padding are permitted. And all accesses must occur over HTTPS; HSTS header max-age ≥ 6 months is set; HTTP requests are rejected or 301 to HTTPS before any verification occurs; no mixed-content redirects are allowed. And redirect destinations are restricted to an allowlist of provider domains (Google Calendar, Microsoft Outlook/Office, Apple Calendar endpoints); if the resolved destination is not on the allowlist, Then respond 400 Bad Request and do not redirect. And access and audit logs store only hashed identifiers and minimal metadata (timestamps, outcome, ip_hash, request_id); no raw IPs, emails, titles, or times are logged.

Device and Provider Auto-Detection UI

"As an attendee opening the invite on my phone, I want the right calendar option preselected so that adding the event takes one tap."

Description

Detect user device/OS and likely calendar provider to surface the most relevant one-tap option with graceful fallback. For iOS/Safari prefer .ics, for Android/Chrome prefer Google intent, for Outlook users present Outlook web/desktop options. Provide accessible, localized buttons usable in email, web embeds, and Slack messages with ARIA labels and keyboard support. Track click-through and completion to inform UX. Outcome: a streamlined, one-tap experience that minimizes friction across contexts.

Acceptance Criteria

iOS Safari one-tap Apple Calendar via webcal with auto-sync

Given a recipient opens the invite email on iOS and taps the Add to Calendar CTA When device/OS detection identifies iOS with Safari Then the primary option shown is "Add to Apple Calendar" And the link uses the webcal:// scheme to an ICS feed with a stable UID for the event And the event data includes correct IANA timezone, title, description, conferencing link, location, organizer, and alarms (if configured) And tapping opens the Apple Calendar subscribe/add flow and adds the event on confirmation And subsequent changes to the source event auto-sync to the subscribed event within 5 minutes of publication And if webcal is unsupported, the fallback .ics download with the same UID and fields is initiated

Android Chrome one-tap Google Calendar with intent and web fallback

Given a recipient on Android using Chrome taps Add to Calendar When detection identifies Android + Chrome Then the primary option shown is "Add to Google Calendar" And tapping attempts to launch the Google Calendar app via an intent targeting package com.google.android.calendar with prefilled title, description (including conferencing link), location, start/end in the event timezone And if the intent cannot be resolved, it falls back to the Google Calendar web URL (render?action=TEMPLATE) with the same fields encoded And a secondary "Subscribe for updates" option is offered using a GCal URL with a cid pointing to the event's webcal ICS; if chosen, subsequent event changes appear in Google Calendar within 10 minutes And if neither the app nor web is available, an .ics fallback is provided

Outlook users see Desktop and Web options with graceful fallback

Given a recipient is on Windows or user-agent indicates Outlook usage When the user taps Add to Calendar Then the UI presents two prominent options: "Outlook Desktop" and "Outlook Web" And selecting Outlook Desktop opens the system handler for .ics (or ms-outlook:// if available) with the event containing correct timezone, conferencing link, and a stable UID And selecting Outlook Web opens the Outlook/Office web compose/add flow with the same details prefilled And a "Subscribe to updates" option is available where supported (internet calendar), ensuring future changes sync within 10 minutes And if the Desktop handler is unavailable, clicking it falls back to the Outlook Web option without error

Cross-context rendering in Email, Web Embed, and Slack

Given the Add to Calendar CTA is included in an email When viewed in major clients (Gmail web, Outlook desktop, Apple Mail) Then a single primary button renders with a tappable area ≥ 44x44 dp and links to a detection landing page with no client-blocked scripts required Given the component is embedded on the web When the page loads Then the correct primary provider button appears within 300 ms with a visible secondary list for other providers and .ics fallback Given a TimeMeld link is posted in Slack When Slack unfurls the link Then a Block Kit message displays provider buttons (Google, Outlook, Apple/.ics) and clicking opens the detection landing page with the detected provider preselected

Keyboard-accessible, screen-reader-friendly buttons (WCAG 2.2 AA)

Given the Add to Calendar UI is rendered on the web When a user navigates using keyboard only Then all interactive elements are reachable in logical order, have visible focus indicators, and activate via Enter and Space And each button has an aria-label that includes the provider and meeting title (e.g., "Add to Google Calendar: Sprint Review") And roles/states are semantically correct (role="button", aria-pressed only when applicable) And color contrast for text and icons on buttons is ≥ 4.5:1 and target size is ≥ 44x44 px And screen readers announce focus and action without redundant or missing information

Localized labels and date/time with RTL support

Given a locale is provided (e.g., es-ES, fr-FR, ar) When the Add to Calendar UI renders Then button labels and helper text are translated for the locale, and date/time formats reflect the locale conventions And the timezone abbreviation/name remains accurate while localized where applicable And right-to-left locales render with dir="rtl", mirrored layout, and correct reading order And if a translation is missing, content gracefully falls back to English without broken placeholders And the same locale is applied consistently in email, web embed, and Slack contexts

Click-through and completion telemetry

Given the Add to Calendar UI is shown in any context (email landing, web, Slack) When the component is displayed, a provider button is clicked, a deep link is launched, or an add/import completes Then analytics events are emitted for view, click, launch, and completion with fields: feature_id, requirement_id, provider, platform, context, locale, detection_confidence, outcome, meeting_id_hash, timestamp And events exclude personal content (no titles/descriptions beyond hashed IDs) and respect user consent/opt-out And ≥ 95% of events are delivered within 60 seconds with retry-once behavior for transient failures And telemetry can be segmented by context and provider to compute click-through and completion rates

Smart Nudges

Localized reminders scheduled to the guest’s day (e.g., 24h/1h/10m before) with a single “Join Now” button and backup dial‑in. Reduces no‑shows and last‑minute confusion, while keeping reminders respectful of local hours.

Requirements

Local Time & Quiet Hours Compliance

"As an organizer, I want reminders to respect each attendee’s local hours so that nudges are helpful, not intrusive."

Description

Detect and persist each attendee’s local timezone from calendar metadata, invite headers, IP/locale hints, or explicit user settings, with full daylight‑saving awareness. Apply organizer‑defined quiet‑hours policies (e.g., do not send between 21:00–07:00 local) so reminders are automatically shifted to the nearest permissible window without violating the intended offsets (24h/1h/10m relative to the attendee’s local start time). Provide conflict handling for last‑minute meetings (e.g., if 1h falls in quiet hours, choose the nearest earlier permissible send). Expose controls at workspace, team, and event level; allow per‑attendee overrides when consented. Include a preview timeline that visualizes planned send times across timezones before scheduling. Log timezone resolution, policy decisions, and final send times for auditability. Fallback gracefully when timezone is unknown by defaulting to organizer’s policy or prompting for confirmation. Ensure compliance with regional privacy regulations and respect user notification preferences.

Acceptance Criteria

Timezone Resolution & DST Persistence

Given an attendee has an explicit timezone setting, When reminders are scheduled, Then the explicit setting is used and persisted with source=UserSetting and confidence=High. Given multiple timezone signals (CalendarMetadata, InviteHeader, Locale, IP) and no explicit setting, When resolving timezone, Then the system selects the highest-precedence source using the order UserSetting > CalendarMetadata > InviteHeader > Locale > IP and persists the chosen timezone with source and confidence. Given an event spans a daylight-saving transition for the attendee’s resolved timezone, When computing 24h/1h/10m reminders, Then send times align to the attendee’s local wall‑clock times accounting for DST shift (no 1-hour drift). Given a timezone has been persisted for an attendee, When the attendee is invited to a new event, Then the persisted timezone is reused unless an explicit override is provided.

Quiet Hours Application & Conflict Resolution

Given organizer quiet hours are 21:00–07:00 local and an attendee’s meeting is at 14:00 local, When computing 24h/1h/10m reminders, Then 24h=previous day 14:00, 1h=13:00, and 10m=13:50 (no sends during quiet hours). Given organizer quiet hours are 21:00–07:00 local and a meeting is at 07:30 local, When computing the 1h and 10m reminders, Then 1h (06:30) and 10m (07:20) are evaluated against quiet hours and any that fall within are shifted to the nearest earlier permissible time (e.g., boundary 21:00 previous day) and logged with shift_reason=quiet_hours. Given a computed nearest earlier permissible time is in the past relative to scheduling, When evaluating a reminder, Then the reminder is suppressed (not sent) and logged with outcome=suppressed and reason=quiet_hours_past. Given multiple reminders are shifted due to quiet hours, When finalizing the schedule, Then no duplicate send times are produced for the same attendee and event.

Granular Policy Controls & Per-Attendee Overrides

Given workspace-, team-, and event-level quiet-hours policies exist, When policies conflict, Then precedence is PerAttendeeOverride > Event > Team > Workspace. Given an organizer enables a per-attendee override with the attendee’s consent recorded, When computing reminders for that attendee, Then the override window is applied and consent metadata (who/when/method) is persisted. Given a policy is updated at any scope, When the organizer saves changes, Then all planned send times are recalculated within 5 seconds and the preview reflects the new schedule. Given an attendee has override quiet hours 22:00–06:00 and the team policy is 21:00–07:00, When reminders are computed, Then that attendee’s reminders respect 22:00–06:00 while others follow 21:00–07:00.

Preview Timeline Visualization Across Timezones

Given an event with attendees across multiple timezones, When the organizer opens the preview timeline, Then each attendee row shows 24h/1h/10m planned send timestamps in the attendee’s local time with quiet-hour periods visually indicated. Given any reminder is shifted due to quiet hours or conflicts, When viewing the preview, Then the item is marked as shifted and a tooltip reveals original_intended_time and shift_reason. Given the organizer changes a policy (e.g., quiet hours or overrides), When viewing the preview, Then the timeline updates to reflect new send times within 1 second without page reload. Given an attendee’s timezone is changed, When refreshing the preview, Then all displayed send times recalculate to the new local timezone.

Audit Logging of Timezone & Policy Decisions

Given reminders are computed, When logging the schedule, Then each planned send entry records event_id, attendee_id, resolved_timezone (IANA), source, confidence, dst_applied (boolean), intended_send_time, quiet_hours_window, final_send_time, shift_reason (if any), applied_policies (workspace/team/event/override IDs), and decision_timestamp (ISO 8601). Given an organizer reviews logs for an event, When filtering by attendee or date range, Then only matching log entries are returned and can be exported as CSV. Given access controls are enforced, When a non-authorized user requests audit logs, Then access is denied and the attempt is logged with reason=forbidden.

Fallback Behavior When Timezone Unknown

Given no timezone can be resolved from user settings, calendar metadata, invite headers, locale, or IP, When scheduling reminders, Then the system either prompts the organizer to confirm a timezone for the attendee or defaults to the organizer’s policy/timezone as configured. Given fallback to organizer’s policy/timezone is applied, When computing reminders, Then quiet hours and offsets are applied using that timezone and the decision is logged with fallback=true and fallback_source=OrganizerPolicy. Given the organizer later sets a definitive attendee timezone, When the change is saved, Then all future planned sends are recalculated to the attendee’s local time and prior fallback entries remain in the audit log.

Privacy Compliance & Notification Preference Respect

Given an attendee has opted out of reminders or disabled a notification channel, When scheduling sends, Then no reminders are sent to that attendee/channel and the suppression is logged with reason=opt_out. Given regional privacy constraints (e.g., GDPR), When deriving timezone from IP/locale, Then raw IP data is not persisted beyond derivation; only the resolved timezone and source=IP are stored, and data processing is recorded for audit. Given per-attendee overrides require consent, When an override is enabled without recorded consent, Then the system blocks the change and surfaces an error requiring consent capture. Given role-based access controls, When viewing timezone, preferences, or audit data, Then only authorized roles can access it, and access events are logged.

Multi‑Stage Reminder Orchestration (24h/1h/10m)

"As an organizer, I want a reliable sequence of reminders at 24h, 1h, and 10m so that invitees are prepared and on time."

Description

Provide a rules‑driven scheduler that attaches to each event and generates reminder jobs at 24h, 1h, and 10m relative to each attendee’s local start time. Support enabling/disabling stages per event, plus custom offsets when allowed by policy. Ensure idempotency (no duplicate sends) and automatic cancellation of pending reminders when the meeting is cancelled or after the attendee joins. Handle reschedules by recalculating offsets and migrating queued jobs. Allow conditional logic (e.g., skip 24h if invite sent <24h prior; suppress 10m if the attendee has joined the waiting room). Include retry/backoff for transient delivery errors and a kill‑switch to halt all reminders for an event. Expose orchestration state to the UI with per‑attendee status and next scheduled send.

Acceptance Criteria

Local-Time Scheduling with Stage Toggles and Custom Offsets

Given an event with attendees each having a known time zone When orchestration initializes for the event Then reminder jobs are queued at T-24h, T-1h, and T-10m in each attendee’s local time, honoring DST boundaries Given one or more reminder stages are disabled at the event level When orchestration queues jobs Then only enabled stages are queued per attendee and disabled stages are not scheduled Given custom offsets are configured and allowed by policy When orchestration runs Then jobs are queued at the configured offsets for each attendee instead of the defaults

Idempotent Delivery and Job Deduplication

Given the same reminder stage is triggered multiple times due to retries or duplicate events When the system attempts to send the reminder Then exactly one reminder per attendee per stage is delivered and duplicates are suppressed using a stable idempotency key Given duplicate scheduled jobs exist for the same attendee and stage When execution occurs Then the duplicates are detected and only a single job is processed

Cancellation and Kill-Switch Suppression

Given an event is canceled When the cancellation signal is received Then all pending reminder jobs for the event are canceled within 30 seconds and no further reminders are sent Given the event-level kill-switch is activated When scheduling or sending a reminder Then all pending and future reminders for that event are halted and no messages are delivered Given an attendee joins the meeting prior to pending reminder stages When join is detected Then all future reminder stages for that attendee are canceled

Reschedule Recalculation and Job Migration

Given an event start time is changed When the reschedule is saved Then queued jobs are recalculated relative to the new start time for each attendee and migrated without duplicate sends Given a reminder stage has already been sent before the reschedule When recalculation runs Then already-sent stages are not re-sent and only remaining stages are scheduled Given the reschedule causes a change in local DST or time zone offset for an attendee When jobs are recalculated Then new job times reflect correct local offsets at T-24h, T-1h, and T-10m

Conditional Skips: Late Invites and Waiting Room Presence

Given the initial invite is sent less than 24 hours before the event start When determining which stages to schedule Then the 24h reminder is not queued for that attendee Given an attendee is detected in the waiting room within 15 minutes of the start time When the 10m reminder would be sent Then the 10m reminder is suppressed for that attendee

Retry and Backoff Handling for Transient Failures

Given a transient delivery error occurs (e.g., 429, 5xx, or network timeout) When sending a reminder Then the system retries using exponential backoff with jitter up to the configured maximum attempts Given a non-retryable error occurs (e.g., invalid recipient or policy rejection) When sending Then no retries are attempted and the attempt is marked failed with a diagnostic reason Given the maximum retry attempts are exhausted without success When the retry policy completes Then the send is marked failed and no further attempts are scheduled

UI Exposure of Orchestration State Per Attendee

Given an event with orchestrated reminders When viewing the event in the UI Then each attendee shows current stage statuses (Pending, Sent, Skipped, Failed) and the next scheduled send timestamp, and whether the event kill-switch is active Given an orchestration state change occurs (send success/failure, cancel, reschedule, attendee join) When the change is processed Then the UI reflects the update within 60 seconds

Smart Channel Selection & Fallback Delivery

"As an invitee, I want reminders delivered on the channel I actually see so that I don’t miss the meeting."

Description

Deliver nudges over the most effective channel per attendee (email, SMS, Slack, or mobile push when available) based on known reachability, user preferences, and past engagement. Implement a channel ranking model with rules/weights (e.g., use SMS only for final 10m nudge if consented; prefer Slack for internal attendees). Validate contactability (phone verified, Slack DM permitted, push token active) before scheduling. On send failures or low‑confidence channels, automatically fall back to the next best channel within the same nudge window. Enforce rate limits and frequency caps to prevent notification fatigue. Provide opt‑in/opt‑out management, sender identity configuration, and compliance with carrier and messaging regulations. Expose delivery outcome telemetry for each channel to inform future selection.

Acceptance Criteria

Internal Attendee: Slack-First Delivery with Contactability Validation

Given the attendee is marked as internal to the organization And Slack direct messages are permitted for the attendee And the attendee has not opted out of Slack And Slack contactability check passes (permission=true, last DM receipt < 14 days) And channel ranking rules for internal attendees are Slack > Push > Email, with SMS disallowed except for 10m nudges When a 1-hour-before nudge is scheduled for this attendee Then Slack is selected as the primary delivery channel for this nudge And SMS is marked ineligible for this nudge And the system records channel eligibility and selection reasons in telemetry

SMS Only Eligible for Final 10-Minute Nudge with Explicit Consent

Given a nudge is scheduled 24 hours before the meeting Or a nudge is scheduled 1 hour before the meeting Then SMS is marked ineligible regardless of phone status or consent Given a nudge is scheduled 10 minutes before the meeting And the attendee’s phone number is verified And the attendee has explicitly opted in to SMS And per-channel frequency caps are not exceeded And sending is permitted for the attendee’s locale and carrier Then SMS is marked eligible for selection for this nudge And if SMS is not selected, the reason is logged (e.g., ranking, preference)

Automatic Fallback on Primary Channel Failure Within Nudge Window

Given a nudge has a selected primary channel and at least one eligible fallback channel And the primary channel send attempt fails (non-2xx provider response or no delivery acknowledgment within 60 seconds) When the failure is detected Then the system initiates delivery via the next-highest ranked eligible channel within 60 seconds And ensures only one successful delivery is recorded for the nudge (idempotency) And records the fallback attempt, timing, and final outcome in telemetry

Low-Confidence Channel Handling and Backup Scheduling

Given the channel ranking model returns a predicted engagement probability below 0.35 for the top-ranked eligible channel When scheduling the nudge Then the system selects the highest-ranked eligible channel with predicted engagement ≥ 0.35 And if no eligible channel meets the threshold, the system schedules a backup fallback attempt to the next-best eligible channel 60 seconds after the primary if no open/click/read/delivered event is observed And the selection rationale "low_confidence" is recorded in telemetry

Sender Identity Configuration and Regulatory Compliance Enforcement

Given organization-level sender identities are configured (email From name/domain, SMS brand/campaign or sender ID, Slack bot app, push app credentials) And per-channel compliance requirements are active (e.g., email DMARC alignment, SMS opt-in and STOP/HELP copy, Slack DM permission, push token validity) When a nudge is sent on any channel Then the message uses the configured sender identity for that channel And any channel failing configuration or compliance checks is marked ineligible and not used for delivery And the compliance status and any rejection reasons are logged in telemetry

Rate Limits and Frequency Caps Across Channels

Given default caps are configured as: max 3 nudges per attendee per event, minimum 30 minutes between nudges, and max 1 SMS per attendee per event When scheduling a nudge that would exceed any cap Then the nudge is not sent And the system records a suppressed event with reason "rate_limited" including the violated cap And no fallback attempts are triggered for suppressed nudges

Delivery Outcome Telemetry Exposed and Feeds Channel Ranking

Given delivery attempts occur for a nudge across one or more channels When telemetry is generated Then for each attempt the system records: attendee_id, meeting_id, nudge_type (24h/1h/10m), channel, eligibility flags, selection reason, send_timestamp, delivery_status, provider error_code (if any), engagement event (open/click/read), fallback_used, final_outcome, and latency_ms And the telemetry is available via API and admin console within 60 seconds of the attempt And a daily job updates per-attendee per-channel engagement scores using the last 30 days of telemetry And subsequent nudges for that attendee use the updated scores in channel ranking and record the version of the scoring data used

One‑Tap Join with Backup Dial‑In

"As an invitee, I want a single join button and a dial‑in fallback so that I can get into the meeting quickly from any device."

Description

Embed a context‑aware “Join Now” action in every nudge that deep‑links directly to the meeting provider (Zoom, Google Meet, Teams, etc.) using the canonical URL from the calendar event. Detect device and client capabilities to choose the best target (native app vs. browser) and gracefully degrade to web if the app is unavailable. Include localized backup dial‑in details (country‑specific access numbers, PIN/meeting ID) and a single‑tap dial string on mobile. Provide copy‑to‑clipboard actions and fail‑safe text formatting to avoid link corruption by email or SMS clients. Support authenticated join when possible and warn on potential phishing risks by displaying verified meeting metadata (host, title, start time).

Acceptance Criteria

Context-Aware One‑Tap Join Target Selection

- Given a device with a provider’s native app installed and enabled When the user taps "Join Now" Then the native app opens directly to the meeting within 2 seconds of tap - Given a device without the provider’s native app or with deep links unsupported When the user taps "Join Now" Then the meeting opens in the default browser using the provider’s web join URL - Given app detection takes longer than 1500 ms or fails When the user taps "Join Now" Then the system automatically falls back to the browser URL and logs a fallback event - Given desktop and mobile form factors When capability detection runs Then the selected target (app vs. web) is recorded in analytics with device type and provider

Canonical Deep Link Resolution Across Providers

- Given a calendar event with structured conferencing metadata (Zoom/Meet/Teams) When "Join Now" is tapped Then the opened URL exactly matches the canonical URL from the event’s conferencing field - Given multiple URLs exist in the event body When rendering the nudge Then the system prioritizes the structured canonical URL over free‑text links - Given a recurring meeting with occurrence‑specific links When "Join Now" is tapped for a specific instance Then the link resolves to that instance’s canonical URL - Given the event lacks a valid canonical URL When "Join Now" is tapped Then a non‑blocking error message is shown and backup dial‑in is elevated as the primary action

Localized Backup Dial‑In With Single‑Tap String

- Given the guest’s country can be inferred from locale, time zone, or phone When the nudge is generated Then the country‑specific access number is selected and displayed with country label - Given the device is mobile When the dial option is presented Then a single‑tap tel link is constructed with required pauses and separators for the provider (e.g., tel:+1XXXXXXXXXX,,<MeetingID>#,,<PIN>#) and successfully reaches the IVR join flow in smoke tests - Given no local access number exists for the guest’s country When the nudge is generated Then the nearest regional number is used and a short note indicates the region - Given the user taps "Copy Dial‑In" When copied to clipboard Then the number, meeting ID, and PIN are included with locale‑appropriate formatting and without line breaks that break dialing - Given the nudge is sent via email or SMS When rendered Then comma pauses and hash characters in the dial string are preserved and remain tappable/clickable

Authenticated Join and Phishing‑Safe Metadata Display

- Given the provider supports authenticated/SSO join and the user has an active session When the user taps "Join Now" Then an authenticated join URL is used and the provider indicates an authenticated session without prompting for credentials - Given verified meeting metadata (host, title, start time) from the calendar event When the nudge is displayed Then these fields are shown above the button and match the event values exactly - Given the join URL domain is not in the allowlist of recognized providers When rendering the nudge Then a phishing warning banner is displayed and a confirm step is required before opening the link - Given screen readers are used When focusing on the metadata and button Then accessible labels announce host, title, start time, and provider name

Fail‑Safe Link and Dial Formatting Across Channels

- Given major email clients (Gmail, Outlook, Apple Mail) and SMS clients (iMessage, Android Messages) When the nudge is received Then the "Join Now" button remains clickable and the URL is not truncated or altered by smart quotes or auto‑linking - Given long provider URLs with query parameters When embedded Then they are wrapped only at safe breakpoints without inserting spaces or zero‑width characters into the URL - Given tracking/redirect requirements When enabled Then only a trusted timemeld.io redirect is used and it preserves the full canonical URL and parameters, with the final destination restricted to an allowlisted provider domain

One‑Tap Copy to Clipboard for Link and Dial‑In

- Given the nudge displays copy actions When the user taps "Copy Join Link" Then the canonical join URL is placed on the clipboard exactly as used by the button and a confirmation toast appears within 1 second - Given the user taps "Copy Dial‑In" When copied Then the clipboard contains the access number, meeting ID, and PIN on a single line suitable for pasting into dialers - Given the clipboard write fails due to permissions When the user taps a copy action Then a fallback modal shows the content with a manual "Select All" affordance

Graceful Degradation and Error Recovery

- Given app launch is attempted and fails to foreground within 3 seconds When "Join Now" was tapped Then the system automatically opens the browser URL and surfaces a brief "Opened in browser" notice - Given both app and browser open are blocked (e.g., corporate policy) When "Join Now" is tapped Then a modal displays the raw URL and dial‑in details with copy actions so the user can join manually - Given any failure path is taken When the nudge flow completes Then an error event with device, provider, and failure reason is logged for diagnostics

Personalized & Localized Nudge Content

"As an invitee, I want reminders in my language and local time format so that details are clear and actionable."

Description

Generate concise, human‑friendly reminder content that includes attendee name, organizer, agenda snippet, and the attendee’s local start time in their preferred format (12/24‑hour). Provide full i18n support with automatic language selection from user preferences or locale, and allow organizers to override per event. Maintain brand‑consistent templates with variable placeholders and conditional sections (e.g., show dial‑in only where available). Support A/B variants for subject lines and copy, with preview across channels and languages. Append minimally invasive tracking for opens/clicks where permitted. Ensure accessibility (readable text length, contrast, alt text) and deliver channel‑optimized payloads (SMS length limits, Slack blocks, email HTML/text).

Acceptance Criteria

Auto language selection with per-event override

Given an attendee has a saved language preference, When a nudge is generated, Then the subject and body are localized to that language. Given no saved preference, When locale is detected from the attendee profile or invite address, Then the subject and body are localized to that locale’s language. Given the organizer sets a per-event language override, When the nudge is generated, Then the override language is used regardless of attendee preference. Given an unsupported language is selected, When the nudge is generated, Then content falls back to English and the fallback is logged. Then all system labels, dates, and connectors use the same language within the message.

Local time display in attendee’s preferred 12/24‑hour format

Given an attendee’s timezone and hour-format preference are known, When rendering the nudge, Then the start time is displayed in the attendee’s local timezone and preferred 12/24-hour format. Then the local date and day-of-week are included where channel length allows, and the time includes the correct DST adjustment for the event date. Then no UTC or organizer time is shown unless explicitly configured, and no ambiguous times are displayed. Then numeric formatting (AM/PM vs 24h) matches the attendee’s preference across subject and body.

Template rendering with placeholders and conditional sections

Given a brand-consistent template with placeholders {attendee_name}, {organizer_name}, {agenda_snippet}, {local_start_time}, {join_url}, {dial_in}, When rendering, Then all placeholders are resolved with event data and no literal placeholders appear. Then the “Join Now” CTA is present and links to {join_url} in all channels that support buttons/links. Then the dial-in section is included only when {dial_in} is available; otherwise it is omitted with no empty headers or extra spacing. Then messages render without HTML/CSS errors (email) and without JSON/schema errors (Slack blocks).

A/B variants for subject lines and copy

Given variants A and B are configured for subject and/or body, When sending to N eligible recipients, Then recipients are allocated A/B in a 50/50 split with a tolerance of ±5%. Then each sent message records the variant identifier in metadata for analytics. Then both variants include the required fields (attendee name, organizer, agenda snippet, local start time, “Join Now” link) and share the same language and time formatting rules. Given variant B is disabled or incomplete, When sending, Then all recipients receive variant A.

Cross-channel, multi-language preview

Given an organizer selects a language and channel in the preview, When preview is generated, Then it renders exactly the text/blocks/HTML that will be sent for that combination, with sample data resolving all placeholders. Then SMS preview displays the estimated segment count for GSM-7 vs UCS-2 and warns if limits will be exceeded. Then Slack preview validates Block Kit against API limits and shows any truncation. Then Email preview provides both HTML and plain-text views and reports missing alt text, if any.

Consent‑aware open/click tracking

Given workspace and recipient tracking permissions are known, When generating the message, Then open tracking is added only to email and only if permitted; click tracking is added as wrapped links only if permitted. Then no tracking parameters or pixels are added when permission is not granted or region policy forbids it, and the send is not blocked. Then tracked links use the branded redirect domain and preserve UTM parameters. Then send, open, and click events are recorded with message ID and variant ID when tracking is active.

Accessibility and channel‑optimized payloads

Email: Then HTML meets WCAG 2.1 AA color contrast; base font size is at least 16px; images include alt text; and the “Join Now” link has an accessible name. SMS: Then the message fits within 2 segments for GSM-7 (≤306 chars) or 2 segments for UCS-2 (≤134 chars); if longer, the body is truncated with an ellipsis and a fallback URL to full details. Slack: Then the message uses Block Kit with ≤50 blocks and ≤3000 characters per text block; includes a primary “Join Now” button; and includes a plain-text fallback section.

Attendance Signals & Nudge Suppression

"As an organizer, I want insight into which nudges were seen and to suppress further reminders after joining so that we avoid noise and learn what works."

Description

Capture and correlate engagement signals (open, click, join, decline) from all channels and meeting providers to infer attendance state in near‑real time. When an attendee has joined or explicitly declined, automatically suppress remaining reminders for that attendee while leaving others unaffected. Feed aggregated metrics (send, delivery, engagement, attendance rate, no‑show rate) back into TimeMeld’s analytics and scheduling heuristics. Provide organizer‑visible dashboards and per‑event reports. Offer webhook/exports for downstream systems. Implement strict privacy controls, retention policies, and deduplication to avoid double‑counting across channels/devices.

Acceptance Criteria

Suppress reminders upon join event

- Given an attendee is on the invite for a scheduled event with Smart Nudges enabled - When a join signal is received from any supported meeting provider or a Join Now click results in a confirmed session start - Then suppress all remaining reminders for that attendee for that event within 5 seconds p95 and 15 seconds p99 - And do not modify other attendees’ reminder schedules - And record a suppression audit entry with event_id, attendee_id, provider/channel, timestamp, reason="joined", dedupe_key - And reflect the attendee state as "Joined" on organizer dashboards within 15 seconds p95 - And process repeated join signals idempotently (no duplicate suppressions or counts)

Suppress reminders upon explicit decline

- Given an attendee explicitly declines via any channel (email decline link, SMS reply keyword, or calendar RSVP = Declined) - When the decline signal is ingested and verified - Then suppress all remaining reminders for that attendee for that event within 5 seconds p95 - And mark the attendee state as "Declined" on dashboards and reports - And exclude the attendee from no-show rate calculations while including in invitee counts - And emit a suppression_applied event with reason="declined"

Cross-channel deduplication of engagement and attendance signals

- Given multiple engagement signals for the same attendee, event, and nudge instance across channels/devices - When deduplication is applied using idempotency keys (event_id + attendee_id + nudge_id + action_type) - Then count at most one of each action_type per nudge instance per attendee in analytics - And treat parallel "Join Now" link success and dial-in bridge connect within 2 minutes as a single attendance - And process webhook retries idempotently using the same keys - And keep false-duplicate rate under 0.1% over 10k events in validation tests

Organizer dashboards and per-event reports show real-time metrics

- Given an organizer opens the per-event report or dashboard - When the page loads or auto-refreshes every 15 seconds - Then display metrics: sends, deliveries, bounces, opens, clicks, joins, declines, attendance rate, no-show rate - And allow filtering by channel, role (organizer/guest), and timezone - And show per-attendee state (Pending, Joined, Declined, No-show) with last signal timestamp - And provide CSV export that matches on-screen totals within 0.5% variance - And reflect new signals within 15 seconds p95 of ingestion

Reliable webhooks and exports for downstream systems

- Given a tenant configures a webhook endpoint with a shared secret - When events of types send, delivery, open, click, join, decline, suppression_applied, attendance_state_change occur - Then deliver JSON webhooks signed with HMAC-SHA256 within 60 seconds p95 and retry for up to 24 hours with exponential backoff on non-2xx responses - And include idempotency_key to enable consumer deduplication - And provide a replay endpoint to re-send events by time range and type - And support bulk exports via API/CSV for a date range with schema versioning and gzip compression

Privacy controls and data retention for signals

- Given tenant privacy settings and default system policies - When storing engagement and attendance events - Then store only minimal metadata (event_id, attendee_id hash, timestamps, channel, action_type, provider) and never store message body content - And encrypt data in transit (TLS 1.2+) and at rest (AES-256) - And enforce role-based access so only organizers and admins of the event’s tenant can view per-attendee states - And honor configured retention: raw events purged after 30 days by default (configurable 7–90), aggregated metrics retained 12 months, with deletion executed within 7 days of request - And provide per-attendee per-event purge that cascades to exports and webhook replays

Aggregated metrics power scheduling heuristics

- Given TimeMeld’s scheduling heuristics consume attendance aggregates - When daily rollups are generated at 01:30 UTC and updated incrementally in near real time - Then produce aggregates by timezone window, weekday, role, channel, and meeting type with definitions documented - And exclude declined attendees from no-show rates and include joined attendees regardless of join channel - And expose aggregates via an internal API with p95 query latency under 300 ms and availability 99.9% monthly - And version metric schemas to allow backward-compatible evolution

Join Precheck

A quick pre‑join diagnostic that tests mic/camera/network and preloads the conferencing token so guests enter cleanly. Offers a fallback join path if something fails, minimizing awkward “can you hear me?” starts.

Requirements

Device Diagnostics & Permissions

"As a remote participant, I want to confirm my mic, speakers, and camera work and have the right permissions so that I can join without audio/video issues."

Description

Implement a pre-join hardware check that verifies microphone input (with visual level meter and loopback playback), speaker output (test tone), and camera preview, including device enumeration and selection. Handle browser permission prompts gracefully, detect blocked devices, and provide clear remediation steps (e.g., enable permissions, select a different device). Persist last-known device choices per user/browser while supporting one-click re-test. Gate the “Join” action behind at least one valid audio path or provide a warned bypass. Ensure cross-browser support (Chromium, Firefox, Safari), timeouts for hung device calls, and robust error messaging integrated into TimeMeld’s pre-join flow.

Acceptance Criteria

Mic Input Check with Level Meter and Loopback

Given the user is on the Join Precheck screen When they click "Test Microphone" Then getUserMedia({ audio: true }) is invoked within 300ms and any browser permission prompt is surfaced Given microphone permission is granted When the mic stream starts Then a level meter renders and updates at ≥10 fps and shows non-zero level when the user speaks and near-zero when silent Given loopback is enabled When the user records a 3-second sample and stops Then playback begins within 1.5s through the selected output and completes without error Given no audio energy above threshold is detected for 5s after stream start When the user remains on the mic test step Then a warning appears with remediation steps and a visible "Retry" control Given the mic request hangs When getUserMedia does not resolve in 5s Then the request is aborted and a timeout error with retry is shown Given multiple microphones are available When the user selects a different microphone Then the input stream switches within 1s and the meter reflects the new source while the previous track is stopped

Speaker Output Test Tone and Device Selection

Given the user is on the Join Precheck screen When they click "Test Speaker" Then a 2-second test tone plays and the UI shows a playing state Given the browser supports setSinkId When the user selects a specific output device Then subsequent playback uses that device and the selection is reflected in the UI Given the browser does not support setSinkId When the user views output options Then the UI indicates output selection is not supported and uses the system default Given autoplay is blocked When the user clicks "Enable Sound" Then the test tone plays successfully Given playback fails (e.g., NotAllowedError, NotFoundError) When the test is triggered Then an error message with remediation and a "Retry" control is displayed

Camera Preview and Selection

Given the user is on the Join Precheck screen When they click "Enable Camera" Then getUserMedia({ video: true }) is invoked within 300ms and any browser permission prompt is surfaced Given camera permission is granted When the video stream starts Then a live preview renders at a minimum of 640x360 within 1.5s Given multiple cameras are available When the user selects a different camera Then the preview switches within 1s and prior video tracks are stopped Given permission is denied or the request hangs for 5s When camera enable is attempted Then a clear error or timeout message is shown with browser-specific remediation and a retry option

Device Enumeration and Persistence of Selections

Given device access is available When enumerateDevices is called on load and after permissions change Then the microphone, speaker, and camera dropdowns populate with accurate labels and update on devicechange events Given the user selects specific microphone, speaker, and camera When they revisit the pre-join screen in the same browser profile Then the last-known selections are restored from storage if still present; otherwise sensible defaults are applied Given a previously saved device is no longer available When the pre-join screen loads Then a notice is shown and the next available default device is selected Given the user chooses to clear saved selections When they click "Reset devices" Then persisted device preferences are removed and defaults are applied on next load

Permission Handling and Error Messaging (Chromium, Firefox, Safari)

Given the user has not previously granted permissions When a device test is initiated Then the app surfaces the native permission prompt and blocks further test results until a decision is made Given the user denies, dismisses, or has permanently blocked permissions When the app detects the state via Permissions API (where available) or getUserMedia errors Then the UI shows explicit state (Denied, Dismissed, Blocked), browser-specific remediation steps, and a "Try again" control Given a permissions-related error occurs When the error is handled Then an error code and context are logged for diagnostics without exposing sensitive data to the user

One-Click Re-Test All Devices

Given device selections are set When the user clicks "Re-test" Then microphone, speaker, and camera checks are re-run without page reload, preserving current selections Given the re-test is running When checks complete or time out Then each device shows a pass/fail/timeout status and the overall status summarizes results Given existing media tracks are active When re-test begins Then prior tracks are stopped/replaced cleanly to avoid resource leaks or echo

Join Gating with Warned Bypass

Given the user has not established a valid audio path When they attempt to press "Join" Then the "Join" button is disabled and a message indicates that at least one audio path (microphone activity detected in last 5s or successful speaker test) is required, with an option to "Join Anyway" Given the user chooses "Join Anyway" When they confirm the warning Then the join proceeds, the event is logged, and the conferencing token (if available) is preloaded to avoid delay Given at least one valid audio path is established When the checks pass Then the "Join" button becomes enabled within 300ms

Network Health Check & Grading

"As a participant on a variable network, I want a quick network check with clear guidance so that I know whether to join normally or switch to a lower-bandwidth option."

Description

Run a WebRTC preflight to assess connectivity and quality: ICE reachability to STUN/TURN, round-trip latency, jitter, packet loss, and sustained up/down throughput via small test streams. Compute a user-friendly grade (e.g., Excellent/Good/Fair/Poor) with recommendations (e.g., switch to audio-only, enable low-bandwidth mode, use PSTN). Detect corporate firewall/NAT constraints and suggest TURN or alternative transports. Display results in the pre-join UI, auto-select optimal media profile based on thresholds, and expose a quick “re-test” control. Integrate with TimeMeld’s meeting context to log results and inform fallback logic.

Acceptance Criteria

ICE Reachability & Corporate Firewall Detection

Given I am on the Join Precheck screen When I start the Network Health Check Then the system performs ICE gathering with STUN within 5 seconds and records success/failure And the system attempts TURN connectivity (UDP, then TCP, then TLS) within 10 seconds and records which transports are reachable And if no server-reflexive (srflx) candidate is obtained OR STUN is blocked, the system flags Restricted NAT/Firewall = true And if only relay candidates are available, the system displays "Relay-only connectivity" and recommends TURN/TLS or PSTN as alternatives And a summary shows STUN Reachable (Yes/No) and TURN Reachable (UDP/TCP/TLS) And the reachability phase completes in under 15 seconds on typical broadband networks

Quality Metrics Measurement & Grade Computation

Given the preflight is running When latency, jitter, and packet loss are sampled for at least 10 seconds using RTCP pings and test media frames Then the system computes average RTT (ms), jitter (ms), and packetLoss (%) And grade is assigned as the worst category across all metrics (including throughput classification): - Excellent: RTT < 50 AND jitter < 15 AND loss < 0.5 AND throughput not below HD classification - Good: no metric in Fair/Poor AND (50<=RTT<100 OR 15<=jitter<30 OR 0.5<=loss<1.5) - Fair: no metric in Poor AND (100<=RTT<200 OR 30<=jitter<50 OR 1.5<=loss<3) OR throughput classified SD - Poor: RTT >= 200 OR jitter >= 50 OR loss >= 3 OR throughput classified Audio-Only And the computed grade and numeric metrics are exposed to the UI and logging layers

Sustained Throughput Assessment

Given the preflight is running When the system streams controlled test media up and down for at least 8 seconds with congestion control enabled Then it reports sustained upstream and downstream throughput in Mbps to one decimal place And upstream capability is classified as: HD (>= 1.0), SD (>= 0.5 and < 1.0), Audio-Only (< 0.5) And downstream capability is classified as: HD (>= 1.5), SD (>= 0.8 and < 1.5), Audio-Only (< 0.8) And if the throughput test aborts due to network error, the throughput subscore is marked Poor and included in grading

Auto Media Profile Selection Before Join

Given network check metrics and grade are available When the system determines an optimal media profile Then if grade is Excellent or Good AND upstream >= 1.0 Mbps AND packetLoss < 1.5%, the default profile is Video High (720p enabled, HD simulcast on) And if grade is Fair OR (0.3 Mbps <= upstream < 1.0 Mbps), the default profile is Video Low (360p, low-bandwidth mode, HD off) And if grade is Poor OR upstream < 0.3 Mbps OR downstream < 0.3 Mbps, the default profile is Audio Only (camera off by default) And the user can override the suggested profile before joining; the preview updates within 500 ms to reflect changes And the selected profile is embedded in the join token/session parameters

Pre-Join UI Results & Recommendations

Given the network check completes When results are ready Then the UI displays within 1 second: overall grade label (Excellent/Good/Fair/Poor), RTT/jitter/loss values, up/down throughput, STUN/TURN status, and a plain-language recommendation And recommendations map as follows: Poor -> "Switch to audio-only and consider PSTN"; Fair -> "Enable low-bandwidth mode"; Restricted NAT/Firewall -> "Connecting via TURN/TLS" And the grade label uses distinct colors and icons with WCAG AA contrast, and each metric has an accessible name/description for screen readers And the UI provides a visible "Re-test" control

One-Click Re-Test Runs Full Preflight

Given I have completed an initial network check When I click Re-test Then the system re-runs ICE reachability, quality metrics, and throughput end-to-end And the Join button is disabled during the re-test and re-enabled upon completion And results, grade, recommendations, and suggested media profile update to reflect the latest measurements And the user can perform up to 3 re-tests within 2 minutes; beyond that, the control is temporarily disabled with a rate-limit message

Diagnostics Logging & Fallback Integration

Given a network check completes When results are finalized Then the system logs to the meeting context a record containing: meetingId, userId, timestamp, RTT ms, jitter ms, packetLoss %, up Mbps, down Mbps, STUN/TURN reachability, ICE candidate types (host/srflx/relay), restrictedNat flag, overall grade, selected profile, attempt number And the record is retrievable via the internal API for that meeting within 5 seconds of completion And if no ICE connectivity can be established to STUN or TURN and the grade is Poor, the UI flags fallbackNeeded and surfaces fallback join options (e.g., "Join with phone audio" or PSTN), while allowing retry And logging failures do not block join; the system retries logging in the background up to 3 times with exponential backoff

Conferencing Token Preload & Validation

"As a host, I want my conferencing token preloaded and validated so that everyone can enter the meeting instantly without authentication delays."

Description

Pre-fetch, validate, and securely cache the conferencing access token prior to join. Support SSO/OAuth flows, role-based capabilities (host/guest), and token refresh if expiry is near. Prefetch room metadata, ICE server lists, and warm DNS/TLS where possible to minimize join latency. Store tokens only in memory with strict TTLs and bind to meeting/user context to prevent reuse. Provide deterministic error handling and automatic retry/backoff on transient failures, falling back to on-demand token fetch if preload fails. Surface readiness state to the UI so users can join instantly when diagnostics pass.

Acceptance Criteria

SSO/OAuth Token Prefetch Success Path

Given a user opens Join Precheck for a scheduled meeting and has a valid SSO/OAuth session When preloading begins Then the system requests a conferencing access token using the active session without additional user interaction And validates token signature, issuer, audience, expiry, and required scopes/claims And completes token prefetch and validation within 1500 ms p95 And securely associates the token with the current userId and meetingId

In‑Memory Token Storage, TTL, and Context Binding

Given a preloaded token is obtained Then the token is stored only in volatile memory, never in localStorage, sessionStorage, cookies, or disk And the token TTL is set to min(server expiry minus 60 seconds skew, 10 minutes), after which it is discarded And the token is bound to meetingId and userId; any reuse in a different meetingId or userId context is rejected and triggers a fresh fetch And the token is cleared on Precheck exit, app reload, or explicit sign-out

Proactive Token Refresh When Expiry Is Near

Given a valid preloaded token that expires within 5 minutes When precheck is active Then the system proactively refreshes the token in the background using a refresh flow And performs at most one refresh attempt per precheck session And on successful refresh, the new token expires at least 10 minutes in the future And if refresh fails with a permanent error, state becomes FALLBACK and no further refresh attempts are made

Prefetch Room Metadata, ICE Servers, and Warm Network

Given precheck starts When preloading runs Then room metadata and participant role capabilities are fetched and cached And an ICE server list containing at least one TURN and one STUN server is retrieved and cached And DNS resolution and TLS preconnect to conferencing/SFU and TURN endpoints are initiated And 95% of preconnect handshakes succeed within 1000 ms And join path requires no additional network calls for room metadata or ICE on the READY path

Deterministic Errors, Retry with Backoff, and Fallback to On‑Demand Fetch

Given a transient fetch failure (HTTP 5xx, network timeout, DNS error) When preloading token or metadata Then retry up to 3 times with exponential backoff starting at 200 ms, multiplier 2, with 0–100 ms jitter, total wait <= 2000 ms And on success within retries, proceed to READY Given a permanent failure (401/403, invalid signature/claims) Then do not retry; set state FALLBACK and surface an error code in {TOKEN_INVALID, TOKEN_EXPIRED, PERMISSION_DENIED, NETWORK_TIMEOUT, SERVER_ERROR} And record telemetry with error code, attempt count, and duration And ensure on-demand fetch is invoked at join time if in FALLBACK

Readiness State Surfaced to UI and Instant Join

Given precheck runs Then UI state transitions through PRELOADING -> READY or FALLBACK within 2000 ms p95 And when READY, the Join button is enabled and labeled "Ready to join"; clicking Join initiates session without a token network call and reaches first media within 500 ms p95 (network permitting) And when FALLBACK, the Join button remains enabled; clicking Join triggers on-demand token fetch once and adds no more than 1000 ms p95 to join time compared to READY And UI exposes ARIA live status updates for state changes

Role-Based Capabilities Enforced via Token Claims

Given a preloaded token with role=host and matching meetingId When attempting host-only actions (start/record/mute-all) Then actions succeed and are authorized within 300 ms Given a preloaded token with role=guest When attempting the same host-only actions Then requests are rejected with PERMISSION_DENIED within 200 ms and no side effects occur And any token with mismatched meetingId or invalid signature is rejected with TOKEN_INVALID and triggers a fresh fetch if allowed

Adaptive Fallback Join Paths

"As a participant, I want a reliable fallback path if tests fail so that I can still join the meeting on time."

Description

Offer resilient alternatives when diagnostics fail or conditions are degraded: audio-only mode, low-bandwidth video (reduced resolution/frame rate), PSTN dial-in with PIN, and optional “call me” bridging where available. Provide browser-switch guidance and a magic-link email fallback for locked-down environments. Auto-suggest and preselect the best fallback based on device and network results, with a manual override and clear tradeoff copy. Ensure seamless transition from precheck to chosen fallback, preserving meeting identity and attendance tracking in TimeMeld. Log chosen fallback for analytics and postmortems.

Acceptance Criteria

Auto-Suggest and Preselect Best Fallback After Diagnostics

Given pre-join diagnostics complete with uplink < 250 kbps OR packet loss >= 15% OR CPU load >= 85%, When fallback options are presented, Then audio-only is auto-suggested and preselected. Given pre-join diagnostics complete with uplink between 250–600 kbps OR packet loss between 5–15% OR camera max capability < 720p, When fallback options are presented, Then low-bandwidth video (360p @ 15 fps) is auto-suggested and preselected. Given microphone access is denied OR no input devices are found, When fallback options are presented, Then call-me (if available) is auto-suggested and preselected; Else PSTN dial-in is preselected. Given WebRTC is unsupported OR getUserMedia is blocked by policy, When fallback options are presented, Then PSTN/call-me or magic-link email fallback is auto-suggested (preferring call-me where available). Then the suggestion displays a one-sentence rationale referencing the failing metric(s) that triggered the choice. Then the preselected option can be confirmed with a single action; all manual options are visible without scrolling on a 1366x768 viewport.

Seamless Transition Preserving Meeting Identity and Attendance

Given the user confirms a fallback option from precheck, When join is initiated, Then the same meeting_id and participant_id are used and the host sees a single attendee entry. Then an attendance record is created/updated with fields: meeting_id, attendance_id, fallback_type, chosen_reason_code, joined_at, and session_id. Then no duplicate attendee records are created if the user switches fallback within 60 seconds; the existing record is updated in place. Then the conferencing token is reused or reissued seamlessly without additional authentication prompts. Then time-to-media (first audio frame) is <= 5 seconds at P50 and <= 10 seconds at P90 on a 300 ms RTT test network; otherwise a non-blocking retry banner is shown with an error code.

PSTN Dial-in and Call-Me Bridging

Given the user selects PSTN dial-in, When a PIN is generated, Then it is 6 digits, unique per meeting instance, and expires 2 hours after meeting end. Then at least one in-country dial-in number is displayed for the detected country (if available); otherwise the nearest regional number is shown. When the caller enters the PIN via IVR, Then they are admitted to the correct meeting lobby and prompted for a name if lobby naming is enabled. Given the user selects call-me, When a valid E.164 phone number is provided and consent is checked, Then the bridge rings the number within 10 seconds at P95 and two-way audio is established within 15 seconds at P95. If three consecutive call attempts fail OR 30 seconds elapse without answer, Then the UI surfaces PSTN dial-in with the same PIN as the next-step fallback. Then phone numbers are masked in UI/logs except for country code and last 2 digits; full numbers are never persisted. Then each call attempt logs call_sid, country_code, outcome, and duration for auditing.

Browser Switch Guidance and Magic-Link Email Fallback

Given the browser is unsupported (e.g., IE, Safari < 14.1, Chrome < 80) OR required media APIs are blocked by enterprise policy, When precheck completes, Then a guidance panel lists at least two supported browsers with minimum versions and an action to open in the recommended browser. Then a Send magic link control is visible; When the user confirms an email, Then a single-use link is delivered within 60 seconds at P95 and expires in 30 minutes. When the user follows the magic link, Then they join the same meeting with the same identity without re-entering PIN or password. If mail delivery fails (bounce or provider error), Then the UI offers copy-link and QR-code alternatives preserving meeting identity. Then the guidance panel includes a short rationale referencing the specific detected block (e.g., camera access blocked by policy).

Manual Override With Clear Tradeoff Copy

Given fallback options are presented, When details are expanded for any option, Then tradeoff copy is shown: Audio-only disables camera and reduces data by ≥90%; Low-bandwidth video sets 360p@15fps and reduces data by ≥60% vs 720p@30fps; PSTN disables screen-share receive. When the user selects any available option, Then the selection updates immediately and can be confirmed in a single action. If diagnostics improve by >30% for key metrics before confirmation, Then the auto-suggested option updates with a non-intrusive notice; the user's explicit manual choice remains selected unless they opt-in to the update. Then the component meets WCAG 2.1 AA for focus order, contrast, and screen-reader labels on all actionable elements. Then the last explicit user choice is remembered for the same device/browser for 24 hours unless diagnostics differ by >30%.

Analytics and Postmortem Logging for Fallbacks

Given any fallback is suggested, selected, changed, or results in a join outcome, When the action occurs, Then an analytics event is sent with: meeting_id, user_id_hash, attendance_id, fallback_type, suggestion_rank, chosen_reason_code, uplink_kbps, packet_loss_pct, rtt_ms, device_os, browser, call_region (if telephony), time_to_join_ms, and outcome. Then 99% of events persist within 5 seconds of the action with retries for up to 2 minutes using exponential backoff. Then events can be correlated to attendance_id and session_id for postmortems without creating duplicate attendees. Then for PSTN/call-me, only country_code and last2 digits of the phone number are included; full numbers are never persisted. Then a nightly job aggregates fallback_type distribution and success rate; QA can query raw events by meeting_id within 24 hours of occurrence.

Pre-Join UI & Guided Fixes

"As a user, I want a simple pre-join screen with actionable fixes so that I can resolve issues quickly and join confidently."

Description

Create a streamlined pre-join screen that presents real-time status of device checks, network grade, and token readiness with clear pass/fail indicators. Include device selectors, quick actions (retry, switch to audio-only, open system settings), and contextual troubleshooting cards for common issues. Support one-click re-test and a “Join anyway” option with warnings. Persist user preferences (e.g., preferred mic/camera) and integrate branding. Ensure accessibility (keyboard navigation, screen reader labels, sufficient contrast) and localization readiness for key languages used by remote-first teams.

Acceptance Criteria

Real-Time Pre-Join Diagnostics Display

Given a user opens the Pre-Join screen on a supported browser When automatic checks start Then mic, camera, network, and token readiness statuses render within 2 seconds with clear Pass/Fail/Degraded indicators and plain-language labels Given the network test completes When metrics are calculated Then a grade is shown using thresholds: A (RTT ≤ 100 ms, jitter ≤ 30 ms, packet loss < 1%), B (RTT ≤ 200 ms, jitter ≤ 50 ms, packet loss < 2.5%), C (RTT ≤ 400 ms, jitter ≤ 80 ms, packet loss < 5%), D (otherwise) with a tooltip explaining impact Given token preloading begins When the token is successfully retrieved Then a "Token ready" status appears within 1.5 seconds; otherwise a "Token not ready" status with a Retry action appears Given device permission changes occur (grant or deny) When the permission state changes Then the corresponding status updates within 1 second and includes an actionable message Given the Pre-Join view is loaded When UI elements render Then TimeMeld branding (logo and theme colors) is visible and matches the current style guide

Device Selection & Preference Persistence

Given multiple input/output devices are available When the user opens the mic/camera/speaker selectors Then all detected devices are listed with human-friendly names and the current selection is highlighted Given the user selects a different device When the selection is confirmed Then the preview/test uses the new device immediately and the selection is saved as the preferred device Given the user is authenticated When they return to the Pre-Join screen in a new session Then their preferred mic/camera/speaker are pre-selected from their profile; if a saved device is unavailable, the system falls back to the default device and shows a non-blocking notice Given the user is unauthenticated (guest) When they return within 30 days on the same browser Then the last selected devices are restored from local storage; if unavailable, fall back as above Given keyboard-only navigation When tabbing through selectors Then focus order is logical, selection is possible via Enter/Space, and the selector announces the current selection to assistive tech

Quick Actions for Fix & Fallback

Given any individual check has failed or is degraded When the user clicks Retry on that check Then only that check re-runs and updates its status within 2 seconds Given the camera check fails or the user opts to reduce bandwidth When "Switch to audio-only" is selected Then video preview is disabled, audio preview remains active, the join mode is set to audio-only, and status updates to "Ready (audio-only)" Given a permission-related failure is detected When the user clicks "Open system settings" Then the relevant browser/OS permissions page opens in a new tab/window and an in-app guide shows the steps to enable access Given any quick action is in progress When the user attempts to trigger it again Then the action control is temporarily disabled and a progress indicator is shown to prevent duplicate requests

Contextual Troubleshooting Cards

Given a failure cause is detected (e.g., "Mic access denied", "No input level", "High packet loss") When the Pre-Join UI renders troubleshooting Then a contextual card appears with a clear title, cause summary, 2–3 recommended steps, and a primary action relevant to the cause Given more than one issue exists When cards are displayed Then cards are ordered by severity and category (permissions first, device not found, quality issues) and are individually dismissible Given the user follows a recommended action from a card When the subsequent re-test passes Then the card auto-collapses, the related status shows Pass, and a success toast confirms the fix Given an error has a technical code When the card is expanded Then the code and a "Copy details" control are available for support escalation

One-Click Re-Test & 'Join Anyway' with Warnings

Given at least one check is in Fail or Degraded state When the user clicks "Re-test all" Then all checks re-run in parallel and render updated results with a timestamp within 3 seconds Given one or more checks remain in Fail or Degraded state after re-test When the user selects "Join anyway" Then a confirmation modal summarizes the specific risks (by failing checks) and requires explicit confirmation to proceed Given the user confirms "Join anyway" When the meeting join is initiated Then the conference opens within 2 seconds and the chosen mode (full or audio-only) is preserved Given all checks pass after re-test When the user proceeds Then "Join anyway" remains available but is visually de-emphasized compared to "Join"

Accessibility: Keyboard, Screen Reader, Contrast

Given the Pre-Join screen is used with a keyboard only When navigating all controls Then no keyboard traps exist, focus is always visible, and actionable elements are reachable in a logical order Given a screen reader is active When statuses change (Pass/Fail/Degraded, token ready) Then changes are announced via polite ARIA live regions with meaningful, non-visual labels Given the UI is audited When tested with Axe (or equivalent) on the Pre-Join screen Then there are 0 Critical and 0 Serious violations and it meets WCAG 2.1 AA for contrast (text ≥ 4.5:1, non-text ≥ 3:1) and non-color cues for status Given users require larger targets When interacting with key controls (Join, Re-test, Retry, selectors) Then hit areas are at least 44x44 px and have visible focus and hover states

Localization & Branding Readiness

Given the application locale is set to English, Spanish, French, German, Portuguese, or Japanese When the Pre-Join screen loads Then all visible strings are translated using externalized resources with no truncation, overlap, or clipped text at up to 120% text expansion Given pluralizable or variable strings are used (e.g., "x devices found") When rendered in each supported locale Then correct pluralization and number/date formats are applied per locale rules Given pseudo-localization is enabled When the Pre-Join screen is tested Then no hard-coded strings appear and layout remains usable without overflow Given brand theming is applied When switching locales or toggling system dark mode (if supported) Then TimeMeld branding (logo, colors) remains consistent and accessible, and does not reduce contrast below WCAG thresholds

Precheck Telemetry & Support Artifact

"As a support engineer, I want precheck metrics and a shareable diagnostic artifact so that I can troubleshoot join issues and improve overall reliability."

Description

Capture structured, privacy-aware telemetry from the precheck (device availability, permission outcomes, network metrics, token preload status, chosen fallback) and correlate with meeting/user IDs using pseudonymous identifiers. Respect consent and admin controls, minimize PII, and enforce a 30-day retention. Provide an exportable diagnostic bundle (hash-signed JSON) that users can share with support to accelerate root-cause analysis. Stream aggregate metrics to analytics for reliability tracking and to inform TimeMeld’s scheduling heuristics (e.g., flag recurring join issues by region).

Acceptance Criteria

Precheck Telemetry Capture Completeness

Given a user runs Join Precheck for a scheduled meeting When the precheck completes (success or failure) Then a telemetry record is created with fields: timestamp (UTC ISO-8601), precheckSessionId, pseudonymousMeetingId, pseudonymousUserId, device availability (mic/camera present/absent), permission outcomes (granted/denied/prompt), network metrics (RTT ms, jitter ms, packet loss %, up/down bandwidth Mbps), token preload status (success/failure with error code), chosen join path (primary/fallback with reason), client app version, OS, browser, region, ASN And the telemetry record is persisted within 2 seconds of precheck completion for 99% of sessions And no duplicate record exists for a single precheckSessionId (idempotent upsert)

Consent and Admin Controls Enforcement

Given workspace telemetry is enabled and the user has not provided consent When the user opens precheck Then a consent prompt is displayed before any telemetry is persisted When the user declines consent Then no telemetry is stored or streamed; only in-memory operational checks run; UI proceeds in reduced mode When the user grants consent Then consent is recorded against the pseudonymousUserId and is revocable; consent state persists for up to 12 months unless revoked Given the admin disables telemetry at the workspace level When any user runs precheck Then no telemetry is collected or streamed regardless of prior user consent and the UI indicates telemetry is disabled Then PII minimization rules are enforced for all flows: no raw emails, names, phone numbers, exact IP addresses, device serials, or full hostnames are stored; geo is stored as region + ASN only

Pseudonymous Correlation Without Re-identification

Given a workspace-scoped secret key and 90-day salt rotation When creating stored identifiers Then userId and meetingId are HMAC-SHA256 hashed and stored as 128-bit truncated hex digests; raw identifiers are never persisted And the same (user, meeting) pair hashes consistently within a salt window and changes after rotation And salts/keys are stored in a secure secrets manager and not exportable via application logs or bundles Then any query interface returns only hashed identifiers; attempts to ingest raw identifiers into storage are rejected at validation

30-Day Retention and Verified Deletion

Given telemetry and diagnostic bundle objects older than 30 days When the retention job runs hourly Then all qualifying records are hard-deleted from primary storage and aged-out from object storage via lifecycle rules And deletion audit logs record counts removed and any failures When querying by a known precheckSessionId older than 30 days Then zero records are returned And on deletion job failure, an alert is emitted within 5 minutes to on-call

Exportable Diagnostic Bundle (Hash-Signed JSON)

Given a completed precheck session When the user selects Export Diagnostic Bundle Then a JSON file is generated within 3 seconds containing: schemaVersion, createdAt, precheckSessionId, pseudonymousMeetingId, pseudonymousUserId, device availability, permission outcomes, network metrics, token preload status and errors, fallback choice and reason, client environment summary And the bundle size is ≤ 256 KB and contains no raw PII or exact IP address And the bundle is signed with Ed25519; offline verification with the published TimeMeld support public key succeeds; any modification causes verification to fail And copy-to-clipboard and download actions produce byte-identical content

Aggregate Metrics Streaming for Reliability and Heuristics

Given a telemetry record is created When emitting to the analytics pipeline Then aggregate metrics (precheck success rate, average/95th latency, jitter, packet loss, token preload success rate, fallback rate) are streamed within 60 seconds for 95% of events And events contain no user- or meeting-level identifiers; include only region, ASN, client environment, app version, and time bucket When regional fallback rate > 15% or token preload failure rate > 10% for a 15-minute window with N ≥ 50 sessions Then a region-issue flag is published to the reliability dashboard and made available to scheduling heuristics within 5 minutes

Fallback Join Path Telemetry and Outcome Correlation

Given precheck detects a blocking issue (e.g., permission denied, device missing, high packet loss, token preload failure) When the fallback path is presented and selected (or auto-selected for hard failures) Then telemetry captures fallbackReasonCode, selection timestamp, and subsequent join outcome (success/failure) with timestamp And the UI label for fallback reason matches the recorded reason code And correlation between precheck session and meeting join uses a pseudonymous joinAttemptId with < 0.1% orphaned prechecks over a rolling 7 days

Auto Block Sync

Continuously ingests personal focus blocks, PTO, travel, and team maker hours from connected calendars and org defaults. Handles recurring patterns, DST, and timezone moves automatically, so proposed meeting windows always reflect the latest protected time—no manual upkeep required.

Requirements

Multi-Calendar Ingestion & Normalization

"As a remote team member, I want TimeMeld to pull my protected time from all my calendars so that meeting proposals never land on my focus, PTO, or travel blocks."

Description

Connect to Google Workspace and Microsoft 365 calendars via OAuth with least-privilege scopes to continuously ingest events from personal, shared, and team calendars. Normalize busy-time into standardized categories (focus blocks, PTO, travel, maker hours) using event metadata, keywords, and admin-defined tags. Support read-only ingestion, ICS imports for non-managed calendars, and per-calendar opt-in. Map ingested blocks to TimeMeld’s protected-time model so scheduling proposals automatically exclude these windows across participants. Provide idempotent upserts, deduping of mirrored events, and resilient backfill for historical recurring series to ensure consistency after reconnects.

Acceptance Criteria

Least-Privilege OAuth Connections with Per-Calendar Opt-In

- Given a user connects Google Workspace or Microsoft 365 via OAuth, When the consent screen is shown, Then only read-only calendar scopes (list/read events) and basic profile are requested; no write or email/send scopes are requested. - Given the connection completes, When the integration is saved, Then the selected calendars default to opt-out and require explicit per-calendar opt-in before ingestion begins. - Given access is revoked at the provider, When webhooks or token refresh fail, Then the connection is marked revoked and ingestion stops within 10 minutes, and the user is notified.

Continuous Ingestion Latency and Timezone/DST Handling

- Given a connected, opted-in calendar, When an event is created, updated, or deleted, Then the change is reflected in TimeMeld’s protected-time model within 2 minutes (p95) and 5 minutes max. - Given a recurring series spans a DST transition or a user changes home timezone, When the provider updates are received, Then the protected-time occurrences align with the correct local times for each occurrence within 5 minutes. - Given the user relocates across timezones, When their primary timezone changes, Then future occurrences are recalculated to the new timezone without shifting past occurrences.

Busy-Time Normalization to Standard Categories

- Given an ingested event with provider metadata (e.g., out of office), admin-defined tags, or keywords (e.g., “PTO”, “travel”, “focus”), When normalization runs, Then the event is classified into focus, PTO, travel, or maker hours with a precedence of admin tag > provider metadata > keyword > default busy. - Given an event series with an override applied by an admin/user, When future occurrences are ingested, Then the override is applied idempotently to the series and exceptions. - Given maker hours are defined via org defaults or team calendars, When the workweek begins, Then daily maker-hour blocks materialize as read-only protected time visible in the model and UI.

ICS Import for Non-Managed Calendars

- Given a valid .ics file up to 10 MB is uploaded, When import runs, Then all events within the selected date range are imported as read-only and normalized using the same rules as live feeds. - Given the same .ics is re-imported, When import runs, Then upsert is idempotent: existing events are updated in place, no duplicates are created, and deleted events are not reintroduced. - Given malformed lines exist in the .ics, When import runs, Then the importer skips invalid entries, logs a count of skipped items, and completes import for valid items.

Idempotent Upserts and Deduping of Mirrored Events

- Given an event appears on multiple calendars (e.g., personal invite + shared/team calendar), When ingestion occurs, Then TimeMeld stores a single protected-time block by matching iCalUID/provider UID and start/end (±60s tolerance) and prefers the primary attendee’s instance as canonical. - Given reconnects or repeated backfills occur, When the same event is re-seen, Then upsert by provider etag/lastModified updates the existing record without creating duplicates. - Given an event is cancelled or replaced by an update, When ingestion runs, Then the protected-time block is removed or updated accordingly within 5 minutes.

Resilient Backfill After Outage/Reconnect

- Given access is restored after a provider outage or token refresh, When backfill starts, Then events are reconciled for the past 90 days and next 365 days, including recurring series and exceptions. - Given provider rate limits are encountered, When backfill runs, Then ingestion throttles with exponential backoff, persists progress checkpoints, and resumes without data loss. - Given partial failures occur, When retry completes, Then the final state matches the provider’s calendar and audit logs show a complete pass.

Scheduling Proposals Exclude Protected Time Across Participants

- Given multiple participants have connected calendars and opt-ins, When TimeMeld generates meeting windows, Then all protected-time blocks categorized as focus, PTO, travel, or maker hours are excluded from proposals. - Given a candidate slot overlaps any protected time by 1 minute or more, When proposals are generated, Then that slot is not proposed unless an explicit override is set by the organizer. - Given a protected-time block ends at time T, When proposals are generated, Then earliest proposal start is T + 5 minutes (configurable buffer).

Recurring & Exception Pattern Engine

"As a product manager, I want recurring and exception rules to be handled automatically so that I don’t have to fix proposals every time a series changes."

Description

Parse RRULE-based recurrences, EXDATE exceptions, and instance overrides to maintain an accurate, expanded set of protected-time intervals. Respect per-event semantics (e.g., modified single occurrences) and align recurrence expansion windows with scheduling horizons. Detect implicit routines (e.g., repeated ad-hoc focus blocks) and allow users to promote them to formal recurrences via suggested patterns. Ensure changes propagate instantly to TimeMeld’s window generator so proposed times remain valid without manual cleanup when series shift or exceptions are added.

Acceptance Criteria

RRULE Weekly Expansion within Horizon

Given an event E exists on a connected calendar with DTSTART 2025-10-01T09:00:00 America/Los_Angeles and RRULE:FREQ=WEEKLY;BYDAY=MO,WE And the system scheduling horizon is 30 days starting now When the Recurring & Exception Pattern Engine ingests and expands E Then it creates protected-time intervals only for E occurrences whose start is within [now, now+30d) And each occurrence is placed at 09:00 America/Los_Angeles on Mondays and Wednesdays And no protected interval for E exists outside the 30-day window And the number of created intervals equals the number of E occurrences in that window

EXDATE and Single-Instance Overrides

Given a recurring event R with DTSTART 2025-10-07T14:00:00 America/New_York and RRULE:FREQ=WEEKLY;BYDAY=TU And EXDATE includes 2025-10-14 And an overridden instance exists with RECURRENCE-ID 2025-10-21T14:00:00 America/New_York and a new start 2025-10-21T15:30:00 America/New_York and duration 60 minutes When the engine expands protected intervals for R within the scheduling horizon Then no protected interval exists on 2025-10-14 for R And a protected interval exists on 2025-10-21 starting 15:30 America/New_York for 60 minutes And all other Tuesday occurrences within the horizon start at 14:00 America/New_York with the base duration And if both EXDATE and an overridden instance exist for the same date, the overridden instance takes precedence and is included

DST Boundary Preservation

Given a recurring event D with DTSTART 2025-10-24T09:00:00 America/Los_Angeles and RRULE:FREQ=WEEKLY;BYDAY=FR that spans a DST change within the scheduling horizon When the engine expands protected intervals for D Then every Friday occurrence starts at 09:00 America/Los_Angeles local time before and after the DST transition And the UTC offset for each occurrence reflects the correct pre-/post-DST offset And no duplicate or skipped occurrences are produced due to the DST change

Timezone Move During Travel

Given the user's working timezone is set to Europe/Berlin for a travel period [T1, T2] And a daily recurring event T exists with DTSTART 2025-10-01T10:00:00 America/Los_Angeles and RRULE:FREQ=DAILY When the engine computes protected-time intervals and evaluates meeting-window conflicts during [T1, T2] Then T is preserved at 10:00 America/Los_Angeles wall time and converted to Europe/Berlin time for conflict detection and display And proposed meeting windows do not overlap the converted protected intervals within [T1, T2] And after T2, conversions revert to the user's original timezone without manual changes

Implicit Routine Detection and Promotion

Given at least 4 ad-hoc focus blocks (no RRULE) start between 09:00 and 09:15 local time on weekdays over the last 14 days with duration 90±10 minutes When the detected alignment of day/time meets or exceeds an 80% threshold Then the engine generates a Suggested Pattern with RRULE {FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0} and DURATION 90 within 60 seconds And the user receives a one-click "Promote to Recurrence" action referencing the suggestion When the user accepts the suggestion Then a formal recurrence is created starting at the next valid occurrence, future protected intervals derive from it, and duplicate overlaps with the original ad-hoc blocks are prevented When the user declines the suggestion Then no recurrence is created and the same pattern will not be suggested again for at least 7 days

Instant Propagation to Window Generator

Given existing proposed meeting windows have been generated for the current scheduling horizon When a change to protected time occurs via RRULE edit, EXDATE addition/removal, instance override, or promotion of a suggested pattern Then within 2 seconds the engine recomputes protected intervals and updates the window generator And any proposed windows that now conflict are withdrawn from the API/UI and replaced by conflict-free alternatives within the same horizon And the update is idempotent (repeating the same change does not create duplicate withdrawals or proposals) And the API emits a change event containing affected window IDs and a monotonic version number

DST & Timezone Drift Resolver

"As an engineer who travels, I want my protected time to follow me through timezone and DST changes so that proposals stay ergonomic wherever I am."

Description

Automatically reconcile protected-time across daylight saving transitions and user timezone changes, preserving event intent (local wall-clock vs absolute UTC) based on source calendar semantics. Detect travel or location-based timezone updates and rebase focus/maker hours so personal ergonomics are respected in the new locale. Harmonize offsets across participants so TimeMeld’s timezone-weighted proposals avoid newly inconvenient slots created by DST shifts or travel, without requiring user intervention.

Acceptance Criteria

DST Transition: Preserve Local-Intent Focus Blocks

- Given a recurring focus block Mon–Fri 09:00–12:00 created with local/wall-clock semantics and the user’s timezone transitions from UTC−5 to UTC−4 due to DST spring-forward, When the DST change occurs, Then the block instances on and after the transition date appear at 09:00–12:00 in the new local timezone with no one-hour drift. - Given a recurring focus block created with absolute UTC semantics, When DST changes, Then the local display time shifts by one hour consistent with UTC anchoring, and intent is preserved. - Then no duplicate or missing instances occur in the affected week (instance count matches expectation). - And all-day/date-only PTO entries remain date-aligned across the transition (start/end dates unchanged).

User Travel: Rebase Maker Hours to New Locale

- Given a user’s device timezone changes from America/Los_Angeles to Asia/Tokyo and a travel itinerary event indicates arrival at a specific date/time, When TimeMeld detects two corroborating signals (device TZ change persists ≥5 minutes and itinerary arrival time reached), Then the user’s maker hours (e.g., 10:00–16:00 local) are rebased to Asia/Tokyo starting at arrival plus ≤30 minutes, and prior instances in the origin timezone remain unchanged. - Then proposals generated after rebase avoid windows outside 10:00–16:00 Asia/Tokyo for that user. - And no retroactive edits are applied to protected-time in the past. - And an audit entry records old TZ, new TZ, effective time, and source signals.

Cross-Participant Harmonization After Staggered DST

- Given participants in US/Pacific and Europe/Berlin with maker hours configured in local time, When US DST begins while EU DST has not yet begun, Then TimeMeld recomputes timezone-weighted proposals so the top 3 candidate windows keep each participant within their maker hours (≤0 minutes outside). - And any previously saved but unsent proposal sets are refreshed automatically within 2 minutes of the DST change. - And windows that newly violate any participant’s protected time are removed from proposals.

Timezone Change Signal Debounce and Accuracy

- Given transient timezone flips (e.g., VPN causes device TZ to alternate for <5 minutes), When the signal does not persist beyond the debounce threshold (5 minutes) and no corroborating calendar/location signal exists, Then TimeMeld does not rebase protected time or proposals. - Given conflicting signals (device TZ says Europe/London, calendar travel indicates arrival tomorrow), When ambiguity exists, Then TimeMeld schedules rebase at the earlier of itinerary arrival or persistent device TZ ≥30 minutes and records pending status without prompting the user. - Then the false-positive rebase rate in automated tests is ≤0.5%.

Recurring Series Integrity Across DST and TZ Moves

- Given a weekly recurring focus series with local intent, When a DST change or timezone move occurs, Then TimeMeld creates series exceptions as needed to preserve wall-clock times without gaps or overlaps; total number of instances in a 90-day window equals expected count. - And no adjusted instance overlaps with existing meetings by more than 0 minutes due to the adjustment. - And ICS exports and connected calendars show the same start/end timestamps as TimeMeld for adjusted instances.

Propagation and Latency SLAs

- Given a detected DST change or confirmed timezone rebase event, When the change is applied, Then the user’s protected-time blocks are updated in TimeMeld within 60 seconds and propagated to connected calendars within 120 seconds. - And team proposal recomputation completes within 120 seconds, and the UI displays an updated status within 150 seconds. - And API webhook notifications (if enabled) are delivered with 99th percentile latency ≤180 seconds.

Real-time Sync & Conflict Resolution

"As a team lead, I want changes to my calendar to update TimeMeld within a minute so that newly blocked time is never suggested for meetings."

Description

Establish near-real-time updates using calendar watch channels/webhooks with exponential backoff and token renewal, falling back to smart polling when push is unavailable. Debounce rapid event churn, batch process deltas, and apply optimistic concurrency with versioning to avoid race conditions. Guarantee end-to-end propagation to proposal generation and invite updates within a target SLA (e.g., p95 < 60s). Provide atomic updates to the protected-time store to prevent transient overlaps and ensure TimeMeld never proposes within newly created blocks.

Acceptance Criteria

Push Sync with Intelligent Polling Fallback

Given a connected calendar supports push and a valid watch is active, when an event is created/updated/deleted, then a notification is received and processed and the protected-time store is updated and visible to proposal generation within SLA targets. Given push registration fails, is revoked, or the provider does not support push, when the condition is detected, then smart polling activates within 15s and uses incremental sync tokens to fetch changes without duplication. Given polling is active, when push becomes available again, then the system switches back to push within 60s with missed delta count = 0 (verified by incremental token continuity). Rule: After a daily full reconcile, drift between source calendars and protected-time store = 0 items.

Debounce and Batch Processing of Rapid Calendar Changes

Given ≥10 changes to the same calendar occur within 3s, when processing begins, then changes are coalesced into ≤2 batches and the final protected-time state matches the source state. Rule: Per-calendar debounce window = 1s; max coalescing delay = 5s; no individual change waits >5s to enter a batch. Rule: Batch processing preserves order per resource, and partial batch failures are retried without duplicating already-applied deltas. Rule: Under burst load (≥100 changes/min/calendar), throughput sustains ≥500 changes/min/node with no SLA breach for end-to-end propagation.

End-to-End Propagation SLA (p95 < 60s)

Given a change in a connected calendar that affects protected time, when the change is committed to the protected-time store, then updated proposed windows and any related invite updates are produced within p95 < 60s and p99 < 120s measured over ≥1000 events under nominal load. Rule: Measurement starts at provider event time (or receipt time if provider omits event time) and ends when proposal generation output reflects the change and invites (if any) are updated. Rule: SLA metrics are emitted (latency histogram, p95/p99, error rate) and an alert triggers if p95 ≥ 60s for 5 consecutive minutes. Rule: Dead-letter/poison message rate ≤ 0.1% with automatic retries and operator visibility.

Optimistic Concurrency with Versioned Protected-Time Store

Given two concurrent writers update the same protected-time record, when a stale version is submitted, then the write fails with 409 Conflict (or equivalent) and includes the current version for retry. Rule: Successful writes increment the version atomically and expose a strictly increasing version per record. Rule: Each write is atomic across all affected time slices; readers never observe partial updates, and no transient overlaps exist post-commit. Rule: Store enforces non-overlapping intervals per user/team policy; attempts to create overlaps are rejected or merged deterministically per specification. Rule: End-to-end tests simulate race conditions and verify zero lost updates and deterministic final state.

Watch Channel Auto-Renewal and Exponential Backoff

Given a push watch/channel has an expiry, when the remaining lifetime reaches 5 minutes, then the system renews the watch or re-registers successfully without losing the sync token. Given token refresh is required, when access tokens are near expiry or invalid, then tokens are refreshed proactively and re-registration uses fresh credentials. Given transient provider errors (429/5xx) occur, when retries are scheduled, then exponential backoff with full jitter is applied (initial 1s, cap 15m) and missed deltas are recovered via sync tokens. Rule: Channel outage recovery results in missed delta count = 0 (validated by incremental sync) and no duplicate side-effects. Rule: All renewals/backoffs are logged with correlation IDs and surfaced in operational dashboards.

Idempotent Delta Handling and Duplicate Suppression

Given duplicate or out-of-order webhook notifications for the same event/change, when processing occurs, then exactly-once application is achieved using event IDs and sequence/version checks, and no duplicate proposals/invites are produced. Rule: Reprocessing the same delta is safe and has no side effects (idempotent handlers for store updates, proposal regeneration, and invite updates). Rule: Deduplication window ≥ 24h with bounded memory usage; eviction does not result in missed or duplicated application (covered by source-of-truth reconciliation). Rule: Verification includes replay tests with shuffled and duplicated streams yielding identical final state and side-effect counts.

Org Defaults & Maker Hours Policy

"As an ops manager, I want org-wide maker hour policies applied automatically so that proposals respect both company standards and individual schedules."

Description

Allow admins to define organization and team-level defaults for maker hours, meeting-free days, company holidays, and blackout windows. Merge org policies with user-specific calendars using clear precedence rules and per-team overrides. Support role-based templates (e.g., support vs engineering) and location-aware policies to reflect regional holidays. Surface effective protected-time to users for transparency and feed directly into TimeMeld’s proposal engine to optimize for collective ergonomics while respecting individual preferences.

Acceptance Criteria

Admin Defines Org Defaults and Team Overrides

Given an authenticated Org Admin When they create and publish an Org Default policy with: - Maker hours: Mon–Thu 10:00–16:00 (local) - Meeting‑free day: Friday - Daily blackout: 12:00–13:00 - Holiday sets: Company + relevant regional calendars And they create and publish a Team Override for Engineering with: - Maker hours: Mon–Thu 09:00–17:00 - Meeting‑free day: none - Additional blackout: Wed 15:00–17:00 Then: - Both policies are persisted with unique policy_id and version numbers - Team Override is effective for all members of Team=Engineering - Effective Protected‑Time preview for a test Engineering user reflects team values overriding org in same categories and retains org settings for categories not overridden

Policy Precedence Merge: User Blocks, Team Overrides, Org Defaults

Given User U in Team=Engineering, Location=America/New_York And Org Defaults: Maker hours Mon–Thu 10:00–16:00; no blackout And Team Override: Maker hours Mon–Thu 09:00–17:00; no blackout And Org Blackout: Daily 16:30–18:00 And User Hard Block (PTO): Thu 13:00–15:00 (Busy=Out of office) When Effective Protected‑Time is computed for Thu 2025‑09‑18 Then: - Precedence order is applied: User Hard Blocks > Holidays (location‑aware) > Team Blackouts/Meeting‑free > Org Blackouts/Meeting‑free > Team Maker Hours > Org Maker Hours - Category overrides are replacement, not union, between team and org - Effective Protected‑Time intervals are 09:00–18:00 local (union of team maker hours 09:00–17:00 and org blackout 16:30–18:00), annotated to show PTO within 13:00–15:00 - Proposed meeting windows exclude any time that intersects [09:00, 18:00) - The Effective Protected‑Time calendar contains no overlaps and is represented at 1‑minute granularity

Role-Based Templates Applied With Team Overrides

Given role templates exist: - Engineering: Maker hours 10:00–16:00; Meeting‑free Fri - Support: Maker hours 08:00–11:00 and 13:00–16:00; Meeting‑free Wed And User S is assigned Role=Support and Team=Support And Team=Support has an override removing Meeting‑free Wed while leaving maker hours as defined by the template When Effective Protected‑Time is computed for Wed Then: - Support template maker hours are applied - Team override removes Meeting‑free Wed from the effective policy - Org defaults for the same categories do not apply - Changing User S Role to Engineering updates the effective policy on the next recompute, visible within 2 minutes

Location-Aware Regional Holidays and Travel

Given Org Holiday Sets include US and UK calendars And User A is located in US/Eastern on 2025‑11‑27 (US Thanksgiving) And User B is located in Europe/London on 2025‑11‑27 When Effective Protected‑Time is computed Then: - User A’s entire 2025‑11‑27 local day is a blackout (no proposals generated) - User B’s 2025‑11‑27 is not a blackout due to UK location And Given User B has a calendar travel event arriving in London on 2025‑12‑24 18:00 local When Effective Protected‑Time is computed for 2025‑12‑25 Then: - 2025‑12‑25 is a blackout for User B due to UK holiday - Location change is detected and applied no later than 15 minutes after the recorded arrival time

DST Stability of Local Maker Hours

Given maker hours are 09:00–17:00 anchored to the user’s local timezone America/Los_Angeles When Effective Protected‑Time is computed for: - 2025‑03‑07 (PST, UTC‑8) - 2025‑03‑10 (PDT, UTC‑7) Then: - Both days show 09:00–17:00 local as protected - UTC representation is 17:00–01:00+1 day for 2025‑03‑07 and 16:00–00:00+1 day for 2025‑03‑10 - No one‑hour gaps or duplications occur in the protected intervals across the DST transition

Transparency of Effective Protected-Time and Sources

Given a user opens the Protected Time panel When the effective schedule is displayed for the next 14 days Then: - Each protected interval shows its source category and origin (e.g., Team Override, Org Default, Role Template, Holiday, User PTO) - A “Why is this blocked?” explainer lists the precedence that produced the interval - The total protected hours per day and per source are shown - The exported ICS/JSON feed for Effective Protected‑Time exactly matches the UI rendering and the proposal engine’s inputs

Policy Change Propagation to Proposal Engine

Given an Org Admin publishes a change that adds a company‑wide blackout on Mon 11:30–13:30 When a participant search and proposal generation is requested for any set of org users Then: - Within 2 minutes of publish, /availability and proposal results exclude 11:30–13:30 on the next applicable Mondays for all affected users - API responses include the new policy ETag/version, and logs show cache invalidation at publish time

Privacy & Consent Controls

"As a privacy-conscious user, I want fine-grained control over what TimeMeld reads and stores so that my sensitive event details remain private."

Description

Provide granular consent for which calendars to sync and which fields to store; default to busy-only ingestion with optional title/description masking and hashing for deduplication. Display clear permission scopes during OAuth, allow per-calendar revoke, and implement data minimization with configurable retention. Maintain audit logs of sync activity and admin actions, and expose a user-facing privacy panel within TimeMeld to review synced sources. Ensure encryption at rest/in transit and isolate tenant data so Auto Block Sync protects user privacy while delivering accurate scheduling outcomes.

Acceptance Criteria

Per-Calendar Consent Selection During OAuth

Given a user with three calendars discovered from the provider And the user initiates Connect Calendars in TimeMeld When the TimeMeld OAuth pre-consent screen is displayed Then the screen lists each requested provider scope with a plain-language description And each discovered calendar is presented with an unchecked checkbox by default And the Authorize action is disabled until at least one calendar is selected When the user selects two calendars and completes OAuth Then only the selected calendars are added as active sources in Auto Block Sync And no data is ingested or stored from any unselected calendars

Default Busy-Only Ingestion

Given a newly added calendar source with no overrides When Auto Block Sync ingests events Then only availability state and time boundaries (start, end, timezone, recurrence meta) are stored And event titles, descriptions, attendees, locations, and attachments are not stored And proposed meeting windows use busy/free only with no content-field exposure And querying stored records returns null/empty for all content fields

Event Field Masking and Hash-Based Deduplication

Given org setting Store content fields = Off and Hash for deduplication = On And two calendars contain the same event title and description at the same time window When Auto Block Sync ingests those events Then title and description are stored as masked placeholders And a salted, non-reversible hash is stored for deduplication And only one busy block is created for the overlapping events And the hash value differs across tenants for the same input When Hash for deduplication = Off Then overlapping events are not deduped via hash while content fields remain masked

User Privacy Panel: Synced Sources Visibility and Controls

Given a user has connected multiple calendars When the user opens Settings > Privacy in TimeMeld Then the panel lists each source with provider, calendar name, scopes granted, masking/dedup status, retention policy, last sync timestamp, and next scheduled sync And each source row provides Revoke and View Audit Trail actions When the user clicks Revoke on a source and confirms Then the source status changes to Revoked and is removed from active sources And no further sync occurs for that source within 5 minutes And the revoked source appears in a Revoked section with revocation timestamp until its data is purged per retention policy

Configurable Data Retention and Minimization

Given an org admin sets retention to 30 days and field minimization to Minimum Required When the nightly retention job runs Then sync artifacts older than 30 days are permanently deleted And only start, end, timezone, availability state, recurrence meta, source id, tenant id, and hash (if enabled) remain for active records And an audit log entry is created with deletion counts and job id When the admin changes retention to 7 days Then the next job deletes items older than 7 days

Audit Logging for Sync and Admin Actions

Given audit logging is enabled by default When any of the following occurs: calendar added, scopes approved, source revoked, retention policy changed, sync run started/completed/failed Then an immutable audit entry is created with timestamp (UTC), actor, tenant id, action, target resource id, outcome, and metadata And org admins can filter logs by action and date range in the Privacy Panel And attempts to modify or delete an audit record via API return 403 and leave the record unchanged

Security Controls: Encryption and Tenant Isolation

Given data flows between providers, TimeMeld services, and storage When inspecting transport security Then TLS 1.2+ is enforced end-to-end with strong ciphers and HSTS on web endpoints When inspecting data at rest Then records are encrypted using KMS-managed keys (AES-256 or equivalent) And each record includes a tenant id and row-level security denies cross-tenant access When a user from Tenant A requests a resource belonging to Tenant B via direct URL or API Then the system returns 403/404 with no data leakage And a security audit entry is recorded for the denied access

Guarded Proposals

Treats focus blocks and maker hours as hard constraints in the scheduler. Proposals never land inside protected windows and are clearly labeled with protection badges, eliminating accidental erosion of deep work and the back‑and‑forth of "can we squeeze it in?" asks.

Requirements

Protected Window Ingestion & Normalization

"As an engineer, I want my focus blocks and maker hours automatically recognized so that proposed meetings never land during my deep work time."

Description

Continuously ingest protected time from connected calendars and user/team settings, normalize them into a unified "protection interval" model, and expose them to the scheduler as hard constraints. Sources include calendar events tagged as focus/deep work/do-not-schedule, user-defined maker hours, and org-level blackout policies. The system reconciles overlapping intervals, handles time zone conversions and recurrence rules, classifies source and sensitivity (user policy vs. org policy), and stores results in a low‑latency constraint service. This ensures Guarded Proposals always operate on accurate, up‑to‑date constraints while preserving privacy controls and auditability.

Acceptance Criteria

Calendar Tag Ingestion to Protection Intervals

Given a connected calendar event labeled with any of ["focus","deep work","do-not-schedule"] (case-insensitive, via tag or category), When the platform receives a webhook or polling delta for creation or update, Then a protection interval is created or updated with matching start/end (to the minute), hardConstraint=true, source="calendar", classification="user policy", within 30 seconds of change receipt. Given an all-day tagged event in timezone T, When ingested, Then a protection interval spans local 00:00–24:00 for each day of the event in T, stored in UTC with T recorded. Given a tagged event is deleted or untagged, When the change is received, Then the corresponding protection interval is removed within 30 seconds.

User Maker Hours Normalization

Given maker hours defined as weekly windows in a user's local timezone, When saved, Then recurring protection intervals are generated with RRULEs so that local wall-clock times remain constant across DST changes, and are stored with classification="user policy". Given a week crossing a DST transition, When queried, Then intervals reflect the correct local start/end each applicable day. Given maker hours are changed, When saved, Then future intervals are replaced and visible via the constraint service within 30 seconds; past intervals remain unchanged.

Org Blackout Policy Ingestion and Precedence

Given an org-level blackout policy (fixed window or RRULE), When activated, Then protection intervals are created with classification="org policy", sensitivity="high", hardConstraint=true. Given overlap between org policy and any user-level protection, When normalized, Then the resulting interval is the union with sensitivity resolved to "org policy" and proposal eligibility is false for the union span. Given the org policy is deactivated, When processed, Then affected intervals are removed within 60 seconds.

Overlapping Interval Reconciliation

Given two or more protection intervals that overlap or abut within the same scope (user or team), When normalized, Then they are merged into a minimal set of non-overlapping intervals with contiguous boundaries coalesced (e.g., [10:00–11:00] + [11:00–12:00] => [10:00–12:00]). Given the merged interval originates from multiple sources, When stored, Then metadata retains the set of contributing sources and the highest sensitivity across them. Given gaps exist between intervals, When normalized, Then no new intervals are introduced.

Recurrence and Exception Handling

Given a recurring tagged calendar series with RRULE and instance exceptions (EXDATE or modified single instance), When ingested, Then protection intervals are generated for occurrences excluding EXDATEs and reflecting per-instance edits. Given a series is updated (RRULE change) or an instance is edited/deleted, When the change is received, Then affected intervals are added/updated/removed accordingly within 60 seconds, without duplicating unaffected instances. Given a long-running RRULE, When stored, Then intervals are materialized only within the configurable planning horizon (e.g., next 12 weeks) and extended incrementally as the horizon advances.

Low-Latency Constraint Service and Freshness

Given a request for constraints for a team and time window with up to 10k intervals in scope, When queried under nominal load (100 QPS per org), Then the service responds in ≤50 ms p95 and ≤200 ms p99 with complete intervals. Given a source change (create/update/delete) is received, When queried after propagation, Then the updated intervals are visible via the service within 60 seconds end-to-end. Given a scheduler proposal is evaluated, When its time overlaps any hard constraint interval, Then the service flags it as ineligible with a reason including source classifications.

Privacy-Preserving Storage and Auditability

Given any ingested calendar event, When normalized, Then only interval bounds, timezone, source type, classification, sensitivity, and opaque event identifiers are stored; titles, descriptions, attendees, and locations are not stored or are irreversibly redacted. Given an authorized auditor requests an audit log for a user and time window, When retrieved, Then logs include trace ID, operation (create/update/delete), source, timestamps, before/after interval bounds, and actor/process, with retention ≥180 days. Given an unauthorized actor queries constraints or audit logs outside their scope, When access is attempted, Then the request is denied and the attempt is logged.

Maker Hours Configuration UI

"As a product manager, I want to configure and preview my maker hours so that the scheduler reliably respects my recurring deep work patterns."

Description

Provide a self-serve configuration interface for users and teams to define recurring maker hours (by weekday/time, time zone, and duration), add exceptions and temporary pauses, and import from existing calendars or templates. Include validation to prevent overlaps with working-hour rules, a heatmap preview of protected coverage across the week, and one-click application of team templates. Persist preferences to user profiles and allow admins to apply org-wide defaults while respecting individual overrides within policy bounds.

Acceptance Criteria

Create Recurring Maker Hours Block

Given I have edit permission and open the Maker Hours configuration UI When I add a recurring block specifying weekday(s), start time, duration, and a time zone Then the block is saved and appears in the list with times normalized to the chosen time zone Given I create a block that spans past midnight When I save it Then the UI clearly represents the cross-day span and the block is persisted without truncation Given I attempt to create a duplicate block (same weekday, start, duration, and time zone) When I save Then the system prevents duplication and displays a non-blocking notice

Validate Non-Overlap With Working-Hour Rules

Given organization or user working-hour rules exist When I attempt to save maker hours that overlap any working-hour rule Then the save is blocked and an inline error lists each conflicting rule and the overlapping time span Given no overlap exists When I save maker hours Then the save succeeds without warnings or errors

Add Exceptions and Temporary Pauses

Given a recurring maker-hours block exists When I add a one-time exception for a specific date Then the block is suppressed for that date and the heatmap reflects the gap Given I add a temporary pause with a start and end date When I view the schedule Then maker hours are suspended during that window and automatically resume after the end date Given I remove an exception or pause When I save Then the original recurrence behavior is restored and reflected in the heatmap

Import Maker Hours From Calendar or Template

Given I choose Import and select a connected calendar or a predefined template When I complete the selection flow Then candidate maker-hour blocks are previewed and I can confirm to create them Given imported blocks would conflict with existing maker hours or working-hour rules When I confirm import Then the system surfaces conflicts, allows me to deselect conflicting items, and blocks only conflicting items from being created Given source events or templates specify a time zone When I import Then resulting maker hours inherit the source time zone

Heatmap Preview Updates and Accuracy

Given I have configured maker hours, exceptions, and pauses When I open the heatmap Then it displays protected coverage for all seven days with a legend and correct local-time labels Given I change a configuration value (add, edit, or remove) When I save the change Then the heatmap updates to reflect the change without requiring a page reload Given I toggle between My View and Team View When I view the heatmap Then My View shows my protection only, and Team View shows aggregated team coverage respecting individual time zones

Apply Team Template With One Click

Given a team template exists When I click Apply Template Then the template’s maker-hour blocks are applied to my profile and previewed before confirmation Given applying the template would override existing blocks When I confirm Then existing blocks are replaced as indicated and an Undo option is shown for at least 10 seconds Given conflicts with working-hour rules are detected during template application When I apply the template Then only compliant blocks are created and all conflicts are listed for review

Persist Preferences and Admin Policy Bounds

Given I save my maker-hours configuration When I log out and back in or retrieve my settings via API Then the saved preferences persist and exactly match what I configured Given an admin defines org-wide defaults and policy bounds When I attempt an override outside the bounds Then the system blocks the change and displays the violated policy with required limits Given my override is within bounds When I save Then it is accepted and takes precedence over the org default for my profile Given an admin updates org-wide defaults When I next load the UI Then my within-bounds overrides remain unchanged and default-only settings update to the new defaults

Hard-Constraint Slot Generation

"As a team lead, I want the scheduler to enforce protected windows as hard constraints so that proposals only include truly viable times for all attendees."

Description

Upgrade the slot generation engine to treat all protection intervals as non-negotiable constraints for every attendee. Candidate windows must exclude protected intervals, satisfy minimum meeting duration and buffer rules, and incorporate TimeMeld’s timezone-weighted ergonomics and fairness scoring. Provide fallback behavior when no viable windows exist (e.g., expand search horizon or suggest invoking the override workflow) and maintain performance SLAs for cross-time-zone, multi-attendee searches.

Acceptance Criteria

Exclude Protected Windows Across All Attendees and Time Zones

Given a meeting request with multiple attendees across different time zones and each attendee has one or more protection intervals within the search horizon When the system generates candidate meeting windows for the next 14 days Then 100% of proposed windows have zero temporal overlap with any protection interval for any attendee (overlap count = 0) And each proposed window is marked in the API payload with protectionBadge = "Protected Windows Respected" And the response summary includes protectedWindowViolations = 0

Enforce Minimum Duration and Pre/Post Buffers

Given minDuration = 45 minutes, bufferBefore = 15 minutes, bufferAfter = 15 minutes, and attendees have calendars with events and protected intervals When the system generates candidate meeting windows Then every proposed window duration is >= 45 minutes And startTime of each proposed window is >= (endTime of the nearest preceding event/protection + 15 minutes) And endTime of each proposed window is <= (startTime of the nearest following event/protection - 15 minutes) And each proposed window includes bufferCompliance = true in the API payload

Rank by Timezone Ergonomics and Fairness with Score Transparency

Given ergonomics scoring is enabled and fairness rotation is enabled with rankingWeights = { ergonomics: 0.7, fairness: 0.3 } And attendees have local-time ergonomic preferences and recent ownership history When the system generates and ranks candidate windows Then each proposed window includes ergonomicsScore, fairnessScore, combinedScore = 0.7*ergonomicsScore + 0.3*fairnessScore And proposals are sorted strictly by combinedScore descending with tie-breaker = earliest startTime And no proposal with a lower combinedScore appears before a proposal with a higher combinedScore And if an attendee exceeds the 4-week ownership quota, proposals burdening that attendee include fairnessPenaltyApplied = true

Fallback on No Viable Windows: Expand Horizon, Suggest Override

Given constraints yield zero viable windows in the default 14-day search When the system attempts fallback search Then the engine expands horizon in +7 day increments up to a maximum of 28 days until windows are found or the limit is reached And if still zero windows, the response includes noResults = true and fallbackActions contains ["SuggestOverrideWorkflow"] And the response includes blockingConstraintsSummary and fallbackAttemptCount >= 1 And analytics/logs record reasonCodes for infeasibility

Performance SLA: Cross-Time-Zone Multi-Attendee Searches

Given a request with 8–10 attendees across >= 5 time zones and a 14-day horizon When generating the first page of top 20 proposals under warm-cache conditions Then p95 end-to-end latency at the slot-generation service boundary is <= 2.0 seconds and p99 <= 3.0 seconds over a sample of >= 1000 requests And under cold-start conditions p95 latency is <= 2.5 seconds And results are streamed or returned atomically with consistent ordering across retries (idempotency key respected)

Handle DST Transitions and Overnight Protected Blocks

Given protected intervals that span midnight and a daylight saving time transition within the horizon When the system normalizes calendars and generates candidate windows for all attendee time zones Then no proposed window partially overlaps a protected interval due to DST offset changes (overlap count = 0 in both UTC and local time checks) And protection intervals are treated as half-open [start, end); a proposal may start exactly at protection end only if buffers are satisfied And proposals that would cross into a protected block after DST shift are excluded

Protection Badges & Reason Transparency

"As a participant, I want proposals to show badges explaining protected times so that I understand why slots are excluded and avoid asking to squeeze meetings in."

Description

Display clear protection badges on proposed and excluded time windows across web UI, extensions, and email. Badges indicate the protection type (e.g., Maker Hours, Focus Block, Org Policy), the affected attendee(s), and a concise reason with hover/tap details and accessible text. Respect privacy settings by redacting sensitive event titles while still conveying the constraint. Provide consistent visual semantics and localization to reduce back-and-forth and build trust in Guarded Proposals.

Acceptance Criteria

Proposed Slots Badge Visibility (Web UI)

Given a scheduling request includes attendees with active protections (Maker Hours, Focus Block, Org Policy) that influenced slot selection And proposed time windows are generated in the web UI When the user views the proposed windows Then each proposed window displays badges for the protections respected that influenced the proposal And each badge shows the protection type and affected attendee name/initials per privacy settings And hovering or tapping a badge reveals a detail tooltip with a concise reason (≤140 chars) and the protection’s start–end time in the viewer’s local timezone And badges are visible at standard desktop and mobile breakpoints (≥320px width) without overlap or truncation And badge display order is deterministic: Org Policy, Focus Block, Maker Hours, then others alphabetically

Excluded Slots Reason Badges (Web UI)

Given excluded time windows are displayed in the day/week view and in the Excluded list When the user inspects an excluded window Then at least one badge indicates the primary blocking protection for that window And the user cannot select the excluded window for proposal (selection control disabled with tooltip explaining why) And hovering/tapping the badge reveals all blocking protections with affected attendees (show up to 5, then “+N more”) And badge styling (icons, colors, shape) matches proposed-slot badges for consistency

Email and Extension Badge Rendering

Given a proposal email and the calendar extension show proposed and excluded windows When the recipient/user views the content Then each slot includes text badges that state protection type and affected attendee(s) per privacy settings And badges render legibly in Gmail web, Outlook (desktop & web), and Apple Mail; if CSS/images are blocked, a plain-text fallback shows the same information And in the extension, hover/tap reveals details; in email, a “Why this time?” link opens the web UI details view And badges include accessible text (no color-only meaning) and alt text for any icons And badge text is localized to the recipient’s locale when known; otherwise falls back to en-US

Privacy Redaction of Sensitive Details

Given an attendee has a private Focus Block or event title and organization policy requires redaction for non-owners When a non-owner views protection badges across web, extension, or email Then the badge shows the protection type with a “Private” qualifier and affected attendee, but does not reveal the event title or description And the tooltip shows a generic reason and time range only (no sensitive text) And the event owner sees the full title per their permissions; admins see details only if policy permits And redaction behavior is consistent across all surfaces and respects per-attendee privacy settings

Localization and Visual Semantics Consistency

Given the application is set to locales fr-FR, de-DE, es-ES, ja-JP, and ar When viewing badges and tooltips across web UI, extension, and emails Then badge labels, dates, times, and pluralization are correctly localized for each locale And right-to-left layout (ar) renders badge alignment and icon placement correctly And the same icons and color semantics are used for each protection type across all surfaces And if a translation is missing, en-US is used and a missing-translation event is logged

Accessibility: Keyboard, Screen Reader, and Contrast

Given a user navigates badges using keyboard and a screen reader When a badge receives focus Then focus is clearly visible and meets minimum 3:1 focus indicator contrast And badge text meets WCAG 2.2 AA (≥4.5:1 contrast) and touch targets are ≥24x24px And the badge exposes an accessible name including protection type, affected attendee(s), and “opens details” when applicable And the details tooltip/panel is announced, linked via aria-controls/expanded, and is dismissible via Esc and focus loss without trapping focus

Policy Hierarchy and Aggregation Rules

Given multiple protections overlap for a time window across one or more attendees When rendering badges for that window Then badges are prioritized by Org Policy > Focus Block > Maker Hours > Other And no more than 3 badges are shown inline; additional protections are summarized as “+N” And the details view lists all protections sorted by priority then attendee name And the same aggregation and ordering rules are applied across web UI, extension, and email And unit tests cover overlap, priority order, and overflow cases with ≥90% coverage of badge rendering logic

Consent-based Override & Audit Trail

"As an organizer, I want a consent-based override flow so that I can handle true emergencies without undermining our focus culture."

Description

Enable organizers to request a scoped override when no viable windows are found or in urgent cases. The flow requires selecting the specific protection to override, entering a justification, and obtaining explicit consent from impacted attendees. Record all actions in an audit log, enforce policy controls (e.g., disable overrides for org policies, require admin or majority consent), and deliver notifications via email/Slack. Overrides are time-bound and revert automatically after the event or expiration.

Acceptance Criteria

Scoped Override Request When No Viable Windows

Given a scheduling attempt finds no viable windows due to protected blocks When the organizer clicks "Request scoped override" Then the UI requires selecting one or more specific protections to override per impacted attendee And the UI requires a non-empty justification of at least 20 characters And the UI displays a summary of impacted attendees, protections, and proposed time window(s) And the Submit action remains disabled until selections and justification are valid And on submit, a pending override request with a unique ID is created

Explicit Attendee Consent Collection and Thresholds

Given a pending override request with impacted attendees exists When the request is submitted Then consent requests are delivered via email and Slack to each impacted attendee within 60 seconds And each consent request includes the justification, protections to be overridden, the time window, and explicit Approve/Decline actions And the system records each response with timestamp and channel And scheduling proceeds only when the configured policy threshold is met (e.g., admin approval or majority of impacted attendees) And until the threshold is met, no event is created and protected blocks remain enforced

Admin and Policy Controls Enforcement

Given an org policy disables overrides entirely When a non-admin attempts to open the override flow Then the override action is blocked with the message "Overrides are disabled by your organization" and an audit entry is recorded Given an org policy requires admin approval for overrides When a non-admin submits an override request Then the request is routed for admin approval and is not scheduled until admin approval is granted in addition to any attendee consent requirements configured

Audit Trail Completeness and Immutability

Given any action occurs in the override lifecycle (creation, update, consent, approval, decline, expiration, reversion) Then an audit log entry is written with actor, action, target, UTC timestamp, and request ID And entries are append-only; updates produce new entries without modifying prior entries And organizer, impacted attendees, and org admins can view the full audit trail for the request And the audit trail can be exported to CSV and JSON including all entries for the request

Notifications and In-Product Indicators

Given a pending override request exists Then the organizer sees an "Override pending" badge on the proposal and draft event And impacted attendees see a "Protected time override requested" badge on relevant time windows And email/Slack notifications contain localized times per recipient timezone and deep links to the consent page And reminder notifications are sent 2 hours before the consent timeout if no response has been recorded

Time-Bound Override Reversion

Given an override is approved and an event is created Then selected protections are lifted only for the event time window specified by the override And after the event ends or the override expiration time passes (whichever is earlier), protections automatically revert without manual action And if the event is canceled or rescheduled outside the overridden window, protections revert immediately and attendees are notified And recurring events require explicit per-occurrence overrides by default; no blanket override is applied unless explicitly configured by policy

Edge Cases and Error Handling

Given all impacted attendees decline or the consent timeout elapses without meeting the threshold Then the override request is marked as failed, no event is created, and organizer and impacted attendees are notified with the reason And if any notification channel fails, the system retries and falls back to alternate channels when available, with failures logged And if the organizer edits protections or time window after requests are sent, prior consents are invalidated, a new consent cycle starts, and audit entries link the versions And if relevant org policy changes mid-process, the request is revalidated immediately; incompatible requests are paused with guidance to comply or cancel

Recurring Meeting & Rotation Compliance

"As a distributed team, I want recurring meetings and rotation to respect protected windows so that no one repeatedly sacrifices deep work or sleep."

Description

Ensure recurring series proposals respect weekly protection patterns and integrate with TimeMeld’s equity scoreboard to rotate ownership and time burdens without violating maker hours. The system simulates multiple future occurrences to avoid repeating inconvenient slots for the same person, rebalances when participants or constraints change, and surfaces a preview of the rotation plan before finalizing.

Acceptance Criteria

Weekly Guard Compliance for Recurring Series

Given a recurring meeting is proposed with Guarded Proposals enabled And all participants have maker hours and focus blocks defined weekly When the system generates the series across the next 12 weeks Then zero occurrences overlap any participant’s protected windows And each proposed occurrence displays protection badges summarizing enforced constraints And if no guard-compliant window exists for a given week, the system withholds that occurrence and surfaces a "No compliant window" reason with impacted participants And daylight saving time transitions are accounted for using each participant’s local timezone so compliance still holds

Equity Scoreboard Ownership Rotation

Given a recurring series with rotation enabled and equity weights configured When generating the next 8 occurrences Then ownership is assigned per occurrence so that no participant is owner twice in a row unless all other owners would violate guards And the cumulative owner count difference between any two participants over the 8 occurrences is at most 1, respecting weights And any owner substitution due to guard conflicts is recorded with reason and reflected in the preview

Time-Burden Distribution Without Violating Maker Hours

Given participants span three or more time zones and guard windows are enforced as hard constraints When proposing times for the next 8 occurrences Then no participant is scheduled outside their maker hours or focus blocks And each participant receives at most one occurrence in their personal edge window (defined as the first or last hour of their allowed scheduling window) within the 8 occurrences, unless constraints make this impossible And in impossibility cases, edge-window assignments rotate so no participant receives consecutive edge-window occurrences

Multi-Occurrence Simulation and Repeat Avoidance

Given the simulation horizon is set to 8 weeks When computing proposals for a new recurring series Then the system evaluates all 8 occurrences before finalizing any And it avoids assigning the same participant to the same relative slot bucket (early/mid/late within their allowed window) more than once within the horizon when alternatives exist And the preview displays a simulation scorecard including, per participant: counts of early/mid/late slots and ownership totals

Dynamic Rebalance on Participant or Guard Changes

Given a recurring series is active and a participant is added, removed, or updates guard windows When the change is saved Then only future occurrences more than 48 hours away are rebalanced by default And rebalanced occurrences remain guard-compliant and maintain rotation fairness constraints And the system presents a change diff listing moved, canceled, and newly scheduled occurrences before applying And upon confirmation, calendar updates are sent and the equity scoreboard is updated accordingly

Rotation Plan Preview and Confirmation Gate

Given a new recurring series is being created When the user opens the rotation preview Then at least the next 6 occurrences are shown with local times per participant, assigned owner, protection badges, and fairness metrics And the Finalize action remains disabled until the user confirms the preview And any manual edit forces the preview to refresh and revalidate before enabling Finalize

No-Feasible-Plan Handling

Given constraints yield no compliant schedule within the horizon When proposals are computed Then the system returns no times and surfaces a structured explanation listing constraint conflicts per participant and week And it offers next actions that do not violate guards (e.g., adjust participants, extend horizon), without placing any occurrence in protected windows

Post-Send Drift Detection & Auto-Reproposal

"As a calendar owner, I want TimeMeld to detect new conflicts after proposals are sent so that it can proactively offer alternatives before my focus time is interrupted."

Description

Monitor calendars for changes after proposals or invites are sent and detect when newly added protection intervals create conflicts. Automatically generate alternative windows that honor all constraints, notify participants with clear protection badges and rationale, and update calendar invites (ICS) when rescheduling is confirmed. Apply smart throttling and organizer preferences to minimize notification noise.

Acceptance Criteria

Drift Detection After Protected Block Added

Given a proposal or invite was sent and has not started or completed When any participant adds or extends a protection interval that overlaps the proposed or scheduled time Then the meeting is marked In Conflict within 5 minutes Given a non-protection calendar event overlaps the time When drift detection evaluates Then no auto-reproposal is triggered by this requirement Given a conflict is created less than 15 minutes before the scheduled start When detection runs Then auto-reproposal is suppressed and only the organizer is alerted Given a protection interval is added and then removed within 2 minutes When drift detection evaluates Then no notification or reproposal is sent Given a drift event is detected When it is recorded Then the log includes meeting ID, actor, overlap reason, and timestamp

Constraint-Compliant Alternative Generation

Given a meeting is marked In Conflict When alternatives are generated Then at least 3 ranked candidate windows are produced that satisfy all participants’ protection windows, declared working hours, minimum notice, and meeting duration Given alternatives are generated When evaluating each option Then no candidate overlaps any participant’s protected intervals and ergonomic limits are respected (e.g., back-to-back caps, lunch breaks if configured) Given alternatives are ranked When scoring is applied Then options are timezone-weighted to minimize total inconvenience and presented in descending suitability Given historical inconvenient slots exist for this meeting in the last 4 weeks When generating options Then no candidate repeats a slot flagged as inconvenient by any participant Given organizer preferences specify single-instance or series adjustment When generating options Then options match the specified scope (instance vs series)

Participant Notification With Protection Badges and Rationale

Given conflict-driven alternatives exist When notifying recipients Then the subject and body include the conflict reason, named participant, overlapping times, and protection badges (e.g., Maker Hours, Focus Block) Given organizer notification preferences are set When sending notifications Then messages are sent to the organizer only by default, or to all participants if configured, or auto-rescheduled if enabled Given a notification is delivered When the recipient views actions Then options include Accept top suggestion, Choose another time, and Request exception Given notifications are rendered When times are displayed Then each time is shown in the recipient’s local timezone and UTC Given throttling bundles multiple conflicts When a consolidated message is sent Then it summarizes the conflicts and lists the current top-ranked options

Smart Throttling and Preference-Aware Delivery

Given multiple drift events occur for the same meeting within 30 minutes When notifications are prepared Then a single consolidated notification thread is sent instead of multiples Given organizer quiet hours are configured When a drift event occurs during quiet hours Then notifications are deferred to the next allowed send window while alternatives are precomputed Given organizer sets a daily max of 5 scheduling notifications When the limit is reached Then subsequent notifications are rolled into a daily digest Given a meeting has an active reproposal awaiting decision When another drift event occurs Then no new reproposal is created and the existing thread is updated with the latest options Given a drift event resolves within 2 minutes of detection When throttling rules are applied Then no external notification is sent

Confirmed Reschedule Updates ICS Correctly

Given the organizer (or authorized delegate) confirms a proposed alternative When calendars are updated Then an ICS update is sent within 2 minutes using the same UID, incremented SEQUENCE, updated DTSTART/DTEND, and preserved attendees and conferencing details Given attendees receive the update When it is processed by their calendars Then the prior time is superseded without creating a duplicate event Given the meeting is a recurring series and only one instance is moved When generating ICS Then a RECURRENCE-ID is included to update the single instance without altering other occurrences Given the event is updated due to protection conflicts When composing the description Then a brief rationale with protection badges is appended to the event notes Given time zone data is required When composing the ICS Then an appropriate VTIMEZONE component is included to ensure correct local time display

Idempotency, Deduplication, and Auditability

Given the same protection interval is edited multiple times within 10 minutes When drift detection runs Then only one drift event and one notification are created Given a reproposal exists for a meeting and no decision has been made When the same conflict persists Then the system does not resend identical options Given a reproposal was sent and the protection interval causing the conflict is removed When detection confirms no conflict remains Then the reproposal is withdrawn and the organizer is notified once subject to throttling Given drift-related actions occur When audit logs are produced Then each drift event, generated options, notifications, and ICS updates are recorded with timestamps and correlation IDs and retained for at least 90 days

Humane Finder

When a requested slot collides with a guard, instantly offers the nearest humane alternatives ranked by explicit tradeoff scores (context‑switch cost, timezone burden, rotation impact). Organizers get transparent, fair options and can confirm the best fit in one click.

Requirements

Real-Time Guardrail Collision Detection

"As an organizer, I want the system to instantly tell me when a requested slot violates participant guardrails so that I don’t waste time on times we can’t use."

Description

Detect scheduling conflicts the moment an organizer proposes a slot by evaluating participant guardrails (working hours, focus blocks, do-not-disturb, no-meeting days, public holidays, and previously assigned rotation constraints). Integrates with connected calendars (Google, Outlook, ICS) and TimeMeld’s team policies to classify a proposed time as hard-blocked, soft-blocked, or acceptable. Exposes a low-latency service (<300ms p95 for up to 12 participants) that returns conflict reasons with machine-readable codes to trigger humane alternative generation. Handles partial attendance requirements (optional vs required attendees), recurring events, and overlapping holds, with robust DST and locale handling. Emits structured telemetry for conflicts to support analytics and continuous tuning.

Acceptance Criteria

Classify Proposed Slot Against Guardrails

Given an organizer proposes a meeting slot and participant guardrails (working hours, focus blocks, do-not-disturb, no-meeting days, public holidays, rotation constraints) are loaded per team policy When the slot is evaluated for all participants Then the service returns overall_classification = hard-blocked if any required participant has a hard conflict under current policy And returns overall_classification = soft-blocked if no required hard conflicts exist but at least one required participant has a soft conflict And returns overall_classification = acceptable if no required participant has a hard or soft conflict (optional attendee conflicts do not elevate the classification)

Low-Latency SLA for Up to 12 Participants

Given a proposed slot with between 1 and 12 participants and valid calendar/policy context When the evaluation request is made to the detection endpoint Then the end-to-end response time p95 is <= 300 ms measured from request receipt to last byte over a rolling 5-minute window under nominal load

Return Machine-Readable Conflict Codes

Given at least one conflict is detected for any participant When the response is returned Then each conflict includes: participant_id, guardrail_type, severity in {hard, soft}, start_ts, end_ts, source in {calendar, policy}, timezone, locale, and a code from an enumerated set And the top-level response includes overall_classification and schema_version And emitted code values conform to the published enumeration and remain backward compatible across versions

Aggregate Classification with Optional vs Required Attendees

Given a meeting proposal with a mix of required and optional attendees When evaluating conflicts Then any hard conflict for a required attendee yields overall_classification = hard-blocked And if no required hard conflicts exist but at least one required attendee has a soft conflict, overall_classification = soft-blocked And if only optional attendees have conflicts, overall_classification = acceptable while their conflicts are still enumerated in the response

Handle Recurring Events with DST Transitions

Given a recurring meeting proposal defined by an RRULE and a start time zone When evaluating the series Then the service returns per-occurrence evaluations within the requested horizon including occurrence_timestamp (organizer time zone), per-occurrence overall_classification, and conflict codes And DST transitions are handled so each participant’s local time reflects correct offsets And locale-specific public holidays and no-meeting days are applied per participant for each occurrence

Merge Multi-Calendar Sources and Overlapping Holds

Given participants have connected Google, Outlook, and/or ICS calendars with overlapping events and holds When evaluating the proposed slot Then events are merged and deduplicated across sources using stable identifiers and time windows And overlapping events collapse to a single conflict with the highest severity per policy (e.g., busy > tentative/hold) And tentative/hold events are treated per team policy as soft or hard and labeled source=calendar with provider metadata

Emit Structured Conflict Telemetry

Given any evaluation request is processed When the response is generated or an error occurs Then a telemetry event guardrail_evaluated is emitted containing request_id, org_id, meeting_id, participant_count, latency_ms, overall_classification, conflict_counts_by_type, per-severity counts, has_recurring flag, timezone_spread, error_code (if any), and schema_version And no PII beyond opaque IDs is included And the event is successfully delivered >= 99% of the time over a rolling 24-hour window

Nearest Humane Alternatives Generator

"As an organizer, I want nearby humane alternatives suggested automatically so that I can quickly choose a workable time without manual back-and-forth."

Description

When a conflict is detected, compute and return the closest feasible meeting windows that minimize participant burden while respecting guardrails and team policies. Generates 3–7 ranked alternatives within a configurable search horizon (e.g., next 10 business days), considering participants’ local times, meeting duration, buffer times, and organizer constraints. Supports hard/soft constraints, mandatory/optional attendees, and per-team “no back-to-back” spacing. Provides a deterministic, explainable selection with ties broken by historical fairness signals. Guarantees sub-700ms p95 end-to-end from proposal to alternatives for teams up to 12 participants.

Acceptance Criteria

Generate 3–7 Ranked Alternatives within Configurable Horizon

Given a scheduling request collides with a guard and the search horizon is configured to 10 business days When the generator runs with a meeting duration and organizer constraints provided Then it returns between 3 and 7 feasible alternatives within the horizon, sorted by total_score descending And if fewer than 3 feasible alternatives exist, it returns all feasible (including zero) and sets result_flag="insufficient_feasible" And each alternative includes: start_utc, end_utc, duration_minutes, participant_timezones[], component_scores{context_switch_cost, timezone_burden, rotation_impact}, total_score, and feasibility_notes

Deterministic, Explainable Ranking with Tradeoff Scores

Given identical inputs (participants, calendars, constraints, weights, horizon) and system seed When the generator is executed 5 times Then the set of alternatives, their order, total_score, and component_scores are identical across runs And each alternative exposes an explanation object enumerating contributions and penalties, whose sum equals total_score within 1e-6 tolerance

Hard/Soft Constraints and Mandatory/Optional Handling

Given attendees have hard constraints, soft preferences, and are marked mandatory or optional When alternatives are generated Then no alternative violates any hard constraint or working-hours guardrail of mandatory attendees And soft-constraint breaches are allowed only with explicit penalties reflected in component_scores and noted in feasibility_notes And alternatives may omit optional attendees only if inclusion would make the slot infeasible, with omitted_optional listed and a recomputed score

No Back-to-Back Spacing and Buffers Enforcement

Given a team rule min_spacing_minutes=S and per-attendee buffers before/after are configured When alternatives are computed Then each proposed slot ensures spacing >= S from adjacent events for all included attendees And per-attendee buffers before and after the meeting are preserved, otherwise the slot is excluded from results

Timezone Ergonomics and Working-Hours Guardrails

Given participants span multiple time zones with defined working hours When alternatives are generated Then every alternative schedules all mandatory attendees within their working hours And the timezone_burden component_score is computed for each alternative and included in the response

Performance SLA: p95 ≤ 700ms for ≤12 Participants

Given teams up to 12 participants and realistic calendar data When measuring end-to-end latency from request to alternatives response over 2000 requests Then the p95 latency is ≤ 700ms and any breach logs an sla_breach event with request_id and measured_latency_ms

Confirm-Ready Payload for One-Click Scheduling

Given a ranked list of alternatives has been returned When the organizer selects an alternative Then the response contains a confirm_token, normalized start/end in UTC, attendee lists segmented by mandatory/optional, and policy references used in scoring And POST /meetings/confirm with the confirm_token creates the event, returns 201 with event_id, or 409 with refreshed alternatives if the slot becomes invalid

Transparent Tradeoff Scoring

"As an organizer, I want to see transparent scores and reasons for each suggested time so that I can choose the fairest option confidently."

Description

Attach a normalized tradeoff score to each alternative based on three weighted factors: context-switch cost (focus fragmentation, buffers, back-to-back risk), timezone burden (distance from participants’ preferred hours, weekend/holiday proximity), and rotation impact (fairness delta vs equity scoreboard). Provide a per-option breakdown and plain-language rationale so organizers can see why an option ranks higher. Offer team-level default weights with per-meeting overrides; persist choices for learning. Ensure scoring is reproducible, auditable, and side-effect free, with versioned formulas and A/B toggles for experimentation.

Acceptance Criteria

Normalized Tradeoff Score Calculation

Given team-level default weights (w_context, w_timezone, w_rotation) exist and sum to 1.0 ± 0.001 When Humane Finder computes scores for a set of alternatives Then each factor subscore is computed in the range [0,100] And weights are each in [0,1] and validated to sum to 1.0 ± 0.001, otherwise computation is rejected with a validation error And the composite score = round(w_context*context_subscore + w_timezone*timezone_subscore + w_rotation*rotation_subscore, 2) and is in [0,100] And the same inputs produce identical composite scores across repeated computations

Per-Option Factor Breakdown and Plain-Language Rationale

Given composite and factor subscores are computed for each alternative When an organizer views an alternative in Humane Finder or retrieves it via API Then the response includes: composite score, each factor subscore, current weights, and each factor’s weighted contribution And a rationale section includes at least one plain-language sentence per factor referencing concrete data (e.g., buffers, preferred hours deviation, equity delta) And all displayed numbers match the underlying computed values within 0.01 And the full breakdown is exportable as JSON via an endpoint with the meeting and option identifiers

Team Default Weights with Per-Meeting Overrides and Persistence

Given a team admin edits default weights When weights are saved Then each weight is between 0 and 1 and totals 1.0 ± 0.001 or the save is rejected with actionable errors And the change is persisted with actor, timestamp, and version Given an organizer sets per-meeting weight overrides during scheduling When scores are computed for that meeting Then the overrides are used instead of team defaults for that session only And the organizer can revert to team defaults in one action And the organizer’s last-used weights are persisted and pre-populated for their next meeting in that team

Reproducibility, Side-Effect Free Scoring, and Auditability

Given a fixed set of inputs (participants, calendars, holidays, preferences, weights, formula version, experiment cohort) When scoring is executed multiple times or on different instances Then the outputs (scores and ranking order) are identical and include a deterministic result checksum And no calendar events, invites, notifications, or other external resources are created, modified, or deleted by the scoring operation And an audit log entry is written capturing: input hash, weight vector, factor versions, formula version, experiment cohort, requester, timestamp, and result checksum And audits are retrievable by meeting ID and include the per-option breakdown used to produce scores

Versioned Formulas and A/B Experiment Toggle

Given formula versions vN and vN+1 are registered and enabled for experimentation When a team is enrolled in experiment E with a 50/50 split Then organizers are stably bucketed into cohorts A or B by a deterministic hash (teamId, organizerId, meetingType) unless an explicit override is set And every score payload includes formulaVersion and experimentCohort metadata And an admin kill switch can disable vN+1, causing new computations to fall back to vN within 60 seconds And audit entries preserve the original version and cohort regardless of subsequent configuration changes

Rotation Impact Fairness Delta vs Equity Scoreboard

Given an equity scoreboard with current ownership balances exists for the team When computing rotation impact for an alternative Then the fairness delta is derived from the projected change to the scoreboard if that alternative is selected And the rotation subscore monotonically increases as projected inequity decreases, per the documented mapping And alternatives that increase inequity beyond a configurable threshold T are flagged in both UI and API And the rationale includes the signed fairness delta and the impacted owners

Deterministic Ranking and Tie-Breaking

Given a set of alternatives with computed composite scores When Humane Finder returns ranked options Then options are sorted by composite score descending And ties within 0.01 are broken by (1) lower timezone burden subscore loss, (2) lower context-switch subscore loss, (3) earlier UTC start time, (4) lexicographic ISO datetime And the ranking order is stable across repeated computations with the same inputs And the top-ranked option corresponds to the maximum composite score within numeric precision

One-Click Confirm & Auto-Invite

"As an organizer, I want to confirm a suggested time in one click so that invites go out immediately without manual editing."

Description

Enable organizers to confirm any suggested alternative in one click, automatically creating the calendar event, adding conferencing details, inviting participants, and posting notifications (email/Slack). Preserves original meeting metadata (title, agenda, docs), updates series logic for recurring events, and writes back to connected calendars with correct organizer/owner. Handles consent prompts when the time falls outside a participant’s preferred hours, and offers fallback placeholders if conferencing provisioning fails. Emits success/failure webhooks and updates TimeMeld timelines for traceability.

Acceptance Criteria

One-Click Confirm Creates Event With Preserved Metadata

Given an organizer views Humane Finder alternatives for a meeting request with title, agenda, and attached docs And the organizer’s calendar and conferencing accounts are connected and have create permissions When the organizer clicks Confirm on an alternative Then an event is created in the designated calendar at the selected time within 5 seconds And the event title matches the original request exactly And the event description contains the original agenda and links to the attached docs And conferencing details are provisioned and inserted into the event location or description And all requested participants are added as invitees with RSVP status "needsAction" And email and Slack notifications are sent to all invitees within 30 seconds containing final time and join details

Correct Organizer Ownership and Multi-Calendar Writeback

Given the meeting has a designated owner based on rotation rules And the owner’s calendar is connected to TimeMeld When the organizer clicks Confirm on an alternative Then the event organizer field is set to the designated owner account And the event is written to the owner’s primary calendar And for participants with connected calendars, the event is added or updated on their calendars And for participants without connected calendars, standard ICS invites are delivered And the rotation ledger is updated to reflect this occurrence assigned to the owner

Consent Prompt for Outside Preferred Hours

Given at least one required participant’s preferred hours exclude the selected alternative time When the organizer clicks Confirm Then a consent modal appears listing impacted participants and the time outside their window And the organizer must choose Request Consent, Override (if policy allows), or Pick Another Time And if Request Consent is chosen, consent requests are sent via email and Slack within 30 seconds And the event remains in Awaiting Consent state and is not sent as final until all required participants approve or the organizer overrides under policy And all approvals and declines are captured in the timeline with timestamps and actor identities

Recurring Series Scope and Series Logic

Given the request is part of a recurring meeting series When the organizer clicks Confirm on an alternative Then the organizer is prompted to select scope: This occurrence only, This and all following, or Entire series And the calendar is updated to reflect the chosen scope using recurrence exceptions where applicable And participants receive updated invitations that correctly reflect the chosen scope And the rotation ownership schedule is recalculated if scope affects future occurrences And the original meeting metadata remains consistent across affected occurrences

Conferencing Provisioning Failure Fallback

Given conferencing provisioning fails or times out within 10 seconds during confirm When the organizer clicks Confirm on an alternative Then the event is still created at the selected time without a conferencing link And a visible placeholder "Conferencing link to be added" is inserted in the event description And a retry job is queued and attempted per provider backoff policy And participants are notified that conferencing details will follow And a failure webhook is emitted with error code, provider, correlationId, and retry schedule

Success and Failure Webhooks with Timeline Traceability

Given an alternative is confirmed When the flow completes with success or failure Then a webhook is emitted within 5 seconds with eventId, meetingId, status (success|failure), selectedSlot, scope (single|series), organizerId, participantIds, and correlationId And the TimeMeld timeline is updated with a single entry containing the same correlationId, the tradeoff scores of the selected slot, and delivery status for email and Slack And in case of retries (e.g., conferencing), subsequent webhooks and timeline entries reference the same correlationId And no sensitive document contents or private notes are included in webhook payloads

True One-Click Confirmation From Alternatives List

Given the Humane Finder alternatives list is visible and no consent prompt is required And conferencing provider tokens are valid When the organizer clicks the Confirm button on a specific alternative Then the meeting is scheduled without any additional required inputs or screens And total user actions from alternatives list to scheduled state is one click And the UI shows a success toast within 3 seconds and auto-dismisses within 6 to 10 seconds And the confirmed alternative is marked as Scheduled and logged with its tradeoff scores in the timeline

Guardrail & Preference Sync

"As a participant, I want my working hours and focus blocks respected automatically so that suggestions fit my schedule without revealing private details."

Description

Continuously ingest and reconcile participant guardrails and preferences from calendars, TimeMeld profiles, and team policies: working hours, focus blocks, time-off, meeting-free days, minimum buffer, and meeting length caps. Provide conflict resolution rules (policy > profile > inferred) and incremental sync with backoff to avoid API throttling. Expose a unified availability model to the conflict detector and generator, with per-user privacy controls that hide sensitive event details while retaining busy/available signals.

Acceptance Criteria

First-Time Multi-Source Ingestion

Given a participant has a connected calendar, a TimeMeld profile, and an active team policy, When the initial sync job runs, Then working hours, focus blocks, time-off, meeting-free days, minimum buffer, and meeting length cap are ingested from all available sources. Given source data spans multiple time zones and includes DST transitions, When times are normalized, Then all intervals are stored in the participant’s primary timezone with UTC offsets preserved per occurrence. Given ingestion completes without fatal errors, When the unified availability model is built for the configured planning horizon, Then each field includes a provenance tag (policy, profile, inferred) and a lastUpdated timestamp. Given a field is missing in one source but present in others, When reconciliation occurs, Then the field value is taken from the highest-priority available source and the provenance reflects that source. Given initial sync completes, When persistence occurs, Then sync checkpoints (lastSyncAt per source and any provider sync tokens) are saved atomically.

Deterministic Conflict Resolution (Policy > Profile > Inferred)

Given a participant’s team policy sets working hours that differ from their profile, When reconciliation runs, Then the policy working hours override the profile values in the unified model. Given a profile defines a minimum buffer and an inferred default also exists, When reconciliation runs, Then the profile value overrides the inferred value. Given overlapping constraints (e.g., a profile focus block during a policy meeting-free day), When availability is computed, Then the stricter constraint (policy meeting-free day) prevails, marking that interval unavailable. Given the same input sources and values, When reconciliation runs multiple times, Then the unified availability output is identical across runs (deterministic). Given a lower-priority source changes while a higher-priority source remains unchanged, When reconciliation runs, Then the resulting unified value for that field does not change.

Incremental Sync with Backoff and Throttling Safety

Given provider sync tokens or ETags are available, When incremental sync runs, Then only changed or new items since the last checkpoint are fetched and applied. Given a calendar API responds with HTTP 429 or a Retry-After header, When retry logic executes, Then exponential backoff with jitter is applied, honoring Retry-After, up to the configured retry limit. Given throttling persists beyond the retry limit, When the sync loop evaluates, Then the job backs off for a longer scheduled delay and exits without hot-looping. Given a transient network error occurs mid-batch, When sync resumes, Then it continues from the last committed checkpoint without duplicating or losing applied changes. Given a large backlog exists, When sync proceeds, Then rate limits are not exceeded and progress metrics (items processed, duration, throttle events) are emitted for observability.

Unified Availability Model Exposure to Detector/Generator

Given the conflict detector requests availability for a time range, When the unified model is queried, Then it returns merged busy/available intervals with minimum buffers and meeting length caps applied to the availability calculation. Given the generator requests constraints for a participant, When the unified model is queried, Then the response includes per-field values (working hours, buffers, caps, meeting-free days) and their provenance (policy, profile, inferred). Given identical inputs (time range, participant set, source states), When the model is queried multiple times, Then the same intervals and constraint values are returned (idempotent and deterministic). Given an invalid query (e.g., end before start), When the model is queried, Then a validation error is returned without side effects. Given a daylight saving time transition within the requested window, When the model is queried, Then intervals accurately reflect the shift without overlapping or gaps beyond the source data.

Per-User Privacy Redaction Controls

Given a participant has privacy set to hide event details, When their availability is exposed to the detector/generator, Then only busy/available signals and permitted categories are returned; titles, descriptions, attendees, and locations are redacted. Given the same participant views their own data within TimeMeld, When availability is rendered for them, Then their own event details remain visible according to their permissions while others’ details remain redacted. Given cross-tenant sharing and no explicit consent, When availability is exposed, Then the most restrictive privacy setting is applied by default. Given logging and caching are enabled, When events are processed, Then sensitive fields are excluded from logs and only redacted views are stored in caches. Given a user changes their privacy setting, When the next sync or query occurs, Then the new redaction rules take effect for subsequent exposures.

Buffers, Focus Blocks, Time-Off, and Meeting-Free Days Handling

Given a policy defines meeting-free days, When availability is computed, Then no schedulable availability is returned for those days regardless of other source data. Given profile-defined focus blocks exist, When availability is computed, Then those intervals are treated as busy for scheduling purposes. Given a configured minimum buffer before and after meetings, When adjacent events are closer than the buffer interval, Then the busy intervals are expanded/merged to enforce the buffer. Given approved time-off spans multiple time zones, When availability is computed, Then the entire time-off interval is marked unavailable across the participant’s normalized timeline. Given overlapping focus blocks and time-off, When reconciliation occurs, Then the stricter unavailability (time-off) is retained for the interval in the unified model.

Equity Rotation Impact & Scoreboard Update

"As a team lead, I want meeting choices to update our fairness rotation automatically so that inconvenience is shared equitably over time."

Description

Calculate how each alternative affects meeting ownership rotation and equity scores, preventing repeated inconvenience for the same people and distributing off-hours impact fairly. On confirmation, atomically update the shared equity scoreboard, logging credits/debits and rationale. Provide guardrails to cap consecutive early/late meetings per participant and surface warnings if fairness thresholds would be exceeded. Integrates with reporting to track fairness over time and supports retroactive adjustments when attendees change.

Acceptance Criteria

Rotation Impact Scoring and Ranking

Given a conflicting meeting request with participants having defined working hours, existing equity balances, and configured weights (default rotation-impact weight = 40%) When Humane Finder generates alternative time slots Then each alternative includes per-participant credit/debit deltas, an overall rotation-impact score (0–100), and a composite tradeoff score with visible breakdown And alternatives are ranked deterministically by composite score; ties break by lowest timezone burden, then earliest in requester’s working hours And the top 5 alternatives render within 300 ms for up to 20 candidates And the UI reveals rotation-impact rationale per alternative, including before/after balances and consecutive early/late counters per participant

Guardrails for Consecutive Off-Hours Caps

Given org-level caps for consecutive early and late meetings (default 2 each) with optional per-user overrides When an alternative would cause any participant to exceed a hard cap Then the alternative is marked as blocked by guardrail, the Confirm action is disabled, and the impacted participant(s) and violated cap are displayed And when an alternative would meet but not exceed the soft threshold, a warning is displayed with current counter state And guardrail evaluation includes already scheduled meetings in the past 14 days and proposed alternatives in the current session

Atomic Equity Scoreboard Update on Confirmation

Given an organizer confirms a selected alternative When the confirmation is processed Then the equity scoreboard updates atomically: apply per-participant deltas, persist before/after balances, and write an audit entry with meetingId, seriesId, timestamp (UTC), actor, rationale, deltas, and version And the operation is idempotent via a confirmationId so retries do not duplicate entries And if calendar invite creation fails, the transaction is rolled back and an error is shown within 2 seconds And audit entries are immutable and queryable by meetingId and participant for at least 18 months

Retroactive Adjustments for Attendance Changes

Given attendees are added, removed, marked absent, or a meeting is canceled/rescheduled after confirmation When the change is finalized within the adjustment window (default 72 hours) Then the system recalculates fair deltas, posts adjustment entries with rationale, and updates balances without violating hard caps And affected participants are notified via email/in-app within 5 minutes with before/after balances and audit links And manual admin adjustments require a reason code and are recorded as compensating entries (no mutation of prior records)

Fairness Reporting Integration

Given a team with recorded equity transactions When the fairness report is viewed or the reporting API is called Then metrics are available per participant and team: cumulative credits/debits, current balance, consecutive early/late streaks, off-hours share %, and a fairness dispersion metric (Gini) And filters include date range, team, meeting series, and meeting type; responses return within 2 seconds for up to 10,000 transactions And data is exportable as CSV and accessible via /reports/fairness with pagination and OAuth2 scopes time:read and equity:read

Timezone and DST Robustness

Given participants across timezones and upcoming DST transitions or personal timezone changes When alternatives are scored and later confirmed during a DST boundary or after a user updates their timezone Then off-hours determination uses the participant’s effective local time at meeting occurrence And consecutive early/late counters roll over by local-day boundaries post-change with no double-counting across DST fall-back And a backfill job recalculates scores for affected upcoming meetings within 15 minutes of a timezone change and posts adjustments if required And automated tests cover at least 6 DST transition dates across NA, EU, and APAC

Timezone Normalization & DST Safety

"As an organizer, I want times displayed and scheduled correctly across timezones and DST changes so that no one joins at the wrong hour."

Description

Normalize all computations to a canonical time model with accurate per-user timezone detection, DST transitions, regional holidays, and short-notice changes. Validate suggested times against future DST shifts, handle ambiguous/nonexistent local times, and present localized times consistently across UI, emails, and calendar invites. Include regression tests for common DST edge cases and provide fallbacks when a locale database update is pending.

Acceptance Criteria

Canonical UTC Normalization for Scheduling Computations

Given organizers and attendees across at least three IANA timezones When Humane Finder computes and ranks alternative meeting windows Then all internal computations are performed in UTC with minute-level precision And the same input produces identical rankings regardless of the requester’s local timezone And each candidate retains per-attendee mapping of UTC start/end to local time via IANA TZID And no candidate’s computed local offset changes after normalization round-trip (UTC -> local -> UTC)

Per-User Timezone Detection and Override Persistence

Given a new user connects their calendar and visits the app When TimeMeld detects timezone from browser and calendar provider Then the stored timezone equals the provider’s IANA TZID by default And a mismatch greater than 30 minutes triggers a non-blocking prompt to confirm or override And a user-selected override persists across sessions and API responses And subsequent alternative-window computations use the persisted TZID

Future DST Shift Validation for Suggested Windows

Given suggested windows may occur after upcoming DST transitions in any attendee’s locale When Humane Finder generates alternatives for the next 12 months Then candidates that fall into nonexistent local times (spring-forward gaps) for any attendee are excluded And ambiguous local times (fall-back overlaps) are disambiguated to the earlier wall-clock occurrence with explicit offset labeling And no .ics payload is produced with DTSTART/DTEND that serialize to nonexistent local times And regression tests cover US, EU, and AU/NZ DST transition dates for the next two seasons

Handling Ambiguous and Nonexistent Local Times in UI and Invites

Given a candidate occurs on a DST transition day for any attendee When the candidate is displayed in UI and notification email and generated as a calendar invite Then the display includes local time, GMT offset, and zone abbreviation (e.g., 09:30 GMT-7 PDT) And a tooltip or detail view shows the canonical UTC timestamp And the .ics contains TZID and a correct VTIMEZONE block matching the attendee’s TZ rules And expanding the .ics with a standards-compliant parser yields the same local clock time as shown in the UI

Cross-Surface Localization Consistency (UI, Email, Calendar Invites)

Given a meeting alternative is selected and confirmed When viewed by each participant across web UI, email, and calendar client Then all surfaces present identical local clock time and offset for that participant And 12/24-hour format follows the participant’s locale preference And automated tests detect no cross-surface discrepancy greater than 1 minute or any offset mismatch And tradeoff scores shown reference the same localized time values used to compute timezone burden

Regional Holidays and Guard Compliance in Humane Alternatives

Given per-attendee regional holiday calendars and personal guard rules are enabled When a requested slot collides with a holiday or guard for any attendee Then Humane Finder excludes the conflicted slot and proposes nearest humane alternatives And ranking penalizes alternatives within 12 hours of a holiday for affected attendees And the UI shows an explanation chip listing affected regions/attendees and rule source And unit tests verify exclusion and penalty for at least US, IN, and AE public holidays

Timezone Database Outage/Update Fallbacks and Reconciliation

Given the timezone database for a locale is outdated or temporarily unavailable When TimeMeld must compute and present alternatives involving that locale Then the system uses last-known tz rules with explicit provisional labeling to users And candidates likely impacted by pending changes are highlighted and optionally deferred And once the tz database updates, the system automatically revalidates and reconciles affected events, notifying organizers of any changes And monitoring emits an alert when fallback mode is active for more than 1 hour

Focus Buffers

Auto-adds smart pre/post buffers around focus blocks and long meetings, adjusting length by meeting type and role. Prevents back‑to‑back context switching, preserves ramp‑up/down time, and improves on‑time starts and session quality.

Requirements

Dynamic Buffer Rules Engine

"As a remote product manager, I want buffer times to adapt to my role and meeting type so that I avoid back-to-back context switching and start sessions prepared."

Description

Compute and auto-apply pre/post buffer durations based on meeting type (e.g., standup, 1:1, design review), role (host, presenter, note-taker, attendee), meeting length, time of day, and context-switch intensity. Incorporate timezone fatigue and TimeMeld’s equity scoreboard signals to lengthen buffers for participants bearing off-hours load or heavy facilitation. Provide configurable defaults, min/max thresholds, and deterministic priority ordering when multiple rules match. Recalculate buffers idempotently on create/update/cancel events, ingesting metadata from invites (labels, templates) and series patterns. Outcome: consistently preserved ramp-up/down time and improved on-time starts without manual tuning.

Acceptance Criteria

Buffers by Meeting Type and Role

Given rule config maps (Design Review, Presenter) to pre=15m and post=10m And a 60-minute Design Review where the current user is the Presenter exists on the user's calendar When the rules engine computes buffers Then it creates a 15-minute pre-buffer immediately before and a 10-minute post-buffer immediately after the meeting on the user's calendar And both buffers are marked as busy and inherit the meeting's privacy setting And no existing non-buffer events are shifted or overlapped by the buffers Given rule config maps (Standup, Attendee) to pre=5m and post=0m And a 15-minute Standup where the current user is an Attendee exists When the rules engine computes buffers Then it creates only a 5-minute pre-buffer and no post-buffer

Timezone Fatigue and Equity Scoreboard Weighting

Given baseline buffers for a meeting compute to pre=10m and post=10m from type/role rules And the meeting starts at 22:00 local time for the current user And an equity scoreboard off-hours burden percentile >= 80% applies to the user And an off-hours multiplier of 1.5x and equity bonus of +5m are configured When the rules engine computes final buffers Then the user's buffers are increased to pre=20m and post=20m (10m * 1.5 + 5m), subject to threshold clamping And the increased buffers remain adjacent to the meeting And other participants without off-hours burden do not receive increased buffers on their calendars

Defaults and Min/Max Threshold Enforcement

Given no type/role/length/time-of-day rules match a meeting And global defaults are configured to pre=5m and post=5m When the rules engine computes buffers Then it applies pre=5m and post=5m Given computed pre-buffer is 40m and post-buffer is 1m And thresholds are configured as min=3m and max=30m When thresholds are enforced Then the pre-buffer is clamped to 30m and the post-buffer is raised to 3m And the final applied buffers equal the clamped values

Deterministic Rule Priority and Tie-Breaking

Given two rules match a meeting And Rule A has priority=90 and Rule B has priority=80 When the rules engine selects a rule Then Rule A is selected and applied Given two rules match with equal priority And Rule C matches (type, role, length) and Rule D matches (type, role) When the rules engine selects a rule Then Rule C (more specific) is selected and applied Given two rules match with equal priority and equal specificity And Rule E has updatedAt=2025-09-10T12:00:00Z and Rule F has updatedAt=2025-08-30T12:00:00Z When the rules engine selects a rule Then Rule E (most recently updated) is selected and applied Given two rules match with equal priority, specificity, and updatedAt And Rule G has ruleId="rule-01" and Rule H has ruleId="rule-02" When the rules engine selects a rule Then the rule with lexicographically smaller ruleId (rule-01) is selected And the same selection occurs on every recomputation with identical inputs

Idempotent Recalculation on Create/Update/Cancel

Given a meeting is created and eligible buffers compute to pre=10m and post=10m When the rules engine runs the first time Then exactly two buffer events are created adjacent to the meeting Given the rules engine runs again with no changes When it recomputes Then no additional buffer events are created and existing buffers are left unchanged Given the meeting start time is moved 15 minutes later When buffers are recomputed Then both buffer events shift to remain exactly adjacent, preserving their durations Given the meeting is canceled When buffers are recomputed Then all associated buffer events are deleted from the user's calendar

Invite Metadata and Series Pattern Ingestion

Given an invite contains label="Design Review" and template="DR-v2" When the rules engine evaluates rules Then it treats the meeting as type=Design Review regardless of the title text And applies the corresponding buffers Given a weekly recurring series with 10 occurrences When a series-level label is added that matches a rule Then buffers are applied to all future occurrences consistently Given a single occurrence is edited to have label="1:1" When rules are recomputed for the series Then the edited occurrence uses 1:1 buffers while other occurrences retain Design Review buffers

Context-Switch Intensity Scaling

Given the user's previous event ends immediately before the meeting and is categorized as Deep Work with intensity=0.9 And a role switch occurs from Note-Taker to Presenter And high-intensity multiplier=1.5x is configured When the rules engine computes the pre-buffer Then the pre-buffer equals base-pre * 1.5, subject to max threshold, and remains adjacent to the meeting Given the previous event and the meeting share the same category and role (low intensity) When the rules engine computes the pre-buffer Then the pre-buffer equals the base-pre with no intensity scaling applied

Calendar Auto-Block & Visibility Controls

"As an engineer, I want buffers to appear as private busy blocks on my calendar so that my time is actually protected without spamming colleagues with extra invites."

Description

Automatically create and maintain adjacent buffer events on connected calendars (Google Workspace, Microsoft 365) with correct duration, color, and privacy (default Private with minimal titles). Support selection of target calendar (primary or dedicated "Buffers" calendar), busy/free display options, and exclusion from attendee notifications. Keep buffers in sync when meetings are moved, extended, or canceled; handle recurring series. Provide offline queueing and rate-limit/backoff handling. Respect OOO/all-day events and working hours. Outcome: buffers are reliably enforced as actual protected time across integrated calendars.

Acceptance Criteria

Auto-create Adjacent Buffers on Meeting Creation (Google & Microsoft 365)

Given the user has connected Google Workspace or Microsoft 365 and enabled Focus Buffers with configured pre/post durations by meeting type and role And the user has selected a target calendar (Primary or a dedicated "Buffers" calendar) and a buffer color and Busy/Free setting When the user creates a new meeting within working hours Then pre- and post-meeting buffer events are created immediately adjacent to the meeting on the selected calendar And the buffer durations match the configured rules for the meeting type and organizer role And the buffer events are marked Private and display a minimal title "Focus Buffer" And the buffer events use the configured color And the buffer events include no attendees and trigger no notifications to any meeting participants And the buffer events’ free/busy status matches the user’s buffer visibility setting And the buffers appear within 10 seconds of meeting creation

Maintain Buffers on Meeting Move/Extend/Cancel

Given a meeting with existing adjacent buffer events When the meeting is moved to a new start time/date Then both buffer events shift to remain immediately adjacent to the meeting with original relative durations When the meeting is extended or shortened Then the buffer events adjust to remain adjacent without overlapping the meeting When the meeting is canceled Then the associated buffer events are deleted within 10 seconds And no orphan or duplicate buffer events remain And updates originating from any client (web, mobile, desktop) are detected and applied within 15 seconds

Offline Queueing and Rate-Limit/Backoff Reliability

Given the system loses connectivity or receives API 429/5xx responses from Google or Microsoft When buffer create/update/delete operations are required Then the operations are queued locally and retried with exponential backoff respecting provider rate limits And operations are idempotent to prevent duplicate buffer events And all queued operations succeed within 5 minutes of connectivity being restored (subject to provider availability) And no user-facing errors persist after successful retries

OOO/All-day Events and Working Hours Compliance

Given the user has defined working hours and may have Out of Office (OOO) or all-day events When a meeting is created or updated adjacent to OOO/all-day events or outside working hours Then buffers are only created within working hours and never overlap all-day or OOO events And if a buffer would fall entirely outside working hours or exclusively within an OOO/all-day block, that buffer is skipped And remaining valid buffers are created as usual and remain Private And skipped buffers are recorded in logs for auditability

Target Calendar Selection and Permissions

Given the user selects a dedicated "Buffers" calendar as the target and has write permission When buffers are created or updated Then all buffer events are placed on the selected "Buffers" calendar When the selected calendar is unavailable or lacks write permission Then the system falls back to the primary calendar and notifies the user in-app without blocking buffer creation And no buffers are attempted on calendars without write access And changing the target calendar only affects newly created buffers; existing buffers remain on their original calendars

Busy/Free and Privacy Visibility Controls

Given the user configures buffers to appear as Busy or Free and sets default privacy to Private with minimal titles When buffers are created or updated Then the buffer events’ transparency (Busy/Free) matches the user configuration And event visibility is Private with a minimal title "Focus Buffer" and no description And no attendees are added and no notifications are sent to any meeting participants And other viewers see only free/busy impact per configuration and cannot view buffer details

Conflict Resolution for Back-to-Back Meetings

Given two meetings are adjacent or near-adjacent such that their configured buffers would overlap When buffers are created or updated Then at most one buffer event exists between the two meetings And the single intermediate buffer has a duration equal to the greater of the two overlapping buffer durations and remains Private And buffers never overlap meetings or extend beyond working hours And no duplicate or fragmented buffer events remain after conflict resolution

Conflict Resolution & Rescheduling Intelligence

"As a team lead, I want the system to intelligently resolve buffer conflicts so that my core focus time isn’t broken and meetings still start on time."

Description

When buffer placement conflicts with existing events or focus blocks, apply policy-driven resolution: preserve hard focus blocks, shrink/expand buffers within min/max thresholds, or propose alternate meeting times via TimeMeld’s suggestion engine. Provide a preview of impacts before applying changes and a one-click rollback. Ensure series-aware adjustments and avoid fragmenting long focus sessions. Outcome: intelligent adjustments maintain ergonomics without disrupting critical commitments.

Acceptance Criteria

Policy-Driven Conflict Resolution Order

Given a buffer placement that conflicts with existing events and a hard focus block When TimeMeld evaluates the conflict Then it preserves the hard focus block unchanged per policy And it attempts buffer shrink/expand within policy-configured min/max thresholds And if the conflict persists, it generates alternate meeting times via the suggestion engine And no calendar changes are committed until the user confirms via the impact preview

Buffer Elasticity Within Policy Thresholds

Given pre/post buffers defined by meeting type and role with policy min/max durations And a buffer conflicts with an adjacent event When adjustment is attempted Then the buffer is reduced or expanded only within the configured min/max bounds And if a valid duration cannot be achieved within bounds, the buffer remains at the nearest bound And the system flags the event as requiring rescheduling suggestions instead of violating bounds

Alternate Meeting Time Proposals When Constraints Are Unsatisfied

Given a buffer conflict that cannot be resolved within policy thresholds without impacting a hard focus block When TimeMeld invokes the suggestion engine Then it returns at least 3 alternate time windows ranked by timezone-weighted ergonomic score ≥ the policy threshold And each suggestion preserves required min buffers, honors hard focus blocks, and respects participants’ working hours And each suggestion includes a reason code summarizing which constraints are satisfied and which conflicts are avoided

Impact Preview and One-Click Rollback

Given pending buffer adjustments and/or reschedules have been computed When the user opens the impact preview Then the preview lists all affected events (title, date/time, attendees), buffer duration deltas, and any moved occurrences And the user can Apply all changes with a single action And after applying, a one-click Rollback restores the exact prior state for all affected items within the current session And rollback events are logged in the audit trail with timestamps and actor

Series-Aware Adjustments for Recurring Events

Given a recurring meeting series where buffer placement for one occurrence causes a conflict When adjustments are applied Then the user can choose This occurrence only or All future occurrences And selecting All future occurrences applies consistent buffer logic across the series respecting per-occurrence exceptions And the system prevents partial updates that would leave inconsistent buffer lengths within the same recurrence rule unless explicitly chosen

Avoid Fragmenting Long Focus Sessions

Given a long focus block exceeding the minimum uninterrupted duration policy And a conflicting buffer adjustment would split the focus block into segments shorter than the minimum When TimeMeld resolves the conflict Then it does not split the focus block And it instead prioritizes rescheduling the adjacent meeting via suggestions or adjusts the meeting’s buffers within policy And the final schedule contains no focus segment shorter than the configured minimum

Personalization & Org Policy Templates

"As an ops admin, I want to define buffer policies by role and meeting type so that teams get consistent protection without manual setup."

Description

Enable users to create personal buffer profiles (e.g., heavier buffers before presentations, lighter after 1:1s) while allowing org admins to define team-wide templates mapped to roles, meeting types, and timezones. Support inheritance and precedence (org > team > user > meeting override), "Do Not Buffer" tags, exception windows, and work-hour alignment. Integrate with HRIS/SCIM for role and team syncing. Outcome: scalable, consistent adoption with room for individual ergonomics.

Acceptance Criteria

Policy Precedence Resolution: Org > Team > User > Meeting Override

Given an org template, a team template, a user profile, and a meeting-level override all define buffer values for the same meeting type When buffer computation runs for a scheduled meeting Then the applied values are selected strictly by precedence Org > Team > User > Meeting Override for each attribute (pre/post length, min/max) And unspecified attributes at a lower level inherit from the nearest higher level that specifies them And a resolution log records the winning source per attribute and the discarded sources with reasons And the same inputs produce identical outputs across repeated runs

HRIS/SCIM Sync Maps Roles/Teams to Templates

Given SCIM/HRIS provides a user with role and team attributes When an initial sync completes Then the user is assigned the correct org/team templates within 15 minutes and policies are evaluated for all future meetings And subsequent attribute changes received via webhook or polling update the mapping within 2 minutes and trigger recomputation of future buffers And if multiple templates match, the highest org-defined priority is applied; ties fall back to most specific (team over org) And if SCIM is unavailable, the last successful mapping persists and sync retries with exponential backoff without duplicating assignments And all mapping and changes are written to an audit log with timestamp, source, and result

User Personal Buffer Profiles by Meeting Type

Given a user creates multiple personal buffer profiles with per–meeting-type pre/post settings When the user selects a default personal profile Then it is applied to their meetings for types not explicitly set by higher-precedence org/team policies And when the user switches to a different profile, future meetings reflect the new settings within 60 seconds without altering meeting start/end times And validation prevents saving profiles with negative values or totals exceeding 60 minutes per side (error displayed with inline message) And a preview panel shows the effective pre/post buffer for a selected upcoming meeting and the source of each value

Respect "Do Not Buffer" Tags and Meeting-Level Flags

Given an event contains a configured "Do Not Buffer" tag (title keyword, label, or metadata flag) When buffer evaluation runs Then no pre or post buffers are added for that event, regardless of policy level And any previously scheduled buffers for that event are removed within 60 seconds And tag detection is case-insensitive and matches whole words from an admin-managed list And an entry in the resolution log states suppression due to Do Not Buffer with the detected token

Exception Windows Modify or Disable Buffers

Given an admin defines exception windows (disable buffers or cap to N minutes) scoped by org/team/timezone and meeting type When a meeting falls fully inside a disable window Then all buffers for that meeting are suppressed And when a meeting falls partially inside a cap window Then buffers are truncated so effective buffer inside the window does not exceed the cap, without changing the meeting time And the exception that applied is recorded in the resolution log with window ID and rule And outside the window, normal policy evaluation resumes

Work-Hour Alignment Across Time Zones

Given per-user working hours derived from calendar settings or org policy and the user's timezone When buffers would extend outside a user's working hours Then buffers are clipped at the workday boundary for that user without moving the meeting And for multi-timezone meetings, clipping is applied per attendee’s personal buffer blocks independently And if a clipped buffer would overlap another event on that user’s calendar, the buffer is further shortened to avoid overlap And a note in the resolution log indicates work-hour clipping with before/after durations

Calendar Updates and Non-Disruptive Invites

Given buffers are created, updated, or removed by policy evaluation When changes are applied Then calendar holds are added/updated/removed within 30 seconds, marked Busy and Private where supported, and do not send email updates to other attendees And meeting start/end times remain unchanged And operations are idempotent: repeating the same evaluation does not create duplicate holds And failures to write to the calendar are retried up to 3 times with backoff and surfaced in an error log

Inline Scheduler UI & Overrides

"As a designer, I want to see and tweak buffer times while scheduling so that I can adjust for special cases without breaking my overall preferences."

Description

Visualize pre/post buffer halos directly in TimeMeld’s scheduler and event detail views, showing computed durations and rationale (rule source, role, time-of-day). Allow one-click per-meeting overrides, series-level edits, and bulk apply. Include guardrails against going below minimum thresholds, undo/redo, keyboard shortcuts, and accessible interactions across web and mobile. Outcome: transparent, controllable buffers that users trust and can adjust quickly when needed.

Acceptance Criteria

Buffer Halos Visualization in Scheduler Grid

Given a user opens the TimeMeld scheduler on web or mobile, When events with eligible focus blocks or long meetings are rendered, Then pre- and post-buffer halos appear around each applicable event with visible duration labels (e.g., "Pre 15m", "Post 10m"). Given an event is selected or hovered, When the user invokes the buffer tooltip, Then the tooltip displays rationale including rule source, user role, and time-of-day modifier. Given the scheduler is zoomed or the viewport changes, When the grid re-renders, Then buffer halos remain aligned to event boundaries and scale accurately to the time grid. Given two buffer halos would visually overlap, When rendered, Then halos clearly indicate constraint state (e.g., striped pattern) without obscuring event details and remain selectable via keyboard and touch. Given a user navigates via keyboard, When focus moves across events, Then halos and tooltips are reachable with visible focus outlines and have accessible names and roles (WCAG 2.1 AA).

Event Detail View Shows Buffer Durations & Rationale

Given a user opens an event’s detail view, When the event has computed buffers, Then the view displays separate Pre and Post buffer durations and a rationale breakdown listing rule source, role, and time-of-day. Given an event is ineligible for buffers, When the detail view is opened, Then the UI shows "No buffer" with reason (e.g., "Short meeting under 10m") and does not show override controls. Given an event has constrained buffers due to adjacent events, When the detail view is opened, Then the UI indicates the constraint with an explanation and a link to preview the impacted time span on the scheduler. Given assistive technology is used, When the detail view loads, Then buffer fields, rationale, and states are announced with semantic labels and meet contrast requirements (WCAG 2.1 AA).

One-Click Per-Meeting Buffer Override

Given a user selects an eligible event, When they click "Override buffers", Then the event switches to manual mode and displays quick-select durations (e.g., 5m/10m/15m) and a custom input for Pre and Post. Given a user adjusts a buffer duration, When the new value is within allowed thresholds, Then a live preview updates on the scheduler and the Save action becomes enabled. Given a user inputs a value below the minimum threshold, When they attempt to save, Then the save is blocked, the invalid field is highlighted, and an inline message states the minimum allowed value. Given the user clicks "Reset to smart", When in manual mode, Then the buffers revert to computed defaults and manual mode is cleared. Given the override is saved, When the user re-opens the event on any device, Then the persisted manual values are shown and applied consistently in scheduling.

Series-Level Buffer Edit Applies to All Future Instances

Given a user opens a recurring event, When they choose "Edit series buffers", Then a scope selector is shown with options: This event only, This and following, Entire series. Given the user selects "This and following" or "Entire series", When they save, Then buffer changes apply to the correct set of future instances within 5 seconds for up to 200 upcoming events. Given some instances have per-event overrides, When a series-level change is initiated, Then the user is prompted to either preserve instance overrides or replace them; the chosen option is honored. Given time conflicts prevent the requested buffers on certain instances, When the series update runs, Then those instances are reported as exceptions with counts and reasons, and no partial saves occur for an instance. Given the series change completes, When the user views the series in scheduler and detail views, Then displayed buffers reflect the new series settings and any preserved overrides.

Bulk Apply Buffer Settings to Selected Events

Given a user multi-selects events via lasso, checkboxes, or filter (e.g., role=Engineer, type=Focus, date range), When they click "Bulk apply buffers", Then a bulk panel shows the target count and selected buffer options. Given the user confirms bulk apply, When processing starts, Then a progress indicator shows completion percentage and an estimated time remaining; the process is cancellable. Given some events are not eligible or conflict with policy, When bulk apply finishes, Then a summary lists successes, failures with reasons, and offers a retry for failed items. Given network latency or app suspend occurs, When bulk apply resumes, Then the operation is idempotent and does not duplicate changes. Given bulk updates complete, When the scheduler refreshes, Then all changed events display updated halos and rationales consistently across web and mobile.

Minimum Threshold Guardrails & Warnings

Given an organization minimum pre/post buffer is configured, When a user attempts to set a value below the minimum, Then the input is blocked at the minimum and a tooltip explains the policy. Given a user’s role has a higher minimum than the org baseline, When setting buffers, Then the role-specific minimum is enforced and surfaces in the rationale. Given applied buffers would cause overlap into locked events or outside working hours, When the user attempts to save, Then the UI proposes the nearest valid durations and disables "Save" until a valid selection is chosen. Given policy forbids overrides below minimum, When the user tries to force save, Then the action is prevented and logged, and a non-dismissable banner explains the restriction with a link to policy settings (if permissions allow).

Undo/Redo and Keyboard Shortcuts for Buffer Changes

Given the user has made buffer changes (per-event, series, or bulk), When they press Cmd/Ctrl+Z, Then the last buffer change is undone; when they press Shift+Cmd/Ctrl+Z, Then the change is redone. Given no further history exists, When undo or redo is invoked, Then the command is ignored and a subtle indicator shows "No more actions". Given the user is on mobile, When editing buffers, Then an on-screen Undo and Redo control is available and performs the same actions as keyboard shortcuts. Given an undo/redo occurs, When using a screen reader, Then the action and resulting state are announced. Given a new change is made after an undo, When the user attempts redo, Then the redo stack is cleared to maintain a correct action history.

Outcomes Analytics & Auto-Tuning

"As a CTO, I want analytics that show how buffers affect punctuality and overruns so that we can tune policies to maximize focus and meeting quality."

Description

Measure on-time starts, meeting overrun vs. planned, late-join rates, context-switch frequency, and focus block integrity to evaluate buffer effectiveness. Provide privacy-preserving, role- and team-level dashboards, export, and alerts. Use feedback loops and opt-in A/B tests to auto-tune default buffer lengths by meeting type and role, with clear change logs. Outcome: data-driven continuous improvement of buffer policies that increases attendance quality and reduces schedule churn.

Acceptance Criteria

Privacy-Preserving Role/Team Outcomes Dashboard & Export

Given a Team Lead with access to Team A selects Role = 'Engineer' and Time Range = 'Last 4 weeks', When they load the dashboard, Then aggregate metrics for on-time start rate, overrun %, late-join rate, context-switch frequency, and focus block integrity are displayed for the selection within 2 seconds. Given the selected cohort contains fewer than k=5 unique participants, When the dashboard is loaded, Then metric cards and charts are suppressed and a message "Insufficient cohort size" is shown. Given a valid cohort (k>=5), When the dashboard is displayed, Then no names, emails, event titles, or raw timestamps are shown and only aggregate values and anonymized cohorts are visible. Given a user clicks "Export CSV" for the current view and k>=5, When the export is requested, Then a CSV with the same aggregates and a data dictionary is downloaded within 5 seconds and contains no user identifiers or raw event data. Given a user lacks permission for Team A, When they attempt to access the dashboard or export, Then access is denied and no metric data is returned.

On-Time Start Metric Calculation

Given the on-time threshold is configured to 2 minutes, When a meeting host joins within 2 minutes of the scheduled start, Then the meeting is counted as on-time; otherwise it is late. Given multiple hosts exist, When computing the start time, Then the earliest host join time is used. Given a set of meetings in the date range, When computing the on-time start rate, Then cancelled meetings and meetings with zero attendees are excluded. Given a recurring series with 10 instances, When 8 are on-time, Then the on-time start rate is reported as 80%. Given a user opens the metric tooltip, When viewing the on-time start card, Then the definition and threshold value are displayed.

Overrun vs Planned Duration Metric

Given a meeting scheduled for 60 minutes with pre/post buffers of 10 minutes total, When the actual end occurs 73 minutes after the scheduled start, Then planned_end is 60 minutes and overrun_minutes is 13. Given a meeting ends before or at the planned_end, When computing overrun, Then overrun_minutes is 0. Given multiple meetings in a range, When computing overrun %, Then overrun % = meetings with overrun > 0 divided by total eligible meetings, excluding cancelled. Given the user opens the metric tooltip, When viewing overrun, Then the definition states buffers are excluded from planned duration.

Late-Join Rate Alerts

Given the late-join threshold is configured to 10% for Team A and Meeting Type = 'Weekly Sync', When the trailing 14-day late-join rate exceeds 10% with n>=50 attendees evaluated, Then a Slack alert is sent to the team's alerts channel with the metric, trend, cohort, and dashboard link. Given an alert was sent for the same metric and cohort within the last 24 hours, When the condition persists, Then no duplicate alert is sent in that window. Given team quiet hours are set to 20:00–08:00 local time, When an alert triggers during quiet hours, Then delivery is deferred to the next window start. Given a user changes the threshold to 15%, When the next computation runs, Then alerts are evaluated against the new threshold.

Context-Switch Frequency & Focus Block Integrity

Given two consecutive calendar events for a user have different categories or organizers and a gap < 10 minutes with no buffer between, When computing context-switch events, Then the transition counts as one context switch. Given a week of data per user, When aggregating to team level, Then context-switch frequency is computed as average context switches per user per week for k>=5 users. Given a focus block is scheduled for 90 minutes, When a meeting overlaps the block by >= 15 minutes, Then the focus block is counted as interrupted. Given focus block integrity is computed for a cohort, When aggregating for the dashboard, Then integrity = uninterrupted focus blocks / total focus blocks in range. Given out-of-office events are present, When computing these metrics, Then OOO blocks are excluded from both numerators and denominators.

Opt-In A/B Testing for Buffer Lengths

Given experimentation is enabled, When a user opts in, Then they are randomly and deterministically assigned per meeting type and role to control or variant with 50/50 split unless configured otherwise. Given assignment is made, When the user schedules meetings of the tested type, Then the assigned buffer policy is applied consistently for the experiment duration. Given a user opts out, When they schedule subsequent meetings, Then default (non-experiment) buffer policies are applied and the user is removed from analysis. Given non-participants, When they schedule meetings, Then experiment policies are never applied. Given an experiment info panel is opened, When a participant views it, Then they can see assignment, cohort definition, start/end dates, and opt-out control. Given experiment data is exported or displayed, When cohorts are smaller than k=5, Then aggregates are suppressed to preserve privacy.

Auto-Tuning Default Buffers with Change Logs and Guardrails

Given an experiment shows improvement of on-time start rate >= 5% absolute with 95% confidence and min sample size n>=200 meetings per arm, When evaluation completes, Then auto-tuning is eligible for that meeting type and role. Given eligibility is met, When auto-tuning applies, Then new defaults must remain within configured bounds (e.g., 5–20 minutes per side) and cannot change by more than 5 minutes per release. Given a change is applied, When the change logs are viewed by an admin, Then an entry shows timestamp, meeting type, role, previous defaults, new defaults, metrics summary, cohort size, confidence, and approver (system or admin). Given a rollback is initiated within 30 days, When executed, Then defaults revert to the previous values and a rollback log entry is recorded. Given impacted users next schedule a meeting of the affected type, When the new defaults are in effect, Then they see an in-app notice summarizing the change with a link to details. Given cohort size is below k or confidence is insufficient, When evaluation runs, Then no change is applied and a "criteria not met" entry is recorded.

Graceful Overrides

Enables controlled exceptions with reason codes and time‑bound waivers. If an override is necessary, the system suggests compensation (swap ownership, extend future buffer, grant make‑up focus time) and updates equity metrics—keeping urgency possible without normalizing violations.

Requirements

Override Request Flow with Time-Bound Waivers

"As a PM scheduling a critical cross-timezone meeting, I want to request a one-time waiver with a reason and end date so that we can meet urgently without permanently relaxing our team’s ergonomics."

Description

Provide a guided, in-context flow to request an override whenever a proposed meeting violates ergonomic constraints (e.g., outside comfort hours, insufficient buffer). The flow captures a mandatory reason code, scope (single meeting vs. window), waiver start/end, and optional notes; annotates the proposed event; and previews downstream effects. On approval, TimeMeld applies the waiver only within the specified window, auto-expires it, and restores normal constraints. The flow integrates with the scheduling engine, calendar connectors, and policy services, supports one-click initiation from conflict banners, and fails safely when required inputs or permissions are missing.

Acceptance Criteria

One-Click Override Flow Launch from Conflict Banner

Given a proposed meeting violates ergonomic constraints and displays a conflict banner When the user clicks "Request Override" Then the override form opens in-context within 1 second with meeting details prefilled (attendees, proposed time, violating rule) Given the form is opened from the banner When it renders Then scope defaults to "This meeting only" and the violating constraint is highlighted Given the form is open When the user cancels Then no changes are persisted and the conflict banner remains visible

Mandatory Reason Code and Time-Bound Waiver Inputs Validation

Given the override form is open When the user attempts to submit without selecting a reason code Then submission is blocked with an inline error "Reason code is required" Given the override form is open When scope "Time window" is selected Then start_at and end_at fields become required and are shown in the requestor's primary timezone Given start_at and end_at are entered When validation runs Then start_at <= end_at, the window length does not exceed the organization-configured maximum, and both times align to minute precision Given all required inputs are valid When the user submits Then the payload includes reason_code, scope, start_at, end_at, optional notes, and requestor_id

Downstream Effects Preview and Compensation Selection

Given required inputs are valid When the user clicks "Preview effects" Then the system displays projected equity impact, suggested compensation options (swap ownership, extend future buffer, grant make-up focus time) with computed values, impacted attendees, and waiver expiry within 2 seconds Given a compensation option is selected When the user proceeds to submit Then the selection is persisted and included in the request payload Given the preview is shown When the inputs change Then the preview recalculates within 1 second and indicates the last refresh time

Waiver Approval, Scope Enforcement, and Auto-Expiry

Given a request is approved by policy services When the scheduling engine re-evaluates the meeting Then the violating constraint is bypassed only within the specified scope/window, and all other constraints remain enforced Given end_at is reached When subsequent scheduling occurs Then the waiver no longer applies and normal constraints are restored automatically without user action Given multiple waivers exist When evaluating a meeting time Then the system applies a waiver only if at least one active waiver covers the meeting time and records the applied waiver IDs in the audit trail

Event Annotation in Calendar and Audit Logging

Given a waiver is approved and applied to an event When viewing the event in TimeMeld Then the event shows a "Waiver" badge with reason code and expiry for users with view permission Given a connected calendar integration is enabled When the invitation/update is sent Then the calendar description includes a standardized annotation with reason code, approver, and expiry timestamp Given any waiver lifecycle event occurs (request, approve, deny, expire) When it is processed Then an immutable audit record is created with timestamp, actor, fields changed, and related event ID

Fail-Safe Handling for Permissions and Service Failures

Given the requestor lacks override permission When attempting to submit an override Then submission is blocked with "Insufficient permissions" and no waiver is created Given a downstream service (calendar connector or policy service) is unavailable or returns an error When submitting or applying a waiver Then the system rolls back partial changes, shows an error with a correlation ID, and leaves scheduling unchanged unless an existing valid waiver covers the time Given a transient network interruption occurs while filling the form When connectivity is restored within 30 seconds Then the form state is recovered from local cache and the user can safely resubmit

Configurable Reason Codes & Policy Catalog

"As a workspace admin, I want to configure standard reason codes and approval rules so that overrides are consistent, auditable, and aligned with company policy."

Description

Deliver an admin-managed catalog of override reason codes with metadata: name, description, category, default duration limits, required approvals, and compensation presets. Policies define which roles/teams can use each code, maximum frequency, and visibility rules. Include versioning with effective dates, auditability of changes, and safe migrations so existing waivers map to the correct policy version. Expose a lightweight API for programmatic maintenance and enable localization for names/descriptions.

Acceptance Criteria

Create reason code with required metadata

Given I am an Org Admin with Manage Policies permission When I create a reason code with name, description, category, defaultDurationLimit (minutes), requiredApprovals, and compensationPresets Then the reason code is persisted with a unique ID And name is unique within the tenant (case-insensitive) And defaultDurationLimit is between 5 and 720 inclusive And requiredApprovals include only allowed approver roles And compensationPresets types are limited to {swap_ownership, extend_future_buffer, grant_focus_time} with positive numeric values And invalid payloads return 422 with field-level errors

Enforce policy roles, team scope, frequency, and visibility

Given a policy grants reason code RC1 to roles Product Manager and team Core Platform with maxFrequency 2 per person per rolling 30 days and visibility restricted When a user outside the permitted roles or teams attempts to view or select RC1 Then RC1 is not shown in the picker and API selection attempts return 403 When an eligible user has already used RC1 twice in the last 30 days Then selection is blocked with an error that includes the next eligible date And if alternative codes are configured, the UI presents them

Apply correct policy version by effective date

Given reason code RC1 has version v1 effective 2025-09-01 and version v2 effective 2025-10-01 When a waiver is created on 2025-09-15 Then v1 terms are applied and the waiver stores a reference to v1 When a waiver is created on or after 2025-10-01 Then v2 terms are applied And editing an existing waiver never changes its stored version And deprecating a version does not alter existing waivers And retrieving the policy as-of any timestamp returns the correct version

Audit trail for catalog and policy changes

Given audit logging is enabled When any reason code or policy is created, updated, versioned, published, or deprecated Then an immutable audit record is written with actor, timestamp, entity, version, and field-level diffs And audit records are queryable by entity, actor, and date range, and exportable as CSV And attempts to modify or delete audit records are rejected

Safe migration mapping for existing waivers on policy update

Given active waivers exist for RC1 under policy version v1 When an admin publishes version v2 that changes requiredApprovals and maxFrequency Then all existing waivers retain their v1 linkage and remain valid And a migration report lists counts by outcome (retained, conflicts, invalid references) And any conflicts are flagged for follow-up without blocking current waivers And designated admins receive a notification with a link to the migration report

Lightweight API with auth, idempotency, and concurrency controls

Given a valid OAuth2 access token with scope policy:write When a client POSTs a new reason code with an Idempotency-Key header Then the operation is idempotent for 24 hours and returns 201 with the created resource When a client PATCHes a policy version with an If-Match ETag Then requests with a stale or missing ETag return 412 And unauthenticated requests return 401 and unauthorized scopes return 403 And the API enforces 100 requests per minute per client with 429 on excess And the 99th percentile latency for GET /reason-codes and GET /policies is under 500 ms measured over 5 minutes

Localization of names/descriptions with fallback

Given the default locale is en-US and translations exist for fr-FR and es-ES When the UI or API is requested with Accept-Language: fr-FR Then reason code name and description are returned in French; otherwise they fall back to en-US And admins can add, update, and delete locale-specific strings without changing the base code ID And missing translations are listed in an exportable gaps report And name length is <= 120 characters and description length is <= 500 characters and both accept UTF-8 characters

Approval Workflow & Multi-Channel Notifications

"As a meeting owner, I want to receive and act on override requests with clear context and deadlines so that I can balance urgency with team well-being."

Description

Implement flexible approval routing based on policy (e.g., meeting owner, team lead, or on-call approver) with SLA timers and escalation paths. Provide actionable notifications in-app, email, and Slack with one-click approve/deny and required rationale on denial. Surface full context (reason code, waiver duration, affected participants, ergonomic impact) and reflect decision state in real time across TimeMeld and calendar annotations. Persist approval outcomes with timestamps and approver identity.

Acceptance Criteria

Policy-Based Approval Routing Selection

Given an override request with a policy requiring approval by the meeting owner or, if unavailable, the team lead, and otherwise the on-call approver When the request is submitted Then the system routes the approval request to the first available approver per policy and records the selected approver and policy path And if the primary approver has an out-of-office event overlapping the waiver window, the system skips to the next approver in the policy And the routed approver count and identities are visible in the request details And no more than one active approver is assigned at a time unless the policy explicitly requires multiple approvers

SLA Timers and Escalation Path

Given an approval request with a 30-minute SLA and an escalation path to the team lead When the SLA timer starts at submission time Then the timer is visible to requester and approver with remaining time And if no action is taken by SLA expiry, the request auto-escalates to the team lead and the original approver is notified And all SLA start, pause (if any), expiry, and escalation events are timestamped and stored And if the escalated approver acts, the timer stops and logs the approver who acted

Multi-Channel Actionable Notifications

Given an approval request is created When notifications are dispatched Then the requester and current approver receive actionable notifications in-app, by email, and via Slack within 15 seconds And each channel presents Approve and Deny actions as one-click options And actions taken from any channel update the request exactly once (idempotent) and reflect in all channels within 10 seconds And notification delivery status (sent/succeeded/failed) is logged per channel

Denial Requires Rationale

Given an approver chooses to deny an override request When the approver initiates the Deny action from in-app, email, or Slack Then the system requires a rationale entry before submission And denial cannot be completed without at least 10 characters of rationale And the rationale is stored with timestamp and approver identity and shown to the requester in the request details And the requester receives a denial notification including the rationale summary

Context Visibility in Approval UI

Given an approver opens the approval notification or modal When the approval view is rendered Then it displays reason code, waiver start/end time, affected participants list, ergonomic impact score and highlights, and proposed compensation options And links to the impacted calendar event and participant time zones are available And all values match the underlying request payload and policy at time of render

Real-Time Decision State Sync and Calendar Annotation

Given an approval decision (approve or deny) is recorded When the decision is saved Then the request status updates across TimeMeld UI for requester and approver within 10 seconds And the associated calendar event gains or updates an annotation reflecting Approved/Denied, approver identity, and timestamp And equity metrics and meeting ownership rotation are recalculated if approved and visible on the scoreboard within 60 seconds And stale notifications are marked resolved across all channels

Audit Trail Persistence and Queryability

Given any approval lifecycle event occurs (submission, reroute, approve, deny, SLA escalation) When the event is stored Then the audit record includes event type, timestamp (UTC), actor identity, channel of action, policy version, and request ID And records are immutable and retrievable by request ID and date range via admin audit view And export to CSV includes all fields with consistent headers

Compensation Suggestion Engine

"As a team lead, I want the system to suggest fair compensation options when an override is used so that the burden is distributed and focus time is protected."

Description

When an override is proposed or approved, compute ergonomic debt and generate ranked compensation options such as rotating meeting ownership, extending future quiet-time buffers, or scheduling make-up focus blocks. Show predicted equity impact and calendar feasibility, allow selection of one or more options, and apply them automatically on approval (including calendar updates and reminders). Provide policy hooks to require compensation for certain codes and guard against double-compensation.

Acceptance Criteria

Compute Ergonomic Debt on Override Proposal

Given an override is proposed or approved with a meetingId, scheduled datetime, participants, and a reason code When the Compensation Suggestion Engine is triggered Then it calculates an ergonomic debt score using the configured policy and current participant contexts And persists the score and inputs as an immutable record linked to the overrideId and meetingId And exposes the score via UI and API within 2 seconds And the computation is deterministic for identical inputs

Ranked Compensation Options Generation

Given an override has an ergonomic debt score When the engine generates compensation options Then it produces a ranked list including, if feasible, at least one option from each category: ownership swap, future quiet-time buffer extension, make-up focus block And each option includes a predicted equity delta (numeric), feasibility status, and earliest applicable time window And options are sorted by descending equity benefit, then feasibility score, then deterministic tiebreaker And if fewer than three options are feasible, the engine still returns all feasible options with rationale codes

Display Impact and Feasibility in Override Modal

Given compensation options have been generated for an override When a user opens the override modal Then each option displays the predicted equity delta, a feasibility indicator, and the earliest application window And hovering or expanding an option reveals conflict reasons, if any And the list order in the UI matches the engine’s ranking And values are updated in the UI within 2 seconds of any input change

Multi-Select Compensation With Compatibility Validation

Given the user is viewing suggested compensation options for an override When the user selects one or more options Then the system validates compatibility rules and prevents mutually exclusive combinations with an explanatory message And it displays a combined compensation preview showing total predicted equity delta and affected calendars And the Confirm button remains disabled until validation passes

Automatic Application on Approval

Given the user has selected valid compensation options and approves the override When the approval action is submitted Then the system applies all selected options atomically: updates equity metrics, creates/updates calendar events/blocks/invites, and schedules reminders And all calendar changes are reflected on participants’ calendars within 10 seconds And the operation is idempotent on retried submissions and emits a single audit log entry And on partial failure, no changes persist and a clear error is surfaced with retry guidance

Policy Hooks Enforcing Required Compensation by Reason Code

Given a reason code is configured as requiring compensation with a minimum equity delta or specific option types When a user attempts to approve an override without satisfying the configured policy Then approval is blocked with a message specifying unmet requirements and suggested options to satisfy them And when the policy is updated via the admin API, enforcement reflects the new configuration on the next evaluation without service restart

Double-Compensation Guard and Deduplication

Given an override for a meetingId already has compensation applied or scheduled When a new override is proposed for the same meetingId or overlapping participant/time window within the configured deduplication horizon Then the engine excludes already-applied compensation from suggestions and prevents double counting toward equity metrics And attempts to reapply the same option are blocked with a clear deduplication message And idempotent retries of the same approval do not create duplicate calendar items or equity updates

Equity Scoreboard Adjustment & Visibility

"As a team member, I want the equity scoreboard to reflect overrides and compensations so that I can see that late/early burdens are tracked and rotated fairly."

Description

Extend the shared equity scoreboard to account for overrides and applied compensations, updating fairness metrics (e.g., off-hours load, ownership rotation, buffer integrity) at individual and team levels. Display clear annotations for override-driven changes, include filters by time range, reason code, and team, and prevent gaming via caps and normalization rules. Provide drill-down to the underlying events and expose read APIs for BI tools.

Acceptance Criteria

Override Adjustments Reflected in Equity Scoreboard Within 5 Minutes

- Given a user applies an override with a valid reason code and selected compensation, When the override is saved, Then the individual and team fairness metrics (off-hours load, ownership rotation, buffer integrity) are recalculated and visible on the equity scoreboard within 5 minutes (p95). - Given the same override event is processed more than once, When recalculation runs, Then metrics remain consistent and are not double-counted (idempotent). - Given the recalculation fails, When the user views the scoreboard, Then a non-blocking "pending recompute" indicator appears with last computed timestamp and the system retries within 1 minute until success. - Given an audit log is requested, When the override ID is queried, Then the audit log shows previous metric values, new values, compute time, and the actor ID.

Annotated Scoreboard Entries for Overrides and Compensations

- Given a scoreboard row affected by an override, When the row renders, Then an annotation badge is displayed with reason code, waiver window, compensation type(s), actor, and timestamp via tooltip and accessible label. - Given a user toggles "Show override annotations" off, When the scoreboard renders, Then annotations are hidden without affecting metric values. - Given the scoreboard is exported (CSV) or fetched via API, When the affected rows are included, Then annotation fields are present (override_id, reason_code, compensation_types, waived_until). - Given multiple compensations are attached to a single override, When the annotation is displayed, Then all compensation types are listed and totals are correctly reflected.

Filter Scoreboard by Time Range, Reason Code, and Team

- Given a user selects a custom date range, reason code(s), and team(s), When Apply Filters is clicked, Then the scoreboard results reflect the intersection of all selected filters and the summary totals match the filtered set. - Given no results match the selected filters, When the scoreboard loads, Then an empty state is shown and exports return an empty dataset with headers only. - Given a dataset of up to 5,000 events in the filtered range, When the scoreboard loads, Then first render completes within 2 seconds on a median laptop over a standard broadband connection. - Given browser refresh, When returning to the scoreboard, Then the last-used filters persist for the user.

Caps and Normalization Prevent Gaming Behavior

- Given an individual accumulates compensation credits from overrides, When credits exceed 2 units in a rolling 30-day window, Then further credits are capped and the scoreboard displays a capped indicator with the overage amount. - Given a single override would increase off-hours load contribution beyond 2x the team median for the selected period, When metrics are computed, Then the contribution is winsorized to 2x and an annotation indicates normalization applied. - Given a user triggers more than 3 convenience overrides within 14 days, When compensation would normally be awarded, Then the compensation is withheld and the event is flagged for review with a visible note on the scoreboard. - Given an admin updates cap and normalization thresholds, When saved, Then changes are applied to subsequent recomputes and the change is written to the audit log with effective timestamp.

Drill-Down from Scoreboard to Underlying Events

- Given a user clicks an individual's score, When the drill-down panel opens, Then it lists underlying events with columns: event_id, datetime (with timezone), reason_code, compensation, ownership, and impact deltas. - Given more than 50 events match, When the panel loads, Then results are paginated (50 per page) with sortable columns and search by event_id. - Given the user has Viewer permissions, When opening the drill-down, Then personal calendar details are redacted; with Admin permissions, full details are shown. - Given the user clicks "Export events", When the file is generated, Then the CSV contains exactly the events in the current filtered view within 10 seconds.

Read API Provides Equity Metrics and Annotations for BI Tools

- Given a BI tool issues GET /equity/scoreboard with team, date_range, and reason_code parameters, When the request is authorized, Then the response includes aggregate metrics and per-user rows with annotations (override_id, reason_code, compensation_types) in a documented schema (OpenAPI) and HTTP 200. - Given a client provides If-None-Match with the last ETag, When no data has changed, Then the API returns HTTP 304 within 500 ms. - Given a large result set (>10,000 rows), When the client uses cursor-based pagination (cursor, limit), Then each page returns within 1 second with a next_cursor until completion. - Given invalid parameters or unauthorized access, When the request is processed, Then the API returns appropriate errors (400, 401, 403, 429) with machine-readable error codes.

Override Limits, Cooldowns, and Guardrails

"As an ops manager, I want limits and cooldowns on overrides so that urgent exceptions don’t become the norm."

Description

Enforce policy-defined ceilings for overrides per user/team per timeframe, with warning thresholds and cooldowns. Offer soft blocks with justification prompts and hard blocks for non-exempt roles or exceeded limits, with admin override capability. Provide real-time feedback during scheduling, summarize current quota usage, and surface trends to admins to identify hotspots and policy tuning opportunities.

Acceptance Criteria

Per-User Rolling Quota With Warning Threshold

Given tenant policy: user_override_limit=5 per rolling_30_days and warning_threshold=80% And user U has used 3 overrides in the last rolling_30_days When U initiates an override in the scheduler Then the override is permitted And the UI shows "2 remaining (60% used)" with no warning banner And an audit event "override_attempt" is recorded with used=3, limit=5, threshold_crossed=false Given tenant policy: user_override_limit=5 per rolling_30_days and warning_threshold=80% And user U has used 4 overrides in the last rolling_30_days When U initiates an override in the scheduler Then the override is permitted And a non-blocking warning "Override quota nearly reached" is shown And an audit event is recorded with used=4, limit=5, threshold_crossed=true Given tenant policy: user_override_limit=5 per rolling_30_days And user U has used 5 overrides in the last rolling_30_days When U initiates an override in the scheduler Then the scheduler transitions to guardrail_block state And the decision engine evaluates soft vs hard block based on role and exemptions

Per-Team Rolling Quota Enforcement

Given tenant policy: team_override_limit=20 per rolling_30_days and warning_threshold=75% And Team T has used 15 overrides in the last rolling_30_days When any member of Team T attempts an override Then the override is permitted And the team usage widget shows "5 remaining (75% used)" with a warning banner And an audit event records team_used=15, team_limit=20, team_threshold_crossed=true when usage >= 75% Given tenant policy: team_override_limit=20 per rolling_30_days And Team T has used 20 overrides in the last rolling_30_days When any member attempts an override Then the scheduler transitions to guardrail_block state And block reason includes "team_limit_reached"

Cooldown Between Overrides

Given tenant policy: user_cooldown=48h between overrides And user U completed an override 12h ago When U attempts another override Then a soft block modal is shown indicating "Cooldown 36h remaining" And proceeding requires selecting a reason code and submitting a justification And an audit event "cooldown_bypass_requested" is recorded with remaining_cooldown=36h Given tenant policy: user_cooldown=48h between overrides And user U completed an override 0h ago And role=non_exempt When U attempts another override Then a hard block is enforced with action disabled And message "Cooldown active (48h remaining). Contact admin for override." is displayed

Soft Block With Justification And Time-Bound Waiver

Given limit reached or cooldown active And role is exempt OR tenant policy allows soft_block_on_limit=true When the user attempts an override Then a modal requires: - selection of a reason_code from the configured list - entry of free-text justification (minimum 20 characters) - confirmation of waiver_expiry within policy bounds (<= 7 days) And the modal displays at least one compensation suggestion (swap ownership, extend buffer, make-up focus time) with a preselected default And on submit, the override is scheduled And the audit log stores reason_code, justification_hash, waiver_expiry, selected_compensation And equity metrics are updated per selected compensation

Hard Block For Non-Exempt Or Exceeded Without Waiver

Given user or team limit is exceeded OR cooldown is active And role=non_exempt When the user attempts an override Then scheduling actions to confirm override are disabled And a hard block banner explains the violated guardrail and next steps And a "Request admin override" control is available And no meeting is scheduled until an admin approves

Admin Override Capability And Auditability

Given a hard block has been triggered for an override attempt And an admin with override_permission opens the request When the admin approves with a reason_code, waiver_expiry within policy bounds, and a selected compensation option Then the override is scheduled immediately And user/team counters are updated according to policy (counted_with_waiver=true) And equity metrics update is applied And a complete audit trail is recorded including approver_id, timestamp, prior_usage, post_usage, and policy_snapshot And the affected user receives a notification summarizing the override and compensation

Real-Time Feedback And Admin Insights

Given the scheduler is open for a user in a tenant When the user selects a time that requires an override OR toggles "Require override" Then the quota usage panel updates within 300 ms to show: user used/limit/remaining/percent, team used/limit/remaining/percent, cooldown remaining, and block state (none/warning/soft/hard) And all values reflect the latest persisted events within 1 second of any new override action Given an admin opens the Override Insights dashboard When data loads Then the dashboard shows: top 10 users and teams by override rate (last 30 days), trend of overrides per day with soft vs hard breakdown, distribution by reason_code, hotspots where warning_threshold crossed > N times/week (configurable), and CSV export control And data freshness is no older than 15 minutes

Audit Trail & Compliance Exports

"As a compliance officer, I want a complete audit log of overrides and approvals with export capabilities so that we can satisfy audits and internal reviews."

Description

Capture an immutable, searchable log of override lifecycle events (request, edits, approvals, expirations, compensations applied), including who, when, what changed, policy version, and communication artifacts. Support scoped access via RBAC, retention controls, and PII minimization. Provide CSV/JSON exports and signed webhooks for SIEM/BI ingestion, enabling SOC 2–friendly evidence collection and incident postmortems.

Acceptance Criteria

Immutable Override Lifecycle Audit Logging

Given an override lifecycle action (request, edit, approve, expire, compensation-apply) is committed When the operation completes Then an append-only audit event is written with fields: event_id (ULID), event_type, override_id, actor_user_id, actor_role, affected_user_ids, timestamp_utc (ISO 8601), policy_version_id, change_diff (JSON Patch), reason_code, communication_artifact_refs[], request_id, source_ip, user_agent, event_hash, prev_event_hash Given an audit event exists When any update or delete of that event is attempted via API, UI, or database interfaces Then the mutation is rejected, no original data is altered, and a tamper_attempt event is recorded with actor_user_id and context Given a sequence of K lifecycle actions for override_id=X When querying audit events by override_id=X Then exactly K events are returned in ascending timestamp order and the hash chain validates end-to-end Given storage corruption or a hash mismatch is detected When the affected event is read Then integrity_status=failed is returned, the event is excluded from default exports, and an alert is sent to org admins within 5 minutes

Audit Log Search, Filtering, and Latency

Given a user with permission View Audit Logs submits a query filtered by date range (<= 90 days), event_type, actor_user_id, override_id, reason_code, and policy_version_id When the query executes over up to 10,000 matching events Then the first page of results (page_size<=100) returns within 2 seconds and includes total_count, page, page_size Given a query contains no matches When executed Then 200 OK is returned with an empty results set and total_count=0 Given a result row is returned When inspected Then it includes all required fields and omits masked PII fields by default (see PII policy) Given a sort order is specified (timestamp_utc asc|desc) When the query executes Then results are deterministically ordered and stable across repeated queries with the same parameters

RBAC-Scoped Access and PII Minimization

Given a user with Role=Org Auditor When accessing audit logs Then they can view events for their organization scope with actor_user_id and affected_user_ids displayed as stable IDs; emails and full names are redacted unless the View PII permission is granted Given a user with Role=Team Lead When accessing audit logs Then they can only view events for teams they manage and cannot view communication content bodies—only artifact references (e.g., message URLs, message_ids) Given a user without scope to an event When attempting access Then access is denied with HTTP 403 (or UI equivalent), and a denied_access audit event is recorded Given PII minimization is enabled by default When events are stored Then direct PII values (emails, phone numbers, message bodies, meeting descriptions) are not stored in cleartext; emails are stored as salted hashes, message bodies are not stored—only references; exports and webhooks inherit the same masking rules unless View PII is granted

Retention Policy and Legal Hold Controls

Given an org-level retention policy is set between 30 and 1825 days (inclusive) When an event ages beyond the configured retention period Then it is purged from hot storage within 24 hours and excluded from searches, exports, and webhooks Given a legal hold is placed on an override_id, actor_user_id, or date range When retention would otherwise purge matching events Then those events are retained until the hold is released; all hold create/release actions are themselves auditable events Given an event is purged When reconciliation is performed Then a non-PII tombstone record (event_id, purge_timestamp, purge_reason) remains for 90 days to support audit counts without revealing content

CSV/JSON Export Integrity and Schema Compliance

Given a user with permission Export Audit Logs requests an export (CSV or JSON) with filters (date range <= 90 days, event_types, actor_user_id, policy_version_id) When the export is generated for up to 1,000,000 events Then a file is produced within 5 minutes, available via a signed URL expiring in 24 hours, and includes a manifest (export_id, schema_version, generated_at_utc, record_count, SHA256 checksum) Given a CSV export is downloaded When inspected Then it is UTF-8 encoded with a header row matching the documented schema, uses RFC 4180 quoting, and has exactly record_count data rows Given a JSON export is downloaded When inspected Then it is newline-delimited JSON (NDJSON) with each object conforming to schema_version; the manifest checksum matches the file content Given the same export parameters are used again without new events When a new export is requested Then the record_count and checksum are identical, and rows are sorted by timestamp_utc asc

Signed Webhook Delivery for SIEM/BI Ingestion

Given a webhook destination is configured with endpoint URL and shared secret When a new audit event is created Then a POST is sent within 5 seconds containing the event JSON body and headers X-TimeMeld-Timestamp and X-TimeMeld-Signature (HMAC-SHA256 over timestamp||payload); the event includes an Idempotency-Key header Given the destination responds with HTTP 2xx When processing Then the delivery is marked delivered and no retries occur Given the destination responds with 5xx or times out in 10 seconds When processing Then retries are attempted with exponential backoff and jitter up to 10 times over 24 hours (at-least-once delivery); duplicate deliveries carry the same Idempotency-Key Given a secret rotation is initiated When webhooks are sent during the rotation window Then signatures using either old or new secret are accepted for 1 hour, and a test delivery endpoint verifies signatures on demand Given repeated 4xx errors (>=10 within 10 minutes) When monitoring Then the endpoint is auto-disabled and an alert is sent to org admins

SOC 2 Evidence Pack and Timeline Reconstruction

Given an auditor requests an evidence pack for period [start, end] When generation is initiated Then the pack includes: export manifest (hashes, counts), RBAC configuration snapshot, retention policy snapshot, webhook delivery summary (success/failure counts, retry logs), and 30 randomly sampled override audit trails with full lifecycle coverage; the pack is delivered as a ZIP with a signed manifest (SHA256) within 10 minutes Given an evidence pack is provided When validation is performed Then every sampled trail contains the required lifecycle events (request, approval/denial, edits, expiration, compensation), each with integrity-verified hash links and policy_version_id present Given evidence generation detects missing or corrupt records When assembling the pack Then generation fails atomically with a detailed error report; no partial pack is released; an alert is sent to org admins Given a pack is generated successfully When accessed Then it is retrievable via a one-time URL valid for 7 days and retained under legal hold for 30 days

Drift Radar

Surfaces attempted and actual guard breaches by team, timezone, and hour. Sends early alerts when risk rises and recommends schedule or policy tweaks to realign, so maker hours stay intact as calendars and priorities evolve.

Requirements

Guard Breach Detection Engine

"As an ops lead, I want accurate detection of attempted and actual guard breaches across timezones so that I can quantify drift and intervene before focus time erodes."

Description

Implements a unified guard policy model (maker hours, no‑meeting windows, meeting caps, working hours, and per‑team exceptions) and a detection pipeline that ingests scheduled events and proposed invites. Normalizes all timestamps to participant local timezones, classifies events as attempted vs. actual breaches, assigns severity and reason codes, and persists results for analytics. Supports near‑real‑time processing, idempotent replays, backfill from calendar history, and performance at org scale.

Acceptance Criteria

Timezone Normalization for Multi‑Participant Events

Given a scheduled event or proposed invite with attendees across at least two IANA timezones (including one with DST and one with a 30/45‑minute offset) When the event is ingested by the detection engine Then start and end times are computed per participant’s local timezone using the correct tz rules effective at the event time And guard evaluation uses the participant’s local calendar day and working hours And events crossing local midnight are evaluated against the correct day’s policies on both sides And events on DST transition days (skipped or repeated hours) retain the intended wall‑clock time without off‑by‑one‑hour errors And the persisted record includes UTC timestamps plus per‑participant local timestamps and tzid

Attempted vs. Actual Guard Breach Classification

Given a proposed invite not yet added to participants’ calendars that violates any guard for any participant When processed Then it is classified as Attempted with the violating participants and guard types recorded Given a calendar event with status confirmed/accepted that violates any guard When processed Then it is classified as Actual with the violating participants and guard types recorded Given an event or invite is cancelled or withdrawn When processed Then any open breach records for its (event_id, sequence) are marked resolved and excluded from active analytics

Policy Precedence and Per‑Team Exception Handling

Given org‑level guard policies and a team‑level exception for a participant When evaluating a time window Then the exception overrides the org default for that participant and guard type And evaluation order is: team exception > team policy > org policy; first match applies And a breach is recorded if any applicable guard is violated for a participant unless an explicit exception exempts that guard for the evaluated time window And policy version effective_at timestamps are honored so historical events use the policy version in force at the event time

Severity and Reason Code Assignment

Given one or more violated guards for an event or invite When assigning severity Then severity is determined by the highest applicable rule across all violations and participants: - S1 Critical: any no‑meeting window violation OR maker‑hours overlap ≥ 30 minutes for any participant - S2 High: maker‑hours overlap > 0 and < 30 minutes OR daily meeting cap exceeded by ≥ 2 for any participant - S3 Medium: daily meeting cap exceeded by 1 OR working‑hours violation > 30 minutes outside maker hours - S4 Low: working‑hours violation ≤ 30 minutes outside maker hours And each violation includes at least one machine‑readable reason code from {G01_MAKER_HOURS, G02_NO_MEETING_WINDOW, G03_MEETING_CAP, G04_WORKING_HOURS} and a human‑readable message And the persisted record lists impacted participants, per‑participant overlaps in minutes, and the final severity level

Streaming Processing Guarantees (Latency & Idempotence)

Given creation, update, or cancellation events arriving from calendars and invite proposals When processed under steady‑state load of 500 events/second system‑wide (≤ 20 events/second per org) Then end‑to‑end detection latency (ingest to persisted breach record) is p95 ≤ 2s and p99 ≤ 5s with error rate < 0.1% Given duplicate deliveries or replays of the same event identified by (event_id, sequence) When processed any number of times in any order Then exactly one breach record exists per unique (event_id, sequence, participant, guard_type); later higher sequence supersedes earlier; equal/lower sequences are deduplicated without changing outcomes And all operations are retriable without side effects (idempotent) and carry a stable correlation_id for traceability

Historical Backfill Accuracy and Completeness

Given a backfill request for a time range (e.g., past 90 days) for an org When executed Then 100% of calendar events in scope are evaluated and breach records are produced consistent with the policy versions effective at each event time And backfill is partitioned to support at least 50,000 users and 30M events with progress checkpoints and restartable jobs And the engine produces identical results between backfill and streaming for the same events (hash equality on normalized breach payloads)

Result Persistence and Queryability

Given a detected breach (attempted or actual) When persisted Then the record includes: org_id, team_id (if available), event_id, sequence, participant_id, attempted_or_actual, violated_guard_types[], reason_codes[], severity, utc_start/end, local_start/end, tzid, overlap_minutes_by_participant, detection_timestamp, policy_version, processing_version, correlation_id, and resolution_status And querying breaches grouped by team, timezone, and hour for the last 30 days completes in p95 ≤ 200 ms for orgs up to 5,000 users and 5M breach records with correct aggregates And soft‑deleted/resolved breaches are excluded from active analytics and retained for at least 400 days for audit

Timezone Heatmap & Drilldowns

"As a product manager, I want to see where guard breaches cluster by timezone and team so that I can target fixes where they matter most."

Description

Provides an interactive dashboard that visualizes breach density by hour and timezone with side‑by‑side attempted vs. actual counts. Offers filters for team, meeting type, severity, date range, and organizer, plus trend lines and week‑over‑week deltas. Enables drill‑down to affected meetings and participants, exports (CSV/JSON), and an analytics API endpoint. Optimized for fast loading and accessibility (keyboard nav, color‑safe palette).

Acceptance Criteria

Heatmap Side-by-Side Attempted vs Actual by Timezone and Hour

Given a user opens Drift Radar > Timezone Heatmap with a populated dataset for the selected date range, When the page loads, Then a 24xN grid renders where N equals the distinct timezones in scope, with each hour/timezone showing Attempted and Actual breach densities side-by-side with clear labels. Given the default view, When the user hovers or focuses a cell, Then a tooltip or focus detail shows timezone, hour (local), attempted count, actual count, and top severity for that cell. Given the selected date range and filters, When totals are computed, Then the sum of all cell attempted counts equals the backend attempted total and the sum of actual counts equals the backend actual total for the same scope with no discrepancy. Given a user toggles the time base between Local and UTC, When toggled, Then hour labels and cell mappings update accordingly without altering total attempted/actual counts.

Filter Combination Updates Visualization and Metrics

Given filters for team, meeting type, severity, date range, and organizer, When the user applies any combination (including multi-select), Then the heatmap, side-by-side counts, totals, and trends update to reflect only the filtered scope. Given filters are applied, When the page reloads or a shareable link is opened, Then the selected filters are restored via URL parameters and the view matches the saved state. Given a filter yields no results, When applied, Then an informative empty state appears and all totals/exports/API responses reflect zero results for the same scope. Given filters are cleared, When the user selects Reset, Then the view returns to the default unfiltered state and URL parameters are cleared.

Drill-Down from Heatmap Cell to Meeting and Participant Details

Given a user clicks or presses Enter on a heatmap cell, When activated, Then a drill-down panel opens listing affected meetings grouped by Attempted and Actual with columns: Meeting ID/Title, Organizer, Participants count, Time (local and UTC), Timezone, Severity, Meeting Type. Given the drill-down list, When the user sorts by any column, Then results reorder correctly and the sort state persists until changed. Given more than 50 results, When displayed, Then results are paginated (50 per page by default) and page controls navigate correctly without losing the applied filters or grouping. Given a listed meeting, When clicked, Then the meeting detail opens in a drawer or new tab per spec, and closing it returns the user to the same drill-down state and scroll position.

Trend Lines and Week-over-Week Delta Accuracy

Given the Trend section is visible for the current filters and date range, When loaded, Then it displays attempted and actual breach trend lines with weekly aggregation and a week-over-week delta (absolute and percent) for the most recent complete week. Given filters or date range change, When applied, Then trend lines and deltas recompute to match the new scope and the timestamp of last refresh updates. Given a backend reference dataset for the same scope, When comparing values, Then trend point totals and deltas match backend calculations within rounding to one decimal place.

Data Export and API Delivery of Current View

Given the current view (heatmap aggregate or drill-down details) and filters, When the user selects Export CSV, Then a file downloads within 5 seconds containing only data for the current scope and level of detail with a header row and fields appropriate to the view; for heatmap: timezone, hour, attempted_count, actual_count, top_severity, date_range, filters_metadata; for drill-down: meeting_id, title, organizer_id, participants_count, timezone, start_time_utc, start_time_local, severity, meeting_type, attempted_or_actual. Given the current view and filters, When the user selects Export JSON, Then a JSON file downloads within 5 seconds using the documented schema and matching row counts to the CSV for the same scope. Given a valid API token, When a GET request is made to /api/analytics/heatmap with query params team[], meeting_type[], severity[], organizer_id[], tz[], start, end, granularity=hour, Then the API returns 200 with attempted and actual counts per timezone-hour and a trends object; unauthorized requests return 401. Given a request within documented limits (e.g., date range ≤ 90 days, ≤ 100 teams), When executed, Then the API responds within 1.5s p95 and 500ms p50 and returns totals consistent with the UI for identical filters.

Performance and Load Time Targets

Given a dataset with up to 200 timezones and 12 months of data, When the dashboard initial load occurs on a standard network (≥50 Mbps) and mid-tier laptop, Then first contentful paint ≤ 1.5s and interactive heatmap render ≤ 2.5s p50 and ≤ 4.0s p95. Given a filter change or drill-down open, When executed, Then visual update latency (from action to rendered state) is ≤ 300ms p50 and ≤ 700ms p95, with a skeleton/loading state shown if rendering exceeds 200ms. Given an export of up to 100,000 rows, When requested, Then the file begins download within 10 seconds or a background job link is provided within 3 seconds with an email/download notification. Given API queries within documented limits, When executed under normal load, Then p95 latency ≤ 1.5s and 24-hour error rate < 0.5%.

Accessibility and Keyboard Navigation Compliance

Given only a keyboard, When navigating the dashboard, Then all interactive elements (filters, toggles, heatmap cells, drill-down controls, export buttons) are reachable in a logical tab order with visible focus indicators and Escape closes modals/drawers returning focus to the invoking element. Given a screen reader (NVDA/JAWS/VoiceOver), When reading the heatmap, Then each cell exposes an accessible name announcing timezone, hour, attempted count, actual count, and severity using appropriate ARIA roles and labels for actionable cells. Given the color-safe palette, When evaluated against WCAG 2.1, Then non-text contrast for critical states and adjacent density swatches meets AA and color is not the sole means of conveying severity (pattern or icon used in addition to color). Given a user presses Enter or Space on a focused heatmap cell, When invoked, Then the same drill-down opens as mouse click and focus is trapped within the drawer until dismissed, after which focus returns to the originating cell.

Early Risk Scoring & Forecasting

"As an engineering manager, I want a forecast of upcoming breach risk so that we can adjust schedules before meetings land in maker hours."

Description

Calculates a forward‑looking risk index per team/timezone/hour for the next 14–30 days by combining invite pipeline signals, historical seasonality, on‑call rotations, PTO/holiday calendars, and release calendars. Uses heuristic or ML models with calibrated thresholds, confidence bands, and backtesting. Exposes scores to the dashboard and alerting system and supports configuration of risk appetite by team.

Acceptance Criteria

Generate 14–30 Day Risk Index by Team/Timezone/Hour

Given TimeMeld has active teams with historical calendar and guard-breach data When the forecast job runs on schedule Then it generates a risk index in the range [0,100] for every team×timezone×hour cell for each day in the next 21 days by default And it supports configuring the forecast horizon between 14 and 30 days And each forecasted point includes 80% and 95% confidence bands, a model_version, input_sources, and generated_at timestamps And all scores are refreshed at least nightly and within 60 minutes of material input changes

Ingest Multi-Source Signals with Fallback Handling

Given connectors for invite pipeline, historical seasonality, on-call rotations, PTO/holiday calendars, and release calendars are configured When the data ingestion job executes Then each source is updated with a maximum freshness lag of 4 hours and recorded with source_status and last_updated And if any source is unavailable or stale, forecasts are still produced using remaining sources with deterministic fallback weights and a degraded=true flag And all times are normalized to IANA timezones with DST adjustments verified by unit tests across at least 5 DST transition regions

Configure and Enforce Team Risk Appetite Thresholds

Given a team admin opens Risk Settings When they set a numeric risk appetite threshold between 0 and 100 and save Then the value is validated, persisted, audit-logged with actor, timestamp, old_value, and new_value And the threshold takes effect in dashboard coloring and alert triggers within 10 minutes And a default threshold of 60 is applied to teams without an explicit setting

Backtest Forecasts and Calibrate Confidence Bands

Given at least 90 days of historical attempted/actual guard-breach outcomes When nightly backtesting runs over a rolling 60-day window Then the model’s 80% confidence band covers 75%–85% of realized outcomes and the 95% band covers 92%–98% And the Brier score improves by at least 10% versus a seasonality-only baseline And precision and recall for high-risk alerts (above team threshold) each meet or exceed 0.60 over the last 30 days And if coverage deviates beyond ±5%, a calibration routine is triggered and a status alert is raised to ops

Expose Risk Scores and Confidence on Dashboard

Given an authorized user views Drift Radar When they filter by team, timezone, and date range up to 30 days Then the grid displays per-hour risk scores with 80%/95% confidence visualization, threshold markers, and a last_updated timestamp And hovering a cell reveals contributing factors with relative weights and source freshness And the view loads in under 2 seconds for 3 teams over 21 days on a standard broadband connection And all visual elements meet WCAG 2.1 AA color-contrast for risk states

Trigger Early Alerts with Recommendations

Given alerting channels (Slack and email) are configured for a team When any forecasted hour in the next 7 days is projected to exceed the team’s risk appetite threshold Then an early alert is sent with at least 24 hours lead time, including risk score, confidence band, top contributors, and recommended schedule/policy tweaks And alerts are deduplicated to at most one per team×hour per 24-hour period and support snooze durations of 1, 3, or 7 days And acknowledgments are recorded with actor and timestamp and stop further alerts for that instance And all alerts are logged and visible in an alert history view

Proactive Alerts & Routing

"As a team lead, I want concise, actionable alerts during work hours so that I can respond quickly without notification noise."

Description

Delivers early alerts when risk or breach thresholds are crossed via Slack, email, and in‑app notifications. Supports routing by team/role, quiet hours based on user timezone, digest vs. real‑time modes, deduplication, escalation rules, and per‑channel templates with actionable context (top drivers, impacted hours, quick links). Provides user‑level preferences and unsubscribe controls.

Acceptance Criteria

Digest vs Real-Time Delivery Configuration

- Given a user with delivery mode set to Real-Time and a Drift Radar risk or breach threshold is crossed, when the event is detected, then a notification is delivered to the user’s enabled channels within 60 seconds of detection. - Given a user with delivery mode set to Digest (daily) at a configured local time, when one or more qualifying events occur before the digest time, then a single digest is sent at the configured time containing a grouped summary by team, guard, and hour; and no real-time notifications are sent for those events. - Given a user changes delivery mode from Real-Time to Digest mid-day, when subsequent qualifying events occur, then those events are included only in the next digest and are not sent real-time; previously sent notifications remain unchanged. - Given an organization default delivery mode is set, when a user has no explicit preference, then the default is applied and reflected in audit logs.

Routing by Team and Role with Fallback

- Given routing rules exist mapping specific teams and roles to destinations (Slack channel, Email group, In‑app audience), when a qualifying event is raised for a matching team/role, then the alert is delivered only to the highest‑priority matching destination. - Given multiple routing rules could apply, when priorities are defined, then the rule with the highest priority is applied; when priorities are equal, then the most specific rule (team+role) is applied. - Given no routing rule matches an event, when the event is raised, then the alert is delivered to the organization default destination and the routing decision is recorded in logs. - Given a role‑based route (e.g., On‑call Engineer), when the current assignee list is resolved, then only active assignees receive the alert and resolution is logged for traceability.

Quiet Hours by User Timezone and Deferred Delivery

- Given a user has quiet hours configured (per weekday) in their profile timezone, when an alert targets that user during their quiet hours, then real‑time delivery to that user is suppressed and the alert is queued. - Given quiet hours end, when queued alerts exist for the user and their delivery mode is Real-Time, then a single bundled notification labeled “Deferred During Quiet Hours” is delivered within 5 minutes after quiet hours end, containing the suppressed items. - Given quiet hours end, when the user’s delivery mode is Digest, then suppressed items are included only in the next digest and not delivered immediately. - Given alerts are routed to shared team destinations (e.g., public Slack channels), when any member’s quiet hours are active, then quiet hours do not suppress delivery to the shared destination (quiet hours apply to individual recipients only). - Given a user profile lacks a timezone, when quiet hours are evaluated, then the organization default timezone is used and a warning is logged.

Alert Deduplication and Coalescing

- Given a deduplication key composed of {team_id, guard_id, hour_bucket, event_type(risk|breach), route_target}, when multiple qualifying events with the same key occur within a 15‑minute window, then only one real‑time notification is sent for that key to that target. - Given additional events are deduplicated, when the original notification supports updates (Slack or in‑app), then the original message is updated or threaded within 2 minutes to reflect the new count and latest context; when the channel is Email, then duplicates are suppressed and counts appear in the next digest. - Given the 15‑minute window elapses or the hour bucket changes, when a new event occurs, then a new notification may be sent. - Given deduplication suppresses a notification, when viewing audit logs, then suppression reason and counts are recorded for the event batch.

Escalation Rules and Acknowledgment Workflow

- Given an alert requires acknowledgment, when sent to the initial tier, then if no acknowledgment is received via supported actions (Slack button/link, in‑app action, email link) within 15 minutes of delivery, the alert escalates to the next configured tier; escalation stops when an acknowledgment is recorded or after the final tier. - Given the next tier recipient is in quiet hours, when escalation is triggered, then delivery is deferred until their quiet hours end and the escalation timer excludes deferred time from SLA measurement. - Given an alert is acknowledged at any tier, when escalation would otherwise trigger, then escalation is canceled and all recipients see the acknowledged status within 60 seconds. - Given an alert escalates, when delivered to the next tier, then the full actionable context and prior attempts/elapsed time are included in the message.

Per-Channel Templates with Actionable Context

- Given a Slack delivery, when an alert is sent, then the message includes: team, guard, event type (risk/breach), impacted hours in the recipient’s local time, top 3 drivers with percentages, and quick links to View Drift Radar, Propose Schedule Tweak, Adjust Policy, and Mute; all placeholders render with non‑empty values or safe defaults. - Given an Email delivery, when an alert is sent, then the subject follows: "[TimeMeld Drift Radar] {Team} {Guard} {Risk|Breach}", and the body includes the same context plus deep links with correct query parameters; links open to the filtered view. - Given an In‑app notification, when an alert is sent, then the notification panel displays the same context and links, and opens the detailed view within the app without a full page reload. - Given any channel template, when required data is unavailable, then default text is rendered and the send does not fail; the missing fields are logged for telemetry.

User-Level Preferences and Unsubscribe Controls

- Given a user opens Preferences, when they toggle channels (Slack DM, Email, In‑app), delivery mode (Real-Time vs Digest), and quiet hours, then changes persist immediately and are enforced on subsequent alerts. - Given a user clicks "Unsubscribe" in Email or sends "stop" as a DM command to the bot, when the request is confirmed, then all future Drift Radar alerts to that user are stopped within 1 minute and the change is auditable. - Given an unsubscribed user is part of a role route, when an alert targets that role, then the user is excluded from delivery while other role members still receive it. - Given a user re‑subscribes via Preferences or "start" command, when confirmed, then delivery resumes per their current settings.

Realignment Recommendations

"As a scheduler, I want concrete recommendations I can apply in one click so that I save time and protect maker hours."

Description

Generates prescriptive suggestions to reduce breach risk: shift recurring meeting windows, rebalance the equity scoreboard rotation, auto‑insert protected focus blocks, or adjust guard policies within safe bounds. Includes a what‑if simulator showing forecast impact, conflict checks, and one‑click apply with rollbacks. Captures rationale and outcomes for continuous learning and future tuning.

Acceptance Criteria

Risk-Triggered Realignment Suggestions

Given Drift Radar detects a team risk score above a configured threshold or >3 guard breaches in the last 7 days When the user opens Realignment Recommendations for that team Then at least one recommendation is returned within 2 seconds And each recommendation is typed as one of: shift meeting windows, rebalance equity rotation, insert focus blocks, adjust guard policies And each recommendation includes an estimated breach-risk reduction percentage and a confidence score between 0.0 and 1.0 And each recommendation lists scope (teams, timezones), meetings/users affected count, and earliest effective date And recommendations that would violate hard guardrails are excluded; soft-guard tradeoffs are explicitly flagged

What-If Simulator Forecast and Conflict Checks

Given a candidate recommendation is selected When the user adjusts parameters (time offsets, rotation assignments, focus block durations) and clicks Simulate Then the simulator displays forecasted risk delta by hour and timezone, and projected maker-hours preserved (numeric values) And a visual diff of current vs proposed schedule is shown And calendar conflicts are computed with total count and a list of conflicting participants/events And parameter tweak responses render within 500 ms; first-run simulation renders within 2 seconds And if any blocking conflicts remain, Apply is disabled and auto-resolve options (e.g., shift ±15 minutes) are presented

One-Click Apply with Safe Rollback

Given an approved recommendation with no blocking conflicts When the user clicks Apply Then calendar updates to recurring meetings are sent with updated times and ICS notifications, focus blocks are created as Busy, and guard policy values are adjusted within configured bounds And all changes commit atomically; if any sub-operation fails, the entire operation rolls back and an error summary is shown And a rollback action is available for 30 days; when invoked, all changes revert and affected invites are corrected within 60 seconds And an activity record is created containing change set ID, actor, timestamp, and affected objects

Equity Scoreboard Rebalance Fidelity

Given a rotation rebalance recommendation When simulated for the selected team and period Then fairness metrics (mean ownership per person and variance) move toward target or stay within ±5% of target And no individual receives more than one additional consecutive ownership slot beyond baseline in the next 4 rotations And personal constraints (unavailable times, core hours) are honored with zero violations And predicted attendance probability increases by at least 5% or projected risk reduces by at least 10%, otherwise the recommendation is marked low impact

Protected Focus Blocks Auto-Insertion Rules

Given team guard policies define focus block duration and windows When the system proposes auto-inserted focus blocks Then blocks do not overlap immovable events and maintain a minimum contiguous length of 90 minutes And total focus-block time does not exceed 20% of a member’s weekly working hours And blocks are placed within local core hours with at least a 15-minute buffer from adjacent meetings And recurring series include an end date per policy and are labeled "Protected Focus" with the correct calendar category And any conflicts are listed with counts, and the simulator allows ±15-minute nudge options

Rationale, Audit, and Outcome Capture

Given a recommendation is applied Then the system stores rationale including detected breach patterns, selected levers, forecast metrics, approver, timestamp, and before/after policy/schedule deltas And records are immutable and queryable by team, timeframe, lever type, and change set ID When the 14-day observation window elapses Then actual outcomes (breach counts, attendance rates, maker-hours preserved) are computed and linked to the change record And PII is masked per policy; exports are available in CSV and JSON; data retention defaults to 12 months with admin-triggered hard delete supported

Integrations & Access Controls

"As a security‑conscious admin, I want granular permissions and audited integrations so that Drift Radar remains compliant and trustworthy for our organization."

Description

Provides secure integrations with Google Workspace and Microsoft 365 calendars, Slack, and SSO (OAuth/SAML) using least‑privilege scopes. Implements role‑based access (admin, lead, member), team scoping, data residency controls, encryption at rest/in transit, audit logs for policy changes and recommendations applied, and data retention/deletion policies. Supplies webhooks for breach events and risk updates.

Acceptance Criteria

Least-Privilege Calendar OAuth for Google Workspace and Microsoft 365

Given an org admin initiates calendar integration setup When the OAuth consent screen is displayed Then the requested scopes are limited to reading availability and creating or updating calendar events and basic OpenID profile information, and do not include mail, drive or storage, contacts, or directory scopes Given the integration is connected When an API call is attempted against a non-authorized resource Then the provider returns insufficient_scope and the attempt is logged in the audit log Given the admin revokes access at the provider When TimeMeld attempts to refresh tokens Then the integration status changes to Disconnected within 5 minutes and the admin receives a notification

Slack Integration with Minimal Scopes and Team-Scoped Alerts

Given a workspace owner installs the Slack app When the permission screen is shown Then the app requests only chat write, channels read for selection, and users read for mapping, and does not request channel or DM history scopes Given a Drift Radar alert is generated for Team A When TimeMeld posts to Slack Then messages are delivered only to the configured channels or DMs for Team A members and are not visible to other teams Given an API attempt to read channel message history occurs When the call is executed Then it fails due to missing scope and the event is recorded in the audit log

SSO and RBAC Mapping Enforcement

Given SAML or OIDC is configured with an identity provider When a user signs in via SSO Then an account is provisioned only if the email domain is on the allowlist and a valid group or role claim maps to admin, lead, or member Given a signed-in user with role member When attempting to access org-wide settings, integrations, or retention policies Then access is denied with 403 and an audit log entry is created with actor, action, and resource Given a user with role lead assigned to Team B When viewing Drift Radar risk and audit logs Then only Team B data is accessible and data for other teams is not retrievable

Data Residency Selection and Encryption Controls

Given an org admin selects a data region during setup, US or EU When data is persisted or processed Then customer data and backups remain in the selected region and cross-region storage is not used Given application traffic is initiated When connections are negotiated Then TLS version 1.2 or higher is enforced and weaker protocols are refused Given data at rest is stored When inspecting storage configuration Then encryption at rest is enabled using industry-standard algorithms and keys are managed by a KMS with rotation enabled

Audit Logging for Policy Changes and Recommendations

Given a policy change or a Drift Radar recommendation is applied When the action is saved Then an immutable audit log entry is recorded containing actor, role, team, timestamp in UTC, source channel UI or API, IP, resource identifier, and before and after values Given an auditor queries logs by date range, actor, team, and action type When 10,000 matching entries exist Then the query returns within 2 seconds and results can be exported as CSV and JSON Given a request attempts to modify or delete an audit entry via API When processed Then the request is rejected and the attempt is itself logged

Data Retention and Deletion Policy Enforcement

Given an admin configures retention periods for risk telemetry and audit logs When records exceed their configured retention Then they are purged from primary storage immediately and from backups within 30 days and the purge is logged Given a user deletion request is submitted When processing completes Then personally identifiable and calendar-derived data for that user is deleted or irreversibly anonymized within 30 days and a deletion certificate is available for download Given a data export is generated after deletion When the export is inspected Then the deleted user’s data is absent

Webhooks for Breach Events and Risk Updates

Given an admin creates a webhook subscription for guard breach attempted, guard breach actual, and risk score updated events When an event occurs Then a POST is delivered within 10 seconds including event id, org id, team id, event type, and timestamp, and an HMAC SHA256 signature header computed with the shared secret Given the receiver returns a non-2xx status When delivery is retried Then up to 3 retries occur with exponential backoff and duplicate deliveries carry the same event id for idempotency Given 10 consecutive delivery failures occur When the threshold is reached Then the webhook is auto-disabled and an admin notification is sent

Drift Heatmap

An interactive grid that visualizes show‑rates by region, day, and hour so you can instantly spot underperforming windows. Hover to see trends, compare cohorts, and jump straight to recommended fixes—eliminating guesswork and speeding confident adjustments.

Requirements

Heatmap Data Pipeline & Show-Rate Metric

"As a data-driven PM, I want a trustworthy, up-to-date show-rate metric by region/day/hour so that I can base scheduling changes on accurate and statistically meaningful insights."

Description

Implement a reliable data pipeline that ingests meeting metadata and attendance outcomes from connected calendars, normalizes timezones, and computes show-rates aggregated by region, day of week, and hour of day. Define a canonical “show-rate” metric (attended/scheduled) with clear rules for attendance, cancellations, reschedules, and no-shows. Bucket events into 7x24 hourly windows using the meeting’s effective region and local time. Support configurable lookback windows (e.g., last 4–12 weeks), rolling updates (hourly/daily), and backfilling. Enforce minimum sample-size thresholds and outlier handling to ensure statistically meaningful cells, masking or annotating low-confidence data. Persist pre-aggregated tiles for fast rendering and expose query APIs that support filters (region, team, meeting type, cohort). Ensure data quality monitoring, idempotent reprocessing, and auditability to guarantee accurate, timely, and trustworthy inputs for the Drift Heatmap and downstream recommendations.

Acceptance Criteria

Ingest and Normalize Calendar Events Across Timezones

- Given connected Google and Microsoft calendars are authorized, when the hourly ingestion job runs, then events created or updated within the lookback window are fetched with fields: provider, calendar_id, event_id, recurrence_id/occurrence_id, organizer, attendees (required/optional), meeting_type, team, cohort tags, start_time, end_time, timezone, created_at, updated_at, status, cancellation/reschedule flags, and outcome. - Given an event is fetched multiple times, when reprocessing occurs, then the pipeline produces a single canonical record per (provider, calendar_id, event_id, occurrence_id) and no duplicates are created (idempotent upsert). - Given an event’s source timezone and IANA identifier, when normalization occurs, then UTC and local timestamps are stored and DST is handled correctly so that local wall-clock time is preserved. - Given a successful source API response, when ingestion completes, then new/updated events are available to downstream aggregation within 60 minutes (p95) and 90 minutes (p99). - Given transient provider failures, when retries are applied, then at least 3 retry attempts with exponential backoff are performed before surfacing an alert, and the backlog is caught up within the next successful run. - Given malformed or missing required fields, when validation runs, then the event is quarantined with a reason code and excluded from aggregates until corrected.

Canonical Show-Rate Metric and Outcome Rules

- Given a filtered event set, when computing show-rate, then show_rate = attended_meetings / scheduled_meetings, rounded to two decimals, and counts (attended_meetings, scheduled_meetings) are included. - Given event.outcome in {attended, no_show, canceled, rescheduled}, when classifying, then scheduled_meetings includes outcomes {attended, no_show} only; canceled >= 60 minutes before start are excluded; rescheduled prior to start are excluded and attributed to the new slot only. - Given a cancellation < 60 minutes before start, when classifying, then it is treated as no_show. - Given conflicting updates (e.g., rescheduled then attended), when finalization runs, then the latest outcome as of aggregation time is used and original slot is excluded from denominator. - Given multi-attendee meetings, when deriving meeting-level outcome, then attended requires organizer present and at least one required attendee present per normalized outcome; otherwise classify as no_show. - Given recurring meetings, when an occurrence is skipped (canceled in series), then that occurrence is excluded from both numerator and denominator.

7x24 Bucketing by Effective Region and Local Time

- Given an event with effective_region and timezone, when bucketing, then the event is assigned to exactly one cell defined by (region, day_of_week, hour_of_day) using the event’s local time in that timezone. - Given DST transitions, when local time repeats or skips, then bucketing uses wall-clock hour labels; repeated hours create distinct cells per occurrence and skipped hours produce no cells. - Given ISO-8601 week rules, when computing day_of_week, then Monday=1 through Sunday=7 is applied consistently across all regions. - Given region precedence rules, when both organizer region and explicit meeting region are present, then explicit meeting region takes precedence; otherwise organizer region is used. - Given 7 days and 24 hours, when building aggregates, then each region yields 168 cells per lookback cohort with correct counts summing to the regional totals.

Configurable Lookback, Rolling Updates, and Backfill

- Given a configuration parameter lookback_weeks ∈ [4,12], when aggregation runs, then only events within the trailing lookback_weeks are included. - Given hourly incremental updates, when source events change, then aggregates reflect changes within 60 minutes (p95) from the source update time. - Given a daily full recompute at 02:00 UTC, when the job completes, then aggregates exactly match recomputed results for the same filters (checksum equality of counts). - Given late-arriving events or outcome changes, when backfill is triggered for a date range, then aggregates are updated idempotently without duplicate records and version metadata is advanced. - Given a backfill up to 52 prior weeks, when executed, then job completion produces a run report with processed windows, counts ingested, and discrepancies vs prior snapshot (if any).

Sample Size Thresholds, Outliers, and Confidence Masking

- Given a configurable minimum_n (default 30), when a cell’s scheduled_meetings < minimum_n, then the cell is masked from the heatmap’s primary color scale and labeled low_confidence=true with N displayed. - Given minimum_n is met, when computing show_rate, then the value is displayed and included in recommendations. - Given regional distributions, when a cell’s show_rate has |z-score| > 3 relative to its region’s distribution for the same lookback, then the cell is annotated outlier=true but not masked if N ≥ minimum_n. - Given configuration for outlier handling, when winsorize=true, then cell show_rate values are clamped to the regional 5th–95th percentile bounds for display-only and raw counts remain unchanged. - Given suppressed cells, when computing regional totals, then suppressed cells are excluded from weighted averages unless include_suppressed=true is specified in the query.

Pre-Aggregated Tiles and Filterable Query API

- Given pre-aggregation, when the tile builder runs, then it persists tiles keyed by (region, day_of_week, hour_of_day, lookback_weeks, team?, meeting_type?, cohort?) including fields: show_rate, attended_meetings, scheduled_meetings, low_confidence, outlier, last_computed_at, version. - Given the Heatmap queries tiles via GET /api/heatmap/tiles, when filters region, team, meeting_type, cohort, and lookback_weeks are provided, then only matching tiles are returned and response p95 latency ≤ 300 ms for up to 10 regions. - Given masked cells, when returned, then cells include low_confidence=true and do not include show_rate in the primary value unless include_masked=true is set. - Given ETag support, when the same query is repeated with If-None-Match and tiles are unchanged, then the API returns 304 Not Modified. - Given pagination parameters limit and cursor, when querying large result sets (>1000 tiles), then results are paginated consistently with stable ordering.

Data Quality Monitoring, Idempotent Reprocessing, and Auditability

- Given pipeline SLAs, when monitoring runs, then freshness for hourly aggregates is < 90 minutes since last successful run (p95) and alerts fire to #data-alerts if breached. - Given source-to-target reconciliation, when daily checks run, then event-level completeness differs by < 0.5% from provider counts per region; larger deltas open an incident automatically. - Given schema contracts, when an unknown outcome/status is encountered, then the event is quarantined and an alert with sample payload is generated; aggregates skip quarantined events. - Given reprocessing by date range, when the same window is recomputed with identical inputs, then output aggregates (counts and rates) are identical (checksum match) and previous versions are soft-deleted with lineage retained. - Given audit requirements, when any ingestion, aggregation, or backfill job runs, then an immutable audit log records actor, parameters, code version, start/end times, row counts, and result location with retention ≥ 400 days.

Interactive Drift Heatmap Grid

"As a scheduling lead, I want an intuitive grid that lets me scan underperforming windows and interact with cells quickly so that I can pinpoint problem times without digging through raw data."

Description

Deliver a responsive, accessible heatmap UI that visualizes show-rates across a 7x24 grid with a clear color scale and legend, tooltips on hover, and keyboard navigation. Support filtering by region, timeframe, team, meeting type, and cohort, with stateful URLs for deep-linking. Allow single and multi-cell selection, brushing/lasso to select ranges, and quick actions from the selection. Provide empty/error states, loading skeletons, and a persistent legend with clear thresholds. Optimize for performance with pre-fetched tiles, client-side caching, and <2s initial render on typical org datasets; ensure interactions (hover, select, filter) respond within 200–500ms. Ensure WCAG AA contrast, tooltip focus management, and screen reader labels for all interactive elements. Render consistently on desktop and tablet, with graceful mobile read-only support.

Acceptance Criteria

Responsive Rendering & Performance SLAs

Given a typical org dataset and a cold cache, When the user opens the Drift Heatmap route, Then the heatmap grid and persistent legend render within 2000 ms at p95. Given a warm cache and pre-fetched tiles, When the user switches any filter (region, timeframe, team, meeting type, cohort), Then the grid re-renders within 500 ms at p95 and previously fetched tiles are reused. Given the user hovers a new cell or moves keyboard focus, When the hover/focus changes, Then the tooltip content and highlight update within 200 ms at p95. Given the user selects one or more cells, When the selection is changed (click, brush, lasso), Then the selection highlight and count update within 200 ms at p95. Given adjacent timeframe navigation is available, When the user navigates to an adjacent period that has been pre-fetched, Then render completes within 300 ms at p95. Given the user reloads the same state, When data has not changed, Then no tile network requests are made (served from client cache) and the view renders within 1000 ms at p95. Given a desktop (≥1280px) or tablet (≥768px and <1280px) viewport, When the page loads, Then the grid fits within the viewport with no horizontal scrollbar and text is readable without zoom. Given a mobile viewport (<768px), When the page loads, Then the heatmap renders in a read-only mode where tap acts as hover to reveal a tooltip, multi-select/brush/lasso are disabled, and performance targets above are still met.

Keyboard Navigation & Screen Reader Accessibility (WCAG AA)

Given focus enters the heatmap grid, When the user presses Arrow keys, Then focus moves cell-by-cell in the corresponding direction and announces the new cell. Given focus is on a cell, When the user presses Enter or Space, Then the cell toggles selection and the selection count is announced. Given focus is on a cell, When the user presses Shift+Arrow, Then the selection extends to include the cell in the pressed direction. Given focus is within the grid, When the user presses Escape, Then the current selection (if any) clears and focus remains in the grid. Given a screen reader user, When a cell receives focus, Then it announces region, day, hour, show-rate percentage, and sample size. Given any interactive control (filters, lasso toggle, quick actions), When it is focused, Then it exposes a role, accessible name, and state via ARIA and is reachable by Tab order. Given any text in the heatmap UI, When evaluated for contrast, Then it meets WCAG AA 4.5:1 for text and 3:1 for non-text/graphical indicators; focus indicators have a 3:1 contrast ratio. Given a tooltip is triggered via keyboard, When it opens, Then it is programmatically associated with the focused cell, is dismissible with Escape, and focus returns to the invoking cell on close.

Filtering Controls & Stateful Deep Links

Given the user changes any filter (region, timeframe, team, meeting type, cohort), When the filter value changes, Then the URL query string updates to reflect the full current state without a page reload. Given a copied/shared URL containing heatmap state, When the page loads from that URL, Then filters, timeframe, and visible grid state are restored exactly. Given the user navigates browser Back/Forward, When the URL state changes, Then the heatmap restores the corresponding filters and view without a full reload. Given the user clears a specific filter, When cleared, Then the corresponding query parameter is removed and defaults are applied. Given the URL contains invalid or unsupported parameters, When parsed, Then safe defaults are applied and the URL is sanitized to valid parameters without breaking navigation. Given a large multi-select filter (e.g., regions), When multiple values are selected, Then the URL encodes them deterministically and the same ordering reproduces the identical state on reload.

Tooltip Content & Hover/Focus Behavior

Given the user hovers a cell on desktop/tablet, When the pointer rests on the cell, Then a tooltip appears within 200 ms showing: show-rate percentage, attended/total counts, delta vs previous comparable period (pp), cohort comparison delta, and the cell's region/day/hour labels. Given the user navigates cells via keyboard, When a cell receives focus, Then the same tooltip content is displayed and remains until focus changes or Escape is pressed. Given the tooltip would overflow the viewport, When positioned, Then it flips or repositions to remain fully visible with a minimum 8px margin from edges. Given quick pointer movements across adjacent cells, When hover changes rapidly, Then the tooltip updates without flicker (no hide/show within 100 ms) and tracks the active cell. Given mobile read-only mode, When the user taps a cell, Then the tooltip appears with the same content and a second tap outside dismisses it.

Selection, Brushing/Lasso, and Quick Actions

Given the user clicks a cell, When the cell is unselected, Then it becomes selected; clicking again deselects it. Given the user holds Shift/Cmd (Ctrl on Windows) and clicks additional cells, When clicking, Then multi-select adds/removes cells accordingly. Given the user click-drags in brush mode, When a rectangle is drawn, Then all enclosed cells become selected upon release. Given the user enables Lasso mode, When a freeform polygon is drawn and closed, Then enclosed cells become selected; pressing Escape cancels the lasso. Given a filter change occurs, When selected cells are no longer in view, Then only still-visible selected cells remain selected; others are dropped. Given one or more cells are selected, When selection exists, Then a quick actions bar appears within 300 ms offering at minimum: Apply as Filter, View Recommended Fixes, and Copy Deep Link to Selection. Given keyboard users, When selection exists, Then Ctrl+Enter opens the quick actions bar, Tab navigates actions, and Enter activates the focused action. Given Copy Deep Link to Selection is invoked, When activated, Then the clipboard receives a URL that restores filters and the selected cell set on load.

Legend, Color Scale, and Thresholds

Given the heatmap is visible, When the page loads, Then a persistent legend is displayed explaining the color scale with labeled numeric thresholds (min, mid/neutral if applicable, max) and units (%). Given filters or timeframe change, When the underlying data domain changes, Then the legend thresholds update to match the new domain and the color mapping remains consistent with the legend. Given colorblind-safe requirements, When the palette is evaluated, Then the chosen colors meet contrast guidance and are distinguishable in common color vision deficiencies. Given a user hovers or focuses the legend info icon, When activated, Then an explanation of how colors map to show-rate and thresholds is displayed and is accessible via keyboard and screen reader. Given printed or exported screenshots, When reviewed, Then the legend alone is sufficient to interpret the heatmap scale without external documentation.

Loading Skeletons, Empty, and Error States

Given initial data load, When the route is opened, Then a loading skeleton appears within 150 ms and remains until data renders to avoid layout shift. Given the selected filters yield no data, When the response is empty, Then an empty state is shown with a clear message and a CTA to adjust filters/timeframe; the grid area is not collapsible to zero height. Given a recoverable network error or timeout, When the request fails, Then an error state with a Retry action is displayed; clicking Retry re-requests and, on success, replaces the error with the heatmap. Given partial data, When some cells have no data, Then those cells render with a distinct no-data pattern and tooltips indicate "No data" without implying zero. Given consecutive retries, When three attempts fail, Then the error state persists and exposes an error code for support while remaining accessible and navigable by keyboard.

Cohort Comparison & Segmentation

"As a RevOps manager, I want to compare show-rates between customer segments and my internal team so that I can see which windows work best for each cohort and tailor scheduling rules accordingly."

Description

Enable side-by-side and overlay comparisons of show-rates across selected cohorts (e.g., teams, roles, internal vs. external, customer segment, region). Provide cohort filters, a delta view that highlights improvements/regressions, and significance annotations when differences are likely non-random. Allow saving and sharing of cohort configurations as named views, with URL state and permission-aware access. Support up to two overlays or a split grid for clarity, with synchronized hover tooltips and legends. Maintain performance by reusing pre-aggregations and limiting high-cardinality dimensions via curated lists.

Acceptance Criteria

Cohort Filter Selection & Curated Dimensions

Given the Drift Heatmap is open and the user has access to cohort filters When the user opens the filter panel and selects up to two cohorts from curated lists for Team, Role, Customer Segment, and Region Then only values from curated lists are selectable, search returns matching curated values within 200 ms, and non-curated values are disabled with an unavailable state Given no cohort is selected When the user applies filters Then the baseline “All” cohort is applied by default and comparison controls remain disabled until at least one cohort is selected

Side-by-Side and Overlay Modes with Two-Cohort Limit

Given two cohorts are selected When the view mode is switched to Overlay Then both cohorts render on a single heatmap with a merged legend, distinct cohort labels, and adding a third cohort is prevented with an explanatory message Given two cohorts are selected When the view mode is switched to Split Grid Then two heatmaps render side-by-side with aligned axes, synchronized zoom/scroll, and a shared color scale domain Given only one cohort is selected When the user switches modes Then only valid modes are enabled and no empty placeholder grids are shown

Delta View for Improvements and Regressions

Given two cohorts are selected and the Delta toggle is on When the heatmap renders Then each cell shows absolute delta (percentage points) and relative delta (%), colored green for improvements and red for regressions, with ±0 within a neutral band Given the user hovers a cell in Delta view When the tooltip appears Then it displays cohort A value, cohort B value, absolute delta, relative delta, and sample sizes for both cohorts Given delta thresholds are set to ±1.0 percentage points When a cell’s absolute delta is below the threshold Then the cell is visually deemphasized and excluded from Top Changes summaries

Significance Annotations and Thresholds

Given minimum per-cell sample size is set to n ≥ 30 per cohort When two cohorts meet the sample requirement and a two-proportion z-test at α = 0.05 indicates significance Then the cell is annotated with a significance marker and the tooltip reports p-value, test type, and sample counts Given multiple cells are tested for significance When annotations are applied Then Benjamini–Hochberg FDR correction at q = 0.10 is applied before marking significant cells Given a cell fails minimum sample size When rendering Then the cell displays an n < 30 indicator and is excluded from significance annotations

Synchronized Hover Tooltips and Legends

Given Overlay or Split Grid mode is active with one or two cohorts When the user hovers any cell Then the hover highlight is synchronized across all visible grids and the tooltip presents values for all visible cohorts plus delta if toggled Given the user navigates via keyboard When arrow keys move focus within the heatmap Then the synchronized tooltip updates accordingly and focus order is cell-by-cell, supporting WCAG 2.1 keyboard operability Given the legend is visible When the user toggles between Absolute and Delta scales Then the legend updates to reflect the active scale, color domain, and units

Save, Share, and Permission-Aware Views with URL State

Given the user has Editor permissions When they save the current cohort configuration as a named view Then the view is persisted with a unique name per workspace and a shareable URL encodes filters, mode, delta, and date range Given a Viewer opens the shared URL When the page loads Then the heatmap restores the exact saved state and save/overwrite controls are disabled Given an unauthorized or unauthenticated user opens the URL When access is checked Then an appropriate permission error is shown without revealing the view name or settings Given an Editor updates a named view When Save is clicked Then the URL remains stable and the view’s updated_at timestamp changes

Performance and Pre-Aggregation Utilization

Given up to 12 months of data and two cohorts selected When the heatmap loads with a warm cache Then time to first interactive render is ≤ 1.2 seconds and hover latency is ≤ 75 ms on a standard laptop Given a cold cache When the same view is loaded Then time to first interactive render is ≤ 3.0 seconds and backend queries are ≤ 3 leveraging pre-aggregations Given a filter change such as Region When the view updates Then the update completes within ≤ 400 ms for warmed data Given high-cardinality dimensions exist When filters are opened Then only curated lists (≤ 100 entries per dimension) are shown and typeahead search returns results within 200 ms

Hover Insights & Trends Tooltip

"As an engineering manager, I want instant trend context when I hover a cell so that I can judge whether a low show-rate is a blip or a persistent issue before making changes."

Description

Augment heatmap cells with rich hover tooltips that display sample size, show-rate, week-over-week and month-over-month deltas, a mini trend sparkline over the selected lookback, and confidence indicators based on sample size thresholds. Include contextual metadata (typical invitee count, common meeting types) and call out anomaly flags when sudden drifts are detected. Ensure tooltips are accessible, fast to render, and respect privacy masking for small samples. Provide localization for date/time formatting aligned to the selected region or viewer settings.

Acceptance Criteria

Tooltip Displays Core Metrics Quickly and Accurately

Given a user hovers or focuses a heatmap cell When the tooltip opens Then it shows sample size (n), show-rate (%), week-over-week delta (pp), month-over-month delta (pp), and contextual metadata (typical invitee count, common meeting types) And all metric values match the backend payload for that cell within ±0.1 percentage points for rates/deltas and exact integer for n And the tooltip’s first content appears within 150 ms (P95) and full content (including sparkline and badges) within 300 ms (P95) on supported browsers/devices And if any metric is unavailable, it displays "—" for that field without causing cumulative layout shift > 0.02

Sparkline Renders Correct Trend for Selected Lookback

Given a lookback period is selected (e.g., 8 weeks or 30 days) When the user opens the tooltip Then a sparkline renders values for that cell across the lookback using the selected aggregation granularity And the number of points equals the number of intervals in the lookback, and the last point equals the current cell’s show-rate And the sparkline has an accessible name "Trend" and an aria-label summarizing direction (up/down/flat) and last three values And if fewer than 3 data points are available, the sparkline is replaced with the text "Insufficient data"

Confidence Indicator Reflects Sample Size Thresholds

Given the cell’s sample size n When the tooltip renders Then it shows a confidence badge with level Low if n < 10, Medium if 10 ≤ n < 50, High if n ≥ 50 And each level includes an icon and label text and meets color contrast ≥ 4.5:1 against the tooltip background And the badge’s title/tooltip reads "Confidence based on sample size n" with the actual n inserted

Privacy Masking for Small Samples

Given masking threshold T = 5 When n < T Then the tooltip masks sensitive fields: show-rate and n display as "Masked (<5)" and WoW/MoM deltas are omitted And contextual metadata (typical invitee count, common meeting types) is omitted when n < T And a note "Limited data — privacy protected" is exposed to screen readers via aria-live polite When n ≥ T Then all fields render normally without masking

Anomaly Flag Appears on Sudden Drift

Given the backend marks the cell with anomaly=true and provides drift_delta_pp and optional rationale When the tooltip opens Then it displays an "Anomaly detected" badge with the delta (e.g., "−22 pp WoW") and an alert icon And activating (clicking or focusing + Enter) the badge reveals the rationale text if provided; otherwise shows "Significant change detected" And when anomaly=false, no anomaly badge or copy is displayed

Tooltip Accessibility and Keyboard Interaction

Given the heatmap is navigated via keyboard When a user tabs to a heatmap cell Then the cell is focusable (role="gridcell") with aria-label including region, day, hour, and show-rate (or "Masked" when applicable) And pressing Enter or Space opens the tooltip, Esc closes it, and the tooltip remains open while focus is within And screen readers announce the tooltip via aria-describedby only once; all interactive elements are reachable with visible focus; no keyboard traps exist

Localized Date/Time and Regional Formatting

Given the viewer’s locale/region is set (or a region is selected in-app) When the tooltip renders date/time and numeric values Then formatting matches the locale: en-US uses 12-hour time and MM/DD/YYYY; en-GB uses 24-hour time and DD/MM/YYYY; fr-FR uses 24-hour time and DD/MM/YYYY with localized month names where shown And weekday/hour labels reflect the selected region’s timezone And numeric separators follow locale conventions (e.g., 1,234.5 for en-US; 1 234,5 for fr-FR) And switching locale updates formatting within the same render cycle

One-Click Recommended Fixes

"As a product ops lead, I want to jump from a bad time slot to recommended alternatives and apply them in one click so that I can reduce no-shows without manual trial-and-error."

Description

From selected underperforming cells, generate ranked recommendations that adjust scheduling windows and rules to higher-performing alternatives by region and cohort. Present expected impact (projected show-rate lift, affected meetings), rationale, and confidence, with a one-click action to open the TimeMeld scheduler pre-populated with proposed changes. Support bulk selection across multiple cells, preview diffs, require confirmation, and log changes for auditability. Enforce permissions, provide rollback, and post-change monitoring links to validate outcomes. Deep-link back to the heatmap state after applying fixes to streamline iterative adjustments.

Acceptance Criteria

Single-Cell Ranked Recommendations Generation

Given a user selects one underperforming heatmap cell (specific region, day, hour, and cohort) When the user clicks "Recommended Fixes" Then the system returns a ranked list within 2 seconds containing at least one recommendation And each recommendation displays: proposed window/rule change, target region/cohort, projected show-rate lift (%) with confidence (Low/Med/High), affected meeting count (next 30 days), and a one-sentence rationale And recommendations are sorted by Impact Score = projected_lift_percent × affected_meetings (descending) And all proposed times fall within the region’s working hours configured in org settings

Bulk Selection Aggregation and Conflict Resolution

Given a user multi-selects two or more underperforming cells across regions and/or cohorts When the user clicks "Recommended Fixes" Then the system aggregates opportunities, deduplicates overlapping windows, and resolves conflicts so that no meeting or rule is adjusted twice And the result displays a selection summary (cells N, regions M, cohorts K, unique windows H) and a combined ranked recommendation list And if no viable alternatives exist, the system shows "No viable recommendations" with reasons (e.g., constraints, data sparsity) and a link to adjust filters

One-Click Apply Opens Pre-Populated Scheduler

Given the recommendations panel is visible and the user selects one or more recommendations When the user clicks "Apply in Scheduler" Then TimeMeld Scheduler opens within 2 seconds in a new tab/window And the scheduler is pre-populated with the selected recommendations (windows/rules, regions, cohorts) as a pending change set with a unique Change Request ID And the deep-link contains the heatmap context (filters, date range, selected cells) encoded in URL parameters

Diff Preview, Confirmation, and Audit Logging

Given a pre-populated change set is open in the scheduler When the user clicks "Review & Confirm" Then a diff view shows current vs proposed values per rule/window and the count of affected upcoming meetings with IDs And the user must explicitly confirm (checkbox + Confirm button) before changes are applied And upon confirmation, an audit log entry is created with user ID, timestamp, change set diff, source heatmap context, recommendation IDs, and outcome status

Permissions Enforcement for Applying Fixes

Given organization roles and permissions are configured When a user without "Apply Fixes" permission views recommendations Then apply/confirm controls are disabled with an explanatory tooltip and server-side checks prevent direct-link application (HTTP 403) And when a user with "Apply Fixes" permission performs the same actions Then the user can proceed to confirm and apply, and the action is recorded with their identity in the audit log

Rollback and Post-Change Monitoring Links

Given a change set has been successfully applied When the user clicks "Rollback" within the configured rollback window (default 24 hours) Then prior rules/windows are restored exactly and affected meetings are reverted or updated accordingly, with notifications sent to impacted organizers And an audit log entry records the rollback with a reference to the original Change Request ID And a monitoring link is provided that opens a post-change performance view (heatmap/report) scoped to impacted regions/cohorts and next 14 days

Deep-Link Back to Preserved Heatmap State

Given a user applies or cancels from the scheduler When they return via the "Back to Heatmap" link or automated redirect Then the heatmap restores the exact prior state (filters, date range, cohort comparison, scroll position, and selected cells) And a dismissible banner summarizes applied actions with a link to the Change Request details And the preserved state remains valid for at least 30 minutes via URL parameters

Permissions, Privacy & Governance

"As a security-conscious admin, I want strict access controls and privacy safeguards on heatmap data so that we can gain insights without exposing sensitive information."

Description

Implement role-based access controls so org admins can see org-wide data, team leads see their teams, and individuals see only aggregated views that protect privacy. Enforce minimum-N masking, region-based data residency rules, and redaction of PII in tooltips, exports, and shared links. Provide expiring, permission-aware share URLs for views and comparisons. Log access and configuration changes for audits and support data retention controls aligned with organizational policies. Ensure SSO integration and adherence to security standards to safeguard sensitive scheduling and attendance data.

Acceptance Criteria

RBAC: Admin, Lead, Individual Visibility in Drift Heatmap

Given an Org Admin is authenticated via SSO, When they open Drift Heatmap, Then they can select All Teams and view org-wide aggregates unless min-N masking applies. Given a Team Lead of Team A is authenticated, When they attempt to view Team B or All Teams, Then the UI displays "Insufficient permissions" and the API responds 403, and no data is rendered. Given an Individual Contributor is authenticated, When they open Drift Heatmap, Then the team filter is disabled and only aggregates at or above min-N are shown; no user-level drilldowns are available. Given any user attempts to access a heatmap view outside their scope via direct URL, When the request is made, Then the server returns 403 and the response omits whether the resource exists; an audit log entry is created.

Privacy Masking: Minimum-N Aggregation Enforcement

Given org minN is configured to 5, When a heatmap cell’s sample size is less than 5, Then the cell displays "—" and the tooltip shows "Insufficient sample size"; raw counts are hidden. Given a user hovers or clicks a masked cell, When requesting details, Then the API returns 200 with masked=true and no counts; drilldown panels do not render individual records. Given an export is generated for a view containing masked cells, When the CSV/JSON is downloaded, Then all masked cells are represented as null and include reason="minN". Given an admin updates minN from 5 to 8, When saved, Then the change propagates within 5 minutes and is reflected in UI and exports; the change is recorded in the audit log.

Data Residency: Regional Storage and Processing

Given org residency=EU, When Drift Heatmap loads, Then all data queries are served from EU endpoints and audit logs record region=EU for each request. Given a share link or export is requested by an EU org, When generated, Then the URL host and storage are located in EU; cross-region transfer attempts are blocked with 403 and logged. Given a view combines EU and US teams, When a user attempts to load raw comparative data, Then cross-region raw joins are prevented; only aggregated results that meet both regions’ minN are returned; otherwise 403 region policy violation is returned. Given an admin initiates residency change EU→US, When migration is in progress, Then the Heatmap remains read-only with banner "Data migration in progress"; all accesses and changes are logged with pre/post region.

PII Redaction Across UI, Tooltips, Exports, and Links

Given any user role, When viewing tooltips or hover details, Then no PII (emails, full names, phone numbers, calendar subjects, meeting URLs) is displayed; only aggregates and anonymized labels (e.g., Team A, Region EU). Given an export is generated, When inspected, Then it contains no PII fields and no values matching PII regexes (email, phone) and event subjects are blank or hashed; a data dictionary is included without PII. Given a shared link is created, When inspecting its URL and response payload, Then it contains no PII or stable identifiers; IDs are ephemeral and scoped to the share; counts are masked by min-N as applicable. Given a client requests unredacted details via undocumented fields, When the API receives the request, Then it returns 400 and logs a redaction policy violation.

Permission-Aware, Expiring Share URLs for Views and Comparisons

Given a user with Share permission, When generating a share URL, Then they can set expiry datetime (default 7 days, max 90 days) and scope (current view, filters, and optional comparison); creation is logged. Given a recipient opens the share URL, When RBAC is evaluated, Then the data returned is limited to their permissions; unauthorized teams are excluded or masked; forbidden access returns 403. Given the share URL is expired, When accessed, Then the server returns 410 Gone and the UI shows "Link expired"; access attempt is logged. Given an owner revokes a share, When revoked, Then subsequent accesses return 403; share cannot be listed or guessed (unguessable token length >= 128 bits); links are hosted in the org’s residency region.

Audit Logging and Retention Controls

Given any access to Heatmap, sharing, export, or settings change, When the action occurs, Then an immutable audit log entry is created with user_id, role, action, entity, timestamp (UTC), IP, region, result, and diff where applicable. Given an admin sets log retention to 180 days, When the retention job runs, Then log records older than 180 days are purged within 24 hours; purge events are themselves logged. Given an admin exports audit logs, When the export completes, Then the file respects residency, contains no PII fields, and includes a checksum; the export event is audited. Given an integrity check is requested, When run, Then the system reports pass/fail for tamper-evidence; any failure blocks exports and raises an alert.

SSO Integration and Security Standards Enforcement

Given SSO is enabled, When users authenticate via SAML or OIDC (Okta, Azure AD, Google Workspace), Then JIT provisioning assigns default roles; password login is disabled; SCIM sync (if configured) updates roles within 15 minutes. Given session management policies, When a session is idle for 60 minutes, Then it expires; IdP-initiated revocations take effect within 5 minutes; sensitive actions require re-auth within 15 minutes. Given transport and storage security requirements, When inspecting the service, Then TLS 1.2+ is enforced with HSTS and CSP headers; data at rest uses AES-256; no critical/high vulnerabilities are present in the latest scan and pen test. Given a security incident drill, When simulated, Then access to PII remains blocked, audit trails are intact, and rotation of share tokens and session keys completes within SLA (60 minutes).

Adaptive Baselines

Automatically learns each team’s normal attendance by region and season, adjusting for holidays and quiet weeks to prevent false alarms. You get timely, trustworthy drift alerts that reflect reality—not one‑size‑fits‑all thresholds.

Requirements

Regional Attendance Baseline Engine

"As a product manager, I want accurate, regional and seasonal attendance baselines so that I can trust drift alerts and avoid chasing normal fluctuations."

Description

Automatically compute per-team attendance baselines segmented by region, role, and local working hours, capturing weekday patterns and seasonal trends from rolling historical calendar signals. The engine ingests attendance outcomes for recurring meetings, applies recency-weighted decay, and produces expected attendance percentages for each meeting archetype and time window. Baselines are stored in a versioned feature store and exposed via API to TimeMeld’s meeting-window scorer and alerting service, ensuring scheduling and alerts reflect realistic team behavior.

Acceptance Criteria

Baseline Computation by Region, Role, and Local Working Hours

Given a team with at least 12 weeks of historical recurring meeting attendance labeled with region, role, and meeting local start time When the engine runs on its daily schedule at 02:00 UTC Then it computes per-team expected attendance percentages segmented by region, role, and local working-hour buckets (e.g., 09:00-12:00, 13:00-17:00 local time) for each weekday And published baselines only include segments with at least 20 occurrences or 6 weeks of data; otherwise a parent-level fallback (missing dimension rolled up) is produced and flagged with fallback=true And each baseline record contains fields: team_id, region, role, weekday, local_hour_bucket, expected_attendance_percent (0-100), sample_size, data_window_start, data_window_end, computation_time And the daily job finishes within 15 minutes for a team with <= 10,000 recurring-event instances

Recency-Weighted Decay Applied to Attendance Signals

Given historical attendance events spanning at least 26 weeks When computing baselines Then the engine applies an exponential decay with a default half-life of 8 weeks (configurable per team) so that events at t weeks ago have weight 0.5^(t/8) And weights are normalized to sum to 1 per segment before computing expected_attendance_percent And a unit test varying the last 4 weeks attendance by +20% changes the baseline by at least +10% while holding prior weeks constant And the configuration endpoint rejects half-life values outside 2-16 weeks with HTTP 400 and code=invalid_half_life

Seasonality and Local Holiday Adjustment

Given a region’s official public holiday calendar and detected company-wide shutdowns When computing baselines Then attendance events on a public holiday in that region are excluded from baseline calculations (weight=0) unless explicitly overridden And the engine identifies seasonal quiet weeks when weekly meeting volume drops >= 40% vs the prior 8-week median for that region; attendance in those weeks is down-weighted by 80% (weight=0.2) And baseline metadata includes seasonality_adjustments entries with {type, period_start, period_end, weight_rule} And a test dataset containing a holiday week and a quiet week produces baselines that differ from the unadjusted baseline by at least 5 percentage points for the affected segments

Meeting Archetype and Time-Window Baseline Output

Given meeting events labeled with archetype and local start times When computing baselines Then the engine produces expected_attendance_percent per combination of archetype, weekday, and 30-minute local time window And if archetype is unknown for >= 30% of events in a segment, a generic archetype baseline is produced and unknown events are included there And baseline output conforms to schema v1.0 with fields {archetype, weekday, local_time_window_start, local_time_window_end, expected_attendance_percent, sample_size, version_id} and validates against JSON Schema with zero errors And expected_attendance_percent values are numeric with one decimal precision and bounded within [0.0, 100.0]

Versioned Feature Store Persistence and Retrieval

Given a new baseline computation run When writing to the feature store Then records are written under a new immutable version_id following pattern baseline_{yyyy-mm-dd}_{run_id} and marked status=active And a read for (team_id, region, role, weekday, local_hour_bucket, archetype) with as_of_date returns the latest active version whose data_window_end <= as_of_date And rewrites with the same version_id are idempotent with no duplicate records, while publishing a newer version atomically flips prior active versions to status=superseded And at least 365 days of versions are retained and retrievable

Baseline API for Scorer and Alerting Services

Given the feature store contains active baselines When the GET /v1/baselines endpoint is called with team_id, region, role, weekday, local_time (ISO-8601 with timezone), and archetype Then it returns 200 with expected_attendance_percent, version_id, sample_size, and effective_period And if no segment baseline exists, the API returns the closest available fallback (dropping dimensions in the order: role -> local_hour_bucket -> archetype -> region) and includes fallback=true and fallback_dimensions And 99th percentile latency under 100 RPS is <= 200 ms with cache hit rate >= 80% for repeated queries And requests without valid auth tokens return 401; malformed parameters return 400 with error codes

Drift Signals Respect Adaptive Baselines (False-Alarm Prevention)

Given an alerting service requests a baseline for a meeting occurrence during a flagged quiet week or on a local holiday When comparing observed attendance to expected_attendance_percent Then no drift alert is issued unless deviation exceeds the team’s configured alert_threshold_percent (default 15%) after seasonal adjustments And the baseline response includes seasonality flags {holiday: true|false, quiet_week: true|false} for traceability And regression tests show a synthetic dataset with a holiday week reduces false positive alerts by at least 80% compared to an unadjusted baseline And baselines older than 24 hours are not served; the API returns 503 with code=baseline_stale until a fresh run completes

Holiday and Quiet-Period Awareness

"As an operations lead, I want baselines to account for holidays and quiet weeks so that expected dips don’t trigger false alarms."

Description

Integrate public holiday calendars by country/region, company-wide closure schedules, user-declared PTO, and auto-detected quiet weeks to dynamically adjust attendance baselines. The system maps each participant to a locale, applies holiday and quiet-week modifiers, and suppresses baseline expectations when reduced availability is expected. Admins can define custom calendars and overrides, ensuring baselines and alerts remain faithful to real-world availability across distributed teams.

Acceptance Criteria

Locale-Based Public Holiday Suppression

Given a meeting occurrence on 2025-11-27 16:00 UTC with participants mapped to locales {Alice: US, Bob: DE, Chandra: IN} and US public holiday "Thanksgiving Day" on 2025-11-27 When attendance baselines are computed for that occurrence Then the expected attendance excludes Alice and decreases by exactly 1 from the non-holiday baseline And no drift alert is generated if actual attendance equals the adjusted expected attendance And the holiday is sourced from the configured US public holiday calendar with a refresh timestamp within the last 24 hours And if the holiday feed is unavailable, the system uses the last known good calendar for that locale, retries per exponential backoff, and emits no alerts solely due to the feed outage

Company Closure Calendar Application

Given an admin-defined company closure from 2025-12-24 00:00 to 2025-12-26 23:59 in company timezone America/Los_Angeles and a recurring team meeting on 2025-12-25 18:00 UTC When baselines are computed for that occurrence Then the expected attendance is set to 0 for that occurrence And no drift alerts or low-attendance notifications are emitted for that occurrence And the closure takes precedence over public holidays and user PTO (baseline remains 0 regardless of other signals) And the closure window is applied using the company timezone boundaries even when participants are in other timezones

User-Declared PTO Adjustment and Latency

Given user Bob declares PTO from 2025-07-01 09:00 to 2025-07-05 18:00 in Europe/Berlin and there is a meeting on 2025-07-02 10:00 Europe/Berlin When the PTO is saved Then Bob is excluded from the expected attendance for any meeting overlapping the PTO window And baseline recomputation and any pending drift-alert predictions reflect the change within 5 minutes of the PTO save And for partial-day PTO (e.g., 2025-07-03 09:00–13:00), Bob’s attendance weight is reduced proportionally (>=50% reduction for a half-day block) And if an admin applies a per-occurrence force-include override for Bob, the override supersedes the PTO and the rationale records "override > PTO"

Quiet Week Auto-Detection and Damping

Given the last 4-week weekday baseline for the team for Thursdays is 10 expected attendees and the current week has >=50% of participants marked OOO (PTO+public holiday+custom closure) for at least 3 of 5 weekdays across >=2 regions When the system computes the baseline for the current Thursday Then the expected attendance is reduced to baseline × (1 − OOO_rate) = 10 × (1 − 0.5) = 5 And no drift alert triggers if actual attendance ≥ the damped baseline (5) And if global OOO_rate <30% and the OOO concentration is isolated to a single region, no quiet-week modifier is applied And the quiet-week flag automatically clears the following week when global OOO_rate drops below 20%

Admin Custom Calendars and Precedence

Given an admin creates a custom calendar event "Engineering Hackday" with reduced availability 50% for group Engineering on 2025-09-15 When baselines are computed for 2025-09-15 Then expected attendance for Engineering-only meetings is reduced by 50%, and for cross-functional meetings only Engineering participant weights are reduced And precedence order is enforced: per-occurrence admin override > company closure > admin custom calendar > user PTO > public holiday > quiet-week damping And on a day with company closure + custom calendar + PTO for Alice, the expected attendance is 0 and the rationale shows "company closure" And if an admin force-includes Alice for a specific occurrence, Alice is counted despite other signals and the rationale shows "override"

Mixed-Locale Meeting Adjustments and Alert Behavior

Given a meeting with 8 participants across locales {US:3, UK:2, IN:2, AU:1} and the occurrence date is a UK bank holiday only When the baseline is computed Then the expected attendance is reduced from 8 to 6 by excluding the 2 UK participants And if actual attendance is 6 or 7, no drift alert is sent; if actual attendance ≤5, one drift alert is emitted within 10 minutes post-meeting referencing the adjusted baseline And for the next occurrence where an AU public holiday affects 1 participant, the expected attendance is reduced by 1 accordingly And participant-locale mapping prioritizes user-declared locale over calendar timezone; if no user-declared locale exists, calendar primary timezone is used

Audit Log and Retroactive Recompute

Given baseline adjustments occur due to any signal (PUBLIC_HOLIDAY, COMPANY_CLOSURE, PTO, CUSTOM_CAL, QUIET_WEEK, OVERRIDE) When the baseline is computed for an occurrence Then an audit entry is stored with fields {occurrence_id, participant_id, reason_code, delta_before_after, source_id, timestamp} And when an admin adds a missed holiday retroactively and triggers recompute for the past 30 days Then past baselines and alerts are recalculated within 15 minutes for a team ≤100 participants and a changelog of alert differences is available And the UI/API exposes before/after expected attendance and reason trails for each affected occurrence

Drift Detection with Adaptive Thresholds

"As a meeting owner, I want adaptive drift alerts based on meaningful deviation so that I only act when attendance truly changes."

Description

Continuously compare actual attendance for recurring meetings against the context-aware baseline using confidence intervals that adapt to sample size, seasonality, and recent variance. Generate actionable drift alerts only when deviations are sustained and statistically meaningful, with cooldowns, duplicate suppression, and channel routing (Slack/email) managed by team preferences. Alerts are automatically muted during known holidays and quiet periods to minimize noise.

Acceptance Criteria

Baseline Learns by Region and Season

Given team regions and historical attendance per recurring meeting instance When the baseline job runs daily at 02:00 UTC Then it computes per-meeting, per-region baseline attendance for the next 8 weeks using rolling windows aligned to weekday and local season Given dates marked as holidays or quiet periods in the team calendar When computing baselines Then those occurrences are excluded from training windows and from n (sample size) Given at least 6 past eligible occurrences exist for a region–weekday pair When computing baselines Then the baseline is marked "stable"; else it is marked "warming" and flagged for wider confidence intervals downstream Given months representing the same local season as the target occurrence When weighting historical samples Then same-season samples receive weights >= 2x non-season samples

Adaptive Confidence Intervals and Small-Sample Handling

Given baseline mean and variance per region–meeting and sample size n When computing confidence intervals Then a 95% CI is produced using t-distribution for n < 30 and normal approximation for n >= 30 Given n < 6 or coefficient of variation > 0.5 When computing the CI Then the interval width is multiplied by a configurable inflation factor f (default f = 1.5) Given n = 0 eligible history for the region–meeting When detection runs Then drift is not evaluated, no alert is emitted, and result code "insufficient_history" is logged

Sustained Drift Detection with Cooldown

Given sustained_window = 3 occurrences and cooldown_hours = 72 (configurable per team) When actual attendance falls below the lower CI bound in at least 3 consecutive eligible occurrences Then a single "downward_drift" alert is emitted and cooldown starts for 72 hours Given cooldown is active When subsequent detection runs see the same drift condition Then no new alert is emitted until cooldown expires Given cooldown has expired When the drift condition holds for at least 1 new eligible occurrence Then a new alert is emitted with incremented sequence number (e.g., #2) Given only 1 of the last 3 eligible occurrences is outside the CI When detection runs Then no drift alert is emitted

Holiday and Quiet Period Muting

Given a meeting occurrence falls on a date marked as holiday or within a configured quiet period When detection executes Then alerts are suppressed and the occurrence is excluded from sustained_window counting and baseline updates Given a quiet period ends When the next eligible occurrence happens Then detection resumes and only eligible (non-muted) occurrences are considered for sustained_window history Given a make-up meeting during a quiet period has "override alerts" enabled by the owner When detection executes Then detection runs and may alert despite the quiet period; the override is logged

Duplicate Suppression and Alert Consolidation

Given multiple detection jobs run within 24 hours for the same meeting and drift key (direction + affected regions set) When a subsequent alert would be emitted Then it is suppressed and the original alert is updated with a cumulative evidence counter Given separate region-specific drifts are detected for the same meeting within 24 hours When alerts are emitted Then they are consolidated into a single message listing all affected regions with their statistics Given the drift direction flips within 24 hours (e.g., from downward to upward) When evaluating duplicate suppression Then a new alert is allowed with a new drift key, and the previous cooldown is closed

Preference-based Channel Routing and Delivery

Given team preferences specify Slack channel "#ops" and fallback email "alerts@company.com" When an alert is emitted Then a Slack message is posted to #ops including: meeting name, drift direction, magnitude (% vs baseline), CI bounds, n, affected regions, sustained_window, and link to inspect baseline Given Slack delivery fails (non-2xx response) or channel not found When retrying up to 3 times within 5 minutes Then on final failure an email with equivalent content is sent to the fallback within 2 minutes of the last retry Given user-level opt-out preferences When routing emails Then opted-out recipients do not receive the alert and the routing decision is logged

Alert Explainability and Audit Trail

Given an alert is emitted When the alert detail endpoint is queried Then it returns inputs (time range, n, mean, variance, CI method, thresholds, sustained_window evidence), decision rationale, and baseline version used Given detection runs without emitting an alert When audit logs are queried for that run Then a record exists with outcome and reason code (e.g., within_CI, insufficient_history, muted_holiday, cooldown_active) Given the same historical dataset and configuration are replayed in a dry-run When detection re-executes Then it produces the same alert/no-alert decisions and timestamps within ±1 second

Explainable Alerts and Baseline Visualization

"As a team lead, I want clear explanations of what changed and why an alert fired so that I can quickly diagnose and address attendance issues."

Description

Provide a dashboard and inline meeting view that explains why an alert triggered by showing baseline values, recent actuals, confidence bands, seasonality factors, and applied holiday/quiet-week adjustments. Highlight top contributing segments (e.g., region or time-of-day) and display change history so users can understand trends over time. Expose this context in TimeMeld’s Team Health and meeting details to build trust and accelerate corrective actions.

Acceptance Criteria

Team Health Alert Panel Explains Baseline, Actuals, Bands, and Adjustments

- Given a drift alert is visible in Team Health for a team, when the user opens the alert details panel, then the panel displays the baseline value with units for the alerted metric. - Given the alert details panel is open, when rendering recent performance, then at least the last 12 data points with timestamps are shown and are queryable via tooltip values. - Given the alert date is selected, when bounds are calculated, then the 95% confidence band lower and upper bounds are displayed numerically and visually on the chart. - Given seasonality and adjustments are applied, when computing expected, then the seasonality factor and each applied holiday/quiet-week adjustment are listed with names, regions, and numeric deltas. - Given the alert trigger condition, when the page renders, then a "Trigger reason" sentence states actual vs expected and bound (e.g., "Actual 62% fell 7pp below the 95% lower bound 69%").

Inline Meeting Details Show Alert Context and Contributors

- Given a meeting detail drawer is opened from a flagged meeting, when the content loads, then P95 load time is <= 1500 ms on a 10 Mbps connection. - Given the meeting is flagged, when computing expectation, then the displayed expected attendance incorporates region mix, time-of-day weighting, and any applicable adjustments, with a "View calculation" tooltip exposing terms used. - Given the meeting is flagged, when contributors are shown, then the top 3 contributing segments are listed with contribution % and absolute impact, and their cumulative contribution is displayed. - Given data is shown, when displaying freshness, then a "Last updated" timestamp appears in viewer local time and UTC.

Top Contributing Segments Ranking and Drill-Down

- Given a drift alert details view, when the "Top contributors" list renders, then items are sorted by absolute contribution descending. - Given contributors are listed, when a user clicks a segment, then the chart filters to that segment and a filter chip appears; clicking multiple segments enables multi-select; filters can be cleared individually or all at once. - Given contributions are computed, when totals are displayed, then the sum of segment contributions is within ±5% of the model-attributed deviation, or an explanation banner is shown. - Given no segment contributes >= 10% individually, when the list renders, then a "No dominant segments" message is displayed.

Change History Timeline and Audit Trail

- Given the user opens Change History, when entries are loaded for a selected date range, then baseline retrains, seasonality updates, holiday calendar imports/edits, quiet-week windows, and threshold changes are listed chronologically. - Given a change entry is shown, when details expand, then timestamp (UTC and local), actor (user or system), change type, and before/after values are visible. - Given filters are applied, when selecting change types, then the list updates without full reload within 300 ms. - Given user role permissions, when a non-admin views history, then actor identities are anonymized; admins see full details. - Given export is requested, when the user clicks "Export CSV", then a CSV with the visible entries is downloaded and matches the current filters. - Given retention policy, when querying beyond 180 days, then older entries are not shown and a "Retention limit" notice appears.

Holiday and Quiet-Week Adjustment Visibility and Alert Suppression

- Given an alert date overlaps a recognized holiday or declared quiet week for any team region, when the explanation renders, then a badge shows the event name, region(s), and numeric adjustment applied. - Given adjustments move the actual within the confidence band, when evaluating alerting, then the alert is marked as "Suppressed" and appears in history with "Suppressed by <event>". - Given a multi-region team, when multiple regional adjustments exist, then the UI shows up to 5 regions plus a "View all" link that reveals the full list. - Given an adjustment references an unknown calendar source, when rendering, then an "Unmapped event" tag with a link to resolve calendar mapping is shown.

Confidence Band Transparency and Interactive Controls

- Given the alert details view is open, when the user opens the confidence control, then options for 90%, 95%, and 99% are available, with the team default preselected. - Given the user switches the confidence level, when bounds recompute, then chart bounds and numeric values update within 200 ms and the trigger reason recalculates accordingly; no settings are saved by this action. - Given the confidence control is hovered, when the tooltip appears, then it explains the bound calculation and terms used.

Data Freshness, Timezones, and Units Consistency

- Given any explanation view is open, when metadata renders, then "Last updated" time is shown in both user local timezone and UTC. - Given data is fetched, when recency exceeds 15 minutes, then a warning banner "Data may be stale" is displayed. - Given values are displayed, when numerics render, then all values include correct units (%, attendees, days) and use the user's locale formatting for numbers and dates. - Given timezone weightings are shown, when tooltips open, then the team's target time window is displayed in the team timezone and converted to the viewer's timezone.

Feedback Loop and Model Tuning

"As a product manager, I want to label alerts and see accuracy improve so that noise decreases and I can rely on the system."

Description

Enable users to mark alerts as helpful or false alarm, add context, and suggest corrections to region/holiday mappings. Capture feedback as labels for offline evaluation and use it to adjust thresholds and feature weights per team, improving precision over time. Provide periodic accuracy reports so stakeholders can see reductions in false positives and the impact of their feedback.

Acceptance Criteria

Inline Alert Feedback: Helpful vs False Alarm

Given a user views an attendance drift alert in-app or via email When the user clicks "Helpful" or "False Alarm" Then the selection is persisted within 2 seconds and a success confirmation is displayed Given a previously labeled alert When the same user relabels it within 15 minutes Then the prior label is replaced, the change is logged, and after 15 minutes the label becomes read-only Given duplicate clicks on a label action within 10 seconds When processed Then only one label record is stored (idempotent) with userId, teamId, alertId, timestamp, and label

Add Context to Feedback Submission

Given the user marks an alert as "False Alarm" When the feedback modal opens Then the user must select at least one reason tag from [Holiday, Quiet Week, Region Mis-mapped, Data Issue, Other] and may add a note up to 500 characters Given the user submits context When saved Then the context is attached to the feedback record and visible in alert details and the audit log Given notes contain obvious PII patterns (e.g., emails) When stored Then the system masks the PII while retaining readability and indicates that redaction occurred

Suggest Region/Holiday Mapping Corrections

Given a user views an alert with reason "Region Mis-mapped" or selects "Suggest mapping fix" When the user opens the suggestion form Then the form allows specifying affected member(s), correct region(s), and holiday calendar source (provider or URL) with field validation Given a suggestion is submitted When an Admin reviews it Then the Admin can Approve or Reject; upon approval, mapping updates apply within 24 hours and impacted baselines are recalculated; the requester and team are notified Given a substantially duplicate suggestion exists in the last 30 days When a new identical suggestion is attempted Then the system prevents duplicate submission and links to the existing request

Per-Team Threshold and Feature Weight Tuning From Feedback

Given a team has ≥20 labeled alerts in the past 30 days When the weekly tuning job runs Then per-team thresholds and feature weights are re-estimated using labels and saved as a versioned model configuration Given the candidate configuration underperforms the current baseline on offline validation (precision decreases by >1% or false positive rate increases by >1%) When evaluated Then deployment is blocked and the prior configuration remains active Given a new configuration is deployed When active Then the change log shows version, deployment time, validation metrics deltas, and author "Auto-tuner"

Periodic Accuracy Reports With Feedback Impact

Given it is Monday 09:00 in the team’s primary timezone When report generation runs Then each team receives an in-app dashboard update and email including last 4 weeks vs prior 4 weeks: precision, recall, false positive rate, alert volume, and feedback count, plus an estimate of false positives avoided due to tuning Given a stakeholder downloads the CSV for the report period When compared to the metrics API for the same filters Then metric values match within 1% relative difference Given there were zero alerts in the period When the report is generated Then the report states "No alerts this period" and suppresses trend indicators

Feedback Data Capture and Auditability

Given a feedback event is submitted (label and optional context) When ingested Then an immutable record is written to the analytics warehouse table feedback_events with fields [eventId, alertId, teamId, userId, label, reasons[], note_redacted, createdAt] within 5 minutes for 99.5% of events measured monthly Given multiple events with the same eventId arrive When processed Then exactly-once semantics are enforced and no duplicates appear downstream Given an auditor filters by teamId and date range in the audit log When viewing results Then they see submitter, label, reasons, redacted notes, timestamps, and links to the originating alert, and can export to CSV

Admin Controls and Baseline Overrides

"As a workspace admin, I want controls and overrides for baselines and alerts so that I can handle edge cases and maintain reliability during transitions."

Description

Offer administrative controls for minimum data requirements, cold-start defaults for new teams, baseline freeze during org changes, manual overrides for exceptional periods, and configuration of alert channels and frequencies. Include audit logging and role-based access so only authorized users can alter baselines and notification behaviors. Provide export/import of baseline snapshots for governance and continuity.

Acceptance Criteria

Configure Minimum Data Requirements

Given I am an Org Admin on Admin > Adaptive Baselines settings When I set per-region minimum weeks_of_data to 4 and min_meetings to 20 and click Save Then teams/regions not meeting both thresholds have drift alerts automatically paused and display "Insufficient data" with current counts And if cold-start defaults are configured for the scope, those defaults are applied until thresholds are met And when thresholds become met, drift alerts resume within 15 minutes And an audit log entry records user, timestamp, scope, and before/after threshold values

Apply Cold-Start Defaults for New Teams

Given a team has not met the configured minimum data thresholds When an Admin assigns cold-start defaults (region, working hours, target attendance %, seasonality setting) to that team Then baseline calculations and drift alerts for that team use the cold-start defaults And the UI shows a Cold Start badge with the configured defaults And when thresholds are subsequently met, the system switches to the learned baseline within 15 minutes and writes an audit event And an Admin can end cold-start early, which takes effect immediately and is logged

Schedule Baseline Freeze During Org Changes

Given I select one or more teams/regions and schedule a baseline freeze with a start and end time When the freeze is active Then auto-learning updates are blocked and skipped updates are recorded in the audit log And drift comparisons continue against the frozen baseline values And the UI displays a Frozen badge with the freeze window And unfreezing re-enables auto-learning within 15 minutes and is logged

Manual Baseline Override for Exceptional Periods

Given I am an Admin and provide scope, date range, target baseline values/deltas, and a required reason When I create the manual override Then the override baseline takes precedence over both frozen and learned baselines for the specified date range And alerts and ergonomic window proposals reflect the override during its active period And overlapping overrides for the same scope are rejected with a validation error And upon override end, the system reverts to the prior state (frozen or learning) and records an audit entry

Configure Alert Channels and Frequencies

Given I configure alert channels (Email, Slack, Webhook) and frequencies (Immediate, Daily Digest) per team/region When I save valid targets and options, including quiet hours and timezone Then a confirmation is shown and a test notification can be sent successfully to each configured channel And delivery respects the configured quiet hours and digest schedule And configuration changes propagate to the alerting service within 5 minutes and are captured in the audit log

Enforce Role-Based Access Controls

Given roles exist (Owner, Admin, Analyst, Viewer) When a user without Owner/Admin role attempts to create, edit, freeze, override, import, or change alert configurations Then the action is blocked with an authorization error and a security audit event is recorded And Owners/Admins can perform these actions successfully, with required reason fields on freeze/override/import and full before/after values logged

Export/Import Baseline Snapshots

Given I am an Admin on Admin > Baseline Snapshots When I export a snapshot Then the file contains effective baselines, thresholds, freeze windows, overrides, and alert configs for the selected scope in JSON and CSV formats with a checksum and version And when I import a snapshot using Dry Run first Then schema and permission validation runs, conflicts are listed, and no changes are applied And when I import with Apply and choose Merge or Overwrite Then changes apply atomically, produce an audit record, and a rollback snapshot is created automatically

Data Privacy and Compliance Safeguards

"As a compliance officer, I want attendance modeling to protect personal data and meet regulatory requirements so that we can safely adopt the feature across regions."

Description

Aggregate and pseudonymize attendance signals so only team-level metrics are stored and displayed, with encryption in transit and at rest and strict role-based access to detailed views. Apply regional data residency rules and configurable retention to meet GDPR and similar regulations. Provide auditable consent and deletion workflows integrated with TimeMeld’s existing privacy controls.

Acceptance Criteria

Team-Level Aggregation and Pseudonymization for Adaptive Baselines

Given a team with 5 or more active members in the selected period When Adaptive Baselines computes or updates attendance metrics Then only aggregated team-level metrics (e.g., count, percentage, mean, variance) are persisted and displayed And no user_id, email, calendar_id, IP address, or device identifier fields are stored in any persistent datastore And any transient processing artifacts containing individual events have a TTL <= 24 hours and are automatically purged Given a cohort (team/region/seasonal slice) with fewer than 5 contributing members When a request is made to view or export attendance metrics Then the metrics are suppressed (no values returned) and the UI displays "Insufficient sample size" And no small-n cohort metrics are exported via API Given an engineer queries production datastores for fields matching identifiable attendee attributes When the query is executed Then zero records are returned for identifiable fields in persisted datasets related to attendance metrics

Encryption In Transit and At Rest for Attendance Metrics

Given any HTTP(S) endpoint handling attendance signals or metrics When a client connects Then TLS 1.2 or higher is enforced and HSTS is enabled (max-age >= 15552000) And connections using HTTP or TLS < 1.2 are rejected Given attendance metrics or transient attendance signals are stored When data is written at rest (databases, object storage, backups) Then AES-256 encryption at rest is enabled using KMS-managed keys And key rotation occurs at least every 90 days and is auditable Given an attempt is made to read encrypted storage without appropriate KMS permissions When the request is executed Then access is denied and the event is logged with user, resource, and timestamp

Role-Based Access Control for Detailed Attendance Views

Given organization roles {Org Admin, Privacy Officer, Team Admin, Member, Viewer} When a Member or Viewer attempts to access detailed attendance views or exports beyond team-level aggregates Then the request is denied with HTTP 403 and the event is logged Given an Org Admin or Privacy Officer is authenticated via SSO and MFA When they access detailed attendance configuration and audit pages Then access is granted And all access is recorded with user, role, timestamp, and resource Given a user's role is downgraded When the change is made in the admin console Then effective permissions reflect the change within 5 minutes across API, UI, and exports

Regional Data Residency Enforcement for EU Teams

Given a team with data residency set to EU When attendance signals are ingested and Adaptive Baselines compute runs Then storage location tags for primary and replicas are EU-only And compute jobs execute on EU-region nodes And no cross-region replication or processing occurs Given an admin attempts to export EU team metrics to a non-EU destination When the export is initiated Then the export is blocked unless a lawful transfer mechanism is recorded (e.g., SCC toggle with justification) And the transfer basis is written to the audit log Given data residency is EU When a data flow scan runs Then zero network calls are detected to non-EU endpoints for relevant data paths

Configurable Data Retention for Attendance Signals

Given an Org Admin sets retention for attendance signals to a value between 30 and 730 days (default 365) When the setting is saved Then the new retention policy is displayed in the admin UI and versioned in the audit log Given the retention is set to 180 days When the daily retention job runs Then all attendance signals older than 180 days are deleted or irreversibly aggregated And a deletion summary report (records scanned, deleted, retained) is produced and stored And no primary datastore contains records older than 180 days Given backups containing deleted records exist When the backup purge window elapses Then purged data is removed from backups within 35 days and the action is logged

Consent Capture and Right-to-Erasure Workflow

Given a new EU-based user is first processed for attendance signals When the user signs in or is first observed Then a consent prompt displays the specific purposes (attendance analytics for Adaptive Baselines) and links to the privacy policy And processing does not begin until explicit opt-in is recorded Given a user withdraws consent via Privacy Controls When the withdrawal is submitted Then new processing of attendance signals for that user stops within 24 hours And previously stored signals are deleted within 30 days And the user's contributions are excluded from the next model rebuild within 7 days Given a data deletion (Art. 17) request is received When the request is submitted via Privacy Controls or API Then an acknowledgment is sent within 72 hours And deletion is completed within 30 days across primary stores, derived datasets, and search indexes And the outcome is recorded in the audit log with request ID

Audit Logging and Export for Privacy Events

Given privacy-impacting events occur (access to detailed views, consent changes, retention updates, data exports, data deletions) When these events happen Then an immutable, append-only audit log entry is created with event_id, actor, role, action, resource, timestamp (UTC), IP, and outcome And entries are tamper-evident via chained hashes Given an Org Admin requests an audit export When filters (date range, event types, actors) are applied Then the system produces CSV and JSON exports within 60 seconds for <=100k events And a checksum of the export is provided Given an unauthorized user attempts to modify or delete audit logs When the attempt occurs Then the action is rejected and an alert is generated to security contacts

Impact Simulator

Test candidate time shifts before committing. See projected show‑rate lift, timezone burden changes, and rotation effects side‑by‑side so you can choose the most humane, high‑impact window with data—not hunches.

Requirements

Interactive Time Shift Controls

"As a remote team organizer, I want to tweak candidate meeting times and instantly see updated impact metrics so that I can quickly find a window that balances attendance and fairness."

Description

Provide an interactive UI to create and adjust candidate meeting time shifts (e.g., +/- 15/30/60 minutes, day offsets) with guardrails for participant working hours, meeting duration, recurrence rules, and organizer constraints. Recalculate key metrics (projected show-rate, timezone burden, and rotation effects) in real time as the user manipulates sliders or selects presets. Support keyboard and mouse interactions, accessibility labels, undo/redo, and reset-to-current-time. Integrate with TimeMeld’s participant profiles to respect declared core hours and with calendar availability to avoid hard conflicts. Handle both one-off and recurring meetings with preview across future instances.

Acceptance Criteria

Real‑Time Metrics Recalculation on Time Shift Adjustment

Given a scheduled meeting and the Impact Simulator is open with a visible candidate window When the user adjusts the time via slider drag, preset click, or keyboard step Then projected show‑rate, timezone burden, and rotation effects recompute and render within 500 ms after the last input event And a loading indicator appears within 300 ms if computation exceeds 500 ms and resolves within 2 seconds or shows a non-blocking error state And metric deltas are shown relative to the current scheduled time and reflect the new candidate time accurately (no stale values) And no UI element displays conflicting values for the same metric across panels

Guardrails for Core Hours, Conflicts, and Organizer Constraints

Given participant profiles with declared core hours and live calendar availability When the candidate time shift would place any part of the meeting outside a participant’s core hours Then the UI blocks commit (Apply) and displays a clear, per‑participant explanation with local‑time details And the candidate window cannot be committed if it overlaps any hard calendar conflict for any required attendee or organizer And the meeting duration and recurrence pattern remain unchanged by the shift; partial truncation is not permitted And day offsets and cross‑midnight shifts evaluate constraints in each participant’s local timezone correctly

Preset Shifts and Day Offsets Apply Correctly

Given preset controls for ±15/30/60 minutes and ±1 day When the user clicks a preset Then the candidate start time shifts by the preset amount from the current candidate value and remains within allowable bounds And consecutive preset clicks compound sequentially until Reset is invoked And the active preset state is visually indicated for 1 second after application And applying a preset immediately updates all metrics within 500 ms and re-validates guardrails

Keyboard Accessibility and Screen Reader Support

Given focus is on the time shift slider When the user presses Left/Right Arrow Then the candidate time changes by the configured step (default 15 minutes) and metrics update within 500 ms And pressing Shift+Arrow multiplies the step by 2; pressing PageUp/PageDown applies ±60 minutes And Space/Enter activates the focused preset; Tab/Shift+Tab traverse controls in a logical order with a visible focus indicator And all interactive elements expose accessible names, roles, and states; live metric updates announce concise deltas via an ARIA polite region; color is not the sole means of conveying status; contrast meets WCAG 2.1 AA

Undo, Redo, and Reset to Current Time

Given a series of time shift changes in the current session When the user invokes Undo (Ctrl/Cmd+Z) or clicks Undo Then the candidate time and all visible metrics revert to the prior state within 500 ms And Redo (Ctrl/Cmd+Shift+Z) reapplies the most recently undone change And the history retains at least the last 10 changes per session And invoking Reset returns the candidate to the original scheduled time, clears the history, and revalidates guardrails

Recurring Meetings: Future Instance Preview and Metrics

Given the meeting is part of a recurring series When the user applies a candidate time shift Then a preview displays the next 8 affected instances with local times per participant and per‑instance conflict indicators And aggregated metrics for the series (e.g., average projected show‑rate, total timezone burden change) update within 1 second And if any future instance has a hard conflict, Apply to Series is disabled until the conflict is resolved or that instance is excluded And instances spanning DST changes show correct local wall‑clock times and compute metrics using the adjusted local times

Attendance Lift Forecasting

"As a product manager, I want to see a data-backed estimate of how attendance will change for each proposed time shift so that I can choose the option most likely to improve show rates."

Description

Implement a forecasting service that projects show-rate changes for candidate time shifts using historical attendance, RSVP behavior, time-of-day/day-of-week effects, and participant reliability signals. Produce a scenario-level projected attendance percentage with a confidence band and callouts for low-data segments. Provide explainability (e.g., top drivers) and guard against bias by capping influence from outliers. Integrate with Google/Outlook calendar data via TimeMeld’s connectors, cache results for snappy UI, and expose a versioned API consumed by the Impact Simulator. Log model inputs/outputs for auditing and enable fallbacks to heuristic scoring when data is sparse.

Acceptance Criteria

Projection and Confidence Band Returned for Candidate Time Shift

Given a valid candidate time shift and sufficient historical attendance/RSVP/reliability data are available When the Impact Simulator requests a forecast via API v1 Then the response includes projectedAttendancePercent between 0 and 100 with two-decimal precision And the response includes confidenceInterval.lower and confidenceInterval.upper between 0 and 100 where lower <= projectedAttendancePercent <= upper And the response includes non-empty modelVersion and scenarioId fields And the same request payload yields identical projectedAttendancePercent within a single modelVersion (idempotent)

Explainability: Top Drivers Included Without PII

Given a forecast response is produced When inspecting explainability fields Then topDrivers contains between 3 and 5 items sorted by absoluteContribution descending And each driver includes featureName from an approved vocabulary and contributionPercent with sign (+/-) And the sum of absolute contributionPercent across topDrivers is >= 60% And no raw PII (names, emails) appears in featureName or description fields And each driver includes a shortExplanation string of <= 200 characters

Low-Data Callouts and Heuristic Fallback

Given the historical data volume for the scenario is below thresholds (e.g., <5 comparable past meetings or <3 participants with reliability scores) When a forecast is requested Then the response sets fallbackUsed = true and fallbackMethod matching pattern heuristic_v* And lowDataSegments lists the impacted segments with counts And projectedAttendancePercent and confidenceInterval are still returned And confidenceInterval width is >= 15 percentage points to reflect uncertainty And an info-level callout message is present indicating data sparsity

Outlier Influence Cap and Robustness

Given inputs that contain extreme outliers (e.g., a participant with an anomalous no-show streak or an event with abnormal RSVPs) When the model applies winsorization/capping at configured 5th/95th percentiles Then no single participant or event contributes >10% absolute weight to the final projection And comparing forecasts with and without the outlier capped yields an absolute difference <= 2 percentage points for the same scenario And modelMeta in the response exposes the capping configuration used (e.g., p5/p95)

Calendar Connector Integration and Data Freshness

Given Google and/or Outlook connectors are authorized When the forecasting service builds features Then it ingests past 12 weeks of events, attendance, and RSVP statuses per connected calendar And deduplicates events using stable IDs (eventId/iCalUID) and excludes canceled instances And data freshness (time since last successful sync) is <= 24 hours for active connectors And if a token is revoked or expired, the API returns 401 connector_auth_required with a remediation message and no PII in payload

Versioned API Contract and Cached Performance for Impact Simulator

Given the Impact Simulator calls POST /api/v1/forecast with a valid request body When the request is processed Then the response validates against JSON Schema forecast.v1.2 And the X-Api-Version response header equals 1.2 And breaking changes are only introduced under /api/v2/* endpoints And p95 latency for cached requests is <= 300 ms and for uncached (cold) requests is <= 2 s under nominal load And cache key includes candidateTime, participantIds hash, scenario options, and modelVersion with TTL = 15 minutes And relevant calendar updates invalidate affected cache entries within 60 seconds And rate limiting enforces <= 60 requests/min per org with 429 and Retry-After on exceedance

Audit Logging and Traceability of Forecasts

Given any forecast is generated When the service completes the request Then an audit record is stored with requestId, scenarioId, modelVersion, featureSummary (counts/means), projectedAttendancePercent, confidenceInterval, fallbackUsed, and a hash of topDrivers And participant identifiers are irreversibly hashed with a rotating salt and no raw PII is logged And audit records are retrievable by requestId via an internal endpoint and retained for 180 days with access control And logs include an ISO-8601 timestamp and are idempotent on retries (no duplicate records for the same requestId)

Timezone Burden Index

"As an engineering lead, I want a clear burden score by person and team for each candidate time so that I can avoid repeatedly scheduling outside someone’s core hours."

Description

Compute and display a per-participant and aggregate burden score for each scenario that reflects meeting occurrences outside core hours, severity of early/late local times, and recurrence frequency. Show deltas versus current schedule and highlight who benefits or is adversely impacted. Allow admins to configure core hours by person or team and weighting rules (e.g., heavier penalties for <6am or >9pm local). Provide visual summaries (heatmap, traffic-light badges) and exportable details. Integrate with participant timezone profiles and daylight saving time shifts to keep calculations accurate over time.

Acceptance Criteria

Per-Participant and Aggregate Burden Score Computation

Given a scenario with up to 50 participants, per-person/team core hours, and weighting rules defined When the Timezone Burden Index is computed for 52 weekly occurrences Then each occurrence is mapped to the participant's local wall time using their timezone profile and the effective DST offset on the occurrence date And band weights are applied (<06:00 heavy, 06:00-08:00 and 19:00-21:00 shoulder, >=21:00 heavy, in-core 0) unless overridden by configuration And per-participant score equals the sum over occurrences of (band_weight x recurrence_weight), rounded to 1 decimal place And aggregate sum and mean are calculated and displayed And the computation completes in <= 1 second And repeated runs with identical inputs return identical outputs

Delta vs Current Schedule Display

Given a baseline schedule is selected When a candidate scenario is loaded Then per-participant and aggregate deltas are shown as absolute and percent change vs baseline And improvements are indicated with green up arrows and regressions with red down arrows; neutral is gray And the participant list is sortable by largest absolute delta And participants with |delta| >= 10% are auto-highlighted And values update within 500 ms after any scenario parameter change

Admin Configurable Core Hours and Weighting Rules

Given an org admin is authenticated When the admin configures core hours at org, team, and person levels Then inputs accept 24h ranges, prevent overlaps, and support weekday/weekend distinctions And precedence is person > team > org for determining effective core hours And weighting rules allow numeric penalties per time band, with defaults heavier for <06:00 and >=21:00 And changes are persisted, versioned with timestamp and actor, and applied to new computations immediately And a secured API endpoint exists to read/write configuration; unauthorized requests are rejected with 401/403

Visual Summaries: Heatmap and Traffic-Light Badges

Given burden scores are computed for the scenario When the user opens the Burden view Then a heatmap renders with a visible legend and tooltips showing band counts and score components per participant And traffic-light badges show Good/Fair/Poor per participant using thresholds (default: Good <= 20th percentile, Fair >20th-<=60th, Poor >60th), which can be configured And all colors meet WCAG 2.1 AA contrast and use a color-blind-safe palette And keyboard navigation provides the same details as hover tooltips And re-render completes in <= 300 ms after configuration or scenario changes for datasets up to 50 participants x 52 occurrences

Exportable Details (CSV/JSON) with Metadata

Given a computed scenario and a selected baseline When the user exports as CSV or JSON Then the export includes per-participant fields: id, name, timezone (IANA), core-hours config version, band counts, per-occurrence timestamps (UTC and local), score, absolute delta, percent delta And aggregate metrics and configuration metadata (scenario id, baseline id, weights version, tzdb version, generated-at UTC) are included And CSV uses UTF-8 with RFC 4180 quoting and ISO 8601 timestamps; JSON adheres to a documented schema with explicit types And exports up to 10,000 rows complete in <= 5 seconds without freezing the UI And filenames include product, scenario id, and generated-at timestamp

DST and Timezone Profile Integration Accuracy

Given participants have IANA timezone IDs and profile history with effective dates When burden scores are computed across dates that include DST transitions or timezone changes Then local times reflect the correct offset per occurrence according to tzdb rules And nonexistent local times are skipped; ambiguous times are resolved to the post-transition offset by default (configurable) And past results remain stable after tzdb updates; future computations use the updated rules, recording the tzdb version in results And if a participant's timezone is missing or invalid, they are flagged and excluded from scoring with a clear error message

Rotation Equity Impact Visualizer

"As an ops leader, I want to see how a proposed time change will alter meeting ownership and fairness over the next several weeks so that we maintain a sustainable rotation."

Description

Model how each scenario affects the equity scoreboard and ownership rotation across upcoming instances. Display projected changes to cumulative burden, ownership frequency, and turn order, with alerts when a scenario violates fairness thresholds. Provide toggles to simulate different planning horizons (e.g., next 4/8/12 weeks). On commit, update the equity scoreboard and rotation plan atomically to maintain consistency with TimeMeld’s rotation engine. Include an API for downstream reporting and audit trail of changes.

Acceptance Criteria

Projected Equity Metrics Display

Given a candidate time shift scenario is selected and a planning horizon is set (e.g., 8 weeks) When the Rotation Equity Impact Visualizer renders projections Then it displays for every participant: current cumulative burden, projected cumulative burden, burden delta, current ownership frequency (count and % for the horizon), projected ownership frequency (count and %), current turn order for the next N instances, and projected turn order for the next N instances And all values are computed using the rotation engine’s timezone‑weighted rules for the selected horizon And burden delta values > 0 show a red up indicator, < 0 a green down indicator, and = 0 a neutral indicator And numeric values are rounded to one decimal place and match server calculations to that precision And the projection renders in ≤ 1000 ms for teams up to 30 participants and a 12‑week horizon

Horizon Toggle Recalculation (4/8/12 Weeks)

Given the user toggles the planning horizon between 4, 8, and 12 weeks When the horizon value changes Then ownership frequencies equal the number of meeting instances within [now, horizon) for each participant And cumulative burden values recompute for the new horizon and are non‑decreasing as the horizon length increases And the displayed turn order reflects the exact sequence of the next N instances within the selected horizon And the UI updates within ≤ 800 ms without losing the selected scenario or scroll position And the selected horizon is persisted in the session so returning to the simulator restores the last chosen value

Fairness Threshold Alerts

Given team fairness thresholds are configured (e.g., max burden variance %, max consecutive ownership count) When a simulated scenario violates any threshold Then an alert banner appears identifying each violated threshold, affected participants, and measured values vs limits And the alert includes a link or affordance to view the specific rows involved And clearing the violation (by adjusting inputs) removes the alert in real time without page reload And committing with active alerts triggers a confirmation modal summarizing the impacts before proceeding

Atomic Commit Updates to Scoreboard and Rotation Plan

Given a scenario has been reviewed and is ready to commit When the user clicks Commit Then the equity scoreboard and the rotation plan are updated in a single atomic transaction that produces a new versionId And if any part of the transaction fails, no changes are persisted and the UI shows a retriable error with correlationId And on success, the UI refreshes to show the updated scoreboard and turn order that match the last shown projections And concurrent commits are serialized; if a newer version exists than the previewed one, the commit is rejected with a non‑destructive conflict message prompting a refresh And the commit operation completes in ≤ 1500 ms for teams up to 30 participants and a 12‑week horizon

Audit Trail and Reporting API

Given a successful commit of a rotation change When the system records the event Then an immutable audit record is stored with: changeId, versionId, actorId, teamId, timestamp (UTC ISO8601), selected horizon, scenario parameters, pre‑commit metrics per participant, post‑commit metrics per participant, and fairness check results And a reporting endpoint GET /api/v1/rotation‑equity/changes exists with filters for date range, teamId, actorId, and cursor‑based pagination (limit, nextCursor) And the endpoint requires authentication; unauthorized requests return 401/403 without data And responses include a stable JSON schema with the above fields and a totalCount estimate And listing up to 100 records returns in ≤ 500 ms p95 And each record includes a SHA‑256 hash of the change payload for integrity verification

Projection Consistency with Rotation Engine

Given fixed team settings, calendar inputs, and fairness rules When the visualizer computes projections for a scenario and horizon Then cumulative burden per participant differs from the rotation engine output by ≤ 0.1, ownership frequencies match exactly, and the next N turn order positions match exactly And unit tests cover edge cases: uneven team sizes, mid‑horizon member join/leave, holiday skips, daylight‑saving transitions, and overlapping recurring series And projections for identical (scenario, horizon, inputs) are consistent across sessions within a 5‑minute window

Side-by-Side Scenario Comparison & Recommendation

"As a scheduler, I want to compare multiple candidate windows side-by-side and get a recommendation so that I can confidently pick the best option quickly."

Description

Enable creation and labeling of multiple what-if scenarios and render them in a side-by-side comparison view with sortable metrics: projected show-rate, burden index, and rotation impact. Provide a composite recommendation score with transparent weighting and allow users to adjust weights to reflect team priorities. Highlight the leading option per metric, flag conflicts, and offer a one-click Commit action that updates the meeting time and triggers TimeMeld’s invite automation. Persist user selections and record the decision rationale for future reference.

Acceptance Criteria

Create and Label Multiple What‑If Scenarios

Given a base meeting is loaded in Impact Simulator When the user creates multiple scenarios with distinct time shifts and labels Then the system allows creating at least 10 scenarios per meeting And each label is required, unique per meeting, 1–50 characters, and trimmed of leading/trailing spaces And attempting to save an invalid or duplicate label shows an inline error and prevents save And all created scenarios persist server‑side and reappear after page refresh or re-login

Side‑by‑Side Comparison with Sortable Metrics

Given 3 or more scenarios exist for the meeting When the user opens the Comparison view Then scenarios render in a grid with columns: Label, Projected Show‑Rate (%), Burden Index (0–100, lower is better), Rotation Impact (Δ fairness, higher is better), Composite Score And clicking any metric header sorts by that metric ascending/descending with a visible sort indicator And sorting completes within 300 ms for up to 50 scenarios And ties are secondarily sorted by Label A→Z

Composite Recommendation Score with Transparent Weighting and Adjustable Weights

Given the Comparison view is open with default weights applied When the user inspects the Composite Score formula Then the formula is displayed as Σ(normalized metric × weight) with per‑metric contributions visible on hover for each scenario And normalization treats higher Projected Show‑Rate and higher Rotation Impact as better, and lower Burden Index as better And the user can adjust weights for each metric from 0–100% in 1% increments, and total weight must sum to 100% And changes to weights update all Composite Scores and the Recommended badge within 250 ms And weight settings persist per user per meeting and are restored on revisit

Highlight Leaders Per Metric and Flag Conflicts

Given the Comparison grid is visible When metrics are calculated Then the leading scenario per metric is visually highlighted (max Projected Show‑Rate, min Burden Index, max Rotation Impact) And if different scenarios lead different metrics, a conflict banner appears summarizing which scenarios lead which metrics And selecting the conflict banner filters the grid to the involved scenarios And if the composite recommendation differs from any single-metric leader, an info callout explains the trade‑off with numeric weight contributions

One‑Click Commit Updates Meeting and Triggers Invites

Given the user has edit permission and a scenario is selected When the user clicks Commit Then the meeting time is updated to the scenario’s time and stored atomically with scenario ID and applied weights And TimeMeld invite automation triggers within 30 seconds, sending calendar updates to all attendees And the UI displays a success state with the new time and a link to the updated calendar event And on any failure, the system rolls back to the prior meeting time, shows a descriptive error, and offers a retry without partial state left behind

Persist Selections and Decision Rationale

Given a recommended scenario is selected When the user enters a decision rationale (up to 500 characters) and saves or commits Then the selection, applied weights, rationale, timestamp, and user are stored in the meeting’s Decision History And the most recent committed decision is labeled Current and appears at the top of the history And saved rationales are immutable after commit and visible to all users with access to the meeting

Access Control and Concurrency Safety

Given multiple users are viewing the same meeting in Impact Simulator When a user without edit permission attempts to adjust weights or commit Then those controls are disabled with a tooltip explaining required permissions And when two editors attempt to commit different scenarios concurrently Then exactly one commit succeeds; the other user receives a notice that the meeting was updated by <user> at <timestamp>, and their view refreshes to the committed scenario

Scenario Save, Share, and Commenting

"As a distributed team member, I want to share and discuss proposed meeting times with stakeholders so that we can reach alignment before committing."

Description

Allow users to save named scenario sets with metadata (owner, meeting series, created date) and share view/edit access with teammates or roles. Support inline comments, mentions, and attachments (e.g., policy links), plus version history to track changes. Provide secure, expiring share links and respect organization permission models. Integrate notifications with email/Slack to request reviews and capture approvals before committing a scenario. Store artifacts in TimeMeld for auditability and enable reloading scenarios later to re-run with updated data.

Acceptance Criteria

Save Named Scenario Set with Metadata and Initial Version

Given I have generated Impact Simulator results for a meeting series When I click "Save Scenario", enter a non-empty unique name within my org and meeting series, and confirm Then the system persists a scenario set with fields: id, name, owner=current user, meetingSeriesId, createdAt=UTC ISO-8601, version=1, and a read-only snapshot of inputs and computed metrics (show-rate lift, timezone burden, rotation effects) And Then saving a duplicate name within the same org and meeting series is rejected with a validation error and no record is created And Then the scenario appears in my scenario list within 2 seconds (p95) and is retrievable by id via API/UI And Then the API returns 201 Created with the scenario id, or 400 with field-level errors if validation fails

Share Access with Users and Roles (View/Edit) Respecting Org Permissions

Given a saved scenario set owned by me When I open Share settings and grant View or Edit access to specific users and/or roles within my org Then only principals with granted access can open the scenario; others in my org receive 403 and non-org users receive 404 And Then Viewers cannot modify scenario, comments, or permissions; Editors can modify scenario and comments but cannot delete the scenario unless explicitly allowed And Then role-based grants apply to all current members immediately and reflect membership changes within 5 minutes And Then I can revoke any grant, after which access is removed within 60 seconds and subsequent requests return 403

Secure Expiring Share Links

Given I have a saved scenario set When I generate a share link specifying permission level (View or Edit) and an expiry (24h, 7d [default], or 30d) Then the system issues a single-use tokenized URL bound to my org that requires authenticated access and enforces the selected permission And Then the link displays its creation and expiry times, and expires at the configured time; after expiry, requests return 410 Gone And Then I can manually revoke the link, invalidating the token within 60 seconds; revoked links return 410 And Then all link accesses are logged with actor, timestamp, and IP for audit retrieval

Inline Comments with Mentions, Threads, and Attachments with Notifications

Given I have at least View access to a scenario When I add a comment or reply in a thread Then the system stores the comment with author, timestamp, and version context and displays it in chronological order And Then I can edit my comment for up to 10 minutes; subsequent edits create a visible revision history And Then mentioning @users is auto-suggested; posting a mention notifies the mentioned users via Slack (if connected) or email within 1 minute and includes a deep link to the thread And Then attachments (PDF, DOCX, PNG, JPG, TXT, CSV) up to 25 MB each (max 5 per comment) are virus-scanned; infected uploads are blocked with an error And Then attempting to mention a user without access prompts to grant access; if declined, the mention cannot be posted

Review Requests and Approval Gate Before Commit

Given I have a saved scenario that requires approval before commit When I click "Request Review" and select approvers and a required approval count (default 1) Then approvers are notified via Slack/email with Approve/Request Changes actions and a deep link to the scenario And Then commit actions remain disabled until the required number of approvals is recorded and there are no open change requests And Then each approval records approver id, timestamp, scenario version, and comment; approvals are invalidated automatically when a new version is saved And Then if any approver requests changes, the scenario status reflects "Changes Requested" and notifications are sent to the owner

Version History, Diff, Restore, and Re-run with Latest Data

Given a scenario with one or more saved versions When I save changes Then a new version number increments by 1 and records author, timestamp, and change summary And Then the Version History view displays versions and a diff of inputs and computed metrics between any two versions within 2 seconds (p95) for up to 100 versions And Then choosing Restore on a prior version creates a new version that reproduces the restored inputs and notes the source version And Then selecting "Re-run with Latest Data" recomputes metrics using current org data and saves results as a new version linked to the originating version

Auditability and Export of Scenario Artifacts

Given scenarios, comments, shares, approvals, and version events are generated When an org admin queries the audit log for a date range Then the system returns a chronological record of create/edit/share/comment/approval/access events with actor, timestamp (UTC), and IP/user agent And Then admins can export a scenario set (current or a selected version) as JSON via API and UI download, with export completing within 10 seconds for scenarios under 5 MB And Then all scenario artifacts are stored in TimeMeld and remain retrievable for at least 12 months unless deleted per org retention policy

Auto Rebalance

Apply the chosen time shift to the whole series in one click. Calendars update, conferencing links persist, localized notices go out, and equity rules stay intact—with a built‑in rollback if priorities change.

Requirements

One-click Series Time Shift

"As a product manager coordinating a recurring cross-timezone meeting, I want to apply a single time shift to the entire series so that I can quickly realign schedules without manually editing each instance."

Description

Implements a bulk time-shift action that applies a selected delta or target anchor time to an entire recurring meeting series in one step. Validates the shift against TimeMeld’s timezone-weighted ergonomic rules (working-hour windows, rotation preferences, and regional holidays), preserves series exceptions, and previews the resulting schedule before confirmation. Integrates with the scheduling engine to recalculate proposed times and with the series model to ensure stable recurrence IDs. Minimizes manual edits, speeds coordination, and guarantees consistent application across all future instances.

Acceptance Criteria

One-Click Delta Shift Across Future Instances

- Given a recurring series with future instances and a selected time delta, When the user clicks Apply Shift, Then exactly all future instances move by the delta and past instances remain unchanged. - Then canceled instances remain canceled and no new instances are created or deleted. - Then each instance retains its UID/recurrenceId, conferencing link, attendees, and attachments. - Then the preview and the post-apply summary display the exact count of impacted instances and attendees. - Then instance times respect local timezone and DST transitions for all attendees.

Anchor-Time Shift With Ergonomic Validation and Preview

- Given a target anchor time is chosen, When the preview is generated, Then the scheduling engine recomputes proposed times respecting working-hour windows, rotation preferences, and regional holidays per configured rules. - Then each instance’s ergonomic score meets or exceeds the configured minimum; any violations are listed with reason tags (e.g., outside-hours, holiday-conflict, rotation-break). - Then hard-rule violations block confirmation (Confirm disabled) until resolved; soft-rule warnings allow confirmation with explicit user acknowledgement. - Then the preview shows before/after times per instance and a summary of rule outcomes.

Preservation of Series Exceptions and Per-Instance Overrides

- Given some instances have per-instance overrides (time, location, attendees, conferencing link) and some are canceled, When the shift is applied, Then those overrides persist and are not overwritten except for the base start-time offset. - Then canceled instances stay canceled and declined responses remain unchanged. - Then organizer and invitees lists are unchanged unless modified by an override. - Then no duplicate conferencing links are created; series-level links and per-instance links remain the same.

Calendar Updates and Localized Notifications

- Given the shift is confirmed, Then calendar entries for all attendees across connected providers are updated within 60 seconds at the 95th percentile and without creating duplicate events. - Then conference join URLs remain unchanged in all updated events. - Then each attendee receives a single localized notification (email/push) containing the new local time, language based on their locale, and an updated ICS; no attendee receives more than one notification for the same change. - Then notification delivery failures are surfaced with counts and retried according to the system’s retry policy.

Equity Rules Integrity Post-Shift

- Given the series uses equity rotation rules and a shared scoreboard, When the shift is applied, Then the rotation order and instance ownership assignments remain identical to the pre-shift plan. - Then per-participant equity metrics recompute for the new times but continue to satisfy configured equity constraints (no additional ownership assigned due to the shift). - Then the scoreboard view reflects updated times while preserving ownership slots and totals.

Rollback of Series Time Shift

- Given a shift was applied, When Rollback is invoked within 24 hours or before any subsequent manual edit to the series, Then all future instances revert to their exact pre-shift state (times, invites, notifications, overrides). - Then calendars reflect the rollback within 60 seconds at the 95th percentile, and attendees receive a single localized rollback notice. - Then audit logs link the rollback to the original shift via a correlation ID and capture counts of reverted instances and attendees.

Access Control, Performance, and Reliability

- Given a user without Manage Series permission attempts a shift, When they try to confirm, Then the action is blocked with a descriptive error and no changes are made. - Given a series with up to 500 future instances and up to 200 attendees, When a preview is requested, Then it completes within 5 seconds at the 95th percentile; When Apply is confirmed, Then the operation completes within 60 seconds at the 95th percentile. - Then the operation is idempotent by correlation ID, retries transient provider failures with exponential backoff, and reports a final success with counts or a failure with actionable error reasons without partial silent misapplies.

Cross-calendar Sync & Conflict Resolution

"As an engineering lead, I want the rebalance to update everyone’s calendars and resolve conflicts automatically so that attendance stays high and I don’t have to chase individual rebookings."

Description

Propagates the approved series shift to all participant calendars (Google, Outlook, iCloud) with idempotent updates, batched writes, and retries. Detects per-attendee conflicts at the new time, proposes nearest ergonomic alternatives within allowed windows, and flags hard conflicts for owner review. Maintains instance-level metadata (titles, agendas, notes, attachments) and preserves per-occurrence edits where compatible. Ensures ICS UID continuity and sends only differential updates to reduce churn and double-booking risk.

Acceptance Criteria

Idempotent Series Shift Across Google/Outlook/iCloud

Given a recurring meeting series with a stable ICS UID and attendees on Google, Outlook, and iCloud And Auto Rebalance proposes a +60 minute shift to all future occurrences When the owner approves the shift Then the system applies batched, provider-specific writes and preserves the same ICS UID for the series and occurrences And updates are idempotent such that re-running the operation produces no additional changes And all attendee calendars reflect the new start/end times within 5 minutes of approval And no duplicate events or duplicate email invites are created And failed writes are retried with exponential backoff up to 3 times per attendee before surfacing an error to the owner

Per-Attendee Conflict Detection and Alternative Proposals

Given at least one attendee is busy at the proposed new time When the sync runs after Auto Rebalance approval Then the attendee is marked as "conflict" and the owner is notified And up to 3 nearest ergonomic alternatives within the allowed scheduling window are proposed, scored by timezone ergonomics And a "hard conflict" is flagged if no viable alternative exists within the window And non-conflicted attendees remain scheduled at the approved new time And a consolidated conflict summary is posted to the series owner for review

Preserve Per-Occurrence Edits and Series Metadata

Given the series has titles, agendas, notes, attachments, and per-occurrence overrides When the series shift is applied Then series-level metadata remains unchanged except for start/end time fields And per-occurrence edits persist unless the edited field directly conflicts with the time shift, in which case only time fields are updated And previously canceled/skipped occurrences remain canceled and are not resurrected And attendee response statuses and conferencing links remain unchanged

Differential ICS Updates and UID Continuity

Given the series shift is approved When calendar updates are sent to providers via iTIP/CalDAV/Graph APIs Then the same ICS UID is used with an incremented SEQUENCE for each changed occurrence And only differential fields (time and sequence) are transmitted; no CANCEL+ADD is performed And each attendee receives at most one update notification per changed occurrence And no new invitation thread is created on Google, Outlook, or iCloud

Localized Notices and Conferencing Link Persistence

Given attendees have stored locale and timezone preferences When notices are dispatched for the approved shift Then each attendee receives a notice in their locale within 2 minutes of approval And the notice displays the new time in both organizer timezone and attendee local timezone And existing conferencing links (e.g., Google Meet/Zoom) remain unchanged in both the event and the notice And links are functional from the updated calendar entries

Rollback of Series Shift

Given the owner initiates a rollback within 24 hours of the applied shift When rollback executes Then all attendee calendars revert to the pre-shift schedule using the same ICS UID with incremented SEQUENCE And per-occurrence edits are restored to their pre-shift state And localized rollback notices are sent to all attendees within 5 minutes And the rollback is idempotent; re-running it produces no additional changes And an audit log entry records the initiator, timestamp, and affected occurrences

Conferencing Link Preservation

"As a remote engineer, I want the meeting link to remain the same after a series shift so that I can join without hunting for new dial-in details."

Description

Maintains continuity of conferencing details (Zoom, Google Meet, Teams) across the rebalance by retaining the existing meeting link, passcodes, and dial-ins while updating time and description fields. Handles provider-specific constraints (recurring vs. single-use links), regenerating links only when required (e.g., expired or revoked) and migrating security settings intact. Ensures join information stays consistent across calendar systems and notifications to prevent broken links and attendee confusion.

Acceptance Criteria

Preserve Existing Conferencing Link on Series Rebalance

Given a recurring meeting series with a valid conferencing link (Zoom/Google Meet/Microsoft Teams), passcode, and dial-ins on the organizer’s event and propagated to all instances And at least one attendee uses a different calendar system (Google, Outlook, or Apple Calendar) When Auto Rebalance shifts the entire series time without changing recurrence rules Then the conferencing join URL, meeting ID, passcode, and dial-ins remain exactly unchanged across all instances And the event start/end times and description/location fields update without duplicating or removing the join information And no new conferencing resource/meeting is created with the provider And attendee invites/updates preserve an identical join block to the pre-rebalance state

Regenerate Only When Link Invalid or Revoked

Given the existing conferencing link is detected as invalid (expired, revoked, deleted, or provider returns 4xx indicating non-existent) at rebalance time When Auto Rebalance is applied Then a new conferencing link is generated with the same provider And equivalent security settings (e.g., waiting room/lobby, passcode policy, authenticated users) are copied to the new meeting And the old join details are fully replaced atomically in the calendar event And all attendees receive an update indicating a new conferencing link is in effect And audit logs record the reason code and old/new meeting identifiers And there is no state in which recipients can access a broken link from the updated invite

Honor Provider-Specific Link Constraints

Given a Zoom scheduled meeting (non-PMI) is attached to the series When Auto Rebalance shifts the series time Then the Zoom join URL and meeting ID remain unchanged and no new meeting is created Given a Google Meet link is attached to the series When Auto Rebalance shifts the series time Then the Meet code and conferenceSolutionId remain unchanged Given a Microsoft Teams meeting is attached to the series with custom meeting options When Auto Rebalance shifts the series time Then the Teams join URL and meeting options persist unchanged

Cross-Calendar Join Info Consistency After Rebalance

Given attendees include users on Google Calendar, Outlook/Exchange (via Microsoft 365/Graph), and Apple Calendar consuming an .ics When Auto Rebalance completes and updates are delivered Then each attendee’s calendar displays the same conferencing URL, passcode, and dial-ins as the organizer’s event And no duplicate or conflicting join information appears across description, location, or conferencing fields And a single conferencing link is present in the .ics payload and renders correctly in Apple Calendar

Rollback Restores Prior Conferencing State

Given a series was rebalanced and a rollback is initiated within the supported rollback window When the rollback executes Then event times and textual fields revert to the pre-rebalance state for all instances And if the original conferencing link was valid at rebalance time, that same link is preserved after rollback And if a new link was generated due to invalidation during rebalance, that regenerated link is retained after rollback And attendees receive a single update reflecting the rollback with no broken or missing join information

Security Settings Migration on Regeneration

Given the meeting has security settings configured on the provider (e.g., waiting room/lobby enabled, passcode complexity, presenters/speakers restrictions, authenticated users required) When Auto Rebalance requires link regeneration Then the regenerated meeting inherits equivalent security settings And no setting becomes less restrictive than before And verification via provider API confirms the applied settings post-regeneration

Localized Notices & Acknowledgements

"As an ops lead, I want localized notices with quick acknowledgement options so that everyone understands the change in their own timezone and can confirm attendance promptly."

Description

Sends localized notifications to all participants with the new schedule in their local time, preferred language, and chosen channels (email, Slack/Teams). Includes a concise summary of what changed, relative time deltas, and quick RSVP/acknowledge controls. Supports delivery windows aligned to recipients’ working hours, throttling to avoid notification spam, and fallbacks for bounced or delayed messages. Updates calendar invitations and posts confirmation receipts back into the meeting thread for auditability.

Acceptance Criteria

Language and Timezone Localization of Notices

- Given a recipient with preferred language fr-FR and timezone Europe/Paris, when a series rebalance triggers a notice, then the notice renders in French and all date/times display in Europe/Paris using fr-FR locale formatting. - Given a recipient with no language preference, when a notice is sent, then the notice defaults to English (en-US) and uses the recipient's stored timezone; if none exists, UTC is used and a preference-missing event is logged. - Given a recipient with an unsupported language code, when a notice is generated, then the system falls back to the nearest supported locale or English and records the fallback locale used in telemetry. - Given recipients across multiple timezones, when the same rebalance notice is sent, then each recipient sees local times that map to the same absolute timestamp with zero drift (verified within ±1 second).

Multichannel Delivery: Email, Slack, and Teams

- Given a recipient with channels email and Slack selected, when a rebalance notice is issued within working hours, then both email and Slack messages are delivered within 2 minutes and contain equivalent content (title, old/new local times, delta, RSVP controls). - Given a recipient with Teams selected only, when a notice is sent, then exactly one Teams message is delivered and no email/Slack messages are sent. - Given channel-specific templates, when notices are generated, then links and interactive controls are functional per channel (email: actionable buttons/ICS link; Slack/Teams: interactive actions) and pass a click test with <2% template rendering error rate across supported clients. - Given per-user channel preferences updated within the last 5 minutes, when a notice is sent, then the latest preferences are honored with no stale channel deliveries.

Relative Time Delta Summary Correctness

- Given a meeting moved from 2025-10-01T09:00 to 2025-10-01T10:30 local time, when the notice is composed, then the summary includes: Was: 09:00, Now: 10:30, Change: +90m (same day). - Given a move that crosses day boundaries in the recipient's timezone, when the notice is composed, then the delta indicates day change (e.g., +30m next day or -45m previous day) and matches computed difference within ±1 minute accounting for DST. - Given DST transitions, when a series instance shifts, then the delta calculation uses absolute UTC timestamps to compute change and the displayed local times reflect correct DST offset. - Given multiple recipients in different timezones, when notices are sent, then each notice's Was/Now times differ by timezone but the numeric delta is identical across recipients.

Delivery Windows and Notification Throttling

- Given a recipient with a delivery window of 09:00–17:00 local, when a rebalance occurs at 20:00 local, then the notice is scheduled for 09:00 next business day and not delivered immediately. - Given multiple rebalances within 10 minutes for the same series, when notices are generated, then at most one notice is sent per recipient and subsequent notices are collapsed into a single consolidated update. - Given more than 3 notices queued for a recipient within 24 hours across all series, when generating notices, then additional notices are aggregated into a digest delivered at the next delivery window start with a count of collapsed changes. - Given a scheduled notice awaiting the delivery window, when the meeting start is <2 hours away, then the notice is promoted for immediate delivery and this exception is recorded in telemetry.

Bounced/Delayed Message Fallbacks

- Given an email hard bounce or a 5xx provider error, when detected, then the system retries up to 3 times with exponential backoff within 10 minutes and, if still failing, sends the notice via the recipient's next available channel (Slack or Teams) and logs the fallback. - Given a Slack/Teams delivery timeout >5 minutes, when detected, then the system retries once and, upon continued failure, sends the notice via email with the same content and marks the original attempt as failed. - Given all channels fail, when escalation completes, then the system creates an admin alert event with recipient, series, error codes, and last attempt timestamp. - Given a fallback was used, when the meeting thread receipt is posted, then it includes the original channel failure and the successful fallback channel used.

RSVP/Acknowledge Controls and State Recording

- Given a recipient clicks Yes/No/Maybe or Acknowledge in any channel, when the action is received, then the response is recorded within 60 seconds and a confirmation is shown to the user in the same channel. - Given multiple responses from the same recipient across channels, when processed, then the first response received is authoritative and subsequent responses return an idempotent confirmation showing the current recorded status. - Given a recorded RSVP, when syncing with the calendar provider, then the attendee response on the calendar event updates to match within 2 minutes without creating a duplicate event. - Given the meeting time changes again before the recipient responds, when the user attempts an old action link, then the system displays a stale-action message and provides updated controls for the latest schedule.

Calendar Invitation Update and Thread Confirmation

- Given a series time shift is applied, when notices are sent, then the corresponding calendar invitations update for all participants within 5 minutes, preserving the original conferencing link and meeting ID. - Given an update to the calendar invitation, when delivered, then the organizer and attendees see a single updated event instance per occurrence rather than duplicates in their calendars. - Given all notices for a rebalance are dispatched, when posting to the meeting thread (Slack/Teams/email thread), then a confirmation receipt is posted containing timestamp, message IDs per channel, delivery counts (sent/succeeded/failed), and any fallbacks used. - Given audit requirements, when a receipt is posted, then it is retained and retrievable for at least 90 days with immutable event metadata.

Equity Rules Preservation & Rotation Balance

"As a distributed team lead, I want the rebalance to keep fairness intact so that inconvenient time slots are shared equitably over time."

Description

Recalculates and enforces TimeMeld’s equity model during rebalance so that the shift does not disproportionately burden one region or role. Adjusts the shared equity scoreboard, enforces configured fairness thresholds, and updates future rotation ownership accordingly. Provides a pre-commit impact preview (credits/debits by cohort), prevents shifts that violate policies unless explicitly overridden, and logs changes to maintain transparency with the team.

Acceptance Criteria

Pre-Commit Equity Impact Preview

Given a proposed series time shift and an active equity policy configuration When the user opens the Impact Preview Then the preview displays, for each cohort (e.g., region, role), the projected credit/debit totals for the next 12 weeks And shows the delta versus the current plan per cohort and per participant And the sum of all credits/debits across cohorts equals zero within ±1 credit And any cohort projected to exceed a configured fairness threshold is highlighted with the specific metric and threshold value And the preview renders within 2 seconds for series with ≤ 52 occurrences And the preview includes the top 5 changes to rotation ownership that would result from the apply

Fairness Threshold Enforcement and Override

Given a proposed shift that would cause any cohort’s projected burden to exceed its configured threshold for the evaluation window When the user selects Apply Rebalance Then the system blocks the action and displays a descriptive violation message listing offending cohorts, metrics, and threshold values And the Apply control is replaced by an Override with Reason control only for users with OverrideEquity permission And entering a non-empty reason of at least 10 characters enables the Override action And on override, the rebalance proceeds and an audit entry is stored capturing the reason and permissioned user And for users without permission, no override control is displayed and the action remains blocked

Equity Scoreboard and Rotation Update on Apply

Given a successful rebalance apply When the operation completes Then the equity scoreboard updates with new credit/debit totals per participant and per cohort And future rotation ownership for the next N meetings (configurable; default 8) is recalculated and persisted And no participant is assigned more than the configured maximum consecutive inconvenient slots And updates are visible in both UI and API within 5 seconds of apply completion And meeting records reflect updated ownership annotations for the affected occurrences

Comprehensive Audit Logging and Transparency

Given any rebalance attempt (blocked, applied, or overridden) When the event occurs Then an immutable audit record is created capturing: user, timestamp (UTC), proposed shift, policy version, pre- and post- credit/debit per cohort, rotation changes, decision (Blocked/Applied/Overridden), and reason (if override) And the record is queryable via Audit API and UI within 10 seconds of the event And audit records can be exported as CSV including all captured fields And audit entries include a correlation ID linking preview → decision → apply/rollback events for traceability

Rollback Restores Equity State

Given a previously applied rebalance When a user with ManageRebalance permission initiates Rollback within 30 days of the apply Then the equity scoreboard, cohort aggregates, and rotation ownership are restored exactly to the pre-apply state And all credits/debits introduced by the apply are reversed without duplication And a rollback audit entry is created linking to the original apply via correlation ID And no participant retains any net equity change after rollback completes And the restore completes within 10 seconds for series with ≤ 52 occurrences

DST and Local-Time Ergonomics Compliance

Given a series rebalance that spans a Daylight Saving Time transition for any participant locale When impact is calculated and the rebalance is applied Then early/late burden scoring uses each participant’s local wall-clock time per occurrence And preview and post-apply credit/debit allocations reflect DST transitions correctly (no artificial gains/losses from clock shifts) And fairness thresholds are enforced against ergonomic windows defined in policy for each locale And no participant exceeds the configured monthly quota of inconvenient slots due to the DST transition

One-click Rollback with Audit Trail

"As a product manager, I want a one-click rollback if priorities change so that I can safely return to the prior schedule without causing confusion."

Description

Provides an immediate undo action that reverts the series to its previous schedule baseline, restoring calendar events, conferencing details, notifications, and equity ledger state. Supports safe rollback windows, conflict-aware reversal (with prompts if new conflicts emerged), and idempotent operations to avoid duplication. Captures who initiated the rollback, reason, timestamps, and diffs for compliance and postmortems.

Acceptance Criteria

Immediate Undo Restores Previous Series Baseline

Given a rebalanced recurring series with a captured pre-rebalance snapshot When the owner clicks "Rollback" within the allowed window Then all future instances are restored to the exact pre-rebalance start/end times, participants, recurrence pattern, titles, and descriptions And conferencing details are restored to the pre-rebalance values for each instance And the equity ledger state is restored to the pre-rebalance values And no duplicate or orphaned calendar events remain in any attendee calendar And the rollback completes within 10 seconds for series with ≤ 50 future instances or a progress indicator remains visible until completion And the UI displays a success message summarizing the number of instances restored

Safe Rollback Window Enforcement and Partial Revert

Given a configured rollback window from the last Auto Rebalance When the current time is outside the rollback window Then the "Rollback" action is disabled with a tooltip explaining the expiry and window policy When inside the window and some instances have started or completed Then only future instances are reverted and past instances remain unchanged And a confirmation modal lists the count of instances that will be reverted and the count excluded due to being in the past And the action requires explicit confirmation before execution

Conflict-Aware Reversal with User Prompt

Given TimeMeld detects new conflicts at the pre-rebalance times (created after the rebalance) When the user initiates "Rollback" Then a preflight scan identifies conflicted instances and attendees and displays a summary modal with counts and names And the user can choose to proceed, cancel, or exclude conflicted instances from rollback When the user proceeds Then rollback executes and conflicted instances are restored and marked with a conflict flag in TimeMeld And if the user cancels Then no changes are made

Idempotent and Concurrent Rollback Protection

Given a rollback for the same series and rebalance has already completed When the rollback is triggered again using the same operation context Then the system performs a no-op and returns a deduplicated response And no additional events, notifications, or audit entries are created When two rollback requests occur concurrently Then only one executes and others return a reference to the completed operation And the final series state checksum matches the pre-rebalance snapshot checksum

Audit Trail Capture and Diff

Given a rollback is executed When the audit log is queried by series ID Then it contains an immutable entry with initiator user ID, role, IP, timestamps (start/end), reason text (required), operation ID, and outcome (success/failure) And the entry includes diffs of schedule (instance datetime changes), equity ledger deltas, notification dispatch results, and counts of events restored/created/deleted And the audit entry is exportable (JSON and CSV) and viewable in the admin UI And if the rollback fails Then the audit entry includes error codes and any partial effects recorded

Localized Rollback Notifications

Given attendees have locale and time zone preferences When a rollback completes Then each attendee receives a localized notification in their preferred language with restored date/time in their local time zone And only one notification per instance per attendee is sent And the conferencing link in each notification matches the restored instance details And notification delivery status is recorded and linked in the rollback audit entry

Rebalance Permissions & Safeguards

"As a workspace admin, I want controls and guardrails on who can trigger a rebalance so that large-scale schedule changes are safe and intentional."

Description

Introduces granular permissions and safeguards around rebalancing, including role-based access control, optional approval workflows for org-wide series, confirmation gates (summary of impacts, affected attendees, equity changes), and processing locks to prevent concurrent edits. Adds observability with progress indicators, error surfacing, and recovery paths for partial failures, plus feature flags to roll out the capability incrementally.

Acceptance Criteria

RBAC: Only authorized roles can initiate Auto Rebalance

Given a user without the Rebalance:Apply permission, When they attempt to rebalance a series via UI or API, Then the action is blocked, the UI control is hidden or disabled, the API responds 403, and no series changes occur. Given a user with Rebalance:Apply permission scoped to specific series, When they attempt to rebalance a series outside their scope, Then the action is blocked as above. Given a user with Rebalance:Apply permission for the target series, When they open the series, Then the Auto Rebalance control is visible and enabled. Given any rebalance attempt, When executed, Then an audit log entry is created capturing initiator ID, timestamp, series ID, scope, pre/post equity metrics, and outcome (success/failure).

Approval workflow required for org-wide or approval-gated series

Given a series that is org-wide or configured to require approval, When a non-exempt user initiates Auto Rebalance, Then an approval request is created, the job status is set to Pending Approval, and execution is blocked until approval. Given a designated approver receives the request, When they approve, Then the rebalance transitions to Executing and the requester is notified. Given the approver rejects the request, Then no changes occur to the series, the status becomes Rejected, and the requester is notified. Given an approval request reaches its configured expiration without action, Then it auto-expires, no changes occur, and both requester and approver are notified.

Confirmation gate summarizes impacts before execution

Given an eligible user initiates Auto Rebalance, When the confirmation gate opens, Then it displays: number of occurrences affected, date range, per-timezone time shifts, impacted attendees, conferencing link retention status, and projected equity score changes for the rotation. Given required approval is detected, When showing the confirmation gate, Then the gate indicates that approval is required and who can approve. Given the user clicks Confirm, Then the rebalance starts; Given the user cancels or closes the gate, Then no changes occur and no notifications are sent. Given stale data or permission changes are detected at confirmation, When the user clicks Confirm, Then the gate re-validates and blocks execution with a clear error and next steps.

Processing locks prevent concurrent edits and rebalances

Given an Auto Rebalance is executing for a series, When any user attempts to edit the same series or start another rebalance, Then the API responds 423 Locked and the UI shows "This series is being updated" with the active job ID. Given a processing lock is set for a series, When the job completes successfully, Then the lock is released; When the job fails, Then the lock is released and failure details are recorded for recovery. Given repeated requests with the same idempotency key, When submitted during or after execution, Then only one execution occurs and subsequent requests return the original outcome without side effects. Given overlapping rebalances are attempted across series that share the same conferencing resource, When a conflict is detected, Then only the earliest lock holder proceeds and others receive a clear locked/conflict response.

Progress indicators, error surfacing, and recovery paths for partial failures

Given a rebalance has started, When the user views the job drawer, Then a step-wise progress indicator shows current phase (Validating, Scheduling, Updating Calendars, Notifying, Equity Update, Done) and percentage complete. Given a partial failure occurs (e.g., some occurrences fail to update), When viewing the job details, Then per-occurrence error messages and affected attendees are listed with actionable guidance. Given partial failures exist, When the user selects "Retry failed only", Then only failed operations are retried with idempotency and updated outcomes are reflected in the job details. Given any changes were applied by the rebalance, When the user initiates "Rollback all changes" within the retention window, Then all changes made by the job are reversed, conferencing links persist, equity is restored, and rollback notifications are sent to affected attendees.

Feature flag gates incremental rollout of Auto Rebalance

Given the Auto Rebalance feature flag is disabled for an org/workspace, When users access a series, Then Auto Rebalance controls are not visible and API endpoints return 404 or 403 with no side effects. Given the feature flag is enabled for an allowlisted cohort, When eligible users access a series, Then Auto Rebalance controls are visible and functional; ineligible users cannot access them. Given the feature flag state changes, When a user refreshes the app or makes a new API call, Then the new state is respected without deployment or app update. Given analytics are enabled, When the feature flag toggles, Then exposure and usage events are logged with org/workspace and user identifiers for auditability.

Cohort Lenses

Slice drift by role, team, seniority, meeting type, or internal/external cohorts to pinpoint who’s slipping and why. Target interventions where they matter most instead of blanket changes that disrupt everyone.

Requirements

Cohort Definition Engine

"As a product ops lead, I want to create dynamic cohorts based on roles, teams, seniority, and meeting types so that I can analyze scheduling drift for the right groups without manual list maintenance."

Description

Provides a rules-based builder to define cohorts using user and meeting attributes (role, team, seniority band, timezone, location, meeting type, internal vs external, organizer/attendee, product area). Supports inclusion/exclusion lists, boolean logic, dynamic membership, and custom tags. Cohorts auto-refresh as attributes change and maintain version history for reproducibility. Validates each cohort against data availability and minimum size thresholds. Exposes cohort identifiers for reuse across analytics, recommendations, alerts, and APIs.

Acceptance Criteria

Boolean Rule-Based Cohort Creation (User and Meeting Attributes)

Given a user with cohort-creation permissions And the following attributes are available for filtering: role, team, seniority band, timezone, location, meeting type, internal/external, organizer/attendee, product area When the user defines a cohort using AND/OR/NOT with parentheses across these attributes And saves the definition with a cohort name and description Then the system validates the rule syntax and returns clear, actionable errors for any invalid expression And the cohort is created with a unique cohort_id and persisted definition And the initial member list is computed and the member count matches the evaluation of the rule And operator precedence and parentheses are respected during evaluation

Dynamic Membership Auto-Refresh on Attribute Changes

Given a cohort defined by attribute-based rules And a member’s underlying attribute (e.g., role, team, timezone) changes When the attribute change event is ingested Then the cohort membership is recalculated and updated within the next refresh cycle (<= 10 minutes) And the member is added or removed accordingly with a timestamped audit entry And no manual rebuild is required by users

Inclusion and Exclusion Lists Precedence

Given a cohort with a base rule And an inclusion list and an exclusion list are specified by user identifiers When membership is computed Then users on the exclusion list are not included even if they match the base rule And users on the inclusion list are included even if they do not match the base rule And if a user appears on both lists, exclusion takes precedence And each member’s record includes a reason code (rule, inclusion_override, exclusion_override)

Minimum Size and Data Availability Validation

Given configured thresholds for minimum cohort size and attribute coverage When a user attempts to save a cohort definition Then the system estimates member count for the current data set And if the estimate is below the configured minimum size threshold, the save is blocked with a clear message and guidance to broaden criteria And if any required attribute coverage is below the configured coverage threshold, a non-blocking warning is shown identifying low-coverage fields And the user can proceed past warnings but not blocking errors

Version History and Reproducibility

Given an existing cohort When a user edits the cohort’s rule or metadata and saves changes Then a new immutable version is created with version number, editor, timestamp, and a diff of rule changes And the prior versions remain accessible and cannot be altered And users can retrieve any version’s definition and recompute membership as of that version’s timestamp for reproducibility And reverting to a prior version creates a new version entry rather than overwriting history

Cohort Identifier Exposure Across Analytics, Recommendations, Alerts, and APIs

Given a created cohort with versions When accessing analytics, recommendation engines, alert configurations, and the public API Then the cohort_id and version_id are available as selectable filters/parameters And API endpoints return consistent membership for the specified version_id or the latest version And access controls are enforced so only authorized users can query or use the cohort identifiers And identifiers are stable and unique within the workspace

Custom Tags and Catalog Searchability

Given a cohort When a user adds, edits, or removes custom tags on the cohort Then tags are saved and immediately associated with the cohort metadata And searching or filtering the cohort catalog by tag or keyword returns the cohort And tags are included in cohort metadata responses from the API

Directory & HRIS Attribute Sync

"As an IT admin, I want TimeMeld to automatically sync user attributes from our directory and HRIS so that cohorts stay accurate without manual updates."

Description

Integrates with Google Workspace, Okta/Azure AD, Slack, and HRIS systems (e.g., Rippling, BambooHR) to ingest user attributes (role, team, manager, seniority, location/timezone, employment status) and map them to calendar identities. Implements secure OAuth or key-based connections, scheduled full sync with near‑real‑time delta updates, schema mapping, and conflict resolution. Provides data lineage, backfill capability, retry logic, and alerting on schema drift. Normalizes timezones and enforces attribute validation to ensure accurate cohort membership.

Acceptance Criteria

Provider Connections via OAuth/API Key

Given an org admin initiates a connection to a supported provider (Google Workspace, Okta, Azure AD, Slack, Rippling, BambooHR), When the flow is completed, Then the system establishes the connection using OAuth 2.0 where available or API key otherwise and records connection status as Active. Given a connection is established, When credentials are stored, Then tokens/keys are encrypted using KMS, are not retrievable in plaintext, and are scoped to least-privilege permissions. Given an Active connection, When the admin views Integrations, Then the provider displays health=OK, last successful sync timestamp, and credential expiry/rotation info where applicable. Given a credential is revoked or expired, When a sync or health check runs, Then the job fails fast, health is set to Needs Attention, and a Reconnect action with a clear error is presented to the admin.

Scheduled Full Sync and Canonical Mapping

Given at least one Active connection, When the scheduled full sync window occurs (configurable daily, default 02:00 UTC), Then the system ingests all active users and maps fields to the canonical schema (role, team, manager, seniority, location, timezone, employment status, primary email, aliases, external id). Given provider field names or types differ, When mapping runs, Then values are transformed to the canonical schema, the mapping version is recorded, and records failing type/format validation are rejected with structured errors. Given the full sync completes, When audit logs are queried, Then completion event, run id, counts (ingested/updated/skipped/errored), and duration are available.

Near-Real-Time Delta Sync

Given a supported provider emits change events, When a user attribute changes, Then the change is reflected in TimeMeld within 5 minutes at P95 and within 15 minutes maximum. Given a provider without webhooks, When polling runs, Then incremental changes since the last cursor are detected and applied at least every 5 minutes. Given delta updates are applied, When concurrent updates occur, Then only changed fields are updated, each change is versioned (source, timestamp, run id), and older values do not overwrite newer ones.

Identity Resolution to Calendar Accounts

Given an ingested user record, When identity resolution runs, Then the user is matched to a calendar identity by primary email; if not found, verified aliases are attempted; otherwise the record is queued with a missing-identity error. Given multiple candidate matches exist, When resolution runs, Then selection follows deterministic precedence (exact primary email > verified alias > HRIS email) and the decision is logged with a confidence score. Given a successful match, When cohort calculations run, Then the user appears once under the correct person with a unified profile and no duplicate calendar identities.

Attribute Validation and Timezone Normalization

Given ingested attributes, When validation runs, Then required fields (role, team, manager, employment status, and either timezone or location) must be present; missing/invalid records are flagged and excluded from cohorts until corrected. Given timezone inputs in IANA, Windows, or UTC offset formats, When normalization runs, Then values are converted to IANA timezones, stored canonically, and validated against the current tzdata. Given location is present but timezone is missing, When normalization runs, Then timezone is inferred from location with an explicit inference flag; ambiguous inferences are queued for review. Given attributes pass validation, When Cohort Lenses are viewed, Then users are included/excluded deterministically based on normalized attributes for identical inputs.

Cross-Source Conflict Resolution

Given conflicting attribute values from multiple sources for the same user, When consolidation runs, Then the configured source priority (e.g., HRIS > Directory > Slack) is applied and the winning value is stored with its source tag. Given two updates of the same attribute arrive from the same source, When timestamps differ, Then the newest update wins; if timestamps are equal, Then the operation is idempotent and no flip-flop occurs. Given a conflict decision is made, When audit history is viewed, Then losing values, sources, and timestamps are visible and a manual override with reason can be applied that persists until revoked.

Resilience, Backfill, Schema Drift Alerting, and Lineage

Given transient provider errors or rate limits, When sync jobs run, Then exponential backoff with jitter is applied with up to 5 retries per batch before marking the job partially failed and queuing a retry. Given an admin triggers a backfill by date range or run id, When the job executes, Then ingestion and mapping are replayed deterministically without duplicate records and lineage is updated. Given provider schema changes (add/remove/rename/type), When detection occurs, Then an alert is sent to configured channels (email and Slack) within 10 minutes, the affected mapping is marked Degraded, and full syncs fail safe without corrupting data. Given any stored attribute, When lineage is queried, Then the system returns source system, source field, source record id, last updated timestamp, mapping version, and sync run id.

Drift & Equity Metrics Per Cohort

"As a remote team lead, I want clear metrics for each cohort so that I can see who is slipping and quantify after-hours burden and equity issues."

Description

Computes cohort-scoped KPIs including scheduling drift versus ergonomic windows, after-hours burden index, reschedule/cancellation rate, attendance and punctuality, meeting ownership equity, lead-time compliance, and timezone pain distribution. Supports daily aggregation, rolling trends, percentile views, and comparisons to org baseline. Implements metric definitions, incremental ETL pipelines, backfills, and a performant query layer with caching to power the Lens UI, alerts, exports, and recommendations.

Acceptance Criteria

Daily Cohort KPIs with Percentiles, Rolling Trends, and Baseline Comparison

Given an org with events tagged by role, team, seniority, meeting_type, internal_external, and participant timezones over the selected date range When the daily aggregation job completes for day D Then for every cohort and day in range the system produces these KPIs: scheduling_drift_minutes_avg, ergonomic_window_hit_rate, after_hours_burden_index, reschedule_rate, cancel_rate, attendance_rate, punctuality_p95_minutes, ownership_equity_index, lead_time_compliance_rate, timezone_pain_score And p50, p90, p95 percentiles and 7-day and 28-day rolling trend values are available for each KPI And each KPI includes delta_absolute and delta_percent versus the org baseline for the same period And null days are represented as null (not 0) and excluded from rate/percentile denominators And applying any combination of cohort filters recomputes totals correctly and returns results within ±0.5% of validated fixtures And values are rounded: rates to 1 decimal percent, minutes to 1 decimal, indices to 3 decimals

Incremental ETL, Late-Arriving Data Handling, and Backfill

Given new events and updates arrive continuously with event_id and updated_at timestamps When the incremental pipeline runs every 15 minutes Then end-to-end latency from ingestion to queryable metrics is ≤ 10 minutes at P95 And late-arriving or updated records within a 7-day lookback are reprocessed and affected aggregates are recomputed And processing is idempotent with exactly-once semantics ensured by primary key (event_id, updated_at) deduplication And each run records an audit log with run_id, watermark_start, watermark_end, input_count, output_count, error_count, duration And a backfill command can rebuild 365 days of history at ≥ 3 million events/hour and produces identical outputs to incremental runs (checksum match) And the job can be safely retried; partial outputs are not visible until commit

Query Layer Performance and Smart Caching for Lens UI

Given a dataset with ≥ 50k meetings/day, 200 cohorts, and 30 concurrent UI users When the Lens UI requests cohort metrics with filters, percentiles, trends, and baseline comparison Then cold query latency is ≤ 1.5 s at P95 and ≤ 600 ms at P50 And cached requests return in ≤ 200 ms at P95 with a cache hit-rate ≥ 80% under typical navigation And cache TTL is 5 minutes and keys are selectively invalidated upon successful ETL completion for affected cohort-day partitions only And results include an as_of timestamp and are consistent with export and alert endpoints (byte-for-byte equality of aggregates for identical parameters)

Timezone-Weighted Drift and After-Hours Burden Calculation Accuracy

Given ergonomic windows configured per cohort (weekday/time spans, local participant time) and a seed dataset with known expected outputs When drift and after-hours metrics are computed Then scheduling_drift_minutes_avg and ergonomic_window_hit_rate reflect participant-weighted local times with correct handling of DST transitions and cross-midnight meetings And after_hours_burden_index counts minutes outside ergonomic windows and weights by participant count and severity tiers (mild/moderate/severe) And outputs match expected fixtures within ±0.5% (rates) or ±1 minute (time metrics)

Meeting Ownership Equity Index Computation

Given organizer identity and cohort membership over the period When the ownership_equity_index is computed Then it is calculated as 1 − Gini(meetings_owned_per_member) and constrained to [0,1] And edge cases are handled: single-member cohort -> index = 1.000; no meetings -> null And metric is stable across re-ingests (identical input -> identical output) and matches fixture values within ±0.005

Cohort Metrics Exports and Alert Integrations

Given a selected cohort, KPI set, and date range When a user exports metrics Then CSV and JSON exports are available within 10 seconds, include column headers/field names, UTC timestamps, and match UI values exactly And when alert rules are configured (threshold, direction, lookback), alerts trigger within 15 minutes of breach with payload including org_id, cohort_id, kpi, threshold, actual, period, link_to_lens And alerts support Slack webhook, email, and generic HTTP webhook with retry (exponential backoff up to 6 hours)

Data Governance, Access Control, and Anonymization for Cohort Lenses

Given a user authenticated to an org When querying cohort metrics Then only data scoped to the user’s org is returned (row-level isolation) And cohorts smaller than 5 unique members are suppressed or aggregated to "Other" and exports redact such rows And no PII (names, emails) appears in metrics, exports, or alerts; only hashed IDs where necessary And all access to metrics, exports, and alerts is logged with user_id, org_id, action, parameters, and timestamp

Lens Explorer UI

"As a product manager, I want an interactive lens to slice metrics by role, team, or meeting type so that I can quickly pinpoint problem areas and share findings with stakeholders."

Description

Delivers an interactive analytics surface to filter by cohort facets, combine filters with AND/OR logic, select date ranges, and pivot by metric. Presents responsive charts and tables with drill-down to meeting lists while enforcing privacy constraints. Supports saved views, shareable deep links, CSV export, annotations, metric tooltips/definitions, empty/loading states, and keyboard navigation for accessibility.

Acceptance Criteria

Filter by Cohort Facets with AND/OR Logic

Given the Lens Explorer is open with default data When the user applies filters Role = Engineer AND Team = Growth AND Meeting Type = Standup Then the results include only meetings where at least one participant satisfies all selected conditions And the filter chip bar displays the human-readable expression exactly as applied When the user switches the operator to OR between Role and Team Then the results include meetings matching either condition and the count updates accordingly When the user groups conditions as Role = Engineer AND (Team = Growth OR Team = Product) Then the evaluation respects the grouping and produces the expected set And applying, removing, or reordering any single filter updates the results within 2s p50 and 4s p95 on datasets up to 100k meetings And clearing all filters resets the view to the default state

Date Range Selection and Timezone Handling

Given the user’s profile timezone is set When the user selects a relative range (Last 7, 30, 90 days, Quarter-to-date) Then meetings are included based on meeting start time occurring within the selected range in the user’s timezone, with the end date inclusive to 23:59:59 When the user selects a custom date range (Start, End) Then the Start and End are inclusive and the range label displays with localized dates and timezone (e.g., Jan 01–Jan 31, 2025, GMT-5) And the selected range persists while navigating within Lens Explorer and is reflected in saved views and deep links And changing the date range updates visualizations and tables within 2s p50 and 4s p95

Metric Pivot with Responsive Visualizations, Tooltips, and Annotations

Given a metric is selected (e.g., Attendance Rate) and a pivot dimension (e.g., Role) When the user changes the metric or pivot dimension Then both the chart and the table update consistently to show the same aggregated values with identical segment ordering and totals And each data point tooltip displays the metric definition, formula, and calculation window, accessible on hover and keyboard focus When the viewport width is ≥1024px Then the chart and table render without horizontal scroll and labels do not overlap When the viewport width is ≤768px Then the layout stacks vertically, legends collapse to a dropdown, and all content remains readable and operable When the user adds an annotation to a specific date or segment Then an annotation marker appears on the chart, the note is visible on hover/focus, and the annotation persists on reload and share links And users can edit or delete their own annotations; edits are versioned and reflected immediately across chart and table

Drill-Down to Meeting List from Visualizations

Given the user views a chart or table segmented by a cohort facet When the user clicks a segment (e.g., Role = Engineer) Then a meeting list opens filtered by the clicked segment plus all currently applied filters and date range And the list shows sortable columns: Start Time, Title, Organizer, Attendees (#), Meeting Type, Internal/External And the default sort is Start Time descending, with stable pagination (page size 25) And the meeting count matches the aggregate number shown on the originating segment When the user navigates back Then the Lens Explorer returns to the prior scroll position and preserves all filters and selections

Saved Views and Shareable Deep Links

Given a set of filters, date range, metric, pivot, and visualization options is configured When the user saves the view with a unique name Then it appears in the Saved Views menu and loads the exact configuration on selection And renaming or deleting a saved view updates the menu immediately and is reflected for the owner on refresh When the user copies a share link Then opening the link reconstructs the exact state (filters, logic, date range, metric, pivot, sort, annotations visibility) for authorized users And unauthorized users see a 403 error page without leaking configuration details And unsaved changes relative to a saved view show an “Edited” indicator until re-saved

Privacy Constraints and CSV Export Redaction

Given privacy is enforced with an aggregation threshold of 5 unique meetings AND 5 unique participants per segment When a segment is below threshold Then the UI replaces the metric with “Insufficient data” and excludes that segment from CSV export And deep links and saved views cannot bypass the threshold; the same redaction applies on load When the user exports CSV Then the file contains only rows permitted by privacy rules and exactly reflects the current filters, date range, metric, and pivot And PII fields (meeting title, attendee emails) are redacted for users without View PII permission and marked as “Redacted” in the CSV And exports complete within 10s p95 for up to 50k rows, with a progress indicator for long-running exports And the CSV filename includes workspace, view name (if any), metric, and date range

Accessibility, Keyboard Navigation, and Loading/Empty States

Given a keyboard-only user When navigating the Lens Explorer Then all controls (filters, operator toggles, date picker, metric selector, chart segments, table headers) are reachable in a logical tab order with visible focus And Space/Enter activate controls, Arrow keys navigate chart segments and table rows, and Esc closes popovers and menus And all interactive elements meet WCAG 2.1 AA contrast requirements When data is loading Then skeleton placeholders and an aria-live polite status announce loading within 200ms, with no layout shift exceeding CLS 0.1 When filters produce no results Then an empty state appears with the message “No meetings found for the selected criteria” and a Clear Filters action; Export and Save View are disabled until data is present

Targeted Recommendations & Nudges

"As an engineering manager, I want actionable recommendations per cohort so that I can fix issues without imposing blanket changes on everyone."

Description

Generates cohort-specific interventions when metrics degrade, such as rebalancing meeting ownership rotation, shifting recurring slots to fairer windows, tightening ergonomic windows, or proposing async alternatives. Provides rationale, expected impact, and one-click application or templated Slack/email nudges to meeting owners. Captures outcomes to learn effectiveness and feeds experimentation tags back into the metrics layer.

Acceptance Criteria

Automatic Cohort Degradation Detection & Recommendation Generation

- Given a user has selected a cohort lens (e.g., Role=Engineer, Team=Payments) and the hourly metrics job has completed, when a monitored metric for that cohort breaches its configured threshold over the trailing 14-day window (e.g., attendance rate < 85% or ownership balance Gini > 0.3), then a targeted recommendation is created and visible in the Cohort Lenses → Recommendations panel within 5 minutes. - Given multiple breaches occur for the same cohort within a 1-hour window, when recommendations are generated, then they are deduplicated and consolidated by issue type with a severity score and timestamp. - Given a recommendation is created, when viewed, then it includes: cohort identifier, degraded metric, threshold and observed value, proposed intervention type (one of: rebalance rotation, shift recurring slot, tighten ergonomic window, propose async alternative), rationale summary, expected impact range, and one-click actions (Apply, Send Nudge). - Given metrics do not breach thresholds for a cohort, when the job completes, then no new recommendation is created for that cohort. - Given a recommendation is generated, when audited, then an entry exists in the audit log capturing generator version, inputs, and time.

One-Click Apply: Rebalance Meeting Ownership Rotation

- Given a recommendation to rebalance ownership rotation for a defined meeting series and cohort, when the user clicks Apply, then the system recalculates rotation weights to target a fairness index ≤ 0.1 Gini (±0.02) effective from the next scheduled occurrence. - Given Apply is initiated, when conflicts are detected for required owners, then the system proposes the nearest feasible rotation that meets fairness within ±0.02 tolerance or blocks with a clear error explaining the constraint. - Given Apply succeeds, then calendar ownership assignments are updated, affected owners are notified, an audit record is written, and the UI displays a success state within 30 seconds. - Given Apply fails at any step, then all changes are rolled back, an error with a reason code is shown, and no notifications are sent. - Given Apply succeeds, when viewed later, then the recommendation shows status Applied with timestamp and a link to the changed series.

One-Click Apply: Shift Recurring Slots to Fair Ergonomic Windows

- Given a recommendation to shift a recurring meeting for a cohort spanning multiple time zones, when the user clicks Apply, then the system reschedules the series into a window that meets the cohort’s ergonomic constraints (e.g., local time 09:00–17:00 for ≥90% of required participants) starting next occurrence. - Given rescheduling would create hard conflicts for any required participant, when computing the new slot, then the system selects the next-best slot with ≤1 hard conflict or presents a blocking error if none exist within the next 4 weeks. - Given Apply succeeds, then the series is updated in the calendar provider, all invitees receive updated invites with a reason note, and the UI shows success within 30 seconds. - Given Apply is previewed, when the user opens the preview, then they see old vs new time, affected time zones, conflict count, and predicted impact. - Given Apply is undone within 10 minutes, when the user clicks Undo, then the series reverts to the prior time and participants are notified of the revert.

Templated Slack/Email Nudges to Meeting Owners

- Given a recommendation exists, when the user selects Send Nudge → Slack, then a prefilled message template opens with cohort, issue, proposed action, and expected impact; the user can edit content before sending. - Given a nudge is sent via Slack, then delivery status (sent, failed) is captured, the message includes deep links (Apply, Preview), and recipients are the meeting owners for the affected series. - Given the user selects Send Nudge → Email, then an email template with the same fields is available, supports CC to team leads, and records delivery status. - Given a nudge is sent, when viewing the recommendation, then the UI shows Nudge Sent with channel, timestamp, and recipients, and tracks link clicks. - Given delivery fails, then a retry option is offered with surfaced error details (e.g., missing Slack mapping, SMTP error).

Rationale, Expected Impact, and Confidence Display

- Given a recommendation is generated, when the user opens its detail, then the rationale includes: degraded metric name, observed value vs threshold, cohort definition, and trailing window used. - Given expected impact is computed, then it is displayed as absolute and relative change with a 80% confidence interval and an indication of data freshness (e.g., last updated timestamp). - Given expected impact cannot be computed due to insufficient data, then the UI displays a clear explanation and disables Apply with a tooltip indicating minimum data requirements. - Given a user reviews multiple recommendations, then each shows a comparable severity score (0–100) and confidence badge (Low/Med/High) derived from sample size and variance.

Outcome Capture and Learning Feedback into Metrics Layer

- Given a recommendation is Applied or a Nudge is sent, then an outcome tracker is created with a unique ID, capturing affected series/cohort, action type, and start of measurement window. - Given the measurement window elapses (default 14 days) or sufficient sample size is reached, when metrics recompute, then the system records observed impact on the targeted metric and labels the outcome as Improved/No Change/Worsened with effect size. - Given outcomes are recorded, when generating future recommendations for the same cohort/meeting type, then the system uses prior outcomes to adjust expected impact and confidence (e.g., downweight ineffective interventions). - Given outcomes exist, then the Cohort Lenses view supports filtering and sorting by intervention type and outcome label. - Given no measurable outcome is available by end of window, then the system marks the outcome Inconclusive and surfaces a prompt to extend or close.

Experimentation Tags Propagation and Attribution

- Given a recommendation is Applied or a Nudge is sent, then an experimentation tag (experiment_id, variant, cohort_id) is attached to the affected meetings and stored in the events stream within 1 minute. - Given tags are attached, when the metrics pipeline runs, then events with experiment tags are attributed in metric aggregations and exposed as filters in the Cohort Lenses UI. - Given a recommendation is rolled back, then its experiment tag is closed (end timestamp set) and no further events are attributed after rollback. - Given experiment tags exist, when the user exports data, then tags are included in the export schema for downstream analysis. - Given conflicting tags would overlap for the same series and metric, then the system prevents Apply and explains the conflict requiring resolution.

Alerts & Subscriptions

"As an operations leader, I want to subscribe to alerts for specific cohorts so that I’m notified when drift or attendance worsens and can act promptly."

Description

Enables threshold- and trend-based alerts on cohort metrics (e.g., after-hours index > target for 2 consecutive weeks), with delivery via Slack and email. Supports per-cohort subscriptions, weekly digests, noise controls (hysteresis, snooze, business hours), and deep links to the triggering Lens view. Respects privacy rules and minimum cohort sizes.

Acceptance Criteria

Immediate Threshold Alert - Slack and Email Delivery

Given a cohort has an alert rule with metric threshold T and immediate delivery enabled And at least one subscriber has Slack and/or email selected for this cohort And the last evaluated period P-1 was at or below T When the new period P value V exceeds T Then an alert is sent within 5 minutes to each subscriber via their selected channels And the notification includes cohort name, metric name, period label, V, T, and a deep link to the Lens And no duplicate alert for the same rule is sent within 24 hours unless the metric returns to at or below T and breaches again

Trend-Based Alert (Consecutive Periods) with Hysteresis

Given an alert rule configured as "metric > T for N consecutive periods" with hysteresis M periods (default 1) And the last period did not meet the N-consecutive condition When the latest N periods all exceed T Then an alert is sent once And no new alert is sent until the metric has been at or below T for M consecutive periods and then again exceeds the rule for N consecutive periods And the notification lists the last N period values and period labels

Per-Cohort Subscription Management and Preference Enforcement

Given a user with view access to a cohort Lens When the user subscribes to alerts for that cohort and selects channels, alert types, and frequency Then the subscription is persisted and used for routing subsequent notifications When the user unsubscribes or changes preferences Then changes take effect within 5 minutes and are reflected in subsequent notifications And subscription attempts without access are rejected with 403 and no subscription is created And a confirmation is shown in-app and via a confirmation message on the chosen channel(s)

Weekly Digest Aggregation and Delivery

Given a user has weekly digest enabled and a digest delivery window set (weekday/time, timezone) When the digest job runs within the window Then a single digest is sent per channel summarizing alerts for the last 7 days that the user is subscribed to and that have not been delivered in a digest And items previously delivered immediately are excluded if the user's preference "exclude duplicates" is true (default), otherwise included once And each item includes cohort, metric, severity rank, and a deep link to the Lens And delivery completes within the window and retries up to 3 times on transient failures

Noise Controls - Business Hours and Snooze

Given organization or user business hours are configured When an alert triggers outside business hours and is not marked urgent Then it is queued and delivered at the next business window start When a user snoozes a cohort or alert rule for duration D Then no notifications for that cohort/rule are delivered to that user during D via any channel and they are excluded from the user's digest And snooze expiration automatically resumes delivery without re-sending queued non-urgent alerts

Privacy Compliance and Minimum Cohort Size

Given a minimum cohort size K and privacy rules are configured When a cohort has fewer than K members during evaluation Then no alert is generated or delivered; the event is logged as "redacted due to privacy" And any deep link resolves to a safe, redacted Lens view or access-denied page without exposing member-level details And notifications never contain PII; only aggregate metrics and cohort labels visible to the recipient's permissions are included

Deep Link Resolution and Context Persistence

Given an alert includes a signed deep link with cohort, metric, time window, and filters When a recipient opens the link Then the Lens loads with the exact cohort, metric, time window, and filters that triggered the alert And if the cohort or metric no longer exists or the user lacks permission, a non-sensitive fallback page is shown with an explanation And the link signature prevents parameter tampering and expires after 72 hours

Privacy & Access Controls

"As a security-conscious admin, I want strict access controls and anonymization in cohort analytics so that sensitive patterns aren’t exposed while still enabling insights."

Description

Enforces role-based access to cohort analytics, k-anonymity thresholds, and masking to prevent identification in small cohorts. Applies least-privilege access, audit logging for metric views/exports, configurable data retention, and PII minimization in alerts and downloads. Integrates with SSO/SCIM for provisioning and revocation, aligning with SOC 2 controls.

Acceptance Criteria

RBAC: Cohort Analytics View vs Export Permissions

- Given a user with Role=Viewer, when accessing Cohort Lenses, then they can view aggregated metrics for authorized cohorts and cannot export or see row-level or PII data. - Given a user with Role=Analyst, when accessing Cohort Lenses, then they can view and export aggregated metrics for authorized cohorts but cannot access PII or row-level data. - Given a user with Role=Admin, when accessing Cohort Lenses, then they can configure RBAC policies and export aggregated metrics but cannot bypass k-anonymity or masking controls. - Rule: Access to a cohort slice is allowed only if the user is assigned to a permission scope that includes the dimensions used (role, team, seniority, meeting type, internal/external). - Rule: Unauthorized slices are excluded from filters and search, and deep links to unauthorized slices return HTTP 403 with no data leakage.

K-Anonymity Thresholds and Masking Enforcement

- Rule: Tenant-configurable k threshold (default 5; allowed range 3–20) applies to all Cohort Lenses visualizations and exports. - Given a cohort slice where count < k, when metrics are requested, then counts are suppressed, percentages are suppressed or rounded per policy, and the slice is labeled "Insufficient sample". - Given a near-threshold cohort where any drilldown would create subgroups with count < k, when the user attempts drilldown, then drilldown is blocked or auto-aggregated to maintain k-anonymity. - Rule: No combination of visible fields (including time granularity and filters) enables derivation of counts < k. - Rule: Exports mirror UI masking/suppression with no optional override.

Least-Privilege Defaults and Access Revocation via SSO/SCIM

- Rule: Newly provisioned users via SCIM are assigned the least-privilege role (Viewer) with export permission disabled by default. - Rule: Role elevation requires Admin approval and is captured in immutable audit logs with approver identity and timestamp. - Given a user is deprovisioned in the IdP or removed from an authorized group, when SCIM/SSO events are received, then all active sessions are revoked and access disabled within 15 minutes. - Given a deprovisioned user attempts access, then requests return HTTP 401/403 and are logged as denied. - Rule: Cohort access scopes are derived from IdP group mappings; local overrides are disallowed unless a tenant setting explicitly enables them.

Audit Logging of Metric Views and Exports

- Rule: Every cohort metric view or export writes an immutable audit record including userId, tenantId, action (view/export), slice definition (dimensions and filters), timestamp (UTC), IP address, user agent, request ID, and outcome (success/failure). - Rule: Audit records are tamper-evident and retained per tenant policy; deletion follows retention rules only. - Given an Admin requests audit logs for a date range they are authorized to view, then results are filterable by user, action, and cohort slice and can be exported as CSV without PII. - Given export volume exceeds a tenant-configurable threshold within a 24h window, then an alert is sent to designated admins containing summary metadata only (no PII).

Configurable Data Retention and Automatic Purge

- Rule: Tenant can configure independent retention periods for analytics aggregates and audit logs (30–730 days), defaulting to 365 days. - Given a record exceeds its retention period T, when the scheduled purge job runs nightly, then records older than T are irreversibly deleted and the purge is logged with counts. - Given retention is reduced, then a backfill purge completes within 24 hours to comply with the new policy and is fully auditable. - Rule: Backups and disaster recovery restores honor current retention; purged data is not reintroduced post-restore.

PII Minimization in Alerts and Downloads

- Rule: Cohort Lenses alerts and exports must not include direct identifiers (e.g., name, email, employee ID) or exact timestamps that enable re-identification in small cohorts. - Given a user generates an export, then only aggregated metrics, cohort dimension labels, and anonymized IDs (if strictly necessary) are included; any PII fields are omitted or redacted. - Given an automated alert is triggered for cohort drift, then the alert contains only cohort labels and masked metrics; no user-level exemplars or raw logs are included. - Rule: CSV headers and metadata avoid PII; schemas are documented and validated in CI to prevent regressions.

SSO-Only Access and SOC 2 Aligned Controls

- Rule: Tenant can enforce SSO-only access; password-based login is fully disabled when enabled. - Rule: Session policies align with tenant configuration within secure bounds (max session 12h, idle timeout 30m by default); enforcement is applied to web and API access. - Given SSO group assertion does not include required cohort access groups, then the user is denied access to restricted slices even if a local role exists. - Rule: Changes to security settings (RBAC, k threshold, retention, SSO-only) require Admin role and are logged with before/after values and approver identity.

Recovery Nudges

When drift persists, the right people get gentle Slack/email prompts with pre‑vetted alternate windows and one‑tap approval. Escalations and reminders keep momentum until attendance returns to baseline.

Requirements

Slack and Email Nudge Delivery

"As a remote team member, I want to receive clear, actionable nudges in my primary communication channel so that I can reschedule quickly without hunting through calendars."

Description

Implement Slack and email channels to deliver Recovery Nudges with pre-vetted alternate windows and actionable controls. Support Slack DMs and threads via OAuth-installed app, interactivity (buttons, modals), and email with secure one-tap links and fallback workflows. Include message templating, personalization, link signing, idempotent click handling, and event tracking. Ensure retries, rate limiting, and graceful degradation if a channel is unavailable. Integrate with TimeMeld’s scheduling engine and user profiles to select channel preference and locale. Log deliveries and outcomes for analytics.

Acceptance Criteria

Slack nudge: DM or thread with actionable controls

Given a nudge is generated for a recipient with Slack OAuth installed and Slack selected as preferred channel in their user profile When the nudge is dispatched Then TimeMeld posts either a DM or a thread reply (if a meeting thread_id is present) to the recipient within 60 seconds of dispatch And the message renders at least 2 pre-vetted alternate windows formatted in the recipient’s locale and timezone And the message includes interactive controls: Approve [Window X], Approve [Window Y], and a "See more" button that opens a modal listing up to 5 windows And Slack interactivity callbacks are verified using Slack signature validation; invalid signatures return 401 and are ignored without state change And the message uses template "recovery_nudge_slack_v1" with personalization tokens {first_name}, {meeting_title}, {owner_name} resolved with no missing tokens And a DeliveryAttempted and Delivered event are recorded with message_id, channel=slack, nudge_id, recipient_id

Email nudge: one-tap secure approval links

Given a nudge is generated for a recipient with email selected as preferred or fallback channel and a verified email address on file When the nudge is dispatched Then an email using template "recovery_nudge_email_v1" is submitted to the ESP within 60 seconds and includes at least 2 pre-vetted alternate windows rendered in the recipient’s locale and timezone And each approval control is a one-tap link containing a signed, expiring token bound to nudge_id, recipient_id, and window_id that expires after 24 hours And clicking a valid link applies the selection and returns a confirmation page within 2 seconds; expired or tampered links return 401 and a secure fallback page offering "Request new link" And DeliveryAttempted, Delivered, Opened, and Clicked events are logged with message_id, channel=email, nudge_id, recipient_id

Action processing: update schedule and invites

Given a recipient approves a proposed window via Slack button or email one-tap link for a nudge tied to meeting_id When the action is processed Then the scheduling engine reserves the selected window, updates the meeting record, and sends calendar invites to all required attendees within 60 seconds And conflicting windows for the same nudge are invalidated and marked as superseded And the equity scoreboard and meeting ownership rotation are updated accordingly And an ActionProcessed event with outcome=approved, meeting_id, window_id is logged; downstream attendees receive a confirmation notification per their channel preferences

Templating, personalization, locale and timezone formatting

Given a nudge is generated for a recipient with user profile fields first_name, locale, timezone, channel_preference, and team When messages are rendered for Slack and email Then the selected template versions are retrieved by key and version and all personalization tokens resolve without placeholders And date/time strings are localized to the recipient’s locale and timezone (e.g., en-US vs fr-FR formats) And if the recipient has no locale, default to workspace locale; if no timezone, default to meeting timezone And rendering failures fail the nudge before dispatch and are logged with error_type=rendering_failed

Idempotent action handling across channels

Given multiple action attempts are made for the same nudge_id and recipient_id (duplicate link clicks, repeated Slack button presses, or retries) When the first valid action is processed Then subsequent duplicate actions return 200 with message "Already processed" and produce no state change And all actions share an idempotency key composed of nudge_id+recipient_id+window_id; only the first succeeds And duplicates are logged with outcome=duplicate without generating additional notifications

Retries, rate limiting, and graceful degradation

Given transient delivery failures occur (Slack 5xx/429, ESP 5xx/deferrals) When dispatch is attempted Then the system retries with exponential backoff (2s, 4s, 8s) up to 3 attempts, honoring provider 'Retry-After' headers And if Slack fails after retries, the nudge is sent via email (if allowed by recipient preferences) within 5 minutes; if email fails, fallback to Slack similarly And if both channels fail, the nudge is queued for a retry cycle in 60 minutes and an alert is emitted to ops And all retries and fallbacks are logged with attempt counts and final outcome

Delivery and outcome analytics logging

Given nudges are dispatched and interacted with When events occur (DeliveryAttempted, Delivered, Opened, Clicked, ModalOpened, ActionProcessed, FallbackTriggered) Then each event is appended to the analytics stream with fields: nudge_id, meeting_id, recipient_id, channel, template_version, timestamp (UTC), and correlation_id And events are queryable in the analytics store within 5 minutes of occurrence for 95% of events and retained for at least 90 days And PII is limited to hashed recipient_id; no raw email addresses or Slack tokens are stored in event payloads

Recipient Targeting Engine

"As a meeting organizer, I want nudges sent only to the people who can unblock scheduling so that we minimize noise and increase response rates."

Description

Build logic to identify the right recipients for Recovery Nudges when attendance drift persists. Determine stakeholders based on meeting role (organizer, rotating owner), criticality, historical attendance, and dependency mapping. Respect user preferences, working hours, timezones, do-not-disturb, and equity rotation. De-duplicate across overlapping meetings, suppress nudges for those already responded, and include escalation recipients when needed. Integrate with calendar sources, attendance logs, and the equity scoreboard to produce a prioritized, minimal recipient list per nudge event.

Acceptance Criteria

Triggering Recipient Selection on Persistent Attendance Drift

Given the last 3 occurrences of a recurring meeting show attendance below baseline by ≥20%, And a nudge event is generated for that series, When the targeting engine runs, Then it selects candidate recipients including the meeting organizer, the current rotating owner per the equity scoreboard, and critical stakeholders as defined in the dependency map, And Then the candidate pool is limited to attendees of the affected meeting series and occurrence.

Prioritized Minimal Recipient List Generation

Given a set of candidate recipients for a nudge event, When the engine prioritizes the list, Then recipients are ordered as: rotating owner (if assigned for this cycle) > organizer > critical-path stakeholders (ascending by historical attendance rate) > optional attendees, And Then the final recipient list contains no more than 5 people and includes at least 1 representative from each affected dependency group (if present), And Then each recipient entry includes a role tag (e.g., organizer, rotating_owner, critical_path, optional) in the output payload.

Respecting Preferences, Timezones, Working Hours, and Do Not Disturb

Given a candidate recipient has active Do Not Disturb or is outside their configured working hours in their local timezone, When compiling the list for the current nudge event, Then that recipient is excluded from the current send, And Then the output payload records channel preference (Slack or email) and local timezone for each included recipient, And Then no recipient is selected more than once within a rolling 24-hour period across all meetings.

De-duplication Across Overlapping Meetings and Response Suppression

Given a recipient is a candidate for multiple meetings with start times overlapping by ≥30 minutes within a 2-hour window, When generating recipients, Then the engine includes the recipient only for the highest-priority meeting (by meeting criticality, then earliest start time) and removes them from others, And Given a recipient has responded (accept/decline/proposed alternate) to a nudge for this meeting series within the last 24 hours, When generating recipients, Then the engine excludes that recipient from the list, And Then the final recipient list contains no duplicate user IDs.

Escalation Recipient Inclusion on Non-Response

Given a nudge was sent and no primary recipient has responded within 8 business hours, When the next evaluation cycle runs, Then the engine adds escalation recipients as defined by the meeting’s escalation policy (e.g., team lead, project owner), capped at 2 additional recipients, And Then only one escalation wave occurs per meeting occurrence per 24 hours, And Then escalation recipients are not added if any primary recipient has accepted or scheduled an alternate time.

Data Integration, Fallbacks, and Error Handling

Given integrations with calendar sources, attendance logs, and the equity scoreboard are available, When the engine runs, Then it uses data timestamps not older than 15 minutes, And When any source is unavailable, Then the engine retries up to 3 times over 5 minutes and falls back to last known data not older than 24 hours; if older than 24 hours, it skips rules requiring that source and marks the run as partial in telemetry, And Then each run emits an audit record with meeting ID, selected recipient IDs, exclusion reasons, data timestamps, and ruleset version.

Equity Rotation Compliance and Fairness Caps

Given an equity scoreboard defines the current rotating owner and per-member nudge counts, When generating recipients, Then the rotating owner for the cycle is included unless they have exceeded a monthly nudge cap of 4, in which case the next eligible member by rotation is selected, And Then no individual is selected as a primary recipient more than 2 times for the same meeting series within a rolling 7-day window.

Alternate Window Generation

"As an attendee, I want suggested times that already respect my hours and the team’s fairness rules so that I can approve a slot with one tap."

Description

Generate a short list of pre-vetted meeting windows optimized for participants’ timezones, working hours, and ergonomic constraints. Use TimeMeld’s timezone-weighted algorithm, avoid repeating recently inconvenient slots, and honor rotation rules from the equity scoreboard. Pull availability from connected calendars, account for buffers and travel time, and produce 3–5 viable options with confidence scores. Expose options to the nudge payload with metadata (start/end, timezone, participant fit score, conflicts).

Acceptance Criteria

Timezone-Weighted Option Generation (3–5 Viable Windows)

Given a meeting request with 4 participants across 3 timezones and all have connected calendars and working hours configured And the lookahead window is the next 10 business days When the alternate window generator runs Then it returns between 3 and 5 unique windows And each window includes a confidenceScore between 0 and 1 And each window’s start and end are within all participants’ declared working hours And no two returned windows have identical start and end

Calendar Availability, Buffers, and Travel Time Respected

Given participants have busy events on connected calendars and personal buffer settings (e.g., 10 minutes before/after meetings) and travel time between in-person events When generating alternate windows Then no proposed window overlaps any participant’s busy events And each proposed window starts no earlier than the required buffer after any preceding event and ends no later than the required buffer before any following event for every participant And proposed windows preserve required travel time gaps between sequential in-person events for every participant

Exclude Recently Inconvenient Slots

Given the system history contains a set of slots marked as inconvenient for any participant within the last 21 days When generating alternate windows Then none of the returned windows match any recorded inconvenient slot within that lookback window And none of the returned windows fall within any exact timestamp range recorded as inconvenient

Honor Equity Scoreboard Rotation

Given the equity scoreboard designates user U3 as the next meeting owner When generating alternate windows Then each window’s metadata includes ownerId = U3 And no window assigns a different ownerId And all returned windows keep U3 within their working hours and ergonomic constraints

Ergonomic Constraints Across Timezones Applied

Given participants have ergonomic constraints configured (e.g., quiet hours, lunch break, daily meeting cap) When generating alternate windows Then no window violates any participant’s quiet hours or lunch break And no window causes any participant to exceed their daily meeting cap on that day And no window falls outside any participant’s allowed working-hours band unless their preferences explicitly permit exceptions

Nudge Payload Option Metadata Complete

Given alternate windows are generated When building the Recovery Nudge payload Then each option object includes: start (ISO 8601), end (ISO 8601), timezone (IANA), confidenceScore (0–1), participantFitScores [{participantId, score 0–1}], conflicts [{participantId, eventId, type}] And the payload validates against the defined schema And for every option, start precedes end and timezone corresponds to the intended local display zone

One-Tap Approval and Auto-Reschedule

"As a busy engineer, I want to confirm a new time instantly from the message so that I don’t have to open my calendar or a separate app."

Description

Provide secure, one-tap approval from Slack buttons or email links to confirm a proposed window, request alternatives, or decline with reason. On approval, automatically update the calendar event, notify all participants, adjust the equity scoreboard, and cancel obsolete holds. Ensure link signing, expiration, and idempotency; handle race conditions if multiple users act simultaneously; and present conflict-resolution flows when the chosen slot becomes unavailable.

Acceptance Criteria

Slack One‑Tap Approval Actions

Given a recipient views a Recovery Nudge in Slack with buttons [Approve], [Need alternatives], [Decline] When the user clicks any button Then the action is acknowledged in Slack within 3 seconds with a visible ephemeral confirmation And the system records the user, meeting ID, proposed window, and action timestamp And the message updates to reflect the action state (approved/alt requested/declined) And only users on the invite list or delegated schedulers can act; others see an authorization error

Email One‑Tap Approval via Signed Link

Given a recipient opens an email nudge containing one‑tap links for [Approve], [Need alternatives], [Decline] When the user clicks a link Then the link is verified as signed, untampered, and unexpired And the user sees a confirmation page within 3 seconds reflecting the action state And the action is recorded with user identity derived from the email recipient and link payload

Escalation and Reminder Cadence

"As a team lead, I want smart reminders that escalate only when necessary so that scheduling momentum is maintained without spamming the team."

Description

Implement configurable reminder and escalation rules that continue nudging until attendance metrics return to baseline or a stop condition is met. Support time-based reminders, channel escalation (e.g., from DM to small group to manager), and ownership escalation to the rotating owner. Enforce quiet hours, per-user rate limits, and global caps. Provide admin-level policies and per-meeting overrides, and stop automatically upon resolution to prevent over-notification.

Acceptance Criteria

Time-Based Reminder Cadence Respects Quiet Hours

Given an admin policy with reminder offsets 15m, 2h, and 24h and per-user quiet hours 20:00–08:00 local And a meeting drift event is detected at 09:00 local When the system schedules reminders Then each recipient receives reminders at 09:15 and 11:00 local and next day at 09:00 local And any reminder falling in their quiet hours is deferred to the next allowed minute after quiet hours And each send is logged with timestamp, recipient, channel, and policy version

Auto-Stop on Resolution and Stop Conditions

Given nudging is active for a meeting series due to attendance below baseline When any of the following occurs: attendance meets or exceeds baseline for 2 consecutive occurrences, a new time is accepted, the meeting is canceled, an admin or rotating owner taps Stop, or a snooze is set Then all pending reminders and scheduled escalations for that series are canceled within 1 minute And no further nudges are sent unless a new trigger occurs And a resolution event is written to the audit log with the stop reason

Channel Escalation Path DM → Small Group → Manager

Given a channel escalation policy DM -> small group -> manager with step thresholds of 2 failed nudges or 24h without response When DM nudges reach the threshold without resolution Then the next nudge posts in the designated small group channel mentioning only required participants and includes pre-vetted alternate windows with one-tap approval links And if that step also fails per threshold, the next nudge is sent to the manager via their preferred channel (Slack DM or email) And at no point does any recipient receive more than one nudge per 4h per-user rate limit And all escalation steps are recorded with timestamps and recipients

Ownership Escalation to Rotating Owner

Given an active series with a configured rotating owner roster When escalation threshold E is reached without resolution Then the current rotating owner is assigned as the recovery owner and receives a high-priority nudge with Accept and Decline And on Accept, ownership is updated in the shared scoreboard and subsequent nudges reference the owner And on Decline or no action for 4h, assignment advances to the next rotating owner And ownership escalation resets the cadence according to the policy and is logged

Quiet Hours, Per-User Rate Limits, and Global Caps

Given per-user quiet hours, a per-user rate limit R per 24h, and a workspace global cap G messages per hour When the system attempts to send a nudge Then it does not send during a recipient’s quiet hours and queues to the next allowed minute And it skips sending to recipients who have reached R nudges in the past rolling 24h and marks the attempt as rate-limited And it defers sends that would exceed the global cap G to the next hour boundary while preserving order And all queued, skipped, and sent events are visible in the audit feed with reasons

Admin Policy and Per-Meeting Overrides

Given an admin-level default policy P and a per-meeting override O When both define cadence, channels, quiet hours, or caps Then O takes precedence within bounds enforced by P such that cadence is not faster than P.minCadence and quiet hours are not narrower than P.minQuietHours And invalid overrides are rejected with a clear validation message and no changes are saved And upon save, the effective policy is computed, stored with a version ID, and displayed in the meeting settings And all changes include who, what, when in the audit log

Attendance Baseline Trigger and Recovery

Given baseline attendance is defined as the median of the last 6 completed occurrences (minimum 3) And the trigger threshold is a drop of at least 10 percentage points for 2 consecutive occurrences When the trigger condition is met Then nudging activates for the affected meeting and targeted attendees And nudging continues until attendance returns to within 2 percentage points of baseline for 2 consecutive occurrences or a stop condition occurs And metrics and state transitions are recorded and available in reporting

Drift Detection and Stop Conditions

"As an operations manager, I want nudges to activate only when attendance problems persist and stop once fixed so that we avoid unnecessary interventions."

Description

Detect when attendance has drifted from baseline to trigger Recovery Nudges and determine when to stop. Compute baselines per team and meeting series over rolling windows, define thresholds, and apply hysteresis to avoid oscillation. Ingest attendance signals (RSVPs, joins, no-shows), classify root causes (time misfit, conflicts), and emit clear trigger events to the nudge pipeline. Record recovery state and suppress nudges once metrics return to baseline.

Acceptance Criteria

Rolling Baseline Computation per Team and Meeting Series

- Rule: For a meeting series, baseline_attendance = mean attendance_rate of the last N valid occurrences (default N=8; min_samples=5). Exclude canceled or skipped occurrences. - Rule: For a team-level baseline, baseline_attendance = mean attendance_rate across the team’s meetings in the trailing 30 days with min_samples=10; otherwise mark baseline_status = insufficient_data and do not evaluate drift. - Rule: Baselines recompute on schedule (00:30 UTC daily) and on occurrence_finalized events; each computation completes in ≤2 seconds per entity. - Rule: Persist baseline value, window parameters, sample_size, computed_at, and contributing occurrence IDs.

Drift Detection and Trigger Emission

- Given a computed baseline and a finalized meeting occurrence with observed_attendance_rate, When observed_attendance_rate ≤ baseline − 10 percentage points OR observed_attendance_rate < 70%, for 2 consecutive finalized occurrences within 21 days, Then emit NudgeTrigger.DriftDetected for the entity with severity = normal. - Rule: The emitted event includes: entity_type, entity_id, occurrence_id, baseline_rate, observed_rate, delta_pp, comparison_window, consecutive_count, computed_at, cause_class (if available), confidence, recovery_state_id. - Rule: Emit at most one DriftDetected per occurrence_id (idempotent). - Rule: Team-level drift and series-level drift are evaluated and emitted independently.

Hysteresis and Stop Conditions to Prevent Oscillation

- Given the entity is in Recovering state after a DriftDetected, When three consecutive occurrences have observed_attendance_rate ≥ (baseline − 2 percentage points) and the 14-day rolling mean ≥ (baseline − 1 percentage point), Then emit RecoveryResolved and transition state to Recovered. - Rule: While in Recovering and before the stop condition is met, do not emit additional DriftDetected for the same entity unless observed_attendance_rate ≤ (baseline − 20 percentage points) for two additional consecutive occurrences (severity = high). - Rule: If no new occurrences finalize within 30 days, retain Recovering state without emitting new events and re-evaluate on the next finalized occurrence.

Signal Ingestion and Attendance Derivation

- Rule: Supported signals: RSVP(yes/no/maybe/optional), Join/Leave timestamps, Meeting start/end, Organizer cancellation, Decline reason text. - Rule: Attendance rate denominator = count of invited required participants who did not decline; numerator = count of those who joined any time before meeting end or within 10 minutes after start; optional invitees are excluded from both numerator and denominator. - Rule: Reschedules preserve occurrence_id; duplicate signals are de-duplicated by source_event_id; late arrivals are counted as attended; no join by meeting end ⇒ no-show. - Rule: Normalize all timestamps to UTC; ingestion latency p95 ≤ 60 seconds; backfill window = 24 hours; ingestion failures are logged and retried up to 3 times with exponential backoff.

Root Cause Classification on Drift

- Given a DriftDetected candidate, When classification runs, Then compute and attach primary_cause and confidence per rules. - Rule: primary_cause = time_misfit if > 40% of required invitees’ local meeting time falls outside ergonomic hours (08:00–18:00 local) OR median local start time < 07:00 or > 19:00; confidence = min(1.0, proportion/0.4). - Rule: primary_cause = scheduling_conflict if > 20% of required invitees had overlapping busy events; confidence = min(1.0, proportion/0.2). - Rule: primary_cause = invite_scope_issue if optional invitees > required invitees and required attendance is within 5 pp of the team baseline; confidence = 0.6. - Rule: primary_cause = technical_issue if a platform incident overlapped the meeting OR join-failure rate > 10%; confidence = min(1.0, proportion/0.1). - Rule: If none apply, primary_cause = unknown; confidence = 0.3.

Recovery State Recording and Idempotency

- Rule: Maintain per entity a recovery_state machine with states {Stable, Drifted, Recovering, Recovered}; allowed transitions: Stable→Drifted→Recovering→Recovered→Stable. - Rule: All state transitions are idempotent by occurrence_id and persisted with timestamps, actor=system, and prior/new state snapshots. - Rule: Query API GET /v1/recovery-state?entity_id returns current_state, last_transition_at, baseline_rate, observed_rate_last, consecutive_counts, and the last 20 transitions in ≤ 200 ms p95. - Rule: Reprocessing the same occurrence does not create duplicate transitions or duplicate events (verified by deterministic keys).

Nudge Suppression and Cooldown after Recovery

- Given the entity transitions to Recovered, When evaluating occurrences within the next 14 days, Then do not emit NudgeTrigger.DriftDetected unless observed_attendance_rate ≤ (baseline − 20 pp) AND < 60% for two consecutive occurrences. - Rule: While Recovered and within cooldown, emit only HealthStatus updates (non-trigger) that include observed_rate and baseline. - Rule: After the 14-day cooldown, resume standard drift detection thresholds and behaviors.

Notification Preferences and Compliance

"As an attendee, I want control over how and when I’m nudged so that messages are helpful and respect my preferences and privacy."

Description

Provide per-user and per-workspace controls for nudge channels, frequency, quiet hours, and opt-in/opt-out, with admin-enforced minimums for critical meetings. Include unsubscribe mechanisms in email, Slack slash commands for preferences, and audit logs. Ensure compliance with GDPR/CCPA, store consent and purpose limitation, and honor data deletion requests. Localize content and time formats based on user locale and timezone.

Acceptance Criteria

User-configurable nudge channels, frequency, and quiet hours

Given a signed-in user with default nudge settings When they open Preferences → Nudges and toggle Email and Slack channels independently Then the changes persist and are reflected on reload Given the user has only Slack enabled When a recovery nudge is triggered for them Then only Slack receives the nudge and Email is not sent Given the user sets frequency cap to 2 nudges per 24 hours When the system attempts to send a 3rd nudge within 24 hours Then the nudge is suppressed, a suppression reason is recorded, and the next send is scheduled after the cap window resets Given the user sets quiet hours to 21:00–08:00 in their timezone When a nudge would be sent at 22:30 local time Then it is deferred to the next allowed window unless the nudge is marked critical Given the user disables all channels for non-critical nudges When non-critical nudges are triggered Then no messages are delivered and the suppression is logged with reason "user opt-out"

Admin-enforced minimums for critical meetings

Given a workspace admin enables a policy requiring at least one channel for critical meetings When a user attempts to opt out of all channels for critical nudges Then the UI blocks the change, displays the policy notice, and retains at least one admin-required channel enabled Given a critical nudge must be sent during a user’s quiet hours When the admin policy allows override for critical Then one nudge is delivered during quiet hours with the minimum frequency set by policy and an enforcement event is added to the audit log Given non-critical nudges are triggered for the same user When user preferences disable all channels for non-critical Then no non-critical nudges are sent despite the critical policy Given an admin changes the critical policy When the policy is saved Then all impacted users’ effective settings recalculate within 5 minutes and are visible in an admin review screen

Email unsubscribe and preferences links

Given a user receives a non-critical nudge email When they click the Unsubscribe link Then they are immediately unsubscribed from non-critical email nudges, receive a confirmation page within 3 seconds, and no further non-critical emails are sent to them Given the same email includes a Manage Preferences link When the user clicks it and updates settings Then changes persist and are effective for subsequent sends within 60 seconds Given a user receives a critical meeting email When they click Unsubscribe Then they are shown a page explaining the admin-enforced policy, with options to adjust non-critical preferences, and no change is made to critical delivery Given a nudge email is sent Then the message includes valid List-Unsubscribe and List-Unsubscribe-Post headers and an HTTPS one-click unsubscribe endpoint that processes requests within 60 seconds

Slack slash commands for managing preferences

Given the TimeMeld Slack app is installed and the user is linked When the user enters "/timemeld prefs" Then an ephemeral interactive message displays current channels, frequency cap, and quiet hours, and saving updates persists settings immediately Given the user enters "/timemeld stop" When the command is processed Then the user is unsubscribed from non-critical Slack nudges immediately and receives an ephemeral confirmation Given the user is not linked or the app is not installed When they issue either command Then they receive an ephemeral error with steps to authenticate/install and no settings are changed Given any change is made via Slack Then an audit entry records actor, source="Slack", fields changed, and timestamp

Audit logging of preference, consent, and policy changes

Given any change to a user’s notification preferences, consent status, or an admin policy When the change is saved Then an immutable audit record is created with timestamp (UTC), actor (user/admin/system), workspace, affected user, fields before/after, source (Web/Email/Slack/API), and request metadata (IP/User-Agent where available) Given audit data is requested by an admin with the proper permission When they filter by user and date range and export as CSV or JSON Then the export completes within 60 seconds for up to 100,000 records and an export event is itself logged Given an auditor attempts to modify or delete an audit record via the UI or API When the request is made Then the system denies the action and records the attempt

GDPR/CCPA consent, export, and deletion handling

Given a user first enables nudges When consent is required by their region Then the system records time-stamped, versioned consent with declared purposes and no nudges are sent until consent is captured Given a user opts out of non-critical nudges When a nudge is triggered Then it is not sent and the suppression is attributed to opt-out; for critical nudges under admin policy, the send includes a recorded lawful-basis note in the audit log Given a user submits a data deletion request When the request is confirmed Then all personal data related to nudges and preferences is erased or irreversibly anonymized within 30 days, sending ceases within 24 hours, and a completion confirmation is provided; minimal non-identifying audit entries are retained where legally permissible Given a user requests a copy of their data When the request is submitted Then a machine-readable export including preferences, consents, and related audit entries is available for secure download within 7 days

Localization of content and time formats

Given a user has locale fr-FR and timezone Europe/Paris When a Slack or Email nudge is sent Then the message text is in French, dates/times use 24-hour format and DD/MM/YYYY, and times are converted to Europe/Paris with appropriate abbreviations Given a translation key is missing for a locale When a nudge is generated Then the system falls back to English content without exposing raw template keys and logs a localization warning Given a workspace default locale differs from a user’s locale When a nudge is sent to that user Then the user’s locale takes precedence for content and formatting Given automated localization tests run When the test suite executes Then snapshots for en-US, en-GB, fr-FR, de-DE, and ja-JP pass for both email and Slack templates

RippleGuard Rebook

Finds the nearest fair time that triggers the fewest downstream conflicts. Slipstream simulates candidate slots across all attendees’ calendars, avoids guard breaches, and chooses the option with minimal ripples—so you reschedule once, not three times, while protecting maker hours.

Requirements

Ripple Simulation Engine

"As a product manager, I want the system to simulate reschedule impacts across all attendees’ calendars so that we pick a time that minimizes downstream conflicts and avoids rebooking cascades."

Description

Implement a scoring-based simulation that evaluates candidate reschedule slots across all attendees’ calendars to quantify downstream conflicts (“ripples”). The engine builds a conflict graph from free/busy, meeting dependencies, buffer/travel times, and recurrence chains, then computes a ripple cost for each candidate. Costs factor in guardrail breaches (maker hours, no‑meeting blocks), timezone fairness, and attendance risk. The engine returns an ordered set of viable times with explanations and trace data for auditability, enabling data-driven rebooking that minimizes rework and protects productivity.

Acceptance Criteria

Conflict Graph Construction from Calendars and Constraints

Given attendees with connected calendars providing free/busy, event metadata (location, buffer/travel time, recurrence), and meeting dependency links And a target reschedule window with enumerated candidate slots When the engine constructs the conflict graph Then nodes represent all relevant events and each candidate slot within the evaluation horizon And edges represent conflicts due to time overlap, buffer/travel requirements, and explicit dependencies And recurrence chains are represented with series identifiers and occurrence indices And cancelled events are excluded; tentative holds are marked as soft conflicts And for each candidate slot, the engine enumerates conflicting events per attendee with timestamps and conflict reasons

Ripple Cost Computation with Guardrails, Fairness, and Risk

Given a constructed conflict graph and a set of candidate slots And a weight configuration for cost components When the engine computes ripple cost per candidate Then total cost equals the sum of weighted components: guardrail breaches, timezone fairness adjustment, attendance risk, number of moves, buffer/travel shifts, and dependency violations And guardrail penalties include detection of maker-hours and no-meeting blocks per attendee profile And timezone fairness adjusts cost based on local-time ergonomics and equity rotation And attendance risk increases cost for slots outside preferred hours or with historical decline/no-show indicators And the output includes a numeric cost breakdown per component for each candidate

Candidate Filtering, Ordering, and Explanations

Given N candidate slots and computed costs When producing results Then candidates violating hard guardrails are excluded with machine-readable reasons And remaining candidates are ordered by ascending total cost And the top candidate’s total cost is less than or equal to all others And ties are resolved deterministically by earlier wall-clock time, then fairness score, then stable input order And each candidate includes a human-readable explanation and a trace id referencing full details

Guardrail Protection and Fallback Behavior

Given maker-hours and no-meeting blocks configured per attendee When evaluating candidates Then any candidate breaching a hard guardrail is excluded from viable results And candidates breaching soft guardrails receive the configured penalty but remain viable And if no candidates avoid hard guardrails, the engine returns the least-breach option with explicit breach reasons and affected attendees listed And the top result flags whether any guardrail was breached

Recurrence and Dependency Sensitivity

Given a meeting that is part of a recurrence series and participates in dependency constraints (e.g., must precede another meeting) When simulating reschedule options for a single occurrence Then ripple cost accounts for impacts to future occurrences within the evaluation horizon and to dependent meetings And ordering constraints are preserved; candidates that would violate required sequencing are marked invalid And explanations identify series/dependency contributors and quantify their cost contribution

Performance and Scalability Targets

Given up to 12 attendees, 100 candidate slots, and an 8-week evaluation horizon on a baseline server (2 vCPU, 4 GB RAM) When building the conflict graph and scoring all candidates Then total computation completes within 2000 ms p50 and 5000 ms p95 And peak memory usage remains under 500 MB p95 And enabling parallel scoring does not change the ordering or costs of results

Auditability and Determinism

Given identical inputs (attendees, calendars, configuration, seed, and time normalization) When the engine runs multiple times Then it produces identical ordered candidates and identical cost breakdowns And each candidate’s trace payload includes config version, weight values, input hashes, conflict graph summary, per-component costs, and decision path And traces are retrievable by trace id for at least 30 days

Nearest‑Fair Slot Finder

"As a distributed team lead, I want RippleGuard to locate the nearest fair time that respects everyone’s working hours so that rescheduling is quick and equitable."

Description

Create an optimization layer that searches the nearest future window satisfying fairness and guardrail constraints while minimizing ripple cost. The solver respects each attendee’s working hours, time‑zone ergonomics, personal preferences, and buffer policies, and applies tie‑breakers using fairness deltas and equity rotation. The output is a single best slot and a ranked shortlist, each annotated with why it was chosen and what trade‑offs were avoided, enabling quick, equitable rebooking aligned with TimeMeld’s fairness goals.

Acceptance Criteria

Nearest Fair Slot Selection and Ranked Shortlist

Given an existing meeting with attendees, original start time T0, and duration D When the solver runs to find a rebook time Then it returns exactly 1 primary slot and a ranked shortlist of up to 5 alternatives And the primary slot is the feasible slot with the smallest non-negative time delta from T0 And all returned slots satisfy fairness and guardrail constraints with zero guard breaches And the shortlist is ordered by: (1) minimal time delta from T0, (2) minimal ripple cost, (3) minimal fairness delta, (4) equity rotation priority, (5) earliest chronological time, (6) deterministic hash as final tie-breaker

Working Hours, Time-Zone Ergonomics, and Preferences Compliance

Given attendees have configured working hours, ergonomic windows, and personal preferences (hard and soft) When candidate slots are evaluated Then for each attendee, start and end times fall within their working hours and ergonomic windows And no hard preferences are violated for any attendee And soft preferences are only violated if no candidate exists within the search horizon that honors them, and any soft violation is explicitly flagged in the slot annotation

Maker-Hour Protection and Buffer Policy Enforcement

Given organization policies define protected maker-hour blocks and per-attendee buffer requirements before/after meetings When evaluating a candidate slot Then the slot does not overlap any protected maker-hour or focus blocks for any attendee And the slot provides at least the configured buffer_before before and buffer_after after adjacent events on each attendee’s calendar And any candidate failing buffer or maker-hour checks is excluded from results

Ripple Cost Simulation and Minimization

Given access to attendees’ calendars within a configurable horizon (default 14 days) And a configured ripple cost function with weighted components (e.g., conflicts created, meetings displaced, priority weight, attendees impacted) When simulating the downstream impact of each feasible candidate Then each candidate is assigned a ripple cost with its component breakdown And the selected primary slot has the lowest ripple cost among candidates with the same minimal time delta from T0 And the shortlist includes each candidate’s ripple cost and top impacted events, if any

Tie-Breakers: Fairness Delta and Equity Rotation

Given two or more feasible candidates with identical time delta from T0 and identical ripple cost When selecting the primary slot Then the solver selects the candidate with the smallest fairness delta versus the 90-day inconvenience baseline And if still tied, selects the candidate that advances the equity rotation to the next owner in the scoreboard And if still tied, selects the earliest chronological slot; if still tied, selects deterministically by stable hash of slot metadata And the applied tie-breaker sequence is recorded in the annotation

Explainability: Annotations and Trade-Offs

Given a chosen primary slot and a ranked shortlist When generating output Then each slot includes machine-readable fields: start/end in UTC, per-attendee local times, constraints satisfied, fairness score and delta, ripple cost with components, buffers applied, and tie-breakers used And each slot includes a human-readable summary listing the top 3 reasons it was favored and the top 3 trade-offs avoided And no personally sensitive data beyond attendee names and emails is included in annotations

Performance and Determinism SLA

Given up to 12 attendees, a 30–60 minute duration, and a 14-day search horizon on standard infrastructure When the solver runs Then 95th percentile end-to-end selection time is ≤ 2 seconds and maximum is ≤ 5 seconds And peak memory usage remains ≤ 200 MB during evaluation And results are deterministic for identical inputs, calendars, and configuration

Guardrail Compliance & Maker Hours Protection

"As an engineer, I want my maker hours to be protected during rebooking so that my focus time isn’t fragmented."

Description

Enforce hard and soft guardrails during rebooking, including maker‑hours blocks, no‑meeting days, lunch windows, and focus sessions. The system must detect potential breaches, suggest compliant alternatives, and clearly label any override as an exceptional action with reason capture and audit logging. Integration with personal calendar keywords (e.g., “Focus”, “Deep Work”) and organization policies ensures consistency, prevents fragmented schedules, and maintains high‑quality focus time for engineers and other makers.

Acceptance Criteria

Hard Guardrails Block and Alternatives Suggested

- Given a rebook is initiated and organizational guardrail configuration is loaded, When the nearest candidate time violates any hard guardrail for any attendee, Then the system must not schedule that time and must present up to 5 nearest compliant alternatives ranked by proximity and ripple score. - Given compliant alternatives are available within the defined search horizon, When alternatives are displayed, Then at least 3 options are shown (or all available if fewer) and each option lists which guardrails it satisfies and any soft warnings count = 0. - Given no compliant alternatives exist within the default horizon, When results are returned, Then the system displays "No compliant slots" with the first violated hard guardrail per attendee and provides controls to expand horizon or adjust participants.

Maker Hours Protected via Keywords and Policy

- Given an attendee has calendar events matching configured maker-hours keywords and maker-hours rules are enabled, When candidate slots are generated, Then no candidate overlaps any keyword-matched block by more than 0 minutes if the rule is hard, or marks a soft warning if soft. - Given a configured minimum contiguous maker-hours block length, When the rebook would split a contiguous maker block into segments shorter than the configured minimum, Then that candidate is rejected if hard or flagged as soft with a warning count incremented. - Given a candidate slot preserves all attendees' maker-hours blocks according to policy, When alternatives are ranked, Then candidates that preserve longer contiguous focus windows are ranked higher (tie-breaker after ripple score).

Soft Guardrail Override Workflow with Reason Capture

- Given a candidate time only violates soft guardrails, When a user selects this slot, Then the UI requires explicit confirmation with a mandatory free-text reason (minimum 10 characters) and shows the list of soft guardrails impacted. - Given an override is confirmed, When the meeting is rebooked, Then the calendar event is labeled as "Exception" in-app and the invite description includes the override reason and impacted guardrails. - Given an override occurs, When audit logs are written, Then the log includes user ID, timestamp, old time, new time, impacted soft guardrails, reason text, and before/after ripple metrics.

Lunch Windows and No-Meeting Days Across Time Zones

- Given each attendee's lunch window and no-meeting days are defined in local time and synced from org policy, When generating and validating candidate slots, Then no slot overlaps a hard lunch window or falls on a hard no-meeting day for any attendee. - Given conflicts with soft lunch windows or no-meeting days occur, When alternatives are presented, Then these candidates are ranked below fully compliant options and display per-attendee soft warnings. - Given daylight saving time transitions or ambiguous local times, When validating guardrails, Then the system evaluates guardrails using attendees' canonical time zones and resolves overlaps according to local civil time without cross-timezone drift.

Ripple-Minimizing Selection Under Guardrails

- Given a set of guardrail-compliant candidate slots within the search horizon, When selecting an automatic recommendation, Then the system chooses the slot with the lowest predicted ripple score (downstream reschedules within the next configured evaluation window) and zero hard guardrail breaches. - Given two or more candidates tie on ripple score and compliance, When breaking ties, Then the system prefers the earliest chronologically nearest slot, then the option earliest in the organizer's workday. - Given the selected slot triggers any soft guardrail warnings, When auto-selecting, Then the system does not auto-book and instead requires explicit override per the override workflow.

Audit Logging and Policy Versioning

- Given any rebooking attempt is initiated, When processing completes (success, failure, or override), Then an audit record is written containing policy version IDs used, rules evaluated, number of candidates evaluated, violations per candidate, final selection rationale, and outcome status. - Given organization policy or keyword list is updated, When the next rebook occurs, Then the system fetches the latest policy (or uses cache not older than the configured TTL) and records the policy version in the audit log. - Given audit logs are queried by an admin, When reviewing a specific rebook, Then the admin can see the exact guardrails and keywords in effect at decision time and the captured override reason if applicable.

One‑Click Rebook & Smart Notifications

"As a meeting owner, I want to rebook in one click and automatically notify attendees so that I don’t have to babysit the reschedule."

Description

Provide a streamlined action to rebook an existing meeting to the selected candidate slot, preserving conferencing links, agendas, and attendees. Automatically issue updated invites and send targeted notifications via email and Slack/Teams to only affected participants. Place short‑lived soft holds on leading candidates to prevent race conditions, gracefully release holds on decision, and manage declines with auto‑fallback from the ranked shortlist. All actions are tracked with status and error handling for reliability.

Acceptance Criteria

One-click rebook preserves meeting artifacts

Given an existing meeting with title T, agenda A, conferencing link L, attendees set S, and calendar event UID U And a ranked shortlist of candidate slots is displayed When the organizer clicks Rebook on candidate slot C Then the meeting start/end time updates to C And the conferencing link remains L And the agenda remains A And the attendees set remains S And the calendar event UID remains U with an incremented sequence/version And only one event exists for UID U after the operation And the operation completes within 5 seconds at the 95th percentile

Targeted notifications via email and Slack/Teams

Given the organizer rebooks a meeting to a new time And attendees include internal users with connected Slack/Teams and external guests without chat integrations When the rebook is confirmed Then internal attendees with connected chat receive a single consolidated chat notification and an updated calendar invite And internal attendees without chat receive an updated calendar invite and a single email notification And external guests receive an updated email invite only And no users outside the attendee list receive notifications And duplicate notifications are de-duplicated per channel per recipient And all notifications are dispatched within 60 seconds at the 95th percentile And delivery status is recorded per recipient and channel

Soft holds on top candidate slots prevent race conditions

Given a ranked shortlist of candidate slots [C1..Cn] with n >= 3 And a soft-hold TTL of 15 minutes When the shortlist is presented to the organizer Then soft holds are placed as tentative events on the top 3 candidates across all attendee calendars And availability reflects Busy for those hold periods during the TTL And if the organizer confirms Ck within the TTL, holds on all other candidates are immediately released And if the TTL expires with no decision, all holds are auto-released And hold placement and release operations are idempotent under retry and concurrent requests

Idempotent, concurrent-safe rebook execution

Given two or more concurrent rebook requests are issued for the same meeting When they target the same or different candidate slots Then exactly one request succeeds and the others return a conflict error without altering the event And the meeting ends with a single definitive time And no orphan soft holds remain after resolution And retries with the same idempotency key do not create duplicate updates or notifications

Auto-fallback on decline from mandatory attendee

Given the meeting is rebooked to C1 from a ranked shortlist [C1, C2, C3] And at least one mandatory attendee declines C1 within 30 minutes of the rebook When auto-fallback is enabled Then the system selects the next available slot in order (C2, then C3) that satisfies guard constraints and attendee availability And rebooks the meeting once to that slot And notifies only participants affected by the change And limits auto-fallback attempts to 2 before requiring organizer confirmation And logs the reason and outcome for each fallback attempt

Action audit trail and step-level error handling

Given any rebook action is attempted When processing completes or fails Then an immutable audit record is created including timestamp, actor, old/new time, selected slot rank, affected attendees, notifications sent, soft holds placed/released, and outcome (success/failure) And transient failures in notification dispatch or hold placement are retried with exponential backoff up to 3 times And terminal failures surface a clear error to the organizer with remediation guidance And step-level status and error codes are recorded and exposed in UI or logs And P95 end-to-end rebook latency is under 5 seconds excluding third-party provider latency

What‑If Impact Preview

"As a scheduler, I want to preview the impact of each candidate time so that I can choose the option with the least disruption."

Description

Before committing, display a comparative preview for top candidate slots, including ripple cost breakdown, attendees impacted, guardrails triggered or avoided, fairness score change, recurrence effects, and buffer/travel implications. Allow quick adjustment of constraints (e.g., make a rule soft for this instance) and instant recompute. Present clear explanations and color‑coded risk indicators so schedulers can make confident, minimally disruptive choices.

Acceptance Criteria

Preview Top Candidate Slots Comparison

- Given a user opens the What‑If Impact Preview for a selected meeting, When the preview loads, Then display between 3 and 5 top candidate slots ranked by lowest ripple cost. - For each candidate slot, Then display the following metrics: ripple cost (integer), conflicts created (count), conflicts resolved (count), guardrails breached (count) with hard vs soft breakdown, attendees impacted (count), fairness score delta (numeric between -1.0 and +1.0 to one decimal), recurrence impact (occurrences affected count), and buffer/travel impact (minutes gained/lost). - Then the preview must render initial results within 2.0 seconds for scenarios up to 12 attendees and a 12‑week recurrence window (95th percentile), and within 4.0 seconds for up to 25 attendees (95th percentile). - When fewer than 3 feasible slots exist, Then show all feasible slots and display a notice stating "Only X feasible slots" without error. - Then sorting must apply tie‑breakers in order: highest fairness delta, fewest guardrail breaches, earliest calendar date/time.

Color‑Coded Risk Indicators and Legend

- Given candidate slots are displayed, Then each candidate shows a risk badge using colors: Green (no guardrail breaches and ripple cost ≤ 1), Yellow (only soft breaches or ripple cost 2–3), Red (any hard breach or ripple cost ≥ 4). - Then each color state must include an icon and text label; color is not the sole carrier of meaning. - Then all badges and text meet WCAG 2.1 AA contrast (≥ 4.5:1) and are announced with accessible names for screen readers. - When a user hovers or taps a badge, Then a tooltip explains the assigned risk including specific guardrails triggered/avoided and numeric thresholds. - Then a persistent legend is visible within the preview and remains synchronized with badge definitions.

Constraint Adjustment with Instant Recompute

- Given the preview is visible, When a user softens a guardrail (Hard → Soft) or adjusts constraints (meeting window, buffer minutes, attendee optionality), Then all candidate metrics recompute and refresh within 1.5 seconds at the 95th percentile without a page reload. - Then the UI preserves scroll position and focus on the previously selected element after recompute. - Then updated candidates display transient diff indicators (e.g., Δ fairness +0.2, ripple −1) for 5 seconds. - When the user clicks Undo or presses Ctrl/Cmd+Z, Then prior constraints and results are restored within 1.5 seconds and diffs are cleared. - Then all recomputations are idempotent and produce identical results for identical inputs.

Attendee Impact and Maker‑Hours Protection

- Given candidate slots are shown, Then each candidate lists per‑attendee local time and a marker indicating whether it lands within protected maker hours. - Then a candidate is marked Invalid if >20% of attendees would breach hard maker‑hour guardrails; invalid candidates cannot be committed. - When the user filters to "Impacted only", Then the attendee list updates within 500 ms to show only negatively impacted participants. - Then the details panel surfaces the top 3 most impacted attendees sorted by severity score with their individual impact explanations. - Then counts and markers must match the underlying calendar simulation within ±1 minute tolerance for time boundaries.

Recurrence Effects and Series Safety

- Given the meeting is part of a series, Then the preview shows whether changes apply to "this instance" or "entire series" and displays number of occurrences affected. - Then ripple cost is presented as cumulative (sum) and per‑occurrence average when series is selected. - When a change would shift the series template by more than ±15 minutes from its standard slot, Then show a "Series drift" warning with Yellow if ≤30 minutes, Red if >30 minutes. - When the user toggles between "this instance only" and "entire series", Then all metrics recompute within 2.0 seconds (95th percentile) and the drift warning updates accordingly. - Then the preview flags any predicted holiday/OOO collisions across the affected occurrences with counts and first occurrence date.

Actionability and One‑Click Commit

- Given candidates are visible, Then each candidate provides a primary "Schedule this slot" action that commits the selection. - When the user commits, Then a confirmation modal summarizes time, attendees added/removed, fairness delta, guardrails soft‑applied, recurrence scope, and buffer/travel changes; user can Confirm or Cancel. - When commit succeeds, Then the meeting is updated, invites are sent, and an audit log entry is recorded with timestamp, operator, constraints, and computed metrics; a success toast appears within 1.0 second. - When commit fails, Then show an error with a Retry option and the next‑best candidate suggestion; no partial state is saved (all‑or‑nothing). - Then the committed result matches the last shown preview values within specified tolerances (time ±1 minute, fairness delta ±0.1, ripple cost exact).

Calendar Connectors & Permissions

"As an IT admin, I want secure, least‑privilege calendar integration so that RippleGuard can simulate schedules without overexposing data."

Description

Deliver secure, least‑privilege integrations with Google Workspace and Microsoft 365 to access free/busy, time zones, and event metadata required for simulation. Support OAuth with granular scopes, domain‑wide delegation options, shared/resource calendars, and per‑user consent. Implement caching with configurable TTLs, robust rate‑limiting/backoff, DST normalization, and encryption in transit/at rest. Provide admin controls, audit logs, and data residency configuration to meet compliance needs while ensuring simulation accuracy and responsiveness.

Acceptance Criteria

OAuth Consent with Least-Privilege Scopes

Given a user initiates connector setup for Google Workspace or Microsoft 365 When the consent screen is presented Then only scopes required to read free/busy, attendee response status, event start/end times, organizer, meeting link, user time zone, and calendar list are requested, excluding event body/attachments and write scopes by default Given the user completes consent When API requests are executed Then calls are limited to granted scopes and any attempt beyond those scopes is blocked and recorded in audit logs Given the user revokes consent or disconnects the connector When revocation is detected via webhook or polling (≤ 5 minutes) Then all access tokens are invalidated, user-specific caches are purged, and the UI reflects a disconnected state Given the user/admin toggles an optional "Create/Update Invites" capability When enabled Then additional write scopes are explicitly requested and must be consented to before any write occurs When disabled Then no write scopes are requested and all write operations are blocked

Domain-Wide Delegation Configuration & Enforcement

Given a tenant admin configures domain-wide delegation/Application Permissions with specified scopes When impersonation is used for an in-tenant user during simulation Then only read operations necessary for free/busy and event metadata are permitted unless write capability is explicitly enabled, and impersonation is limited strictly to the selected users Given an attendee is outside the managed tenant When included in a simulation Then the system does not attempt impersonation and uses per-user consent or publicly shared free/busy endpoints where available; otherwise the attendee is treated as unknown availability Given the admin revokes or narrows delegation scopes When the next impersonated call is attempted Then impersonation stops within 5 minutes, the admin console shows an actionable error, and an audit entry captures the failing scope and user context

Shared and Resource Calendars Coverage

Given a connected account has access to shared and resource calendars When calendar discovery runs Then the system lists those calendars and allows per-user or admin inclusion/exclusion for simulation Given a resource calendar (e.g., meeting room) is included When requesting availability during simulation Then free/busy is fetched and respected for conflicts, and no event body content is retrieved Given calendar ACLs change When the next sync occurs (≤ 10 minutes) Then access reflects the new ACLs, unauthorized calendars are removed from cache, and simulations exclude them

Caching TTLs and Staleness Management for Simulation Accuracy

Given free/busy data is fetched When caching is enabled Then free/busy cache TTL is configurable per connector (default 120s, range 30–600s) with per-user overrides, and expired entries refresh on demand Given provider rate limits or transient errors occur When cache TTL has expired but staleness threshold has not (default 5 minutes, configurable) Then simulations may use cached data and mark results as stale with last-refreshed timestamps in logs/telemetry Given a user disconnects or consent is revoked When revocation is detected (≤ 5 minutes) Then all cached tokens and calendar data for that user are purged immediately Given calendar lists change infrequently When caching is applied Then calendar list TTL is configurable (default 15 minutes, range 5–1440 minutes) and respected

Rate Limiting, Backoff, and Idempotent Retries

Given the provider returns HTTP 429 or a Retry-After header When issuing subsequent requests Then the client applies exponential backoff with full jitter (base 1s, cap 64s) and honors Retry-After Given a transient 5xx error occurs When retry policy executes Then at most 5 retries are attempted before surfacing a clear, actionable error to the caller Given event create/update operations are performed When retries occur Then idempotency keys are used to prevent duplicate events across providers Given sustained rate limiting persists beyond 2 minutes When a simulation is requested Then the system uses last-known cached data per staleness rules and reports degraded mode via telemetry/UI

Time Zone and DST Normalization Fidelity

Given attendees span multiple time zones When computing candidate windows Then all times are normalized using the IANA TZ database and Windows time zones are deterministically mapped to IANA equivalents Given a DST transition day with missing or repeated local times When proposing slots Then nonexistent local times are excluded and repeated hours are disambiguated with correct UTC offsets Given tzdata updates are released When new rules become available Then the platform updates its time zone data within 72 hours and re-normalizes stored mappings Given an event crosses a DST boundary When displaying attendees’ local times Then start and end times reflect correct local wall times and provider APIs report matching UTC offsets

Security & Compliance: Encryption, Audit Logs, and Data Residency

Given any connector traffic is transmitted When requests/responses occur Then TLS 1.2+ is enforced and weak ciphers are disabled Given tokens, calendar metadata, and caches are stored When data is at rest Then it is encrypted using AES-256 or FIPS 140-2 validated cryptographic modules, with keys managed by KMS and automatic rotation at intervals ≤ 90 days Given an admin selects a data residency region When storing or processing cached calendar data and logs Then data remains within the selected region; cross-region transfers are blocked and logged with governance overrides Given calendar data is accessed (read/write/impersonation) When operations complete or fail Then an immutable audit log records actor, subject, operation, scope, timestamp, outcome, and request identifiers; logs are searchable, exportable (CSV/JSON), and retained per policy (minimum 90 days)

Equity Scoreboard Integration & Tie‑Breaking

"As a remote teammate, I want rebooking to account for past inconveniences so that meeting times remain fair over the long run."

Description

Integrate rebooking decisions with TimeMeld’s equity scoreboard to maintain rotation fairness and prevent repeated inconvenience for the same individuals or regions. Compute fairness deltas for each candidate and apply them as tie‑breakers in the selection algorithm. On confirmation, update scoreboard metrics, annotate the meeting with fairness context, and surface any accrued fairness debt to be repaid in future scheduling windows, keeping long‑term balance intact.

Acceptance Criteria

Fairness Delta Tie-Breaker Applied

Given a set of candidate slots where base_ripple_score differences are <= 0.01 When the selection algorithm evaluates candidates Then it computes total_fairness_delta for each candidate as the sum of attendee_fairness_delta weighted by role_weight and region_weight from the equity scoreboard And it selects the candidate with the lowest total_fairness_delta And if multiple candidates have equal total_fairness_delta within 0.001 Then it selects the earliest start_time in organizer local time And if still tied Then it selects the candidate with the lowest candidate_id lexicographically And it records the chosen candidate and all evaluated fairness_deltas in the decision log

Repeated Inconvenience Guard Within Rolling Window

Given an attendee has >= 1 inconvenience event in the past 14 days with inconvenience_score >= 0.7 And at least one candidate exists within 10% of the minimal ripple_cost that assigns this attendee an inconvenience_score < 0.7 When the algorithm selects a rebook slot Then it must not choose a candidate that assigns this attendee an inconvenience_score >= 0.7 Unless no candidate within 15 minutes of the target time meets ripple_cost within 10% of the minimum Then it may choose the minimal ripple_cost candidate but must append a fairness_debt entry for that attendee and region

Scoreboard Update on Rebook Confirmation

Given a rebook proposal is confirmed by the organizer When the confirmation event is processed Then the equity scoreboard is updated atomically with per-attendee rotation count, personal fairness_debt/credit adjustments, and regional aggregates And a meeting annotation is added summarizing prior_score, post_score, and fairness_delta for each attendee And an audit event equity_update.created is emitted with meeting_id and decision_key And the update is idempotent based on (meeting_id, confirmation_id) And no scoreboard changes occur for proposals that are simulated, expired, or canceled before confirmation

Fairness Debt Surfaced Post-Selection

Given a selected candidate generates non-zero fairness_debt entries When the selection result is returned Then the UI displays a fairness banner listing each attendee/region with debt > 0 and the first suggested repayment window And the API response includes fairness_debt[] with attendee_id/region_id, amount_points, and repayment_window_start/end And any attendee with amount_points >= 2.0 is labeled Repay Soon

Deterministic Outcome Under Identical Inputs

Given identical inputs (attendee set, calendars, configuration, equity scoreboard snapshot, target metadata) and a fixed random_seed When the selection algorithm runs multiple times Then it returns the same selected candidate_id and identical fairness_delta values And the decision log stores a decision_key hash of the inputs and tie-break path And no stochastic choice occurs without the provided random_seed

Explainable Decision and Audit Trail

Given a completed selection When an admin requests the fairness explanation via UI or API Then the system returns an explanation including per-attendee prior_score, post_score, fairness_delta, role_weight, region_weight, base_ripple_score, total_fairness_delta for all evaluated candidates, tie-break reason, and final rationale And the explanation and inputs snapshot are retained for at least 90 days And PII fields are redacted according to privacy settings

Equity Ledger Lock

Enforces rotation and burden limits at reschedule time with a clear preview of who gets earlier/later and how the change impacts the equity scoreboard. If a tradeoff is unavoidable, it offers auto-compensation (e.g., next-owner swap or future offset) before you confirm—preventing silent bias creep.

Requirements

Reschedule Policy Engine Enforcement

"As a remote team organizer, I want reschedules to be automatically checked against fairness and burden rules so that no one is repeatedly stuck with inconvenient times."

Description

Evaluate every reschedule action against workspace/team rotation rules and participant burden limits (max early/late minutes per period, quiet hours, protected days) before confirmation. Use attendee timezone profiles and historical load to score proposed times and generate compliant alternatives prioritized by TimeMeld’s ergonomics model. Block non-compliant choices, surface specific rule violations, and calculate tentative equity credits/debits against the Equity Scoreboard for the preview. Expose machine-readable validation results to the UI and API and support synchronous execution for organizer-initiated reschedules.

Acceptance Criteria

Block Quiet Hours and Protected Days at Reschedule

Given workspace/team policies define quiet hours and protected days per attendee, and the organizer initiates a reschedule When the organizer selects a proposed time that intersects any attendee’s quiet hours or protected day Then the engine returns decision=block and prevents confirmation And the result includes a violations array with an entry per violated rule containing: rule_code, rule_name, impacted_attendees[user_id, local_start, local_end], and evidence[timezone, local_date] And the UI/API receive at least 3 compliant alternatives within the requested scheduling horizon, sorted by ergonomics_score descending And each alternative’s attendees’ local times do not intersect quiet hours or protected days for any attendee

Enforce Max Early/Late Minutes Budget with Auto-Compensation

Given each attendee has max early_minutes and late_minutes budgets defined per rolling 7-day period and historical burden is recorded When the proposed time would cause any attendee’s early or late minutes to exceed their budget after application Then the engine returns decision=block with a violation detailing attendee_ids, before_totals, deltas, and projected after_totals And the result includes auto_compensation options: next_owner_swap and future_offset with required_minutes >= exceeded_minutes and a proposed window within the next 14 days And if the organizer selects an auto_compensation option, the follow-up validation returns decision=allow and reflects the applied compensation in the equity preview

Rotation Rule Compliance and Ownership Preview

Given a configured round-robin ownership rotation rule for the meeting series When a reschedule would break rotation order or repeat the current owner contrary to rule Then the engine returns decision=block with violation including current_owner, expected_next_owner, and rule_code=rotation And the preview payload shows before and after next_owners sequences (minimum length 3) and identifies the owner for the proposed slot And if the organizer selects the next-owner swap compensation, the revalidation returns decision=allow and the after sequence reflects the swap

Ergonomics-Scored Compliant Alternatives Generation

Given attendee timezone profiles and historical attendance/load are available When a non-compliant proposed time is evaluated Then the engine generates at least 5 compliant alternative slots within a 14-day window And each alternative includes: start_utc, end_utc, ergonomics_score in [0.0,1.0], attendance_uplift_pct, and per_attendee local_time preview And alternatives are sorted by ergonomics_score descending and all pass all active rules (zero violations)

Equity Credits/Debits Preview Consistency

Given a compliant proposed time or alternative is selected for preview When equity credits/debits are computed Then the preview includes per_attendee entries with user_id, minutes_early_delta, minutes_late_delta, credit_debit, and ownership_delta And the sum of all credit_debit values equals 0 and no ledger is committed until confirmation=true And UI tags each attendee as earlier, later, or neutral consistent with the minutes_*_delta signs

Machine-Readable Validation Result Contract

Given the Validation API is called for a reschedule evaluation When the request is processed Then the response is returned as JSON with schema_version="1.0" and fields: decision, reasons[], violations[], alternatives[], equity_preview, and timing_ms And for allow decisions, violations[] is empty and all alternatives[] (if present) are compliant; for block decisions, decision=block and violations[] has at least one entry with rule_code and impacted_attendees And the response time is <= 2000 ms at p95 for requests with up to 12 attendees and a 30-day search horizon

Synchronous Organizer Reschedule Execution and Idempotency

Given the organizer initiates a reschedule from the UI When the organizer selects a new time and requests validation Then the policy engine executes synchronously and returns a result within 1500 ms at p95 for meetings with up to 12 attendees And confirmation controls remain disabled until a decision=allow is received And if the same request_id is retried within 60 seconds, the engine returns an identical decision, reasons, and alternatives (idempotent)

Real-time Equity Impact Preview

"As an organizer, I want to see exactly how a new time affects each participant and the rotation before I confirm so that I can make an informed, fair decision."

Description

Present a live, pre-confirmation panel that shows per-attendee impact in minutes earlier/later, equity score deltas, and the next-owner rotation outcome for the proposed change. Highlight compliance status with badges (Compliant, Needs Compensation, Blocked) and annotate the specific constraints affected. Update instantly as the organizer drags a time, selects alternatives, or toggles attendees. Accessible in web and calendar add-ins, supports keyboard navigation and screen readers, and localizes time and date formats.

Acceptance Criteria

Per-Attendee Impact Preview

Given an organizer proposes a new time for an existing meeting and opens the Real-time Equity Impact Preview When the preview renders Then each included attendee shows name, ±minutes earlier/later (rounded to nearest minute) relative to their local time at the proposed date, and equity score delta (signed, one decimal) And the next-owner rotation outcome displays the next owner name and date based on the proposed change And any attendee with 0 minutes change and 0.0 score delta displays 0 with neutral styling And excluded attendees are not listed

Compliance Badge and Constraint Annotations

Given fairness constraints and burden limits are configured for the workspace When a proposed change is previewed Then the panel shows exactly one badge state from [Compliant, Needs Compensation, Blocked] And Blocked is shown if any hard rule is violated And Needs Compensation is shown if no hard rules are violated but fairness thresholds are exceeded for any attendee And Compliant is shown otherwise And the panel lists each triggered constraint with a short code and human-readable description And in Blocked state, the Confirm action is disabled and a tooltip explains which constraint blocks the change And badge colors meet WCAG AA contrast

Real-Time Update on Drag and Toggle

Given the preview panel is open When the organizer drags the proposed time on the calendar grid Then per-attendee minutes earlier/later, equity score deltas, next-owner rotation, and badge state update within 300 ms of the last input event And while the pointer is moving, the panel refreshes at least 5 times per second When the organizer toggles attendee inclusion or selects an alternative slot Then the same fields update within 300 ms of the interaction

Cross-Surface Parity (Web and Add-ins)

Given the organizer performs the same proposed change in the web app and in supported calendar add-ins When the preview is shown on each surface Then the per-attendee minutes earlier/later, equity score deltas, next-owner rotation, badge state, and constraint annotations are identical, allowing rounding differences of at most ±1 minute and ±0.1 score And all actions required to open and view the preview are available on each surface

Keyboard Navigation

Given the preview panel is open When using only the keyboard Then all interactive elements are reachable via Tab/Shift+Tab in a logical order and have visible focus indicators And attendee include/exclude toggles are actionable via Space or Enter And alternative slot selection is reachable and selectable via keyboard And Escape closes the panel without side effects And no keyboard traps are present

Screen Reader Accessibility

Given a screen reader is active When the preview panel opens Then it is exposed as a named region with an accessible name "Equity Impact Preview" And each attendee row has a role and label that includes the attendee name, minutes earlier/later, and equity score delta And the compliance badge is announced with its state and a summary of triggered constraints And when values change, a polite live region announces the updated badge and the top attendee changes And the panel conforms to WCAG 2.1 AA for semantics and non-text contrast

Localization and Timezone Handling

Given the organizer's locale and timezone are set When the preview renders Then all displayed times and dates are formatted according to the organizer's locale (including 12/24‑hour and day/month order) And per-attendee minutes earlier/later are computed using each attendee's timezone at the proposed date, accounting for daylight saving transitions And numeric formatting (minus sign, decimal separator) follows the organizer's locale And changing the organizer locale updates formats on next render

Auto-Compensation Suggestions

"As an organizer, I want the system to offer fair compensation options when perfect slots don’t exist so that I can proceed without introducing silent bias."

Description

When a compliant slot is unavailable or a slightly non-compliant time is selected, automatically propose compensation options such as next-owner swap, future offset credit/debit (minutes bank), or role-weighted burden adjustment. Simulate each option’s impact on the Equity Scoreboard, ensure hard caps aren’t breached, and default to the option that restores balance soonest. Allow one-click apply/compare, write chosen compensation as provisional ledger entries, and roll back on cancellation.

Acceptance Criteria

Non‑Compliant Selection Triggers Auto‑Compensation Suggestions

Given a user is rescheduling a meeting in TimeMeld And no fully compliant slot is available OR the selected time is within the configured soft non‑compliance tolerance When the user selects or requests that time Then the system generates compensation suggestions including next‑owner swap, minutes bank credit/debit, and role‑weighted burden adjustment when applicable And suggestions are computed and displayed within 1.5 seconds And any suggestion that would breach a hard cap is excluded from the list And if at least two valid suggestions exist, at least two are shown; otherwise a single valid suggestion is shown And each suggestion is labeled with its compensation type

Equity Scoreboard Impact Simulation and Preview

Given the suggestions panel is open for a reschedule When suggestions are shown Then each suggestion displays a preview including per‑participant delta minutes, earlier/later indication, projected equity score change, and next‑owner rotation impact And the preview includes a total equity variance change metric for the group And values in the preview match the simulated ledger outcome within ±1 minute per participant And any potential hard cap proximity (within 10% of cap) is visually indicated

Recommended Option Restores Balance Soonest

Given two or more valid compensation suggestions are available When the system ranks suggestions Then the top suggestion is marked Recommended and pre‑selected by default And the ranking minimizes time‑to‑balance across participants within the next two rotation cycles, breaking ties by lowest projected equity variance, then lowest added weekly burden, then least deviation from core hours And the ranking rationale is accessible via a tooltip on the Recommended label

One‑Click Compare and Apply Compensation

Given the suggestions panel is open When the user clicks Compare on any two suggestions Then a side‑by‑side scoreboard preview is displayed with synchronized participant ordering and metric highlighting When the user clicks Apply on a suggestion Then the selected suggestion is applied in a single click, the meeting time preview updates, and a confirmation banner appears And the apply action completes within 1 second and remains reversible until final confirmation

Provisional Ledger Entries and Rollback on Cancellation

Given a suggestion has been applied but the reschedule is not yet confirmed When the apply occurs Then provisional ledger entries are written with type=provisional, linked to the reschedule operation ID and meeting ID, and timestamped And the provisional entries adjust the simulated scoreboard but do not affect committed balances When the user cancels the reschedule Then all provisional entries for that operation are removed within 1 second and the scoreboard reverts with no residual effects And the system logs both the provisional write and rollback in the audit log

Hard Cap Enforcement in Suggestions

Given hard caps are configured in Equity Ledger Settings When generating suggestions for a non‑compliant or near‑compliant time Then any option that would breach a hard cap is not presented and is flagged in diagnostics And if no valid suggestion exists without breaching caps, the UI displays No compliant compensation available and disables Apply And the API returns 0 valid suggestions with reason codes indicating the cap(s) preventing suggestions

Policy Configuration & Guardrails

"As a workspace admin, I want to configure fairness rules and guardrails so that rescheduling enforces standards that match our team’s needs."

Description

Provide admin controls to define and version rotation cadence, max early/late budgets per person and per team, quiet hours, protected days, role-based weighting, and opt-out rules. Offer presets (e.g., Global Distributed, EU/US Overlap) and a simulator to test settings against recent meetings. Enforce effective dates, audit changes, and expose read-only policy via API to clients for consistent validation.

Acceptance Criteria

Policy Versioning, Effective Dates, and Auditing

Given an admin creates a new policy version with a future effective date, When the policy is saved, Then the system stores it as a draft with the specified effective_at timestamp and it does not affect scheduling until that timestamp. Given the current datetime is before the new policy’s effective_at, When meetings are scheduled or rescheduled, Then the previous effective policy version is applied and logged as the evaluator. Given the current datetime reaches or passes effective_at, When the next scheduling/rescheduling occurs, Then the new version becomes active and the version_id is included in decision logs and API responses. Given any policy create/update/delete action, When saved, Then an audit record is written including actor, org, before/after diff, reason, ip_address, timestamp, and policy version_id. Given an admin attempts to backdate effective_at earlier than now, When saving, Then the system blocks the change unless the actor has an explicit override permission; if overridden, a mandatory reason is captured and flagged in audit logs.

Rotation Cadence Configuration and Reschedule Enforcement

Given rotation cadence is configured (e.g., weekly, biweekly, custom sequence), When a meeting is rescheduled, Then the proposed next owner is calculated from the active policy version and cadence at reschedule time and displayed prior to confirmation. Given a rotation lock window (e.g., 24 hours pre-meeting) is configured, When a reschedule occurs within the lock window, Then ownership does not rotate, a rationale is shown, and the non-rotation is logged to the audit trail. Given a user attempts to manually pick an owner that violates the configured cadence, When confirming, Then the action is blocked unless the user has override permission and provides a justification which is recorded. Given ownership changes due to reschedule, When confirmation occurs, Then the equity scoreboard preview updates to show delta by participant and will persist the change post-confirmation.

Early/Late Budgets with Auto-Compensation on Reschedule

Given per-user and per-team early/late minute budgets are configured for a rolling window (e.g., 90 days), When generating candidate reschedule times, Then options that would exceed any participant’s remaining budget are flagged or filtered and the budget impact is shown per option. Given all feasible options exceed at least one budget, When the user selects auto-compensation, Then the system proposes compensation strategies (e.g., next-owner swap, future offset) with quantified impact and links the selected plan to the meeting upon confirmation. Given a reschedule is confirmed, When the new time is saved, Then early/late debits/credits are applied within 60 seconds to individuals and aggregated to team budgets, and the equity scoreboard reflects the changes. Given a compensation plan was applied, When the compensating event occurs (e.g., future offset executed), Then the system reconciles the planned credit and marks the plan as completed in the audit log.

Quiet Hours and Protected Days Enforcement

Given quiet hours and protected days are configured per participant timezone or locale, When generating reschedule suggestions, Then any slot overlapping a participant’s quiet hours or protected days is excluded by default and the count of excluded slots is shown. Given a user with override permission attempts to include a conflicting slot, When they proceed, Then the system requires explicit acknowledgment, captures a reason, and lists impacted participants; the confirmation writes an audit entry with participant_ids and conflict types. Given multiple participants have non-overlapping quiet hours, When suggestions are computed, Then the optimization favors ergonomic windows minimizing total quiet-hour conflicts according to policy weighting.

Role-Based Weighting, Presets, and Simulator Outcomes

Given an admin applies a preset (e.g., Global Distributed, EU/US Overlap), When saving, Then the preset parameters are materialized into the policy version and labeled with preset_id and any local overrides. Given role-based weighting is configured, When scoring candidate meeting times in the simulator, Then higher-weight roles contribute proportionally more to the ergonomic score and the score breakdown per role is displayed. Given the simulator is run against the last N meetings (default 30, configurable 1–200), When executed, Then it outputs predicted owner rotations, attendance windows, early/late budget impacts, and a delta versus the current active policy, all exportable as CSV. Given a simulator run completes, When results are viewed, Then the policy version_id, dataset window, assumptions, and timestamp are included for reproducibility.

Read-Only Policy API Access and Caching

Given a client with a valid org-scoped API token requests GET /v1/policy?version=current, When authorized, Then the server returns HTTP 200 with a read-only JSON document containing version_id, effective_at, presets, budgets, weights, quiet hours, protected days, opt-out rules, and evaluation parameters; no admin PII is included. Given a client requests a specific version via GET /v1/policy/{version_id}, When the version exists within the client’s org, Then HTTP 200 with the document is returned; otherwise HTTP 404 is returned. Given responses include ETag and Last-Modified, When the client sends If-None-Match or If-Modified-Since for an unchanged document, Then the server returns HTTP 304 with no body. Given an OpenAPI schema is published, When the API response is validated against the schema in CI, Then any schema regression fails CI and triggers an alert.

Opt-Out Rules and Eligibility Controls

Given opt-out rules can be defined per user/role/team with start/end times and reasons, When scheduling or rescheduling, Then opted-out entities are excluded from owner rotation and budget calculations for the effective period. Given a user requests a temporary opt-out, When policy requires approval, Then the request remains pending until an admin approves; upon approval the effective window is enforced and logged with approver and reason. Given an opt-out is nearing expiration, When 24 hours remain, Then the system notifies the user and relevant admins and automatically reinstates eligibility at expiration with an audit entry.

Equity Ledger & Audit Trail

"As a compliance reviewer, I want a complete audit trail of how rescheduling decisions were made so that I can verify fairness and address exceptions."

Description

Maintain an immutable ledger of reschedule evaluations, chosen slots, equity deltas, compensation entries, ownership rotations, and any overrides with reason codes. Include actor IDs, timestamps, rule versions, and before/after snapshots for traceability. Provide export (CSV/JSON), admin review filters, and anomaly alerts (e.g., repeated overrides benefiting the same person). Respect data retention settings and PII minimization.

Acceptance Criteria

Reschedule Decision Is Fully Logged

- Given a user initiates a reschedule and confirms a new slot, When the system finalizes the reschedule, Then a ledger entry is appended capturing: meeting_id, request_id, previous_slot_utc, new_slot_utc, per_participant_equity_delta (unit, value), compensation_entries (type, value, target), ownership_rotation_result, overrides (flag, reason_code, actor_id), initiator_actor_id, confirmer_actor_id, created_at_utc, evaluation_completed_at_utc, rule_version, before_snapshot, after_snapshot, and ledger_id. - Given the ledger entry is written, Then the read API returns exactly these fields and values; And ledger_id is unique across the ledger. - Given malformed or partial data, When a write is attempted, Then the API responds 400 with validation errors and no ledger entry is created.

Ledger Is Append-Only and Tamper Evident

- Given an existing ledger entry, When a client attempts to update or delete it via API, Then the request is rejected with 403; And no row is changed. - Given a direct database attempt to modify a row, Then database constraints/triggers prevent the change and log a security event. - Given an error is discovered, When a correction is needed, Then a new correction entry is appended referencing original ledger_id with correction_reason and delta-only fields; And the original entry remains unchanged. - Given N sequential entries for a meeting series, Then each stores content_hash and prev_hash; And recomputing the chain verifies integrity end-to-end.

CSV/JSON Export With Field Coverage and Filtering

- Given an admin selects date_range, team_ids, meeting_series_ids, and format=CSV, When export is requested, Then a file is generated within 60 seconds for up to 100k entries and includes all required fields with header names matching the data dictionary. - Given format=JSON, Then the export returns a JSON array with the same fields and data types. - Given PII minimization is enabled, Then exports contain actor_id only (no names, emails, or timezone strings). - Given a filter on override_reason_code in [MANUAL_EXCEPTION, URGENT_OUTAGE], Then only matching entries are included.

Admin Review Filters and Performance

- Given an admin applies filters (actor_id, beneficiary_actor_id, rule_version, equity_delta>=threshold, has_override=true, date_range), When the search is executed, Then the result count and list match the filter and return within 2 seconds for up to 10k entries. - Given pagination parameters (page, page_size), Then results are chunked deterministically and stable across pages during the same query session. - Given sort by created_at_utc desc, Then the first page contains the newest entries.

Anomaly Alerts for Repeated Beneficiary Overrides

- Given the same actor benefits from overrides >=3 times or accrues equity_delta_benefit >= 2 hours within a rolling 30 days, When the latest qualifying entry is appended, Then an anomaly alert is created with summary, actor_id, counts, time_window, and deep-link to filtered review. - Given alert destinations are configured (email, webhook), Then alerts are delivered within 60 seconds and deduplicated to at most 1 alert per actor per 24 hours per rule. - Given an admin resolves an alert, Then subsequent alerts require new qualifying activity to trigger again.

Data Retention and PII Redaction

- Given retention_days=180, When an entry’s age exceeds 180 days and no legal_hold is active, Then PII fields remain minimized (actor_id only) and snapshots are redacted of personal details; And entry remains for aggregate integrity with tombstone markers for redacted fields. - Given a legal_hold is applied to a meeting_series_id, Then no redaction/purge occurs until the hold is removed. - Given an export request outside the retention window, Then redacted fields are absent and clearly marked as null/tombstoned.

Rule Versioning and Replayability

- Given a stored ledger entry with rule_version and config_hash, When the evaluation is replayed using stored inputs, Then the output matches the stored chosen_slot, equity_deltas, and compensation entries. - Given the rule engine version changes, When new reschedules occur, Then new entries record the new rule_version; And filters by rule_version return the correct subsets. - Given missing snapshot data, When replay is requested, Then the API returns 422 with a message indicating which inputs are missing.

Calendar Gate & Participant Notifications

"As a participant, I want clear notifications about how reschedules affect me and what compensation applies so that I can consent or raise concerns promptly."

Description

Integrate with Google and Microsoft calendars to gate event updates until Equity Ledger Lock passes. Create or update invites only after a compliant or compensated decision is confirmed. Send participant-specific notifications summarizing the change, personal early/late shift, applied compensation, and a time-bound appeal/decline option. Reconcile responses back into the ledger, retry on transient failures, and fall back with organizer prompts if consent windows expire.

Acceptance Criteria

Gate Calendar Update on Equity Check Result

- Given a reschedule is initiated in TimeMeld, When Equity Ledger Lock returns Compliant or Compensated and the decision is confirmed, Then the system creates or updates the event via the connected calendar provider API. - Given a reschedule is initiated in TimeMeld, When Equity Ledger Lock returns Non-compliant and no compensation is selected, Then no calendar provider API calls are made and the Send Updates control is disabled. - Given a compliant or compensated decision is confirmed, When the calendar update succeeds, Then an audit record is stored with decisionId, providerEventId, provider, status=success, and timestamp. - Given a compliant or compensated decision is confirmed, When the calendar update fails with a non-transient error, Then no ledger state is advanced, the user is shown a blocking error, and an audit record is stored with status=failure and errorCode.

Participant Notification Personalization and Content

- Given an event change is confirmed, When notifications are dispatched, Then each participant receives a message that includes old start and end times, new start and end times in the participant's local timezone, the early/late delta in minutes relative to their local time, the applied compensation summary, and an appeal or decline link with an absolute expiry timestamp. - Given a participant is the next owner after rotation, When the notification is generated, Then the message explicitly states the ownership change and their equity scoreboard impact. - Given notifications are generated, When sent to each participant, Then no other participants' personal deltas, timezones, or compensation details are included in the message. - Given a participant's personal time does not shift, When the notification is generated, Then the message states no personal time shift and omits the appeal option.

Time-Bound Appeal and Ledger Reconciliation

- Given a participant receives an appeal or decline link, When they respond before the expiry timestamp, Then the response is recorded with participantId, decision, timestamp, and the equity ledger is updated according to policy. - Given a participant declines within the window, When the event requires their attendance, Then the event status is set to Needs Attention and the organizer is notified with options to compensate or propose alternatives. - Given a participant appeals citing burden, When an auto-compensation rule is applicable, Then the system applies the compensation, updates the ledger, and sends updated notifications within 5 minutes. - Given multiple responses arrive, When reconciliation completes, Then the equity scoreboard shows a single consolidated result per participant without duplication and the audit trail lists all responses.

Transient Failure Retry and Idempotency

- Given a calendar provider or email service returns a transient error (HTTP 429, 5xx, or timeout), When the operation is retried, Then the system uses exponential backoff with jitter for up to 5 attempts within 10 minutes. - Given retries are attempted, When an operation eventually succeeds, Then only one calendar update and one notification per participant are effected by using idempotency keys or deduplication tokens. - Given all retries are exhausted, When the operation still fails, Then the organizer receives a single consolidated failure notification containing the impacted participants or providers and a Retry Now action.

Consent Window Expiry Organizer Fallback

- Given an appeal or decline window is active, When the expiry timestamp passes with no response from a participant, Then the system prompts the organizer to choose keep as is, apply default compensation, or re-propose times before any further updates are sent. - Given required attendees remain unresponsive at expiry, When the organizer does not act within 24 hours of the prompt, Then the event is placed on hold, stale links are invalidated, and an escalation email is sent to the organizer. - Given the organizer selects a fallback option, When confirmed, Then the calendar invites, notifications, and ledger are updated consistently and previous appeal links are invalidated.

Google and Microsoft Calendar Update Compliance

- Given Google Calendar is connected, When a compliant or compensated decision is confirmed, Then the event is created or updated with correct attendees, start and end times, timezone, description including equity summary snippet, and meeting join details preserved. - Given Microsoft 365/Outlook is connected, When a compliant or compensated decision is confirmed, Then the event is created or updated with the same fidelity as Google including attendees, times, timezone, description equity summary snippet, and join details preserved. - Given updates are blocked due to non-compliance, When the organizer attempts to send from TimeMeld, Then the action is blocked and the UI displays the Equity Ledger Lock reason and required compensation before enabling Send. - Given a mixed-attendee event using cross-provider invites, When updates are sent, Then all attendees receive standards-compliant iCalendar updates reflecting the new time and the ownership change in the event description.

Quorum Soft-Hold

Puts temporary holds on top candidate times and gathers one-tap approvals from required roles via Slack/email. The first slot to reach quorum auto-confirms; if key people decline, Slipstream falls back to the next fair option—speeding alignment without calendar ping-pong.

Requirements

Role-Based Quorum Rules Engine

"As an organizer, I want to define which roles and how many approvals are required for a meeting slot so that the first acceptable time can be auto-confirmed without waiting on every invitee."

Description

Provides configurable quorum policies that define which roles (e.g., PM, Eng Lead, Ops) and how many approvals are required for a slot to be confirmed. Supports must-have vs. optional attendees, per-meeting templates, and dynamic mapping of invitees to roles. Evaluates approvals per candidate slot, respects out-of-office and delegation rules, and exposes a clear quorum state for each option. Integrates with TimeMeld’s scoring model so that quorum checks run against the highest‑ranked ergonomic windows first.

Acceptance Criteria

Per-Meeting Quorum Policy Configuration and Validation

Given a meeting template with role quorum rules (role name, must_have flag, required_count) When the template is saved Then the rules engine validates that required_count is a non-negative integer and role names are unique within the template And Given validation fails When saving Then the engine rejects the save with a list of field-specific errors and no policy is stored And Given validation passes When retrieving the template Then the stored policy matches the submitted configuration exactly

Must-Have vs Optional Enforcement and Numeric Aggregation

Given a policy that sets must-have role R1 with required_count = N and optional role R2 with required_count = M When evaluating approvals for a candidate slot Then quorum is achieved only when approvals for R1 >= N, regardless of R2 counts And Given multiple approvals from invitees mapped to R1 When approvals reach N Then additional approvals for R1 do not change quorum state but are recorded And Given zero approvals for a must-have role When evaluating Then quorum_state is "partial" and not "quorum_met"

Dynamic Invitee-to-Role Mapping and De-duplication

Given per-meeting role overrides and directory role attributes When mapping invitees to roles Then per-meeting overrides take precedence, directory roles fill remaining mappings, and unmapped invitees are classified as "no_role" and do not count toward quorum And Given an invitee mapped to multiple roles When the invitee approves a slot Then the approval is counted once toward a single role and is not double-counted across roles

Per-Slot Quorum Evaluation and State Transitions

Given multiple candidate slots under soft hold When approvals and declines are received over time Then the engine updates each slot independently and transitions quorum_state among {pending, partial, quorum_met, blocked_decline, expired} according to approvals and timeouts And Given a decline from any invitee in a must-have role for a slot with no delegate When processed Then the slot quorum_state becomes "blocked_decline" and it cannot reach "quorum_met"

Out-of-Office and Delegation Handling

Given a must-have invitee is marked out-of-office for the candidate slot and a delegate is configured for that invitee When the delegate approves Then the approval satisfies the invitee's role requirement for that slot And Given a must-have invitee is out-of-office and no delegate is configured When evaluating the slot Then the slot quorum_state is "blocked_ooo" and cannot reach "quorum_met" And Given both the invitee and their delegate approve When counting Then only one approval counts toward the role requirement

Quorum State Exposure and Role Breakdown

Given candidate slots exist When the API is queried for quorum status Then each slot response includes quorum_state and, per role, {required_count, approved_count, outstanding_count} that are numerically consistent And Given a Slack or email notification is generated for a candidate slot When rendered Then it displays the current quorum_state and explicitly lists outstanding must-have roles

Scoring Model Integration and Confirmable Flag

Given candidate slots each have an ergonomic score from the TimeMeld scoring model When the engine evaluates quorum Then it processes slots in descending score order and marks the highest-scored slot that reaches "quorum_met" with confirmable = true And Given two slots reach "quorum_met" in the same evaluation cycle with identical scores When selecting the confirmable slot Then the engine applies a deterministic tiebreaker (earliest start time, then earliest quorum_met timestamp) and marks only one as confirmable

Multi-Channel One-Tap Approvals (Slack & Email)

"As a busy attendee, I want to approve or decline proposed times with one tap in Slack or email so that I can respond quickly without opening a calendar UI."

Description

Delivers interactive Slack messages and actionable emails showing local-time candidate windows with approve/decline actions and optional "prefer" feedback. Uses signed links and Slack interactivity to attribute responses without login friction, supports mobile, and records decisions with timestamps. Includes contextual details (agenda, hold expiration) and lightweight reminders before hold expiry. Handles rate limiting, retries, and message updates as slot state changes.

Acceptance Criteria

Slack One‑Tap Approval Delivery and Recording

Given an open hold with candidate slots and a required participant mapped to a Slack user, When notifications are triggered for that participant, Then the participant receives a single Slack DM or channel message within 5 seconds containing interactive Approve, Decline, and Prefer actions for each candidate slot and showing agenda and hold expiration. Given the Slack message is delivered, When the participant taps Approve on a slot, Then the system attributes the approval to that participant and role without additional login, records a UTC timestamp to the second, updates the message to reflect the approval, and prevents duplicate approvals for that slot. Given the Slack message is delivered, When the participant taps Decline on a slot, Then the decline is recorded with a UTC timestamp, the message reflects the decline state, and the slot’s buttons are disabled for that participant to avoid repeated actions. Given the Slack message is delivered, When the participant taps Prefer on a slot, Then a non-binding preference is recorded (does not count toward quorum), is visible in the message, and can be updated by the participant by choosing Prefer on a different slot (previous preference is cleared). Given a participant repeats the same action for a slot, When a duplicate action request is received within any time window, Then the operation is handled idempotently and no additional records are created.

Email Signed-Link One‑Tap Attribution

Given an open hold with candidate slots and a participant with a valid email address, When notifications are triggered, Then the participant receives an actionable email within 60 seconds containing Approve, Decline, and Prefer buttons per slot implemented as unique signed, single-use links and showing agenda and hold expiration. Given the participant clicks an Approve link, When the signature is valid and the link is unexpired, Then the system records the approval with the participant identity and role without requiring login, stores a UTC timestamp to the second, displays a confirmation page within 2 seconds, and marks the link as consumed. Given the participant clicks a Decline link, When the signature is valid and the link is unexpired, Then the system records the decline with a UTC timestamp, displays a confirmation page, and marks the link as consumed. Given the participant clicks a Prefer link, When the signature is valid and the link is unexpired, Then the system records a non-binding preference for the slot and displays a confirmation page. Given a signed link is tampered with, expired (hold expired), or already consumed, When the link is opened, Then no new action is recorded and an informative state page (expired or already-processed) is shown within 2 seconds.

Accurate Local‑Time Rendering of Candidate Windows

Given participants reside in different time zones, When Slack messages and emails are generated, Then each candidate slot is rendered in the recipient’s local time zone with date and time labels and includes an explicit “Your time” indicator. Given the participant’s time zone is available from Slack profile or account settings, When rendering candidate slots, Then that time zone is used; otherwise a default time zone from the participant’s account is used, and if none exists, UTC is used. Given a candidate slot overlaps a daylight saving time transition for the recipient, When rendering, Then the time is shown using the correct DST offset for that date in the recipient’s IANA time zone. Given a recipient opens the email or Slack message on a device set to a different time zone than their account time zone, When a web confirmation page is displayed after a click, Then the page clearly shows both the slot in the participant’s account time zone and the device-local time to avoid ambiguity.

Mobile‑Friendly One‑Tap Interactions

Given a participant views the Slack message on iOS or Android, When they tap an Approve, Decline, or Prefer action, Then the action completes with a confirmation within 3 seconds on a 3G/slow‑LTE connection and the buttons have a minimum 44×44 px touch target. Given a participant opens the actionable email on a mobile client (Gmail, Apple Mail, Outlook mobile), When they tap any action button, Then the deep link opens in the default mobile browser and the confirmation page is responsive with readable text and tappable controls without horizontal scroll. Given a participant has dark mode enabled, When viewing the email or confirmation page, Then text maintains a minimum 4.5:1 contrast ratio and buttons remain visible and tappable. Given a participant uses a screen reader on mobile, When interacting with action buttons, Then each button has an accessible name that includes the slot local time and action (e.g., “Approve Tuesday 3 PM”).

Contextual Details and Reminder Before Hold Expiry

Given an open hold, When Slack messages and emails are generated, Then they include the meeting agenda summary and the exact hold expiration timestamp. Given a participant has not responded to any slot, When the hold has 10 minutes remaining until expiration, Then the participant receives a single lightweight reminder via their original channel (Slack or email) that includes current slot states and the time remaining. Given a participant submits any action (Approve, Decline, Prefer) on any slot, When reminder time is reached, Then no reminder is sent to that participant. Given a hold is confirmed or canceled before the reminder threshold, When reminder time would have occurred, Then no reminders are sent and prior messages are updated to show the final state.

Real‑Time Slot State Updates and Quorum Effects

Given a participant takes an action that changes a slot’s state (e.g., reaches quorum or loses a key approval), When the state changes, Then all previously sent Slack messages and the confirmation web pages reflect the new state within 10 seconds and disable actions that are no longer valid. Given a slot reaches quorum first, When auto‑confirmation occurs, Then recipients’ Slack messages and emails update to show the slot as Confirmed, all other slot actions are disabled, and late clicks on obsolete links return an already‑confirmed state page without recording new actions. Given a key participant declines a slot, When Slipstream fallback selects the next fair option, Then messages reflect the updated candidate list and any removed slot actions are disabled within 10 seconds. Given a hold expires without confirmation, When expiration occurs, Then messages show Hold Expired and all actions are disabled; clicking any prior link shows an expired state page.

Rate Limiting, Retries, and Idempotency

Given Slack API rate limiting (HTTP 429) is encountered, When sending messages or updates, Then the system honors Slack’s Retry‑After header, retries with exponential backoff up to 5 attempts, and ensures no duplicate messages via idempotency keys. Given transient email provider failures occur (5xx), When sending actionable emails, Then the system retries up to 3 times with exponential backoff and deduplicates sends via a stable message identifier to prevent duplicates. Given the action processing service experiences a transient outage, When a user clicks an action link or Slack button, Then the request is accepted, queued, processed within 60 seconds of service recovery, and the user sees a non‑blocking “processing” confirmation. Given the same action is received more than once due to retries or user double‑clicks, When processing, Then the operation is idempotent and only one decision record exists per participant per slot per action. Given any notification send or action processing attempt, When it completes, Then an audit log entry is written with participant, channel, slot, action, timestamp, and outcome (success/failure) for troubleshooting.

Calendar Soft-Hold Placement & Lifecycle

"As an organizer, I want TimeMeld to place temporary holds on the best candidate times across calendars so that those slots remain available while approvals are gathered."

Description

Places temporary, uniquely identifiable holds on top candidate slots across required attendees’ Google Workspace and Microsoft 365 calendars using tentative events or placeholders. Applies a configurable TTL, prevents duplicate or overlapping holds, and respects calendar privacy settings. Automatically extends, releases, or converts holds based on quorum outcomes while guaranteeing cleanup on expiry or cancellation. Provides visual indicators and a dedicated hold summary for organizers.

Acceptance Criteria

Soft-Hold Creation on Candidate Slots (Google & Microsoft)

Given an organizer selects at least two candidate time slots and required attendees with a mix of Google Workspace and Microsoft 365 accounts And a hold prefix and a TTL are configured for the scheduling session When the organizer initiates soft-hold placement Then a tentative placeholder event is created on each required attendee’s default calendar for each candidate slot And each placeholder reserves the time (busy/opaque or ShowAs=Tentative per provider) without sending a confirmed invitation And each placeholder contains a unique holdId and schedulingSessionId stored in provider-supported private/extended properties And if a placeholder with the same holdId already exists, it is updated in-place and no duplicate is created

Configurable TTL and Auto-Expiry Cleanup

Given holds are placed with a TTL of 2 hours When the TTL elapses without quorum and without manual or automatic extension Then all related placeholders are removed from every attendee’s calendar within 120 seconds And the organizer’s hold summary marks the session and affected slots as Expired with a timestamp And querying provider APIs for the holdId returns no remaining events

Quorum-Driven Conversion, Release, and Auto-Extension

Given required roles are defined and approvals are collected per candidate slot When the first candidate slot reaches quorum according to the role rules Then its placeholders are converted into a single confirmed meeting on all required attendees’ calendars And placeholders for all other candidate slots in the same session are removed within 120 seconds And the confirmed meeting references the original holdId and schedulingSessionId in private metadata When any candidate slot is within 10 minutes of TTL expiry and at least 80% of required roles have approved Then its TTL is automatically extended by the configured extension window and the new expiry is visible in the organizer UI and event metadata

Privacy-Respecting Hold Placement

Given some attendees’ calendar sharing is set to Private or limited details When soft-holds are placed Then other viewers of those calendars see only Busy blocks (or provider-equivalent minimal detail) with no descriptive content or attendee list And the organizer and the event owner can see the hold title and context per internal policy And holdId, roles, and session metadata are stored only in private or extended properties not exposed to other calendar viewers

Duplicate and Overlap Prevention and Idempotency

Given an attendee has overlapping candidate windows or placement is triggered multiple times for the same session When soft-hold placement runs Then no two holds overlap for the same attendee and time window within the same session And re-running placement for the same session and candidates creates no additional placeholders (idempotent) And attempts to create a duplicate or overlapping hold are skipped and recorded in the audit log with counts

Organizer Visual Indicators and Hold Summary

Given holds exist for a scheduling session When the organizer opens TimeMeld Then each candidate slot shows visual indicators including current approval count versus quorum, TTL countdown, hold state, and provider icon And a dedicated hold summary view lists each slot with holdId, expiry time, approval status by required role, and last activity timestamps And from the summary the organizer can extend TTL, release holds, or manually convert a slot, and the action propagates to all calendars within 120 seconds

Guaranteed Cleanup on Cancellation

Given an organizer cancels the scheduling session before quorum is reached When the organizer confirms cancellation Then all soft-holds for that session are removed from all attendee calendars within 120 seconds And the hold summary records the cancellation with timestamp and counts of holds removed And querying provider APIs for the session’s holdIds returns no remaining events

Auto-Confirm & Hold Revocation Orchestration

"As an organizer, I want the first slot that meets quorum to auto-confirm and all other holds to be withdrawn so that we finalize quickly and avoid confusion."

Description

When a candidate slot reaches the defined quorum, atomically converts that slot’s holds into a confirmed meeting, dispatches final calendar invites, and revokes all other active holds. Ensures idempotent operations and concurrency safety in case of near-simultaneous approvals. Sends confirmation notifications via Slack/email, updates the meeting record, and syncs with TimeMeld’s equity scoreboard to track scheduling burden and rotation.

Acceptance Criteria

Atomic Quorum Conversion and Hold Revocation

Given a candidate slot has active holds and a defined quorum threshold And no other slot is confirmed for this meeting When approvals received cause the slot to reach quorum Then the system confirms exactly that slot atomically And converts its holds to final invitations with a single meeting UID And transitions all other active holds for this meeting to revoked status And no other slot remains in held or tentative status for this meeting And all state changes share a single operationId and commit together And the end state is observable within the system within 10 seconds

Concurrency Control on Near-Simultaneous Approvals

Given two or more candidate slots receive approvals within 250 ms of each other And each would meet quorum absent locking When the system evaluates quorum under concurrent load Then exactly one slot is confirmed using a deterministic tie-breaker: earliest quorum timestamp, then lowest slotId And all other slots’ holds are revoked And no duplicate confirmations occur even under >=50 parallel approval events And external observers never see more than one confirmed slot at any point (linearizability)

Idempotent Retries and Duplicate-Safe Operations

Given an approval event is delivered multiple times due to retries or network duplication When the orchestration processes events with the same idempotency key Then the meeting remains a single confirmed event with the same meeting UID And no additional calendar events or invites are created And notifications are not re-sent more than once per recipient for the same confirmation And the final persisted state is identical regardless of 1 or many duplicate deliveries And duplicate requests return 200 OK with a reference to the original operationId

Confirmation and Revocation Notifications

Given a slot is confirmed by quorum When orchestration completes the transaction Then all required and optional invitees receive a confirmation via their configured channel(s) (Slack and/or email) And holders of other candidate slots receive a revocation/cancellation notice And messages include final date/time with timezone, conferencing link, and calendar attachment/ICS link And delivery succeeds within 60 seconds for the 95th percentile And no recipient receives more than one confirmation for the same event And notifications are sent only after the commit succeeds

Meeting Record Update and Audit Logging

Given a meeting is auto-confirmed When persistence is updated Then the meeting record shows status=confirmed, confirmedAt, finalSlotId, quorumDetails (roles/approvers), and meetingUID And an audit log entry includes operationId, actor=system, approvedBy list, revokedHoldIds, and notification dispatch results And API reads reflect these updates within 5 seconds (read-after-write) And the API returns a new version/etag so clients can detect the change

Equity Scoreboard Sync and Single-Burden Increment

Given a meeting is auto-confirmed When orchestration completes Then the equity scoreboard increments scheduling burden for the owning role/person exactly once And ownership rotation state is advanced according to policy And the scoreboard reflects the update to viewers within 10 seconds And retries do not produce multiple increments for the same operationId

Fallback Selection & Fairness Preservation

"As a cross-timezone team member, I want declined slots to trigger the next fair option automatically so that we don’t repeatedly schedule at inconvenient times."

Description

If key attendees decline or quorum becomes impossible for a held slot, automatically promotes the next best candidate according to timezone-weighted ergonomics and the equity rotation model. Reissues holds, carries forward participant preferences, and avoids repeatedly placing inconvenient times on the same individuals. Tracks attempt history, caps retry cycles, and escalates with a summary if no option can reach quorum by a defined deadline.

Acceptance Criteria

Auto-Promote Next Candidate After Decline or Timeout

Given a held slot within a Quorum Soft-Hold thread and required roles defined And at least one required attendee declines or the hold timer elapses without reaching quorum And at least one alternative candidate remains When the system evaluates fallback Then it selects the next candidate using the configured composite score (timezone-weighted ergonomics + equity rotation) And promotes it within the configured promotion SLA And reissues soft-holds and one-tap approvals via Slack/email to all required roles for the new candidate And releases calendar holds for the superseded slot per the configured hold-removal SLA And posts a reasoned update in the thread indicating decline/timeout and the promoted time

Carry Forward Preferences and Constraints to New Holds

Given participant hard constraints (work hours, DND windows, blackouts) and soft preferences captured for the thread When a new candidate is promoted Then the candidate satisfies 100% of hard constraints for all required attendees And the selected candidate’s aggregate soft-preference score is within the configured tolerance of the maximum score among remaining candidates And prior per-participant prefer/avoid choices are pre-selected in the new one-tap UI And any slot previously declined for a hard-constraint reason is never re-proposed in subsequent rounds of this thread

Fairness Preservation Across Fallbacks

Given the equity rotation model and per-attendee ergonomic score for each candidate When choosing a fallback candidate Then no attendee is assigned a time below the configured ergonomic threshold more than once within the rolling fairness window configured for this team Unless no quorum-capable candidate exists above that threshold before the deadline, in which case the selection proceeds and fairness debt is recorded for affected attendees And the selection summary includes the fairness impact and updated rotation state

Detect Quorum Impossibility and Skip

Given a held candidate and the set of required roles When |confirmed| + |pending but available| < |required roles| for that candidate Or any required role has only declines on that candidate Then the candidate is marked impossible, its holds are released within the configured hold-removal SLA, and the next candidate is promoted per fallback logic And an impossibility notice with per-role counts is posted to the thread

Retry Cap and Deadline-Based Escalation

Given a configured retry cap and quorum deadline for the thread When the number of promotions equals the retry cap without reaching quorum, or the current time reaches the deadline Then the system halts further promotions and sends an escalation summary via Slack/email to the organizer and required-role owners And the summary includes attempt history, reasons for each fallback, current fairness debt, and the top remaining viable options (if any) And the thread state is marked Escalated

Attempt History and Audit Trail

Given any fallback event (promotion or impossibility) When the event occurs Then an immutable history entry is stored with timestamp, candidate time (ISO 8601 with timezone), composite score components, quorum counts, reason code, notifications sent, holds applied/removed, and fairness impact And the history is retrievable via API and in-thread UI for at least 30 days And entries are ordered chronologically and cannot be edited, only appended

Conflict Detection & Live Recalculation

"As an organizer, I want TimeMeld to detect new conflicts while holds are active and adjust candidate slots automatically so that we avoid last-minute surprises."

Description

Continuously monitors calendars for changes during the hold window and invalidates candidate slots that gain conflicts for must-have attendees. Recalculates the candidate set and quorum viability in near real time using push notifications and periodic polling, updating participants and organizers as state changes. Ensures that approvals tied to invalidated slots are clearly communicated and redirected to the next viable option.

Acceptance Criteria

Invalidate Held Slot on Must‑Have Conflict

Given an active hold window with candidate slots and defined must‑have roles And a candidate slot S_k is currently viable and accepts approvals When a new busy event overlapping S_k is added to any must‑have attendee’s calendar Then the system detects the conflict via push within 20 seconds or via polling within 60 seconds And marks S_k as Invalid with reason "Must‑have attendee conflict" And blocks further approvals on S_k and prevents auto‑confirm for S_k And updates Slack/email hold cards and the organizer dashboard to reflect the invalid status within 10 seconds of detection

Redirect Approvals from Invalidated Slot

Given approvals have been recorded for slot S_k prior to invalidation When S_k becomes invalid due to a newly detected conflict Then all prior approvals for S_k are preserved with status Superseded (read‑only) in the audit log And approvers receive a one‑tap prompt to re‑apply their approval to the next viable slot as determined by the recalculation engine And no superseded approval counts toward quorum for any slot until explicitly re‑applied by the approver And the organizer is notified of the redirection status and remaining quorum gap for the suggested slot

Auto‑Recalculate Quorum and Confirm First to Quorum

Given a defined quorum by required roles and a set of candidate slots under hold When any approval, decline, conflict addition/removal, or availability change is processed Then the engine recalculates slot viability and rankings within 5 seconds And if any slot satisfies quorum with all must‑have roles conflict‑free, it is auto‑confirmed immediately And confirmation calendar invites are sent to all attendees within 10 seconds of auto‑confirm And holds on all other slots are released and their approval actions become non‑actionable within 10 seconds

Hybrid Push/Poll Reliability and Latency

Given connected calendars using push webhooks (e.g., Google/Microsoft) and others using polling When calendar changes occur during an active hold window Then 99% of push‑detected changes are processed end‑to‑end within 20 seconds And polling detects changes within 60 seconds with zero missed events in a 24‑hour soak test And if a webhook fails or is revoked, the system falls back to polling within 30 seconds and logs the transition And duplicate deliveries from push and poll are handled idempotently with no duplicate user notifications or state thrashing

Real‑Time Participant and Organizer Notifications

Given any state change (slot invalidated, slot re‑enabled, quorum reached, hold expired) When the change is applied Then participants and organizers receive a Slack/email update that includes local time, reason, current quorum status, and a deep link to the live hold view And duplicate notifications for the same state change are suppressed per user for 2 minutes And failed notifications retry with exponential backoff up to 3 attempts before surfacing an error to the organizer And notification delivery and engagement metrics are captured for audit

Hold Window Expiry and Safe Termination

Given an active hold window with no slot having reached quorum by expiry time T When T is reached Then all holds are released within 10 seconds and no further approvals are accepted And participants are notified that the window expired and what the next action is (e.g., new window proposal) And the organizer receives a summary of approvals, invalidation reasons, and the top next viable window And the recalculation engine stops processing events for the expired hold and ignores late approvals

Revalidation on Conflict Removal

Given a candidate slot S_k was invalidated due to a must‑have conflict When the conflicting event is removed or rescheduled so S_k is conflict‑free Then the system detects the change within push/poll SLAs and revalidates S_k within 10 seconds of detection And S_k is reinserted into the candidate set with an updated ranking and viability status And participants are notified that S_k is available again with a one‑tap approval action And previously superseded approvals are not auto‑restored to S_k without explicit user action

Asset Carry-Through

Moves the meeting without breaking anything: agenda, attachments, conferencing link, recording settings, and invite rules persist. Participants receive delta-only updates and ICS continuity, so externals keep working links and nobody has to rebuild the invite.

Requirements

Agenda & Structured Notes Persistence

"As a product manager scheduling across time zones, I want the agenda and notes to persist when I move a meeting so that I don’t have to rebuild structure and participants retain context."

Description

When a meeting is rescheduled within TimeMeld, all agenda content, sections, checklists, and timeboxed items created in TimeMeld or synced from connected docs remain attached to the event. The system updates only the start/end time while preserving the agenda data model and bi-directional links, ensuring participants see the same agenda in the new time slot. Recurring series and single-instance moves are handled via stable event UID and instance IDs, and conflicts are resolved with last-writer-wins plus change annotations.

Acceptance Criteria

Single-Instance Reschedule Preserves Agenda Assets

Given a non-recurring meeting with agenda sections, checklists with completion states, timeboxed items, and linked external docs When the organizer reschedules the meeting within TimeMeld to a new start and end time Then the event UID remains unchanged And agenda content, structure, and checklist completion states remain identical And timeboxed durations and relative ordering persist, anchored to the new start time And bi-directional links to external docs remain unchanged and functional And only the event start and end timestamps are changed in the event record

Recurring Series—Move One Occurrence

Given a recurring series with instance-specific agenda edits When the organizer moves only a single occurrence to a new time Then the series master UID remains unchanged And the moved occurrence retains its instance identifier (RECURRENCE-ID) and agenda content And no other occurrences are modified And participants see the same agenda for the moved occurrence at its new time

Recurring Series—Move Entire Series

Given a recurring series with a shared agenda template and per-instance notes When the organizer moves the entire series to a new schedule Then the series master UID remains unchanged And the agenda template persists unchanged and is visible at the new times And per-instance notes remain attached to their respective instances at the new schedule And no agenda content is duplicated or orphaned

External Doc Sync and Links Intact After Move

Given agenda items synced from a connected document with bi-directional links When the meeting is rescheduled within TimeMeld Then the external document URL and anchors remain the same And TimeMeld continues syncing with the same document without creating a new document or link And users opening the agenda from calendar or invite link land on the same document and sections

Concurrency—Last-Writer-Wins With Change Annotations

Given two participants edit agenda content concurrently while the event is rescheduled When the system merges the changes Then last-writer-wins is applied at the smallest addressable element level such as an agenda item or checkbox And conflicting elements are annotated with editor identity, timestamp, and prior value And no successful user edit is lost without an annotation And the agenda remains attached to the moved event

Participant View and Links Consistent Post-Reschedule

Given internal and external invitees access the agenda via supported calendar clients and shared links When the event is moved to a new time Then opening the event from any supported calendar shows the same agenda content And the agenda share URL remains unchanged and accessible And checklist completion states and timeboxed items are identical to pre-move

Operation Is Atomic and Audited

Given a reschedule action is initiated When any step of the operation fails Then the event remains at its original time with its agenda intact and the user is notified of failure When the operation succeeds Then the event is fully moved with the agenda intact and a Rescheduled system annotation including actor and timestamp is recorded And no duplicate agendas or orphaned links exist after the operation

Attachment & Link Integrity Validation

"As an engineer, I want attachments and links to keep working after a reschedule so that I can access the same materials without chasing new URLs."

Description

All attachments (files, decks, PRDs) and deep links associated with the meeting are preserved across moves without generating new share URLs. TimeMeld maintains attachment metadata and permissions, revalidates accessibility post-move, and warns on broken links with one-click fix flows. For external attendees, share links continue functioning via unchanged resource IDs embedded in the event description or attachment fields.

Acceptance Criteria

Same-calendar reschedule preserves attachment and link URLs

Given an existing meeting with N attachments and M deep links in the description and attachment fields When the meeting is moved to a new time/date on the same calendar without editing content Then no new share URLs are generated for any attachment or link And each resource ID for all attachments and links remains identical pre- and post-move And the attachments list (count, order, filenames, MIME types) is unchanged And the event description text and markup are unchanged And all links return HTTP 200 for attendees who previously had access And the revalidation completes within 5 seconds of move completion

Move a single instance of a recurring meeting retains assets

Given a recurring series with attachments and deep links applied at the series or instance level When a single occurrence is rescheduled (RECURRENCE-ID) without content edits Then only that occurrence's DTSTART/DTEND change and SEQUENCE increments by 1 And the attachments and deep links on that occurrence remain identical (no additions, removals, or regenerated URLs) And the series master and other instances remain unchanged And external attendees can access the same URLs from their existing calendar entries for that occurrence

External attendee continues to access unchanged share links after move

Given at least one external attendee has previously received the invitation and accepted When the organizer moves the meeting Then the external attendee's existing invite maintains the same join link and attachment URLs And the ICS UID remains unchanged and SEQUENCE increments by 1 And the update email and ICS contain only delta changes (time fields) with no ATTACH/URL replacements And previously received links in the original email continue to function without requiring a new invite And the external attendee can access each link with HTTP 200 using prior permissions

Post-move accessibility revalidation flags broken assets

Given the meeting has attachments/links where at least one resource has become inaccessible due to provider permission changes or deletion When the meeting is moved Then TimeMeld revalidates each attachment/link within 10 seconds And inaccessible items are flagged with specific reasons (e.g., 403 permission, 404 missing) and affected attendees And the organizer is shown a non-blocking warning listing the broken items and a one-click Fix Access action And no attachment/link URLs are auto-replaced during revalidation

One-click fix restores access without changing URLs

Given one or more attachments/links are flagged as inaccessible to some attendees post-move When the organizer clicks Fix Access in TimeMeld and confirms the audience scope Then TimeMeld updates provider permissions to match the meeting attendee list or selected scope And the original URLs and resource IDs remain unchanged And revalidation reruns automatically and passes within 10 seconds for fixable items And external attendees with link-based access can retrieve the resource with HTTP 200 And an audit entry records the permission changes and the acting user And if provider denies the change, a clear error is shown with next steps

ICS continuity and delta-only updates for moved meetings

Given a meeting (single or recurring instance) is moved by TimeMeld When update notifications are sent to attendees and calendars sync Then the ICS UID remains unchanged and SEQUENCE increments by exactly 1 And only DTSTART/DTEND (and RECURRENCE-ID for instances) are modified; DESCRIPTION, ATTACH, and URL fields remain byte-for-byte identical And attendees do not receive a new meeting object (no duplicates) across Google and Outlook And conferencing links and recording settings remain unchanged in the calendar payload And the attendee sees a single updated event with the same links accessible as before

Conferencing Bridge Continuity

"As an ops lead, I want the video link to stay the same when we move a meeting so that invitees’ bookmarks and room systems still work."

Description

The conferencing provider details (join URL, meeting ID, dial-ins, passcodes) remain unchanged when the event time shifts, preventing new links from being issued. TimeMeld uses provider APIs (Google Meet, Zoom, Microsoft Teams) to update time metadata only, preserving meeting identifiers. If a provider enforces time-bound windows, TimeMeld extends the session window or regenerates tokens behind the same join URL where supported; otherwise it alerts the organizer with clear fallback options.

Acceptance Criteria

Google Meet — Reschedule Within Allowed Window

Given an existing calendar event with a Google Meet conference (join URL, meeting code, dial-ins, passcode) When the organizer shifts the event start/end time by up to 12 hours using TimeMeld Then the Google Meet join URL, meeting code, dial-ins, and passcode remain unchanged And no new conference is created on the provider And only the provider time metadata is updated successfully And attendees receive a single time-change update with the same join URL visible And the ICS UID remains unchanged and SEQUENCE increments by 1

Zoom — Cross-Day Reschedule With Session Extension

Given an existing Zoom meeting with a join URL and meeting ID And the new time moves the meeting across calendar days When the organizer reschedules the meeting using TimeMeld Then TimeMeld extends the Zoom meeting’s scheduled window without issuing a new join URL And the Zoom meeting ID and join URL remain unchanged And attendees receive a delta-only calendar update with unchanged conferencing details And the ICS UID remains unchanged and SEQUENCE increments by 1

Microsoft Teams — Single Occurrence Reschedule in a Series

Given a recurring Teams meeting where a single occurrence is selected for reschedule When the organizer shifts only that occurrence using TimeMeld Then the Teams join URL and conference identifiers remain identical for that occurrence And other occurrences retain their original times and links And the rescheduled occurrence is published with a RECURRENCE-ID in ICS; UID unchanged; SEQUENCE increments And attendees of that occurrence receive a time-change update with the same link

ICS Continuity for External Attendees

Given a rescheduled meeting with preserved conferencing When TimeMeld issues updates to external attendees via .ics Then the iCalendar object retains the same UID And METHOD is REQUEST with SEQUENCE incremented by at least 1 And VEVENT contains unchanged conferencing properties/links; only DTSTART/DTEND are modified And no additional .ics attachments containing a different conferencing link are sent

Provider Requires Link Regeneration — Organizer Fallback Prompt

Given a provider indicates the join URL cannot be preserved for the requested new time When TimeMeld attempts the update and receives a constraint error Then TimeMeld presents options: keep original time; create new link and notify attendees; propose alternate windows And the prompt clearly states a new link would be required if proceeding And no attendee updates are sent until the organizer chooses an option And the audit log records the provider error code and the organizer’s decision

Delta-Only Update Content

Given a successful reschedule with preserved conferencing details When attendee notifications are sent Then the update contains only time changes and does not display a new or different join link, meeting ID, dial-ins, or passcodes And the event description and conferencing fields remain byte-identical to the prior version And update delivery latency to all attendees is under 60 seconds for the 95th percentile

Provider API Usage — Time Metadata Only

Given a reschedule request for a meeting with existing conferencing When TimeMeld updates the conferencing provider Then only time-related fields are modified via the provider API And no API calls to create or replace the conference are executed And provider resource identifiers (meeting ID/UUID) remain unchanged before and after And telemetry captures the API calls made for audit and troubleshooting

Recording & Meeting Options Preservation

"As a meeting host, I want recording and option settings to carry over when I change the time so that our compliance and facilitation settings remain intact."

Description

Recording preferences and meeting-level options (auto-record, lobby, host/presenter roles, mute-on-join, passcode settings, breakout assignments) persist through rescheduling. TimeMeld updates provider-side schedule metadata while retaining option flags and role assignments mapped to attendee identities. The system verifies that organizer permissions remain valid post-move and prompts reassignment only if provider constraints require it.

Acceptance Criteria

Reschedule Keeps Recording and Core Options Intact

Given an existing meeting created via TimeMeld with auto-record enabled, mute-on-join enabled, lobby enabled, and a specified recording destination And provider-side meeting metadata for these fields is captured as Baseline A When the meeting is rescheduled to a new time via TimeMeld without changing options Then the provider-side metadata for auto-record, mute-on-join, lobby, and recording destination equals Baseline A after the update And the conferencing join URL remains unchanged And TimeMeld records a verification entry indicating no option deltas

Role Assignments Persist Across Reschedule

Given host and presenter roles are assigned to named attendees (internal and external) by identity And provider-side role mapping is captured as Baseline R When the meeting is rescheduled via TimeMeld Then host and presenter assignments after the update equal Baseline R And the designated host retains organizer/host capabilities upon join And no participants are downgraded in role

Passcode and Lobby Settings Remain Stable

Given the meeting has lobby enabled and a passcode value P currently in effect And the current passcode P is visible via provider API and ICS When the meeting is rescheduled via TimeMeld Then the passcode remains P and lobby remains enabled post-update And both the provider API and the regenerated ICS reflect passcode P And no new passcode is generated

Breakout Room Assignments Are Preserved

Given breakout rooms are configured with assigned attendees by identity And provider-side breakout configuration is captured as Baseline B When the meeting is rescheduled via TimeMeld Then the breakout configuration after the update equals Baseline B (rooms, names, and attendee-to-room assignments) And attendees not assigned before remain unassigned after the update

Organizer Permission Revalidation and Prompted Reassignment

Given TimeMeld holds organizer credentials sufficient to update the meeting When a reschedule is initiated Then TimeMeld validates update permissions with the provider before committing changes And if validation passes, the reschedule is applied without changing the organizer And if validation fails due to missing scope or expired token, the user is prompted to reauthenticate or reassign an eligible organizer before any change occurs And the reschedule proceeds only after successful reauthentication or reassignment, with the action captured in the audit log

Provider Constraint Handling for Unsupported Options

Given certain configured options are not preservable for the requested move due to provider constraints (e.g., cross-tenant restriction on breakout assignments or recording location) When the meeting is rescheduled via TimeMeld Then all supported options are preserved unchanged And only the specific unsupported options are adjusted as required by the provider And the user is shown a pre-commit summary detailing the exact option deltas and provider reason codes And an audit record is stored listing the constraints and applied deltas

Invitee Rules & RSVP State Retention

"As an organizer, I want invitee settings and RSVPs to stay intact when I reschedule so that I don’t lose commitments or have to reconfigure attendance."

Description

Attendee lists, optional/required status, RSVP responses, reminders, and notification preferences persist during a move. TimeMeld updates the event’s start/end time while maintaining the same iCalendar UID and incrementing SEQUENCE to ensure clients treat the change as an update, not a new event. Optional attendees remain optional, delegation and forwarding rules remain applied, and reminder offsets are recomputed against the new start time without altering user-set preferences.

Acceptance Criteria

Time-Only Move Preserves Attendee Roster and Roles

Given an existing event with required and optional attendees (including externals) When the organizer updates only the start and/or end time via TimeMeld Then the updated event contains the exact same set of attendees as before And each attendee's required/optional designation is unchanged And the organizer identity remains unchanged And no duplicate or missing attendees are present

RSVP State Retention Across Time Change

Given attendees have Accepted, Tentative, Declined, and Needs Action states on the event When the event time is changed via TimeMeld Then each attendee's RSVP state remains unchanged And any response comments/notes remain associated to the attendee And no attendee's state is reset or cleared

Reminder and Notification Preferences Persist and Recompute

Given attendees have user-set reminder channels and offsets (e.g., email 30m, popup 10m) When the event start time is moved Then reminders are rescheduled relative to the new start time using the same offsets per attendee And the number and type of reminders per attendee remain unchanged And notification channels and quiet-hours preferences remain unchanged

iCalendar UID Continuity with SEQUENCE Increment

Given an existing iCalendar event with UID = U and SEQUENCE = S When TimeMeld updates only the start/end time Then the outgoing ICS retains UID = U And SEQUENCE equals S + 1 And DTSTAMP is updated to the update time And clients display a single updated event (not a duplicate)

Delta-Only Update and Link Continuity for Externals

Given the event includes external attendees and has conferencing links and attachments When the event time is changed via TimeMeld Then the ICS update includes only changed properties (start/end time, SEQUENCE, DTSTAMP) And conferencing links and attachment URLs remain identical and functional And external attendees can join using previously received links without re-accepting

Delegation and Forwarding Rules Remain Applied

Given an attendee with a delegate (DELEGATED-TO/DELEGATED-FROM) and existing forwarding rules When the event time is updated via TimeMeld Then delegation metadata persists for both principal and delegate in the updated invite And update notifications are routed to delegate/forward recipients per existing rules And no additional recipients beyond the original routing receive notifications

Delta-Only Notifications with ICS UID Continuity

"As an external attendee, I want a minimal update that keeps my calendar event intact so that I don’t end up with duplicate invites or dead links."

Description

Participants receive concise delta updates reflecting only what changed while preserving the original iCalendar UID to maintain continuity for external calendars. TimeMeld sends iTIP updates with incremented SEQUENCE and appropriate METHOD values, aggregates changes into a single update, and suppresses redundant emails. For externals, ICS attachments include the same UID and updated DTSTAMP/DTSTART/DTEND, preventing duplicate events and broken links.

Acceptance Criteria

Reschedule Time—Delta-Only Update Preserved UID

Given an existing event with UID U and SEQUENCE S When the organizer changes only the meeting time (DTSTART/DTEND) and saves Then TimeMeld sends a single iTIP update with METHOD:REQUEST, UID=U, SEQUENCE=S+1, DTSTAMP increased And the ICS reflects updated DTSTART/DTEND only; other event identifiers (UID) remain unchanged And the participant notification content lists only the time change and omits unchanged fields And each participant receives no more than one email for this action

Add and Remove Attendees—Single Aggregated Update

Given an existing event with UID U and SEQUENCE S And the organizer adds Alice and removes Bob within a 2-minute aggregation window When the organizer saves changes (or the aggregation window elapses) Then existing attendees receive one iTIP update with METHOD:REQUEST, UID=U, SEQUENCE=S+1 summarizing attendee changes only And Alice (new attendee) receives one invitation with METHOD:REQUEST, UID=U, SEQUENCE=S+1 containing full current event details And Bob (removed attendee) receives one cancellation with METHOD:CANCEL, UID=U, SEQUENCE=S+1 And no attendee receives more than one email for these combined changes And notification content lists only the added/removed attendees and omits unchanged fields

External Calendar Update—UID Continuity Prevents Duplication

Given an external attendee has accepted the event in Google Calendar or Outlook And the event has UID U and SEQUENCE S When the organizer updates the meeting time and saves Then the external attendee receives one update email with an ICS attachment where UID=U, METHOD:REQUEST, SEQUENCE=S+1, and DTSTAMP increased And after calendar sync, the attendee’s calendar shows exactly one event (no duplicate) updated in place to the new DTSTART/DTEND And the conferencing/join link in the event remains functional and unchanged And the event’s reminder settings on the external calendar are preserved by virtue of in-place update

No Material Change—No Notification or Sequence Bump

Given an existing event with UID U and SEQUENCE S When the organizer opens the event and saves without changing any notifiable fields Then TimeMeld sends no iTIP message and no email to participants And the stored SEQUENCE remains S (no increment) And the event’s UID remains U And audit logs reflect a no-op save with zero outbound notifications

Batch Multiple Edits—One Consolidated Update

Given an existing event with UID U and SEQUENCE S And within a 2-minute aggregation window the organizer changes the time and updates the location When the changes are committed (save or window elapses) Then participants receive exactly one iTIP update with METHOD:REQUEST, UID=U, SEQUENCE=S+1 that includes both changes And notification content lists only the changed fields (time, location) and omits unchanged fields And no intermediate or redundant emails are sent during the aggregation window And the ICS DTSTAMP is later than the previous DTSTAMP and DTSTART/DTEND/location reflect new values

Cancellation Uses Correct METHOD with UID Continuity

Given an existing event with UID U and SEQUENCE S When the organizer cancels the event Then TimeMeld sends one iTIP message with METHOD:CANCEL, UID=U, SEQUENCE=S+1 and updated DTSTAMP to all attendees And external calendars remove or mark the original event as canceled without creating duplicates And no further update emails are sent after the cancellation for this event

Atomic Move with Idempotent Retry and Rollback

"As a distributed team organizer, I want moves to be all-or-nothing with safe retries so that we don’t end up in a broken state where links or attendees are out of sync."

Description

Rescheduling executes as an atomic operation across calendar, conferencing, and attachment services. Either all assets update successfully, or the system rolls back to the previous state. Operations are idempotent with request IDs, featuring exponential backoff and compensating actions on partial failure. Pre-flight checks validate organizer permissions, event ownership, and provider quotas. A detailed audit log records changes with trace IDs to support troubleshooting and compliance.

Acceptance Criteria

Atomic Reschedule Success Across Services

Given an owned event with valid organizer permissions and sufficient provider quotas across calendar, conferencing, and attachment services And the event has agenda, attachments, conferencing link, recording settings, and invite rules configured When the organizer reschedules the event to a new valid time window Then the system updates the event time across all services within a single logical transaction boundary And agenda, attachments, conferencing link, recording settings, and invite rules persist unchanged And external participants receive a delta-only update with ICS continuity (same UID, incremented SEQUENCE, updated DTSTART/DTEND) And all conferencing and attachment URLs remain unchanged and functional And the attendee list remains unchanged unless explicitly modified And the operation completes within 5 seconds P95 under normal load

Rollback on Partial Failure

Given a reschedule attempt triggers a non-retriable error in any downstream service during commit When partial changes are detected Then the system rolls back all changes, restoring the original time and assets across all services And participants receive no net-change notification (or a corrective cancellation/update) such that the final calendar state matches the original And the final state across all services equals the pre-operation snapshot And an audit log entry records rollback=true with error details and trace ID And no duplicate, orphaned, or stale conferencing rooms, recordings, or attachments remain

Idempotent Move with Request ID

Given the client includes a unique request_id in the reschedule request When the same request_id and identical payload are submitted multiple times within 24 hours Then exactly one reschedule is executed and subsequent submissions return 200 with idempotent_result=duplicate and produce no side effects And when the same request_id is reused with a different payload, the system returns 409 Conflict and applies no changes And idempotency keys expire after 24 hours and are garbage collected

Exponential Backoff and Retry Policy

Given a reschedule attempt encounters retriable errors (e.g., 429, 5xx, or network timeouts) from any service When retrying the affected operation Then the system uses exponential backoff with jitter: initial delay 1s, multiplier 2, ±20% jitter, max delay 32s, max 5 attempts per service And total retry wall-clock time does not exceed 90 seconds And retries stop immediately on non-retriable errors And the final outcome is either full success or full rollback with no partial state left

Pre-flight Validation Blocks Unsafe Moves

Given the organizer initiates a reschedule When pre-flight checks run Then the system verifies organizer permissions, event ownership, attendee modification rights, conferencing/recording policy compliance, and provider quotas And if any check fails, the move is blocked with a descriptive error code and no changes are applied to any service And a pre-flight audit entry is recorded with trace ID and failure reason And pre-flight completes within 1 second P95

Comprehensive Audit Logging with Traceability

Given any reschedule attempt (success, rollback, or failure) When the operation completes Then an immutable audit log entry is stored containing: trace_id, request_id, actor, timestamps (received, started, committed/rolled_back), pre and post event metadata (time, assets, attendees), per-service outcomes, retry counts, and final state And audit entries are queryable by trace_id and request_id within 1 second P95 And sensitive fields are redacted per policy while retaining forensic value And audit logs are retained for at least 400 days and are tamper-evident

Smart Decline Swap

When a required attendee can’t make the proposed time, Slipstream offers them humane alternates within equity rules and lets the organizer swap into the earliest mutually fair window in one tap—saving manual triage while keeping fairness intact.

Requirements

Instant Decline Trigger

"As a required attendee, I want my decline to automatically offer a smarter reschedule path so that I don’t have to manually negotiate a new time."

Description

Detects when a required attendee declines or marks the proposed time as not workable via calendar response, in‑app prompt, or Slack action, and initiates the Smart Decline Swap flow. Pulls attendee context (timezone, working hours, do‑not‑disturb, focus blocks) from TimeMeld profiles and connected calendars to determine eligibility and constraints. Normalizes responses across Google/Microsoft calendars via webhooks, maps decline reasons, and records the triggering event for auditability. Ensures only meetings with required attendees and reschedulable policies are processed and gracefully falls back to standard decline behavior when the feature is disabled or constraints cannot be met.

Acceptance Criteria

Cross-Calendar Decline Webhook Triggers Swap

Given a scheduled TimeMeld meeting with reschedulable policy enabled and at least one required attendee integrated via Google or Microsoft 365 And calendar webhooks are active for the attendee When the attendee submits a Decline RSVP from Google Calendar or Outlook/Office 365 Then TimeMeld receives the provider webhook and normalizes the status to a unified "decline" with a mapped reason code And a Smart Decline Swap flow is initiated within 10 seconds of webhook receipt And duplicate provider notifications for the same attendee/event received within 60 seconds are deduplicated And the meeting reflects that a swap flow has started, with trigger_source="calendar"

In-App and Slack Decline Triggers

Given a scheduled TimeMeld meeting with reschedulable policy enabled and a required attendee viewing the meeting in-app or in Slack When the attendee selects "Can't make it" via the in-app prompt or the Slack message action Then TimeMeld records a normalized decline with trigger_source set to "in-app" or "slack" and captures any provided decline reason And the attendee receives an acknowledgment in the same surface within 1 second And a Smart Decline Swap flow is initiated within 3 seconds of the action And the event is recorded for auditability

Eligibility Gate: Required Attendee and Reschedulable Policy

Rule: Optional attendee declines must not initiate Smart Decline Swap; standard decline behavior applies Rule: Meetings with reschedulable policy disabled must not initiate Smart Decline Swap even if a required attendee declines Rule: If the Smart Decline Swap feature is disabled at the workspace or meeting level, declines must fall back to standard behavior Rule: Eligibility decisions are recorded with eligibility_result and reason for auditability

Context Enrichment on Trigger

Given a valid decline trigger for a required attendee When evaluating eligibility and constraints Then TimeMeld fetches timezone, working hours, do-not-disturb windows, and focus blocks from the attendee profile and connected calendars covering the next 14 days And the fetch completes within 1500 ms or falls back to cached values no older than 24 hours And if data is missing or sources are unavailable, documented defaults are applied without failing the trigger And the resolved constraints are attached to the swap flow payload for downstream use

Audit Logging of Decline Trigger

Given any decline trigger processed by TimeMeld When the trigger is handled Then an immutable audit record is written containing: meeting_id, attendee_id, trigger_source, provider, normalized_status, normalized_reason, received_at_utc, processed_at_utc, eligibility_result, policy_snapshot_id, idempotency_key, and swap_flow_id (if started) And the record is available for query via the audit interface/API within 5 seconds of processing And audit records are retained for at least 180 days

Graceful Fallback on Ineligibility or Constraint Failure

Given a decline trigger where the meeting or workspace is ineligible or constraints cannot be satisfied (e.g., calendars disconnected, context fetch failure, no fair alternate windows) When processing the trigger Then Smart Decline Swap is not initiated And the attendee is informed that a standard decline will be used And the organizer receives only the standard provider decline notification (no duplicate TimeMeld email or DM) And an audit record is written with failure_reason and recovery_action

Idempotency and Concurrency Control for Declines

Given multiple decline signals for the same attendee and meeting arriving within a 5-minute window from any combination of calendar, in-app, or Slack sources When the signals are processed concurrently Then exactly one Smart Decline Swap flow is created And subsequent duplicate signals are acknowledged without side effects using a stable idempotency key And only one organizer notification about swap initiation is sent And a metric "decline_trigger_duplicates_suppressed" increments for each suppressed duplicate

Fairness Rules Engine Compliance

"As an organizer, I want alternates to be validated against our fairness rules so that reschedules don’t concentrate burden on the same people."

Description

Evaluates candidate reschedule windows against TimeMeld’s equity scoreboard and fairness policies before any option is shown or accepted. Enforces rotation of meeting ownership, prevents repeated inconvenient slots for the same individuals or regions, applies timezone‑weighted ergonomics (e.g., avoids very early/late hours), and respects recent burden history and cooldowns. Computes a fairness score for each window and rejects/flags options that would regress equity. Exposes machine‑readable reasons for acceptance/rejection and writes fairness decisions to the audit log for transparency and analytics.

Acceptance Criteria

Candidate Window Fairness Scoring and Threshold Enforcement

Given a fairness policy with min_score in [0,100] And a set of candidate windows for a meeting When the engine evaluates the candidates Then each candidate is assigned a fairness_score in [0,100] and persisted And candidates with fairness_score >= policy.min_score are marked acceptable And candidates with fairness_score < policy.min_score are rejected with reason_codes including "below_min_score" And only acceptable candidates may be displayed or selected for swap

Timezone-Weighted Ergonomics Compliance

Given each required attendee has an ergonomic_band [start_local,end_local] and hard_limits [earliest_local,latest_local] from policy When a candidate places an attendee outside their ergonomic_band but within hard_limits Then a penalty proportional to hours outside is applied to fairness_score And reason_codes includes "outside_ergo_band" with impacted_participants identified When a candidate places any required attendee outside hard_limits Then the candidate is automatically rejected with reason_codes including "outside_hard_limit" for that attendee And no rejected candidate is shown or accepted

Ownership Rotation Preservation on Swap

Given a swap is initiated to an accepted candidate window And the fairness scoreboard tracks meeting ownership rotation When computing ownership for the swapped meeting Then the selected window must not assign the same owner consecutively unless all other eligible owners have owned since the last cycle reset And if rotation would be violated, the engine either reassigns owner to the next eligible or rejects the candidate with reason_codes including "rotation_violation" And upon a successful swap, the scoreboard update and calendar change occur atomically

Recent Burden History and Cooldown Enforcement

Given policy.cooldown_days = 7 And burden is defined as any slot outside an attendee's ergonomic_band or flagged by policy as high-burden When a candidate would impose a burden on an attendee who had a burden event within the past policy.cooldown_days Then the candidate is rejected with reason_codes including "cooldown_violation" and includes prior_burden_at timestamps per impacted attendee And candidates that avoid additional burden are not penalized by cooldown logic

Humane Alternates on Decline with Earliest Mutually Fair Window

Given a required attendee declines the proposed time When alternates are requested Then the engine returns up to policy.max_alternates (default 3) earliest future windows with fairness_score >= policy.min_score and no violations of rotation, cooldown, or hard_limits And alternates are sorted by start_time ascending and include fairness_score And tapping Swap on the earliest alternate schedules that window, updates calendar invites, and records a fairness decision with decision="accepted" And no alternate that would regress equity is returned

Decision Explainability via Machine-Readable Reasons

Given a fairness evaluation result exists for a meeting's candidate window When retrieved via API GET /fairness/decisions?meeting_id={id} Then each item returns JSON fields: decision ("accepted"|"rejected"), fairness_score (number), reason_codes (array<string>), impacted_participants (array<id>), policy_version (string), weights (object) And rejected decisions include at least one reason_code And accepted decisions include an empty reason_codes array And the response validates against the versioned JSON Schema for policy_version

Audit Log Write and Retrieval for Fairness Decisions

Given any fairness decision is finalized (accepted or rejected) When the decision is recorded Then an immutable audit log entry is written within 1000 ms containing: decision_id, meeting_id, window_start, window_end (ISO 8601 UTC), actor_id, decision, fairness_score, reason_codes, policy_version, previous_owner_id, new_owner_id, timestamp And audit entries are retrievable via API with filters by meeting_id and time range and are ordered by timestamp descending And attempts to modify or delete existing audit entries are denied and logged

Humane Alternate Window Generation

"As a decliner, I want ergonomic, fair suggestions I can choose from quickly so that I minimize disruption and still attend."

Description

Generates a small, high‑quality set of alternate windows for the decliner that balance mutual availability, fairness scores, and ergonomic constraints. Surfaces 3–5 options ranked by earliest mutually fair time, with clear local‑time displays for all required attendees. Allows the decliner to pick one, propose a range, or request the next fair week. Honors buffer times, travel blocks, and personal preferences, and supports quick actions from email, in‑app, or Slack without forcing context switches. Fails gracefully with guidance when no fair windows exist and can optionally expand the search according to policy.

Acceptance Criteria

Decliner Receives 3–5 Ranked Fair Alternate Windows

Given a required attendee declines the proposed meeting time and all required attendees are marked as required When the system generates alternate windows Then it returns between 3 and 5 options inclusive, or all available if fewer than 3 exist And every option is mutually available for all required attendees And every option meets ergonomic constraints defined by policy (e.g., working hours, no-early/late bands) And every option meets or exceeds the minimum fairness score threshold defined by policy And options are ranked by earliest mutually fair time; ties are ordered by higher fairness score, then earlier chronological time And each option matches the original meeting duration And generation completes within 2 seconds at the 95th percentile

Clear Local-Time Displays for All Required Attendees

Given alternate windows have been generated When options are presented in any channel (email, in‑app, Slack) Then each option displays the start time in the decliner’s local time and in the local time for every required attendee And each displayed time includes the time zone abbreviation and UTC offset with DST correctly applied And any attendee for whom the time falls outside their stated working hours is clearly indicated And formatting respects each viewer’s 12/24‑hour preference in in‑app views and uses a standard 24‑hour format in email/Slack summaries

Quick Actions from Email, In‑App, and Slack

Given alternate windows are delivered via email, in‑app notification, or Slack When the decliner selects “Pick Option”, “Propose Range”, or “Next Fair Week” in that channel Then the action is accepted in‑channel without requiring a context switch And if a valid secure token is present the action completes without additional authentication; otherwise a single SSO step is prompted And the system acknowledges the action within 3 seconds end‑to‑end and reflects the selection in the app state And the organizer receives a confirmation notification and the relevant calendar artifacts (invite/update or hold) are created

Decliner Can Pick, Propose Range, or Request Next Fair Week

Given the decliner is viewing the generated alternates When the decliner picks a single option Then TimeMeld proposes/swaps the meeting to that slot, updates all required attendees, and reconciles any temporary holds When the decliner proposes a time range Then the system returns the earliest mutually fair window within that range that meets policy and requests confirmation And if no window fits the range, a clear message is shown with an option to expand search per policy When the decliner requests the next fair week Then the system surfaces the earliest mutually fair window in the next calendar week that meets policy and requests confirmation

Honor Buffers, Travel Blocks, and Personal Preferences

Given attendee calendars include buffer rules, travel/commute blocks, and personal no‑meeting preferences When alternate windows are generated Then no proposed option violates any attendee’s buffer-before/after constraints relative to neighboring events And no proposed option overlaps travel/commute blocks or personal no‑meeting times And minimum notice lead time and maximum daily meeting load limits are respected per policy And options that would repeat inconvenient slots for the same attendee cohort in consecutive weeks are excluded per equity rules

Graceful Failure and Policy-Governed Expansion

Given the system finds no alternate windows that satisfy availability, ergonomics, and fairness under current policy When alternates are requested Then the decliner sees a clear explanation of the constraint(s) preventing options and is offered actions And available actions include: request next fair week; expand search using policy-defined relaxations And upon choosing to expand, the system applies the configured relaxations in order and regenerates options, labeling any relaxed constraints And if still no options exist, the system records the outcome, offers to notify the organizer, and provides guidance to coordinate asynchronously

One‑Tap Swap & Auto‑Reschedule

"As an organizer, I want to swap into the earliest mutually fair window in one tap so that I can reschedule without manual triage."

Description

Enables the organizer to approve a selected alternate in a single action, automatically updating the original event and invites. Modifies start/end time, preserves conferencing links and agenda, updates resources/rooms, notifies all participants, and cancels the original slot with proper ICS updates to prevent duplicates. Ensures atomicity with transactional updates across Google/Microsoft APIs, retries on transient failures, and rollback if any participant cannot be updated. Maintains the meeting thread context in email/Slack and posts a concise change summary with before/after times in each attendee’s local timezone.

Acceptance Criteria

One‑tap swap preserves event details and updates time

Given an existing meeting with conferencing link, agenda, attachments, participants, and an approved alternate time When the organizer taps "Swap into alternate" Then the event start and end times are updated to the alternate time And the conferencing link/meeting ID remains unchanged And the agenda text and attachments remain unchanged And there is exactly one meeting instance on each attendee’s calendar after synchronization And a success confirmation is shown to the organizer within 5 seconds (P95)

Atomic cross‑provider reschedule with retries, rollback, and idempotency

Given attendees span Google Workspace and Microsoft 365 tenants and network conditions may be unreliable When the swap is initiated Then updates to all participants’ calendars are executed as a single transaction and are only committed if every participant update succeeds And transient errors (HTTP 429/5xx/timeouts) are retried up to 3 times with exponential backoff up to 90 seconds total And if any participant cannot be updated after retries, all interim changes are rolled back to the original meeting time for everyone And no update notifications are sent until the transaction commits And the operation is idempotent: duplicate taps within 60 seconds do not create duplicate updates or notifications (same idempotency key)

Proper ICS/iTIP sequencing prevents duplicates

Given the original event has a stable UID and an alternate time is approved When the system updates external calendars via ICS/iTIP Then the UID remains the same and SEQUENCE is incremented by +1 on the updated invite (METHOD: REQUEST) And any separate hold/placeholder for the original slot is canceled with METHOD: CANCEL and matching UID And attendees in Google Calendar and Outlook receive exactly one updated event on their calendars and zero duplicates after the next sync cycle And removed placeholders no longer appear on any attendee or room calendar

Thread continuity and localized change summary in Email and Slack

Given the meeting has an existing email thread and a Slack thread for coordination When the swap completes Then an email is sent as a reply in the existing thread (In-Reply-To/References preserved) with subject prefixed "[Rescheduled]" And the email and Slack thread messages include a concise summary: old time → new time for each attendee in their local timezone with city and UTC offset And the Slack message is posted in the existing thread (same thread_ts) without creating a new channel thread And at least three attendees in different timezones see correct localized times matching their profile timezones

Room/resource rebooking on swap

Given the original meeting has a room/resource booked and an alternate time is selected When the swap is executed Then the system attempts to rebook the same room at the new time and releases the prior hold And if the room is unavailable, the best available room is auto-selected per configured preference rules And if no rooms are available, the swap is aborted, all changes are rolled back, and the organizer sees a clear error with alternatives And no orphaned room holds remain on any resource calendar after completion

Organizer can approve from mobile and web in one tap/click

Given the organizer is viewing the proposed alternate in the mobile app or web app When the organizer approves the alternate Then the action requires at most one primary tap/click from the alternate view And the CTA is labeled "Swap into this time" and shows a loading/disabled state during processing And the end-to-end operation completes within 5 seconds at P95 and 10 seconds at P99 And the CTA is disabled if the meeting starts within 5 minutes or if the alternate violates equity policies

Fairness guardrails validated before swap

Given equity policies are configured (timezone-weighted fairness and ownership rotation) When the organizer attempts to swap into an alternate time Then the policy engine evaluates the alternate and returns pass/fail with an audit record of scores And swaps proceed only if the policy evaluation passes and do not increase any attendee’s inconvenience beyond configured thresholds And if the evaluation fails, the swap is blocked with a clear reason and at least one compliant next-best suggestion

Smart Holds & Conflict Resolution

"As a scheduler, I want tentative holds on candidate times so that good slots aren’t lost while we finalize the swap."

Description

Places short‑lived, reversible soft holds on candidate windows across required attendees to reduce race conditions while a swap is being confirmed. Continuously rechecks availability and fairness scores up to confirmation, resolves conflicts if overlapping holds arise, and releases holds immediately on rejection, timeout, or completion. Handles edge cases like newly added attendees, changed working hours, or organizer overrides, and escalates with alternatives or retry strategies when conflicts invalidate the leading option.

Acceptance Criteria

Soft Hold Placement on Leading Candidate Window

Given a Smart Decline Swap is initiated for a meeting with a defined set of required attendees and a leading candidate window is selected When soft holds are placed Then a reversible soft hold is created for each required attendee on the leading window within 3 seconds, without sending calendar invites or emails And each hold is labeled as "TimeMeld Soft Hold" and is visible in TimeMeld UI indicators for the affected attendees And hold placement is idempotent: repeated requests with the same correlation ID do not create duplicate holds And holds do not overwrite or delete existing hard events And an audit record is stored with correlation ID, attendees, window, timestamp, and initiator

Continuous Recheck of Availability and Fairness During Pending Hold

Given a leading window has active soft holds and the swap is awaiting confirmation When any attendee availability changes, a new conflicting event arrives, working hours are updated, or fairness inputs change Then the system recalculates availability and fairness within 2 seconds of the change And the current leading window and its score are updated in the UI And if the held window no longer satisfies availability or minimum fairness thresholds, it is marked invalid and escalation is triggered And all recalculations are logged with timestamps and inputs used

Conflict Detection and Deterministic Resolution Across Overlapping Holds

Given overlapping soft holds exist that involve at least one common attendee across different meetings or swap flows When a conflict is detected Then the system applies a deterministic tiebreaker: (1) higher meeting priority, (2) earlier hold timestamp, (3) greater organizer equity deficit, (4) lexicographical meeting ID as final fallback And the losing hold set is released within 1 second and the impacted flow is notified with the reason code And at most one soft hold per attendee per time window remains active across the system

Immediate Release on Confirmation, Rejection, or Timeout

Given a window is under soft hold When the organizer confirms the swap, any required attendee rejects, or the response SLA timeout elapses (default 5 minutes, configurable) Then all holds associated with the window are released within 1 second And no soft hold indicators remain visible in UI for any attendee And exactly one confirmation event is persisted atomically to prevent duplicate bookings And an outcome audit record (confirmed/rejected/expired) is stored with timestamps and actor IDs

Dynamic Updates for Added/Removed Attendees and Working Hours Changes

Given a window has active soft holds during an in‑progress swap When a required attendee is added or removed, or any required attendee changes working hours affecting the held window Then the system reevaluates validity and fairness within 3 seconds and updates the hold set accordingly And holds are added for newly added required attendees only if the window remains valid; otherwise escalation is triggered And holds for removed attendees are released immediately And the fairness score and rationale are updated and logged

Organizer Override with Guardrails and Equity Accounting

Given the leading window is invalid due to availability or fairness constraints When the organizer performs an override to force confirmation Then the system requires an explicit confirmation with a mandatory override reason and displays the policy impact And the confirmation is recorded with an override flag and rationale in the audit log And the equity scoreboard is adjusted according to policy to debit/credit fairness balances for affected participants And all previously held windows not selected are released within 1 second and attendees are notified of the override outcome

Integrates Backup Buddy events with TimeMeld’s equity scoreboard so that promoted backups receive appropriate credit and recurring ownership rotation adjusts accordingly. Distinguishes between voluntary and automatic takeovers, prevents double-crediting, and ensures inconvenient-time penalties or credits are applied to the correct person and timezone. Displays history of takeovers in the scoreboard detail view and exports to CSV. Expected outcome: fair attribution that reinforces balanced facilitation and prevents repeated inconvenient slots.

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Interview Orchestrator Ivy

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Postmortem Marshal Max

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Sprint Workshop Wrangler Sanaa

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Enablement Cadence Coach Casey

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Community Demo Director Diego

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Board Briefing Booker Isha

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

LinkLock

Requirements

Recipient-Bound Magic Link Issuance

Description

Acceptance Criteria

Lightweight OTP Email Verification

Description

Acceptance Criteria

Forwarded Link Access Request Flow

Description

Acceptance Criteria

Host Approval Console and Notifications

Description

Acceptance Criteria

Session Binding and Re-entry Window

Description

Acceptance Criteria

Audit Trails and Attendance Integrity

Description

Acceptance Criteria

Auto‑Localize

Requirements

Automatic Timezone Detection & Verification

Description

Acceptance Criteria

Locale‑Aware Date/Time & Language Formatting

Description

Acceptance Criteria

DST‑Safe Scheduling Engine

Description

Acceptance Criteria