🐛 fix(playbook): add heading to generated CLAUDE.md

scripts/playbook.py

@@ -760,6 +760,10 @@ _CLAUDE_BLOCK_END = "<!-- playbook:claude:end -->"
 _CLAUDE_MD_CANDIDATES = ["CLAUDE.md", ".claude/CLAUDE.md"]
 
 
+def _claude_block_needs_heading(text: str) -> bool:
+    return text.lstrip().startswith(_CLAUDE_BLOCK_START)
+
+
 def sync_claude_md(project_root: Path, config: dict) -> None:
     claude_md_config = config.get("playbook", {}).get("claude_md")
 
@@ -796,7 +800,9 @@ def sync_claude_md(project_root: Path, config: dict) -> None:
     if not claude_md.exists():
         ensure_dir(claude_md.parent)
         claude_md.write_text(
-            "\n".join(block_lines) + "\n", encoding="utf-8", newline="\n"
+            "# CLAUDE.md\n\n" + "\n".join(block_lines) + "\n",
+            encoding="utf-8",
+            newline="\n",
         )
         log(f"Created {claude_md.relative_to(project_root)} with playbook block.")
         return
@@ -819,9 +825,10 @@ def sync_claude_md(project_root: Path, config: dict) -> None:
                     in_block = False
                 continue
             updated.append(line)
-        claude_md.write_text(
-            "\n".join(updated) + "\n", encoding="utf-8", newline="\n"
-        )
+        updated_text = "\n".join(updated) + "\n"
+        if _claude_block_needs_heading(updated_text):
+            updated_text = "# CLAUDE.md\n\n" + updated_text.lstrip()
+        claude_md.write_text(updated_text, encoding="utf-8", newline="\n")
         log("Updated CLAUDE.md (playbook block).")
     elif "@AGENTS.md" in text:
         log("Skip: CLAUDE.md already references AGENTS.md")