AGENT SKILL

vibey-quality-gates

The 7-gate CI sweep (ruff check, ruff format, mypy, per-layer coverage × 4, lint-imports, bandit, pip-audit), what each gate catches, the other CI jobs, and the workspace tenants' own checks.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
3

01 前言 Front Matter

name
vibey-quality-gates
description
The 7-gate CI sweep (ruff check, ruff format, mypy, per-layer coverage × 4, lint-imports, bandit, pip-audit), what each gate catches, the other CI jobs, and the workspace tenants' own checks.
allowed-tools
Bash

03 SKILL.md 正文

vibey quality gates

CI runs a 7-gate sweep over the root vibey package, split over two jobs in .github/workflows/ci.yml: lint (named "Lint and static gates": Gates 1, 2, 3, 3b and 5 with the corpus index and TypeScript artifact checks) and gates (the test run, Gate 4, bandit and pip-audit). All seven must pass — together with the other CI jobs below — before a PR can merge. Run them locally with pre-commit run --all-files --hook-stage pre-push (a plain pre-commit run --all-files runs only the ruff hooks) or individually:

Gate 1: ruff check

Linter. Catches unused imports, undefined names, syntax errors, and common anti-patterns.

uv run ruff check .

Root ruff covers src/**/*.py and tests/**/*.py, so it also lints the workspace tenants under src/vibey_runners/ and src/vibey_tools/.

Gate 2: ruff format --check

Formatter. Ensures consistent code style across the repo. Fails if any file would be reformatted.

uv run ruff format --check .

To fix: uv run ruff format .

Gate 3: mypy --strict

Type checker. Enforces --strict mode across src/vibey/. Catches type errors, missing type annotations, and Any usage.

uv run mypy --strict src/vibey

Gate 3b runs the same checker over the other declared trees (scripts/, the storm tools and the tenants), read from [[tool.vibey.static_gates]]:

uv run python scripts/static_gates.py

Gate 4: pytest per-layer coverage (100%)

One test run produces a combined .coverage file; four per-layer reports enforce 100% branch coverage. Each must pass or the build fails.

uv run pytest -q -p no:cacheprovider --cov=vibey --cov-branch --cov-report=
uv run coverage report --include='src/vibey/domain/*' --fail-under=100
uv run coverage report --include='src/vibey/application/*' --fail-under=100
uv run coverage report --include='src/vibey/infrastructure/*' --fail-under=100
uv run coverage report --include='src/vibey/cli/*' --fail-under=100

Why per-layer, not aggregate? Because domain/ is the safety-critical layer and must never drop below 100%. An aggregate gate would allow a 95% domain to hide behind a 100% infrastructure. See ADR-0023.

The test run needs a reachable Postgres even for a subset: tests/conftest.py clones a migrated template database per xdist worker at session start. See the vibey-testing skill.

Gate 5: lint-imports

Onion architecture enforcer. Verifies dependencies point inward only, and that domain/ imports nothing but stdlib.

uv run lint-imports

If it fails, the error names the contract and the violating import. See .importlinter for the contracts: onion-layers, domain-independence, application-independence, and the declare-only contracts that keep each interfaces/ package from importing its consumers (interfaces-declare-only for application/interfaces, infrastructure-interfaces-declare-only, vibey-gh-interfaces-declare-only). The declare-only rule applies to every interfaces/ package. See ADR-0016.

See the vibey-architecture skill before fixing a violation.

Gate 6: bandit

Security linter. Scans for common security issues: hardcoded passwords, SQL injection, insecure temp files, weak crypto, shell=True, etc.

uv run bandit -q -r src/vibey

Gate 7: pip-audit

Dependency vulnerability scanner. Checks for known CVEs in pinned dependencies.

uv run pip-audit

