ref-agents 1.0.0__tar.gz

ref_agents-1.0.0/.dockerignore

@@ -0,0 +1,12 @@
+__pycache__
+*.pyc
+.git
+.venv
+tests/
+.pytest_cache/
+.cursor/
+docs/reports/
+
+# Documentation Iterations
+GAP_ANALYSIS.md
+docs/misc/

ref_agents-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: Elite Quality Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # STAGE 1: LINT
+  lint:
+    name: 1. Lint & Static Analysis
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install
+      - name: Validate Python Version
+        run: uv run python scripts/validate_python_version.py
+      - name: Install Dependencies
+        run: uv sync --all-extras --dev
+      - name: Lint (Ruff)
+        run: uv run ruff check .
+      - name: Format Check (Ruff)
+        run: uv run ruff format --check .
+
+  # STAGE 2: SECURITY
+  security:
+    name: 2. Security Scan
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install
+      - name: Install Dependencies
+        run: uv sync --all-extras --dev
+      - name: Secrets Scan (detect-secrets)
+        run: |
+            uv tool install detect-secrets
+            uv tool run detect-secrets scan --baseline .secrets.baseline .
+      - name: Dependency Audit (pip-audit)
+        run: |
+            uv tool install pip-audit
+            uv tool run pip-audit .
+      - name: Policy Scan (make audit)
+        run: |
+           uv run python -m ref_agents.security_scan --format json
+
+  # STAGE 3: TEST
+  test:
+    name: 3. Test & Coverage
+    runs-on: ubuntu-latest
+    needs: security
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install
+      - name: Install Dependencies
+        run: uv sync --all-extras --dev
+      - name: Run Tests (Pytest)
+        run: uv run pytest --cov=src/ref_agents --cov-report=xml --cov-fail-under=0
+
+  # STAGE 4: BUILD
+  build:
+    name: 4. Build Artifacts
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install
+      - name: Build Wheel & Sdist
+        run: uv build
+      - name: Archive Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/
+
+  # STAGE 5: DEPLOY (Dry Run)
+  deploy:
+    name: 5. Deploy (Dry Run)
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/
+      - name: Simulate Deployment
+        run: |
+          echo "🚀 SIMULATING DEPLOYMENT..."
+          ls -R dist/
+          echo "✅ Ready to publish to PyPI"

