Bridge

Bridge is a command-line tool that coordinates codebase verification. It tracks evidence obligations across your code, specifications, and tests, keeping them in sync as your system changes.

Instead of running verification checks directly, Bridge acts as a coordination layer. It maps changed files to project subsystems, checks which tests or validations are required by your policy, and helps you execute those commands and track the results.

---

Installation & Setup

Bridge 0.2.x uses the com.blockether/bridge coordinate and can be used from Babashka or the Clojure CLI.

Babashka

Install Babashka, then register Bridge in your project's bb.edn:

{:deps {com.blockether/bridge {:mvn/version "0.2.2"}}
 :tasks
 {bridge {:doc "Run Bridge"
          :requires ([bridge.cli :as cli])
          :task (apply cli/-main *command-line-args*)}}}

Clojure CLI

Add the same coordinate to deps.edn:

{:deps {com.blockether/bridge {:mvn/version "0.2.2"}}
 :aliases {:bridge {:main-opts ["-m" "bridge.cli"]}}}

Use clojure -M:bridge in place of bb bridge below.

Initialize the Configuration

Run the initializer from your repository root:

bb bridge init

This creates:

• .bridge/profile.yaml (project profile defining your subsystems)
• .bridge/verification-policy.yaml (rules outlining what evidence is required)
• .bridge/ephemeral/ (directory for run receipts and local analysis cards)

Install Git Hooks (Optional)

To gate the exact index before commit and recheck exact pushed trees:

bb bridge install-hooks

---

Core Concepts & Gradual Workflow

Bridge is designed for gradual adoption. You do not need to configure everything at once; you can start by tracking simple tests and add more verification checks as needed.

Step 1: Define Your Profile & Policy

The workflow relies on two core configuration files:

• Project Profile (profile.yaml): Maps directory structures and file paths to project subsystems, and registers the shell commands (e.g. unit tests, integration tests) used to verify them.
• Verification Policy (verification-policy.yaml): Defines what evidence is required for changes to specific subsystems before they are considered ready to merge, and can declare sandbox access for Bridge-owned paths.

Step 2: Check Status and Find Next Steps

When files change, Bridge uses your profile and policy to evaluate what needs to be verified.

• Check Status:

  bb bridge check --format json
  

  Bare check is iterative: it analyzes the current working snapshot, including staged, unstaged, and untracked files. It never silently becomes a commit gate.

• Find Next Step:

  bb bridge next
  

  This inspects outstanding obligations and suggests the immediate next action to take (e.g., pointing you to the exact test command to run).

Step 3: Run Evidence Commands

To view and run verification commands registered in your profile:

# List all registered commands
bb bridge list-evidence

# Run a specific command (e.g., unit tests)
bb bridge run-evidence --id unit

Executing a command via run-evidence generates an evidence-run receipt in .bridge/ephemeral/. When you run bb bridge check --format json again, Bridge detects this receipt and marks the obligation as satisfied.

Step 4: Verify an Exact Commit Candidate

Candidate mode is explicit:

# One-time trust bootstrap for an already trusted, configured HEAD.
bb bridge check --tree HEAD --frontier HEAD --approve --format json

# Plan obligations for exactly what is staged.
bb bridge check --index --format json

# Run the pinned action returned by next_action (example values shown).
bb bridge run-evidence --id unit --tree <candidate-tree> --frontier <frontier-tree>

# Recheck the unchanged index and record an explicit local approval.
bb bridge check --index --approve --format json

--index resolves the index with git write-tree; --tree pins any commit or tree object. Bridge compares that candidate with the nearest approved ancestor, checks it in a disposable linked worktree, and binds receipts to the candidate tree, frontier tree, and governance digests. It does not copy ambient untracked files into the candidate. Put reproducible setup in tracked evidence scripts so the same preparation can run in a clean CI checkout.

A commit is not verified merely because it exists. A tree becomes a verified frontier only through an explicit clear approval (which may have fresh receipts, reused exact-tree receipts, or no evidence obligations). Approvals are Git-private local state. When project policy includes CI, CI should rerun candidate verification for the exact pushed SHA and publish its result; Bridge itself does not require a particular hook or CI flow.

