atdd 0.7.1__py3-none-any.whl → 0.7.3__py3-none-any.whl

atdd/coach/validators/test_session_manifest_alignment.py

@@ -0,0 +1,387 @@
+"""
+Session-manifest alignment validation.
+
+Ensures session files and manifest entries are synchronized:
+1. Every manifest entry has a corresponding session file
+2. Every session file has a manifest entry
+3. Status in session frontmatter matches manifest status
+
+Convention: src/atdd/coach/conventions/session.convention.yaml
+Schema: src/atdd/coach/schemas/manifest.schema.json
+
+Run: atdd validate coach
+"""
+import pytest
+import yaml
+from pathlib import Path
+from typing import Dict, List, Any, Optional, Tuple
+
+from atdd.coach.utils.repo import find_repo_root
+
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+REPO_ROOT = find_repo_root()
+SESSIONS_DIR = REPO_ROOT / "atdd-sessions"
+ARCHIVE_DIR = SESSIONS_DIR / "archive"
+MANIFEST_FILE = REPO_ROOT / ".atdd" / "manifest.yaml"
+
+# Valid statuses from convention
+VALID_STATUSES = {"INIT", "PLANNED", "ACTIVE", "BLOCKED", "COMPLETE", "OBSOLETE", "UNKNOWN"}
+
+
+# ============================================================================
+# Fixtures
+# ============================================================================
+
+@pytest.fixture
+def manifest() -> Optional[Dict[str, Any]]:
+    """Load session manifest from .atdd/manifest.yaml."""
+    if not MANIFEST_FILE.exists():
+        return None
+
+    with open(MANIFEST_FILE) as f:
+        return yaml.safe_load(f)
+
+
+@pytest.fixture
+def session_files() -> List[Path]:
+    """Get all session files (excluding template, including archive)."""
+    if not SESSIONS_DIR.exists():
+        return []
+
+    files = []
+
+    # Main sessions directory
+    for f in SESSIONS_DIR.glob("SESSION-*.md"):
+        if f.name != "SESSION-TEMPLATE.md":
+            files.append(f)
+
+    # Archive directory
+    if ARCHIVE_DIR.exists():
+        for f in ARCHIVE_DIR.glob("SESSION-*.md"):
+            files.append(f)
+
+    return sorted(files)
+
+
+def parse_session_frontmatter(path: Path) -> Optional[Dict[str, Any]]:
+    """Parse YAML frontmatter from session file."""
+    content = path.read_text()
+
+    if not content.startswith("---"):
+        return None
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return None
+
+    try:
+        return yaml.safe_load(parts[1])
+    except yaml.YAMLError:
+        return None
+
+
+def get_session_id_from_filename(filename: str) -> Optional[str]:
+    """Extract session ID from filename (e.g., SESSION-01-foo.md -> 01)."""
+    import re
+    match = re.match(r"SESSION-(\d{2})-", filename)
+    return match.group(1) if match else None
+
+
+# ============================================================================
+# Manifest Entry Validation Tests
+# ============================================================================
+
+@pytest.mark.coach
+def test_manifest_exists():
+    """
+    SPEC-COACH-MANIFEST-001: Manifest file exists
+
+    Given: Initialized ATDD project
+    When: Checking for manifest file
+    Then: .atdd/manifest.yaml exists
+    """
+    if not (REPO_ROOT / ".atdd").exists():
+        pytest.skip("ATDD not initialized (no .atdd/ directory)")
+
+    assert MANIFEST_FILE.exists(), \
+        f"Manifest file not found at {MANIFEST_FILE}. Run 'atdd init' first."
+
+
+@pytest.mark.coach
+def test_manifest_entries_have_session_files(manifest: Optional[Dict], session_files: List[Path]):
+    """
+    SPEC-COACH-MANIFEST-002: Every manifest entry has a corresponding session file
+
+    Given: Session manifest with entries
+    When: Checking for session files
+    Then: Each manifest entry has a matching file on disk
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    sessions_dir = manifest.get("sessions_dir", "atdd-sessions")
+    missing = []
+
+    for entry in manifest.get("sessions", []):
+        file_path = entry.get("file", "")
+        session_id = entry.get("id", "")
+
+        # Resolve full path
+        full_path = REPO_ROOT / sessions_dir / file_path
+
+        if not full_path.exists():
+            missing.append(f"id={session_id}: {file_path}")
+
+    if missing:
+        pytest.fail(
+            f"Found {len(missing)} manifest entries without session files:\n" +
+            "\n".join(f"  - {m}" for m in missing)
+        )
+
+
+@pytest.mark.coach
+def test_session_files_have_manifest_entries(manifest: Optional[Dict], session_files: List[Path]):
+    """
+    SPEC-COACH-MANIFEST-003: Every session file has a manifest entry
+
+    Given: Session files in atdd-sessions/
+    When: Checking manifest entries
+    Then: Each session file has a corresponding manifest entry
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    if not session_files:
+        pytest.skip("No session files found")
+
+    # Build set of manifest file paths
+    sessions_dir = manifest.get("sessions_dir", "atdd-sessions")
+    manifest_files = set()
+
+    for entry in manifest.get("sessions", []):
+        file_path = entry.get("file", "")
+        manifest_files.add(file_path)
+
+    # Check each session file
+    orphaned = []
+
+    for session_path in session_files:
+        # Compute relative path from sessions_dir
+        try:
+            rel_path = session_path.relative_to(REPO_ROOT / sessions_dir)
+            rel_str = str(rel_path)
+        except ValueError:
+            rel_str = session_path.name
+
+        if rel_str not in manifest_files:
+            orphaned.append(session_path.name)
+
+    if orphaned:
+        pytest.fail(
+            f"Found {len(orphaned)} session files without manifest entries:\n" +
+            "\n".join(f"  - {o}" for o in orphaned) +
+            "\n\nRun 'atdd session sync' to update manifest."
+        )
+
+
+@pytest.mark.coach
+def test_manifest_status_matches_session_frontmatter(manifest: Optional[Dict]):
+    """
+    SPEC-COACH-MANIFEST-004: Manifest status matches session frontmatter status
+
+    Given: Session manifest with status fields
+    When: Comparing to session file frontmatter
+    Then: Status values match (or warning on mismatch)
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    sessions_dir = manifest.get("sessions_dir", "atdd-sessions")
+    mismatches = []
+
+    for entry in manifest.get("sessions", []):
+        file_path = entry.get("file", "")
+        session_id = entry.get("id", "")
+        manifest_status = entry.get("status", "UNKNOWN").upper()
+
+        # Load session file
+        full_path = REPO_ROOT / sessions_dir / file_path
+        if not full_path.exists():
+            continue
+
+        frontmatter = parse_session_frontmatter(full_path)
+        if frontmatter is None:
+            continue
+
+        # Compare status
+        file_status = str(frontmatter.get("status", "UNKNOWN")).upper()
+        # Handle status with extra info (e.g., "ACTIVE - working on X")
+        file_status_word = file_status.split()[0] if file_status else "UNKNOWN"
+
+        if file_status_word != manifest_status:
+            mismatches.append(
+                f"SESSION-{session_id}: manifest={manifest_status}, file={file_status_word}"
+            )
+
+    if mismatches:
+        # Warn but don't fail - mismatches may be intentional during transitions
+        print(
+            f"\n⚠️  Found {len(mismatches)} status mismatches between manifest and files:\n" +
+            "\n".join(f"  - {m}" for m in mismatches) +
+            "\n\nRun 'atdd session sync' to reconcile."
+        )
+
+
+@pytest.mark.coach
+def test_manifest_type_matches_session_frontmatter(manifest: Optional[Dict]):
+    """
+    SPEC-COACH-MANIFEST-005: Manifest type matches session frontmatter type
+
+    Given: Session manifest with type fields
+    When: Comparing to session file frontmatter
+    Then: Type values match
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    sessions_dir = manifest.get("sessions_dir", "atdd-sessions")
+    mismatches = []
+
+    for entry in manifest.get("sessions", []):
+        file_path = entry.get("file", "")
+        session_id = entry.get("id", "")
+        manifest_type = entry.get("type", "unknown").lower()
+
+        # Load session file
+        full_path = REPO_ROOT / sessions_dir / file_path
+        if not full_path.exists():
+            continue
+
+        frontmatter = parse_session_frontmatter(full_path)
+        if frontmatter is None:
+            continue
+
+        # Compare type
+        file_type = str(frontmatter.get("type", "unknown")).lower()
+
+        if file_type != manifest_type:
+            mismatches.append(
+                f"SESSION-{session_id}: manifest={manifest_type}, file={file_type}"
+            )
+
+    if mismatches:
+        pytest.fail(
+            f"Found {len(mismatches)} type mismatches between manifest and files:\n" +
+            "\n".join(f"  - {m}" for m in mismatches)
+        )
+
+
+@pytest.mark.coach
+def test_manifest_ids_are_unique(manifest: Optional[Dict]):
+    """
+    SPEC-COACH-MANIFEST-006: Manifest session IDs are unique
+
+    Given: Session manifest
+    When: Checking session IDs
+    Then: No duplicate IDs exist
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    ids = {}
+    duplicates = []
+
+    for entry in manifest.get("sessions", []):
+        session_id = entry.get("id", "")
+        file_path = entry.get("file", "")
+
+        if session_id in ids:
+            duplicates.append(f"id={session_id}: {ids[session_id]} AND {file_path}")
+        else:
+            ids[session_id] = file_path
+
+    if duplicates:
+        pytest.fail(
+            f"Found duplicate session IDs in manifest:\n" +
+            "\n".join(f"  - {d}" for d in duplicates)
+        )
+
+
+@pytest.mark.coach
+def test_manifest_file_ids_match_filename(manifest: Optional[Dict]):
+    """
+    SPEC-COACH-MANIFEST-007: Manifest entry ID matches filename
+
+    Given: Session manifest entries
+    When: Comparing ID to filename pattern
+    Then: Entry ID matches SESSION-{ID}-* in filename
+    """
+    if manifest is None:
+        pytest.skip("No manifest file found")
+
+    mismatches = []
+
+    for entry in manifest.get("sessions", []):
+        session_id = entry.get("id", "")
+        file_path = entry.get("file", "")
+
+        # Extract ID from filename
+        filename = Path(file_path).name
+        file_id = get_session_id_from_filename(filename)
+
+        if file_id and file_id != session_id:
+            mismatches.append(
+                f"id={session_id} but filename has id={file_id}: {file_path}"
+            )
+
+    if mismatches:
+        pytest.fail(
+            f"Found {len(mismatches)} ID mismatches between manifest and filenames:\n" +
+            "\n".join(f"  - {m}" for m in mismatches)
+        )
+
+
+# ============================================================================
+# Summary
+# ============================================================================
+
+@pytest.mark.coach
+def test_manifest_alignment_summary(manifest: Optional[Dict], session_files: List[Path]):
+    """
+    Generate a summary of manifest alignment.
+
+    This test always passes but prints a summary.
+    """
+    if manifest is None:
+        print("\n⚠️  No manifest file found. Run 'atdd init' to create one.")
+        return
+
+    manifest_count = len(manifest.get("sessions", []))
+    file_count = len(session_files)
+
+    print("\n" + "=" * 60)
+    print("SESSION MANIFEST ALIGNMENT SUMMARY")
+    print("=" * 60)
+    print(f"\nManifest entries: {manifest_count}")
+    print(f"Session files:    {file_count}")
+
+    if manifest_count == file_count:
+        print("\n✅ Manifest and files are aligned")
+    else:
+        print(f"\n⚠️  Difference: {abs(manifest_count - file_count)} entries")
+
+    # Status breakdown
+    statuses = {}
+    for entry in manifest.get("sessions", []):
+        status = entry.get("status", "UNKNOWN")
+        statuses[status] = statuses.get(status, 0) + 1
+
+    print("\nBy Status:")
+    for status, count in sorted(statuses.items()):
+        print(f"  {status}: {count}")
+
+    print("\n" + "=" * 60)

atdd/coach/validators/test_session_validation.py

@@ -21,6 +21,7 @@ from typing import List, Dict, Optional, Set, Tuple, Any
 import yaml
 
 from atdd.coach.utils.repo import find_repo_root
+from atdd.coach.utils.config import load_atdd_config
 
 # ============================================================================
 # Configuration
@@ -498,6 +499,166 @@ def test_session_has_gate_commands(active_session_files: List[Path]):
         pytest.fail(f"Missing gate commands:\n" + "\n".join(f"  - {m}" for m in missing))
 
 
+# ============================================================================
+# Gate Command Prefix Validation
+# ============================================================================
+
+# Default allowed command prefixes
+DEFAULT_GATE_COMMAND_PREFIXES = [
+    "atdd",
+    "pytest",
+    "python",
+    "npm",
+    "supabase",
+    "cd",  # Allow cd for directory changes before commands
+]
+
+
+@pytest.fixture
+def coach_config() -> Dict[str, Any]:
+    """Load coach configuration from .atdd/config.yaml."""
+    config = load_atdd_config(REPO_ROOT)
+    return config.get("coach", {})
+
+
+@pytest.fixture
+def gate_command_prefixes(coach_config: Dict[str, Any]) -> List[str]:
+    """Get allowed gate command prefixes from config."""
+    return coach_config.get(
+        "session_gate_command_prefixes",
+        DEFAULT_GATE_COMMAND_PREFIXES
+    )
+
+
+@pytest.fixture
+def gate_command_exceptions(coach_config: Dict[str, Any]) -> List[str]:
+    """Get session files exempt from gate command validation."""
+    return coach_config.get("session_gate_command_exceptions", [])
+
+
+def extract_gate_commands(body: str) -> List[str]:
+    """
+    Extract commands from code blocks in session body.
+
+    Returns list of command strings found in ```bash or ```shell blocks.
+    """
+    import re
+
+    commands = []
+
+    # Match code blocks with bash/shell language hint
+    code_block_pattern = re.compile(
+        r"```(?:bash|shell|sh)?\n(.*?)```",
+        re.DOTALL
+    )
+
+    for match in code_block_pattern.finditer(body):
+        block_content = match.group(1)
+        # Extract individual commands (non-empty lines)
+        for line in block_content.strip().split('\n'):
+            line = line.strip()
+            # Skip comments and empty lines
+            if line and not line.startswith('#'):
+                commands.append(line)
+
+    return commands
+
+
+def command_matches_prefix(command: str, prefixes: List[str]) -> bool:
+    """
+    Check if command starts with an allowed prefix.
+
+    Handles:
+    - Direct prefix match: "pytest tests/"
+    - Path prefix: "./atdd/atdd.py" matches "atdd"
+    - Chained commands: "cd foo && pytest" (each part checked)
+    """
+    import re
+
+    # Split on && and || to check each command part
+    parts = re.split(r'\s*(?:&&|\|\|)\s*', command)
+
+    for part in parts:
+        part = part.strip()
+        if not part:
+            continue
+
+        # Check direct prefix match
+        matched = False
+        for prefix in prefixes:
+            # Direct match
+            if part.startswith(prefix + " ") or part == prefix:
+                matched = True
+                break
+            # Path match (e.g., ./atdd/atdd.py matches "atdd")
+            if "/" in part:
+                cmd_name = part.split()[0].split("/")[-1]
+                # Remove .py extension
+                if cmd_name.endswith(".py"):
+                    cmd_name = cmd_name[:-3]
+                if cmd_name == prefix:
+                    matched = True
+                    break
+
+        if not matched:
+            return False
+
+    return True
+
+
+def test_session_gate_commands_use_canonical_prefixes(
+    active_session_files: List[Path],
+    gate_command_prefixes: List[str],
+    gate_command_exceptions: List[str]
+):
+    """
+    Test that gate commands use canonical command prefixes.
+
+    Given: Active session files with gate commands
+    When: Checking command prefixes in code blocks
+    Then: All commands start with allowed prefixes from config
+
+    Configurable via .atdd/config.yaml:
+        coach:
+          session_gate_command_prefixes: ["atdd", "pytest", "npm"]
+          session_gate_command_exceptions: ["SESSION-00-*.md"]
+    """
+    import fnmatch
+
+    violations = []
+
+    for f in active_session_files:
+        # Check if file is exempt
+        is_exempt = any(
+            fnmatch.fnmatch(f.name, pattern)
+            for pattern in gate_command_exceptions
+        )
+        if is_exempt:
+            continue
+
+        parsed = parse_session_file(f)
+        body = parsed["body"]
+
+        commands = extract_gate_commands(body)
+
+        for cmd in commands:
+            if not command_matches_prefix(cmd, gate_command_prefixes):
+                # Extract first word for clearer error message
+                first_word = cmd.split()[0] if cmd.split() else cmd
+                violations.append(
+                    f"{f.name}: '{first_word}...' not in allowed prefixes"
+                )
+
+    if violations:
+        pytest.fail(
+            f"Found {len(violations)} gate commands with non-canonical prefixes:\n" +
+            "\n".join(f"  - {v}" for v in violations[:20]) +
+            (f"\n  ... and {len(violations) - 20} more" if len(violations) > 20 else "") +
+            f"\n\nAllowed prefixes: {gate_command_prefixes}\n"
+            "Configure in .atdd/config.yaml: coach.session_gate_command_prefixes"
+        )
+
+
 # ============================================================================
 # Pre-Implementation Gate
 # ============================================================================

atdd/planner/conventions/train.convention.yaml

@@ -257,6 +257,23 @@ registry:
   structure: "theme-category-grouped"
   description: "Trains grouped by theme, then by category (nominal/error/alternate/exception) in _trains.yaml manifest"
 
+  # Two-file pattern: Registry + Per-Train Spec Files
+  two_file_pattern:
+    description: "Each train requires two files: a registry entry and a spec file"
+    files:
+      registry:
+        path: "plan/_trains.yaml"
+        purpose: "Central manifest listing all trains with summary metadata"
+        contains: "train_id, description, path, wagons (summary list)"
+      spec:
+        path: "plan/_trains/{train_id}.yaml"
+        purpose: "Full train specification with complete workflow definition"
+        contains: "train_id, title, themes, participants, sequence, dependencies, test, code, expectations"
+    validation:
+      rule: "Every registry entry MUST have a corresponding spec file"
+      validator: "SPEC-TRAIN-VAL-0003 (test_train_files_exist_for_registry_entries)"
+      enforcement: "Planner phase gate fails if spec file missing"
+
   format: |
     trains:
       0-commons:

atdd/planner/validators/test_plan_wagons.py

@@ -95,6 +95,72 @@ def test_wagon_slugs_match_directory_names(wagon_manifests):
                 f"Wagon slug '{wagon_slug}' doesn't match expected slug '{expected_slug}' (from directory '{directory_name}') for {path}"
 
 
+@pytest.mark.platform
+def test_wagon_names_follow_verb_object_pattern(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0008: Wagon names follow verb-object semantic pattern
+
+    Given: All wagon manifests
+    When: Checking wagon name format
+    Then: Wagon names follow verb-object pattern (e.g., resolve-dilemmas, commit-state)
+          - Format: verb-object (kebab-case, at least 2 hyphen-separated words)
+          - First segment should be a verb (action)
+          - Subsequent segments describe the object/domain
+          Per naming.convention.yaml wagon section
+    """
+    import re
+
+    # Pattern: verb-object with optional additional words (e.g., burn-timebank, juggle-domains)
+    # Requires at least 2 segments separated by hyphens
+    verb_object_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:
+        wagon_name = manifest.get("wagon", "")
+        if wagon_name:
+            assert verb_object_pattern.match(wagon_name), \
+                f"Wagon {path}: name '{wagon_name}' doesn't follow verb-object pattern (e.g., resolve-dilemmas)"
+
+
+@pytest.mark.platform
+def test_feature_names_follow_verb_object_pattern(wagon_manifests):
+    """
+    SPEC-PLATFORM-WAGONS-0009: Feature names follow verb-object semantic pattern
+
+    Given: All wagon manifests with features[] entries
+    When: Checking feature name format from URNs
+    Then: Feature names follow verb-object pattern (e.g., capture-choice, pair-fragments)
+          - URN format: feature:{wagon}:{feature-name}
+          - Feature name requires at least 2 hyphen-separated words
+          Per naming.convention.yaml feature section
+    """
+    import re
+
+    # Pattern: verb-object with optional additional words
+    verb_object_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:
+        features_list = manifest.get("features", [])
+        wagon_name = manifest.get("wagon", "")
+
+        for feature in features_list:
+            feature_name = None
+
+            # Extract feature name from URN
+            if isinstance(feature, dict) and "urn" in feature:
+                urn = feature["urn"]
+                parts = urn.split(":")
+                if len(parts) >= 3:
+                    feature_name = parts[2]
+            elif isinstance(feature, str) and feature.startswith("feature:"):
+                parts = feature.split(":")
+                if len(parts) >= 3:
+                    feature_name = parts[2]
+
+            if feature_name:
+                assert verb_object_pattern.match(feature_name), \
+                    f"Wagon {wagon_name}: feature '{feature_name}' doesn't follow verb-object pattern (e.g., capture-choice)"
+
+
 @pytest.mark.platform
 def test_produce_artifact_names_follow_convention(wagon_manifests):
     """
@@ -153,9 +219,10 @@ def test_telemetry_urns_match_pattern(wagon_manifests):
 
     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
+    Then: Telemetry URNs match pattern telemetry:{path}:{aspect}(.{variant})?
+          - Colons (:) for hierarchical descent (e.g., telemetry:commons:ux:foundations)
+          - Dots (.) for lateral variants (e.g., telemetry:mechanic:decision.choice)
+          Per telemetry.convention.yaml id_vs_urn section
     """
     import re