fix: make planning-doc validation portable across knowledge roots

Closes #212

Author: alexeygrigorev

scripts/validate_planning_docs.py

@@ -278,7 +278,7 @@ def validate_doc_registry(repo_root: Path) -> list[str]:
         return violations
 
     for template_path in sorted((root / "tasks" / "templates").glob("*.md")):
-        repo_path = _repo_path(root.parent, template_path)
+        repo_path = _corpus_path(root, template_path)
         record = registry.by_path.get(repo_path)
         if record is None:
             violations.append(f"{repo_path}: missing from document registry")
@@ -298,7 +298,7 @@ def validate_task_templates(repo_root: Path) -> list[str]:
 
     seen_titles: dict[str, str] = {}
     for template_path in template_paths:
-        repo_path = _repo_path(repo_root, template_path)
+        repo_path = _corpus_path(root, template_path)
         text = template_path.read_text(encoding="utf-8", errors="replace")
         raw, body = sop_parse.split_frontmatter(text)
         metadata = sop_parse.parse_frontmatter(raw) if raw else {}
@@ -482,6 +482,10 @@ def _normalize_text(text: str) -> str:
     return text.lower()
 
 
+def _corpus_path(content_root: Path, path: Path) -> str:
+    return (Path("content") / path.resolve().relative_to(content_root.resolve())).as_posix()
+
+
 def _repo_path(repo_root: Path, path: Path) -> str:
     return path.resolve().relative_to(repo_root).as_posix()
 

tests/planning_docs/test_validate_planning_docs.py

@@ -13,6 +13,52 @@
 import validate_planning_docs  # noqa: E402
 
 
+VALID_TEMPLATE = """---
+title: "Newsletter"
+doc_type: task-template
+schema_version: 1
+source: "backend/scripts/seed-templates.ts"
+systems:
+  - dataops
+  - datatasks
+tags:
+  - task-template
+  - newsletter
+---
+
+# Newsletter
+
+<!-- sop-section-start: summary -->
+## Summary
+<!-- sop-section-start: purpose -->
+## Purpose
+<!-- sop-section-start: references -->
+## References
+<!-- sop-section-start: required-card-links -->
+## Required Card Links
+<!-- sop-section-start: task-definitions -->
+## Task Definitions
+
+| # | Ref ID | Phase | Offset | Owner | Operator action | Context | Proof / closure | Waiting / follow-up |
+| - | - | - | -: | - | - | - | - | - |
+| 1 | `create-document` | intake | -14 | owner | Create document | doc.id | url: Document |  |
+"""
+
+INVALID_TEMPLATE = """---
+title: "Invalid"
+doc_type: template
+schema_version: 2
+source: "wrong-place.ts"
+systems:
+  - dataops
+tags:
+  - task-template
+---
+
+# Invalid
+"""
+
+
 def test_current_repo_planning_docs_contract_passes():
     assert validate_planning_docs.validate(REPO_ROOT) == []
 
@@ -121,3 +167,55 @@ def test_task_template_accepts_richer_operator_workflow_table(tmp_path):
     violations = validate_planning_docs.validate_task_templates(tmp_path)
 
     assert violations == []
+
+
+def test_task_template_paths_are_stable_across_corpus_layouts(tmp_path, monkeypatch):
+    layouts = {
+        "repository-local": (
+            tmp_path / "repository-local" / "app" / "content",
+            tmp_path / "repository-local" / "app",
+        ),
+        ".knowledge": (
+            tmp_path / "dot-knowledge" / "app" / ".knowledge" / "content",
+            tmp_path / "dot-knowledge" / "app",
+        ),
+        "configured-external": (
+            tmp_path / "configured-external" / "corpus" / "content",
+            tmp_path / "configured-external" / "app",
+        ),
+        "sibling-style": (
+            tmp_path / "sibling-style" / "dataops-knowledge" / "content",
+            tmp_path / "sibling-style" / "differently-named-app",
+        ),
+    }
+    results = {}
+
+    for layout, (content_root, app_root) in layouts.items():
+        templates_dir = content_root / "tasks" / "templates"
+        templates_dir.mkdir(parents=True)
+        (templates_dir / "newsletter.md").write_text(VALID_TEMPLATE, encoding="utf-8")
+
+        if layout == "configured-external":
+            monkeypatch.setenv("DATAOPS_CONTENT_ROOT", str(content_root))
+        else:
+            monkeypatch.delenv("DATAOPS_CONTENT_ROOT", raising=False)
+
+        assert validate_planning_docs.validate_task_templates(app_root) == []
+
+        newsletter_path = templates_dir / "newsletter.md"
+        newsletter_path.write_text(
+            INVALID_TEMPLATE.replace('title: "Invalid"', 'title: "Newsletter"'),
+            encoding="utf-8",
+        )
+        violations = validate_planning_docs.validate_task_templates(app_root)
+
+        assert violations
+        assert all(violation.startswith("content/tasks/templates/") for violation in violations)
+        assert not any(str(app_root) in violation for violation in violations)
+        assert any(
+            violation == "content/tasks/templates/newsletter.md: doc_type must be task-template"
+            for violation in violations
+        )
+        results[layout] = tuple(violations)
+
+    assert len(set(results.values())) == 1