@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/remix/references/streaming-defer.md

@@ -1,138 +0,0 @@
-# Streaming with Defer
-
-Load this when implementing `defer`, `Await`, `Suspense`, streaming SSR, or handling slow data sources without blocking TTFB.
-
-## How Streaming Works in Remix
-
-When a loader returns `defer()`, Remix sends the initial HTML immediately with resolved data inline and `<script>` placeholders for deferred promises. As deferred promises resolve on the server, Remix streams HTML chunks that replace the placeholders. The browser progressively renders content without a full page reload.
-
-## Basic Defer Pattern
-
-```tsx
-import { defer, type LoaderFunctionArgs } from "@remix-run/node";
-import { Await, useLoaderData } from "@remix-run/react";
-import { Suspense } from "react";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-
-  // Critical data: await it (included in initial HTML)
-  const user = await getUser(userId);
-
-  // Non-critical data: do NOT await (streamed later)
-  const recommendations = getRecommendations(userId); // Returns a Promise
-  const activityFeed = getActivityFeed(userId);        // Returns a Promise
-
-  return defer({ user, recommendations, activityFeed });
-}
-
-export default function Dashboard() {
-  const { user, recommendations, activityFeed } = useLoaderData<typeof loader>();
-
-  return (
-    <div>
-      {/* Renders immediately — user is already resolved */}
-      <h1>Hello, {user.name}</h1>
-
-      {/* Streams in when recommendations resolve */}
-      <Suspense fallback={<RecommendationsSkeleton />}>
-        <Await resolve={recommendations} errorElement={<ErrorFallback />}>
-          {(data) => <RecommendationsList items={data} />}
-        </Await>
-      </Suspense>
-
-      {/* Streams in when activity feed resolves */}
-      <Suspense fallback={<ActivitySkeleton />}>
-        <Await resolve={activityFeed} errorElement={<ErrorFallback />}>
-          {(data) => <ActivityFeed items={data} />}
-        </Await>
-      </Suspense>
-    </div>
-  );
-}
-```
-
-## Rules for Defer
-
-1. **Await critical data, defer non-critical data** -- Only defer data that is not needed for the initial meaningful render. The user should see useful content immediately.
-
-2. **Every `<Await>` must be inside a `<Suspense>`** -- Suspense provides the fallback UI while the promise is pending. Missing Suspense causes an unhandled error.
-
-3. **Use `errorElement` for per-promise error handling** -- Without errorElement, a rejected promise propagates to the route ErrorBoundary, potentially breaking the entire page.
-
-4. **Deferred data is not available on the initial server render** -- The Suspense fallback is what renders in the initial HTML. The resolved content arrives via streaming chunks.
-
-5. **Defer only works with streaming-capable runtimes** -- Node.js, Deno, and Cloudflare Workers support streaming. Some hosting platforms buffer the response and negate the benefit.
-
-## Error Handling with Await
-
-```tsx
-<Suspense fallback={<Skeleton />}>
-  <Await
-    resolve={analytics}
-    errorElement={<AnalyticsUnavailable />}
-  >
-    {(data) => <AnalyticsChart data={data} />}
-  </Await>
-</Suspense>
-```
-
-The `errorElement` renders when the deferred promise rejects. It receives the error via `useAsyncError()`:
-
-```tsx
-import { useAsyncError } from "@remix-run/react";
-
-function AnalyticsUnavailable() {
-  const error = useAsyncError();
-  console.error("Analytics failed:", error);
-
-  return (
-    <div className="error-panel">
-      <p>Analytics are temporarily unavailable.</p>
-      <a href="." reloadDocument>Retry</a>
-    </div>
-  );
-}
-```
-
-## Type Safety with Defer
-
-```tsx
-// TypeScript infers the deferred types correctly
-export async function loader() {
-  const user = await getUser();           // Resolved: User
-  const stats = getStats();               // Deferred: Promise<Stats>
-
-  return defer({ user, stats });
-}
-
-// In the component:
-const { user, stats } = useLoaderData<typeof loader>();
-// user: User (resolved value)
-// stats: Promise<Stats> (must use <Await> to resolve)
-```
-
-## Streaming Response Headers
-
-When using `defer`, set response headers in the defer call:
-
-```tsx
-return defer(
-  { user, analytics },
-  {
-    headers: {
-      "Cache-Control": "private, no-store",
-      "X-Custom-Header": "value",
-    },
-  }
-);
-```
-
-Streaming responses cannot use `headers()` export for Content-Type because the response has already started.
-
-## When NOT to Defer
-
-- Data required for the page title, meta tags, or SEO content -- search engines may not execute streamed JavaScript.
-- Data that determines the layout or routing -- deferred data is not available during SSR, so layout-dependent data must be awaited.
-- Authentication checks -- always await auth checks to prevent rendering protected content in the initial HTML.
-- Data that takes less than 50ms -- the overhead of streaming setup negates the benefit for fast data sources.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/SKILL.md

