atdd 0.2.12__py3-none-any.whl → 0.3.1__py3-none-any.whl

atdd/cli.py

@@ -44,6 +44,7 @@ from atdd.coach.commands.initializer import ProjectInitializer
 from atdd.coach.commands.session import SessionManager
 from atdd.coach.commands.sync import AgentConfigSync
 from atdd.coach.commands.gate import ATDDGate
+from atdd.coach.utils.repo import find_repo_root
 from atdd.version_check import print_update_notice
 
 
@@ -57,8 +58,8 @@ class ATDDCoach:
     - Coder: Implementation phase validation
     """
 
-    def __init__(self):
-        self.repo_root = ATDD_DIR.parent
+    def __init__(self, repo_root: Path = None):
+        self.repo_root = repo_root or find_repo_root()
         self.inventory = RepositoryInventory(self.repo_root)
         self.test_runner = TestRunner(self.repo_root)
         self.registry_updater = RegistryUpdater(self.repo_root)
@@ -290,6 +291,14 @@ Phase descriptions:
 
     # ----- Existing flag-based arguments (backwards compatible) -----
 
+    # Repository root override
+    parser.add_argument(
+        "--repo",
+        type=str,
+        metavar="PATH",
+        help="Target repository root (default: auto-detect from .atdd/)"
+    )
+
     # Main command groups
     parser.add_argument(
         "--inventory",
@@ -394,8 +403,9 @@ Phase descriptions:
 
     # ----- Handle flag-based commands (backwards compatible) -----
 
-    # Create coach instance
-    coach = ATDDCoach()
+    # Create coach instance with optional repo override
+    repo_path = Path(args.repo) if args.repo else None
+    coach = ATDDCoach(repo_root=repo_path)
 
     # Handle commands
     if args.inventory:

atdd/coach/commands/inventory.py

@@ -26,7 +26,7 @@ class RepositoryInventory:
     """Generate comprehensive repository inventory."""
 
     def __init__(self, repo_root: Path = None):
-        self.repo_root = repo_root or Path(__file__).parent.parent
+        self.repo_root = repo_root or Path.cwd()
         self.inventory = {
             "inventory": {
                 "generated_at": datetime.now().isoformat(),
@@ -288,7 +288,7 @@ class RepositoryInventory:
         feature_files = len(python_tests) + len(ts_tests)
 
         meta_cases = planner_cases + tester_cases + coder_cases + platform_cases
-        feature_cases = python_cases  # Dart/TS case counting would require parsing those languages
+        feature_cases = python_cases  # TS case counting would require parsing those languages
 
         return {
             "total_files": meta_files + feature_files,
@@ -312,13 +312,11 @@ class RepositoryInventory:
             "feature_tests": {
                 "files": {
                     "python": len(python_tests),
-                    "dart": len(dart_tests),
                     "typescript": len(ts_tests),
                     "total": feature_files
                 },
                 "cases": {
                     "python": python_cases,
-                    "dart": "not_counted",
                     "typescript": "not_counted",
                     "total": feature_cases
                 }

atdd/coach/commands/test_runner.py

@@ -15,7 +15,7 @@ class TestRunner:
     """Run ATDD meta-tests with various configurations."""
 
     def __init__(self, repo_root: Path = None):
-        self.repo_root = repo_root or Path(__file__).parent.parent.parent.parent
+        self.repo_root = repo_root or Path.cwd()
         self.atdd_dir = self.repo_root / "atdd"
 
     def run_tests(

atdd/coach/templates/ATDD.md

@@ -13,6 +13,11 @@ missions:
 #
 # PROTOCOL:
 # ---------
+# 0. TOOL GATE (MANDATORY)
+#    If your agent supports plan mode (Claude Code, etc.), enable it NOW.
+#    This is a tool capability gate, NOT the ATDD Planner phase.
+#    If unavailable, state: "Plan mode unavailable" and proceed.
+#
 # 1. Run this command FIRST:
 #
 #    atdd gate

atdd/coach/templates/SESSION-TEMPLATE.md

@@ -1,3 +1,12 @@
+<!--
+# =============================================================================
+# TOOL GATE (MANDATORY BEFORE FILLING THIS FILE)
+# =============================================================================
+# If your agent supports plan mode (Claude Code, etc.), enable it NOW.
+# This is a tool capability gate, NOT the ATDD Planner phase.
+# If unavailable, state: "Plan mode unavailable" and proceed.
+# =============================================================================
+-->
 ---
 # SESSION METADATA (YAML frontmatter - machine-parseable)
 #

atdd/coach/utils/__init__.py

@@ -0,0 +1,5 @@
+"""ATDD Coach utilities."""
+
+from atdd.coach.utils.repo import find_repo_root, require_repo_root
+
+__all__ = ["find_repo_root", "require_repo_root"]

atdd/coach/utils/repo.py

@@ -0,0 +1,97 @@
+"""
+Repository root detection utility.
+
+Finds the consumer repository root using multiple detection strategies:
+1. .atdd/manifest.yaml (preferred - explicit ATDD project marker)
+2. plan/ AND contracts/ both exist (ATDD project structure)
+3. .git/ directory (fallback - any git repo)
+4. cwd (last resort - allows commands to work on uninitialized repos)
+
+This ensures ATDD commands operate on the user's repo, not the package root.
+"""
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+
+@lru_cache(maxsize=1)
+def find_repo_root(start: Optional[Path] = None) -> Path:
+    """
+    Find repo root by searching upward for ATDD project markers.
+
+    Detection order (first match wins):
+    1. .atdd/manifest.yaml - explicit ATDD project marker
+    2. plan/ AND contracts/ both exist - ATDD project structure
+    3. .git/ directory - fallback for any git repository
+    4. cwd - last resort if no markers found
+
+    Args:
+        start: Starting directory (default: cwd)
+
+    Returns:
+        Path to repo root (falls back to cwd if no markers found)
+
+    Note:
+        Results are cached for performance. If .atdd/manifest.yaml is not found,
+        commands may operate in a degraded mode.
+    """
+    current = start or Path.cwd()
+    current = current.resolve()
+
+    while current != current.parent:
+        # Strategy 1: .atdd/manifest.yaml (preferred)
+        if (current / ".atdd" / "manifest.yaml").is_file():
+            return current
+
+        # Strategy 2: plan/ AND contracts/ both exist
+        if (current / "plan").is_dir() and (current / "contracts").is_dir():
+            return current
+
+        # Strategy 3: .git/ directory (fallback)
+        if (current / ".git").is_dir():
+            return current
+
+        current = current.parent
+
+    # Strategy 4: Return starting directory as last resort
+    # Commands can handle uninitialized repos appropriately
+    return start.resolve() if start else Path.cwd().resolve()
+
+
+def require_repo_root(start: Optional[Path] = None) -> Path:
+    """
+    Find repo root, raising RuntimeError if no markers found.
+
+    This is a stricter version of find_repo_root() for commands that
+    require a valid ATDD project structure.
+
+    Args:
+        start: Starting directory (default: cwd)
+
+    Returns:
+        Path to repo root
+
+    Raises:
+        RuntimeError: If no ATDD project markers (.atdd/manifest.yaml,
+                     plan/ + contracts/, or .git/) are found
+    """
+    current = start or Path.cwd()
+    current = current.resolve()
+    start_path = current
+
+    while current != current.parent:
+        # Check for any valid marker
+        if (current / ".atdd" / "manifest.yaml").is_file():
+            return current
+        if (current / "plan").is_dir() and (current / "contracts").is_dir():
+            return current
+        if (current / ".git").is_dir():
+            return current
+
+        current = current.parent
+
+    raise RuntimeError(
+        f"No ATDD project markers found searching from {start_path}. "
+        "Expected one of: .atdd/manifest.yaml, plan/ + contracts/, or .git/"
+    )

atdd/coach/validators/shared_fixtures.py

@@ -118,6 +118,8 @@ def wagon_manifests() -> List[Tuple[Path, Dict[str, Any]]]:
                             manifests.append((manifest_path, manifest_data))
 
     # Also discover individual wagon manifests (pattern: plan/*/_{wagon}.yaml)
+    if not PLAN_DIR.exists():
+        return manifests
     for wagon_dir in PLAN_DIR.iterdir():
         if wagon_dir.is_dir() and not wagon_dir.name.startswith("_"):
             for manifest_file in wagon_dir.glob("_*.yaml"):

atdd/tester/conventions/security.convention.yaml

@@ -0,0 +1,165 @@
+version: "1.0"
+name: "Security Convention"
+description: "Security validation rules for contract schemas"
+
+# Validator Specifications
+validators:
+  - id: "SPEC-TESTER-SEC-0001"
+    name: "Secured operations must declare auth headers"
+    test: "test_secured_operations_have_required_headers"
+    mode: "hard"
+    description: |
+      Secured operations must include appropriate authentication headers
+      based on their declared security scheme. This ensures that all
+      protected endpoints have proper header declarations for auth tokens.
+
+  - id: "SPEC-TESTER-SEC-0002"
+    name: "Operations must have explicit security field"
+    test: "test_operations_have_explicit_security"
+    mode: "soft (xfail)"
+    description: |
+      All API operations should declare their security requirements explicitly.
+      Use security: [] for public endpoints and security: [{...}] for protected.
+      This ensures security posture is intentional, not accidental.
+
+  - id: "SPEC-TESTER-SEC-0003"
+    name: "Secured operations need SEC/RLS acceptance coverage"
+    test: "test_secured_operations_have_security_acceptance"
+    mode: "soft (xfail)"
+    description: |
+      Secured operations must have at least one acceptance criteria using
+      the SEC (Security) or RLS (Row-Level Security) harness. This ensures
+      security requirements are tested.
+
+  - id: "SPEC-TESTER-SEC-0004"
+    name: "Error responses should not expose sensitive data"
+    test: "test_error_responses_have_no_sensitive_fields"
+    mode: "warning only"
+    description: |
+      Error responses (4xx/5xx) should not contain fields with sensitive
+      names like password, secret, credential, ssn, api_key, private_key.
+      This prevents accidental exposure of sensitive data in error messages.
+
+# Security Scheme to Header Mapping
+scheme_header_mapping:
+  jwt:
+    headers: ["authorization"]
+    format: "Bearer {token}"
+    description: "JSON Web Token authentication"
+
+  bearer:
+    headers: ["authorization"]
+    format: "Bearer {token}"
+    description: "Bearer token authentication"
+
+  oauth2:
+    headers: ["authorization"]
+    format: "Bearer {access_token}"
+    description: "OAuth 2.0 authentication"
+
+  http:
+    headers: ["authorization"]
+    format: "Varies by scheme (basic, bearer, digest)"
+    description: "HTTP authentication"
+
+  apiKey:
+    headers: "dynamic"
+    source: "security[].name (default: x-api-key)"
+    location: "security[].in (header, query, or cookie)"
+    description: "API Key authentication"
+
+# Enforcement Modes
+enforcement:
+  environment_variable: "ATDD_SECURITY_ENFORCE"
+  default: "0"
+  modes:
+    soft:
+      value: "0"
+      behavior: "pytest.xfail - test marked as expected failure"
+      visibility: "Visible in test output as XFAIL"
+      use_case: "Development, incremental adoption"
+
+    hard:
+      value: "1"
+      behavior: "pytest.fail - test fails the suite"
+      visibility: "Visible as FAILED"
+      use_case: "CI/CD, production readiness"
+
+# Sensitive Data Detection
+sensitive_data_detection:
+  description: "Rules for detecting potentially sensitive fields in error responses"
+
+  sensitive_fields:
+    - "password"
+    - "secret"
+    - "credential"
+    - "ssn"
+    - "api_key"
+    - "private_key"
+    - "token"
+
+  allowed_exceptions:
+    - "error_key"
+    - "key_id"
+    - "token_type"
+
+  detection_method: "Substring match (case-insensitive)"
+  note: "Review flagged fields manually - not all matches are security issues"
+
+# Threat Modeling Integration
+threat_modeling:
+  canonical_location: "feature.yaml: security.abuse_cases[]"
+  description: |
+    Threat models and abuse cases should be documented in the feature YAML
+    files under the security.abuse_cases array. This ensures security
+    considerations are part of the feature specification.
+
+  schema:
+    abuse_case:
+      required:
+        - id       # Unique identifier (e.g., THREAT-001)
+        - name     # Short name
+        - threat   # Description of the threat
+        - mitigation # How the threat is addressed
+      optional:
+        - severity # low, medium, high, critical
+        - likelihood # unlikely, possible, likely
+        - acceptance_ref # URN to acceptance test covering this threat
+
+  example:
+    security:
+      abuse_cases:
+        - id: "THREAT-001"
+          name: "Session Hijacking"
+          threat: "Attacker steals session token via XSS"
+          mitigation: "HttpOnly cookies, CSP headers"
+          severity: "high"
+          acceptance_ref: "acc:auth:D001-SEC-001-session-protection"
+
+# Acceptance Coverage Requirements
+acceptance_coverage:
+  description: "Requirements for security acceptance test coverage"
+
+  valid_harnesses:
+    - "SEC"  # Security-focused tests
+    - "RLS"  # Row-Level Security tests
+
+  urn_format: "acc:{wagon}:{WMBT}-{HARNESS}-{NNN}[-{slug}]"
+  full_format_required: true
+  note: |
+    Short refs (without harness) cannot be validated for SEC/RLS coverage.
+    Always use the full URN format with the harness identifier.
+
+  examples:
+    valid:
+      - "acc:auth:D001-SEC-001-token-validation"
+      - "acc:player:P002-RLS-001-own-data-only"
+    invalid:
+      - "SEC-001"  # Missing wagon and WMBT
+      - "D001-001" # Missing harness identifier
+
+# Cross-References
+references:
+  test_file: "atdd/tester/validators/test_contract_security.py"
+  contract_convention: "atdd/tester/conventions/contract.convention.yaml"
+  api_structure: "contract.convention.yaml#api_structure.authentication"

atdd/tester/validators/test_contract_security.py

@@ -0,0 +1,569 @@
+"""
+Platform tests: Contract security validation.
+
+Validates that contract schemas properly declare security requirements:
+- Secured operations have required auth headers
+- Operations have explicit security field
+- Secured operations have SEC/RLS acceptance coverage
+- Error responses do not expose sensitive data
+
+Spec: SPEC-TESTER-SEC-0001 through SPEC-TESTER-SEC-0004
+URN: tester:validators:contract-security
+"""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+import pytest
+
+# Import find_repo_root with fallback
+try:
+    from atdd.coach.utils.repo import find_repo_root
+except ImportError:
+    def find_repo_root() -> Path:
+        """Fallback: search upward for .git directory."""
+        current = Path.cwd().resolve()
+        while current != current.parent:
+            if (current / ".git").is_dir():
+                return current
+            current = current.parent
+        return Path.cwd().resolve()
+
+# Import parse_acceptance_urn with fallback
+try:
+    from atdd.tester.utils.filename import parse_acceptance_urn
+except ImportError:
+    URN_PATTERN = r'^acc:([a-z][a-z0-9-]*):([DLPCEMYRK][0-9]{3})-([A-Z0-9]+)-([0-9]{3})(?:-([a-z0-9-]+))?$'
+
+    def parse_acceptance_urn(urn: str) -> Dict[str, Optional[str]]:
+        """Fallback URN parser."""
+        match = re.match(URN_PATTERN, urn)
+        if not match:
+            raise ValueError(f"Invalid acceptance URN: {urn}")
+        wagon, WMBT, HARNESS, NNN, slug = match.groups()
+        return {
+            'wagon': wagon,
+            'WMBT': WMBT,
+            'HARNESS': HARNESS,
+            'NNN': NNN,
+            'slug': slug
+        }
+
+
+# Path constants
+REPO_ROOT = find_repo_root()
+CONTRACTS_DIR = REPO_ROOT / "contracts"
+
+# Security enforcement mode
+ENFORCE_SECURITY = os.environ.get("ATDD_SECURITY_ENFORCE", "0") == "1"
+
+# Scheme to required headers mapping
+SCHEME_HEADERS = {
+    "jwt": {"authorization"},
+    "bearer": {"authorization"},
+    "oauth2": {"authorization"},
+    "http": {"authorization"},
+}
+
+# Sensitive field names that should not appear in error responses
+SENSITIVE_FIELDS = {"password", "secret", "credential", "ssn", "api_key", "private_key", "token"}
+# Fields that are allowed even if they contain "key" or similar
+ALLOWED_IN_ERRORS = {"error_key", "key_id", "token_type"}
+
+
+def find_all_contract_schemas() -> List[Path]:
+    """Find all contract schema files."""
+    if not CONTRACTS_DIR.exists():
+        return []
+    return list(CONTRACTS_DIR.glob("**/*.schema.json"))
+
+
+def load_contract(path: Path) -> Optional[Dict]:
+    """Load and parse a contract schema file."""
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def get_secured_operations(contract: Dict) -> List[Dict]:
+    """Extract operations that have security defined."""
+    metadata = contract.get("x-artifact-metadata", {})
+    api = metadata.get("api", {})
+    operations = api.get("operations", [])
+
+    secured = []
+    for op in operations:
+        if not isinstance(op, dict):
+            continue
+        security = op.get("security", [])
+        if security:  # Non-empty security array means secured
+            secured.append(op)
+    return secured
+
+
+def is_secured_operation(contract: Dict) -> bool:
+    """Check if contract represents a secured operation."""
+    # First check operations-based security (preferred method)
+    secured_ops = get_secured_operations(contract)
+    if secured_ops:
+        return True
+
+    # Fallback to legacy metadata checks
+    metadata = contract.get("x-artifact-metadata", {})
+    security = metadata.get("security", {})
+
+    # Check for explicit security declaration
+    if security.get("requires_auth") is True:
+        return True
+    if security.get("authentication"):
+        return True
+
+    # Check for security scheme references
+    if "securitySchemes" in contract:
+        return True
+
+    # Check API metadata for security indicators
+    api = metadata.get("api", {})
+    if api.get("security"):
+        return True
+
+    return False
+
+
+def get_declared_headers(contract: Dict) -> Set[str]:
+    """Extract declared header parameters from contract."""
+    headers = set()
+
+    # Check parameters at root level
+    for param in contract.get("parameters", []):
+        if param.get("in") == "header":
+            headers.add(param.get("name", "").lower())
+
+    # Check properties that might be headers
+    props = contract.get("properties", {})
+    if "headers" in props and isinstance(props["headers"], dict):
+        header_props = props["headers"].get("properties", {})
+        headers.update(k.lower() for k in header_props.keys())
+
+    # Check x-artifact-metadata for header declarations
+    metadata = contract.get("x-artifact-metadata", {})
+    api = metadata.get("api", {})
+    for header in api.get("headers", []):
+        if isinstance(header, str):
+            headers.add(header.lower())
+        elif isinstance(header, dict):
+            headers.add(header.get("name", "").lower())
+
+    # Check operations for header declarations
+    for op in api.get("operations", []):
+        if not isinstance(op, dict):
+            continue
+        for header in op.get("headers", []):
+            if isinstance(header, str):
+                headers.add(header.lower())
+            elif isinstance(header, dict):
+                headers.add(header.get("name", "").lower())
+
+    return headers
+
+
+def get_operation_headers(operation: Dict) -> Set[str]:
+    """Extract declared headers from a single operation."""
+    headers = set()
+    for header in operation.get("headers", []):
+        if isinstance(header, str):
+            headers.add(header.lower())
+        elif isinstance(header, dict):
+            headers.add(header.get("name", "").lower())
+    return headers
+
+
+def get_required_headers_for_security(security_schemes: List[Dict]) -> Set[str]:
+    """Determine required headers based on security schemes."""
+    required = set()
+    for scheme in security_schemes:
+        if not isinstance(scheme, dict):
+            continue
+
+        scheme_type = scheme.get("type", "").lower()
+
+        # Check SCHEME_HEADERS mapping
+        if scheme_type in SCHEME_HEADERS:
+            required.update(SCHEME_HEADERS[scheme_type])
+        elif scheme_type == "apikey":
+            # apiKey: use the name field, default to x-api-key
+            header_name = scheme.get("name", "x-api-key").lower()
+            if scheme.get("in", "header") == "header":
+                required.add(header_name)
+        else:
+            # Unknown scheme, require authorization header as fallback
+            required.add("authorization")
+
+    return required
+
+
+def get_acceptance_refs(contract: Dict) -> List[str]:
+    """Extract acceptance references from contract."""
+    metadata = contract.get("x-artifact-metadata", {})
+    traceability = metadata.get("traceability", {})
+    return traceability.get("acceptance_refs", [])
+
+
+def _resolve_schema_ref(contract: Dict, schema_ref: str) -> Optional[Dict]:
+    """Resolve $ref to actual schema definition."""
+    if not isinstance(schema_ref, str):
+        return None
+    if not schema_ref.startswith("#/definitions/"):
+        return None
+    definition_name = schema_ref.split("/")[-1]
+    return contract.get("definitions", {}).get(definition_name)
+
+
+def _extract_field_names(schema: Dict, contract: Dict, visited: Optional[Set[str]] = None) -> Set[str]:
+    """Recursively extract all field names from a schema."""
+    if visited is None:
+        visited = set()
+
+    fields = set()
+
+    if not isinstance(schema, dict):
+        return fields
+
+    # Handle $ref
+    ref = schema.get("$ref")
+    if ref:
+        if ref in visited:
+            return fields
+        visited.add(ref)
+        resolved = _resolve_schema_ref(contract, ref)
+        if resolved:
+            fields.update(_extract_field_names(resolved, contract, visited))
+        return fields
+
+    # Extract property names
+    properties = schema.get("properties", {})
+    if isinstance(properties, dict):
+        fields.update(properties.keys())
+        for prop_schema in properties.values():
+            if isinstance(prop_schema, dict):
+                fields.update(_extract_field_names(prop_schema, contract, visited))
+
+    # Handle items in arrays
+    items = schema.get("items")
+    if isinstance(items, dict):
+        fields.update(_extract_field_names(items, contract, visited))
+
+    # Handle allOf, anyOf, oneOf
+    for combinator in ("allOf", "anyOf", "oneOf"):
+        combined = schema.get(combinator, [])
+        if isinstance(combined, list):
+            for sub_schema in combined:
+                if isinstance(sub_schema, dict):
+                    fields.update(_extract_field_names(sub_schema, contract, visited))
+
+    return fields
+
+
+def soft_fail_or_fail(message: str, issues: List[str]):
+    """Fail test or soft-fail (xfail) based on ATDD_SECURITY_ENFORCE env var."""
+    full_message = (
+        f"{message}:\n" +
+        "\n".join(f"  {issue}" for issue in issues[:10]) +
+        (f"\n  ... and {len(issues) - 10} more" if len(issues) > 10 else "")
+    )
+
+    if ENFORCE_SECURITY:
+        pytest.fail(full_message)
+    else:
+        pytest.xfail(
+            f"[SOFT-FAIL] {full_message}\n\n"
+            "Set ATDD_SECURITY_ENFORCE=1 to enforce."
+        )
+
+
+@pytest.mark.tester
+@pytest.mark.security
+def test_secured_operations_have_required_headers():
+    """
+    SPEC-TESTER-SEC-0001: Secured operations must declare auth headers
+
+    Given: Contract schemas with security requirements
+    When: Checking for header declarations
+    Then: Secured operations must include appropriate auth header based on scheme
+
+    Security scheme to header mapping:
+    - jwt/bearer/oauth2/http: authorization
+    - apiKey: dynamic (from security[].name, default x-api-key)
+    """
+    contract_files = find_all_contract_schemas()
+
+    if not contract_files:
+        pytest.skip("No contract schema files found")
+
+    missing_headers = []
+
+    for contract_path in contract_files:
+        contract = load_contract(contract_path)
+        if not contract:
+            continue
+
+        metadata = contract.get("x-artifact-metadata", {})
+        api = metadata.get("api", {})
+        operations = api.get("operations", [])
+
+        # Check each secured operation
+        for op in operations:
+            if not isinstance(op, dict):
+                continue
+
+            security = op.get("security", [])
+            if not security:
+                continue  # Not a secured operation
+
+            required_headers = get_required_headers_for_security(security)
+            declared_headers = get_operation_headers(op)
+
+            # Also check contract-level headers
+            declared_headers.update(get_declared_headers(contract))
+
+            if not declared_headers.intersection(required_headers):
+                op_desc = f"{op.get('method', '?')} {op.get('path', '?')}"
+                missing_headers.append(
+                    f"{contract_path.relative_to(REPO_ROOT)} [{op_desc}]: "
+                    f"Secured operation missing auth header. "
+                    f"Declared: {sorted(declared_headers) or 'none'}. "
+                    f"Required one of: {sorted(required_headers)}"
+                )
+
+    if missing_headers:
+        soft_fail_or_fail(
+            f"Found {len(missing_headers)} secured operations without auth headers",
+            missing_headers
+        )
+
+
+@pytest.mark.tester
+@pytest.mark.security
+def test_operations_have_explicit_security():
+    """
+    SPEC-TESTER-SEC-0002: All operations should have explicit security field
+
+    Given: Contract schemas
+    When: Checking for security metadata
+    Then: Operations should declare security requirements explicitly
+          (either security: [] for public or security: [{...}] for protected)
+
+    This ensures security posture is intentional, not accidental.
+    """
+    contract_files = find_all_contract_schemas()
+
+    if not contract_files:
+        pytest.skip("No contract schema files found")
+
+    missing_security = []
+
+    for contract_path in contract_files:
+        contract = load_contract(contract_path)
+        if not contract:
+            continue
+
+        metadata = contract.get("x-artifact-metadata", {})
+
+        # Skip non-API contracts (e.g., shared schemas, types)
+        if not metadata.get("api"):
+            continue
+
+        api = metadata.get("api", {})
+        operations = api.get("operations", [])
+
+        # Check each operation for explicit security
+        for op in operations:
+            if not isinstance(op, dict):
+                continue
+
+            # security field must be present (even if empty array for public)
+            if "security" not in op:
+                op_desc = f"{op.get('method', '?')} {op.get('path', '?')}"
+                missing_security.append(
+                    f"{contract_path.relative_to(REPO_ROOT)} [{op_desc}]: "
+                    f"Operation missing explicit security field. "
+                    f"Add security: [] for public or security: [{{...}}] for protected"
+                )
+
+        # Also check for legacy x-artifact-metadata.security pattern
+        if not operations:
+            security = metadata.get("security", {})
+            has_explicit_security = (
+                "requires_auth" in security or
+                "authentication" in security or
+                "securitySchemes" in contract or
+                api.get("security")
+            )
+
+            if not has_explicit_security:
+                missing_security.append(
+                    f"{contract_path.relative_to(REPO_ROOT)}: "
+                    f"API contract missing explicit security declaration. "
+                    f"Add x-artifact-metadata.api.operations[].security"
+                )
+
+    if missing_security:
+        soft_fail_or_fail(
+            f"Found {len(missing_security)} operations without explicit security",
+            missing_security
+        )
+
+
+@pytest.mark.tester
+@pytest.mark.security
+def test_secured_operations_have_security_acceptance():
+    """
+    SPEC-TESTER-SEC-0003: Secured operations must have SEC/RLS acceptance coverage
+
+    Given: Contract schemas with security requirements
+    When: Checking acceptance_refs
+    Then: At least one acceptance criteria must use SEC or RLS harness
+
+    SEC harness: Security-focused acceptance tests
+    RLS harness: Row-Level Security acceptance tests
+    """
+    contract_files = find_all_contract_schemas()
+
+    if not contract_files:
+        pytest.skip("No contract schema files found")
+
+    SECURITY_HARNESSES = {"SEC", "RLS"}
+    missing_coverage = []
+
+    for contract_path in contract_files:
+        contract = load_contract(contract_path)
+        if not contract:
+            continue
+
+        if not is_secured_operation(contract):
+            continue
+
+        acceptance_refs = get_acceptance_refs(contract)
+
+        # Check if any acceptance ref uses SEC or RLS harness
+        has_security_coverage = False
+        for ref in acceptance_refs:
+            try:
+                parsed = parse_acceptance_urn(ref)
+                if parsed.get("HARNESS") in SECURITY_HARNESSES:
+                    has_security_coverage = True
+                    break
+            except ValueError:
+                # Invalid URN format, skip
+                continue
+
+        if not has_security_coverage:
+            missing_coverage.append(
+                f"{contract_path.relative_to(REPO_ROOT)}: "
+                f"Secured operation missing SEC/RLS acceptance coverage. "
+                f"Current refs: {acceptance_refs or 'none'}"
+            )
+
+    if missing_coverage:
+        soft_fail_or_fail(
+            f"Found {len(missing_coverage)} secured operations without SEC/RLS acceptance",
+            missing_coverage
+        )
+
+
+@pytest.mark.tester
+@pytest.mark.security
+def test_error_responses_have_no_sensitive_fields():
+    """
+    SPEC-TESTER-SEC-0004: Error responses should not expose sensitive data.
+
+    Given: Contract schemas with error response definitions
+    When: Checking 4xx/5xx response schemas
+    Then: Response schemas should not contain sensitive field names
+
+    Mode: warning only (pytest.xfail, not hard fail)
+
+    Sensitive fields: password, secret, credential, ssn, api_key, private_key, token
+    Allowed exceptions: error_key, key_id, token_type
+    """
+    contract_files = find_all_contract_schemas()
+
+    if not contract_files:
+        pytest.skip("No contract schema files found")
+
+    sensitive_exposures = []
+
+    for contract_path in contract_files:
+        contract = load_contract(contract_path)
+        if not contract:
+            continue
+
+        metadata = contract.get("x-artifact-metadata", {})
+        api = metadata.get("api", {})
+        operations = api.get("operations", [])
+
+        for op in operations:
+            if not isinstance(op, dict):
+                continue
+
+            responses = op.get("responses", {})
+            if not isinstance(responses, dict):
+                continue
+
+            # Check 4xx and 5xx responses
+            for status_code, response in responses.items():
+                if not isinstance(status_code, str):
+                    continue
+
+                # Only check error responses (4xx, 5xx)
+                if not (status_code.startswith("4") or status_code.startswith("5")):
+                    continue
+
+                if not isinstance(response, dict):
+                    continue
+
+                schema = response.get("schema", {})
+                if not schema:
+                    continue
+
+                # Handle $ref - can be string or dict with $ref key
+                if isinstance(schema, str):
+                    resolved = _resolve_schema_ref(contract, schema)
+                    if resolved:
+                        schema = resolved
+                    else:
+                        continue  # Can't resolve, skip
+                elif isinstance(schema, dict) and "$ref" in schema:
+                    resolved = _resolve_schema_ref(contract, schema["$ref"])
+                    if resolved:
+                        schema = resolved
+
+                # Extract all field names from the schema
+                field_names = _extract_field_names(schema, contract)
+
+                # Check for sensitive fields
+                for field in field_names:
+                    field_lower = field.lower()
+                    # Check if field matches sensitive patterns
+                    for sensitive in SENSITIVE_FIELDS:
+                        if sensitive in field_lower and field_lower not in ALLOWED_IN_ERRORS:
+                            op_desc = f"{op.get('method', '?')} {op.get('path', '?')}"
+                            sensitive_exposures.append(
+                                f"{contract_path.relative_to(REPO_ROOT)} [{op_desc}] {status_code}: "
+                                f"Error response contains potentially sensitive field '{field}'"
+                            )
+                            break
+
+    if sensitive_exposures:
+        # This is warning-only mode, always xfail
+        pytest.xfail(
+            f"[WARNING] Found {len(sensitive_exposures)} error responses with potentially sensitive fields:\n" +
+            "\n".join(f"  {exp}" for exp in sensitive_exposures[:10]) +
+            (f"\n  ... and {len(sensitive_exposures) - 10} more" if len(sensitive_exposures) > 10 else "") +
+            "\n\nReview these fields to ensure no sensitive data is exposed in error responses."
+        )

atdd/tester/validators/test_contracts_structure.py

@@ -7,6 +7,7 @@ Tests ensure contract directories align with URN conventions.
 import pytest
 import re
 from pathlib import Path
+from typing import Optional
 
 # Path constants
 REPO_ROOT = Path(__file__).resolve().parents[4]
@@ -198,3 +199,83 @@ def test_contract_files_are_valid_formats():
             (f"\n  ... and {len(invalid_files) - 10} more" if len(invalid_files) > 10 else "") +
             f"\n  Allowed: {', '.join(sorted(allowed_extensions))}"
         )
+
+
+def contract_urn_to_path(contract_urn: str) -> Optional[Path]:
+    """
+    Convert contract URN to expected file path.
+
+    Pattern: contract:{theme}:{domain}.{facet} → contracts/{theme}/{domain}/{facet}.schema.json
+
+    Examples:
+      contract:commons:player.identity → contracts/commons/player/identity.schema.json
+      contract:mechanic:decision.choice → contracts/mechanic/decision/choice.schema.json
+      contract:match:dilemma:current → contracts/match/dilemma/current.schema.json
+    """
+    if not contract_urn or contract_urn == "null":
+        return None
+    if not contract_urn.startswith("contract:"):
+        return None
+
+    # Remove "contract:" prefix
+    urn_without_prefix = contract_urn[9:]
+
+    # Split by colon
+    parts = urn_without_prefix.split(":")
+    if len(parts) < 2:
+        return None
+
+    # First part is theme
+    theme = parts[0]
+
+    # Remaining parts form domain.facet (join with : if multiple)
+    domain_facet = ":".join(parts[1:])
+
+    # Convert domain.facet to domain/facet path (dots become slashes)
+    path_parts = domain_facet.replace(".", "/")
+
+    # Also convert colons to slashes for multi-level URNs
+    path_parts = path_parts.replace(":", "/")
+
+    return CONTRACTS_DIR / theme / f"{path_parts}.schema.json"
+
+
+@pytest.mark.platform
+def test_wagon_produce_contracts_exist(wagon_manifests):
+    """
+    SPEC-PLATFORM-CONTRACTS-0006: All wagon produce contracts have schema files
+
+    Given: Wagon manifests with produce[] declarations
+    When: Checking for declared contract URNs
+    Then: Each contract:* URN resolves to an existing .schema.json file
+
+    This ensures the planner's intent (wagon declares contract) matches
+    the tester's reality (contract file exists).
+    """
+    missing_contracts = []
+
+    for manifest_path, manifest in wagon_manifests:
+        wagon_slug = manifest.get("wagon", "unknown")
+
+        for produce_item in manifest.get("produce", []):
+            contract_urn = produce_item.get("contract")
+
+            if not contract_urn or contract_urn == "null":
+                continue
+
+            expected_path = contract_urn_to_path(contract_urn)
+
+            if expected_path and not expected_path.exists():
+                artifact_name = produce_item.get("name", "?")
+                missing_contracts.append(
+                    f"wagon:{wagon_slug} → {contract_urn}\n"
+                    f"    Artifact: {artifact_name}\n"
+                    f"    Expected: {expected_path.relative_to(REPO_ROOT)}"
+                )
+
+    if missing_contracts:
+        pytest.fail(
+            f"Found {len(missing_contracts)} wagon produce declarations without contract files:\n\n" +
+            "\n\n".join(missing_contracts[:10]) +
+            (f"\n\n... and {len(missing_contracts) - 10} more" if len(missing_contracts) > 10 else "")
+        )

{atdd-0.2.12.dist-info → atdd-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atdd
-Version: 0.2.12
+Version: 0.3.1
 Summary: ATDD Platform - Acceptance Test Driven Development toolkit
 License: MIT
 Requires-Python: >=3.10

{atdd-0.2.12.dist-info → atdd-0.3.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
 atdd/__init__.py,sha256=-S8i9OahH-t9FJkPn6nprxipnjVum3rLeVsCS74T6eY,156
 atdd/__main__.py,sha256=B0sXDQLjFN9GowTlXo4NMWwPZPjDsrT8Frq7DnbdOD8,77
-atdd/cli.py,sha256=ONdVyLKHb4PCCmRg2Qi9UCU6CScihKBdPSrzgtdHbg0,14149
+atdd/cli.py,sha256=osZ_WFMbp3BFGgH-K7vApnoeulgeSU7-z6LB86-htnI,14534
 atdd/conftest.py,sha256=Fj3kIhCETbj2QBCIjySBgdS3stKNRZcZzKTJr7A4LaQ,5300
 atdd/version_check.py,sha256=B9MbbxO_sJrEC3fxFJhTlOIkLLTRQCDO1_8ec1KvuWY,3540
 atdd/coach/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -12,13 +12,13 @@ atdd/coach/commands/gate.py,sha256=_V2GypqoGixTs_kLWxFF3HgEt-Wi2r6Iv0YL75yWrWo,5
 atdd/coach/commands/infer_governance_status.py,sha256=91-VnI64mOzijc1Cgkmr7cnNCir2-z2ITA2-SGwk3TU,4473
 atdd/coach/commands/initializer.py,sha256=Hli3hlL_aHnuDIzK0lHzE6KjG2QGvl2E2TvjmYoPPNE,6069
 atdd/coach/commands/interface.py,sha256=PPCwICFNN4ddPqucUATIiBrfEkDO66MZbYQkwNu6lm4,40459
-atdd/coach/commands/inventory.py,sha256=k81T6kjhE5iutHkmYN0OvJruECvuELq2mhdV3i5htGs,21034
+atdd/coach/commands/inventory.py,sha256=Xakb6U3SfnEcR7rhZ0Wg8SK5frg-oPE7C0fCvE-VoH4,20923
 atdd/coach/commands/migration.py,sha256=KlRXXM1O-ZqfwGOWxN5C_gxfTttbXUG_yq9pOLYsGnQ,8119
 atdd/coach/commands/registry.py,sha256=r1QWg841eK6bS4vEbYEviylDCpFkInUVMTsf5h4ArrQ,58344
 atdd/coach/commands/session.py,sha256=MhuWXd5TR6bB3w0t8vANeZx3L476qwLT6EUQMwg-wQA,14268
 atdd/coach/commands/sync.py,sha256=dA6BYsebTT1zOMXgea6DqawkvjU_N-JJJMFj9GP2onk,12259
 atdd/coach/commands/test_interface.py,sha256=a7ut2Hhk0PnQ5LfJZkoQwfkfkVuB5OHA4QBwOS0-jcg,16870
-atdd/coach/commands/test_runner.py,sha256=PIIGi-gekRiavkvPfy0dVATmWMuwjFCYu9y7OGxe6so,3961
+atdd/coach/commands/test_runner.py,sha256=Lutclc8Qr8BmLBvAYshXAjf8ynUM4eJgHF8GLPa1Usw,3929
 atdd/coach/commands/traceability.py,sha256=SYl0dRB_nQZJKe1IOCHxX193vaxOChVjnh6hcqcSOB0,163581
 atdd/coach/commands/tests/__init__.py,sha256=svBEnRruMuXuaYi3lFxJlzHNWdZ5vlBTaBpjXupaxDA,33
 atdd/coach/commands/tests/test_telemetry_array_validation.py,sha256=WK5ZXvR1avlzX7mSX84dmxxLFnw7eQB4jtjo7bHG7aE,8464
@@ -27,13 +27,14 @@ atdd/coach/overlays/__init__.py,sha256=2lMiMSgfLJ3YHLpbzNI5B88AdQxiMEwjIfsWWb8t3
 atdd/coach/overlays/claude.md,sha256=33mhpqhmsRhCtdWlU7cMXAJDsaVra9uBBK8URV8OtQA,101
 atdd/coach/schemas/config.schema.json,sha256=xzct7gBoPTIGh3NFPSGtfW0zIiyFdHDZkvjuy1qgAqA,951
 atdd/coach/schemas/manifest.schema.json,sha256=WO13-YF_FgH1awh96khCtk-112b6XSC24anlY3B7GjY,2885
-atdd/coach/templates/ATDD.md,sha256=uoLt3gSUym4hd0S5joaTVqmrfbMASn6jhTwrvDSBlhI,11920
-atdd/coach/templates/SESSION-TEMPLATE.md,sha256=p_AwdV9ktKS-FGcg8ocDso74NdR7yeMEQO3dJmeb4VQ,8647
-atdd/coach/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+atdd/coach/templates/ATDD.md,sha256=DnJ1jzdoUWATEwvnweh2DCfoCepLMC_f35wlSvKF1FI,12153
+atdd/coach/templates/SESSION-TEMPLATE.md,sha256=tZ4Bgf4MZ6uHXwhy1C43SGpTiYm-_AvmFS6QxA2ISng,9140
+atdd/coach/utils/__init__.py,sha256=7Jbo-heJEKSAn6I0s35z_2S4R8qGZ48PL6a2IntcNYg,148
+atdd/coach/utils/repo.py,sha256=9rZeAf1b7-modoTiPZAwtjnoiI8YyHWIZhpqXvkJ7Qo,3104
 atdd/coach/utils/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 atdd/coach/utils/graph/urn.py,sha256=O2AHIB_CmmMUvXzyejc_oFReNW_rOcw7m4qaqSYcnNQ,33558
 atdd/coach/validators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-atdd/coach/validators/shared_fixtures.py,sha256=mhNr6ZI1FwU5L29Tq5ytLh9OoCkmYwV8ZEpgMjWtzRU,11865
+atdd/coach/validators/shared_fixtures.py,sha256=ZxpTYM1ERL9sJXNl_IbtBl8MHnGBx1IhKT091Jh_gH4,11920
 atdd/coach/validators/test_enrich_wagon_registry.py,sha256=WeTwYJqoNY6mEYc-QAvQo7YVagSOjaNKxB6Q6dpWqIM,6561
 atdd/coach/validators/test_registry.py,sha256=ffN70yA_1xxL3R8gdpGbY2M8dQXyuajIZhBZ-ylNiNs,17845
 atdd/coach/validators/test_session_validation.py,sha256=Tx5HfQ0mZfVLypLe4wbKTracMc9nVRCoxDobOko6xwU,39104
@@ -124,6 +125,7 @@ atdd/tester/conventions/filename.convention.yaml,sha256=WywcPhdxIZSoY6F6OSx5v3_A
 atdd/tester/conventions/migration.convention.yaml,sha256=xqZZrMKJVlBQdGab5mJF2enChLebGGPQkd-ioDWFQtw,20075
 atdd/tester/conventions/red.convention.yaml,sha256=S0mc4JpvNuOSYhqmt6bm0tCuDTCFYFRsSBru3XMwXgs,28901
 atdd/tester/conventions/routing.convention.yaml,sha256=gRJrnQd-cXCUGby0CeaJdRmrFXZx70kl-FxXCoXiu5Y,2751
+atdd/tester/conventions/security.convention.yaml,sha256=3QjQZqw1Iw8g6jUmuKWkOqcZ1n1sc1OJDvKD0eTk070,5445
 atdd/tester/conventions/telemetry.convention.yaml,sha256=n8Q8x7BtiDnDf920EWiq3xBzaf8tYev7WIi1pQ27O6o,16119
 atdd/tester/schemas/a11y.tmpl.json,sha256=o-i8-fQeLxqTPgeDysOQDvyoHdlcCDOlUGtPG1-_Wro,1088
 atdd/tester/schemas/artifact.schema.json,sha256=CVmhmz9dsSsZW4HYS_wohn-kzq_mx4YPYunwrBHtbQg,5755
@@ -163,7 +165,8 @@ atdd/tester/validators/test_acceptance_urn_filename_mapping.py,sha256=sLopDoF78h
 atdd/tester/validators/test_acceptance_urn_separator.py,sha256=PnXaISoOVgr21cGgbcFnm8V9re1nv0ctatJaIqJk6KE,6847
 atdd/tester/validators/test_artifact_naming_category.py,sha256=V7AOamSUIbpl6bO_Qj3h_46vc2hsh6OVPCMco1H7zTc,12541
 atdd/tester/validators/test_contract_schema_compliance.py,sha256=8LnZotoND2UNdZy9XdoNnTcBdMjyDsHtgjKLZ4bFeX8,26103
-atdd/tester/validators/test_contracts_structure.py,sha256=LTHXBDfFff30c3vRPQjE4L7u0kMREb1pyep3rypzV58,6922
+atdd/tester/validators/test_contract_security.py,sha256=fKNaevmbSAoGyOKBhPnHw5xSGXptG0ciS0__qtO9Qac,19541
+atdd/tester/validators/test_contracts_structure.py,sha256=b930uB96iXK9xF080pATkzBWtP4mvRenkOeA1RdhJOE,9784
 atdd/tester/validators/test_coverage_adequacy.py,sha256=1UCJ0-7xnkvcdAagfvB7dT4ZzPEyZC5mMxA3z2g4yGA,27026
 atdd/tester/validators/test_dual_ac_reference.py,sha256=3yksy4xWta7kC1QMJQvx-a-cBXNSpY4FNpi0K8H3CYU,8888
 atdd/tester/validators/test_fixture_validity.py,sha256=nmkPOWXQFieyGC-hXtIhMm_j1wAW-kIRJsGC3QDB1hM,12071
@@ -178,9 +181,9 @@ atdd/tester/validators/test_red_supabase_layer_structure.py,sha256=26cnzPZAwSFy0
 atdd/tester/validators/test_telemetry_structure.py,sha256=hIUnU2WU-8PNIg9EVHe2fnUdIQKIOUm5AWEtCBUXLVk,22467
 atdd/tester/validators/test_typescript_test_naming.py,sha256=E-TyGv_GVlTfsbyuxrtv9sOWSZS_QcpH6rrJFbWoeeU,11280
 atdd/tester/validators/test_typescript_test_structure.py,sha256=eV89SD1RaKtchBZupqhnJmaruoROosf3LwB4Fwe4UJI,2612
-atdd-0.2.12.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-atdd-0.2.12.dist-info/METADATA,sha256=wXMZmjryLTwuJkG58IwWdVh-JgDeos2x0bx2b0Z3x6A,7082
-atdd-0.2.12.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-atdd-0.2.12.dist-info/entry_points.txt,sha256=-C3yrA1WQQfN3iuGmSzPapA5cKVBEYU5Q1HUffSJTbY,38
-atdd-0.2.12.dist-info/top_level.txt,sha256=VKkf6Uiyrm4RS6ULCGM-v8AzYN8K2yg8SMqwJLoO-xs,5
-atdd-0.2.12.dist-info/RECORD,,
+atdd-0.3.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+atdd-0.3.1.dist-info/METADATA,sha256=xAWoy8Xg4lpkMoYfxoNn6gFJxUuX8lHE8fhT5Ns3DOw,7081
+atdd-0.3.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+atdd-0.3.1.dist-info/entry_points.txt,sha256=-C3yrA1WQQfN3iuGmSzPapA5cKVBEYU5Q1HUffSJTbY,38
+atdd-0.3.1.dist-info/top_level.txt,sha256=VKkf6Uiyrm4RS6ULCGM-v8AzYN8K2yg8SMqwJLoO-xs,5
+atdd-0.3.1.dist-info/RECORD,,