Miro CI Contract Tests

Overview

Keep pull-request checks credential-free and reserve live Miro calls for protected, explicitly scoped lanes. A test must never mutate a collaboration board by accident; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• CI trust-boundary and fork policy
• Pinned schemas/fixtures and test command
• Dedicated app, team, board, identity, and cleanup owner for live tests

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Untrusted fork workflows must not receive Miro credentials.
• Live traffic consumes production-like per-user/application credits even on test resources.
• Bulk create is transactional but cleanup still needs an explicit inventory and board guard.
• OAuth refresh rotation can invalidate concurrent jobs sharing one installation.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Split formatting, unit, schema, security, and fixture tests from the protected live lane.
2. Assert that PR/fork lanes have no credential context and cannot invoke live helpers.
3. Pin dependencies and validate captured fixtures against current official response contracts.
4. Serialize protected live jobs per installation, assert app/team/board guards, and use bounded read-first tests.
5. Mark any created item with the run identity, reconcile it, then clean only confirmed run-owned IDs.
6. Fail the gate on leaked data, ambiguous writes, cleanup residue, unexpected schema, or quota-policy breach.

Approval Boundaries

Do not expose credentials to forks, share one rotating token across parallel jobs, or enable destructive live tests without repository and board-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return lane/trust map, fixture provenance, protected-resource guards, test results, credits used, cleanup receipt, and gate conclusion. State what was not inspected or changed so the receipt cannot overclaim coverage.

Miro API Error Diagnosis

Overview

Classify the failing layer before changing code or credentials. Preserve the response status, safe error code, request timing, and tenant context without retaining board content; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Failing operation and sanitized response metadata
• Expected user, app, team, board, and scopes
• Deployment and token-mode context

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• 401 generally indicates missing, invalid, expired, or revoked authorization; one refresh attempt is the safe ceiling.
• 403/404 can represent scope, membership, role, plan, resource, or tenant-boundary failures.
• 409 means current state conflicts with the requested mutation and requires a re-read.
• 429 responses must be handled from rate-limit headers; 5xx and network failures do not prove a write was absent.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Reproduce once with the smallest safe request and capture status, safe code, timing, and rate headers.
2. Verify URL, method, API version, token context, required scope, plan, and resource ownership.
3. Separate authorization, validation, conflict, throttling, vendor, and network hypotheses.
4. Test the leading hypothesis with a read-only probe or local schema fixture.
5. For ambiguous mutations, reconcile target state before considering a replay.
6. Return the root cause or a ranked evidence table with one bounded next test.

Approval Boundaries

Do not broaden scopes, reinstall an app, rotate credentials, or repeat a destructive mutation merely to diagnose an error without owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return classification, evidence, ruled-out causes, tenant/scope result, retry safety, remediation, and unresolved uncertainty. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Governed Board and Item Writes

Overview

Convert a requested canvas change into an explicit write set. Confirm board identity and permissions before any mutation, then reconcile what Miro actually persisted; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved target board and expected team
• OAuth installation with only the required board scopes
• Desired state, ownership, rollback, and collision policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Board and item writes require boards:write; reads use boards:read.
• The v2 API exposes item-type endpoints rather than the polymorphic v1 widget model.
• Bulk item creation accepts at most twenty items, is transactional, and charges Level 2 credits per item.
• A successful mutation response must be followed by a read when persisted state matters.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Resolve token context, team, board, and current permissions; stop on any mismatch.
2. Read the target objects and calculate a deterministic create/update/delete plan.
3. Present counts, affected types, destructive actions, credit estimate, and rollback before writing.
4. Apply the smallest approved operation or a maximum-twenty-item transactional bulk create.
5. Re-read affected IDs and compare normalized desired versus observed state.
6. Return a redacted receipt and rollback outcome; never retry an ambiguous write blindly.

Approval Boundaries

Require explicit approval for board creation/deletion, sharing changes, member changes, or deleting/replacing existing items. Do not infer a target from a board name alone. Pause when the responsible owner or exact target is uncertain.

Output

Return board/team confirmation, planned and applied counts by item type, credit estimate, reconciliation result, rollback handle, and exceptions. State what was not inspected or changed so the receipt cannot overclaim cove…

Miro Board Read and Reconciliation

Overview

