From cd5ea68fe3cd22c94bad061746e55a35fd5bf92c Mon Sep 17 00:00:00 2001
From: "russell@unturf.com" <russell@unturf.com>
Date: Sat, 16 May 2026 09:39:17 -0400
Subject: [PATCH] =?UTF-8?q?fix:=20MPS-24=20Phase=202.8c=20=E2=80=94=20cach?=
 =?UTF-8?q?e-bust=20ALL=20static=20JS=20(THE=20root=20cause)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

THE root cause of the entire 'still reloads / still not working' saga
across 2.7 -> 2.8 -> 2.8b: shop_tags.j2 (tag_bulk.js) and
product_edit.j2 (product_tags.js) loaded their <script> WITHOUT the
?v={{ request.git_hash }} cache-bust. routes.py serves /static with
cache_max_age=3600, so the operator's browser kept the STALE JS for up
to an hour after every deploy — the new SPA code never executed, forms
fell back to native submit = full page reload, every time. Server-side
functional tests passed throughout because they have no browser cache.

Fix: append ?v={{ request.git_hash }} to EVERY static <script> include
(the established base.j2 / offer.js / pay-countdown.js convention) —
not just the two at fault but the whole latent class: tag_bulk,
product_tags, tag_filter, auction, player, sandbox, watch, signals,
comments, shop-settings. request.git_hash shifts every deploy -> URL
changes -> fresh fetch, no hard-refresh ever needed again.

Gate (must be empty):
  grep -rnE '<script src="/static/js/[^"?]+\.js"' make_post_sell/templates/

The 2.8/2.8b JS (onTagFormClick unified click handler, AJAX focus,
drag-to-reorder) stands — it just was never being fetched by the
browser. 1131 tests pass. Docs: mps-24.md Phase 2.8c, CLAUDE.md
(new mandatory cache-bust convention section).
---
 CLAUDE.md                                     | 17 +++++++++++++++++
 docs/tickets/mps-24.md                        | 16 ++++++++++++++++
 make_post_sell/templates/auction.j2           |  2 +-
 make_post_sell/templates/base.j2              |  2 +-
 make_post_sell/templates/content.j2           |  4 ++--
 make_post_sell/templates/home.j2              |  2 +-
 make_post_sell/templates/player.j2            |  2 +-
 make_post_sell/templates/product.j2           |  4 ++--
 make_post_sell/templates/product_edit.j2      |  2 +-
 make_post_sell/templates/shop.j2              |  2 +-
 make_post_sell/templates/shop_settings.j2     |  2 +-
 make_post_sell/templates/shop_tags.j2         |  2 +-
 make_post_sell/templates/snippets/comments.j2 |  2 +-
 13 files changed, 46 insertions(+), 13 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7cbe2c7..ae827ac 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -379,6 +379,23 @@ new comment into our DOM without a page reload (preserving media playback).
 Our server returns JSON (HTTP 201) for AJAX requests and falls back to our
 normal redirect flow on any error.
 
+## Static Asset Cache-Busting (MANDATORY)
+
+**Every `<script src="/static/...">` and `<link href="/static/...">` MUST
+end with `?v={{ request.git_hash }}`.** `routes.py` serves `/static` with
+`cache_max_age=3600`, so an un-versioned asset is cached by the browser
+for up to an hour — meaning a deploy that changes that JS/CSS is
+**invisible to users for up to an hour**. This manifests as "the new
+feature doesn't work / the SPA still full-reloads" even though the deploy
+landed and server-side tests pass (tests have no browser cache). This was
+the root cause of the entire MPS-24 tag-SPA debugging saga (5+ deploys).
+`request.git_hash` is a reified request method that shifts every deploy →
+URL changes → fresh fetch, no hard-refresh ever needed. Gate before
+commit (must be empty):
+```
+grep -rnE '<script src="/static/js/[^"?]+\.js"' make_post_sell/templates/
+```
+
 ## CI/CD Notes
 
 - Build uses `virtualenv-clone` which requires `bin/python` symlink (Python 3.12 `venv` may only create `python3`)