Step 5: Gradual Expansion

As your workflow matures, you can opt into tracking additional durable verification artifacts:

1. Verification Brief (verification-brief): Plans the scope, verification strategy, and environment assumptions for a particular subsystem or major change.
2. Observable Contract (observable-contract): Specifies assertions, triggers, and trace parameters to collect during execution.
3. Omission Decision Record (omission-decision-record): Formally documents why a particular policy requirement was skipped or deferred.
4. Assumption Ledger (assumption-ledger): Records platform or environment assumptions that your verification depends upon.

---

CLI Command Reference

Common commands for everyday development:

# Initialize configuration files
bb bridge init

# Verify current status and list missing evidence
bb bridge check --format json

# Evaluate the last committed patch instead of the live working tree
bb bridge check --git-diff HEAD^1 --format json

# Verify the exact staged candidate
bb bridge check --index --format json

# Verify an exact CI checkout against an explicitly trusted base
bb bridge check --tree "$GITHUB_SHA" --frontier "$BASE_SHA" --format json

# Show the recommended next verification step
bb bridge next

# List registered verification commands
bb bridge list-evidence

# Run an evidence command with a dry run (shows the shell command without executing)
bb bridge run-evidence --id unit --dry-run

# Run an evidence command and record the receipt
bb bridge run-evidence --id unit

# Validate the schema of an individual artifact file
bb bridge validate-artifact .bridge/artifacts/verification-brief.yaml

# Validate all artifacts in a directory
bb bridge validate-dir .bridge/artifacts

Commands listed under Stable commands in bb bridge help follow the 0.2.x compatibility contract. Commands listed under Experimental commands are opt-in previews and may change or disappear in a minor release.

The stable command names are init, init-profile, migrate-profile, install-hooks, validate-artifact, validate-dir, summary, debug-profile, coverage, coverage-as-evidence, analyze-change, check, next, auto, list-evidence, and run-evidence.

---

Key Artifacts

Bridge uses schema-validated data files (typically YAML or EDN format) to manage the verification state:

• verification-policy: Declares evidence requirements and Bridge-owned path sandbox rules.
• verification-brief: Records verification scope, methods, and assumptions.
• observable-contract: Details runtime monitoring, triggers, and timing.
• omission-decision-record: Explains why a required test or check was waived.
• assumption-ledger: Captures external dependencies and environment assumptions.
• completeness-ledger: Summarizes which required artifacts are present or missing.
• change-intent-card: An ephemeral card capturing a change and its derived obligations.

The canonical artifact inventory and field schemas live in resources/bridge/schemas.edn.

---

Subsystem Categories

Different types of subsystems require different verification approaches. You can define categories in your profile to customize verification behavior:

• actor-message: Emphasizes message ordering and trace observables.
• shared-memory / lock-free: Emphasizes memory models, atomicity, and concurrency behavior.
• async-runtime: Emphasizes notification hooks, parks, and wake targets.
• business-rule / data-pipeline: Emphasizes specification quality, completeness checks, and differential outputs.

---

Library API

Bridge can be consumed as a library (the Vis bridge extension is the reference consumer). The only supported entry point is the bridge.api namespace; every public var there is part of the stable 0.2.x contract, and (bridge.api/contract) returns the inventory as data. All other bridge.* namespaces are internal. See docs/api.md for the full contract and change policy, and CHANGELOG.md for contract-level changes.

---

Repo Layout

• src/bridge/ — CLI and workflow engine implementation.
• resources/bridge/schemas.edn — Canonical artifact schemas.
• resources/bridge/templates/ — Prompts and template definitions.
• examples/ — Sample profiles and policy setups (e.g., examples/generic/).
• docs/ — Public API and artifact examples.
• test/ — Core automated test suite.

---

Examples

• Generic Example: See examples/generic/ for a simple profile and verification brief.
• Experimental Features: Run bb bridge help; preview commands are listed separately from the stable 0.2.x CLI.