Memory Wiki

Now let me examine the existing module code to understand the interfaces and patterns I need to follow.

Let me also check the composer.json and test patterns used by existing modules.

Let me also check the existing test patterns used across modules.

Let me check a sample migration and exception file to understand the patterns.

Now let me also see the CheckoutServiceModule to understand the full registration pattern.

Now I have a complete picture of the codebase. Let me write all three build briefs.

Let me verify all three files were written correctly.

All three build briefs written successfully. Here's the summary of what was produced: --- ## Delivery: 3 Per-Module Build Briefs ### 1. `/root/.hermes/plans/task-t52-build-plan.md` (554 lines) **T52: `google_ads_conversion`** — New module for server-side Google Ads Conversion API Key contents: - **Interface contract**: `GoogleAdsConversionInterface` with `uploadConversion()`, `isReady()`, `hashEmailForEnhancedConversions()` — full method signatures with docblocks - **Exception class**: `GoogleAdsConversionException` with factory methods `fromApiError()`, `credentialsNotConfigured()`, `tokenRefreshFailed()` - **OAuth2 setup**: 5-step Google Cloud Console walkthrough (service account, consent screen, refresh token) - **Developer token**: Application procedure (1-2 week review), token types (Basic/Standard/Premium), security rules - **Config keys**: 10 config values documented (`developer_token`, `customer_id`, `oauth2.*`, `conversion_action_id`, etc.) — all credential values MUST be encrypted at rest - **composer.json**: Depends on `googleads/google-ads-php ^26` - **DI wiring**: Module registers `GoogleAdsConversionInterface` → `GoogleAdsConversionService` with single `ConfigManagerInterface` dependency - **Error handling**: 8 scenarios covered (missing credentials, OAuth2 expiry, rate limits, network timeout, invalid GCLID) - **Tests**: 18 tests specified (14 service + 4 module), exceeding the 12-test minimum - **FAULT prevention**: References FAULT-003, FAULT-005, FAULT-008, FAULT-011, FAULT-017 ### 2. `/root/.hermes/plans/task-t17-conversion.md` (492 lines) **T17: `webhook_handler`** — Conversion upload integration in webhook handler Key contents: - **Interface unchanged**: `WebhookHandlerInterface` is stable — conversion upload is an internal detail - **Modified `handleCheckoutSessionCompleted()`**: Emits `payment_succeeded` as before, then calls `uploadConversionToGoogleAds()` with GCLID from session metadata - **Non-blocking design**: Conversion upload failures are caught and logged — they MUST NOT propagate up and cause the webhook to be marked as failed - **Retry queue**: Uses `profe_webhook_events` table with 3 new columns (`conversion_retry_count`, `conversion_retry_at`, `conversion_payload`) — exponential backoff: 5min → 15min → 1hr → 6hr → 24hr - **DI wiring**: 5 → 6 dependencies in constructor (adds `GoogleAdsConversionInterface`), factory closure updated in `WebhookHandlerModule` - **GCLID skip**: When `gclid` is empty/null in metadata, upload is silently skipped (logged at INFO) - **Tests**: 10 new tests (7 unit + 3 integration) plus updates to existing tests - **FAULT prevention**: References FAULT-005, FAULT-008, FAULT-011, FAULT-013 ### 3. `/root/.hermes/plans/task-t15-embedded-checkout.md` (603 lines) **T15/T16:** Stripe Embedded Checkout mode + GCLID capture from Site Kit Key contents: - **Backwards-compatible interface**: `createCheckoutSession()` gains `$uiMode = 'hosted'` (default) and `$metadata = []` — existing callers unaffected - **Return value**: Hosted mode returns `{ session_id, url }` as before. Embedded mode returns `{ session_id, url, client_secret }` - **GCLID capture**: Reads from Site Kit by Google cookies (`_gcl_aw`, `_gcl_dc`) — we do NOT build custom GCLID detection. Falls back to `$_GET['gclid']` - **Frontend component**: `stripe-embedded-checkout.js` — mounts Stripe iframe in `#checkout-container`, fires `gtag` on `onComplete` callback. Client-side conversion is **redundant** — server-side (Phase 1) is the reliable path - **CSP directives**: 4 directives specified (`frame-src`, `script-src`, `connect-src`, `style-src`) with Stripe domains - **Error handling**: 10 scenarios covered — ad blocker guard on `gtag`, timeout/loading state, invalid `ui_mode` validation, missing `client_secret` - **Tests**: 16 new tests across T15 and T16 - **FAULT prevention**: References FAULT-004, FAULT-005, FAULT-008, FAULT-011 ### Cross-Cutting Concerns Addressed | Requirement | Coverage | |---|---| | FAULT-005 (no tests) | T52: 18 tests, T17: +10 tests, T15/T16: +16 tests | | FAULT-008 (dependency not injected) | All DI wiring verified — every declared dependency is injected and used | | FAULT-011 (quadruple-backslash) | All namespace strings use `\\` (2 backslashes) as required | | Deduplication strategy | Both browser + server signals share same `(Gclid, ConversionAction, ConversionDateTime)` — Google Ads deduplicates | | GCLID persistence chain | Site Kit cookie → T16 `metadata['gclid']` → Stripe Session → T17 webhook → T52 upload |