The npm lockfiles (the root workspace and clients/app) get the same gate from vibey-gh advisory-check in the @vibey/core, app and the two VS Code extension jobs: npm audit at [advisories] audit_level (high), less the declared exceptions in .github/advisory-exceptions.toml. An exception is never a silent skip: it names one advisory, package and workspace, records why the vulnerable code is not reached, and expires within max_exception_days (30). Every run prints each exception it honours and until when, and fails when one has expired, matches nothing (remove it), or its package has a patched release (take the fix). The file is a protected path, so accepting a risk takes the code owner's approval and a human merge. An outage of the advisory service itself is handled separately: on_unavailable = "fail" is the default, and this repository sets "warn", so a nonresponsive endpoint prints ::warning:: naming the workspace and the reason and continues unaudited; a real advisory, a malformed report or a missing lockfile still fails. SECURITY.md, "Dependency advisories", has the rest.

Hook diet

The seven gates are split across git hook stages so commits stay fast (.pre-commit-config.yaml):

Pre-commit stage (runs on every git commit):

  • ruff (--fix) + ruff format, on changed files

Pre-push stage (runs on every git push):

  • The plain parallel test suite (uv run pytest -q -p no:cacheprovider) — kept so a test failure reports as itself rather than as a coverage-gate failure
  • mypy --strict
  • lint-imports
  • Per-layer 100% coverage gates (pytest --cov + four reports)
  • bandit
  • pip-audit

Commit-msg stage: Conventional Commits enforcement.

Pushing: push through the push gate, never with a bare git push. Run python3 <storm>/tools/push_gate.py run -- git push origin HEAD:<branch>, or from a checkout with no storm, set VIBEY_PUSH_LOCK=<dir> and run the tracked docs/plans/qwenstorm-3.0.0/tools/push_gate.py. It lets one pre-push run happen at a time across every lane on the machine. Exit 124 (reaped: hang) means the reaper stopped a hung gate run; it is not a test failure. CONTRIBUTING.md, "Pushing in this repository", has the rest.

Install all three hook types once, then the provenance hooks, with one idempotent command (the order matters, because pre-commit install refuses to run while core.hooksPath is set, and the command does it in that order):

uv run --extra dev vibey-gh setup

vibey-gh install points core.hooksPath at .githooks. The tracked shims there (pre-commit, commit-msg.local, pre-push.local) chain back to the framework through git rev-parse --git-common-dir, so one install covers the main checkout and every linked worktree (git worktree add). If a shim prints warning: the pre-commit framework's <stage> hook is not installed, the commit or push went ahead but none of that stage's gates ran. Run them by hand before you push.

The other CI jobs

ci.yml runs fourteen jobs on every push and PR to develop/main. The seven below are the Python and deployment gates; the others are noloss (the no-loss property suite at 10,000 examples), postgres-compatibility (the database suite on PostgreSQL 14 to 18), krypton-app, vibey-core (@vibey/core), app (the krypton app, mobile and web), the two VS Code extension jobs (Ubuntu and macOS) and desktop (the krypton desktop client on Ubuntu, Arch, Fedora and macOS, where it also bundles, verifies, launches and images the app):

Job What it checks
uv-lock uv lock --check. gates, tools and tools-lint depend on it. The lock carries vibey's own version, so a version bump without uv lock fails here first.
gates The seven gates above, against a postgres:17 service. postgres-compatibility additionally runs the database suite on PostgreSQL 14, 15, 16, 17, and 18.
tools Each absorbed tenant's own suite on its own Python floors, plus, on its floor row, its own static gates from the row's static key: its mypy, lint-imports and bandit. codexloop and vibey-skills also run their own strict docs builds (the docs key) (ADR-0022).
tools-lint vibey-gh's own linters and its managed-automation drift check.
image Builds deploy/docker/Dockerfile for amd64 and arm64 and asserts each Image contract - … step: the entrypoint runs, it runs as non-root uid 10001, it has no compiler/uv/pip, migrations ship in the image, and every console script is on PATH.
chart Render-only: deploy/helm/golden/render.sh runs helm lint --strict and helm template for each profile (defaults, ollama.enabled, the GPU + gptossloop wiring with qwenloop switched on beside it, and the KEDA query unbound and bound to a project) and diffs each render against its committed golden under deploy/helm/golden/, with helm pinned. After an intended chart change, regenerate with deploy/helm/golden/render.sh --update.
cluster-smoke Helm install of deploy/helm/vibey on minikube and four cluster contracts: a projectless worker parks instead of crash-looping, the worker picks up a project created in-cluster, the KEDA ScaledObject reconciles against real Postgres, and a worker drains promptly on SIGTERM (ADR-0025, ADR-0026).

