atdd 0.2.1__py3-none-any.whl

atdd/planner/validators/test_plan_uniqueness.py

@@ -0,0 +1,224 @@
+"""
+Platform tests: Uniqueness constraints.
+
+Validates that entities have unique identifiers across the repository.
+Tests ensure no duplicate wagon slugs, train IDs, or WMBT IDs.
+"""
+import pytest
+from collections import Counter
+from typing import Dict, List, Any
+
+
+@pytest.mark.platform
+def test_wagon_slugs_are_unique(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0001: Wagon slugs are unique across repository
+
+    Given: All wagon manifests
+    When: Checking wagon slug uniqueness
+    Then: Each wagon slug appears exactly once
+          No two wagons share the same slug
+    """
+    wagon_slugs = [manifest.get("wagon", "") for _, manifest in wagon_manifests]
+    slug_counts = Counter(wagon_slugs)
+
+    duplicates = {slug: count for slug, count in slug_counts.items() if count > 1}
+
+    assert not duplicates, \
+        f"Found duplicate wagon slugs:\n" + \
+        "\n".join(f"  '{slug}': {count} occurrences" for slug, count in duplicates.items())
+
+
+@pytest.mark.platform
+def test_train_ids_are_unique(trains_registry):
+    """
+    SPEC-PLATFORM-UNIQUE-0002: Train IDs are unique across repository
+
+    Given: All train definitions in plan/_trains.yaml
+    When: Checking train_id uniqueness
+    Then: Each train_id appears exactly once
+    """
+    train_ids = [train.get("train_id", "") for train in trains_registry.get("trains", [])]
+    train_id_counts = Counter(train_ids)
+
+    duplicates = {tid: count for tid, count in train_id_counts.items() if count > 1}
+
+    assert not duplicates, \
+        f"Found duplicate train IDs:\n" + \
+        "\n".join(f"  '{tid}': {count} occurrences" for tid, count in duplicates.items())
+
+
+@pytest.mark.platform
+def test_produce_artifact_names_unique_per_wagon(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0003: Produce artifact names unique within each wagon
+
+    Given: Wagon produce items
+    When: Checking artifact name uniqueness per wagon
+    Then: Each wagon has unique produce artifact names
+          No wagon produces the same artifact name twice
+    """
+    errors = []
+
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+        artifact_names = [item.get("name", "") for item in manifest.get("produce", [])]
+
+        name_counts = Counter(artifact_names)
+        duplicates = {name: count for name, count in name_counts.items() if count > 1}
+
+        if duplicates:
+            errors.append(
+                f"Wagon '{wagon_slug}' at {path} has duplicate produce names:\n" +
+                "\n".join(f"    '{name}': {count} occurrences" for name, count in duplicates.items())
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+def test_wmbt_ids_unique_per_wagon(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0004: WMBT IDs are unique within each wagon
+
+    Given: Wagon WMBT definitions
+    When: Checking WMBT ID uniqueness per wagon
+    Then: Each wagon has unique WMBT IDs
+          No wagon defines the same WMBT ID twice
+    """
+    errors = []
+
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+        wmbt_section = manifest.get("wmbt", {})
+
+        # WMBT section can be dict or list - handle both formats
+        if isinstance(wmbt_section, dict):
+            wmbt_ids = list(wmbt_section.keys())
+        elif isinstance(wmbt_section, list):
+            wmbt_ids = [item.get("id", "") for item in wmbt_section]
+        else:
+            continue  # Skip if wmbt is not dict or list
+
+        wmbt_id_counts = Counter(wmbt_ids)
+        duplicates = {wid: count for wid, count in wmbt_id_counts.items() if count > 1}
+
+        if duplicates:
+            errors.append(
+                f"Wagon '{wagon_slug}' at {path} has duplicate WMBT IDs:\n" +
+                "\n".join(f"    '{wid}': {count} occurrences" for wid, count in duplicates.items())
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+def test_feature_urns_unique_per_wagon(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0005: Feature URNs are unique within each wagon
+
+    Given: Wagon feature definitions (URN array format)
+    When: Checking feature URN uniqueness per wagon
+    Then: Each wagon has unique feature URNs
+          No wagon defines the same feature URN twice
+    """
+    errors = []
+
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+        features = manifest.get("features", [])
+
+        # Features can be array of URN objects or legacy dict - handle array format
+        if isinstance(features, list):
+            feature_urns = [item.get("urn", "") for item in features if isinstance(item, dict)]
+
+            urn_counts = Counter(feature_urns)
+            duplicates = {urn: count for urn, count in urn_counts.items() if count > 1}
+
+            if duplicates:
+                errors.append(
+                    f"Wagon '{wagon_slug}' at {path} has duplicate feature URNs:\n" +
+                    "\n".join(f"    '{urn}': {count} occurrences" for urn, count in duplicates.items())
+                )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+def test_contract_urns_unique_globally(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0006: Contract URNs are unique globally
+
+    Given: All contract URNs from wagon produce items
+    When: Checking global uniqueness
+    Then: Each contract URN is produced by exactly one wagon
+          No two wagons produce the same contract URN
+    """
+    contract_to_wagons: Dict[str, List[str]] = {}
+
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+
+        for produce_item in manifest.get("produce", []):
+            contract = produce_item.get("contract")
+            if contract and contract is not None:
+                contract_to_wagons.setdefault(contract, []).append(wagon_slug)
+
+    # Find contracts produced by multiple wagons
+    duplicates = {
+        contract: wagons
+        for contract, wagons in contract_to_wagons.items()
+        if len(wagons) > 1
+    }
+
+    if duplicates:
+        pytest.fail(
+            f"Found contract URNs produced by multiple wagons:\n" +
+            "\n".join(
+                f"  '{contract}': {wagons}"
+                for contract, wagons in duplicates.items()
+            )
+        )
+
+
+@pytest.mark.platform
+def test_telemetry_urns_unique_globally(wagon_manifests):
+    """
+    SPEC-PLATFORM-UNIQUE-0007: Telemetry URNs are unique globally
+
+    Given: All telemetry URNs from wagon produce items
+    When: Checking global uniqueness
+    Then: Each telemetry URN is produced by exactly one wagon
+          No two wagons produce the same telemetry URN
+    """
+    telemetry_to_wagons: Dict[str, List[str]] = {}
+
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+
+        for produce_item in manifest.get("produce", []):
+            telemetry = produce_item.get("telemetry")
+            if telemetry and telemetry is not None:
+                # Handle both string and list types
+                telemetry_urns = telemetry if isinstance(telemetry, list) else [telemetry]
+                for urn in telemetry_urns:
+                    telemetry_to_wagons.setdefault(urn, []).append(wagon_slug)
+
+    # Find telemetry URNs produced by multiple wagons
+    duplicates = {
+        telemetry: wagons
+        for telemetry, wagons in telemetry_to_wagons.items()
+        if len(wagons) > 1
+    }
+
+    if duplicates:
+        pytest.fail(
+            f"Found telemetry URNs produced by multiple wagons:\n" +
+            "\n".join(
+                f"  '{telemetry}': {wagons}"
+                for telemetry, wagons in duplicates.items()
+            )
+        )

atdd/planner/validators/test_plan_urn_resolution.py

@@ -0,0 +1,268 @@
+"""
+Platform tests: URN resolution to filesystem.
+
+Validates that contract and telemetry URNs resolve to actual directories/files.
+Tests ensure URN to filesystem mapping follows conventions.
+"""
+import pytest
+from pathlib import Path
+from typing import Tuple
+
+# Path constants
+REPO_ROOT = Path(__file__).resolve().parents[4]
+CONTRACTS_DIR = REPO_ROOT / "contracts"
+TELEMETRY_DIR = REPO_ROOT / "telemetry"
+
+
+def parse_urn(urn: str) -> Tuple:
+    """Parse URN into components.
+
+    Returns tuple of (type, *path_parts) where:
+    - type: contract or telemetry
+    - path_parts: remaining segments (2+ for multi-level paths)
+    - Both : and . create directory levels per artifact-naming convention
+
+    Examples:
+    - contract:ux:foundations → ('contract', 'ux', 'foundations')
+    - telemetry:commons:ux:foundations → ('telemetry', 'commons', 'ux', 'foundations')
+    - telemetry:match:dilemma.paired → ('telemetry', 'match', 'dilemma', 'paired')
+    """
+    import re
+    parts = urn.split(":", 1)  # Split into [type, rest]
+    if len(parts) < 2:
+        raise ValueError(f"Invalid URN format: {urn} (must have URN type)")
+
+    urn_type = parts[0]
+    rest = parts[1]
+
+    # Split rest by both : and . per artifact-naming convention
+    segments = re.split(r'[:\.]', rest)
+
+    if len(segments) < 2:
+        raise ValueError(f"Invalid URN format: {urn} (must have at least 2 path segments)")
+
+    return tuple([urn_type] + segments)
+
+
+@pytest.mark.platform
+@pytest.mark.e2e
+def test_contract_urn_resolves_to_directory(contract_urns):
+    """
+    SPEC-PLATFORM-URN-0001: Contract URNs resolve to filesystem directories
+
+    Given: A contract URN from wagon produce (e.g., contract:ux:foundations)
+    When: Mapping URN to filesystem path
+    Then: contracts/{domain}/{resource}/ directory exists
+          OR contracts/{domain}/ exists (for domain-level contracts)
+    """
+    errors = []
+
+    for contract_urn in contract_urns:
+        parts = parse_urn(contract_urn)
+        urn_type = parts[0]
+        path_parts = parts[1:]  # All parts after 'contract:'
+
+        # Expected path: contracts/{path_parts joined}/
+        # For contract:commons:player:identity -> contracts/commons/player/identity/
+        # For contract:ux:foundations -> contracts/ux/foundations/
+        expected_path = CONTRACTS_DIR / Path(*path_parts)
+
+        # Also check for domain-level contracts: contracts/{domain}/
+        domain_path = CONTRACTS_DIR / path_parts[0] if len(path_parts) >= 1 else None
+
+        if not (expected_path.exists() or (domain_path and domain_path.exists())):
+            errors.append(
+                f"Contract URN {contract_urn} does not resolve to filesystem:\n"
+                f"  Expected: {expected_path} OR {domain_path}\n"
+                f"  Neither path exists"
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+@pytest.mark.e2e
+def test_telemetry_urn_resolves_to_directory(telemetry_urns):
+    """
+    SPEC-PLATFORM-URN-0002: Telemetry URNs resolve to filesystem directories
+
+    Given: A telemetry URN from wagon produce
+    When: Mapping URN to filesystem path
+    Then: telemetry/{path}/ directory exists (multi-level paths supported)
+
+    Examples:
+    - telemetry:ux:foundations → telemetry/ux/foundations/
+    - telemetry:commons:ux:foundations → telemetry/commons/ux/foundations/
+    """
+    errors = []
+
+    for telemetry_urn in telemetry_urns:
+        parts = parse_urn(telemetry_urn)
+        urn_type = parts[0]
+        path_parts = parts[1:]  # All parts after 'telemetry:'
+
+        # Expected path: telemetry/{path}/{to}/{aspect}/
+        expected_path = TELEMETRY_DIR / Path(*path_parts)
+
+        if not expected_path.exists():
+            errors.append(
+                f"Telemetry URN {telemetry_urn} does not resolve to filesystem:\n"
+                f"  Expected: {expected_path}\n"
+                f"  Path does not exist"
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+@pytest.mark.e2e
+def test_telemetry_directory_contains_signal_files(telemetry_urns):
+    """
+    SPEC-PLATFORM-URN-0003: Telemetry directories contain signal JSON files
+
+    Given: A telemetry URN that resolves to a directory
+    When: Checking directory contents
+    Then: Directory contains *.json files (signal definitions)
+          Signal files follow pattern: {aspect}.{signal-type}.{plane}[.{measure}].json
+    """
+    errors = []
+
+    for telemetry_urn in telemetry_urns:
+        parts = parse_urn(telemetry_urn)
+        path_parts = parts[1:]  # All parts after 'telemetry:'
+        telemetry_path = TELEMETRY_DIR / Path(*path_parts)
+
+        if not telemetry_path.exists():
+            continue  # Tested in URN-0002
+
+        # Find all JSON files in directory
+        json_files = list(telemetry_path.glob("*.json"))
+
+        if not json_files:
+            errors.append(
+                f"Telemetry directory {telemetry_path} exists but contains no *.json signal files"
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+def test_all_contract_urns_are_unique(contract_urns):
+    """
+    SPEC-PLATFORM-URN-0004: Contract URNs are unique across wagons
+
+    Given: All contract URNs from wagon produce items
+    When: Checking for duplicates
+    Then: Each contract URN appears only once
+          No two wagons produce the same contract URN
+    """
+    from collections import Counter
+
+    # contract_urns fixture already returns unique URNs (set to sorted)
+    # This test validates the assumption
+    urn_counts = Counter(contract_urns)
+    duplicates = {urn: count for urn, count in urn_counts.items() if count > 1}
+
+    assert not duplicates, \
+        f"Found duplicate contract URNs (should be unique):\n" + \
+        "\n".join(f"  {urn}: {count} occurrences" for urn, count in duplicates.items())
+
+
+@pytest.mark.platform
+def test_all_telemetry_urns_are_unique(telemetry_urns):
+    """
+    SPEC-PLATFORM-URN-0005: Telemetry URNs are unique across wagons
+
+    Given: All telemetry URNs from wagon produce items
+    When: Checking for duplicates
+    Then: Each telemetry URN appears only once
+          No two wagons produce the same telemetry URN
+    """
+    from collections import Counter
+
+    # telemetry_urns fixture already returns unique URNs
+    urn_counts = Counter(telemetry_urns)
+    duplicates = {urn: count for urn, count in urn_counts.items() if count > 1}
+
+    assert not duplicates, \
+        f"Found duplicate telemetry URNs (should be unique):\n" + \
+        "\n".join(f"  {urn}: {count} occurrences" for urn, count in duplicates.items())
+
+
+@pytest.mark.platform
+def test_contracts_directory_structure_matches_urns(contract_urns):
+    """
+    SPEC-PLATFORM-URN-0006: contracts/ structure aligns with URN domain/resource
+
+    Given: Contract URNs and contracts/ directory
+    When: Comparing URN domain/resource to directory structure
+    Then: For each contract URN contract:domain:resource,
+          contracts/{domain}/{resource}/ exists OR contracts/{domain}/ exists
+    """
+    if not CONTRACTS_DIR.exists():
+        pytest.skip(f"contracts/ directory does not exist at {CONTRACTS_DIR}")
+        return
+
+    missing_paths = []
+
+    for urn in contract_urns:
+        parts = parse_urn(urn)
+        urn_type = parts[0]
+        path_parts = parts[1:]  # All parts after 'contract:'
+
+        # Expected path: contracts/{path_parts joined}/
+        resource_path = CONTRACTS_DIR / Path(*path_parts)
+        domain_path = CONTRACTS_DIR / path_parts[0] if len(path_parts) >= 1 else None
+
+        if not (resource_path.exists() or (domain_path and domain_path.exists())):
+            missing_paths.append(
+                f"  {urn} -> Expected: {resource_path} OR {domain_path}"
+            )
+
+    if missing_paths:
+        pytest.fail(
+            f"Found {len(missing_paths)} contract URNs without matching filesystem paths:\n" +
+            "\n".join(missing_paths[:10]) +
+            (f"\n  ... and {len(missing_paths) - 10} more" if len(missing_paths) > 10 else "")
+        )
+
+
+@pytest.mark.platform
+def test_telemetry_directory_structure_matches_urns(telemetry_urns):
+    """
+    SPEC-PLATFORM-URN-0007: telemetry/ structure aligns with URN hierarchy
+
+    Given: Telemetry URNs and telemetry/ directory
+    When: Comparing URN path to directory structure
+    Then: For each telemetry URN telemetry:{path}:{aspect},
+          telemetry/{path}/{aspect}/ exists (supports multi-level paths)
+
+    Examples:
+    - telemetry:ux:foundations → telemetry/ux/foundations/
+    - telemetry:commons:ux:foundations → telemetry/commons/ux/foundations/
+    """
+    if not TELEMETRY_DIR.exists():
+        pytest.skip(f"telemetry/ directory does not exist at {TELEMETRY_DIR}")
+        return
+
+    missing_paths = []
+
+    for urn in telemetry_urns:
+        parts = parse_urn(urn)
+        path_parts = parts[1:]  # All parts after 'telemetry:'
+        expected_path = TELEMETRY_DIR / Path(*path_parts)
+
+        if not expected_path.exists():
+            missing_paths.append(
+                f"  {urn} -> Expected: {expected_path}"
+            )
+
+    if missing_paths:
+        pytest.fail(
+            f"Found {len(missing_paths)} telemetry URNs without matching filesystem paths:\n" +
+            "\n".join(missing_paths[:10]) +
+            (f"\n  ... and {len(missing_paths) - 10} more" if len(missing_paths) > 10 else "")
+        )

atdd/planner/validators/test_plan_wagons.py

@@ -0,0 +1,174 @@
+"""
+Platform tests: Wagon manifest schema validation.
+
+Validates that all wagon manifests in plan/ conform to wagon.schema.json.
+Tests are parametrized to run once per wagon manifest for surgical diagnostics.
+"""
+import pytest
+import jsonschema
+from pathlib import Path
+
+
+@pytest.mark.platform
+@pytest.mark.e2e
+def test_wagon_manifest_matches_schema(wagon_schema, wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0001: Wagon manifest validates against wagon.schema.json
+
+    Given: A wagon manifest YAML file in plan/
+    When: Validated against .claude/schemas/planner/wagon.schema.json
+    Then: Validation passes with no schema errors
+          All required fields are present
+          URN patterns match expected format
+    """
+    errors = []
+
+    for manifest_path, manifest in wagon_manifests:
+        try:
+            jsonschema.validate(manifest, wagon_schema)
+        except jsonschema.ValidationError as e:
+            errors.append(
+                f"Wagon manifest validation failed for {manifest_path}:\n"
+                f"  Error: {e.message}\n"
+                f"  Path: {' -> '.join(str(p) for p in e.path)}\n"
+                f"  Schema path: {' -> '.join(str(p) for p in e.schema_path)}"
+            )
+
+    if errors:
+        pytest.fail("\n\n".join(errors))
+
+
+@pytest.mark.platform
+def test_all_wagons_have_required_fields(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0002: All wagons have required top-level fields
+
+    Given: All wagon manifests
+    When: Checking required fields
+    Then: Each wagon has: wagon, description, subject, context, action, goal, outcome
+    """
+    required_fields = ["wagon", "description", "subject", "context", "action", "goal", "outcome"]
+
+    for path, manifest in wagon_manifests:
+        missing_fields = [field for field in required_fields if field not in manifest]
+        assert not missing_fields, \
+            f"Wagon {path} missing required fields: {missing_fields}"
+
+
+@pytest.mark.platform
+def test_all_produce_items_have_contract_and_telemetry(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0003: All produce items have contract and telemetry fields
+
+    Given: All wagon manifests with produce items
+    When: Checking produce item structure
+    Then: Each produce item has 'contract' and 'telemetry' fields
+          Fields can be null but must be present
+    """
+    for path, manifest in wagon_manifests:
+        for idx, produce_item in enumerate(manifest.get("produce", [])):
+            assert "contract" in produce_item, \
+                f"Wagon {path}: produce[{idx}] missing 'contract' field"
+            assert "telemetry" in produce_item, \
+                f"Wagon {path}: produce[{idx}] missing 'telemetry' field"
+
+
+@pytest.mark.platform
+def test_wagon_slugs_match_directory_names(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0004: Wagon slugs match their directory names
+
+    Given: Wagon manifests in plan/{wagon_dirname}/ directories
+    When: Comparing wagon field to directory name
+    Then: Wagon slug (kebab-case) matches directory name (snake_case) after conversion
+          Per SPEC-COACH-UTILS-0281: slug.replace('-','_')→dirname, dirname.replace('_','-')→slug
+    """
+    for path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "")
+
+        # Check if manifest is in a wagon-specific directory (not in plan/ root)
+        if path.parent.name != "plan":
+            directory_name = path.parent.name
+            # Convert directory name (snake_case) to expected slug (kebab-case)
+            expected_slug = directory_name.replace('_', '-')
+            assert wagon_slug == expected_slug, \
+                f"Wagon slug '{wagon_slug}' doesn't match expected slug '{expected_slug}' (from directory '{directory_name}') for {path}"
+
+
+@pytest.mark.platform
+def test_produce_artifact_names_follow_convention(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0005: Produce artifact names follow naming convention
+
+    Given: Wagon produce items
+    When: Checking artifact name format
+    Then: Names follow pattern per artifact-naming.convention.yaml:
+          - Hierarchy: domain:resource (colon for hierarchy)
+          - Variants: domain:resource.variant (dot for facets)
+          - Can have unlimited colons, typically 0-1 dots
+    """
+    import re
+
+    # Pattern: domain(:category)*:aspect(.variant)? per artifact-naming.convention.yaml
+    # Allows: commons:auth, commons:auth.claims, commons:ux:foundations:color.primary
+    name_pattern = re.compile(r"^[a-z][a-z0-9\-]*:[a-z][a-z0-9\-:]*(\.[a-z][a-z0-9\-]+)?$")
+
+    for path, manifest in wagon_manifests:
+        for produce_item in manifest.get("produce", []):
+            name = produce_item.get("name", "")
+            if name:  # Skip empty names
+                assert name_pattern.match(name), \
+                    f"Wagon {path}: produce artifact name '{name}' doesn't match pattern per artifact-naming.convention.yaml"
+
+
+@pytest.mark.platform
+def test_contract_urns_match_pattern(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0006: Contract URNs follow naming convention
+
+    Given: Wagon produce items with non-null contract URNs
+    When: Validating URN format
+    Then: Contract URNs match pattern per artifact-naming.convention.yaml:
+          contract:{artifact_name} where artifact_name can have colons and dots
+          Pattern: contract:domain(:category)*:aspect(.variant)?
+    """
+    import re
+
+    # URN exactly matches artifact name with "contract:" prefix
+    # Per artifact-naming.convention.yaml line 627-645
+    contract_pattern = re.compile(r"^contract:[a-z][a-z0-9\-]*:[a-z][a-z0-9\-:]*(\.[a-z][a-z0-9\-]+)?$")
+
+    for path, manifest in wagon_manifests:
+        for produce_item in manifest.get("produce", []):
+            contract = produce_item.get("contract")
+            if contract and contract is not None:
+                assert contract_pattern.match(contract), \
+                    f"Wagon {path}: contract URN '{contract}' doesn't match pattern per artifact-naming.convention.yaml"
+
+
+@pytest.mark.platform
+def test_telemetry_urns_match_pattern(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0007: Telemetry URNs follow multi-level pattern
+
+    Given: Wagon produce items with non-null telemetry URNs
+    When: Validating URN format
+    Then: Telemetry URNs match pattern telemetry:{path}:{aspect}
+          Supports multi-level paths (e.g., telemetry:commons:ux:foundations)
+          Uses colons (not dots) for hierarchy
+    """
+    import re
+
+    # Pattern: telemetry: followed by 2+ colon-separated segments (kebab-case), optional dot for variant
+    # Supports: telemetry:commons:ux:foundations, telemetry:match:dilemma.paired
+    telemetry_pattern = re.compile(r"^telemetry:([a-z][a-z0-9\-]*:)+[a-z][a-z0-9\-]*(\.[a-z][a-z0-9\-]*)?$")
+
+    for path, manifest in wagon_manifests:
+        for produce_item in manifest.get("produce", []):
+            telemetry = produce_item.get("telemetry")
+            if telemetry and telemetry is not None:
+                # Handle both string and list types
+                telemetry_urns = telemetry if isinstance(telemetry, list) else [telemetry]
+                for urn in telemetry_urns:
+                    assert telemetry_pattern.match(urn), \
+                        f"Wagon {path}: telemetry URN '{urn}' doesn't match pattern telemetry:{{path}}:{{aspect}}"