vibegate 0.1.0a7

Deterministic production readiness gate for vibe-coded FastAPI repos.

VibeGate

VibeGate runs deterministic readiness checks for vibe-coded FastAPI repos and produces an evidence ledger plus a deterministic Fix Pack of remediation patches.

Status: Alpha - Automated releases via semantic-release

Quickstart

Install and run VibeGate in the way that matches your workflow.

A) Install VibeGate as a tool to run on other repos (pipx recommended)

This keeps the CLI isolated and available on your PATH.

pipx install "vibegate[tools]"

B) Install VibeGate in a project venv

Use this when VibeGate should live alongside your project dependencies.

python -m pip install "vibegate[tools]"

If you want the minimal package without tooling, install without extras.

python -m pip install "vibegate"

C) Contributor dev install

Use this when working on VibeGate itself.

python -m pip install -e ".[dev]"

Release workflow

Releases are fully automated using semantic-release based on Conventional Commits.

How it works:

1. Merge PRs with conventional commit messages to main (feat:, fix:, perf:, etc.)
2. The semantic-release workflow automatically runs on every push to main
3. If releasable commits exist, semantic-release will:
   • Determine the next version based on commit types
   • Update CHANGELOG.md automatically
   • Create and push a git tag
   • Build and publish to PyPI via Trusted Publishing
   • Create a GitHub Release with changelog notes

No manual version bumping required!

Commit types and version bumps:

• feat: → minor version bump (0.1.0 → 0.2.0)
• fix:, perf:, refactor: → patch version bump (0.1.0 → 0.1.1)
• feat!: or BREAKING CHANGE: → major version bump (0.1.0 → 1.0.0)
• docs:, chore:, ci:, test: → no release

For contributors:

• Use conventional commits (enforced by pre-commit hooks)
• See CONTRIBUTING.md for commit message format
• See docs/RELEASING.md for detailed release documentation

Manual releases (backup method):

• For emergency releases, use the hotfix workflow
• For manual control, use the deprecated prepare_release workflow
• See docs/RELEASING.md for details

Run VibeGate

One-command workflow (recommended for humans):

# Does everything: creates config if missing, verifies tools, runs checks
vibegate start .

Evolution workflow (for maintainers improving check quality):

# Full cycle: check → triage (optional) → tune → propose
vibegate evolve .

Step-by-step workflow (CI and manual control):

vibegate init .      # Create config
vibegate doctor .    # Verify tools
vibegate check .     # Run checks
vibegate triage .    # Label findings interactively (TTY only)
vibegate tune .      # Generate tuning recommendations
vibegate propose .   # Generate actionable proposal pack (PR-ready)

From source path (works without installing the console script):

python -m vibegate start .
python -m vibegate evolve .
python -m vibegate check .

Review artifacts:

VibeGate writes vibegate.yaml, .vibegate/suppressions.yaml, and generates artifacts/ plus evidence/. The report, fix pack, and JSONL evidence ledger are the audit trail for what ran and why it failed. artifacts/ and evidence/ are generated outputs and typically should not be committed.

List fix pack tasks without jq:

vibegate fixpack-list --path artifacts/fixpack.json

Developer install

python -m pip install -e ".[dev]"

Contributor quickstart

make install
make test
make gate
make sync-schemas

Smoke CI repro (build wheel, install, run checks):

./scripts/ci_smoke.sh

Release smoke (clean build, install newest wheel, run CLI checks):

./scripts/build_and_smoke.sh

On Windows:

./scripts/ci_smoke.ps1

Demo

Try the demos:

• examples/fastapi-demo/ (fails: a test expectation mismatch)
• examples/fastapi-demo-fixed/ (passes)

Each demo includes a run_vibegate.sh script that runs python -m vibegate check . and prints where artifacts and evidence land.

CI example (GitHub Actions)

- name: Install VibeGate
  run: pipx install "vibegate[tools]"
