fix: preserve .mdc frontmatter, add tests, clean up on switch

1. Rewrite _ensure_mdc_frontmatter() with regex — preserves comments,
   formatting, and custom keys in existing frontmatter instead of
   destructively re-serializing via yaml.safe_dump(). Inserts or
   fixes alwaysApply: true in place.

2. Add 6 focused .mdc frontmatter tests to cursor-agent test file:
   new file creation, missing frontmatter, preserved custom keys,
   wrong alwaysApply value, idempotent upserts, removal cleanup.

3. Call remove_context_section() during integration switch Phase 1 —
   prevents stale SPECKIT markers from being left in the old
   integration's context file. Also clear context_file from
   init-options during the metadata reset.

Author: mnriem

src/specify_cli/__init__.py

@@ -2155,6 +2155,7 @@ def integration_switch(
                 )
                 raise typer.Exit(1)
             removed, skipped = old_manifest.uninstall(project_root, force=force)
+            current_integration.remove_context_section(project_root)
             if removed:
                 console.print(f"  Removed {len(removed)} file(s)")
             if skipped:
@@ -2185,6 +2186,7 @@ def integration_switch(
         opts.pop("integration", None)
         opts.pop("ai", None)
         opts.pop("ai_skills", None)
+        opts.pop("context_file", None)
         save_init_options(project_root, opts)
 
     # Ensure shared infrastructure is present (safe to run unconditionally;

src/specify_cli/integrations/base.py

@@ -395,34 +395,51 @@ def _ensure_mdc_frontmatter(content: str) -> str:
 
         If frontmatter is missing, prepend it.  If frontmatter exists but
         ``alwaysApply`` is absent or not ``true``, inject/fix it.
+
+        Uses string/regex manipulation to preserve comments and formatting
+        in existing frontmatter.
         """
-        import yaml as _yaml
+        import re as _re
+
+        leading_ws = len(content) - len(content.lstrip())
+        leading = content[:leading_ws]
+        stripped = content[leading_ws:]
 
-        stripped = content.lstrip()
         if not stripped.startswith("---"):
             return "---\nalwaysApply: true\n---\n\n" + content
 
-        # Parse existing frontmatter
-        end = stripped.find("\n---", 3)
-        if end == -1:
+        # Match frontmatter block: ---\n...\n---
+        match = _re.match(
+            r"^(---[ \t]*\r?\n)(.*?)(\r?\n---[ \t]*)(\r?\n|$)(.*)",
+            stripped,
+            _re.DOTALL,
+        )
+        if not match:
             return "---\nalwaysApply: true\n---\n\n" + content
 
-        fm_text = stripped[4:end]  # between first --- and closing ---
-        try:
-            fm = _yaml.safe_load(fm_text)
-        except Exception:
-            fm = None
-        if not isinstance(fm, dict):
-            fm = {}
-
-        if fm.get("alwaysApply") is True:
-            return content  # already correct
-
-        fm["alwaysApply"] = True
-        new_fm = _yaml.safe_dump(fm, sort_keys=False).strip()
-        # Reconstruct: frontmatter + rest of file after closing ---
-        rest = stripped[end + 4:]  # after \n---
-        return f"---\n{new_fm}\n---{rest}"
+        opening, fm_text, closing, sep, rest = match.groups()
+        newline = "\r\n" if "\r\n" in opening else "\n"
+
+        # Already correct?
+        if _re.search(
+            r"(?m)^[ \t]*alwaysApply[ \t]*:[ \t]*true[ \t]*(?:#.*)?$", fm_text
+        ):
+            return content
+
+        # alwaysApply exists but wrong value — fix in place
+        if _re.search(r"(?m)^[ \t]*alwaysApply[ \t]*:", fm_text):
+            fm_text = _re.sub(
+                r"(?m)^([ \t]*)alwaysApply[ \t]*:.*$",
+                r"\1alwaysApply: true",
+                fm_text,
+                count=1,
+            )
+        elif fm_text.strip():
+            fm_text = fm_text + newline + "alwaysApply: true"
+        else:
+            fm_text = "alwaysApply: true"
+
+        return f"{leading}{opening}{fm_text}{closing}{sep}{rest}"
 
     @staticmethod
     def _build_context_section(plan_path: str = "") -> str:

tests/integrations/test_integration_cursor_agent.py

@@ -1,5 +1,10 @@
 """Tests for CursorAgentIntegration."""
 
+from pathlib import Path
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
 from .test_integration_base_skills import SkillsIntegrationTests
 
 
@@ -11,6 +16,81 @@ class TestCursorAgentIntegration(SkillsIntegrationTests):
     CONTEXT_FILE = ".cursor/rules/specify-rules.mdc"
 
 
+class TestCursorMdcFrontmatter:
+    """Verify .mdc frontmatter handling in upsert/remove context section."""
+
+    def _setup(self, tmp_path: Path):
+        i = get_integration("cursor-agent")
+        m = IntegrationManifest("cursor-agent", tmp_path)
+        return i, m
+
+    def test_new_mdc_gets_frontmatter(self, tmp_path):
+        """A freshly created .mdc file includes alwaysApply: true."""
+        i, m = self._setup(tmp_path)
+        i.setup(tmp_path, m)
+        ctx = (tmp_path / i.context_file).read_text(encoding="utf-8")
+        assert ctx.startswith("---\n")
+        assert "alwaysApply: true" in ctx
+
+    def test_existing_mdc_without_frontmatter_gets_it(self, tmp_path):
+        """An existing .mdc without frontmatter gets it added."""
+        i, m = self._setup(tmp_path)
+        ctx_path = tmp_path / i.context_file
+        ctx_path.parent.mkdir(parents=True, exist_ok=True)
+        ctx_path.write_text("# User rules\n", encoding="utf-8")
+        i.upsert_context_section(tmp_path)
+        content = ctx_path.read_text(encoding="utf-8")
+        assert content.lstrip().startswith("---")
+        assert "alwaysApply: true" in content
+        assert "# User rules" in content
+
+    def test_existing_mdc_with_frontmatter_preserves_it(self, tmp_path):
+        """An existing .mdc with custom frontmatter is preserved."""
+        i, m = self._setup(tmp_path)
+        ctx_path = tmp_path / i.context_file
+        ctx_path.parent.mkdir(parents=True, exist_ok=True)
+        ctx_path.write_text(
+            "---\nalwaysApply: true\ncustomKey: hello\n---\n\n# Rules\n",
+            encoding="utf-8",
+        )
+        i.upsert_context_section(tmp_path)
+        content = ctx_path.read_text(encoding="utf-8")
+        assert "alwaysApply: true" in content
+        assert "customKey: hello" in content
+        assert "<!-- SPECKIT START -->" in content
+
+    def test_existing_mdc_wrong_alwaysapply_fixed(self, tmp_path):
+        """An .mdc with alwaysApply: false gets corrected."""
+        i, m = self._setup(tmp_path)
+        ctx_path = tmp_path / i.context_file
+        ctx_path.parent.mkdir(parents=True, exist_ok=True)
+        ctx_path.write_text(
+            "---\nalwaysApply: false\n---\n\n# Rules\n",
+            encoding="utf-8",
+        )
+        i.upsert_context_section(tmp_path)
+        content = ctx_path.read_text(encoding="utf-8")
+        assert "alwaysApply: true" in content
+        assert "alwaysApply: false" not in content
+
+    def test_upsert_idempotent_no_duplicate_frontmatter(self, tmp_path):
+        """Repeated upserts don't duplicate frontmatter."""
+        i, m = self._setup(tmp_path)
+        i.upsert_context_section(tmp_path)
+        i.upsert_context_section(tmp_path)
+        content = (tmp_path / i.context_file).read_text(encoding="utf-8")
+        assert content.count("alwaysApply") == 1
+
+    def test_remove_deletes_mdc_with_only_frontmatter(self, tmp_path):
+        """Removing the section from a Speckit-only .mdc deletes the file."""
+        i, m = self._setup(tmp_path)
+        i.upsert_context_section(tmp_path)
+        ctx_path = tmp_path / i.context_file
+        assert ctx_path.exists()
+        i.remove_context_section(tmp_path)
+        assert not ctx_path.exists()
+
+
 class TestCursorAgentAutoPromote:
     """--ai cursor-agent auto-promotes to integration path."""