Other workflows also gate a merge: provenance.yml (runs on every push and PR), and pr-evaluate.yml, which re-evaluates a PR each time CI or Provenance completes and dispatches pr-review.yml for the review ([pr_automation] scan_workflows in .vibey-gh.toml) and hands ready PRs to merge-train.yml (see the vibey-releasing skill).

Workspace tenants: their own checks

The tenants under src/vibey_runners/ and src/vibey_tools/ keep the gates they arrived with (ADR-0021, ADR-0022). The root mypy, bandit and coverage gates cover src/vibey only. Run a tenant's checks from its own directory, with plain pip and a Python at its floor — every tenant now shares the 3.12 floor, so the matrix exercises the common 3.12–3.14 range. Plain pip knows nothing about [tool.uv.sources] workspace = true, so a tenant that needs a sibling installs that sibling from the tree first -- no family package may be requested from an index, because none of them is published any more (ADR-0037). These are the tools and tools-lint commands, verbatim:

# vibey-gh (CI: Python 3.12, 3.13, 3.14; 100% branch floor in its own addopts)
cd src/vibey_tools/gh
pip install -e ".[dev]"
python -m pytest -q
python -m black --check vibey_gh test
isort --check-only vibey_gh test
python -m mypy vibey_gh

# vibey-skills (CI: Python 3.12, 3.13, 3.14)
cd src/vibey_tools/skills
pip install -e .
python3 tools/validate_manifests.py && python3 tools/check_links.py \
  && PYTHONPATH=src python3 -m unittest discover -s tests

# vibey-bootstrap (CI: Python 3.12, 3.13, 3.14). It imports vibey_gh, so install that first.
cd src/vibey_tools/bootstrap
pip install -e ../gh && pip install -e ".[test,all]"
pytest test/ -m "not integration" --cov=vibey_bootstrap --cov-report=term

# claudeloop (CI: Python 3.12, 3.13, 3.14 -- the common library floor)
cd src/vibey_runners/claude
pip install -e ../common && pip install -e ".[dev]"
pytest tests/domain --cov=claudeloop.domain --cov-branch --cov-report=term-missing --cov-fail-under=100
pytest tests/application --cov=claudeloop.application --cov-branch --cov-report=term-missing --cov-fail-under=100
pytest tests/infrastructure -n auto --maxprocesses=8 --cov=claudeloop.infrastructure --cov-branch --cov-report=term-missing --cov-fail-under=100
pytest tests/cli -n auto --maxprocesses=8 --cov=claudeloop.cli --cov-branch --cov-report=term-missing --cov-fail-under=100

# codexloop (CI: Python 3.12, 3.13).
cd src/vibey_runners/codex
pip install -e ../common && pip install -e ".[dev]"
pytest -q --cov=codexloop --cov-branch --cov-report=
coverage report --include='src/codexloop/domain/*' --fail-under=100
coverage report --include='src/codexloop/application/*' --fail-under=100
coverage report --include='src/codexloop/infrastructure/*' --fail-under=100
coverage report --include='src/codexloop/cli/*' --fail-under=100

# qwenloop (CI: Python 3.12, 3.13, 3.14; its floor is already in its addopts)
cd src/vibey_runners/qwen
pip install -e ".[dev]"
python -m pytest -q

vibey-gh's suite drives real git history and shells out to gh, so it needs both on PATH and a full clone -- a shallow one fails. It does not need uv: the single test that drives a real uv lock is marked network, below.

