user-journey-simulation

Imported from dtebar-10010/tq_v02 (.github/skills/user-journey-simulation/SKILL.md). Install upstream with npx skills add dtebar-10010/tq_v02 --skill user-journey-simulation. Copyright stays with the author.

User Journey Simulation Workflow (tqv02)

Use this skill to build and execute a bounded, high-confidence simulator for user interactions across tqv02, record the results into the persistent journey catalog, gate publish readiness, and remediate defects found during exploration.

This skill is catalog-backed: the journey inventory, the state dimensions, the run ledger, and the publish-readiness gate all live in the database (tq_journey_* tables), not in prose. Prose here tells you how to drive them.

Scope

End-to-end user journeys across:

• HTTP routes and function-based view handlers (tqv02_app/views/*.py)
• front-end interaction paths (jQuery CartManager in static/js/front.js, AJAX endpoints)
• state transitions (auth, role, cart, wishlist, coupon, locale, currency, stock, merge, payment intent, consent, rate-limit, notification)
• correctness invariants at every transition (HTTP, DB, money units, cross-surface parity, i18n, security)
• side-effect surfaces (emails, Stripe, webhooks, sessions, cache, CSV exports, PDFs)
• defect reproduction and remediation with regression tests
• persistence of results and readiness trend (JourneyRun, PublishReadinessSnapshot)

Out of scope unless explicitly requested: load/performance benchmarking (use performance-auditor), translation-string authoring (use i18n-workflow), deploy execution (use pa-deploy-safety).

Persistence spine (read this before anything else)

Hard facts about the spine that constrain what you may do:

• JourneyPermutation.permutation_code is max_length=24 and unique. Generated codes are f"{journey_code}-{sha256(...)[:11]}". Never hand-write a code longer than 24 chars.
• Every StateDimension must have values and exactly one is_default=True, or build_combinations raises JourneyCatalogError.
• get_publish_readiness() fails closed: skipped and never-run permutations block publish, and a family with zero permutations blocks publish.
• get_publish_readiness() uses .distinct("permutation_id") (PostgreSQL-only). Do not port these gates to SQLite.
• verify_journey_readiness additionally requires: catalog integrity clean, no warnings, no latest run older than --max-age-hours (default 24), a fresh snapshot, snapshot equal to live values, and no runs recorded after the snapshot.
• record_journey_runs accepts only the field set {permutation_code, status, test_module, test_command, defect_ref, notes, blocks_publish}; unknown keys, duplicate codes, or a non-bool blocks_publish abort the whole batch.

Mandatory startup preflight

1. Confirm the DB is PostgreSQL (topquarks_v01); the readiness gate needs DISTINCT ON.
2. Graph tools (codebase-memory-mcp):
   • list_projects and confirm D-current-code-top-quarks-tqv02_project.
   • index_status; if stale or missing, index_repository with repo_path = "D:/current/code/top-quarks/tqv02_project", mode = "moderate".
   • Prefer search_graph / get_architecture / trace_path / search_code over raw grep for structural questions.
3. Catalog preflight:

   python manage.py seed_journey_catalog --dry-run
   python manage.py verify_journey_catalog

   If the catalog is empty, seed it (see Step 2). verify_journey_catalog without --strict prints warnings for families with no permutations; --strict promotes those to failures.

Step 1: Enumerate routes, edges, and triggers

Build the candidate set from three sources, in order:

1. Graph-first: architecture / routes / dependencies via search_graph and trace_path.
2. Urlconf: tqv02_app/urls.py (namespace tqv02_app) plus tqv02_settings/urls.py for the project-level mounts and the error handlers.
3. Runtime-only edges: template <form action> targets, data-* attributes read by static/js/front.js, and $.ajax() call sites. These carry edges the urlconf cannot show (trigger type, method, expected JSON contract).

Authoritative route surface (regenerate whenever urls.py changes)

Project level (tqv02_settings/urls.py):

• /admin/analytics/ (staff), /admin/ (Django admin + custom actions)
• /ckeditor5/ (editor uploads), /webhooks/stripe/ (system)
• /sitemap.xml, /robots.txt, /jsi18n/, /i18n/setlang/
• custom auth before include('allauth.urls'): /accounts/login/, /accounts/logout/, /accounts/register/, /accounts/register/ajax/, /accounts/password-reset/, reset confirm/done
• /accounts/ (allauth: social login/callback/cancel/error, logged-out)
• /orbit/, /ai-assistant/, /mcp, /__debug__/ (DEBUG only)
• error handlers: handler400 handler403 handler404 handler500 -> utility_views.custom_400/403/404/500; rate-limit renders 429.html via common.rate_limit_response

App level (tqv02_app/urls.py, namespace tqv02_app):

• storefront: home, search, search_autocomplete, set_currency, categories, product_list, product_detail
• reviews: get_reviews, add_review, edit_review, delete_review
• basket: basket, basket_mini, add_to_cart, remove_from_cart, update_cart_quantity, apply_coupon, remove_coupon
• checkout: checkout, create_payment_intent, update_checkout_totals, process_order, order_confirmation, guest_order_track, download_invoice
• wishlist: wishlist, add_to_wishlist, remove_from_wishlist
• account: customer_account, footer_counts, customer_orders, order_detail, customer_addresses, delete_address, payment_methods, add_payment_method, set_default_payment, delete_payment_method, data_export, delete_account
• blog + comments: blog_index, blogs_topics_list, blog_post_detail, add_comment, add_reply, edit_comment, delete_comment, get_comments, get_comment_html, api_get_comments
• chat: customer_service_chat
• static pages: about_us, contact, faq, terms, privacy, shipping, returns
• email lifecycle: email_subscribe, verify_email, resend_verification, unsubscribe
• history: recently_viewed, remove_from_history
• notifications/returns: subscribe_stock_notification, my_returns, request_return, return_confirmation
• health: health_check, readiness_check, liveness_check
• sourcing (staff): generate_purchase_orders, send_purchase_order, fulfill_purchase_order, download_purchase_order

Normalized route inventory record

Produce one row per edge with:

• route pattern, method(s), view dotted path
• trigger type: direct URL | form submit | AJAX ($.ajax) | JS event | email link | webhook | crawler | cron
• mutation flag (read / write) and whether it must call _invalidate_checkout_session(request)
• auth requirement (@login_required? guest-allowed by design?) and role (user / staff)
• rate-limit / CAPTCHA gate (@ratelimit, Turnstile)
• response contract (HTML template name, or JSON keys, or file/CSV/PDF)
• criticality (payment / auth / order / PII = critical or high)
• edge id: route + method + trigger + auth_guard
• mapped JourneyFamily.journey_code (or NEW if it needs a family)

Any edge with no mapped family is a catalog gap: add the family before claiming coverage.

Step 2: Seed and extend the bounded catalog

The seeded catalog currently holds 57 families and 10 state dimensions: J-001 .. J-048 (48 storefront) plus O-001, O-002, O-002b, O-003 .. O-008 (9 support/system, where O-002b is admin CSV exports). Seeding is idempotent and never overwrites operator-edited rows.

Verify the live counts before trusting any number here:

python manage.py seed_journey_catalog --dry-run   # prints Unchanged=<families+dimensions+values>
python manage.py verify_journey_catalog

python manage.py seed_journey_catalog --dry-run
python manage.py seed_journey_catalog
python manage.py seed_journey_catalog --generate-permutations --strategy pairwise
python manage.py seed_journey_catalog --generate-permutations --strategy 3way --max-permutations 110000
python manage.py seed_journey_permutations --family J-029 --strategy 3way --max-permutations 2000 --dry-run

seed_journey_catalog --generate-permutations plans the whole batch before writing and rolls back the family/dimension seed if generation fails, so a budget overflow leaves no partial catalog.

Permutation budget (the default no longer covers 3-way)

The catalog has grown past 100k rows, so --max-permutations needs deliberate sizing. The budget check is limit = max_permutations // len(families), compared against the per-family row count, and it raises as soon as the running total exceeds that limit.

Measured against the live 10 dimensions (auth 3, cart 5, coupon 4, currency 4, locale 3, payment_intent 4, role 2, session_merge 3, stock 2, wishlist 4) and 57 families:

Consequences:

• A full-catalog --strategy 3way run at the default 50000 exits 1 with RESULT: FAIL reason=Permutation budget exceeded; select a family or raise the limit. Pass --max-permutations 110000 for headroom.
• A single-family --strategy 3way run needs --max-permutations >= 1858; the per-family divisor makes a bare --family <code> call use the whole budget as its limit, so 2000 is a safe scoped value.
• Full 3-way is the correct default only for critical packs. Prefer --strategy pairwise (15,960 rows) as the baseline and scope 3-way with --family, per Step 4.

Re-derive these numbers whenever dimensions or values change - do not trust the table blind:

python manage.py seed_journey_permutations --strategy pairwise --max-permutations 110000 --dry-run
python manage.py seed_journey_permutations --strategy 3way --max-permutations 110000 --dry-run

Both print Candidates in bound: <n> without writing, which is the authoritative count.

Regeneration trap: these commands recreate every candidate they are allowed to. Running seed_journey_permutations or seed_journey_catalog --generate-permutations without --risk-tier undoes the pruning policy and re-floods the gate with not_run rows. Always pass --risk-tier critical unless you deliberately want the full cross-product.

Scale note: catalog_findings() evaluates every permutation-level check set-wise in the database, in a fixed 6 queries regardless of catalog size (measured: 0.55s over 106k permutations, ~5s wall for the full verify_journey_catalog command including Django startup). Offender lists are capped at MAX_LISTED_CODES (20) per finding, with an explicit list truncated. line when more exist, so a broken catalog cannot flood the gate output. Both gates are safe to wire into a deploy step.

Keep it that way: never reintroduce a per-permutation Python loop into catalog_findings(). tqv02_app/tests/test_journey_catalog_findings_scale.py pins the query count with assertNumQueries, so a regression fails the suite rather than silently costing minutes.

Adding a family (do this whenever Step 1 finds an unmapped edge)

Append a tuple to JOURNEY_FAMILIES in tqv02_app/management/commands/seed_journey_catalog.py in the order: (journey_code, actor_class, title, entry_trigger, route_pattern, primary_invariants, risk_tier, category).

• journey_code: keep the J- (storefront) / O- (support+system) prefix, zero-padded, unique, max_length=12. Suffix letters are allowed for insertions (O-002b already exists).
• risk_tier: one of critical, high, medium, low.
• category: storefront or support.
• No en-dashes or em-dashes anywhere in the tuple.
• tqv02_app/tests/test_seed_journey_catalog.py asserts JourneyFamily.objects.count() == len(JOURNEY_FAMILIES), so a new tuple must survive a double-seed run without duplicates.

Known catalog gaps to close for full-surface coverage

These edges exist in the codebase but have no dedicated family yet. Add them (suggested codes) before declaring the inventory complete:

When you add a family, also add the matching regression test module to the journey-to-test map in Step 7.3, or record its permutations as blocked with a reason instead of silently skipped.

Step 3: Build the finite state-machine model

Seeded dimensions (already in STATE_DIMENSIONS)

Recommended additional dimensions (add only with exactly one default)

shipping_tier (below_threshold default / at_threshold / above_threshold), tax_jurisdiction (none default / us_state / intl), address_book (empty default / single / multiple_with_default), payment_method (none default / saved_card / new_card / declined_card), consent (unset default / accepted / rejected), rate_limit (under default / tripped), captcha (disabled default / pass / fail), device (desktop default / mobile_599).

Cost warning: build_combinations is pairwise/3-way over all dimensions, and the per-family limit is max_permutations // len(families). Adding a dimension is not free at the current scale - the live 10 dimensions already produce 280 pairwise / 1,858 3-way rows per family (15,960 / 105,906 across 57 families). Rows are default-filled, so growth is roughly quadratic (pairwise) and cubic (3-way) in the number of dimensions, not exponential: a measured 11th dimension with 4 values takes 3-way to 2,698 per family (153,786 total) and pairwise to 355 per family (20,235 total).

Add dimensions one at a time, and always run seed_journey_permutations --dry-run first to read Candidates in bound: <n> before writing anything. See the budget table in Step 2.

Represent, for each transition: states (nodes), actions/events (edges), guards (preconditions), effects (expected state delta). Keep the model finite and explicit; never expand over unbounded product/session permutations.

tqv02-specific guards you must model explicitly

• Cart duality: anonymous -> session["basket"] dict; authenticated -> Basket rows. unique_together = ['user', 'product', 'variant']; quantity capped at 99.
• Variant keys: "{product_id}" simple, "{product_id}:variant:{variant_id}" variant.
• remove_from_cart / update_cart_quantity take AllProduct.product_id, not Basket.basket_id.
• remove_from_wishlist takes the wishlist item id, not a product id.
• Money units: catalogue fields are integer dollars; Order / OrderItem / Payment / Coupon are cents; conversion only through tqv02_app/services/money.py.
• Post-login redirect funnels through TQAccountAdapter.get_login_redirect_url(); the guest cart is auto-merged into the DB ("Keep All") - there is no cart_merge_prompt.
• Any cart mutation must call _invalidate_checkout_session(request).
• Session keys in play: basket, checkout_email, checkout_login_email, checkout_redirect, checkout_snapshot, checkout_payment_intent_id, last_order_number.

Step 4: Define the bounded exhaustive strategy

Layered bounds:

1. Pairwise coverage across all state dimensions (baseline, --strategy pairwise, 15,960 rows - fits the default budget).
2. Targeted 3-way for critical flows (--strategy 3way --family <code> --max-permutations 2000; full-catalog 3-way needs --max-permutations 110000 and yields 105,906 rows):
   • auth + session_merge + cart
   • coupon + shipping_tier + cart total
   • locale + currency + checkout summary
   • payment_intent + process_order + webhook side effects
   • auth + role + admin export
   • stock + variant + process_order
3. Depth-limited traversal: default depth 6, depth 8 for critical packs.
4. Neighbor replay budget on failure: replay the same edge with alternate guard outcomes.
5. Deterministic fixtures and seeds. For parallel-only or order-sensitive regressions use Django's built-in --shuffle [SEED] runner before reaching for any external random-order tool.
6. Record the budget you used (--max-permutations) and everything it cut.

Always report what was out of bound and why.

Step 5: Run dynamic simulation

Three execution layers:

1. Django test client for deterministic backend transitions and DB assertions (primary layer).
2. Browser automation (Playwright preferred, Selenium acceptable) only for UX/runtime contracts the test client cannot observe: JS-driven qty spinners, mini-cart hover, variant selector state, consent banner, 44x44 touch targets.
3. Direct API checks for JSON contract consistency on the AJAX endpoints.

Fixture discipline:

• Use tqv02_app/tests/factories.py / factories_fb.py for domain objects and tqv02_app/tests/journey_fixtures.py::JourneyFixtureMixin for catalog objects.
• Deterministic prices, stock, and coupon rules; no random without a fixed seed.
• Mock external APIs at the service boundary: unittest.mock.patch('tqv02_app.services.payments.stripe'). Never hit live Stripe.
• Stripe test cards: success 4242 4242 4242 4242, 3DS 4000 0027 6000 3184, declined 4000 0000 0000 9995.
• Orbit is DISABLED in tqv02_settings/test_settings.py. Do not re-enable it for a journey run.
• Any test that POSTs set_language MUST call translation.deactivate() in tearDown.

Step 6: Enforce invariants at every step

Assert on each transition. A violated invariant is a failed path, not a warning.

I1 HTTP and routing

Status code, redirect chain and final URL, method guards (@require_POST), and that remove_from_cart / update_cart_quantity reject non-POST where declared.

I2 Response contract

Template marker presence for HTML; for AJAX, success: bool always present, error responses carry an explicit non-200 status= (400/401/403/422), and endpoint-specific keys are present: add_to_cart -> created, quantity, product, wishlist_removed; update_cart_quantity -> quantity, item_subtotal, removed; basket_mini -> html, count, total, items; add_to_wishlist -> created.

I3 Database state

Creates/updates/deletes and counters; get_or_create semantics honoured (no duplicate Basket rows); Order / OrderItem / Payment written exactly once; stock decremented exactly once.

I4 Side effects

Emails (count + recipient + subject + locale), notifications, merge behaviour, session key deltas, cache deltas, ProcessedStripeEvent dedupe rows, RefundAudit written before stripe.Refund.create.

I5 Security

Route protection (@login_required, @staff_member_required), CSRF on POST, webhook signature verified before any DB write, no mark_safe on user content, rate-limit and Turnstile gates active where declared, no secret leakage in logs or responses.

I6 i18n

Active-locale output consistency; gettext_lazy at module level and gettext at runtime; breadcrumb labels use runtime gettext; locked terms respected (es cesta, fr panier); French NBSP before : ; ! ? % and decimal comma; no en-dashes or em-dashes.

I7 Money and pricing

Subtotal / shipping / discount / tax / total arithmetic; unit discipline (dollars vs cents) with conversion only in services/money.py; zero-decimal currency handling for JPY (no * 100); stripe.PaymentIntent(amount=) is an int in cents; idempotency_key= derived from (user.id or session_key, cart_hash, currency, amount_cents), never a per-call UUID.

I8 Cross-surface parity

The same numbers must appear in: endpoint JSON, basket_mini html, consolidated_css_context (basket_count, basket_total), navbar badge, basket page, checkout summary, and /account/footer-counts/. basket_total is pre-formatted, so never prepend a second $.

I9 Idempotency and replay

Repeat mutation calls do not corrupt state: duplicate process_order with the same PaymentIntent id is a no-op; duplicate Stripe events are ignored via ProcessedStripeEvent; seed commands re-run without duplicates.

I10 Accessibility and responsive

44x44px minimum touch targets, keyboard reachability of variant selectors and qty spinners, single mobile breakpoint at <= 599.98px, out-of-stock affordances non-interactive.

Step 7: Defect remediation loop

For each failed invariant:

1. Capture a minimal reproduction path (state vector + action sequence + permutation code).
2. Patch the root cause with the smallest safe change.
3. Add or extend regression tests for the failing edge and one neighbour edge.
4. Replay the failing path and the impacted neighbourhood.
5. Record the outcome with record_journey_run (Step 8): fail + --defect-ref + --blocks-publish while open, then pass after the fix and replay.
6. Mark status: fixed, blocked, or deferred-with-risk.

Cap at 3 fix attempts per defect before escalating as blocked. Never silently relax an assertion to make a test pass. If you find a pre-existing violation outside the current task, add a # SECURITY: or # BUG: TODO with file:line and surface it at the end of the turn instead of drive-by fixing.

Step 7.1: Ranked change-safety checklist (hotspot-aware)

1. Highest risk: checkout finalization - tqv02_app/views/basket_views.py::process_order. Always test: guest/auth submit, missing PI, duplicate PI, non-succeeded PI, idempotent re-submit, snapshot/intent mismatch, stock decrement, oversell guard.
2. High risk: coupon validation and discount math - tqv02_app/models/coupon.py::{validate_coupon,calculate_discount}. Always test: percentage / fixed / free-shipping / BOGO branches, usage caps, min-order, first-order, guest-email caps, bounds and rounding.
3. High risk: checkout totals and Stripe amount composition - tqv02_app/views/basket_views.py::{create_payment_intent,update_checkout_totals,apply_coupon}. Always test: cross-surface parity, FX conversion and currency exponents, PI reuse/cancel paths, idempotency key stability.
4. Medium-high risk: social/auth merge handoff - tqv02_app/allauth_adapter.py::{pre_login,get_login_redirect_url,pre_social_login}. Always test: session snapshot persistence, existing-email social linking, merge prompt vs account redirect branches, login(..., backend='django.contrib.auth.backends.ModelBackend').
5. Medium risk: admin exports/actions - tqv02_app/admin.py::{export_orders_csv,export_users_csv,export_products_csv}. Always test: CSV schema/headers, guest/auth row variants, staff-only visibility, translated labels.

If any item in a touched area fails, treat it as a hard defect and run the remediation loop.

Step 7.2: Standard one-command gate profiles

Fast gate (targeted hotspot smoke)

python manage.py test tqv02_app.tests.test_views_basket_internal_helpers tqv02_app.tests.test_allauth_regressions tqv02_app.tests.test_coupons tqv02_app.tests.test_tax_shipping tqv02_app.tests.test_multicurrency tqv02_app.tests.test_webhooks tqv02_app.tests.test_views_social_auth tqv02_app.tests.test_admin_views --settings=tqv02_settings.test_settings --keepdb --failfast

Medium gate (hotspot regression suite)

python manage.py test tqv02_app.tests.test_views_basket tqv02_app.tests.test_views_basket_pass3 tqv02_app.tests.test_coupons tqv02_app.tests.test_coupon_model_pass3 tqv02_app.tests.test_tax_shipping tqv02_app.tests.test_multicurrency tqv02_app.tests.test_ui_state_sync_matrix tqv02_app.tests.test_allauth tqv02_app.tests.test_allauth_regressions tqv02_app.tests.test_views_social_auth tqv02_app.tests.test_webhooks tqv02_app.tests.test_webhook_views_pass3 tqv02_app.tests.test_admin_views tqv02_app.tests.test_admin_pass3 --settings=tqv02_settings.test_settings --keepdb --parallel=8

Journey-catalog gate (always run when the catalog or its commands changed)

python manage.py test tqv02_app.tests.test_seed_journey_catalog tqv02_app.tests.test_seed_journey_permutations tqv02_app.tests.test_services_journey tqv02_app.tests.test_services_journey_catalog tqv02_app.tests.test_record_journey_run tqv02_app.tests.test_record_journey_runs tqv02_app.tests.test_verify_journey_catalog tqv02_app.tests.test_verify_journey_readiness tqv02_app.tests.test_command_generate_journey_run_report tqv02_app.tests.test_command_journey_report_filters tqv02_app.tests.test_journey_catalog_findings_scale tqv02_app.tests.test_prune_journey_permutations --settings=tqv02_settings.test_settings --keepdb --parallel=8

Full gate (pre-merge high confidence)

python manage.py test tqv02_app.tests --settings=tqv02_settings.test_settings --keepdb --parallel=8

Area-specific quick gates

• Checkout/payment path:

python manage.py test tqv02_app.tests.test_views_basket tqv02_app.tests.test_views_basket_pass3 tqv02_app.tests.test_webhooks tqv02_app.tests.test_webhook_views_pass3 tqv02_app.tests.test_multicurrency tqv02_app.tests.test_stock_decrement tqv02_app.tests.test_checkout_addresses --settings=tqv02_settings.test_settings --keepdb --failfast

• Coupon/tax/currency path:

python manage.py test tqv02_app.tests.test_coupons tqv02_app.tests.test_coupon_model_pass3 tqv02_app.tests.test_tax_shipping tqv02_app.tests.test_multicurrency tqv02_app.tests.test_currency_switching_effects tqv02_app.tests.test_pricing_properties tqv02_app.tests.test_money_and_composition_properties tqv02_app.tests.test_ui_state_sync_matrix --settings=tqv02_settings.test_settings --keepdb --failfast

• Auth/social merge path:

python manage.py test tqv02_app.tests.test_allauth tqv02_app.tests.test_allauth_regressions tqv02_app.tests.test_views_social_auth tqv02_app.tests.test_guest_auth_matrix --settings=tqv02_settings.test_settings --keepdb --failfast

• Admin exports/actions path:

python manage.py test tqv02_app.tests.test_admin_views tqv02_app.tests.test_admin_pass3 tqv02_app.tests.test_admin_consolidation tqv02_app.tests.test_i18n_phase9b_admin_catalog --settings=tqv02_settings.test_settings --keepdb --failfast

• Abuse/security gates path:

python manage.py test tqv02_app.tests.test_rate_limiting tqv02_app.tests.test_captcha tqv02_app.tests.test_validate_turnstile tqv02_app.tests.test_security tqv02_app.tests.test_settings_hardening tqv02_app.tests.test_sanitize_comment_html --settings=tqv02_settings.test_settings --keepdb --failfast

• i18n/locale path:

python manage.py test tqv02_app.tests.test_i18n_phase3 tqv02_app.tests.test_i18n_phase10_db_translation tqv02_app.tests.test_i18n_phase12 tqv02_app.tests.test_i18n_phase13_seo tqv02_app.tests.test_i18n_phase13_seo_fr tqv02_app.tests.test_i18n_phase15_fr_switcher tqv02_app.tests.test_translation_service_coverage tqv02_app.tests.test_o007_jsi18n_catalog --settings=tqv02_settings.test_settings --keepdb --failfast

Step 7.3: Journey family to test-module map

Use this to pick the evidence module recorded in JourneyRun.test_module. If a family has no module, that is a coverage gap: create the module or record blocked with a reason.

Step 8: Record results and gate publish readiness

Record every executed permutation. Untested and skipped permutations fail the gate, so silence is never neutral.

Single result:

python manage.py record_journey_run J-018-a1b2c3d4e5f pass --test-module tqv02_app.tests.test_views_basket --test-command "python manage.py test tqv02_app.tests.test_views_basket --settings=tqv02_settings.test_settings --keepdb"
python manage.py record_journey_run J-029-9f8e7d6c5b4 fail --defect-ref BUG-142 --blocks-publish --test-module tqv02_app.tests.test_views_basket --notes "stale PI reuse regression"
python manage.py record_journey_run J-006-1122334455a pass --dry-run

Batch import (preferred for a full simulation pass; one snapshot for the whole batch, all-or-nothing):

python manage.py record_journey_runs tests_artifacts/journey_runs.json --dry-run
python manage.py record_journey_runs tests_artifacts/journey_runs.json

tests_artifacts/journey_runs.json shape:

[
  {
    "permutation_code": "J-018-a1b2c3d4e5f",
    "status": "pass",
    "test_module": "tqv02_app.tests.test_views_basket",
    "test_command": "python manage.py test tqv02_app.tests.test_views_basket --settings=tqv02_settings.test_settings --keepdb",
    "defect_ref": "",
    "notes": "",
    "blocks_publish": false
  }
]

Gate and report:

python manage.py verify_journey_catalog --strict
python manage.py verify_journey_readiness --max-age-hours 24
python manage.py generate_journey_run_report --dry-run
python manage.py generate_journey_run_report

generate_journey_run_report writes misc/manual/reports/user-journey-run-ledger.html by default. All of these commands print RESULT: OK or RESULT: FAIL reason=<short> and exit 0 / 1, so they compose into a deploy gate.

Readiness interpretation:

• is_publishable is True only when every permutation's latest run is pass and every family has at least one permutation.
• A fail / blocked run with blocks_publish=True increments open_blocking_defects.
• readiness_score is the percentage of permutations whose latest run is pass.
• verify_journey_readiness also fails on stale evidence: run it in the same session as the tests, or raise --max-age-hours deliberately and say so in the report.

Step 8.5: Maximum-work run recipe and where the reports land

Invoke the skill with an explicit scope and bound, for example:

Run user-journey-simulation. Full storefront + checkout + account scope, pairwise baseline, 3-way on the critical packs, execute the full gate, record every result, regenerate the ledger.

The full ladder, in order

# 0. Preflight - catalog exists and is internally consistent (~5s)
python manage.py seed_journey_catalog
python manage.py verify_journey_catalog --strict

# 1. Candidates for critical families only (policy: not_run rows stay scoped)
python manage.py seed_journey_permutations --risk-tier critical --strategy pairwise --dry-run
python manage.py seed_journey_permutations --risk-tier critical --strategy pairwise

# 2. Deepen an individual critical family (1,858 rows each)
python manage.py seed_journey_permutations --risk-tier critical --family J-029 --strategy 3way --max-permutations 2000

# 3. Execute the evidence (this is the actual work - hours, not seconds)
python manage.py test tqv02_app.tests --settings=tqv02_settings.test_settings --keepdb --parallel=8

# 4. Record results as a single atomic batch + one snapshot
python manage.py record_journey_runs tests_artifacts/journey_runs.json --dry-run
python manage.py record_journey_runs tests_artifacts/journey_runs.json

# 5. Gate and publish the ledger
python manage.py verify_journey_readiness --max-age-hours 24
python manage.py generate_journey_run_report

Steps 3 and 4 are where the effort lives. Steps 0, 1, 2, and 5 are fast bookkeeping.

Reading the outputs

Serve the manual locally if you prefer HTTP over file://:

python manage.py runserver_quiet
# then browse to the report path under /media/ or open the file directly

Scoping the ledger

generate_journey_run_report renders one table row per permutation, so it caps output at --limit 2000 by default and prints a warning when it truncates. Scope it instead of dumping everything:

python manage.py generate_journey_run_report --family J-029 --family O-004
python manage.py generate_journey_run_report --status fail --status blocked
python manage.py generate_journey_run_report --status not_run --limit 50
python manage.py generate_journey_run_report --limit 0    # no cap; 15,960 rows = 5.5 MB, ~17s
python manage.py generate_journey_run_report --output tests_artifacts/scratch.html

• --family and --status are repeatable; --status not_run selects never-executed permutations.
• An unknown --family exits 1 rather than silently producing an empty table.
• Readiness KPIs are always catalog-wide. Filtering changes only the ledger table, so a scoped report can never make the catalog look healthier than it is. The HTML carries a Scoped ledger: showing N of M banner whenever a filter or cap is in effect.

Right-sizing the catalog

Permutation counts are candidates, not evidence. Generating candidates is cheap; executing them is not, and every unexecuted candidate fails the readiness gate as not_run. Keep the catalog to what you can actually execute:

• pairwise across all 57 families = 15,960 candidates (the current, recommended baseline),
• pairwise on the 8 risk-prioritized packs = a few thousand,
• 3-way reserved for the handful of critical families.

Policy: unexecuted candidates only for critical families

An unexecuted candidate is a not_run row. It has exactly one use: failing the readiness gate closed so an untested catalog cannot look healthy. It contributes nothing to the ledger, where it renders as an identical "No run recorded" row.

The standing policy is therefore: carry not_run rows only for critical families. Everywhere else the catalog holds just the permutations that have real evidence.

Generate within the policy:

python manage.py seed_journey_permutations --risk-tier critical --strategy pairwise
python manage.py seed_journey_permutations --risk-tier critical --family J-029 --strategy 3way --max-permutations 2000

--risk-tier is repeatable and filters which families gain candidates at all. Without it, seed_journey_permutations regenerates the full cross-product and re-floods the gate.

Enforce the policy on an existing catalog:

python manage.py prune_journey_permutations --keep-unexecuted-tier critical --dry-run
python manage.py prune_journey_permutations --keep-unexecuted-tier critical

Other pruning modes:

python manage.py prune_journey_permutations --keep-per-family 280
python manage.py prune_journey_permutations --family J-029 --keep-per-family 100

Guarantees, all test-pinned:

• Only permutations with no JourneyRun history are ever deleted; evidence always survives.
• Executed permutations count against the per-family allowance.
• A family is never emptied. Pruning always leaves at least one candidate, because a family with zero permutations is an uncovered family and a hard readiness failure.
• One transaction: an interrupt rolls back with no partial state.

Current shape after applying the policy:

Total 3,441 permutations, 186 runs, readiness_score 5.41%, uncovered_families 0. The full ledger renders uncapped in ~7s at 1.25 MB.

History: the catalog was generated at full 3-way (106,092 candidates against 186 runs), which no gate could ever turn green. It was pruned to the 15,960 pairwise baseline, then to 3,441 under this policy, with all 186 runs intact throughout.

Step 9: Bounded exhaustive exploration strategy

Use bounded search rather than infinite path expansion:

1. Depth-limited BFS or DFS (default depth 4-6 unless overridden).
2. Pairwise or reduced combinatorics across state dimensions; 3-way only for critical packs.
3. Risk-weighted prioritization for high-impact edges first:
   • payment / order / auth transitions
   • session-to-auth merge
   • coupon invalidation and shipping-tier crossings
   • stock decrement and oversell
   • PII export and account deletion
4. Always report unvisited but in-scope edges when bounds cut them off.

Risk-prioritized packs (execute in this order when in scope)

1. Checkout and payment intent pack (J-026..J-032, O-004, proposed J-057).
2. Auth and cart merge pack (J-009..J-017, J-025).
3. Coupon and shipping-threshold pack (J-022, J-023, J-027).
4. Cart lifecycle and cross-surface counter pack (J-018..J-024, J-033..J-035, J-040).
5. Locale and currency pricing pack (J-006, J-007, O-007).
6. PII and account-lifecycle pack (J-042..J-045).
7. Staff and system pack (O-001..O-003, O-005, O-006, O-008).
8. Abuse and resilience pack (J-010, J-012, proposed J-054, J-055).

Output contract

Return these artifacts:

1. Route inventory and transition catalog (with an explicit unmapped-edge list).
2. State-machine summary: dimensions, values, guards, bounds, and the exact --strategy / --max-permutations used.
3. Executed path matrix with pass/fail by invariant class I1..I10.
4. Defects found with reproduction path, permutation code, fix status, and regression test links.
5. Coverage summary: visited states, visited edges, skipped edges with reason.
6. Recorded-evidence summary: record_journey_run(s) invocations, resulting PublishReadinessSnapshot values, and the verify_journey_readiness outcome.
7. Follow-up recommendations ordered by risk.

Report metrics (required)

• total families in catalog / families with at least one permutation
• total permutations in bound / visited permutations
• total edges in bound / visited edges
• pairwise combination coverage percentage
• critical-edge coverage percentage
• invariant failures by class (I1..I10)
• defects fixed vs blocked vs deferred
• readiness_score, open_blocking_defects, is_publishable
• unvisited in-scope edges, each with the bound that cut it

Hard constraints

1. Never claim full-path exhaustion over an unbounded state space.
2. Always disclose coverage bounds and skipped edges.
3. Treat invariant failures as hard defects, never warnings.
4. Prefer deterministic fixtures and reproducible seeds.
5. Do not skip remediation for an in-scope, fixable defect.
6. Do not silently relax assertions to make tests pass.
7. Do not mark a permutation pass without an executed command recorded in test_command.
8. Do not re-enable Orbit in test settings to make a journey run.
9. Never hit live Stripe, live email, or production data from a simulation run.
10. Commit with .\gc.cmd -m "msg", never raw git commit.

Definition of done

1. Route candidates are enumerated, normalized, and every edge maps to a JourneyFamily.
2. A finite state machine was built, documented, and seeded into the catalog.
3. Dynamic simulations executed with an explicit bounded strategy.
4. Invariants I1..I10 enforced on each executed step.
5. In-scope defects were fixed with regression tests or documented as blocked.
6. Every executed permutation has a JourneyRun row; verify_journey_catalog --strict and verify_journey_readiness were run and their output reported.
7. The HTML run ledger was regenerated when results changed.
8. Results include coverage gaps and risk-ranked next actions.

Troubleshooting (observed failure modes)

Related skills and agents

• .github/agents/user-journey-simulator.agent.md - the agent persona that drives this skill.
• .github/prompts/simulate-user-journeys.prompt.md - one-shot invocation prompt.
• ui-state-sync-tests - cross-surface counter/total parity (invariant class I8).
• stripe-payments-expert - PaymentIntent, webhook, and refund specifics (I7, I4).
• currency-types-ecommerce-expert - money units and zero-decimal currencies (I7).
• i18n-workflow - locale invariants and .po regeneration (I6).
• pa-deploy-safety - deploy gating once readiness is green.
• performance-auditor - when a journey exposes an N+1 or slow path rather than a correctness defect.