fix(compiler): YAML-safe brief in concept frontmatter (closes #67)

LLM-authored brief values often contain colons, quotes, or hashes; the
existing f-string interpolation in _write_concept produced invalid
frontmatter (e.g. "brief: Why X: Y" → mapping value not allowed).
OpenKB's own reader uses string slicing so it never noticed, but
external YAML-aware tools (VS Code preview, Obsidian, doc generators)
reject the page.

- New _yaml_kv_line helper routes the value through yaml.safe_dump so
  PyYAML auto-quotes when needed.
- Both write sites in _write_concept (re.sub update path + create
  path) use the helper. re.sub now takes a lambda replacement to
  bypass backref interpretation when brief contains literal \1 / \g<…>.
- New find_invalid_frontmatter check in lint.py runs yaml.safe_load
  on every wiki page's frontmatter and is wired into the
  run_structural_lint report; future regressions surface immediately
  instead of silently writing bad YAML.

Repro and root-cause analysis by @invu557 (issue #67).

Author: KylinMountain

openkb/agent/compiler.py

@@ -27,6 +27,7 @@
 from pathlib import Path
 
 import litellm
+import yaml
 
 from openkb.lint import list_existing_wiki_targets, strip_ghost_wikilinks
 from openkb.schema import get_agents_md
@@ -564,6 +565,19 @@ def _sanitize_concept_name(name: str) -> str:
     return sanitized or "unnamed-concept"
 
 
+def _yaml_kv_line(key: str, value: str) -> str:
+    """Render a single ``key: value`` line that round-trips through any YAML loader.
+
+    LLM-authored values often contain colons, quotes, ``#``, brackets, etc.;
+    f-string interpolation produces invalid YAML for those. ``yaml.safe_dump``
+    auto-quotes when needed and never wraps (``width=inf``).
+    """
+    dumped = yaml.safe_dump(
+        {key: value}, default_flow_style=False, width=10**9, allow_unicode=True,
+    ).strip()
+    return dumped.split("\n", 1)[0]
+
+
 def _write_concept(wiki_dir: Path, name: str, content: str, source_file: str, is_update: bool, brief: str = "") -> None:
     """Write or update a concept page, managing the sources frontmatter."""
     concepts_dir = wiki_dir / "concepts"
@@ -598,10 +612,13 @@ def _write_concept(wiki_dir: Path, name: str, content: str, source_file: str, is
             if end != -1:
                 fm = existing[:end + 3]
                 body = existing[end + 3:]
+                brief_line = _yaml_kv_line("brief", brief)
                 if "brief:" in fm:
-                    fm = re.sub(r"brief:.*", f"brief: {brief}", fm)
+                    # Lambda to bypass re.sub backref interpretation in the
+                    # replacement string (brief may contain \1, \g<…>, etc.).
+                    fm = re.sub(r"brief:.*", lambda _m: brief_line, fm)
                 else:
-                    fm = fm.replace("---\n", f"---\nbrief: {brief}\n", 1)
+                    fm = fm.replace("---\n", f"---\n{brief_line}\n", 1)
                 existing = fm + body
         path.write_text(existing, encoding="utf-8")
     else:
@@ -611,7 +628,7 @@ def _write_concept(wiki_dir: Path, name: str, content: str, source_file: str, is
                 content = content[end + 3:].lstrip("\n")
         fm_lines = [f"sources: [{source_file}]"]
         if brief:
-            fm_lines.append(f"brief: {brief}")
+            fm_lines.append(_yaml_kv_line("brief", brief))
         frontmatter = "---\n" + "\n".join(fm_lines) + "\n---\n\n"
         path.write_text(frontmatter + content, encoding="utf-8")
 

openkb/lint.py

@@ -5,13 +5,16 @@
 - Orphaned pages — pages with no incoming or outgoing links
 - Missing wiki entries — raw files without corresponding sources/summaries
 - Index sync — index.md links vs actual files on disk
+- Invalid frontmatter — YAML that won't round-trip through safe_load
 """
 from __future__ import annotations
 
 import re
 import unicodedata
 from pathlib import Path
 
+import yaml
+
 # Matches [[wikilink]] or [[subdir/link]]
 _WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")
 
@@ -402,6 +405,36 @@ def check_index_sync(wiki: Path) -> list[str]:
     return sorted(issues)
 
 
+def find_invalid_frontmatter(wiki: Path) -> list[str]:
+    """Return wiki pages whose YAML frontmatter fails ``yaml.safe_load``.
+
+    Catches the silent-write class of bug where an LLM-authored field
+    (e.g. ``brief:``) ships unquoted and turns a colon-bearing value
+    into invalid YAML that OpenKB itself reads with string slicing but
+    external YAML-aware tools (VS Code, Obsidian, doc generators) reject.
+    """
+    issues: list[str] = []
+    if not wiki.exists():
+        return issues
+    for path in sorted(wiki.rglob("*.md")):
+        if path.name in _EXCLUDED_FILES:
+            continue
+        text = _read_md(path)
+        if not text.startswith("---"):
+            continue
+        end = text.find("\n---", 3)
+        if end == -1:
+            continue
+        fm = text[3:end].strip("\n")
+        try:
+            yaml.safe_load(fm)
+        except yaml.YAMLError as exc:
+            rel = path.relative_to(wiki)
+            msg = str(exc).splitlines()[0]
+            issues.append(f"{rel}: {msg}")
+    return issues
+
+
 def run_structural_lint(kb_dir: Path) -> str:
     """Run all structural lint checks and return a formatted Markdown report.
 
@@ -418,6 +451,7 @@ def run_structural_lint(kb_dir: Path) -> str:
     orphans = find_orphans(wiki)
     missing = find_missing_entries(raw, wiki)
     sync_issues = check_index_sync(wiki)
+    bad_frontmatter = find_invalid_frontmatter(wiki)
 
     lines = ["## Structural Lint Report\n"]
 
@@ -455,5 +489,14 @@ def run_structural_lint(kb_dir: Path) -> str:
             lines.append(f"- {issue}")
     else:
         lines.append("Index is in sync.")
+    lines.append("")
+
+    # Invalid frontmatter
+    lines.append(f"### Invalid Frontmatter ({len(bad_frontmatter)})")
+    if bad_frontmatter:
+        for issue in bad_frontmatter:
+            lines.append(f"- {issue}")
+    else:
+        lines.append("All frontmatter parses as valid YAML.")
 
     return "\n".join(lines)