@@ -1,84 +0,0 @@
----
-name: requesting-code-review
-description: "Use when preparing code for review, writing PR descriptions, selecting reviewers, structuring changes for easy review, or managing review timelines."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: "Claude Code, Codex, GitHub Copilot"
----
-# Requesting Code Review
-
-## Purpose
-
-Maximize the value of every code review by preparing changes for easy, efficient review. This skill turns review requests from a passive "please look at my code" into a structured communication that gives reviewers the context they need to provide fast, high-quality feedback — reducing review cycles, minimizing back-and-forth, and shipping changes faster with fewer defects.
-
-## When to Use
-
-- Preparing a pull request for review and writing a clear, complete PR description
-- Deciding who to assign as reviewers based on domain expertise and availability
-- Structuring commits and file changes so reviewers can follow the logic progressively
-- Managing review timelines when changes are urgent or blocking other work
-- Determining whether to use draft PRs, stacked PRs, or ready-for-review workflows
-- Adding self-review annotations and inline comments to reduce reviewer cognitive load
-
-## Instructions
-
-1. **Self-review before requesting** — walk through your own diff line by line before assigning reviewers, because catching obvious issues yourself (typos, debug logs, accidental file inclusions) prevents wasted reviewer cycles and builds trust that your PRs are worth reviewing carefully.
-
-2. **Write clear PR descriptions with context** — include what changed, why it changed, how it was tested, and any risks or trade-offs, because reviewers who understand the intent behind changes give more relevant feedback and catch issues that a context-free review would miss.
-
-3. **Keep PRs small and focused** — limit each PR to a single logical change (one feature, one bug fix, one refactor), because PRs over 400 lines get slower, shallower reviews with more missed defects, while PRs under 200 lines get reviewed 3x faster with higher-quality feedback.
-
-4. **Add inline comments on tricky decisions** — annotate your own PR with comments on non-obvious choices, workarounds, and known complexity, because proactive explanation prevents reviewers from wasting time asking "why?" on decisions you can explain upfront.
-
-5. **Select appropriate reviewers** — choose reviewers based on domain expertise, recent context with the affected code, and current workload, because assigning the right person gets you faster, more relevant feedback while assigning too many people diffuses responsibility.
-
-6. **Provide context about testing approach** — describe what was tested, how it was tested (manual, unit, integration, E2E), and what was deliberately not tested and why, because reviewers who understand the testing approach can focus their review on untested areas and skip re-verifying covered paths.
-
-7. **Highlight areas needing careful review** — explicitly call out the sections of your change that carry the most risk, complexity, or uncertainty, because directing reviewer attention to high-value areas produces better feedback than hoping they independently identify what matters most.
-
-8. **Manage review timelines and urgency** — communicate the urgency level (blocking deployment, time-sensitive fix, routine feature) and desired review timeline, because reviewers prioritize based on perceived urgency and silent PRs sit at the bottom of the queue.
-
-9. **Structure commits for progressive review** — organize commits in a logical sequence (refactor first, then feature, then tests) so reviewers can follow the evolution of the change, because commit-by-commit review reveals the reasoning behind the final diff better than reviewing the squashed result.
-
-10. **Document known limitations** — explicitly state what this PR does not do, what technical debt it introduces, and what follow-up work is planned, because undocumented limitations become forgotten debt and reviewers who know the scope can evaluate completeness accurately.
-
-11. **Include screenshots for UI changes** — add before/after screenshots, GIFs, or screen recordings for any user-facing visual changes, because reviewers cannot assess UI correctness from code alone and visual evidence eliminates an entire category of back-and-forth.
-
-12. **Link related issues** — reference the issue, ticket, or discussion that motivated the change using closing keywords (Fixes #123, Closes #456), because traceability from PR to requirement enables reviewers to verify the change addresses the original problem and automates issue lifecycle.
-
-13. **Use draft vs ready-for-review intentionally** — open a draft PR when you want early directional feedback on an incomplete approach, and mark ready-for-review only when the change is complete and self-reviewed, because mixing these signals wastes reviewer time on unfinished work or delays feedback on work that needs early course-correction.
-
-14. **Set review expectations** — specify what kind of feedback you need (architecture direction, security audit, quick sanity check, full deep review), because reviewers who know the expected depth can calibrate their effort and provide the specific type of feedback you actually need.
-
-## Output Format
-
-When preparing a review request, provide:
-
-1. **PR title** — concise summary of the change in imperative mood (under 72 characters)
-2. **Description** — what changed, why, and how, structured with clear headings
-3. **Testing summary** — what was tested, how, and what was not tested
-4. **Risk assessment** — areas of highest risk or uncertainty that need careful review
-5. **Reviewer recommendation** — who should review and why, with urgency level
-6. **Review guidance** — what type of feedback is needed and any specific areas to focus on
-
-## References
-
-| File | Purpose |
-|------|---------|
-| `references/pr-description-patterns.md` | Templates and examples for writing effective PR descriptions across different change types |
-| `references/reviewer-selection.md` | How to select the right reviewers based on expertise, workload, and change characteristics |
-| `references/self-review-checklist.md` | Step-by-step checklist for self-reviewing your changes before requesting external review |
-
-## Copilot Platform Notes
-
-- Custom agents are defined in `.github/agents/*.md` with YAML frontmatter: `name`, `description`, `tools`, `model`, `handoffs`.
-- Agent `handoffs` field enables guided workflow transitions (e.g., `@project-planner` → `@orchestrator`).
-- Skill files are stored under `.github/skills/` (skill markdown) and `.github/prompts/` (prompt files).
-- Path-scoped instructions in `.github/instructions/*.instructions.md` provide file-pattern-targeted guidance via `applyTo` frontmatter.
-- User arguments are provided as natural language input in the prompt, not through a `$ARGUMENTS` variable.
-- Frontmatter keys `context: fork` and `allowed-tools` are not natively supported; guidance is advisory.
-- Reference files can be included via `#file:references/<name>.md` syntax in Copilot Chat.
-- MCP configuration lives in `.vscode/mcp.json`. MCP skill tools are available when configured.
-- Rules file: `.github/copilot-instructions.md` — broad and stable, not task-specific.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/evals/assertions.md

@@ -1,52 +0,0 @@
-# Requesting Code Review Eval Assertions
-
-## Eval 1: PR Description Quality
-
-This eval tests whether the skill produces a well-structured PR description with sufficient context, risk assessment, testing details, and review guidance for a feature change that touches multiple areas.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                          |
-|---|----------|-------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| 1 | contains | `cache` — Core feature description              | The PR description must clearly describe the caching feature being added, as this is the central change.|
-| 2 | contains | `Redis` — Implementation technology             | Reviewers need to know the specific technology to evaluate the approach and check for Redis-specific issues (connection pooling, memory limits, serialization). |
-| 3 | contains | `auth` — Risk area identification               | The auth middleware reordering is the highest-risk part of this change. Failing to highlight it means the reviewer may not scrutinize it. |
-| 4 | contains | `invalidation` — Cache consistency strategy     | Cache invalidation is the hardest part of caching. The description must address how stale data is prevented. |
-| 5 | contains | `test` — Testing approach description           | Reviewers need to know what was tested and how, so they can focus review effort on untested areas. |
-| 6 | contains | `review` — Review guidance and expectations     | The request must specify what feedback is needed and where reviewers should focus their attention. |
-
-### What a passing response looks like
-
-- Includes a concise PR title summarizing the caching feature.
-- Provides a structured description with What/Why/How sections.
-- Calls out the auth middleware reordering as a high-risk area needing careful review.
-- Describes the cache invalidation strategy and its trade-offs.
-- Includes a testing section covering unit tests, integration tests, and manual verification.
-- Recommends a reviewer with backend/infrastructure expertise.
-- Specifies the desired review depth and focus areas.
-
----
-
-## Eval 2: Reviewer Selection and Timeline
-
-This eval tests whether the skill correctly selects reviewers based on expertise and availability, and communicates appropriate urgency for a security fix.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                          |
-|---|----------|-------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| 1 | contains | `Bob` — Primary reviewer selection              | Bob is the best primary reviewer: frontend expertise, availability, and original code context. |
-| 2 | contains | `Alice` — Security sign-off                     | Alice should be involved as security team lead, even if her review comes after initial approval. |
-| 3 | contains | `urgent` — Urgency communication                | The review request must clearly communicate that this is time-sensitive due to an active vulnerability. |
-| 4 | contains | `XSS` — Vulnerability identification            | The vulnerability type must be clearly stated so reviewers understand the threat model. |
-| 5 | contains | `sanitiz` — Fix approach description            | The sanitization approach must be described so reviewers can evaluate completeness and correctness. |
-
-### What a passing response looks like
-
-- Recommends Bob as the primary reviewer due to availability and frontend expertise.
-- Recommends Alice as a secondary reviewer for security sign-off after her meetings.
-- Does not recommend waking Dave (different timezone, 11pm) for a non-critical-infrastructure fix.
-- Notes Carol is too new to be the primary reviewer for a security fix but could be added for learning.
-- Communicates clear urgency with a specific timeline (review by end of day).
-- Includes a PR description that clearly states the XSS vulnerability and the sanitization fix.
-- Suggests a two-phase approval: Bob for immediate merge, Alice for post-merge security audit if timeline requires.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/evals/evals.json

@@ -1,71 +0,0 @@
-[
-  {
-    "name": "pr-description-quality",
-    "description": "Validate that the skill produces a well-structured PR description with context, testing details, and review guidance for a feature change.",
-    "input": "I just finished implementing a new caching layer for our API. It uses Redis to cache GET responses for 5 minutes. I changed the middleware pipeline, added cache invalidation on POST/PUT/DELETE, and updated the config to accept Redis connection strings. The changes touch the auth middleware because I had to reorder the pipeline. Help me write a PR description and prepare this for review.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "cache",
-        "description": "Must describe the caching feature being added, as this is the core change being reviewed."
-      },
-      {
-        "type": "contains",
-        "value": "Redis",
-        "description": "Must mention the specific technology (Redis) used for caching, as reviewers need to know the implementation approach."
-      },
-      {
-        "type": "contains",
-        "value": "auth",
-        "description": "Must highlight the auth middleware reordering as a risk area, since changes to auth pipeline require careful review."
-      },
-      {
-        "type": "contains",
-        "value": "invalidation",
-        "description": "Must address cache invalidation strategy, as stale cache is the most common caching bug."
-      },
-      {
-        "type": "contains",
-        "value": "test",
-        "description": "Must include a testing section describing how the caching behavior was verified."
-      },
-      {
-        "type": "contains",
-        "value": "review",
-        "description": "Must provide review guidance specifying what kind of feedback is needed and where reviewers should focus."
-      }
-    ]
-  },
-  {
-    "name": "reviewer-selection-and-timeline",
-    "description": "Validate that the skill recommends appropriate reviewers and manages review timeline for an urgent security fix.",
-    "input": "I found and fixed an XSS vulnerability in our user profile page. The fix sanitizes user-generated HTML in the bio field before rendering. It's a 30-line change in the frontend rendering layer plus 10 lines of tests. This needs to ship today because we got a report from a security researcher. We have these potential reviewers:\n- Alice: security team lead, currently in meetings until 3pm\n- Bob: frontend team lead, currently free, reviewed the original profile page code\n- Carol: full-stack developer, free, but new to the team (2 weeks)\n- Dave: backend developer, familiar with the sanitization library, in a different timezone (currently 11pm for him)\n\nHelp me prepare this review request.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "Bob",
-        "description": "Must recommend Bob as a primary reviewer since he has frontend expertise, is available, and reviewed the original code."
-      },
-      {
-        "type": "contains",
-        "value": "Alice",
-        "description": "Must recommend involving Alice (security lead) for security sign-off, even if delayed until after her meetings."
-      },
-      {
-        "type": "contains",
-        "value": "urgent",
-        "description": "Must communicate the urgency of the review given the active security vulnerability and same-day shipping requirement."
-      },
-      {
-        "type": "contains",
-        "value": "XSS",
-        "description": "Must identify the vulnerability type (XSS) clearly in the review request context."
-      },
-      {
-        "type": "contains",
-        "value": "sanitiz",
-        "description": "Must describe the sanitization approach so reviewers can evaluate the fix's completeness."
-      }
-    ]
-  }
-]

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/examples/01-preparing-pr-for-review.md