Tests that leave the machine (a real package index, a real remote) carry @pytest.mark.network and are skipped unless VIBEY_GH_NETWORK_TESTS=1. Marker and variable are two halves of one mechanism -- the marker declares, and test/conftest.py does the skipping -- so a plain offline python -m pytest reaches the package's 100% branch floor with no flag to remember, and a run that reports 4 skipped is correct rather than degraded. Every branch a network test touches must also be reachable offline, or that floor fails. Where an index is reachable, ask for them by name:

cd src/vibey_tools/gh
VIBEY_GH_NETWORK_TESTS=1 python -m pytest -q -m network --no-cov

CI runs that on one matrix row with continue-on-error: it reports on somebody else's service, so it must never gate a merge.

The runners (src/vibey_runners/{claude,codex,qwen}) carry their own tests/, ruff, mypy and import-linter configuration in their pyproject.toml. Since 2026-09-15 the root tools matrix runs all three, one row per runner and Python version (read the rows in ci.yml), so a runner regression turns the tools job red. It reports rather than blocks: tools is not named in required_checks in .vibey-gh.toml, and no tools row ever has been. Read a runner's [tool.pytest.ini_options] before running anything by hand. Only qwenloop's addopts carry a coverage floor. The other two deliberately leave --cov= and --cov-fail-under out, because pytest-cov unions every --cov= it sees and one baked in there would widen the explicitly-scoped per-layer runs back out to the whole package -- so for them a bare pytest runs the tests but enforces no floor. Use the commands above, which are their own.

Where work lives, and how often it is saved

Keep every clone and worktree on storage a reboot keeps (sub-doctrine 10.h, ADR-0057). Never use /tmp, /private/tmp, /var/tmp, /var/folders, /dev/shm, /run/user or $TMPDIR: the OS empties them. On 2026-09-24 a reboot emptied /private/tmp mid-storm and took every uncommitted worktree, measurement and draft with it. Worktrees go in the storm home: VIBEY_STORM_HOME, else ~/git/vibey-storm on macOS, $XDG_DATA_HOME/vibey/storm (else ~/.local/share/vibey/storm) on Linux.

python3 docs/plans/qwenstorm-3.0.0/tools/storm_durability.py status   # durable or not
git worktree add "$(python3 docs/plans/qwenstorm-3.0.0/tools/storm_durability.py worktree fix-x)" \
  -b fix/x origin/develop
  • Commit as soon as a change is coherent, not when it is finished.
  • Push work in progress to a draft PR (gh pr create --draft) at least every 30–45 minutes; the merge train never merges a draft, and the pre-push gates still run.
  • A long measurement writes each step as it finishes and resumes (StepJournal in docs/plans/qwenstorm-3.0.0/tools/storm_checkpoint.py).
  • The storm tools refuse volatile storage with exit 78 and name the key to change. CONTRIBUTING.md, "Where your work lives", has the rest.

What each gate catches

Gate Catches
ruff check Unused imports, undefined names, syntax errors, anti-patterns
ruff format Inconsistent code style
mypy --strict Type errors, missing annotations, Any usage
pytest (per-layer 100%) Untested branches, logic errors, regressions
lint-imports Onion violations, forbidden imports
bandit Security issues, hardcoded secrets, insecure patterns
pip-audit Dependency CVEs

04 同仓库更多 Skills

the-vibey-project
the-vibey-project/vibey

white-paper-writing

Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks "how should I structure this" for a long-form document.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-technical-mechanics

Use when editing or writing prose at a technical/mechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-mechanics

Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate/Jamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix "AI-sounding" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.

★ 5
the-vibey-project
the-vibey-project/vibey

narrative-structure

Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or "how should I structure this story/pitch/presentation" request.

★ 5
the-vibey-project
the-vibey-project/vibey

legal-brief-writing

Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic/neurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.

★ 5
the-vibey-project
the-vibey-project/vibey

journal-publishability-criteria

Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs/paper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.

★ 5