plm-knowledge 1.0.0__py3-none-any.whl

plm_knowledge/__init__.py

@@ -0,0 +1,92 @@
+"""TracePulse PLM Knowledge — Wave 6.5 Conv B.
+
+PRD §3 #6 product-line carve. Hosts the 4-sub-layer knowledge stack:
+
+  * **Foundation** — `01_Dictionnaries/**` (146 .md files at repo root)
+    + `plm_taxonomy` + `plm_evaluation_grids`. Path stays at repo root
+    through Wave 6.5 per Decision #171 = (c) defer relocation to Wave 7;
+    the ``foundation_loader`` module is a thin reader.
+  * **Rule & Policy** — ``issue_classification`` + ``business_validator``
+    (lifted via `git mv` from the monolith).
+  * **Retrieval** — ``rag_service`` + ``knowledge_pack_loader`` +
+    ``knowledge_search_engine`` (BM25; lifted via `git mv` from the
+    monolith).
+  * **Operational** — V1 placeholder per D-LOCKED-15 + Decision #172.
+
+Public surface:
+  * The 5 lifted modules at top level (``rag_service``,
+    ``issue_classification``, ``business_validator``,
+    ``knowledge_pack_loader``, ``knowledge_search_engine``).
+  * ``foundation_loader`` — Foundation layer thin reader.
+  * ``operational`` — Operational layer V1 placeholder.
+  * ``lifecycle`` — 4-state FSM aligned verbatim with PRD §8.11.3
+    (Decision #167 mirrored).
+  * ``manifests`` — YAML manifest loader (Decision #168 precedent =
+    YAML + filesystem).
+  * ``contracts`` — wire-contract Pydantic v2 frozen models for the
+    public surface (Decision #160 interface-freeze pattern).
+  * ``registry`` — manifest+lifecycle registry exposed to the kernel
+    (capability registry callers).
+
+Re-export shims at every monolith path keep legacy callers working
+through Wave 7 Extraction (Wave 1 W1.4 RunTaskTracker template + Wave
+6.5 Conv A precedent).
+"""
+
+from plm_knowledge.contracts import (
+    KNOWLEDGE_PACKAGE_VERSION,
+    KnowledgeKind,
+    KnowledgeLifecycleState,
+    KnowledgePackManifest,
+)
+from plm_knowledge.lifecycle import (
+    LIFECYCLE_STATES,
+    LIFECYCLE_TRANSITIONS,
+    InvalidLifecycleTransition,
+    can_transition,
+    is_terminal,
+    next_state,
+)
+from plm_knowledge.manifests import (
+    MANIFESTS_DIR,
+    ManifestLoadError,
+    load_all,
+    load_manifest,
+)
+from plm_knowledge.registry import (
+    KnowledgePackRegistry,
+    get_knowledge_registry,
+)
+from plm_knowledge.foundation_loader import (
+    list_foundation_documents,
+    resolve_foundation_root,
+)
+from plm_knowledge.operational import (
+    OPERATIONAL_LAYER_VERSION,
+    OperationalAck,
+    record_operational_event,
+)
+
+__all__ = [
+    "KNOWLEDGE_PACKAGE_VERSION",
+    "KnowledgeKind",
+    "KnowledgeLifecycleState",
+    "KnowledgePackManifest",
+    "LIFECYCLE_STATES",
+    "LIFECYCLE_TRANSITIONS",
+    "InvalidLifecycleTransition",
+    "can_transition",
+    "is_terminal",
+    "next_state",
+    "MANIFESTS_DIR",
+    "ManifestLoadError",
+    "load_all",
+    "load_manifest",
+    "KnowledgePackRegistry",
+    "get_knowledge_registry",
+    "list_foundation_documents",
+    "resolve_foundation_root",
+    "OPERATIONAL_LAYER_VERSION",
+    "OperationalAck",
+    "record_operational_event",
+]

plm_knowledge/business_validator.py

