# SESSION-0005.0 — Shopify BDD analysis: final domains + library complete

**Date:** 2026-05-31
**Driver:** Ben Stull + Claude (Sonnet 4.6)
**Repos touched:** wiggleverse-ecomm-meta (session record),
Shopify Analysis workspace (`~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/` — not a git repo; flat file workspace)

> **Honesty note on this artifact.** This is a *session record* authored by
> the assistant from the conversation — faithful and uncurated as to
> decisions, sequence, and wrong turns, but **not** the raw byte-for-byte
> transcript. OHM publishes raw transcripts via `ohm-infra`'s
> `publish-transcript.sh`; ecomm has no such tooling yet. Building a
> transcript-dump path is a future roadmap item. Until then, records like
> this stand in — labeled as what they are.

---

## Purpose

Complete the Shopify BDD scenario library. Session 4 left four domains in the
queue (`analytics/`, `finance/`, `markets/`, `sales-channels/`) and marked
`apps/` as lower-priority / deferred. This session targeted those four, then
Ben extended scope to include `apps/` — bringing the entire library to
completion in a single session.

## What happened, in order

1. **Session opened; memory loaded.** Ben said "Continue the Shopify BDD
   work." Memory was read (`project-shopify-bdd.md`) — confirmed 4 remaining
   domains, locked style rules, and running totals (44 files, ~960 scenarios
   at session open). No realignment needed.

2. **Task list created.** Five tasks scaffolded upfront: one per domain plus
   an update task for memory and the domain map. `apps/` was not yet on the
   list — it was still marked deferred in memory.

3. **analytics/ — 3 files written.** `dashboard.md` (overview metrics —
   today's KPIs, period comparison, date-range switching, sales by channel,
   top products, returning vs. new customer split, widget drill-through, zero-
   state for new store; sessions and traffic — time-series chart, source
   breakdown, top landing pages, engagement metric, device-type filter),
   `reports.md` (sales — over time, by product, by traffic referrer, by
   billing location, by discount code, export, date-range change, channel
   filter; customers — over time, returning, first-time vs. returning split,
   by location, predicted spend tier; inventory — snapshot, sell-through rate,
   ABC analysis, days remaining; behaviour/conversion — online store conversion
   funnel, drop-off identification, top referrers, sessions by device type,
   sessions by landing page), `live-view.md` (real-time monitoring — current
   visitor count, geographic map, top active pages, recent completed orders,
   add-to-cart events, source filter, flash-sale monitoring, zero-activity
   state; activity feed detail — event-type distinction, add-to-cart frequency
   read, order value visibility). ~65 scenarios. Memory updated.

4. **finance/ — 3 files written.** `balance.md` (account overview — current
   balance, pending vs. available distinction, transaction history, date-range
   filter, payout deposit identification, transaction detail, CSV export; card
   and rewards — card details, fund transfer to card, cashback view, cashback
   redemption), `payouts.md` (schedule and history — next payout amount/date,
   history list, payout detail breakdown, processing fees identification, bank
   account on file, bank account change, instant payout, schedule frequency
   view and change; holds and reserve — hold with reason, reserve amount,
   failed payout notification), `bills.md` (bill history — current cycle
   charges, history list, invoice detail, plan subscription line item, app
   charges, transaction fees, download/print invoice; payment method — card on
   file, card update, billing failure notice; credits and adjustments — credit
   line item, pro-rated upgrade charge). ~65 scenarios. Memory updated.

5. **markets/ — 3 files written.** `international-markets.md` (creating and
   configuring — view all markets, single-country market, multi-country
   grouping, activate, deactivate without deleting, delete, unassigned
   countries, set primary market; per-market settings — currency, customer
   access toggle, dedicated domain/subdomain, language assignment, shipping
   rates, product availability restriction), `localized-pricing.md` (currency
   and exchange rates — automatic rate, manual/fixed rate, percentage-based
   price adjustment, negative adjustment for discounting, price rounding,
   pricing preview, variant-level fixed override, removing an override;
   duties and import fees — enable duty collection, duty-inclusive pricing,
   DDP shipping terms, duty collection disabled), `market-domains.md` (domain
   and subdomain assignment — assign existing domain, assign subdomain, assign
   subfolder path, view domain per market, remove domain assignment, conflict
   warning; geolocation and redirection — automatic country-based redirect,
   selector banner vs. auto-redirect, customer override preference, wrong-market
   browsing behaviour). ~70 scenarios. Memory updated.