Produce a consistent, bounded view of board state and distinguish indexing delay, pagination defects, and real drift before proposing changes; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved board and team scope
• OAuth installation with boards:read
• Field, item-type, pagination, freshness, and redaction requirements

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Board collection filters other than team/project can have indexing delay.
• Collection endpoints use cursor pagination where documented; cursor presence, not page fullness, controls continuation.
• Different item types have distinct v2 schemas and must not be collapsed into a v1 widget shape.
• Resource URLs and board content are sensitive and may be time-bound or access-controlled.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Confirm token context and board ownership boundary.
2. Define item types, fields, page/item ceilings, freshness window, and comparison keys.
3. Traverse documented cursors while detecting repeats and enforcing termination limits.
4. Normalize item-specific fields without discarding type or parent relationships.
5. Compare the snapshot with the approved baseline and classify added, changed, missing, and uncertain records.
6. Return a redacted drift report; propose writes separately with a new approval boundary.

Approval Boundaries

Do not expand from one board/team to an organization-wide inventory, follow download URLs, or persist content beyond the approved purpose without approval. Pause when the responsible owner or exact target is uncertain.

Output

Return board context, pages/items read, cursor termination reason, freshness caveats, drift counts, uncertain records, and a content-handling receipt. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Credit-Efficiency Planning

Overview

Treat API credits as capacity, not currency. Attribute demand by operation and caller, then remove waste without inventing a dollar price; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Request and rate-header telemetry by operation
• Documented endpoint credit levels
• Freshness, completeness, and priority requirements

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Miro documents credits and request capacity, not a per-credit billing price.
• REST levels currently cost 50, 100, 500, or 2,000 credits per call.
• Bulk creation remains charged Level 2 per item, so batching reduces round trips but not necessarily credit total.
• Retired REST webhooks are not an available zero-polling substitute.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Attribute calls and credits to tenants, features, endpoints, schedules, retries, and operators.
2. Separate required freshness from inherited polling frequency and duplicate consumers.
3. Model options: narrower scope, cursor checkpoints, deduplication, cache, coalescing, or reduced cadence.
4. Estimate credit reduction and quantify freshness, completeness, memory, and operational tradeoffs.
5. Test the selected policy against representative change bursts and full-reconciliation recovery.
6. Roll out with per-tenant fairness and alerts for credits, staleness, backlog, and missed-state indicators.

Approval Boundaries

Do not represent credits as direct monetary savings or weaken contractual freshness/completeness without product and service-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return baseline credits, waste sources, options, selected policy, expected reduction, SLO tradeoffs, test results, and rollback threshold. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Board Data Handling

Overview

Assume collaborative canvases can contain personal, confidential, regulated, or credential-like material; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Board read scope can expose metadata, members, and item content.
• Resource URLs and payloads must not enter logs or debug bundles.
• Enterprise export/audit/organization scopes require plan and role checks.
• Stored Miro data needs application-layer authentication and authorization.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Map each field to purpose, source, class, owner, destination, retention, and deletion.
2. Minimize boards, item types, fields, windows, and tenants.
3. Pseudonymize operational identifiers and keep content out of telemetry.
4. Enforce tenant authorization, encryption, access logs, expiry, and deletion paths.
5. Test deletion, revoked access, cross-tenant denial, redaction, and backup expiry.
6. Block any field without purpose, owner, retention, or access policy.

Approval Boundaries

Exporting, persisting, training on, or transmitting board content requires data-owner, privacy, and security approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Redacted Debug Bundle

Overview

Create evidence useful to maintainers or Miro support while excluding credentials, authorization codes, board content, personal data, and unrestricted configuration; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Incident identifier and narrow UTC window
• Approved evidence destination and retention period
• Known redaction rules for identifiers, URLs, headers, and payloads

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Safe evidence includes versions, operation names, status/code, latency, rate headers, counts, hashes, and timestamps.
• Authorization headers, cookies, tokens, client secrets, callback query strings, and raw board payloads are never safe evidence.
• Access-token context is useful only after user/team identifiers are pseudonymized.
• Official status evidence should include observation time because incidents change.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Define the incident window, failing operations, recipient, purpose, and retention.
2. Collect repository version, deployment version, app mode, safe configuration names, and dependency lock facts.
3. Extract bounded request metadata and rate headers; replace identifiers with stable incident-local hashes.
4. Record token-context match as a boolean and include no credential or raw context response.
5. Scan the bundle for bearer patterns, secrets, emails, callback codes, board text, and private URLs.
6. Review the manifest and redaction report before writing the approved artifact.

