Vibe

Mission: make intent the source code and preserve it through compilation.

Vibe is an intent-first language and compiler. A compile is accepted only when verification reports that emitted artifacts preserve intent above the configured bridge threshold.

---

What Vibe is

Vibe is a local-first compiler toolchain around .vibe specs.

Pipeline:

intent spec (.vibe) -> parse -> typed IR -> verify -> proof/report -> emit

Core law:

• Intention is source code.
• Preservation is compilation truth.

If preservation checks fail, emission is blocked.

---

Current status (implemented phases snapshot)

Vibe currently includes:

• Phase 1.x parser + typed IR foundations.
• Phase 2.x verification obligation surfaces, backend abstraction, SMT-ready slice, and semantic correspondence reporting.
• Phase 3.x deterministic emit targets and reporting improvements.
• Phase 4.x calibration and proof artifacts.
• Phase 5.x package manifest/build foundations.
• Phase 6.2 local-first intent registry (publish/search/registry-inspect/compat).
• Phase 6.3 local LSP server.
• Phase 6.4 CI bridge-check integration (including GitHub Actions bridge-check action).
• Phase 7A–7.4 cross-domain profiles and initial hardware/scientific/legal/genomics slices.
• Phase 8.1 bounded self-hosting self-check.
• Phase 8.2 semver derivation from semantic intent diff.
• Phase 8.3 intent negotiation protocol.
• Phase 8.4 intent-as-interchange layer (interchange-from-text, intent-brief, proof-brief) for bounded NL->.vibe scaffolding and machine-consumable proof summaries.
• Initial standard-library package set (vibe_http, vibe_payment, vibe_vector, vibe_agent) as reusable intent contracts.

This is still a prototype compiler with bounded slices, not complete language coverage.

---

Quickstart

python -m pip install -e .

Verify an intent spec:

vibec verify vibe/examples/payment_router.vibe

Store a local snapshot and verify by snapshot id:

vibec snapshot-put vibe/examples/payment_router.vibe --report json
# capture snapshot_id from output
vibec verify --snapshot <sha256> --snapshot-store ./.vibe_snapshots --report json

Compile when preservation passes:

vibec compile vibe/examples/payment_router.vibe

Generate proof artifact explicitly:

vibec verify-proof vibe/examples/payment_router.vibe

Run tests:

python -m pytest -q

---

PhiPython v1.4 (guided Python layer inside Vibe)

PhiPython is a bounded, deterministic Python authoring layer inside Vibe, not a separate product.

• Vibe remains the intent-first source-of-truth system.
• PhiPython adds guided Python learning/building flows.
• Python is used as a practical emit/runtime target where appropriate.

Current PhiPython v1.4 scope:

• scaffold generation for starter Python projects (cli, automation, api_tool, scraper, flask_app, dashboard),
• deterministic snippet registry with metadata/placeholders (forloop, readfile, writejson, api_get, tryexcept, flask_app, argparse_cli, pandas_csv, requests_json, file_append, env_var),
• plain-English Python explanation helpers for common beginner constructs,
• plain-English translation for common Python exception types,
• bounded intent-to-Python scaffold bridge for structured starter inputs,
• bounded fix engine for common starter mistakes (candidate fixes only),
• bounded traceback parser + traceback-aware fix suggestions,
• bounded scaffold-from-intent helper (template selection + starter generation),
• optional safe patch preview/apply flow for a narrow set of high-confidence fixes,
• bounded doctor project/scaffold validation and local scaffold metadata introspection,
• interactive-style deterministic patch selection (--interactive, --select),
• constrained multi-file patch plans with preview-first per-file views,
• local exportable doctor/patch/inspect artifacts for CI-friendly review.
• starter-aware deterministic test generation (testgen) + local .phipython.tests.json manifests,
• local repair receipts for patch/plan preview/apply/reject flows,
• local review bundles that combine doctor/inspect/receipt/test-manifest artifacts.

Important truthfulness boundary:

• PhiPython v1.4 does not claim full semantic verification of arbitrary Python programs.
• Explanations and error guidance are intentionally bounded and may be heuristic.
• Fix suggestions are heuristic candidates, not guaranteed patches.
• Traceback analysis (including chain parsing) is bounded to common traceback shapes.
• Scaffold-from-intent is starter generation, not full semantic synthesis.
• Safe patching is optional, narrow, and should be reviewed via preview before --apply.
• Doctor profiles are starter/template oriented and do not guarantee runtime correctness.
• Multi-file patch plans are narrow and preview-first.
• Exported artifacts are local review artifacts, not proofs of correctness.
• Generated tests are starter-oriented guidance, not exhaustive correctness validation.
• Repair receipts are local review artifacts, not formal proofs.
• Review bundles are local operator-inspection bundles, not proof bundles.

Examples:

vibec phipython init cli
vibec phipython explain hello.py
vibec phipython translate-error --type TypeError --message "unsupported operand type(s) for +: 'int' and 'str'"
vibec phipython fix hello.py
vibec phipython fix-traceback trace.txt
vibec phipython scaffold --from-intent "build a flask starter app"
vibec phipython show-template flask_app
vibec phipython show-snippet api_get
vibec phipython doctor ./demo_app
vibec phipython patch app.py --preview
vibec phipython patch app.py --apply
vibec phipython patch app.py --interactive
vibec phipython patch app.py --select patch-001 --preview
vibec phipython patch app.py --select patch-001 --apply
vibec phipython patch-traceback trace.txt --preview
vibec phipython patch-traceback trace.txt --interactive
vibec phipython inspect-project ./demo_app
vibec phipython doctor ./demo_app --export ./artifacts
vibec phipython inspect-project ./demo_app --export ./artifacts
vibec phipython testgen ./demo_cli --preview
vibec phipython testgen ./demo_cli --apply
vibec phipython show-test-profile cli
vibec phipython receipts ./demo_cli
vibec phipython bundle ./demo_cli --out ./artifacts

---

CLI overview

Primary commands:

• vibec compile <file.vibe> — verify + emit when preservation passes.
• vibec verify <file.vibe> — verification only.
• vibec snapshot-put <file.vibe> — store local file in content-addressed snapshot store.
• vibec verify --snapshot <sha256> --snapshot-store <dir> — verify blob content by content hash.
• vibec verify-proof <file.vibe> — verification + proof artifact write.
• vibec inspect-proof <file.vibe.proof.json> — inspect proof summary.
• vibec diff <old.vibe> <new.vibe> — semantic intent diff.
• vibec merge-verify <base.vibe> <left.vibe> <right.vibe> — conservative three-way merge + verification.
• vibec semver <old.vibe> <new.vibe> — derive recommended semver bump.
• vibec negotiate <a.vibe> <b.vibe> ... — deterministic contract negotiation.
• vibec init / manifest-check / build — package lifecycle.
• vibec publish / search / registry-inspect / compat — local registry operations.
• vibec lsp — local LSP server over stdio.
• vibec phipython init <template> — create starter Python scaffolds.
• vibec phipython explain <file.py> — plain-English explanation for simple Python files.
• vibec phipython explain-snippet <trigger> — describe snippet usage and starter code.
• vibec phipython show-template <template> — show scaffold metadata and starter file layout.
• vibec phipython show-snippet <trigger> — show snippet metadata and expanded default body.
• vibec phipython translate-error --type <ExceptionName> --message <msg> — plain-English error guidance.
• vibec phipython fix <file.py> — bounded candidate fixes for common starter issues.
• vibec phipython fix-traceback <traceback.txt> — bounded traceback parsing and fix hints.
• vibec phipython scaffold --from-intent "<text>" — bounded intent-to-template scaffold helper.
• vibec phipython doctor <path> — bounded scaffold/project validation checks.
• vibec phipython patch <file.py> [--interactive|--select <id>] [--preview|--apply] — narrow safe patch candidate selection + preview/apply.
• vibec phipython patch-traceback <traceback.txt> [--interactive|--select <id>] [--preview|--apply] — traceback-driven patch selection + preview/apply for safe cases.
• vibec phipython inspect-project <path> [--export <dir>] — inspect scaffold metadata/file structure and optionally export review artifacts.
• vibec phipython doctor <path> [--template-profile <name>] [--export <dir>] — template-aware bounded doctor checks + optional artifact export.
• vibec phipython testgen <path> [--template <id>] [--preview|--apply] — bounded starter-aware pytest generation.
• vibec phipython show-test-profile <template> — inspect bounded test generation profile coverage for a starter template.
• vibec phipython receipts <path> — inspect local repair receipts for patch/plan flows.
• vibec phipython bundle <path> --out <dir> — build a local review bundle combining doctor/inspect/receipt/test-manifest artifacts.
• vibec phipython list-templates / list-snippets — inspect deterministic PhiPython registries.
• vibec ci-check — deterministic CI bridge checks.
• vibec self-check — bounded self-hosting check.
• vibec domains — list domain profiles.
• vibec stdlib-list — list built-in standard-library packages in stdlib/.
• vibec interchange-from-text <requirements.txt> — deterministic NL-to-.vibe interchange scaffold artifact.
• vibec intent-brief <file.vibe> — deterministic machine-readable intent brief.
• vibec proof-brief <file.vibe.proof.json> — deterministic machine-readable consumer proof brief.

---

Language pipeline and architecture

Current compile/report spine:

1. Parse .vibe source into AST.
2. Lower to typed IR.
3. Generate verification obligations from preserve/constraint/bridge/domain metadata.
4. Evaluate obligations with configured backend(s).
5. Compute bridge/preservation outcome.
6. Produce report + optional proof artifact.
7. Emit target artifact only when gate passes.

The architecture is deterministic-by-default for local reproducibility.

---

Verification, proofs, and calibration (truthful scope)

What exists now:

• Machine-checkable obligation outcomes and preservation gate decisions.
• Deterministic proof artifact output (.vibe.proof.json) with hashes, backend metadata, summaries, and evidence surfaces.
• Optional empirical calibration path for epsilon estimation.
• Runtime monitor metadata surfaces.

What this is not:

• Not full formal verification of arbitrary program semantics.
• Not complete theorem proving across all language features.

When this README says “proof,” it refers to current machine-checkable proof metadata produced by Vibe’s implemented verifier/proof pipeline.

Muse integration JSON contract (Issue #34 kickoff)

For the Vibe-side integration contract consumed by Muse (verify --report json, diff --report json, and .vibe.proof.json schema/versioning), see docs/muse_integration_contract.md.

Snapshot mode and proof provenance are explicitly local-first:

• snapshot-put writes only to a local content-addressed store.
• snapshot verification proof artifacts include honest provenance (input_mode, snapshot_id, snapshot_store) and do not claim filesystem source paths for snapshot inputs.

External obligation registration seam (Phase 4A)

Vibe now includes a controlled Python-level extension seam for registering additional obligation categories.

What it does today:

• lets Python code register deterministic external obligation providers by category name,
• executes registered providers during verify,
• surfaces resulting obligations through normal machine-readable outputs (verify --report json, .vibe.proof.json).
• emits provider execution diagnostics (external_obligation_providers) with stable provider identity, emitted count, status summary, and error fields.

What it does not do yet:

• no plugin marketplace or automatic discovery,
• no remote loading,
• no automatic bridge-score math changes for external obligations.

Minimal API:

from vibe.obligation_registry import register_external_obligation_provider

---

Package manager, registry, LSP, and CI

Package manager

Vibe packages use vibe.toml and package-local module graphs.

Key flows:

• vibec manifest-check <path-or-manifest>
• vibec build <path-or-manifest>

Local registry

Vibe includes a local-first filesystem registry.

Key flows:

• vibec publish <project-dir>
• vibec search <query>
• vibec registry-inspect <package[@version]>
• vibec compat <packageA[@version]> <packageB[@version]>

Registry entries include package metadata and proof-status surfaces from the current pipeline.

LSP

Vibe includes a stdio Language Server for editor integration (diagnostics, symbols, completion/hover slices, semantic tokens).

CI

vibec ci-check provides deterministic bridge-check outputs for local CI and GitHub Actions usage.

merge-verify --report json now includes bridge-aware verification_context (base/left/right/merged summaries + merged-vs-base bridge delta), conservative intent_conflicts, and a bounded regression_evidence block (top problematic obligations) for CI triage. Use --regression-top-n <int> to tune only regression-evidence verbosity (with deterministic clamping); it does not change merge/verification outcomes. Use --require-merged-bridge <float> to enforce a minimum merged bridge_score in CI (opt-in; default behavior unchanged). Use --max-bridge-regression <float> to enforce an upper bound on allowed bridge regression vs base (bridge_score_delta_vs_base >= -value), e.g. 0.00 disallows any regression and 0.05 allows regression up to 0.05. Use --fail-on-intent-conflicts to fail merges that still produce non-empty intent_conflicts (opt-in; default behavior unchanged). When any merge policy flag is used, merge-verify JSON includes policy_evaluation with requested, available, passed, and per-check machine-readable status rows.

---

Cross-domain support summary

Implemented domain profile slices include:

• hardware
• scientific simulation
• legal/compliance
• genomics

These currently provide bounded, deterministic metadata/check/emitter surfaces and are intended to expand iteratively.

---

Ecosystem: initial standard library

Vibe now includes an initial standard library of reusable intent packages under stdlib/.

Current packages:

• stdlib/vibe_http
• stdlib/vibe_payment
• stdlib/vibe_vector
• stdlib/vibe_agent

Design intent:

• packages are reusable intent contracts, not generic helper-code dumps,
• packages participate in normal manifest-check/build/verify-proof/publish flows,
• package metadata is registry-visible,
• proof metadata is machine-checkable through the existing verifier/proof pipeline.

Example flows:

vibec manifest-check stdlib/vibe_http --report json
vibec build stdlib/vibe_http --report json
vibec verify-proof stdlib/vibe_http/src/main.vibe --report json
vibec publish stdlib/vibe_http --report json
vibec search http --report json
vibec registry-inspect vibe_http@0.1.0 --report json
vibec stdlib-list --report json

Scope note: this is an initial, bounded standard library. Coverage will expand in future phases.

---

Intent as universal intermediate language (Phase 8.4 roadmap alignment)

Vibe now treats .vibe as an interchange contract between humans/LLMs/agents and downstream compilers/proof consumers.

Implemented bounded interchange slice:

• vibec interchange-from-text <requirements.txt> builds a deterministic NL-to-.vibe interchange artifact (scaffold, not autonomous correctness magic).
• vibec intent-brief <file.vibe> exports a deterministic machine-readable intent contract summary.
• vibec proof-brief <file.vibe.proof.json> exports a deterministic machine-readable consumer brief from proof data.

This enables the roadmap pipeline:

natural language requirement -> interchange artifact -> .vibe intent contract -> verify/prove -> machine-consumable proof brief.

Truthfulness boundaries:

• no live hosted LLM provider integration in this phase,
• no claim of perfect natural-language understanding,
• no claim that proof brief equals complete formal behavioral proof.

---

Self-hosting, semver, and negotiation

• Self-hosting (8.1): bounded compiler self-check with baseline/regression surfaces.
• Semver (8.2): semantic intent diff drives recommended version bump categories.
• Negotiation (8.3): deterministic merged intent contracts + explicit conflict reporting.

These are integrated with the CLI and intended to support local-first release governance.

---

Repository layout

• vibe/ — compiler, verifier, emitters, registry, CLI, domain slices, LSP.
• stdlib/ — standard-library packages (Phase 8.4).
• tests/ — unit/integration tests.
• .github/actions/bridge-check/ — native bridge-check action.
• .github/workflows/ — CI workflow examples.
• docs/ — project site (docs/index.html).
• self_hosting/ — bounded self-hosting specs/artifacts.

---

Current boundaries and non-goals

• Vibe is not claiming full formal verification across all emitted behaviors.
• Vibe is not claiming complete self-bootstrap yet.
• Vibe stdlib is intentionally small in this phase (4 packages).
• Domain slices are bounded and intentionally incremental.

The project prioritizes deterministic, inspectable preservation surfaces over broad but unverifiable feature claims.

---

Roadmap / next steps

Near-term:

• Expand stdlib package set and inter-package contract surfaces.
• Broaden semver and compatibility rule coverage.
• Deepen negotiation rules for richer multi-party contracts.
• Continue hardening verifier backends and diagnostics.
• Expand bounded self-hosting slices toward fuller compiler coverage.

---

License

MIT — see LICENSE.