6. **sales-channels/ — 5 files written.** `online-store.md` (channel
   management — confirm active, product availability toggle, password
   protection on/off, storefront preview, channel performance metrics;
   customization entrypoints — themes, navigation, preferences navigation
   shortcuts), `pos.md` (setup — add channel, view locations, activate at
   location, staff access, hardware setup, receipt configuration; selling
   and checkout — add by search/scan, apply discount, split payment methods,
   card reader payment, refund, offline cash sale, orders in admin view;
   inventory and cash management — inventory deduction on sale, cash drawer
   open/close session, shift cash flow summary), `shop-app.md` (channel
   overview — enable, eligibility requirements, store profile customization,
   product availability, performance metrics; Shop Pay and post-purchase —
   accelerated checkout, order tracking, post-purchase offers, follower count,
   Shop campaign to followers), `social.md` (Facebook & Instagram — connect
   Business account, catalog sync, Facebook Shop setup, Instagram Shopping
   tags, sync status and errors, channel orders, Meta Pixel configuration;
   Google & YouTube — connect Merchant Center, product sync, Smart Shopping
   campaigns, free listings, resolve disapproval; TikTok — connect for
   Business, catalog sync, ad campaign), `headless.md` (Hydrogen — create
   storefront, view connected storefronts, Storefront API credentials, deploy
   via Oxygen, rollback deployment, performance metrics, custom domain,
   delete storefront; Storefront API — product catalog retrieval, cart
   management, checkout redirect, customer account data, metafield exposure).
   ~85 scenarios. Memory updated.

7. **Memory and domain map updated — four-domain run complete.** Running
   total at this point: 12 domains, 61 files, ~1,215 scenarios. Domain map
   (`shopify-domain-map.md`) updated with Status column for all rows.

8. **Ben extended scope to apps/.** After completing the four queued domains,
   Ben said "Go ahead and tackle that, too." `apps/` had been flagged in
   memory as deferred/lower-priority. Two new tasks created on the spot.

9. **apps/ — 4 files written.** `app-store.md` (discovery — browse App Store,
   keyword search, category filter, app detail page, pricing preview, reviews,
   Shopify-built indicator; installation — free app install, permissions review
   and accept, decline and abort, paid app plan selection, free trial install,
   external-account setup redirect), `installed-apps.md` (list management —
   view all installed, open embedded app, billing status identification, last-
   used date, uninstall with confirmation, data retention post-uninstall,
   reinstall; permission review — view granted scopes, write-access risk
   understanding, permission upgrade prompt, revoke without uninstalling),
   `custom-apps.md` (custom app creation — navigate to section, enable custom
   app development, create app, configure Admin API scopes, generate access
   token, regenerate token, view API key and secret, delete custom app;
   collaborator access — approve collaborator request, grant section-level
   access, remove collaborator, seat-limit non-consumption, view all
   collaborators), `webhooks.md` (subscription management — view all, create,
   test, available topics, orders/create, products/update, update endpoint,
   delete, delivery failure retry, reactivate paused; security — HMAC
   verification, reject invalid HMAC, shop-domain header for multi-store
   routing). ~70 scenarios. Memory updated to final state.

10. **Session record requested.** Ben issued the record request with the
    exact filename pre-assigned (`SESSION-0005.0-TRANSCRIPT-2026-05-31.md`),
    target path, and format instructions matching SESSION-0001.0 house style.

11. **Sessions folder not mounted; access requested and approved.** Same
    pattern as Session 4 — the sessions directory is not a pre-connected
    workspace folder. `request_cowork_directory` called with explicit path;
    Ben approved it. SESSION-0001.0 and SESSION-0004.0 read for house style
    before writing.

12. **Session record written (this file).** Serial from main agent context;
    no subagents.

## Decisions citable later