@@ -1,81 +0,0 @@
-# Example: Preparing a Feature PR for Review
-
-## Scenario
-
-A developer has completed a new search feature for an e-commerce application. The change touches the API layer, database queries, and frontend components. The developer needs to prepare a review request that gives reviewers full context and directs their attention effectively.
-
-## User Prompt
-
-> I just finished building product search for our e-commerce app. Here is what I changed:
->
-> - Added a `/api/products/search` endpoint that accepts query, category, price range, and sort parameters
-> - Created a PostgreSQL full-text search index on product name and description
-> - Added a search bar component in the header with autocomplete
-> - Added debounced API calls from the frontend (300ms)
-> - Changed the product list page to support search results view
->
-> Total: ~350 lines across 8 files. The autocomplete uses a new dependency (`downshift`). I am not sure if the full-text search index approach is the right long-term solution versus Elasticsearch, but it works for our current catalog size (5,000 products).
->
-> Help me prepare this for code review.
-
-## Expected Response
-
-### PR Title
-
-Add product search with full-text search and autocomplete
-
-### PR Description
-
-#### What
-
-Adds product search functionality with server-side full-text search and client-side autocomplete. Users can search by product name and description, filter by category and price range, and sort results by relevance, price, or date.
-
-#### Why
-
-Product search is the #1 requested feature from user feedback (Issue #89). Currently users must browse categories manually, which does not scale as the catalog grows.
-
-#### How
-
-- **Backend**: New `/api/products/search` endpoint using PostgreSQL `tsvector` full-text search with GIN index on `products.name` and `products.description`. Supports filtering by category and price range, with relevance-ranked results.
-- **Frontend**: Search bar component in the header using `downshift` for accessible autocomplete. API calls are debounced at 300ms to avoid excessive requests during typing.
-- **Database**: Migration adds a `search_vector` column and GIN index. Migration is backward-compatible (additive only).
-
-#### Testing
-
-- Unit tests for search query builder (edge cases: empty query, special characters, SQL injection attempts)
-- Integration test for the search endpoint with seeded test data
-- Manual testing of autocomplete UX in Chrome and Firefox
-- **Not tested**: Safari autocomplete behavior, search performance at scale beyond 5,000 products
-
-#### Known Limitations
-
-- Full-text search is PostgreSQL-specific. If we migrate databases, this will need rework.
-- The `tsvector` approach works for our current catalog size (~5,000 products) but may need to be replaced with Elasticsearch or Typesense as the catalog grows past 50,000.
-- Autocomplete does not yet support search history or popular searches.
-
-#### Risk Areas
-
-1. **Database migration** (medium risk) — adds a GIN index that may lock the products table during creation on large datasets. Current production table is small, so this should be fast.
-2. **New dependency: downshift** (low risk) — well-maintained React library for accessible autocomplete. 2MB gzipped, tree-shakeable.
-
-### Review Guidance
-
-- **Primary focus**: Please review the search query builder for correctness and SQL injection safety. I am using parameterized queries but want a second set of eyes.
-- **Secondary focus**: Is the `downshift` dependency justified, or should we build a simpler autocomplete without a library?
-- **Architecture question**: I chose PostgreSQL full-text search over Elasticsearch for simplicity. Does this trade-off make sense given our current scale?
-- **Depth**: Standard review. No auth or payment changes.
-
-### Reviewer Recommendation
-
-- **Primary**: Someone with PostgreSQL and backend API experience
-- **Secondary**: Someone with React component and accessibility experience
-- **Urgency**: Normal — no deadline pressure, but this unblocks the catalog team
-
-## Why This Response Works
-
-- The PR description follows a clear What/Why/How structure that gives reviewers full context before they read code.
-- Known limitations and the Elasticsearch trade-off are stated upfront, preventing reviewers from raising issues the author already considered.
-- The testing section explicitly states what was not tested, directing reviewer attention.
-- Risk areas are ranked and explained, so reviewers calibrate depth accordingly.
-- Review guidance specifies exactly what feedback the author needs, avoiding wasted effort on areas that are already settled.
-- The reviewer recommendation matches expertise to the areas that need review.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/examples/02-complex-refactor-review-request.md

