fix(review): harden frontmatter writes (title-case type, quote full_text, backfill order + dirty-check, lint isinstance)

Author: KylinMountain

openkb/agent/compiler.py

@@ -783,7 +783,7 @@ def _write_summary(wiki_dir: Path, doc_name: str, summary: str,
     if description:
         fm_lines.append(_yaml_kv_line("description", description))
     fm_lines.append(f"doc_type: {doc_type}")
-    fm_lines.append(f"full_text: sources/{doc_name}.{ext}")
+    fm_lines.append(_yaml_kv_line("full_text", f"sources/{doc_name}.{ext}"))
     frontmatter = "---\n" + "\n".join(fm_lines) + "\n---\n\n"
     (summaries_dir / f"{doc_name}.md").write_text(frontmatter + summary, encoding="utf-8")
 
@@ -917,7 +917,7 @@ def _write_entity(
 
     def _build_frontmatter(sources: list[str]) -> str:
         fm_lines = [_yaml_list_line("sources", sources)]
-        fm_lines.append(_yaml_kv_line("type", (type_ or "other").capitalize()))
+        fm_lines.append(_yaml_kv_line("type", (type_ or "other").title()))
         if brief:
             fm_lines.append(_yaml_kv_line("description", brief))
         if aliases:
@@ -932,7 +932,7 @@ def _build_frontmatter(sources: list[str]) -> str:
         if end != -1:
             fm = existing[:end + 3]
             fm = _set_fm_line(fm, "description", brief) if brief else fm
-            fm = _set_fm_line(fm, "type", type_.capitalize()) if type_ else fm
+            fm = _set_fm_line(fm, "type", type_.title()) if type_ else fm
             # Drop any legacy ``brief:`` key (migrated to ``description:``),
             # mirroring _write_concept's update path.
             fm = re.sub(r"^brief:.*\n?", "", fm, flags=re.MULTILINE)
@@ -2055,17 +2055,21 @@ async def compile_long_doc(
     schema_md = get_agents_md(wiki_dir)
     summary_content = summary_path.read_text(encoding="utf-8")
 
-    # Backfill OKF fields on the indexer-written summary (idempotent).
+    # Backfill OKF fields on the indexer-written summary. Idempotent: set
+    # description before type so that when both keys are missing the prepends
+    # leave `type` first (canonical order); only rewrite when content changed.
     if summary_content.startswith("---"):
         fm_end = summary_content.find("---", 3)
         if fm_end != -1:
             fm = summary_content[:fm_end + 3]
             body = summary_content[fm_end + 3:]
-            fm = _set_fm_line(fm, "type", "Summary")
             if doc_description:
                 fm = _set_fm_line(fm, "description", doc_description)
-            summary_content = fm + body
-            summary_path.write_text(summary_content, encoding="utf-8")
+            fm = _set_fm_line(fm, "type", "Summary")
+            updated = fm + body
+            if updated != summary_content:
+                summary_content = updated
+                summary_path.write_text(summary_content, encoding="utf-8")
 
     # Base context A. cache_control marker on the doc message creates a
     # cache breakpoint covering (system + doc) for every concept call.

openkb/lint.py

@@ -511,9 +511,11 @@ def find_missing_okf_fields(wiki: Path) -> list[str]:
                         fm = None
             fm = fm if isinstance(fm, dict) else {}
             rel = path.relative_to(wiki)
-            if not str(fm.get("type") or "").strip():
+            type_val = fm.get("type")
+            if not (isinstance(type_val, str) and type_val.strip()):
                 issues.append(f"{rel}: missing non-empty 'type'")
-            if not str(fm.get("description") or "").strip():
+            desc_val = fm.get("description")
+            if not (isinstance(desc_val, str) and desc_val.strip()):
                 issues.append(f"{rel}: missing non-empty 'description'")
     return issues
 

openkb/tree_renderer.py

@@ -15,7 +15,7 @@ def _yaml_frontmatter(source_name: str, doc_id: str, description: str = "") -> s
     if description:
         lines.append(_yaml_kv_line("description", description))
     lines.append("doc_type: pageindex")
-    lines.append(f"full_text: sources/{source_name}.json")
+    lines.append(_yaml_kv_line("full_text", f"sources/{source_name}.json"))
     return "---\n" + "\n".join(lines) + "\n---\n"
 
 

tests/test_compiler.py

@@ -209,7 +209,7 @@ def test_writes_type_and_description(self, tmp_path):
         assert 'type: "Summary"' in text
         assert 'description: "A one-line summary."' in text
         assert "doc_type: short" in text
-        assert "full_text: sources/my-doc.md" in text
+        assert 'full_text: "sources/my-doc.md"' in text
         assert "# Summary" in text
 
     def test_omits_description_when_empty(self, tmp_path):
@@ -773,6 +773,12 @@ def test_update_entity_strips_legacy_brief(self, tmp_path):
         assert "Old brief." not in text
         assert 'description: "New desc."' in text
 
+    def test_entity_type_multiword_title_cased(self, tmp_path):
+        _write_entity(tmp_path, "acme", "# Acme\n\nx.", "summaries/a.md",
+                      is_update=False, brief="b", type_="real estate")
+        text = (tmp_path / "entities" / "acme.md").read_text(encoding="utf-8")
+        assert 'type: "Real Estate"' in text
+
 
 class TestBacklinkSummary:
     def test_adds_missing_concept_links(self, tmp_path):
@@ -1063,7 +1069,7 @@ async def test_full_pipeline(self, tmp_path):
         summary_path = wiki / "summaries" / "test-doc.md"
         assert summary_path.exists()
         summary_text = summary_path.read_text()
-        assert "full_text: sources/test-doc.md" in summary_text
+        assert 'full_text: "sources/test-doc.md"' in summary_text
         assert 'type: "Summary"' in summary_text
         # Summary body comes from the rewrite step
         assert "[[concepts/transformer]]" in summary_text
@@ -1741,7 +1747,7 @@ async def test_short_doc_briefs_in_index_and_frontmatter(self, tmp_path):
         # Summary frontmatter has doc_type and full_text
         summary_text = (wiki / "summaries" / "test-doc.md").read_text()
         assert "doc_type: short" in summary_text
-        assert "full_text: sources/test-doc.md" in summary_text
+        assert 'full_text: "sources/test-doc.md"' in summary_text
 
         # Concept frontmatter has type and description
         concept_text = (wiki / "concepts" / "transformer.md").read_text()

tests/test_lint.py

@@ -675,3 +675,12 @@ def test_flags_null_type_as_missing(tmp_path):
         '---\ntype: null\ndescription: "x"\n---\n\n# Bad\n', encoding="utf-8")
     issues = find_missing_okf_fields(wiki)
     assert any("null_type.md" in i and "type" in i for i in issues)
+
+
+def test_flags_non_string_type_as_missing(tmp_path):
+    wiki = tmp_path / "wiki"
+    (wiki / "concepts").mkdir(parents=True)
+    (wiki / "concepts" / "bool_type.md").write_text(
+        '---\ntype: true\ndescription: "x"\n---\n\n# Bad\n', encoding="utf-8")
+    issues = find_missing_okf_fields(wiki)
+    assert any("bool_type.md" in i and "type" in i for i in issues)

tests/test_recompile.py

@@ -343,3 +343,5 @@ def test_compile_long_doc_backfills_summary_frontmatter(tmp_path):
     text = summary_path.read_text(encoding="utf-8")
     assert 'type: "Summary"' in text
     assert 'description: "A long report."' in text
+    # canonical order: type before description
+    assert text.index('type:') < text.index('description:')

tests/test_tree_renderer.py

@@ -15,7 +15,7 @@ def test_has_yaml_frontmatter(self, sample_tree):
         output = render_summary_md(sample_tree, "Sample Document", "doc-abc")
         assert output.startswith("---\n")
         assert "doc_type: pageindex" in output
-        assert "full_text: sources/Sample Document.json" in output
+        assert 'full_text: "sources/Sample Document.json"' in output
 
     def test_top_level_nodes_are_h1(self, sample_tree):
         output = render_summary_md(sample_tree, "Sample Document", "doc-abc")
@@ -47,4 +47,15 @@ def test_summary_md_has_type_and_description():
     assert 'type: "Summary"' in md
     assert 'description: "Quarterly report."' in md
     assert "doc_type: pageindex" in md
-    assert "full_text: sources/my-doc.json" in md
+    assert 'full_text: "sources/my-doc.json"' in md
+
+
+def test_summary_full_text_quoted_yaml_safe():
+    import yaml
+    tree = {"structure": []}
+    md = render_summary_md(tree, "weird: name", "doc-1", description="d")
+    # full_text is JSON-quoted, so a source name with a colon stays valid YAML
+    assert 'full_text: "sources/weird: name.json"' in md
+    fm = yaml.safe_load(md.split("---")[1])
+    assert fm["full_text"] == "sources/weird: name.json"
+    assert fm["type"] == "Summary"