diff --git a/docs/tickets/mps-24.md b/docs/tickets/mps-24.md
index fa1907f..1161a7f 100644
--- a/docs/tickets/mps-24.md
+++ b/docs/tickets/mps-24.md
@@ -363,6 +363,22 @@ Tests (`test_functional.py::TestProductTagsSpa`):
 Deferred (occasional click, not the hot path): AJAX-ifying the
 "Suggest categories" link — still a full navigation by design.
 
+**Phase 2.8c — THE root cause** (shipped 2026-05-16): every "still
+reloads / still not working" report across 2.7 → 2.8 → 2.8b was the
+**same defect** — `shop_tags.j2` (`tag_bulk.js`) and `product_edit.j2`
+(`product_tags.js`) loaded their `<script>` **without**
+`?v={{ request.git_hash }}`. `/static` is served
+`cache_max_age=3600`, so the operator's browser kept the stale JS for
+up to an hour after every deploy: the new SPA code never ran, forms
+fell back to native submit = full reload, every time — while
+JS-blind server tests passed. Fix: append `?v={{ request.git_hash }}`
+to **all** static `<script>` includes (the existing `base.j2` /
+`offer.js` convention), not just the two — same latent bug class
+across `tag_filter`, `auction`, `player`, `sandbox`, `watch`,
+`signals`, `comments`, `shop-settings`. Grep gate:
+`grep -rnE '<script src="/static/js/[^"?]+\.js"' templates/` must be
+empty. (The 2.8/2.8b JS work stands; it just was never being fetched.)
+
 **Phase 2.8b** (shipped 2026-05-16): the generic `data-tag-form`
 **`submit`-event** interception proved unreliable in the field —
 operator reported Add / Delete / reorder *all* still full-reloaded
diff --git a/make_post_sell/templates/auction.j2 b/make_post_sell/templates/auction.j2
index 9021fee..25f0ae9 100644
--- a/make_post_sell/templates/auction.j2
+++ b/make_post_sell/templates/auction.j2
@@ -102,5 +102,5 @@
 
 </section>
 
-<script src="/static/js/auction.js"></script>
+<script src="/static/js/auction.js?v={{ request.git_hash }}"></script>
 {% endblock %}
diff --git a/make_post_sell/templates/base.j2 b/make_post_sell/templates/base.j2
index 8b25036..74a7b80 100644
--- a/make_post_sell/templates/base.j2
+++ b/make_post_sell/templates/base.j2
@@ -251,7 +251,7 @@
     <div id="sandbox-actions" class="sandbox-actions"></div>
   </div>
 </div>
-<script src="/static/js/sandbox.js"></script>
+<script src="/static/js/sandbox.js?v={{ request.git_hash }}"></script>
 {% endif %}
 
 </body>
diff --git a/make_post_sell/templates/content.j2 b/make_post_sell/templates/content.j2
index 5e3821d..6df63c9 100644
--- a/make_post_sell/templates/content.j2
+++ b/make_post_sell/templates/content.j2
@@ -204,8 +204,8 @@ function playInline(container, videoUrl) {
 }
 </script>
 {% if request.shop.watch_mode_enabled %}
-<script src="/static/js/watch.js"></script>
+<script src="/static/js/watch.js?v={{ request.git_hash }}"></script>
 {% endif %}
-<script src="/static/js/signals.js"></script>
+<script src="/static/js/signals.js?v={{ request.git_hash }}"></script>
 
 {%- endblock -%}
diff --git a/make_post_sell/templates/home.j2 b/make_post_sell/templates/home.j2
index 5dfee8e..4974c91 100644
--- a/make_post_sell/templates/home.j2
+++ b/make_post_sell/templates/home.j2
@@ -244,7 +244,7 @@
   </section>
   {% endif %}
 
-  <script src="/static/js/tag_filter.js" defer></script>
+  <script src="/static/js/tag_filter.js?v={{ request.git_hash }}" defer></script>
 
 {% endif %}
 