Approval Boundaries

Do not collect raw payloads, full environment/configuration dumps, database exports, or user content without data-owner and security approval. Pause when the responsible owner or exact target is uncertain.

Output

Return bundle path, manifest, time window, redaction counts, evidence gaps, sensitivity label, recipient, and deletion date. State what was not inspected or c…

Miro Integration Deployment

Overview

Promote one immutable artifact while keeping authorization configuration and write enablement separately controlled; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• OAuth redirects must exactly match the environment's Miro app configuration.
• REST secrets remain server-side and out of Web SDK bundles.
• A read-only context probe precedes write enablement.
• Retired experimental webhooks cannot be a health dependency.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Bind the release to SHA, dependency lock, app hash, scopes, redirects, and environment.
2. Deploy secret references and configuration with Miro writes disabled.
3. Run service health, token-context, and bounded board-read probes.
4. Canary approved tenants against error, latency, credit, and semantic thresholds.
5. Enable writes only after approval and reconcile the first mutations.
6. Exercise rollback and verify all pre-rollback writes.

Approval Boundaries

Production deployment, tenant rollout, redirect/scope changes, and write enablement require explicit owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Enterprise Access Governance

Overview

Compare intended access with effective plan, app-scope, role, team, and board controls; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Enterprise scopes have distinct plan and role availability.
• v2 team endpoints are Enterprise-only and require an Enterprise-team installation.
• App scopes and user/admin roles jointly constrain access.
• Board movement permissions vary by plan and role.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Define organizations, teams, boards, apps, identities, roles, and policy in scope.
2. Verify plan and scopes before Enterprise queries.
3. Collect minimum membership/settings evidence with pseudonymized people.
4. Classify excessive, missing, orphaned, conflicting, and unknown access.
5. Prepare but do not apply changes during audit mode.
6. After approved changes, re-read effective access and retain attestation evidence.

Approval Boundaries

Role/member, session, export, legal-hold, team, and sharing-policy mutations require relevant administrator approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Read-Only Connection Probe

Overview

Run the smallest useful REST probe and produce a redacted receipt. A successful HTTP response is insufficient unless tenant and scope context also match; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• An approved OAuth installation with boards:read
• Expected team and user context
• A test board or permission to list board metadata

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• GET https://api.miro.com/v2/boards requires boards:read.
• Filtering by team_id or project_id is indexed immediately; other search filters can lag by several seconds.
• Board-list responses are paginated and must not be treated as a complete inventory from one page.
• Response bodies can contain confidential names, descriptions, owners, and links.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inspect the integration configuration without reading credential values.
2. Confirm token context and expected team before querying board resources.
3. Request one bounded board page filtered to the approved team when available.
4. Record status, latency, rate-limit headers, page size, and only redacted board identifiers.
5. Verify the response shape and pagination cursor handling against the official reference.
6. Keep writes disabled and return the minimal evidence needed to authorize the next stage.

Approval Boundaries

Do not create a sample board or item as part of a connectivity probe unless the user explicitly authorizes that mutation and identifies the test board. Pause when the responsible owner or exact target is uncertain.

Output

Return environment, context match, scope sufficiency, HTTP status, latency, rate-limit headroom, page/cursor facts, and go/no-go. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Integration Incident Response

Overview

Stabilize user impact before changing authorization or replaying writes. Keep an UTC action log and make ambiguity explicit; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Incident commander, owners, severity, and affected window
• Current deployment, app/team context, dashboards, and safe logs
• Write-disable, circuit-breaker, reconciliation, and rollback controls

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• 401, 403/404, 409, 429, network, and 5xx failures require different containment.
• One refresh attempt is safe only when serialized against rotating token storage.
• 429 recovery follows observed reset headers and shared credit demand.
• Timeout/5xx on a mutation is ambiguous until target state is reconciled.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Declare incident scope, commander, severity, start time, affected tenants/operations, and change freeze.
2. Contain with write disablement, queue pause, concurrency reduction, or circuit opening appropriate to evidence.
3. Correlate deployment changes, token events, rate headers, semantic drift, and official Miro status.
4. Run the smallest read-only probe to classify auth, tenant, capacity, vendor, network, or local failure.
5. Recover in a canary cohort; reconcile ambiguous operations before draining queues.
6. Verify SLOs and data correctness, document timeline/root cause/follow-ups, and obtain closure approval.

