harness = parse_frontmatter_and_body("HARNESS.md")
present_to_user(harness.name, harness.description)
inject_into_context(harness.body)

load_content(path: str) -> str
    If path points to a grouping directory, returns its routing file.
    If path points to a leaf directory, returns its primary file (per .leaf-detectors)
      and lists available scripts.
    If path points to a file, returns the full file content.

pip install harnesses-ref
harnesses-ref validate ./my-harness

from pathlib import Path


def load_harness(harness_path: Path) -> dict:
    harness_md = (harness_path / "HARNESS.md").read_text()
    frontmatter, body = parse_frontmatter_and_body(harness_md)
    return {
        "name": frontmatter["name"],
        "description": frontmatter["description"],
        "body": body,
    }


def _load_leaf_detectors(harness_path: Path) -> dict[str, str]:
    detectors: dict[str, str] = {}
    leaf_file = harness_path / ".leaf-detectors"
    if leaf_file.exists():
        for line in leaf_file.read_text().splitlines():
            line = line.strip()
            if not line or line.startswith("#"):
                continue
            if "=" in line:
                leaf_type, rel_path = line.split("=", 1)
                detectors[leaf_type.strip()] = rel_path.strip()
    return detectors


def _routing_file_name(top_level_dir: Path) -> str:
    return top_level_dir.name.upper() + ".md"


def _leaf_type(directory: Path, detectors: dict[str, str]) -> str | None:
    if (directory / ".harnessleaf").exists():
        return "leaf"
    for ltype, rel_path in detectors.items():
        if (directory / rel_path).exists():
            return ltype
    return None


def load_content(harness_path: Path, rel_path: str) -> str:
    target = harness_path / rel_path
    detectors = _load_leaf_detectors(harness_path)

    if target.is_dir():
        ltype = _leaf_type(target, detectors)
        if ltype is not None:
            primary_rel = detectors.get(ltype)
            if primary_rel and (target / primary_rel).exists():
                result = (target / primary_rel).read_text()
                scripts = list((target / "scripts").glob("*")) if (target / "scripts").exists() else []
                if scripts:
                    result += "\n\nAvailable scripts: " + ", ".join(s.name for s in scripts)
                return result
            return "\n".join(f.name for f in sorted(target.iterdir()))

        # Find the top-level ancestor to derive the routing file name
        parts = Path(rel_path).parts
        routing_name = parts[0].upper() + ".md" if parts else "HARNESS.md"
        routing_file = target / routing_name
        if routing_file.exists():
            return routing_file.read_text()

        # Fall back to listing the directory
        return "\n".join(f.name for f in sorted(target.iterdir()))

    return target.read_bytes().decode(errors="replace")