atdd 0.5.0__py3-none-any.whl → 0.6.1__py3-none-any.whl

atdd/coach/schemas/config.schema.json

@@ -58,6 +58,69 @@
       },
       "required": ["last_version"],
       "additionalProperties": false
+    },
+    "coverage": {
+      "type": "object",
+      "description": "Hierarchy coverage validation settings (ATDD Hierarchy Coverage Spec v0.1)",
+      "properties": {
+        "exceptions": {
+          "type": "object",
+          "description": "Allow-lists for coverage exceptions",
+          "properties": {
+            "wagons_not_in_train": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Wagon slugs allowed without train coverage"
+            },
+            "features_orphaned": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Feature URNs allowed without wagon manifest reference"
+            },
+            "wmbts_without_acceptance": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "WMBT URNs allowed without acceptance criteria"
+            },
+            "acceptance_without_tests": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Acceptance URNs allowed without test coverage"
+            },
+            "contracts_unreferenced": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Contract URNs allowed without produce/consume"
+            },
+            "telemetry_unreferenced": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Telemetry URNs allowed without references"
+            },
+            "features_without_implementation": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Feature URNs allowed without code implementation"
+            }
+          },
+          "additionalProperties": false
+        },
+        "thresholds": {
+          "type": "object",
+          "description": "Coverage threshold settings",
+          "properties": {
+            "min_acceptance_coverage": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100,
+              "default": 80,
+              "description": "Minimum percentage of acceptances that must have tests"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": ["version", "release"],

atdd/coach/templates/ATDD.md

@@ -71,7 +71,7 @@ code:
 # Dev Servers
 dev_servers:
   backend:
-    command: "cd python && python3 game.py"
+    command: "cd python && python3 app.py"
     url: "http://127.0.0.1:8000"
     swagger: "http://127.0.0.1:8000/docs"
   frontend:

atdd/coach/utils/coverage_phase.py

@@ -0,0 +1,97 @@
+"""
+ATDD Hierarchy Coverage Spec v0.1 Rollout Phase Controller.
+
+Manages the phased rollout of coverage validation rules:
+- Phase 1 (WARNINGS_ONLY): All validators emit warnings only
+- Phase 2 (PLANNER_TESTER_ENFORCEMENT): Sections 2 + 3 validators strict
+- Phase 3 (FULL_ENFORCEMENT): All validators (including Section 4) strict
+
+Usage in validators:
+    from atdd.coach.utils.coverage_phase import CoveragePhase, should_enforce
+
+    if should_enforce(CoveragePhase.PLANNER_TESTER_ENFORCEMENT):
+        assert condition, "Error message"
+    else:
+        if not condition:
+            emit_coverage_warning("COVERAGE-PLAN-2.1", "Warning message", CoveragePhase.PLANNER_TESTER_ENFORCEMENT)
+"""
+
+from enum import IntEnum
+from typing import Optional
+import warnings
+
+
+class CoveragePhase(IntEnum):
+    """
+    Rollout phases for ATDD Hierarchy Coverage Spec v0.1.
+
+    Phases are ordered by strictness level:
+    - WARNINGS_ONLY (1): All new validators emit warnings, no assertions
+    - PLANNER_TESTER_ENFORCEMENT (2): Planner (Section 2) + Tester (Section 3) strict
+    - FULL_ENFORCEMENT (3): All validators including Coder (Section 4) strict
+    """
+    WARNINGS_ONLY = 1
+    PLANNER_TESTER_ENFORCEMENT = 2
+    FULL_ENFORCEMENT = 3
+
+
+# Current rollout phase - update this to advance through phases
+CURRENT_PHASE = CoveragePhase.WARNINGS_ONLY
+
+
+def should_enforce(validator_phase: CoveragePhase) -> bool:
+    """
+    Check if a validator should enforce strict mode.
+
+    Args:
+        validator_phase: The phase at which this validator becomes strict
+
+    Returns:
+        True if current phase >= validator_phase (should enforce)
+        False if current phase < validator_phase (should warn only)
+
+    Example:
+        # This validator becomes strict in Phase 2
+        if should_enforce(CoveragePhase.PLANNER_TESTER_ENFORCEMENT):
+            assert wagon_in_train, "Wagon must be in at least one train"
+        else:
+            if not wagon_in_train:
+                emit_coverage_warning("COVERAGE-PLAN-2.1", "Wagon not in any train", CoveragePhase.PLANNER_TESTER_ENFORCEMENT)
+    """
+    return CURRENT_PHASE >= validator_phase
+
+
+def get_current_phase() -> CoveragePhase:
+    """Get the current rollout phase."""
+    return CURRENT_PHASE
+
+
+def get_phase_name(phase: Optional[CoveragePhase] = None) -> str:
+    """Get human-readable name for a phase."""
+    phase = phase or CURRENT_PHASE
+    return {
+        CoveragePhase.WARNINGS_ONLY: "Phase 1: Warnings Only",
+        CoveragePhase.PLANNER_TESTER_ENFORCEMENT: "Phase 2: Planner+Tester Enforcement",
+        CoveragePhase.FULL_ENFORCEMENT: "Phase 3: Full Enforcement",
+    }.get(phase, "Unknown Phase")
+
+
+def emit_coverage_warning(
+    spec_id: str,
+    message: str,
+    validator_phase: CoveragePhase = CoveragePhase.PLANNER_TESTER_ENFORCEMENT
+) -> None:
+    """
+    Emit a coverage validation warning with phase context.
+
+    Args:
+        spec_id: The SPEC ID (e.g., "COVERAGE-PLAN-2.1")
+        message: The warning message
+        validator_phase: Phase when this becomes an error
+    """
+    phase_name = get_phase_name(validator_phase)
+    warnings.warn(
+        f"[{spec_id}] {message} (will become error in {phase_name})",
+        category=UserWarning,
+        stacklevel=3
+    )

atdd/coach/validators/shared_fixtures.py

@@ -445,3 +445,157 @@ def pytest_html_results_summary(prefix, summary, postfix):
         'against platform schemas and conventions.</p>'
         '</div>'
     ])