- name: Run VibeGate
  run: |
    vibegate doctor .
    vibegate check .

Why the helper scripts exist (zsh-safe)

Shells like zsh can error on unmatched globs (for example, dist/*.whl). The helper scripts in scripts/ avoid that footgun by using find and explicit selection of the newest wheel.

Hello Plugin walkthrough

VibeGate supports external check plugins via Python entry points. A minimal example plugin lives at examples/hello-plugin/.

1. Install the example plugin in editable mode:

python -m pip install -e examples/hello-plugin

2. Enable the plugin in vibegate.yaml:

plugins:
  checks:
    enabled:
      - hello

3. (Optional) Customize the message from the plugin:

plugins:
  checks:
    config:
      hello:
        message: "Hello from my repo!"

4. Run VibeGate as usual:

vibegate check .

You should see a new finding with check_id set to plugin.hello in the report.

Local dev

python -m pip install -e ".[dev]"
pytest

Continuous Integration

CI runs a fast Ubuntu job on every pull request targeting main, and runs a broader OS matrix on pushes to main (plus manual workflow dispatches). Each job installs dev dependencies, runs the test/check steps, and always uploads debugging artifacts from artifacts/ and evidence/ to the workflow run's "Artifacts" section in GitHub Actions.

Expected output files

Defaults (can be overridden by vibegate.yaml):

• artifacts/vibegate_report.md
• artifacts/fixpack.json
• artifacts/fixpack.md
• evidence/vibegate.jsonl

Configuration contract:

• vibegate.yaml (validated against schema/vibegate.schema.json)

Profiles

Profiles let you define named override bundles (for enabling/disabling checks, severity overrides, or tool-specific configuration tweaks) and select one with profile. The base config is loaded first, then the selected profile overrides are applied on top.

Example:

profile: "strict"
profiles:
  fast:
    checks:
      tests:
        enabled: false
      dependency_hygiene:
        enabled: false
  strict:
    checks:
      sast:
        enabled: true
        severity_threshold: high
    severity_overrides:
      "sast.bandit": high
  ci:
    checks:
      runtime_smoke:
        enabled: true
    tool_overrides:
      pytest:
        args: ["-q", "--maxfail=1"]

Troubleshooting

If vibegate.yaml fails schema validation, regenerate it or fix the required fields:

vibegate init . --force

This overwrites the existing vibegate.yaml. Or fix the required fields listed in the schema errors.

What runs

Baseline checks:

• Formatting: ruff format --check
• Lint: ruff check --output-format json
• Typecheck: pyright --outputjson
• Tests: pytest -q
• Dependency hygiene: lockfile required + uv lock --check when UV is detected
• Config sanity: deterministic scanning for debug/uvicorn reload/cors/secret/placeholder patterns
• Error handling: AST-based detection of bare except, empty except blocks, generic exceptions, and missing logging
• Defensive programming: AST-based detection of missing None checks, bounds validation, and zero divisor checks
• Code complexity: Function length, nesting depth, and cyclomatic complexity analysis
• Dead code: Detection of unreachable code and commented-out code blocks (optional vulture tool integration)

Optional when the tool is on PATH:

• bandit (JSON output)
• gitleaks (JSON output)
• osv-scanner offline only when a local DB snapshot is configured
• vulture (dead code detection)

Workspace scope

VibeGate only scans files in the workspace set:

• In a Git repo, the workspace is git ls-files (tracked files).
• Outside Git, VibeGate walks the repo and applies default excludes.

Default excludes: .venv/, venv/, env/, .git/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, node_modules/, dist/, build/, .tox/, .eggs/, site-packages/, *.egg-info/.

Virtualenv site-packages are excluded by default, including .venv/site-packages and venv/site-packages.

Evidence & Fix Pack

Evidence is written as JSONL with run_start, tool_exec, finding, suppression_applied, and run_summary events. Each tool execution records argv, cwd, duration, exit code, and artifact hashes.

Fix Pack output (fixpack.json + fixpack.md) is deterministic and ordered by category: dependency hygiene → vulnerability → secrets → security → typecheck → lint → formatting → tests → config → runtime.

CLI

• vibegate check [REPO_ROOT] (defaults to .; exit 0 on PASS, 1 on FAIL, 2 on config error)
• vibegate init [REPO_ROOT] (scaffold vibegate.yaml, artifacts/, evidence/, .vibegate/)
• vibegate doctor [REPO_ROOT] (report missing tools + version drift)
• vibegate fixpack (runs checks, emits fix pack only, still writes evidence)
• vibegate fixpack-list [--path artifacts/fixpack.json] (TSV summary of fixpack tasks)
• vibegate label <fingerprint> [--false-positive|--true-positive|--acceptable-risk] --reason <reason> (label findings for quality tracking)
• vibegate tune [REPO_ROOT] (analyze labeled findings and generate tuning recommendations)
• vibegate propose [REPO_ROOT] (generate actionable proposal pack from tuning clusters)
• vibegate verify (alias of check)
• vibegate prompt (stub)

Evolving checks: The tuning workflow

VibeGate provides an offline, deterministic tuning pipeline to help you evolve check quality based on labeled findings.

Key distinction:

• Suppressions (.vibegate/suppressions.yaml) - Affect CI/CD behavior (findings are suppressed and don't cause failures)
• Labels (.vibegate/labels.yaml) - Learning signal only (track false positives, true positives, acceptable risks for analysis)

Workflow:

1. Run checks and find a false positive:

   vibegate check .
   # Review artifacts/vibegate_report.md
   

2. Label the finding:

   vibegate label sha256:abc123... --false-positive --reason "typing-context"
   

   You can also label as --true-positive or --acceptable-risk.

3. Generate tuning insights:

   vibegate tune .
   

   This produces:

   • artifacts/tuning/tuning_report.md - Human-friendly summary with actionable hints
   • artifacts/tuning/tuning_clusters.json - Machine-readable cluster data
   • artifacts/tuning/tuning_examples/ - Code snippets for each cluster

4. Generate actionable proposals:

   vibegate propose .
   

   This creates a Proposed Patch Pack with:

   • artifacts/proposals/proposal_report.md - PR-ready proposals with concrete suggestions
   • artifacts/proposals/proposals.json - Machine-readable proposal data
   • artifacts/proposals/regression_snippets/ - Code snippets that should NOT trigger after rule refinement
   • artifacts/proposals/copy_paste_snippets/ - Ready-to-use suppression snippets

5. Review and apply proposals:

   • Each proposal includes rule refinement suggestions (e.g., "Narrow AST predicate to exclude type-annotation context")
   • Copy-paste suppression snippets are provided as a last resort
   • Regression snippets help verify rule refinements don't introduce false positives
   • Use proposals to create PRs that refine rules or add regression tests

Example action hints:

• If >80% of FPs are in tests/ directory → consider ignoring test code or downgrading severity
• If many findings are in type annotations → consider guarding for type annotation context
• If findings cluster in specific file globs → consider file-glob suppression or narrower AST predicates

Note: The evolution pipeline (tune + propose) is completely offline and deterministic - no network calls, no AI models, just pattern analysis and heuristics. The propose command does NOT auto-modify files; it generates suggestions for human review.

How to add VibeGate to an existing FastAPI repo

1. Add vibegate.yaml at the repo root using the contract schema in schema/vibegate.schema.json.
2. Set project.app_module to your ASGI entrypoint (e.g. app.main:app).
3. Commit a lockfile (uv.lock, poetry.lock, or pdm.lock) and ensure it stays fresh.
4. Add .vibegate/suppressions.yaml if you need to suppress known findings with justification and expiry.
5. Run vibegate check locally and in CI, and review artifacts/fixpack.md for remediation steps.