feat(polish): emit polish: skipped frontmatter on lenient fallback (#33)

Surface a polish bypass in the rendered YAML frontmatter so the
degradation shows up in PR diffs. Without this marker, raw-Jinja
output is structurally identical to a normal generation (same
headings, same frontmatter shape) and slips past review — see
attune-author#30 and attune-rag d39e39d, where a regeneration with
polish silently bypassed merged in degraded form.

The marker is only added when polish falls back to returning raw
content in lenient mode (no API key, swallowed LLM error). The
success path and the cache-hit path are unchanged.

Helper is idempotent: re-running polish on an already-marked file
does not double-write. Non-YAML output (project-doc templates with
HTML-comment footers) passes through unchanged — surfacing bypass
there would need a different mechanism and is deliberately out of
scope here.

Tests:
- ``test_lenient_bypass_marks_yaml_frontmatter`` — bypass injects
  the marker; body is preserved verbatim.
- ``test_lenient_bypass_is_idempotent_when_already_marked`` —
  re-running does not double-write.
- ``test_lenient_bypass_passes_through_non_frontmatter_content`` —
  non-YAML content unchanged.
- Updated golden snapshots reflect the new marker (snapshots are
  recorded under the lenient-by-default conftest fixture).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

src/attune_author/polish.py

@@ -345,7 +345,33 @@ def polish_template(
             template_type,
             exc,
         )
+        return _mark_polish_skipped(content)
+
+
+def _mark_polish_skipped(content: str) -> str:
+    # Surface a polish bypass in the rendered YAML frontmatter so
+    # the regression shows up in PR diffs. Without this marker,
+    # raw-Jinja output looks indistinguishable from a normal
+    # generation (same headings, same frontmatter shape) and slips
+    # past review — see attune-author#30 and attune-rag d39e39d.
+    #
+    # Only YAML frontmatter is supported. Non-YAML output (e.g.
+    # project-doc templates with an HTML comment footer) passes
+    # through unchanged; surfacing bypass there would need a
+    # different mechanism.
+    if not content.startswith("---\n"):
         return content
+    end = content.find("\n---\n", 4)
+    if end == -1:
+        return content
+    frontmatter = content[4:end]
+    rest = content[end + 5 :]
+    if "\npolish:" in "\n" + frontmatter:
+        # Idempotent: don't double-write if a previous run already
+        # marked the file.
+        return content
+    new_frontmatter = frontmatter.rstrip("\n") + "\npolish: skipped\n"
+    return f"---\n{new_frontmatter}---\n{rest}"
 
 
 def _sanitize_output(content: str) -> str:

tests/__snapshots__/test_generated_templates_golden.ambr

@@ -9,6 +9,7 @@
   generated_at: <TIMESTAMP>
   source_hash: <HASH>
   status: generated
+  polish: skipped
   ---
 
   # Auth
@@ -49,6 +50,7 @@
   generated_at: <TIMESTAMP>
   source_hash: <HASH>
   status: generated
+  polish: skipped
   ---
 
   # Auth reference
@@ -81,6 +83,7 @@
   generated_at: <TIMESTAMP>
   source_hash: <HASH>
   status: generated
+  polish: skipped
   ---
 
   # Work with auth

tests/test_polish.py

@@ -97,6 +97,51 @@ def test_returns_original_on_llm_error_when_lenient(self) -> None:
                 result = polish_template(content, "test", "summary", strict=False)
                 assert result == content
 
+    def test_lenient_bypass_marks_yaml_frontmatter(self) -> None:
+        # A polish bypass injects ``polish: skipped`` into the YAML
+        # frontmatter so the regression is visible in PR diffs —
+        # otherwise raw Jinja output is indistinguishable from a
+        # normal generation. See attune-author#30.
+        with patch.dict("os.environ", {}, clear=True):
+            content = (
+                "---\n"
+                "type: reference\n"
+                "feature: auth\n"
+                "status: generated\n"
+                "---\n"
+                "\n# Auth reference\n"
+            )
+            result = polish_template(content, "auth", "summary", strict=False)
+            assert "polish: skipped" in result
+            # Original body is preserved verbatim — only the
+            # frontmatter is annotated.
+            assert "# Auth reference" in result
+
+    def test_lenient_bypass_is_idempotent_when_already_marked(self) -> None:
+        # Re-running polish on an already-marked file should not
+        # double-write the marker.
+        with patch.dict("os.environ", {}, clear=True):
+            content = (
+                "---\n"
+                "type: reference\n"
+                "status: generated\n"
+                "polish: skipped\n"
+                "---\n"
+                "\n# Body\n"
+            )
+            result = polish_template(content, "auth", "summary", strict=False)
+            assert result.count("polish: skipped") == 1
+
+    def test_lenient_bypass_passes_through_non_frontmatter_content(self) -> None:
+        # Content without YAML frontmatter (e.g., project-doc
+        # templates with an HTML comment footer) is returned
+        # unchanged — surfacing bypass there would need a
+        # different mechanism.
+        with patch.dict("os.environ", {}, clear=True):
+            content = "# Test\nNo frontmatter here.\n"
+            result = polish_template(content, "test", "summary", strict=False)
+            assert result == content
+
     def test_returns_polished_on_success(self) -> None:
         """Test successful polish returns LLM output.