+
+
+# ============================================================================
+# COVERAGE VALIDATION FIXTURES (ATDD Hierarchy Coverage Spec v0.1)
+# ============================================================================
+
+
+@pytest.fixture(scope="module")
+def coverage_exceptions(atdd_config: Dict[str, Any]) -> Dict[str, List[str]]:
+    """
+    Load coverage exception allow-lists from .atdd/config.yaml.
+
+    Returns:
+        Dict mapping exception type to list of allowed URNs/slugs
+    """
+    return atdd_config.get("coverage", {}).get("exceptions", {})
+
+
+@pytest.fixture(scope="module")
+def coverage_thresholds(atdd_config: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Load coverage threshold settings from .atdd/config.yaml.
+
+    Returns:
+        Dict with threshold settings (min_acceptance_coverage, etc.)
+    """
+    defaults = {"min_acceptance_coverage": 80}
+    thresholds = atdd_config.get("coverage", {}).get("thresholds", {})
+    return {**defaults, **thresholds}
+
+
+@pytest.fixture(scope="module")
+def feature_files() -> List[Tuple[Path, Dict[str, Any]]]:
+    """
+    Discover all feature files in plan/*/features/.
+
+    Returns:
+        List of (path, feature_data) tuples
+    """
+    import re
+    features = []
+    if not PLAN_DIR.exists():
+        return features
+
+    for wagon_dir in PLAN_DIR.iterdir():
+        if wagon_dir.is_dir() and not wagon_dir.name.startswith("_"):
+            features_dir = wagon_dir / "features"
+            if features_dir.exists():
+                for feature_file in features_dir.glob("*.yaml"):
+                    try:
+                        with open(feature_file) as f:
+                            data = yaml.safe_load(f)
+                            if data:
+                                features.append((feature_file, data))
+                    except Exception:
+                        pass
+    return features
+
+
+@pytest.fixture(scope="module")
+def wmbt_files() -> List[Tuple[Path, Dict[str, Any]]]:
+    """
+    Discover all WMBT files in plan/*/.
+
+    WMBT files match pattern: [DLPCEMYRK]NNN.yaml (e.g., D001.yaml, L010.yaml)
+
+    Returns:
+        List of (path, wmbt_data) tuples
+    """
+    import re
+    wmbts = []
+    if not PLAN_DIR.exists():
+        return wmbts
+
+    wmbt_pattern = re.compile(r"^[DLPCEMYRK]\d{3}\.yaml$")
+
+    for wagon_dir in PLAN_DIR.iterdir():
+        if wagon_dir.is_dir() and not wagon_dir.name.startswith("_"):
+            for wmbt_file in wagon_dir.glob("*.yaml"):
+                if wmbt_pattern.match(wmbt_file.name):
+                    try:
+                        with open(wmbt_file) as f:
+                            data = yaml.safe_load(f)
+                            if data:
+                                wmbts.append((wmbt_file, data))
+                    except Exception:
+                        pass
+    return wmbts
+
+
+@pytest.fixture(scope="module")
+def acceptance_urns_by_wagon(wmbt_files: List[Tuple[Path, Dict[str, Any]]]) -> Dict[str, List[str]]:
+    """
+    Extract all acceptance URNs grouped by wagon slug.
+
+    Returns:
+        Dict mapping wagon slug to list of acceptance URNs
+    """
+    by_wagon: Dict[str, List[str]] = {}
+
+    for path, wmbt_data in wmbt_files:
+        # Derive wagon slug from directory name (snake_case -> kebab-case)
+        wagon_slug = path.parent.name.replace("_", "-")
+
+        if wagon_slug not in by_wagon:
+            by_wagon[wagon_slug] = []
+
+        for acc in wmbt_data.get("acceptances", []):
+            if isinstance(acc, dict) and "identity" in acc:
+                urn = acc["identity"].get("urn", "")
+                if urn:
+                    by_wagon[wagon_slug].append(urn)
+            elif isinstance(acc, str):
+                by_wagon[wagon_slug].append(acc)
+
+    return by_wagon
+
+
+@pytest.fixture(scope="module")
+def all_acceptance_urns(acceptance_urns_by_wagon: Dict[str, List[str]]) -> List[str]:
+    """
+    Get flat list of all acceptance URNs across all wagons.
+
+    Returns:
+        List of all acceptance URNs
+    """
+    all_urns = []
+    for urns in acceptance_urns_by_wagon.values():
+        all_urns.extend(urns)
+    return all_urns
+
+
+@pytest.fixture(scope="module")
+def wagon_to_train_mapping(train_files: List[Tuple[Path, Dict]]) -> Dict[str, List[str]]:
+    """
+    Build mapping of wagon slugs to train IDs that reference them.
+
+    Returns:
+        Dict mapping wagon slug to list of train IDs
+    """
+    mapping: Dict[str, List[str]] = {}
+
+    for train_path, train_data in train_files:
+        train_id = train_data.get("train_id", train_path.stem)
+        participants = train_data.get("participants", [])
+
+        for participant in participants:
+            if isinstance(participant, str) and participant.startswith("wagon:"):
+                wagon_slug = participant.replace("wagon:", "")
+                if wagon_slug not in mapping:
+                    mapping[wagon_slug] = []
+                mapping[wagon_slug].append(train_id)
+
+    return mapping

atdd/coder/conventions/backend.convention.yaml

@@ -281,7 +281,7 @@ backend:
 
             direct_adapter:
               pattern: "direct_*_client.py"
-              use_when: "Wagons run in same process (monolith via game.py)"
+              use_when: "Wagons run in same process (monolith via app.py)"
               example: "DirectCommitStateClient reads from shared StateRepository"
               benefits:
                 - "No network latency"

atdd/coder/conventions/boundaries.convention.yaml

@@ -243,7 +243,7 @@ interaction:
 
   composition_roots:
     description: |
-      Composition roots (composition.py, wagon.py, trains/runner.py, game.py) are entrypoints
+      Composition roots (composition.py, wagon.py, trains/runner.py, app.py) are entrypoints
       that wire dependencies. They are executed, never imported by other code.
 
     feature_composition:
@@ -332,15 +332,15 @@ interaction:
     # ========================================================================
     station_master_pattern:
       description: |
-        When multiple wagons run in a single process (game.py), the Station Master
+        When multiple wagons run in a single process (app.py), the Station Master
         pattern enables shared dependency injection without HTTP self-calls.
 
-        game.py creates shared singletons (StateRepository, EventBus, etc.) and
+        app.py creates shared singletons (StateRepository, EventBus, etc.) and
         passes them to wagon composition.py functions, which decide internally
         whether to use Direct adapters (monolith) or HTTP adapters (microservices).
 
       architecture: |
-        game.py (Station Master / Thin Router)
+        app.py (Station Master / Thin Router)
           │
           ├── Creates shared singletons:
           │     - StateRepository (commit-state data)
@@ -391,7 +391,7 @@ interaction:
               """Wire dependencies with optional SharedDependencies.
 
               Args:
-                  shared: SharedDependencies from game.py (monolith mode).
+                  shared: SharedDependencies from app.py (monolith mode).
                           When provided, uses Direct adapters for cross-wagon data.
                           When None, uses Fake adapters for standalone testing.
               """
@@ -424,7 +424,7 @@ interaction:
           Same interface (implements Port), different implementation.
 
       station_master_responsibilities:
-        game_py:
+        app_py:
           - "Create shared singletons (StateRepository, EventBus)"
           - "Pass shared deps to wagon composition.py"
           - "Include wagon routers in FastAPI app"
@@ -440,12 +440,12 @@ interaction:
         required:
           - "composition.py accepts optional shared dependency parameters"
           - "Direct adapters exist for cross-wagon data access"
-          - "game.py calls composition.py, not duplicates wiring"
+          - "app.py calls composition.py, not duplicates wiring"
 
         forbidden:
-          - "game.py creating use cases that composition.py should own"
+          - "app.py creating use cases that composition.py should own"
           - "HTTP clients calling localhost in production monolith"
-          - "Duplicated wiring logic between game.py and composition.py"
+          - "Duplicated wiring logic between app.py and composition.py"
 
   forbidden_cross_wagon_imports:
     rule: "Code in wagon A MUST NOT import directly from wagon B"

atdd/coder/conventions/coverage.convention.yaml

@@ -0,0 +1,85 @@
+version: "1.0"
+name: "Coder Coverage Convention"
+description: "Section 4 of ATDD Hierarchy Coverage Spec v0.1 - Ensures code implementation covers all features"
+
+rules:
+  - id: "COVERAGE-CODE-4.1"
+    name: "Feature - Implementation Coverage"
+    description: "Every feature must have corresponding code implementation"
+    requirement: "Each feature's components must map to code paths"
+    exceptions: "features_without_implementation allow-list"
+    validator: "test_all_features_have_implementations"
+
+  - id: "COVERAGE-CODE-4.2"
+    name: "Implementation - Tests Coverage"
+    description: "Every implementation must have at least one linked test"
+    requirement: "Each implementation must have at least one linked test"
+    validator: "test_all_implementations_have_tests"
+
+coverage_graph:
+  description: "The coder coverage graph ensures features are implemented and tested"
+  levels:
+    - name: "Feature"
+      implemented_by: "Code files in python/, supabase/, web/"
+      validators: ["COVERAGE-CODE-4.1"]
+
+    - name: "Implementation"
+      tested_by: "Test files referencing feature/component"
+      validators: ["COVERAGE-CODE-4.2"]
+
+exception_handling:
+  description: "How exceptions are handled in coder coverage validation"
+  allow_lists:
+    features_without_implementation:
+      description: "Feature URNs that are allowed without code implementation"
+      use_case: "Planned features, design-only features, or features implemented externally"
+      config_path: "coverage.exceptions.features_without_implementation"
+
+implementation_patterns:
+  description: "How features map to code implementations"
+
+  python:
+    location: "python/{wagon}/"
+    patterns:
+      - "use_case_{feature_slug}.py"
+      - "service_{feature_slug}.py"
+      - "{feature_slug}_handler.py"
+    example: "python/maintain_ux/use_case_provide_foundations.py"
+
+  typescript:
+    location: "supabase/functions/{wagon}/{feature}/"
+    patterns:
+      - "index.ts"
+      - "handler.ts"
+      - "{feature_slug}.ts"
+    example: "supabase/functions/maintain-ux/provide-foundations/index.ts"
+
+  web:
+    location: "web/src/features/{wagon}/{feature}/"
+    patterns:
+      - "index.tsx"
+      - "{feature_slug}.tsx"
+      - "components/"
+    example: "web/src/features/maintain-ux/provide-foundations/index.tsx"
+
+test_patterns:
+  description: "How implementations map to tests"
+
+  python:
+    location: "python/{wagon}/"
+    filename: "test_*.py"
+    reference_method: "Import or reference to implementation module"
+
+  typescript:
+    location: "supabase/functions/{wagon}/{feature}/test/"
+    filename: "*.test.ts"
+    reference_method: "Import or reference to implementation"
+
+  web:
+    location: "web/tests/{wagon}/{feature}/"
+    filename: "*.test.tsx"
+    reference_method: "Import or reference to component"
+
+rollout:
+  phase: "FULL_ENFORCEMENT"
+  description: "Section 4 validators become strict in Phase 3 (after planner+tester)"

atdd/coder/conventions/presentation.convention.yaml

@@ -540,25 +540,25 @@ validation:
       - "Simple error handling has TODO(REFACTOR) marker"
 
     unified_game_server:
-      description: "python/game.py must aggregate all wagon presentation layers"
-      file: "python/game.py"
+      description: "python/app.py must aggregate all wagon presentation layers"
+      file: "python/app.py"
       requirements:
-        - "When new wagon adds FastAPI controller, game.py MUST be updated"
-        - "game.py imports controller's app and includes via app.include_router()"
+        - "When new wagon adds FastAPI controller, app.py MUST be updated"
+        - "app.py imports controller's app and includes via app.include_router()"
         - "All wagon endpoints accessible via unified game server"
-        - "Validator checks: all wagons with presentation are registered in game.py"
+        - "Validator checks: all wagons with presentation are registered in app.py"
 
       rationale: |
-        game.py is the unified entry point for all backend services.
+        app.py is the unified entry point for all backend services.
         Without registration, wagon endpoints are inaccessible to game server/mobile app.
 
       pattern: |
-        # python/game.py
+        # python/app.py
         from burn_timebank.track_remaining.src.presentation.controllers.remaining_controller import app as timebank_app
         app.include_router(timebank_app.router, prefix="/timebank")
 
       anti_pattern: |
-        # ❌ WRONG: Wagon has FastAPI controller but not registered in game.py
+        # ❌ WRONG: Wagon has FastAPI controller but not registered in app.py
         # Result: Endpoints exist but unreachable from unified server
 
   usage: |

atdd/coder/conventions/train.convention.yaml

@@ -8,8 +8,8 @@ rationale: |
   defined in YAML specifications by coordinating wagons through contract-based communication.
 
   TRANSFORMATION (SESSION-12):
-    - OLD: Trains in e2e/ (test-only), custom orchestration in game.py
-    - NEW: Trains in python/trains/ (production), game.py becomes thin Station Master
+    - OLD: Trains in e2e/ (test-only), custom orchestration in app.py
+    - NEW: Trains in python/trains/ (production), app.py becomes thin Station Master
 
   BENEFITS:
     - Single source of truth (YAML defines both production AND tests)
@@ -21,7 +21,7 @@ cross_references:
   composition_hierarchy:
     - file: "refactor.convention.yaml"
       section: "composition_root.hierarchy"
-      note: "Trains add new orchestration layer between game.py and wagon.py"
+      note: "Trains add new orchestration layer between app.py and wagon.py"
 
   boundaries:
     - file: "boundaries.convention.yaml"
@@ -37,14 +37,15 @@ cross_references:
 # ============================================================================
 
 composition_hierarchy:
-  description: "Trains sit between application (game.py) and wagons (wagon.py)"
+  description: "Trains sit between application (app.py) and wagons (wagon.py)"
 
   levels:
     application:
-      file: "python/game.py"
+      file: "python/app.py"
       role: "Station Master - thin router"
       responsibility: "Map user actions → train_ids, invoke TrainRunner"
       size: "< 50 lines of routing logic"
+      note: "app.py is the Station Master entrypoint"
 
     train:
       file: "python/trains/runner.py"
@@ -65,8 +66,8 @@ composition_hierarchy:
 
   dependency_flow:
     rule: "Dependencies flow downward only"
-    chain: "game.py → trains.runner → wagon.py → composition.py → src/"
-    forbidden: "NEVER: wagon imports from trains or game"
+    chain: "app.py → trains.runner → wagon.py → composition.py → src/"
+    forbidden: "NEVER: wagon imports from trains or app"
 
 # ============================================================================
 # TRAIN INFRASTRUCTURE
@@ -138,7 +139,7 @@ wagon_train_mode:
   multi_mode_pattern:
     description: "Wagons support multiple execution modes"
     cli: "Interactive demo (python3 wagon.py)"
-    http: "API endpoints (via game.py)"
+    http: "API endpoints (via app.py)"
     train: "Production orchestration (via TrainRunner)"
 
 # ============================================================================
@@ -170,14 +171,14 @@ cargo_pattern:
     method: "JSON Schema Draft-07 validation"
 
 # ============================================================================
-# STATION MASTER PATTERN (game.py)
+# STATION MASTER PATTERN (app.py)
 # ============================================================================
 
 station_master:
-  description: "game.py becomes thin router that delegates to TrainRunner"
+  description: "app.py becomes thin router that delegates to TrainRunner"
 
   pattern: |
-    # game.py - Station Master
+    # app.py - Station Master
     from trains.runner import TrainRunner
 
     JOURNEY_MAP = {
@@ -198,7 +199,7 @@ station_master:
     - "Translate HTTP ↔ artifacts"
     - "Handle errors"
 
-  anti_pattern: "Business logic in game.py (belongs in trains/wagons)"
+  anti_pattern: "Business logic in app.py (belongs in trains/wagons)"
 
 # ============================================================================
 # TESTING
@@ -278,10 +279,10 @@ observability:
 # ============================================================================
 
 migration:
-  step_1: "Identify user journeys in game.py"
+  step_1: "Identify user journeys in app.py"
   step_2: "Create train YAML (plan/_trains/{train_id}.yaml)"
   step_3: "Add run_train() to participating wagons"
-  step_4: "Refactor game.py to Station Master pattern"
+  step_4: "Refactor app.py to Station Master pattern"
   step_5: "Update tests to use TrainRunner"
 
 # ============================================================================

atdd/coder/validators/conftest.py

@@ -0,0 +1,5 @@
+"""
+Shared fixtures for coder tests.
+"""
+# Import all shared fixtures from coach via absolute import
+from atdd.coach.validators.shared_fixtures import *