fix(email): specification.html has drifted from its generator — regeneration would drop hand-edited sections

[itomek]

Problem

The email agent's committed hub/agents/python/email/specification.html carries hand-edited sections (e.g. the #1892 context-window envelope block, the #1889 thread-handling sentence) that its generator hub/agents/python/email/gaia_agent_email/spec_html.py does not produce — a fresh render_endpoint_spec_html() run would silently DROP those sections. Recent PRs matched the established practice of editing both files in parallel, but the generator and the committed artifact have structurally drifted: regeneration is no longer safe.

Outcome

spec_html.py regenerates the committed specification.html faithfully (hand-maintained sections become generator-emitted), or the file is explicitly split into a generated part and a hand-maintained part with a drift guard, so regeneration cannot silently lose documentation.

Acceptance criteria

• Running the generator reproduces the committed specification.html byte-identically (or the split/guard makes the hand-maintained region explicit and protected)
• A test (mirroring the existing committed-artifact drift-test pattern, e.g. the openapi one) fails loudly when the generator and the committed file diverge
• The feat(email): pin the context-window envelope (16K target / 32K max) as a requirement #1892 envelope section and feat(email): long-thread handling via iterative summarization to fit the context budget #1889 thread-handling content survive a regeneration

Scope & expectations

• Where: hub/agents/python/email/gaia_agent_email/spec_html.py, hub/agents/python/email/specification.html, tests in hub/agents/python/email/tests/
• Out of scope: content changes to the spec; openapi.email.json (already generator-guarded)
• Constraints: keep the rendered page's structure/anchors stable (external links may target section ids)

How to verify

Test run output showing the new drift guard passing on the synced pair and failing when either side is edited alone.

[github-actions]

Good news for whoever picks this up: the two files are already in sync — I regenerated the spec and it comes out byte-for-byte identical to the committed specification.html (same MD5). So there are no hand-edited-only sections that a regeneration would silently drop today; acceptance criterion #1 already holds. Heads-up too: the #1892 and #1889 references cited as examples don't actually appear in either file, so those specific pointers look stale — worth double-checking the premise before scoping.

That means the real, still-valid gap is a smaller one: there's no drift-guard test for this pair. The openapi.email.json artifact has exactly the guard this issue wants, but specification.html has nothing equivalent, so the two could silently drift on a future edit even though they happen to match now. The clean fix is to mirror the openapi pattern rather than split the file — since the HTML is 100% generator-produced, no hand-maintained region needs carving out.

🔍 Technical details

Verified in sync (no current drift):

$ md5sum specification.html /tmp/regen.html
e055810c8704a3c576c279874f58f127  specification.html   # committed
e055810c8704a3c576c279874f58f127  /tmp/regen.html      # render_endpoint_spec_html()

Regenerated via gaia_agent_email.spec_html.render_endpoint_spec_html() (spec_html.py:364). diff is empty.

Stale examples: committed specification.html tops out at #1887; the generator source references up to #1795. Neither #1892 (context-window envelope) nor #1889 (thread-handling) appears in either file — so criterion #3's named sections aren't present to protect.

The genuine gap — no guard test. openapi.email.json is guarded by tests/test_rest_contract.py:199 (test_committed_openapi_artifact_is_up_to_date) backed by export_openapi.check_artifact() (export_openapi.py:83). Nothing in tests/ references spec_html / specification.html at all.

Recommended shape (mirror, don't split):

1. Add a check_artifact()-style helper to spec_html.py that renders and compares against the committed specification.html. Note the committed file lives at the package root (hub/agents/python/email/specification.html), whereas write_and_open_spec() currently defaults to ~/.gaia/email/endpoint-spec.html (spec_html.py:985) — the helper needs to point at the committed path explicitly, and a python -m gaia_agent_email.spec_html-style regen entry would make "how do I fix it" obvious in the failure message.
2. Add tests/test_spec_html_artifact.py asserting byte-equality, with a regenerate hint in the assert message (same as the openapi test).

This satisfies all three acceptance criteria: #1 already holds, #3 is moot (no hand-only sections), #2 is the deliverable.

[github-actions]

Opened #2082 with a fix.

What was fixed: specification.html had no regeneration path or drift test — a file-only edit would survive until the next render_endpoint_spec_html() run, then vanish silently. The PR adds the same guard openapi.email.json already has, so the file can no longer diverge from its generator undetected.

How to verify:

1. git fetch origin autofix/issue-2080 && git checkout autofix/issue-2080
2. cd hub/agents/python/email
3. python -m gaia_agent_email.spec_html --check → exits 0 (file and generator in sync)
4. Append a stray line to specification.html, re-run --check → exits 1; python -m pytest tests/test_spec_html_artifact.py fails loudly. Revert the edit and both pass again.

Note: the file and generator are byte-identical today, so no doc content changed — this is purely the missing drift guard. The PR includes passing lint and the new drift-guard tests.