>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588788. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Acquia's CDN layer (<code>*.acquia.site</code>) aggressively caches Canvas page HTML and component JS bundles for hours after an upload. All post-upload verification must use the direct CMS URL (<code>*.cms.acquia.site</code>) to avoid false "fix didn't work" conclusions.</p> <p>This gotcha causes an agent to believe a code fix failed when it actually succeeded, leading to unnecessary additional changes that compound the problem. When the CDN is serving stale HTML it may reference an old JS bundle hash that no longer exists on the server, which means the page throws errors on the CDN URL but works perfectly on the CMS URL. In recorded efi-ed sessions this pattern recurred from Q2 through Q3 and was only solved by establishing a consistent discipline: always verify on <code>efi-ed.cms.acquia.site</code>, never on <code>efi-ed.acquia.site</code>. In a jamie-demo session the <code>?nocache=N</code> query-string pattern was used for Varnish cache-busting. Without this discipline written into the skill, each new session starts without it and risks the same false-negative cycle.</p> <p>Root cause: Acquia's CDN layer (Varnish + CloudFront) caches Canvas page HTML and JS bundle URLs aggressively. When <code>canvas:upload</code> succeeds, the new bundle hash is written to the CMS backend, but the CDN continues serving the previous version until its TTL expires &mdash; which can be several hours. The <code>*.cms.acquia.site</code> hostname bypasses the CDN and hits the origin CMS directly, always showing the current version. The <code>?nocache=N</code> query string busts the Varnish cache for per-page Canvas content. Neither workaround is documented in the skill by default.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Make a code change to a Canvas component. Run <code>canvas:upload</code> &mdash; succeeds.</li> <li>Open the public CDN URL (<code>&lt;site&gt;.acquia.site</code>) and verify the change.</li> <li>Observe: the change is not visible. The page may also throw a JS bundle 404 because the cached HTML references an old bundle hash that no longer exists on the server.</li> <li>Open the CMS URL (<code>&lt;site&gt;.cms.acquia.site</code>) for the same page.</li> <li>Observe: the change is visible immediately on the CMS URL.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Document the verification discipline in <code>.claude/skills/migrate-site/SKILL.md</code>, <code>.claude/agents/visual-verifier.md</code>, and <code>docs/migration/gotchas.md</code>. No platform code change is proposed &mdash; the CDN behavior is an Acquia infrastructure decision; the agent must work around it with the correct verification URL and cache-busting query string.</p> <p><strong>Step 1 &mdash; In <code>.claude/skills/migrate-site/SKILL.md</code></strong>, add the following block in the Phase 4 section and again in the Phase 8 visual-verification section:</p> <pre>VERIFICATION DISCIPLINE (mandatory): ALWAYS verify component changes on the CMS direct URL: https://&lt;site&gt;.cms.acquia.site/ NEVER conclude "fix didn't work" based on the CDN URL: https://&lt;site&gt;.acquia.site/ The CDN caches Canvas page HTML and JS bundle URLs for hours after upload. For Canvas page content, append ?nocache=&lt;random_int&gt; to bust Varnish cache.</pre><p><strong>Step 2 &mdash; In <code>.claude/agents/visual-verifier.md</code></strong>, add at the top of the verification protocol:</p> <pre>BROWSER: Always open &lt;site&gt;.cms.acquia.site, not &lt;site&gt;.acquia.site. Append ?nocache=&lt;timestamp&gt; to Canvas page URLs to ensure fresh content.</pre><p><strong>Step 3 &mdash; Add to <code>docs/migration/gotchas.md</code>:</strong> "CDN (<code>*.acquia.site</code>) caches Canvas page HTML for hours after upload. Always verify on <code>*.cms.acquia.site</code> (direct CMS, no CDN). For page content: append <code>?nocache=&lt;N&gt;</code> to bust Varnish."</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the VERIFICATION DISCIPLINE block to <code>.claude/skills/migrate-site/SKILL.md</code> at Phase 4 and Phase 8.</li> <li>Add the verifier protocol line to <code>.claude/agents/visual-verifier.md</code>.</li> <li>Add the gotchas.md entry.</li> <li>Verify: <code>grep -n "cms.acquia.site" .claude/skills/migrate-site/SKILL.md</code> returns at least one result.</li> <li>Verify: <code>grep -n "nocache" .claude/skills/migrate-site/SKILL.md</code> returns at least one result.</li> <li>Verify: <code>grep -n "cms.acquia.site" .claude/agents/visual-verifier.md</code> returns at least one result.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None. Behavioral change in agent verification flow only.</p> <h3 id="summary-api-changes">API changes</h3> <p>None at the platform level. Agents are directed to use the existing <code>*.cms.acquia.site</code> origin hostname and the <code>?nocache=&lt;N&gt;</code> query string &mdash; both already supported by Acquia infrastructure.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None. New documentation only &mdash; SKILL.md/agent file blocks and a gotchas.md entry.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-5-Drupal-Canvas-Gotchas/04-P2-8-cdn-serves-stale-assets.md</code> (id: P2-8)</li> <li>Gotcha catalog: <code>RESEARCH-2026-04-28/07-cross-cutting/acquia-cms-gotchas.md</code> &sect; G3 (verbatim entry)</li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-8</li> <li>Q1 discovery: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q1-records-1-to-2884/issues-found.md</code> Platform Limitation 12</li> <li>Q3 recurrence + discipline: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q3-records-5768-to-8651/issues-found.md</code> Issue #15 and <code>visual-fidelity-iteration-pattern.md</code></li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> &sect; SKILL.md / Verify Always on CMS URL</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is the CMS URL format always <code>*.cms.acquia.site</code> or does it vary by environment? The efi-ed URL was <code>173672-*.cms.acquia.site</code> (with a numeric prefix). Confirm whether the <code>verify-browser-session</code> preflight script already records the correct CMS URL, and reference that variable in the skill block if so.</li> <li>Should the <code>?nocache=&lt;random_int&gt;</code> pattern be automated &mdash; a helper function in <code>scripts/</code> that appends a timestamp &mdash; or is a manual instruction sufficient?</li> </ul>