Approval Boundaries

Credential rotation/revocation, scope or redirect changes, destructive repair, queue replay, and broad re-enable require the incident commander's explicit approval. Pause when the responsible owner or exact target is uncertain.

Output

Return severity, impact, timeline, evidence, containment, root cause/confidence, recovery metrics, reconciliation, approvals, and follow-ups. State what was not inspected or changed so the receipt canno…

Miro OAuth Installation and Token Lifecycle

Overview

Establish an auditable authorization boundary before any board operation. Prefer expiring-token apps and prove tenant context without exposing credentials; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• A Miro Developer team and an app configuration for the target environment
• Approved redirect URIs and a server-side encrypted token store
• A capability-to-scope map and accountable installation owner

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• REST apps use OAuth 2.0 Authorization Code; authorization starts at https://miro.com/oauth/authorize and exchange uses https://api.miro.com/v1/oauth/token.
• The REST resource base is https://api.miro.com/v2; OAuth endpoints remain v1 and are not deprecated by the REST v2 migration.
• Expiring-token mode provides a one-hour access token and a sixty-day refresh token; refresh rotates both values and invalidates the prior pair.
• Token-expiration mode is chosen when the app is created and cannot later be enabled, disabled, or changed.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory environments, redirect URIs, requested capabilities, scopes, and installation owners.
2. Create or inspect the environment-specific app and select expiring-token mode for new production apps.
3. Generate the authorization URL with an unguessable, session-bound state value and an exact registered redirect URI.
4. Exchange the single-use code server-side, atomically store both tokens and expiry metadata, and discard the code.
5. Call access-token context, compare the returned user/team context with the intended tenant, then perform a read-only board probe.
6. Exercise refresh rotation, concurrent-refresh locking, revocation, reinstall, and recovery before enabling writes.

Approval Boundaries

Do not add scopes, register a new redirect origin, create a produ…

Miro Local Development Loop

Overview

Shorten feedback cycles without turning a real collaboration board into a test fixture. Separate configuration, deterministic fixtures, and destructive cleanup; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• A non-production Miro app and Developer team
• A dedicated test board with an accountable owner
• Local configuration names, fixture schema, and cleanup policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Web SDK code runs only while its Miro app context is loaded on a board.
• REST OAuth and Web SDK authorization are separate; hybrid apps must configure both flows.
• Board operations are asynchronous and can take time to synchronize.
• REST test traffic consumes the same per-user/per-application credit budget as other callers.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Map the feature to REST, Web SDK, or a deliberate hybrid before writing code.
2. Load configuration by environment and assert that production app, team, and board IDs are absent.
3. Create deterministic fixture items with a run marker on the dedicated test board.
4. Run unit tests with schema-faithful fixtures, then one bounded live contract test.
5. Compare the observed response and rate headers with the recorded contract.
6. Delete only run-marked fixtures after verifying board ID, item IDs, and ownership; retain a redacted receipt.

Approval Boundaries

Do not expose a local callback publicly, install an app to another team, or delete unmarked board content without explicit approval. Pause when the responsible owner or exact target is uncertain.

Output

Return environment guards, fixture IDs as hashes, test results, observed contract drift, cleanup count, and leftovers. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro v1-to-v2 Resource Migration

Overview

Modernize legacy resources without changing OAuth unnecessarily or flattening distinct v2 item schemas; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• OAuth /v1/oauth is outside the resource migration.
• v2 replaces generic widgets with item-type endpoints.
• Connection objects became direct actions such as sharing.
• Several collections changed from offset to cursor pagination.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory v1 endpoints, widgets, connections, pagination, timestamps, and consumers.
2. Map each operation to official v2 behavior and record no-equivalent cases.
3. Build typed translators retaining IDs, types, relationships, and unsupported fields.
4. Run v1/v2 shadow reads and compare normalized semantic state.
5. Canary bounded writes with read-after-write and rollback.
6. Cut over incrementally and remove v1 resource code only after retained evidence.

Approval Boundaries

Bulk board copies, sharing changes, v1 data deletion, and OAuth changes require service and board-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Multi-Environment Isolation

Overview