@@ -1,131 +0,0 @@
-# Example: Complex Refactor Review Request
-
-## Scenario
-
-A senior developer has completed a large refactoring of the notification system, moving from a synchronous in-process model to an async event-driven architecture using a message queue. The change is 600 lines across 15 files and needs to be reviewed by multiple people with different expertise.
-
-## User Prompt
-
-> I just finished refactoring our notification system from synchronous to async. Here is the summary:
->
-> - Replaced direct function calls to `sendEmail()`, `sendSMS()`, `sendPush()` with events published to a RabbitMQ queue
-> - Added a notification worker service that consumes events and dispatches to the appropriate channel
-> - Added retry logic with exponential backoff (3 retries, max 30s delay)
-> - Added a dead letter queue for failed notifications
-> - Migrated 12 call sites across 6 services to use the new event-based API
-> - Added a `notifications` database table to track delivery status
->
-> Total: ~600 lines across 15 files. This is bigger than I wanted but the migration had to be atomic — we cannot have some call sites using the old pattern and some using the new one.
->
-> The team is:
-> - Elena: principal engineer, designed the original notification system, on PTO until Thursday
-> - Frank: backend lead, RabbitMQ expert, available now
-> - Grace: owns 3 of the 6 services that were migrated, available now
-> - Hassan: DevOps, manages the RabbitMQ cluster, available tomorrow
->
-> This is not urgent — no deadline. But I want thorough review because this touches a lot of surfaces. Help me prepare the review request.
-
-## Expected Response
-
-### PR Title
-
-Refactor notification system to async event-driven architecture
-
-### PR Description
-
-#### What
-
-Replaces the synchronous notification dispatch (`sendEmail()`, `sendSMS()`, `sendPush()`) with an async event-driven architecture using RabbitMQ. All 12 notification call sites across 6 services now publish events to a message queue, and a new worker service consumes and dispatches notifications.
-
-#### Why
-
-The synchronous approach causes three problems:
-1. **Latency**: Sending notifications inline blocks the request (email API calls take 200-500ms).
-2. **Reliability**: If the email provider is down, the entire request fails even though the core operation succeeded.
-3. **Scalability**: Notification volume during peak events (sales, password resets) creates cascading slowdowns across services.
-
-The async approach decouples notification dispatch from business logic, adds retry capability, and enables independent scaling of notification throughput. Related: Issue #156 (notification latency), Issue #201 (email provider outages).
-
-#### How
-
-**Architecture change**:
-```
-Before: Service -> sendEmail() -> Email API (synchronous, inline)
-After:  Service -> publish(NotificationEvent) -> RabbitMQ -> Worker -> Email API (async, decoupled)
-```
-
-**Key components**:
-- `NotificationEvent` schema: type, recipient, template, payload, metadata
-- `notification-worker`: new service that consumes events, dispatches via the appropriate channel, and tracks delivery status
-- Retry policy: exponential backoff (1s, 4s, 16s), max 3 attempts, then dead letter queue
-- `notifications` table: tracks event_id, status (queued/sent/failed/dead-lettered), attempts, timestamps
-
-**Migration approach**:
-- All 12 call sites migrated atomically in this PR to avoid split-brain behavior
-- Old `sendEmail/SMS/Push` functions replaced with `publishNotification()` wrapper
-- Backward-compatible: if RabbitMQ is unreachable, falls back to synchronous dispatch with a warning log
-
-#### Commit Structure
-
-Review commit-by-commit for the best experience:
-1. `Add NotificationEvent schema and RabbitMQ publisher` — the new event model and publishing layer
-2. `Add notification worker service with retry logic` — the consumer, dispatcher, and retry policy
-3. `Add notifications tracking table and migration` — database schema for delivery tracking
-4. `Migrate call sites to event-based notification API` — the 12 call site migrations across 6 services
-5. `Add integration tests for async notification flow` — end-to-end tests with RabbitMQ test container
-6. `Add dead letter queue handling and alerting` — DLQ consumer and PagerDuty alert integration
-
-#### Testing
-
-- Unit tests for NotificationEvent validation, retry logic, and backoff calculation
-- Integration tests using Testcontainers with a real RabbitMQ instance
-- End-to-end test: publish event, verify worker consumes and dispatches, verify delivery status recorded
-- Manual testing: killed RabbitMQ mid-dispatch to verify fallback behavior
-- Load test: 1,000 events/second sustained for 5 minutes, no message loss
-- **Not tested**: Behavior during RabbitMQ cluster failover (need Hassan's help to simulate)
-
-#### Known Limitations
-
-- The fallback to synchronous dispatch means a RabbitMQ outage degrades performance but does not prevent notifications. This is a conscious trade-off for the migration period. Post-migration, we should consider queuing to a local buffer instead.
-- The dead letter queue alert goes to PagerDuty but there is no self-service retry UI yet. Failed notifications must be replayed manually via `rabbitmqadmin`.
-- No rate limiting per recipient. A bug in a calling service could spam a user with notifications. Follow-up: Issue #234.
-
-#### Risk Areas
-
-1. **Call site migration correctness** (high risk) — 12 call sites across 6 services must all produce correctly-shaped events. A malformed event silently enters the DLQ.
-2. **Retry and backoff logic** (medium risk) — incorrect backoff could hammer the email provider or create infinite retry loops.
-3. **Database migration** (low risk) — additive only, new table, no existing schema changes.
-4. **RabbitMQ configuration** (medium risk) — queue declarations, exchange bindings, and DLQ routing must match between publisher and consumer.
-
-### Review Guidance
-
-- **Commit-by-commit review recommended**: Each commit builds on the previous one. Reviewing the squashed diff will be overwhelming at 600 lines.
-- **Focus areas by reviewer**:
-  - Frank: RabbitMQ patterns (exchange/queue topology, message durability, ack handling, retry logic)
-  - Grace: Call site migrations in the 3 services she owns (verify event payloads match the templates each service uses)
-  - Hassan: RabbitMQ configuration, deployment concerns, monitoring and alerting setup
-  - Elena: Overall architecture review when she returns from PTO (non-blocking)
-- **Architecture decision to validate**: The synchronous fallback when RabbitMQ is down. Is this the right trade-off, or should we fail fast and rely on the calling service to handle the error?
-- **Depth**: Deep review for the worker service and retry logic. Standard review for call site migrations. Quick review for the database migration.
-
-### Reviewer Recommendation
-
-| Reviewer | Focus Area | Priority | Timeline |
-|----------|-----------|----------|----------|
-| Frank | RabbitMQ architecture, retry logic, message durability | Primary | This week |
-| Grace | Call site migrations in her 3 services | Primary | This week |
-| Hassan | RabbitMQ config, deployment, monitoring | Secondary | When available tomorrow |
-| Elena | Overall architecture sign-off | Advisory | After PTO Thursday (non-blocking) |
-
-**Urgency**: Low — no deadline. Prefer thorough review over speed. Happy to wait for Elena's feedback before merging if the team prefers.
-
-## Why This Response Works
-
-- The PR description addresses the "why" before the "how," helping reviewers understand the motivation.
-- The architecture diagram (before/after) gives reviewers a mental model before diving into code.
-- The commit structure guide enables progressive review of a large change.
-- Each reviewer gets specific focus areas matching their expertise, reducing duplicated effort.
-- The risk areas are ranked so reviewers allocate attention proportionally.
-- Known limitations and follow-up issues demonstrate the author has thought about completeness.
-- The non-urgent timeline with an advisory review from Elena shows mature process awareness.
-- The architecture question (synchronous fallback) invites the kind of feedback that improves the design.