AGENTS: deleting a file does not un-publish it

[mmcky]

Adds a fourth ordering trap alongside the existing three.

The current third rule — "repoint, publish, then delete — the published site lags main" — gets the ordering right, but it implies the delete step takes effect once it merges and a publish follows. It does not.

The mechanism

ci.yml and publish.yml in lecture-python.myst both restore the build-cache artifact produced by cache.yml, then build over it. Sphinx copies html_static_path into _build/html/_static but never prunes assets that have since been removed from source, so a deleted _static file survives in the restored tree and gets deployed again.

Only cache.yml builds from a clean checkout, and it runs weekly (cron: '0 3 * * 1'). A deletion merged on a Tuesday therefore keeps being served until the following Monday's rebuild and a publish after it.

Measured, not inferred

QuantEcon/lecture-python.myst#1035 deletes five data files. Its Netlify preview served all five at HTTP 200 with the correct content-type and byte count — from a branch that does not contain them:

Probe	Result
deleted path _static/lecture_specific/mle/fp.dta	200 · application/x-stata-dta · 1024085 B · real Stata bytes, incl. the C:\Russian billionaires\AER\fp.dta label
control path that never existed	404 · HTML error page

The control is what makes this evidence rather than a guess: the host discriminates correctly, so the 200 is a genuine served file, not a Netlify SPA-fallback false pass. The build-cache artifact in play was dated 2026-08-10, 272 MB — built while the files still existed.

Why it earns a rule

It is a false completion, not breakage. Files keep resolving, which is strictly safer than the alternative — but the repo, migration.yml and CATALOG.md all read "deleted" while readers still get the old bytes. Anyone checking the work by fetching the published URL sees a 200 and reasonably concludes the deletion failed; anyone checking main sees it gone and reasonably concludes it succeeded. Both are looking at the wrong thing.

Hence the rule's operative half: verify a deletion against the published URL, never against main — and if the window needs closing deliberately, workflow_dispatch cache.yml before tagging the publish. That is a ~1h50m GPU build, which is precisely why the cache exists, so it is a deliberate cost rather than a default.

Scope, deliberately not overstated

The rule names lecture-python.myst because that is where it was measured. Whether the other lecture repos share the pattern — and whether earlier waves' deletions were silently affected — is being established separately; that finding will either widen this rule or confirm it is repo-specific. I would rather land a narrow rule that is true than a general one that is not.

Part of QuantEcon/workspace-lectures#39.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the repository’s contributor/agent guidance (AGENTS.md) by adding a newly discovered “ordering trap” for cross-repo repoints and deletions, clarifying that deleting a file in a lecture repo does not necessarily stop it from being served immediately due to cached build artifacts.

Changes:

• Renames the “Repointing a lecture — three ordering traps” section to “four ordering traps”.
• Adds a new fourth rule documenting how cached _build artifacts can cause deleted _static files to remain published until a clean cache rebuild plus a subsequent publish.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.