Make environment confusion detectable before a request leaves the process; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Each app has independent identity, redirects, scopes, token mode, and installations.
• Access-token context must match the intended tenant.
• Production credentials never belong in local or preview environments.
• Token-expiration mode can differ because it is fixed at app creation.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Build an environment matrix of app hash, redirects, token mode, scopes, team, boards, store, and owner.
2. Fail startup on missing, duplicated, or inconsistent mappings.
3. Resolve credentials only through each environment's approved server-side reference.
4. Assert token context before enabling operations.
5. Test that production identifiers cannot appear in lower-environment config.
6. Exercise rotation, revocation, promotion, and rollback per environment.

Approval Boundaries

Creating/installing production apps, copying tokens, and changing production redirects/scopes require explicit owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Integration Observability

Overview

Observe vendor transport and business correctness without turning board content, credentials, or high-cardinality identifiers into telemetry; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Service objectives and supported user journeys
• Operation, retry, queue, reconciliation, and token lifecycle map
• Approved telemetry fields, retention, access, and alert owners

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Rate responses expose limit, remaining, and reset credit headers suitable for gauges and forecasts.
• HTTP success alone does not prove a mutation or synchronization outcome; semantic reconciliation needs separate signals.
• Miro's public status is a dependency clue, not proof that a local authorization or tenant issue is vendor-wide.
• Board names, item content, resource URLs, tokens, and raw user/team IDs should not be metric labels or logs.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Define SLIs for availability, latency, errors, credits, queue age, token refresh, reconciliation lag, and semantic drift.
2. Instrument adapters with bounded operation names, status classes, retry decisions, and redacted tenant hashes.
3. Parse rate headers and emit remaining fraction, reset time, weighted demand, and throttled duration.
4. Trace OAuth refresh and write/reconcile spans without recording credential or content fields.
5. Create alerts tied to user impact and runbooks, including Miro status as corroborating context.
6. Test dashboards and alerts with synthetic 401, 429, 5xx, drift, queue, and stale-checkpoint failures.

Approval Boundaries

Do not add board/user content, raw identifiers, credentials, or unrestricted URLs to telemetry without privacy/security approval. Pause when the responsible owner or exact target is uncertain.

Output

Return SLI/SLO table, metric/log/trace fields, dashboards, alerts, redaction tests, ru…

Miro Integration Performance Tuning

Overview

Optimize credits, latency, payload, or reconciliation time without sacrificing correctness or tenant fairness; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Calls consume endpoint-specific credits under a shared user/application budget.
• Cursor presence, not guessed page fullness, controls collection continuation.
• Bulk create supports at most twenty items and charges Level 2 credits per item.
• Board searches without team/project filters may have indexing delay.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Measure latency, pages, items, bytes, credits, errors, and queue age by operation.
2. Find redundant reads, unbounded traversal, duplicate callers, and reconciliation hot spots.
3. Apply narrow filters, checkpoints, deduplication, bounded concurrency, and explicit cache freshness.
4. Use bulk create only when transactional and per-item credit semantics fit.
5. Load-test synthetic data under a fixed credit budget and verify tenant fairness.
6. Canary one change and retain rollback thresholds for latency, drift, errors, and credits.

Approval Boundaries

Do not relax reconciliation, increase concurrency, or cache board content without service and data-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Production Readiness Gate

Overview

Turn production approval into an evidence-backed decision bound to one immutable release and app configuration; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Immutable release candidate and deployment manifest
• Production app/team ownership and approved scopes
• Test, observability, incident, rollback, and data-handling evidence

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Production REST uses v2 resource endpoints and OAuth under /v1/oauth.
• Experimental features are not production contracts and must be isolated behind explicit risk acceptance.
• Rate capacity is credit-weighted and must include all callers for a user/application pair.
• Miro service status, token revocation, and tenant mismatch need operational responses before launch.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Bind the review to release SHA, dependency lock, app ID hash, scopes, redirect URIs, and environment.
2. Verify tenant isolation, expiring-token rotation, revocation, least privilege, and redaction controls.
3. Run unit, contract, bounded live-read, failure, rate, rollback, and recovery tests.
4. Confirm dashboards, alerts, runbooks, owner/on-call, status dependency, retention, and support escalation.
5. List every mutation and experimental dependency; require an explicit disposition for each.
6. Issue GO only when all blocking evidence is current; otherwise return NO-GO with owners and retest criteria.

Approval Boundaries

Production deployment, new app installation, scope changes, initial write enablement, and risk acceptance require the designated owners' explicit approval. Pause when the responsible owner or exact target is uncertain.