diff --git a/make_post_sell/templates/player.j2 b/make_post_sell/templates/player.j2
index cda7e8d..e8a47f6 100644
--- a/make_post_sell/templates/player.j2
+++ b/make_post_sell/templates/player.j2
@@ -246,7 +246,7 @@
     </div>
   </div>
 
-  <script src="/static/js/player.js"></script>
+  <script src="/static/js/player.js?v={{ request.git_hash }}"></script>
   <script>
     // Pass navigation data to player.js
     window.playerData = {
diff --git a/make_post_sell/templates/product.j2 b/make_post_sell/templates/product.j2
index 1eb9c2a..c33d4af 100644
--- a/make_post_sell/templates/product.j2
+++ b/make_post_sell/templates/product.j2
@@ -374,8 +374,8 @@ function playInline(container, videoUrl) {
 }
 </script>
 {% if request.shop.watch_mode_enabled %}
-<script src="/static/js/watch.js"></script>
+<script src="/static/js/watch.js?v={{ request.git_hash }}"></script>
 {% endif %}
-<script src="/static/js/signals.js"></script>
+<script src="/static/js/signals.js?v={{ request.git_hash }}"></script>
 
 {%- endblock -%}
diff --git a/make_post_sell/templates/product_edit.j2 b/make_post_sell/templates/product_edit.j2
index 3a96f63..4a4d287 100644
--- a/make_post_sell/templates/product_edit.j2
+++ b/make_post_sell/templates/product_edit.j2
@@ -630,6 +630,6 @@
 
 </div>
 
-<script src="/static/js/product_tags.js" defer></script>
+<script src="/static/js/product_tags.js?v={{ request.git_hash }}" defer></script>
 
 {%- endblock -%}
diff --git a/make_post_sell/templates/shop.j2 b/make_post_sell/templates/shop.j2
index 9247bd1..502696f 100644
--- a/make_post_sell/templates/shop.j2
+++ b/make_post_sell/templates/shop.j2
@@ -147,6 +147,6 @@
 </div> {# /.tag-detail-layout #}
 {% endif %}
 
-<script src="/static/js/tag_filter.js" defer></script>
+<script src="/static/js/tag_filter.js?v={{ request.git_hash }}" defer></script>
 
 {%- endblock -%}
diff --git a/make_post_sell/templates/shop_settings.j2 b/make_post_sell/templates/shop_settings.j2
index b0f1bdc..98e65e8 100644
--- a/make_post_sell/templates/shop_settings.j2
+++ b/make_post_sell/templates/shop_settings.j2
@@ -1628,7 +1628,7 @@ function toggleCryptoWallets() {
     timer = setInterval(poll, 4000);
 })();
 </script>
-<script src="/static/js/shop-settings.js"></script>
+<script src="/static/js/shop-settings.js?v={{ request.git_hash }}"></script>
 
 {%- endblock -%}
 
diff --git a/make_post_sell/templates/shop_tags.j2 b/make_post_sell/templates/shop_tags.j2
index ffb802a..5f9ce19 100644
--- a/make_post_sell/templates/shop_tags.j2
+++ b/make_post_sell/templates/shop_tags.j2
@@ -174,6 +174,6 @@
   </ul>
 </section>
 
-<script src="/static/js/tag_bulk.js" defer></script>
+<script src="/static/js/tag_bulk.js?v={{ request.git_hash }}" defer></script>
 
 {%- endblock -%}
diff --git a/make_post_sell/templates/snippets/comments.j2 b/make_post_sell/templates/snippets/comments.j2
index 4af6d24..cf1f66c 100644
--- a/make_post_sell/templates/snippets/comments.j2
+++ b/make_post_sell/templates/snippets/comments.j2
@@ -133,5 +133,5 @@
         </div>
     {% endif %}
 </div>
-<script src="/static/js/comments.js"></script>
+<script src="/static/js/comments.js?v={{ request.git_hash }}"></script>
 {% endif %}