@@ -0,0 +1,279 @@
+"""
+Business Validator Agent
+Validates generated BPMN processes against original source data.
+"""
+
+import json
+from typing import Dict, Any, Optional
+
+from plm_shared.agents.base_agent import BaseAgent
+from plm_shared.protocols.services.llm import llm_service
+
+
+# Define the response schema for validation as a plain dict
+VALIDATION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "isValid": {
+            "type": "boolean",
+            "description": "True ONLY if the process perfectly matches ALL source data patterns and is syntactically perfect."
+        },
+        "score": {
+            "type": "number",
+            "description": "A confidence score from 0 to 100 based on data coverage."
+        },
+        "keywords": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "3 to 10 short thematic keywords (domains, roles, themes) for the process. Lowercase. No duplicates."
+        },
+        "criticalIssues": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "List of logical errors, missing activities from CSV, BPMN violations, or BPMN elements missing a precise expert description in documentation/persona/system."
+        },
+        "improvementSuggestions": {
+            "type": "string",
+            "description": "Technical instructions for the analyst to fix the issues, including completing expert-level documentation for each BPMN element."
+        }
+    },
+    "required": ["isValid", "score", "criticalIssues", "improvementSuggestions", "keywords"]
+}
+
+
+SYSTEM_INSTRUCTION = """You are a Senior Process Auditor & BPMN Validator. 
+Your goal is to find ANY discrepancy between the raw source data (CSV/Text) and the AI-generated model.
+
+STRICT CRITERIA:
+1. EXHAUSTIVE COVERAGE: Every unique activity found in the CSV 'Activity' or 'Event' column MUST be represented as a Task in the BPMN.
+2. SEQUENCE INTEGRITY: Timestamps in CSV must justify the flow. If 'Invoice' always follows 'Receipt', the BPMN must show this.
+3. BPMN 2.0 SYNTAX: 
+   - Must have exactly ONE Start Event.
+   - Must have at least ONE End Event.
+   - All nodes must be connected (no islands).
+   - Gateways must have clear labels for their outgoing flows.
+4. METRICS REALISM: Execution counts in 'miningData' must sum up logically (e.g., sum of branches = entry count).
+5. BUSINESS METADATA COMPLETENESS: Every step in the BPMN diagram (tasks, start/end events, gateways) MUST have a precise, expert-level description in <bpmn:documentation>. The description must be specific to the element (what it represents in the process, business meaning), not generic. For each <bpmn:task>: require <bpmn:documentation>; tasks that involve a responsible role or an IT system must have <bpmn:extensionElements> with <persona> and/or <system>. For start event: documentation should state what triggers the process. For end event(s): what outcome is reached. For gateways: what decision or split is represented. If any element lacks a precise, expert description or missing persona/system where relevant, add a critical issue and in improvementSuggestions ask to complete these properties with expert-level wording.
+
+BE PEDANTIC. If a single task is missing or a flow is illogical, set isValid to false.
+
+KEYWORDS REQUIREMENT:
+- Provide 3 to 10 short thematic keywords for the process.
+- Derive them from the source data and the generated BPMN (domains, roles, themes).
+- Use lowercase, avoid duplicates.
+"""
+
+
+class BusinessValidatorAgent(BaseAgent):
+    """
+    Business Validator Agent
+    
+    Validates generated BPMN processes against original source data.
+    Acts as a Senior Process Auditor checking:
+    
+    1. EXHAUSTIVE COVERAGE: Every activity in source data must be in BPMN
+    2. SEQUENCE INTEGRITY: Timestamps must justify the flow
+    3. BPMN 2.0 SYNTAX: Valid structure, connected nodes
+    4. METRICS REALISM: Execution counts add up logically
+    5. BUSINESS METADATA: Precise descriptions and persona/system assignments
+    
+    Input:
+        - original_content: Original CSV or text source data
+        - generated_process: Generated process dictionary to validate
+    
+    Output:
+        - isValid: Boolean validation result
+        - score: Confidence score (0-100)
+        - keywords: Extracted thematic keywords
+        - criticalIssues: List of found issues
+        - improvementSuggestions: Instructions for fixing issues
+    """
+
+    def __init__(self):
+        super().__init__(
+            name="business_validator",
+            description="Validates generated BPMN processes against original source data"
+        )
+
+    def get_output_schema(self) -> Dict[str, Any]:
+        """Define business validator output schema."""
+        return {
+            "type": "object",
+            "properties": {
+                "isValid": {"type": "boolean"},
+                "score": {"type": "number"},
+                "keywords": {"type": "array", "items": {"type": "string"}},
+                "criticalIssues": {"type": "array", "items": {"type": "string"}},
+                "improvementSuggestions": {"type": "string"},
+            },
+            "required": ["isValid", "score", "criticalIssues", "improvementSuggestions", "keywords"],
+        }
+
+    def get_required_fields(self) -> list:
+        """Return required input fields."""
+        return ["original_content", "generated_process"]
+
+    def validate_input(self, input_data: Dict[str, Any]) -> bool:
+        """Validate business validator input."""
+        if "original_content" not in input_data:
+            raise ValueError("Missing required field: original_content")
+        
+        if "generated_process" not in input_data:
+            raise ValueError("Missing required field: generated_process")
+        
+        original_content = input_data.get("original_content")
+        if not original_content or not str(original_content).strip():
+            raise ValueError("original_content must be non-empty string")
+        
+        generated_process = input_data.get("generated_process")
+        if not generated_process or not isinstance(generated_process, (dict, str)):
+            raise ValueError("generated_process must be dict or string")
+        
+        return True
+
+    async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute business validation workflow."""
+        self.validate_input(input_data)
+        
+        original_content = input_data.get("original_content")
+        generated_process = input_data.get("generated_process")
+        
+        return await self._validate_process(original_content, generated_process)
+
+    async def _validate_process(
+        self,
+        original_content: str,
+        generated_process: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Validate a generated BPMN process against original source data using ADK multi-LLM.
+        
+        Args:
+            original_content: Original CSV or text content
+            generated_process: Generated process dictionary to validate
+            
+        Returns:
+            Dictionary containing isValid, score, criticalIssues, improvementSuggestions, keywords
+            
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            print(f"[SCAN] Validating with provider: {llm_service.provider}")
+            
+            # Phase 1: Preprocess large CSV to avoid token overflow
+            source_content = await self._preprocess_source_data(original_content)
+            
+            # Phase 2: Build validation prompt
+            prompt = self._build_validation_prompt(source_content, generated_process)
+            
+            # Phase 3: Call ADK service
+            result = await llm_service.generate_structured(
+                system_prompt=SYSTEM_INSTRUCTION,
+                user_prompt=prompt,
+                output_schema=VALIDATION_SCHEMA,
+                temperature=0.3
+            )
+            
+            print(f"[OK] Validation complete - Score: {result.get('score', 0)}%")
+            return result
+            
+        except Exception as error:
+            print(f"[ERR] Validator Agent Error: {error}")
+            import traceback
+            traceback.print_exc()
+            # Return permissive validation on error
+            return self._get_default_validation()
+
+    async def _preprocess_source_data(self, original_content: str) -> str:
+        """
+        Preprocess large CSV to avoid token overflow.
+        
+        Args:
+            original_content: Original source data (CSV or text)
+            
+        Returns:
+            Preprocessed source data or original if small enough
+        """
+        if len(original_content) > 50000 and "Employee_ID" in original_content:
+            print("[SCAN] Applying CSV preprocessing for validation...")
+            try:
+                from plm_shared.utils.csv_preprocessor import smart_csv_preprocessor
+                return smart_csv_preprocessor(original_content)
+            except ImportError:
+                print("[WARN] CSV preprocessor not available, using original content")
+                return original_content[:50000]
+        
+        return original_content
+
+    def _build_validation_prompt(
+        self,
+        source_content: str,
+        generated_process: Dict[str, Any]
+    ) -> str:
+        """
+        Build validation prompt combining source data and generated process.
+        
+        Args:
+            source_content: Preprocessed source data
+            generated_process: Generated process to validate
+            
+        Returns:
+            Formatted validation prompt
+        """
+        return f"""[SOURCE_DATA_EXTRACT]
+{source_content[:10000]}
+
+[GENERATED_BPMN_AND_METRICS]
+{json.dumps(generated_process) if isinstance(generated_process, dict) else str(generated_process)}
+"""
+
+    def _get_default_validation(self) -> Dict[str, Any]:
+        """
+        Return permissive default validation result on error.
+        
+        Returns:
+            Default validation dictionary
+        """
+        return {
+            "isValid": True,
+            "score": 100,
+            "keywords": [],
+            "criticalIssues": [],
+            "improvementSuggestions": ""
+        }
+
+
+# Singleton instance
+business_validator_agent = BusinessValidatorAgent()
+
+
+# ==================== BACKWARD COMPATIBILITY ====================
+
+async def validate_process(
+    original_content: str,
+    generated_process: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Backward compatibility wrapper for original function.
+    
+    Validate a generated BPMN process against original source data using ADK multi-LLM
+    
+    Args:
+        original_content: Original CSV or text content
+        generated_process: Generated process dictionary to validate
+        
+    Returns:
+        Dictionary containing isValid, score, criticalIssues, improvementSuggestions
+        
+    Raises:
+        Exception: If validation fails
+    
+    Delegates to business_validator_agent singleton.
+    """
+    result = await business_validator_agent.execute({
+        "original_content": original_content,
+        "generated_process": generated_process,
+    })
+    
+    return result