Output

Return GO/NO-GO, immutable identity, gate table, evidence links, approvals, rollback trigger, residual risks, and expiry date. State what was not inspected or changed so the receipt canno…

Miro Credit-Budget and Rate-Limit Control

Overview

Plan capacity in credits rather than raw request count and preserve headroom across every caller sharing a user/application quota; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Sanitized rate-limit headers and recent 429 history
• Endpoint inventory with documented credit levels
• Caller priorities, freshness targets, and retry SLO

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• REST limiting is per user and application with a published global budget of 100,000 credits per minute.
• Level 1 costs 50 credits, Level 2 costs 100, Level 3 costs 500, and Level 4 costs 2,000 per call.
• At the global budget those levels correspond to 2,000, 1,000, 200, and 50 calls per minute respectively when used alone.
• Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and Unix-epoch X-RateLimit-Reset; published limits are subject to change.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory users/apps, callers, endpoints, weights, bursts, and retry loops.
2. Capture current headers from bounded authorized requests and validate reset conversion.
3. Model each operation in credits, including bulk-create Level 2 cost per item.
4. Allocate priority budgets with explicit interactive and incident-recovery headroom.
5. Queue requests with jitter, a maximum elapsed retry time, and no token sharding to evade limits.
6. Load-test synthetic traffic and verify fairness, queue age, header telemetry, and bounded 429 recovery.

Approval Boundaries

Do not add installations or identities to multiply quota, request Enterprise capacity, or starve interactive traffic without account and service-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return observed budget/reset, weighted demand, allocations, headroom, queue policy, test results, and 429 recovery evidence. St…

Miro Integration Reference Architecture

Overview

Put each capability at the correct browser, backend, tenant, and persistence boundary; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Approved Miro application, tenant, and board scope
• Current repository and deployment evidence
• Named owner, success criteria, and rollback or recovery boundary

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Web SDK operates in loaded board contexts; REST requires OAuth Authorization Code.
• Hybrid apps configure SDK authorization for backend REST authentication.
• Tokens must bind to app, user, team, and scopes.
• Durable change capture requires reconciliation because REST webhooks were retired.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Map actors, tenants, boards, data classes, journeys, and destructive operations.
2. Assign in-board interaction to Web SDK and durable orchestration to backend REST.
3. Define OAuth callback, rotating encrypted token storage, tenant authorization, and revocation.
4. Add weighted queues, cursor checkpoints, operation records, reconciliation, and safe telemetry.
5. Design failures for auth loss, tenant mismatch, 429, ambiguous writes, drift, and outage.
6. Review scopes, retention, capacity, recovery, and experimental use with owners.

Approval Boundaries

Shared tokens, browser-held client secrets, unbounded polling, and experimental dependencies require architecture/security approval and should normally be rejected. Pause when the responsible owner or exact target is uncertain.

Output

Return scope, observed contract, proposed or completed actions, verification evidence, approvals, residual risks, and next owner. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Miro Client and Schema Patterns

Overview

Keep vendor transport details behind a narrow adapter so auth rotation, response drift, retries, and test doubles stay independently verifiable; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Runtime and deployment constraints
• Required REST operations and response schemas
• Official client version or pinned OpenAPI contract

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• @mirohq/miro-api is Miro's official Node.js client for REST API v2.
• Miro manages OAuth-oriented flows and storage; MiroApi represents an access-token-bound API client.
• Collection helpers can be asynchronous iterators; callers must preserve pagination and bounded termination.
• Official examples simplify storage and sessions; production adapters must supply durable tenant-bound implementations.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory current HTTP/SDK calls, token lookup, retries, pagination, and response assumptions.
2. Choose raw REST when protocol control is required or the official client when its surface is verified and sufficient.
3. Expose domain operations through an adapter that accepts tenant context rather than raw credentials.
4. Validate external responses at the boundary and retain unknown fields for drift diagnosis.
5. Centralize safe retry classification, rate headers, timeouts, and redacted error metadata.
6. Pin dependencies, run contract fixtures plus a bounded live read, and record the observed API/client versions.

Approval Boundaries

Do not swap clients, regenerate from OpenAPI, or change retry semantics across production callers without owner approval and compatibility evidence. Pause when the responsible owner or exact target is uncertain.

Output

Return client choice, pinned version, operation map, pagination contract, validation boundaries, tenant-isolation tests, and migratio…