ref_agents-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ref-agents
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: read  # Required to checkout the repository
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch full history for tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.5.5"
+
+      - name: Build package
+        run: uv build
+
+      - name: Version Consistency Check
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          PYPROJECT_VERSION=$(grep -m 1 'version =' pyproject.toml | cut -d '"' -f 2)
+          echo "Tag: $TAG_VERSION"
+          echo "PyProject: $PYPROJECT_VERSION"
+          if [ "$TAG_VERSION" != "$PYPROJECT_VERSION" ]; then
+            echo "Error: Version mismatch! Tag is $TAG_VERSION but pyproject.toml is $PYPROJECT_VERSION"
+            exit 1
+          fi
+
+      - name: Check Metadata (Twine)
+        run: uv tool run twine check dist/*
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ref_agents-1.0.0/.github/workflows/security-scan.yml

@@ -0,0 +1,51 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Security Scan
+        run: uv run python -m ref_agents.security_scan --format json > security_results.json
+
+      - name: Check Security Results
+        run: |
+          if grep -q '"passed": false' security_results.json; then
+            echo "❌ Security scan failed!"
+            cat security_results.json
+            exit 1
+          else
+            echo "✅ Security scan passed!"
+            cat security_results.json
+          fi
+
+      - name: Upload Security Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-report
+          path: ref-reports/security/
+          if-no-files-found: ignore
+
+      - name: Run Tests
+        run: uv run pytest tests/test_security_scan.py -v

ref_agents-1.0.0/.gitignore

@@ -0,0 +1,91 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Test artifacts
+.coverage
+coverage.xml
+htmlcov/
+
+# Caches & IDEs
+.cursor/
+.idea/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.agent/
+.ref_cache/
+
+# MCP runtime logs (created in client project roots, not in ref-agents repo)
+handoff_log.jsonl
+
+# Session working files (ephemeral, not part of package)
+tasks/
+CLAUDE.md
+
+# Documentation Iterations
+GAP_ANALYSIS.md
+docs/misc/
+docs/pitch-deck/
+
+# Research / presentation docs (not part of the package)
+docs/ARXIV_SUBMISSION_GUIDE.md
+docs/CONSOLE_SCREENS.md
+docs/CONTEXT_CODEBASE_DIAGRAM.md
+docs/RESEARCH_POTENTIAL.md
+
+# Optional Documentation (not required for ref-agents runtime)
+docs/architecture/
+docs/design/
+docs/features/
+docs/guides/
+docs/process/
+docs/product/
+docs/requirements/README.md
+docs/requirements/FLOW_DIAGRAM.md
+
+# Security Reports
+bandit-report.json
+pip-audit-report.json
+*.json
+
+# Committed supply-chain artifacts (regenerated via scripts/generate_sbom.py).
+# NOTE: must override the blanket *.json ignore above — these ship as evidence.
+!docs/sbom.json
+!docs/runtime_licenses.json
+
+# Generated Reports (auto-generated by agents, not needed in package)
+ref-reports/
+docs/project_status.md
+
+# Per-story lifecycle artifacts (generated by REF agents, not permanent docs)
+docs/analysis/
+docs/closure/
+docs/specs/
+docs/test_repo/
+
+# Playwright MCP cache
+.playwright-mcp/
+
+# Binary / exported assets (not source artifacts)
+docs/*.html
+docs/*.jpeg
+docs/*.jpg
+docs/*.png
+
+# API Keys (never commit)
+api_keys.json
+src/ref_agents/api_keys.json
+/docs/superpowers_concept_integration.txt
+/docs/COMPLIANCE_METRICS.md
+/docs/MARKETING_STORYBOARD.md
+/docs/METRICS_SUMMARY.md
+/docs/MIGRATION_MAP.md

ref_agents-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,80 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+
+  - repo: local
+    hooks:
+      - id: detect-secrets
+        name: detect-secrets (Audit)
+        entry: bash -c 'NEW_SECRETS=$(uv run detect-secrets scan . 2>/dev/null | uv run detect-secrets audit --diff --baseline .secrets.baseline - 2>/dev/null | grep -c "Secret Type" || true); [ "$NEW_SECRETS" -gt 0 ] && echo "❌ $NEW_SECRETS new secrets detected!" && exit 1 || echo "✅ No new secrets"'
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: bandit
+        name: bandit (SAST)
+        entry: bash -c 'uv run bandit -r src/ -f json -o bandit-report.json --exit-zero && uv run python -c "import json, sys; d=json.load(open(\"bandit-report.json\")); hc=[r for r in d.get(\"results\",[]) if r.get(\"issue_severity\") in [\"HIGH\",\"CRITICAL\"]]; sys.exit(1 if hc else 0)"'
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pip-audit
+        name: pip-audit (Dependencies)
+        entry: bash -c 'uv run pip-audit . --desc --format json --output pip-audit-report.json 2>/dev/null || true; grep -qE "severity.*CRITICAL|severity.*HIGH" pip-audit-report.json 2>/dev/null && echo "❌ CRITICAL/HIGH vulnerabilities!" && exit 1 || echo "✅ Dependencies safe"'
+        language: system
+        pass_filenames: false
+        always_run: true
+
+
+  - repo: local
+    hooks:
+      - id: check-policy
+        name: Policy Scan (Security/License/URL)
+        entry: uv run python -m ref_agents.security_scan --no-report
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: check-lock
+        name: Check usage of uv.lock
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pytest-collect
+        name: pytest (Test Collection & Import Check)
+        entry: bash -c 'uv run pytest --collect-only -q || (echo "❌ Test collection failed - fix imports before committing" && exit 1)'
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pytest-fast
+        name: pytest (Fast Smoke Tests - Stop on First Failure)
+        entry: bash -c 'uv run pytest -x --maxfail=1 -q || (echo "❌ Tests failed - fix before committing" && exit 1)'
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: ruff-format-validate-all
+        name: Validate all files are formatted
+        entry: bash scripts/check-format.sh
+        language: system
+        pass_filenames: false
+        always_run: true

ref_agents-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

ref_agents-1.0.0/.secrets.baseline

@@ -0,0 +1,141 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {
+    "Makefile": [
+      {
+        "type": "Secret Keyword",
+        "filename": "Makefile",
+        "hashed_secret": "e441659cd1b30148c99024a81228d16b63f772af",
+        "is_verified": false,
+        "line_number": 26
+      }
+    ]
+  },
+  "generated_at": "2025-12-26T12:10:33Z"
+}