plm_knowledge/contracts.py

@@ -0,0 +1,178 @@
+"""Wire-contract Pydantic v2 frozen models for the public surface.
+
+Authored at Wave 6.5 Conv B per Decision #160 (interface-freeze pattern,
+P-3 lock) — every cross-package symbol exposed by this sibling-package
+becomes a frozen v2 model so Wave 7 Extraction is mechanical (filter-
+repo + pin update; no behaviour rewrite).
+
+Public surface (frozen V1):
+  * ``KNOWLEDGE_PACKAGE_VERSION`` — the wire-contract version string.
+    Bump via dedicated migration story; out-of-band bumps trip
+    ``test_contracts_version_pinned``.
+  * ``KnowledgeKind`` — enum of knowledge-pack kinds carved at Wave 6.5
+    Conv B (covers all 4 PRD §3 #6 sub-layers).
+  * ``KnowledgeLifecycleState`` — enum mirroring
+    ``lifecycle.LIFECYCLE_STATES`` (4 states, PRD §8.11.3 verbatim).
+  * ``KnowledgePackManifest`` — the YAML manifest shape; one file per
+    knowledge pack under ``manifests/*.yaml``.
+
+Pydantic v2 ``model_config = ConfigDict(frozen=True)`` enforces
+immutability after construction — the registry and downstream consumers
+(kernel manifest harvest, capability registry) treat manifests as
+read-only descriptors. Mutations require constructing a new instance.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Wire-contract version. Authored at Wave 6.5 Conv B. Subsequent bumps
+# trace through a dedicated story + ADR per the interface-freeze
+# discipline (Decision #160). Pinned to the same wave-tag string used
+# by the Wave 6.5 Conv A `plm-skill-packages` carve (`v1.0.0-wave6.5`)
+# so the two siblings share a freeze checkpoint.
+KNOWLEDGE_PACKAGE_VERSION: str = "v1.0.0-wave6.5"
+
+
+class KnowledgeKind(str, Enum):
+    """Knowledge-pack kinds carved into plm-knowledge at Wave 6.5 Conv B.
+
+    Mirrors PRD §3 #6 product-line scope across the 4 named sub-layers:
+    Foundation, Rule & Policy, Retrieval, Operational. Wave 7+ may
+    extend this enum via a wire-contract bump
+    (``KNOWLEDGE_PACKAGE_VERSION``).
+    """
+
+    FOUNDATION_DICTIONARY = "foundation_dictionary"
+    """Foundation layer — `01_Dictionnaries/**` markdown corpus."""
+
+    FOUNDATION_TAXONOMY = "foundation_taxonomy"
+    """Foundation layer — `plm_taxonomy` definitions."""
+
+    FOUNDATION_EVALUATION_GRID = "foundation_evaluation_grid"
+    """Foundation layer — `plm_evaluation_grids` rubrics."""
+
+    RULE_POLICY = "rule_policy"
+    """Rule & Policy layer — issue classification + business validator."""
+
+    RETRIEVAL_RAG = "retrieval_rag"
+    """Retrieval layer — Azure Assistants RAG service."""
+
+    RETRIEVAL_BM25 = "retrieval_bm25"
+    """Retrieval layer — BM25 search engine over knowledge chunks."""
+
+    OPERATIONAL = "operational"
+    """Operational layer — V1 placeholder per D-LOCKED-15."""
+
+
+class KnowledgeLifecycleState(str, Enum):
+    """4-state lifecycle FSM mirror — PRD §8.11.3 verbatim (Decision #167).
+
+    Mirrors ``plm_knowledge.lifecycle.LIFECYCLE_STATES`` 1:1; the enum
+    exists to give Pydantic a constrained validator for the
+    ``lifecycle_state`` field of ``KnowledgePackManifest`` without a
+    free-form string.
+    """
+
+    DRAFT = "draft"
+    RELEASED = "released"
+    DEPRECATED = "deprecated"
+    RETIRED = "retired"
+
+
+class KnowledgePackManifest(BaseModel):
+    """YAML knowledge-pack manifest — one file per pack under ``manifests/*.yaml``.
+
+    Mirrors the Wave 6.5 Conv A `plm_skill_packages.contracts.SkillManifest`
+    template (Decision #168 = YAML + filesystem precedent) — manifests
+    load at boot via ``manifests.load_all()``, matching the
+    ``litellm_config/model_list.yaml`` catalog-as-truth pattern. No SQL,
+    no admin UI in V1.
+
+    Frozen-v2 model — mutations require constructing a new instance.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    pack_id: str = Field(
+        ...,
+        description="Stable identifier (e.g. 'foundation.dictionnaries'). Matches the YAML file basename.",
+        min_length=3,
+        max_length=128,
+    )
+    """Stable identifier; the basename of the manifest YAML file (less
+    extension). Format: ``<sub_layer>.<pack_name>``."""
+
+    kind: KnowledgeKind = Field(
+        ...,
+        description="Knowledge-pack kind enum (sub-layer assignment).",
+    )
+
+    title: str = Field(
+        ...,
+        description="Human-readable title shown in admin UI / capability registry.",
+        min_length=3,
+        max_length=200,
+    )
+
+    description: str = Field(
+        ...,
+        description="One-line description of the knowledge pack's surface.",
+        min_length=5,
+        max_length=500,
+    )
+
+    version: str = Field(
+        ...,
+        description="Knowledge-pack version (semver-style). Bumps trace through a dedicated story.",
+        pattern=r"^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$",
+    )
+
+    lifecycle_state: KnowledgeLifecycleState = Field(
+        ...,
+        description="Current lifecycle state (PRD §8.11.3 4-state).",
+    )
+
+    capability_id: Optional[str] = Field(
+        default=None,
+        description="Optional pointer into plm_shared.capability_registry.",
+    )
+
+    autonomy_level: Optional[str] = Field(
+        default=None,
+        description="Optional pointer into plm_shared autonomy levels (CR.10).",
+    )
+
+    entry_module: str = Field(
+        ...,
+        description="Dotted module path inside plm_knowledge (e.g. 'plm_knowledge.rag_service').",
+        pattern=r"^plm_knowledge(?:\.[A-Za-z_][A-Za-z0-9_]*)+$",
+    )
+
+    entry_callable: Optional[str] = Field(
+        default=None,
+        description="Optional callable name within the entry module (function or class). Foundation packs may omit this when the entry module is a static asset directory.",
+        max_length=128,
+    )
+
+    tags: List[str] = Field(
+        default_factory=list,
+        description="Optional tags for capability registry filtering.",
+        max_length=32,
+    )
+
+    notes: Optional[str] = Field(
+        default=None,
+        description="Free-form notes; not parsed by runtime.",
+        max_length=2000,
+    )
+
+
+__all__ = [
+    "KNOWLEDGE_PACKAGE_VERSION",
+    "KnowledgeKind",
+    "KnowledgeLifecycleState",
+    "KnowledgePackManifest",
+]

plm_knowledge/foundation_loader.py

@@ -0,0 +1,113 @@
+"""Foundation layer — thin reader for `01_Dictionnaries/`.
+
+Wave 6.5 Conv B per Decision #171 = (c) "defer relocation to Wave 7".
+The 146 markdown files at `01_Dictionnaries/` (repo root) stay in place
+through Wave 6.5; this loader resolves the path through the existing
+backend `config.dictionnaries_path` setting (already configurable) so
+no consumer needs a path change at this conv.
+
+Public surface:
+  * ``resolve_foundation_root(override=None)`` — returns the directory
+    Path. With ``override=None``, resolves via the backend
+    ``config.settings.dictionnaries_path`` (default `../../01_Dictionnaries`
+    relative to the backend module). The override exists for tests +
+    admin tooling that want to point at a snapshot directory.
+  * ``list_foundation_documents(override=None)`` — enumerate the
+    `*.md` files under the resolved root in stable lexicographic order.
+    Returns an empty list (with a warning) if the root is missing —
+    matches the boot-time pattern in `02_App/backend/main.py:306`
+    ("PLM Knowledge Engine (BM25 — non-bloquant si 01_Dictionnaries
+    absent)").
+
+Wave 7 Extraction will physically relocate the directory into
+`02_App/plm-knowledge/foundation/01_Dictionnaries/` and the resolution
+function will switch to a package-relative anchor.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Default repo-root path. The backend `config.settings.dictionnaries_path`
+# resolves this same string relative to the backend CWD; here we keep an
+# absolute fallback for sibling-package callers that don't have the
+# backend `config` module loaded (e.g. standalone admin tooling).
+_DEFAULT_REPO_ROOT_FALLBACK: Path = (
+    Path(__file__).resolve().parents[3] / "01_Dictionnaries"
+)
+
+
+def resolve_foundation_root(override: Optional[Path] = None) -> Path:
+    """Resolve the Foundation layer root directory.
+
+    Resolution order:
+      1. Explicit ``override`` Path (test + admin tooling escape hatch).
+      2. Backend ``config.settings.dictionnaries_path`` if importable.
+      3. Repo-root fallback ``../../../../01_Dictionnaries`` relative
+         to this module.
+
+    Returns the resolved Path even if the directory does not exist on
+    disk; callers that need a stricter contract can call
+    ``Path.exists()`` + branch on absence.
+    """
+    if override is not None:
+        return Path(override).resolve()
+    # Wave 6.7 Conv A: prefer the plm_shared.protocols settings proxy so
+    # the resolution path does not depend on ``02_App/backend/`` at
+    # import time. The proxy raises ``ProtocolNotRegistered`` on
+    # attribute access when the host has not wired the DI registry
+    # (e.g. truly standalone foundation_loader tests); fall back to the
+    # legacy ``config`` import in that case, then to the absolute repo-
+    # root fallback.
+    configured = None
+    try:
+        from plm_shared.protocols.services.settings import settings as _shared_settings
+
+        configured = getattr(_shared_settings, "dictionnaries_path", None)
+    except Exception:
+        configured = None
+    if configured is None:
+        try:
+            from plm_shared.settings import settings  # type: ignore[import-not-found]
+
+            configured = getattr(settings, "dictionnaries_path", None)
+        except ImportError:
+            configured = None
+    if configured is None:
+        return _DEFAULT_REPO_ROOT_FALLBACK
+    return Path(configured).resolve()
+
+
+def list_foundation_documents(override: Optional[Path] = None) -> List[Path]:
+    """Enumerate ``*.md`` files under the Foundation root.
+
+    Returns an empty list (with a warning logged) if the root is
+    missing — matches the non-blocking startup pattern in
+    `backend/main.py:306`. Sub-directories are walked recursively;
+    output is in stable lexicographic order.
+    """
+    root = resolve_foundation_root(override)
+    if not root.exists():
+        logger.warning(
+            "foundation_root_missing path=%s — returning empty document list",
+            root,
+        )
+        return []
+    if not root.is_dir():
+        logger.warning(
+            "foundation_root_not_a_directory path=%s — returning empty document list",
+            root,
+        )
+        return []
+    documents = sorted(root.rglob("*.md"))
+    return documents
+
+
+__all__ = [
+    "resolve_foundation_root",
+    "list_foundation_documents",
+]