Audit registered node documentation

tools/prompt_map_audit.py

@@ -118,6 +118,10 @@ AUDIT_DOC_SNIPPETS: tuple[tuple[str, str], ...] = (
         "docs/prompt-pool-routing-map.md",
         "multi-seed route sweeps",
     ),
+    (
+        "docs/prompt-pool-routing-map.md",
+        "node documentation validation",
+    ),
 )
 
 PROMPT_ROW_READ_SCAN_GLOBS: tuple[str, ...] = (
@@ -137,6 +141,10 @@ ALLOWED_PROMPT_ROW_READS: set[tuple[str, str]] = {
 
 ROUTE_POLICY_ACTION_EXCLUSIONS = {"default"}
 ROUTE_POLICY_POSITION_EXCLUSIONS = {"any"}
+NODE_DOC_PATHS = (
+    "docs/prompt-pool-routing-map.md",
+    "README.md",
+)
 
 
 def _literal_or_none(node: ast.AST) -> Any:
@@ -734,6 +742,26 @@ def _routing_doc_errors() -> list[tuple[str, str, str]]:
     return errors
 
 
+def _node_documentation_errors(display_names: dict[str, Any]) -> list[tuple[str, str, str]]:
+    doc_parts = []
+    for doc_name in NODE_DOC_PATHS:
+        path = ROOT / doc_name
+        if path.exists():
+            doc_parts.append(path.read_text(encoding="utf-8"))
+    doc_text = "\n".join(doc_parts)
+    errors: list[tuple[str, str, str]] = []
+    if not doc_text:
+        return [("(node docs)", ", ".join(NODE_DOC_PATHS), "no node documentation sources found")]
+    for class_name, display_name in sorted(display_names.items(), key=lambda item: str(item[1])):
+        display_text = str(display_name or "").strip()
+        if not display_text:
+            errors.append((str(class_name), "display name", "registered node has empty display name"))
+            continue
+        if display_text not in doc_text:
+            errors.append((str(class_name), "node documentation", f"missing display name in docs: {display_text}"))
+    return errors
+
+
 class _PromptRowReadVisitor(ast.NodeVisitor):
     def __init__(self, path: Path) -> None:
         self.path = path
@@ -1071,6 +1099,13 @@ def main() -> int:
         return 1
     print("OK: critical route modules are documented and covered by smoke cases.")
 
+    print("\n# Node Documentation Validation")
+    node_doc_errors = _node_documentation_errors(display)
+    if node_doc_errors:
+        print_table(("Node", "Location", "Issue"), node_doc_errors)
+        return 1
+    print("OK: registered node display names are documented in the route map or README.")
+
     print("\n# Metadata Prompt Fallback Validation")
     prompt_row_read_errors = _prompt_row_read_errors()
     if prompt_row_read_errors: