Vibecheck

Vibecheck is a typed classification, scoring, and decision service. A caller submits state and trusted facts, selects a versioned policy, and receives the typed Jev answers plus the deterministic outcome that policy selected. The caller, not Vibecheck, executes or enforces the result.

The service runs. It serves the REST API under /v1, a Streamable HTTP MCP endpoint at /mcp, and the unversioned /healthz and /ready probes on one public listener, with Prometheus metrics on a separate internal listener.

Read references/setup.md before changing the repository. It records the supported commands.

Security and safety

• Treat submitted state, policy files, provider responses, and database data as untrusted at their boundaries.
• Never put provider keys, API tokens, or real request data in tracked files, prompts, examples, test fixtures, or logs.
• Vibecheck returns decisions. Do not add shell execution, arbitrary webhooks, or other ambient authority unless the user explicitly changes that product boundary.
• Do not hand-edit Servicepack-owned files. Update them with the documented Servicepack workflow.

When to use

• Implementing or reviewing the Vibecheck policy engine, Jev adapter, persistence, HTTP API, MCP surface, or audit trail.
• Running the repository's Docker-backed build, generation, lint, test, coverage, security, Compose, or image checks.
• Checking whether public docs and integrations match code that has actually landed.

When not to use

• Treating a model probability as permission to execute an action.
• Inventing routes, MCP tools, policy fields, or configuration beyond the implementation.
• Editing framework-owned files directly.

Work in the repository

Use the Make targets. They run the pinned Go toolchain and checks in Docker:

make generate
make build
make lint
make test
make test-integration
make test-api
make test-coverage
make sec
make audit-compose
make docker-build

Application code belongs under internal/pkg/services/, with project hooks in cmd/init.go, commands in cmd/commands.go, and integration coverage under tests/.

Framework boundary

Servicepack owns internal/app/, internal/pkg/service-manager/, pkg/runner/, cmd/main.go, Makefile.servicepack, scripts/make/servicepack/, Dockerfile.servicepack*, and servicepack.version. Use make servicepack-update, review and test its update branch, then merge through make servicepack-update-merge.

Verify claims

Before documenting or using a route, tool, config value, or response field, find the registered implementation and its behavioral test. api/api.yml is the source of truth for the REST contract, and the six MCP tools are registered in internal/pkg/mcp. Both transports call the same services in internal/pkg/core, so a decision made over MCP produces the same audit row as the same decision made over REST.

The MCP tools are vibecheck_evaluate, vibecheck_list_policies, vibecheck_get_policy, vibecheck_get_evaluation, vibecheck_validate_policy, and vibecheck_submit_feedback.