Move sync markers outside codeblock and strip codeblock fences in comparison

Copilot · nathanjmcdougall · Copilot · commit 02d098f1dabd · 2026-03-27T04:55:53.000Z
Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/fe83eae1-2e6d-4e23-926b-9f9fdb6fdf37 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
diff --git a/AGENTS.md b/AGENTS.md
@@ -59,8 +59,9 @@ External skills can be installed if they are not present — see the `usethis-sk
 
 ## Module Structure
 
-```text
 <!-- sync:docs/module-tree.txt -->
+
+```text
 usethis                           # usethis: Automate Python project setup and development tasks that are otherwise performed manually.
 ├── __main__                      # The CLI application for usethis.
 ├── _config                       # Global configuration state for usethis.
@@ -247,9 +248,10 @@ usethis                           # usethis: Automate Python project setup and d
         ├── tool                  # CLI commands for individual tool management.
         ├── typecheck             # CLI commands for type checking tools.
         └── version               # CLI commands for displaying version information.
-<!-- /sync:docs/module-tree.txt -->
 ```
 
+<!-- /sync:docs/module-tree.txt -->
+
 ## Lessons
 
 When you are working on a problem, you are almost always going to encounter a difficulty. This is great - it's an opportunity for learning. ALWAYS make a note explicitly of what lessons you are drawing as you complete a task or when receiving user feedback. Try and keep this structured: consider the root cause of the difficulty, and how you overcame it. After finishing work on a task, report back all your lessons. Finally, try and update the relevant skills with any new insights you've drawn, to help future agents, and/or create a new skill.
diff --git a/hooks/check-doc-sync.py b/hooks/check-doc-sync.py
@@ -19,6 +19,21 @@
 _SYNC_START = re.compile(r"^<!--\s*sync:(\S+)\s*-->$")
 # Pattern matches <!-- /sync:some/path --> and captures the path.
 _SYNC_END = re.compile(r"^<!--\s*/sync:(\S+)\s*-->$")
+# Pattern matches a markdown fenced code block opening (e.g. ```text).
+_CODEBLOCK_FENCE = re.compile(r"^```\w*$")
+
+
+def _strip_codeblock(text: str) -> str:
+    """Strip a surrounding markdown fenced code block, if present."""
+    stripped = text.strip()
+    lines = stripped.splitlines()
+    if (
+        len(lines) >= 2
+        and _CODEBLOCK_FENCE.match(lines[0])
+        and lines[-1].strip() == "```"
+    ):
+        return "\n".join(lines[1:-1])
+    return stripped
 
 
 def _find_sync_blocks(text: str) -> list[tuple[str, str]]:
@@ -80,7 +95,7 @@ def main() -> int:
 
             expected = source.read_text(encoding="utf-8")
 
-            if actual_content.strip() != expected.strip():
+            if _strip_codeblock(actual_content) != expected.strip():
                 print(
                     f"ERROR: Content in {path} between sync:{source_path} markers "
                     f"is out of sync with {source}.",