- **apps/ included in the BDD library.** Originally deferred as lower-priority;
  Ben extended scope in-session. The library now covers all 13 domains in
  `shopify-domain-map.md` (all rows marked ✅).
- **Webhook HMAC verification captured as a scenario.** The security contract
  (verify `X-Shopify-Hmac-Sha256`, reject non-2xx on mismatch, use
  `X-Shopify-Shop-Domain` for multi-store routing) is documented in
  `apps/webhooks.md` — relevant to any integration layer we build.
- **Custom app token is one-time visible.** The Admin API access token is
  revealed and copyable exactly once after install; navigating away loses it.
  Captured in `apps/custom-apps.md`; our platform must decide whether to
  adopt the same security posture or offer re-display with re-auth.
- **Collaborator access does not consume a staff seat.** Shopify's carve-out
  for Partner/collaborator access is documented. Our platform will need a
  similar concept (agency/developer access without burning a plan-tier seat).
- **Shopify-built apps are labeled distinctly in the App Store.** Trust signal
  in the discovery flow — our platform's equivalent marketplace should consider
  the same first-party provenance marker.
- **POS offline cash sales sync on reconnect; card payments require connectivity.**
  Captured in `sales-channels/pos.md`. Fundamental constraint for the POS
  design (Hasan and Connie are both in-person sellers).

## Open / carried forward

- **`general.md` first-person inconsistency** — carried from Sessions 2 and 3,
  still unresolved. Ben to decide.
- **No git history on Shopify Analysis workspace** — still a flat folder with
  no version control. If the library is a reference artifact for the build
  phase, this is worth addressing.
- **Sessions folder must be re-approved each session** — not a pre-connected
  workspace folder; `request_cowork_directory` will be needed again.
- **Shopify BDD library is now complete.** The analysis phase is done. Next
  natural step is to consume the ~1,285 scenarios to drive platform design —
  either synthesising them into a capability map / requirements doc, or moving
  directly into the prototype (Wave 1 of the ROADMAP).

## Next session

```
This is the next session of the ecomm project. The Shopify BDD analysis phase
is complete.

READ FIRST:
- Your memory for this project (project-shopify-bdd.md and any other loaded
  memories via MEMORY.md).
- ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/ROADMAP.md — confirm
  where we are in the wave plan and what Wave 1 says.
- ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/sessions/SESSION-0005.0-TRANSCRIPT-2026-05-31.md
  — especially "Decisions citable later" and "Open / carried forward."
- ~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/shopify-domain-map.md
  — the full domain list; all 13 domains are now marked ✅.

CONTEXT:
The Shopify BDD library is complete: 13 domains, 65 files, ~1,285 Gherkin
scenarios covering every significant slice of Shopify admin functionality.
It lives at ~/projects/wiggleverse/ecomm/Claude/Shopify Analysis/.

The library was built to answer: "what does Shopify do, so we can decide what
to rebuild?" That question is now answered in scenario form. The next phase
is to act on it.

TASK OPTIONS — Ben to choose or direct at session open:

  A) Synthesis pass — read across the 65 files and produce a platform
     capability map: which Shopify features are must-have for Hasan & Connie
     on day one, which are nice-to-have, and which we intentionally skip or
     do differently (our wedge). Output: a CAPABILITY-MAP.md in
     wiggleverse-ecomm-meta/.

  B) Wave 1 — vibe-code the throwaway prototype in wiggleverse-ecomm-prototype,
     driven by the Hasan & Connie scenarios from the BDD library (POS sale,
     storefront browse + checkout, discount at spend). Per the ROADMAP:
     super wobbly, local-only, fake money, no engineering standards.

  C) Wave 2 — OHM concept RFCs for the core commerce entities surfaced by the
     BDD analysis (Product, Order, Cart, Payment, Merchant, Storefront, Credit).
     These need to land in ohm-rfc/ before binding code can be written.

Ben to decide direction. If unclear, do Option A first — the capability map is
a fast session and sharpens scope for whichever wave comes next.

NOTE: The sessions folder is not pre-connected — call request_cowork_directory
for ~/projects/wiggleverse/ecomm/git/wiggleverse-ecomm-meta/sessions before
writing the next record.
```

*Session 5 closed here.*