fix: prevent LLM polish from laundering source_hash frontmatter

[silversurfer562]

Summary

Fixes the regen/staleness source_hash mismatch bug — features stayed permanently "stale" after a successful regen because the polished file's frontmatter source_hash didn't match what compute_source_hash recomputed.

Root cause

apply_polish_results wrote the LLM's polished output verbatim, including any frontmatter the LLM emitted. The LLM is given the rendered template (with frontmatter) as input context; it polishes the body but ALSO echoes the frontmatter — sometimes with single-character transcription errors in deterministic fields.

Concrete evidence (attune-ai spec-engine, 2026-05-27):

frontmatter: f8ced22b02899aa25ff409636e659830c6ba856d70de6ddd1a9bf1cbe37a1337
computed:    f8ced22b02899aa25ff709636e659830c6ba856d70de6ddd1a9bf1cbe37a1337
                                ^
                                position 19: LLM wrote f4 instead of f7

compute_source_hash is called once at generator.py:355 and is fully deterministic (verified by calling it twice in a row — identical output). The divergence is entirely in the polish step's output mutation. The original spec hypothesis (budget truncation of hash inputs) was wrong; the polish layer never re-hashes the source.

Fix

_replace_polished_frontmatter(polished, canonical_source) strips whatever frontmatter the LLM emitted from the polished content and re-injects the canonical frontmatter from entry.rendered_content. apply_polish_results calls it for every depth with a polished result. Lenient-mode failures fall through to the raw rendered template (which already has correct frontmatter).

Tests

7 new regression tests in tests/unit/test_polished_frontmatter_reinjection.py:

• test_polished_with_perturbed_source_hash_is_corrected — exactly reproduces the f4/f7 bug, asserts canonical hash wins.
• test_polished_with_missing_frontmatter_gets_canonical_prepended — LLM strips frontmatter → still gets canonical prepended.
• test_polished_with_correct_frontmatter_unchanged_semantically — non-perturbed case still works.
• test_canonical_without_frontmatter_returns_polished_unchanged — defensive: no canonical frontmatter → polished returned as-is.
• test_extra_blank_lines_in_polished_body_preserved — body whitespace passes through.
• test_polished_template_keeps_canonical_source_hash — end-to-end via apply_polish_results.
• test_no_polish_result_uses_rendered_content_directly — lenient-mode fallthrough path.

Local: 173/173 unit tests pass.

Spec doc

docs/specs/regen-staleness-hash-mismatch/decisions.md updated with the verified diagnosis, replacing the original (wrong) budget-truncation hypothesis.

Downstream impact

Unblocks attune-gui Phase 2 (living-docs-regen-automation) which needed attune-author status --dry-run to reach a fixed point after regen. Once this lands and gets released (likely 0.14.2 patch), attune-gui can pin the new version and turn on its CI fail-if-stale gate.

After this lands: cut attune-author 0.14.2 → update attune-ai's attune-author dep cap if needed → regenerate spec-engine in attune-ai (the feature that's still stale post-fix in the current ecosystem) and confirm staleness clears.

Test plan

• Local: 173/173 unit tests pass
• CI: full matrix green
• After merge: cut 0.14.2 release; verify on PyPI; confirm in attune-ai that attune-author generate spec-engine --all-kinds clears the stale flag

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 81.39535% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/attune_author/generator.py	81.39%	4 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!