Miro Integration Security Baseline

Overview

Apply a minimum security baseline tied to Miro's supported authorization model and the app's actual data flows. Eliminate obsolete webhook assumptions from the threat model; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Data-flow and trust-boundary diagram
• App configuration, scopes, token mode, and storage design
• Threat model and approved data-retention policy

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Miro requires OAuth 2.0 for REST apps and tells Marketplace apps not to request user credentials.
• Every request must be authenticated and authorized; stored Miro user data requires its own access control.
• Session cookies should be HttpOnly and Secure; OAuth callbacks require session-bound state validation.
• The retired experimental webhook service provides no current server-to-server signature contract to implement.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Map entry points, OAuth redirects, sessions, tokens, board data, logs, exports, and administrators.
2. Minimize scopes and verify authorization again at each server-side tenant/resource boundary.
3. Encrypt tokens at rest, restrict decryption, serialize refresh rotation, and provide revocation/deletion paths.
4. Set secure cookie, CSRF, frame/origin, redirect, input-validation, and outbound-host controls appropriate to the app.
5. Redact credentials and content from telemetry; scan dependencies and production bundles for accidental exposure.
6. Test cross-tenant denial, revoked tokens, stale sessions, malformed inputs, and data deletion; record residual risks.

Approval Boundaries

Do not add scopes, retain board content, weaken cookie/CSRF controls, or introduce an experimental platform dependency without security and data-owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return threat bo…

Miro Dependency and API Upgrade

Overview

Treat upgrades as contract changes, not package-only edits. Separate REST major-version migration from client-library and Web SDK lifecycle changes; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Current and target dependency/API inventory
• Official changelog, lifecycle, and endpoint references
• Representative fixtures, sandbox board, and rollback artifact

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Miro maintains one recommended production REST major version; current resource work uses v2.
• OAuth /v1/oauth was not included in the REST v1-to-v2 resource migration.
• v2 replaced polymorphic widgets with item-type endpoints and changed several relationship and pagination models.
• Experimental endpoints can change or be removed and cannot silently graduate into a production dependency.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory SDK, raw endpoints, OAuth, scopes, response schemas, pagination, item types, and experimental use.
2. Diff current code against official lifecycle, migration, reference, and pinned package contracts.
3. Build compatibility fixtures and translate one operation at a time behind the adapter boundary.
4. Run shadow reads and normalized comparisons on a sandbox board before enabling writes.
5. Canary the target with error, latency, credit, and semantic-drift thresholds.
6. Promote only after reconciliation; retain the prior artifact/config and exercise rollback.

Approval Boundaries

Do not change a production API path, scopes, token mode, or enable a formerly experimental capability without service-owner approval and fresh evidence. Pause when the responsible owner or exact target is uncertain.

Output

Return contract diff, dependency changes, compatibility results, shadow/canary metrics, cutover decision, rollback evidence, and leftovers. State what was not inspected or changed so…

Miro Eventing Gap and Supported Alternatives

Overview

Prevent new systems from depending on Miro's discontinued experimental webhook infrastructure. Select an alternative that honestly represents durability and freshness; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Event use case, consumers, and freshness/loss tolerance
• Current REST and Web SDK capability inventory
• Authorized boards, rate budget, and reconciliation state store

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Miro discontinued experimental REST webhooks and /v2-experimental/webhooks/board_subscriptions.
• There is no current production Miro REST callback/signature contract documented as its replacement.
• Web SDK UI events such as items:create and items:delete run in active board app contexts; they are not durable server-to-server delivery.
• experimental:items:update remains experimental, and items:create does not fire for copy-paste or duplication.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory every retired subscription call, callback handler, signature assumption, queue, and downstream consumer.
2. Define required freshness, completeness, replay, ordering, and active-board assumptions.
3. Choose bounded REST reconciliation for durable server state or supported Web SDK UI events for active in-board behavior.
4. For polling, store normalized checkpoints, traverse cursors safely, budget credits, and run periodic full reconciliation.
5. For Web SDK events, register and unregister stable handlers, tolerate duplicates/misses, and label session-only semantics.
6. Remove retired endpoints and secrets; test detection gaps and publish the residual freshness/loss contract.

Approval Boundaries

Do not reactivate retired endpoints, invent a signature header, market session events as durable delivery, or increase polling load without owner approva…