atdd 0.2.8__tar.gz → 0.3.3__tar.gz

{atdd-0.2.8/src/atdd.egg-info → atdd-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atdd
-Version: 0.2.8
+Version: 0.3.3
 Summary: ATDD Platform - Acceptance Test Driven Development toolkit
 License: MIT
 Requires-Python: >=3.10
@@ -54,7 +54,9 @@ atdd sync                      # Sync rules to agent config files
 atdd --test all                # Run validators
 ```
 
-> **⚠️ `atdd gate` is required.** Agents skip instruction files but can't ignore tool output. No gate = no ATDD guarantees.
+> **⚠️ `atdd gate` is required.** 
+> 🤖 Tell your agent: "Run `atdd gate` and follow ATDD rigorously." 
+> Agents skip instruction files but can't ignore tool output. No gate = no ATDD guarantees.
 
 ## What It Does
 

{atdd-0.2.8 → atdd-0.3.3}/README.md

@@ -40,7 +40,9 @@ atdd sync                      # Sync rules to agent config files
 atdd --test all                # Run validators
 ```
 
-> **⚠️ `atdd gate` is required.** Agents skip instruction files but can't ignore tool output. No gate = no ATDD guarantees.
+> **⚠️ `atdd gate` is required.** 
+> 🤖 Tell your agent: "Run `atdd gate` and follow ATDD rigorously." 
+> Agents skip instruction files but can't ignore tool output. No gate = no ATDD guarantees.
 
 ## What It Does
 

{atdd-0.2.8 → atdd-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atdd"
-version = "0.2.8"
+version = "0.3.3"
 description = "ATDD Platform - Acceptance Test Driven Development toolkit"
 requires-python = ">=3.10"
 readme = "README.md"
@@ -35,3 +35,8 @@ where = ["src"]
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["src/atdd"]
+markers = [
+    "tester: marks tests as tester validators",
+    "platform: marks tests as platform validators",
+    "security: marks tests as security validators",
+]

{atdd-0.2.8 → atdd-0.3.3}/src/atdd/cli.py

@@ -44,7 +44,8 @@ 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.version_check import print_update_notice
+from atdd.coach.utils.repo import find_repo_root
+from atdd.version_check import print_update_notice, print_upgrade_sync_notice
 
 
 class ATDDCoach:
@@ -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:
@@ -426,10 +436,14 @@ Phase descriptions:
 
 
 def cli() -> int:
-    """CLI entry point with version check."""
+    """CLI entry point with version and upgrade checks."""
+    # Check if repo needs sync after ATDD upgrade (at startup)
+    print_upgrade_sync_notice()
+
     try:
         result = main()
     finally:
+        # Check for newer versions on PyPI (at end)
         print_update_notice()
     return result
 

{atdd-0.2.8 → atdd-0.3.3}/src/atdd/coach/commands/initializer.py

@@ -160,11 +160,21 @@ class ProjectInitializer:
             print(f"Config already exists: {self.config_file}")
             return
 
+        # Get installed ATDD version
+        try:
+            from atdd import __version__
+            toolkit_version = __version__
+        except ImportError:
+            toolkit_version = "0.0.0"
+
         config = {
             "version": "1.0",
             "sync": {
                 "agents": ["claude"],  # Default: only Claude
             },
+            "toolkit": {
+                "last_version": toolkit_version,  # Track installed version
+            },
         }
 
         with open(self.config_file, "w") as f:

{atdd-0.2.8 → atdd-0.3.3}/src/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-0.2.8 → atdd-0.3.3}/src/atdd/coach/commands/sync.py

@@ -115,6 +115,13 @@ class AgentConfigSync:
                 unchanged_count += 1
 
         print(f"\nSync complete: {synced_count} updated, {unchanged_count} unchanged")
+
+        # Update toolkit.last_version to mark sync complete
+        from atdd.version_check import update_toolkit_version
+        if update_toolkit_version(self.config_file):
+            from atdd import __version__
+            print(f"Updated toolkit.last_version to {__version__}")
+
         return 0
 
     def verify(self) -> int:

{atdd-0.2.8 → atdd-0.3.3}/src/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(
@@ -88,11 +88,11 @@ class TestRunner:
         # Show collected tests summary
         cmd.append("--tb=short")
 
-        # Run pytest
+        # Run pytest from current directory (consumer repo)
         print(f"🧪 Running: {' '.join(cmd)}")
         print("=" * 60)
 
-        result = subprocess.run(cmd, cwd=self.repo_root)
+        result = subprocess.run(cmd)
         return result.returncode
 
     def run_phase(self, phase: str, **kwargs) -> int:

{atdd-0.2.8 → atdd-0.3.3}/src/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
@@ -214,6 +219,35 @@ git:
       - "GREEN: commit passing implementation"
       - "REFACTOR: commit clean architecture"
 
+# Release Gate (MANDATORY - session completion)
+# Every session MUST end with version bump + tag
+release:
+  mandatory: true
+
+  rules:
+    - "Tag must match version exactly: v{version}"
+    - "No tag without version bump"
+    - "No version bump without tag"
+    - "Every repo MUST have versioning"
+
+  change_class:
+    PATCH: "bug fixes, docs, refactors, internal changes"
+    MINOR: "new feature, new validator, new command, new convention (non-breaking)"
+    MAJOR: "breaking API/CLI/schema/convention change or behavior removal"
+
+  workflow:
+    - "Determine change class"
+    - "Bump version in version file"
+    - "Commit: 'Bump version to {version}'"
+    - "Create tag: git tag v{version}"
+    - "Push with tags: git push origin {branch} --tags"
+    - "Record in Session Log: 'Released: v{version}'"
+
+  # Consumer repos configure version file location in .atdd/config.yaml:
+  # release:
+  #   version_file: "pyproject.toml"  # or package.json, VERSION, etc.
+  #   tag_prefix: "v"
+
 # Agent Coordination (Detailed in action files)
 agents:
   planner:

{atdd-0.2.8 → atdd-0.3.3}/src/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)
 #
@@ -322,6 +331,31 @@ Reference: src/atdd/coach/conventions/session.convention.yaml
 
 ---
 
+## Release Gate (MANDATORY)
+
+<!--
+Every session MUST end with a version bump + matching git tag.
+
+Change Class:
+- PATCH: bug fixes, docs, refactors, internal changes
+- MINOR: new feature, new validator, new command, new convention (non-breaking)
+- MAJOR: breaking API/CLI/schema/convention change or behavior removal
+
+Rules:
+- Tag must match version exactly: v{version}
+- No tag without version bump
+- No version bump without tag
+-->
+
+- [ ] Determine change class: PATCH / MINOR / MAJOR
+- [ ] Bump version in version file (pyproject.toml, package.json, etc.)
+- [ ] Commit: "Bump version to {version}"
+- [ ] Create tag: `git tag v{version}`
+- [ ] Push with tags: `git push origin {branch} --tags`
+- [ ] Record tag in Session Log: "Released: v{version}"
+
+---
+
 ## Notes
 
 {Additional context, learnings, or decisions that don't fit elsewhere.}

atdd-0.3.3/src/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-0.3.3/src/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-0.2.8 → atdd-0.3.3}/src/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-0.3.3/src/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"